Module studio-agentExperimental

@honua/sdk-js/studio-agent — the agent session that turns a prompt into a live map.

One entrypoint, three layers:

1. Wire contract (StudioAiChatRequest and friends) — the provider-neutral shapes honua-server's Studio AI proxy speaks over POST /v1/studio/ai/chat (SSE) and GET /v1/studio/ai/capabilities.
2. Transports — SseChatTransport for the real proxy and McpClient for honua-server's POST /mcp tool plane. Both are hand-rolled, dependency-free fetch wrappers with typed error channels; mcp-client.ts's module doc records why this does not use @modelcontextprotocol/sdk.
3. Session (createStudioAgentSession) — the turn loop that streams a chat turn, dispatches the tool calls the model emits (local @honua/sdk-js/agent-tools verbs through a kit, server-discovered composition tools through MCP), feeds results back, and repeats until the model stops asking. It never throws mid-stream. The composition tool set comes from paging the server's tools/list and filtering it through a StudioToolPolicy — see StudioToolCatalog for why a honua_studio_ name prefix is never a routing credential. Opt in to watchToolListChanged and the session also subscribes to the server's standalone GET /mcp notification stream (McpNotificationStream) and re-discovers on notifications/tools/list_changed.

import { createHonuaAiMapKit } from "@honua/sdk-js/agent-tools";
import { createStudioAgentSession } from "@honua/sdk-js/studio-agent";

const kit = createHonuaAiMapKit({ runtime, policy: { allowActions: true } });
const session = createStudioAgentSession({
  baseUrl: "/api",
  kit,
  system: () => kit.systemPrompt(),
  draft: { draftId, generation },
});

const turn = await session.chat("Filter the parcels chart to whatever I click on the map.");
if (turn.status !== "completed") console.warn(turn.errorMessage);
Copy

The transports and the MCP client are ported from honua-studio (src/chat/*, src/mcp/*) with their origin and design decisions recorded in each module's documentation.

This entrypoint tracks honua-server's Studio AI proxy and honua_studio_* tool contracts plus geospatial-mcp ADR-0030's interaction vocabulary; all three may change before 1.0.