Interface StudioAgentSessionOptionsExperimental

interface StudioAgentSessionOptions {
    auth?: StudioAiTokenSource;
    baseUrl?: string;
    disableToolDiscovery?: boolean;
    draft?: StudioAgentDraftBinding;
    execute?: ((call: HonuaAgentToolCall) => Promise<HonuaAgentToolResult<unknown>>);
    fetchImpl?: {
        (input: URL | RequestInfo, init?: RequestInit): Promise<Response>;
        (input: string | URL | Request, init?: RequestInit): Promise<Response>;
    };
    kit?: HonuaAiMapKit;
    maxTokens?: number;
    maxToolRounds?: number;
    mcpClient?: McpClient;
    model?: string;
    onEvent?: ((event: StudioAgentSessionEvent) => void);
    provider?: string;
    studioTools?: StudioToolPolicy;
    system?: string | (() => string | Promise<string>);
    temperature?: number;
    toolChoice?: StudioAiToolChoice;
    toolDiscoveryTimeoutMs?: number;
    toolListChangedWatch?: Omit<McpNotificationWatchOptions, "onNotification">;
    tools?: readonly HonuaAgentToolDefinitionLike[];
    transport?: ChatTransport;
    watchToolListChanged?: boolean;
}

Properties

auth? baseUrl? disableToolDiscovery? draft? execute? fetchImpl? kit? maxTokens? maxToolRounds? mcpClient? model? onEvent? provider? studioTools? system? temperature? toolChoice? toolDiscoveryTimeoutMs? toolListChangedWatch? tools? transport? watchToolListChanged?

Properties

Optional Readonly Experimentalauth

auth?: StudioAiTokenSource

Bearer-token source. The model's own credentials never leave the server.

Optional Readonly ExperimentalbaseUrl

baseUrl?: string

Base of the honua-server API — the session calls ${baseUrl}/v1/studio/ai/* and ${baseUrl}/mcp.

Default

"/api"

Optional Readonly ExperimentaldisableToolDiscovery

disableToolDiscovery?: boolean

Skips tools/list discovery entirely. The session then advertises and routes only its runtime-kit tools. Use for a host with no MCP endpoint.

Default

false

Optional Readonly Experimentaldraft

draft?: StudioAgentDraftBinding

Composition draft honua_studio_* tools mutate.

Optional Readonlyexecute

execute?: ((call: HonuaAgentToolCall) => Promise<HonuaAgentToolResult<unknown>>)

Explicit executor, when not supplying a kit.

Optional ReadonlyfetchImpl

fetchImpl?: {
    (input: URL | RequestInfo, init?: RequestInit): Promise<Response>;
    (input: string | URL | Request, init?: RequestInit): Promise<Response>;
}

Override for tests. Defaults to globalThis.fetch.

Type declaration

    • (input, init?): Promise<Response>

    • MDN Reference

      Parameters

      • input: URL | RequestInfo
      • Optionalinit: RequestInit

      Returns Promise<Response>

    • (input, init?): Promise<Response>

    • Parameters

      • input: string | URL | Request
      • Optionalinit: RequestInit

      Returns Promise<Response>

Optional Readonly Experimentalkit

kit?: HonuaAiMapKit

The local runtime tool plane.

Optional Readonly ExperimentalmaxTokens

maxTokens?: number

Optional Readonly ExperimentalmaxToolRounds

maxToolRounds?: number

Assistant rounds per chat() before the loop stops asking.

Default

8

Optional Readonly ExperimentalmcpClient

mcpClient?: McpClient

Replaces the MCP client used for composition-tool routing.

Optional Readonly Experimentalmodel

model?: string

Optional ReadonlyonEvent

onEvent?: ((event: StudioAgentSessionEvent) => void)

Observes every streamed event and every tool dispatch. Never throws into the loop.

Optional Readonly Experimentalprovider

provider?: string

Optional Readonly ExperimentalstudioTools

studioTools?: StudioToolPolicy

Which server-advertised Studio descriptors this session may route and advertise. Defaults approve the canonical server family in every view, keep the allowlist empty, and use the deprecated HONUA_STUDIO_MCP_TOOL_NAMES table as the migration-diagnostic required baseline. See ./tool-catalog.ts.

Optional Readonly Experimentalsystem

system?: string | (() => string | Promise<string>)

System prompt. A function is awaited once per chat() call, so a kit's systemPrompt() re-reads live map context on every turn.

Optional Readonly Experimentaltemperature

temperature?: number

Optional Readonly ExperimentaltoolChoice

toolChoice?: StudioAiToolChoice

Optional Readonly ExperimentaltoolDiscoveryTimeoutMs

toolDiscoveryTimeoutMs?: number

Wall-clock bound on one tools/list discovery pass (handshake plus every page). An MCP endpoint that accepts the request and never answers would otherwise hold every chat() open forever, since fetch has no deadline of its own. On expiry the pass fails like any other discovery failure: the turn degrades to runtime-kit tools, the reason is reported on StudioAgentSession.toolDiscovery, and the next turn retries. 0 disables the bound.

Default

15000

Optional Readonly ExperimentaltoolListChangedWatch

toolListChangedWatch?: Omit<McpNotificationWatchOptions, "onNotification">

Backoff, budget, and observer overrides for the watchToolListChanged subscription. The session supplies onNotification itself; everything else is passed through.

Optional Readonly Experimentaltools

tools?: readonly HonuaAgentToolDefinitionLike[]

Explicit tool definitions, when not supplying a kit. Merged with the kit's tools when both are present.

Optional Readonly Experimentaltransport

transport?: ChatTransport

Replaces the SSE transport. Supply a scripted transport to drive a session with no model.

Optional Readonly ExperimentalwatchToolListChanged

watchToolListChanged?: boolean

Subscribes to the server's GET /mcp notification stream after the first successful discovery pass and re-runs discovery on every notifications/tools/list_changed, so a catalog the server changes mid-session does not go stale until the next reconnect().

Off by default: opening a second long-lived HTTP request is a network behavior change no existing consumer asked for, and a server that offers no such stream would be probed for nothing. When the server declines the channel (405/501) the subscription ends unsupported and the session carries on exactly as it does today.

Default

false

Settings

Member Visibility

On This Page

Properties