@memberjunction/ai-inworld 0.0.1 → 5.42.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './inworldRealtime.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+// Inworld Realtime API — realtime (voice) driver. BaseRealtimeModel implementation.
+export * from './inworldRealtime.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,cAAc,mBAAmB,CAAC"}

package/dist/inworldRealtime.d.ts

@@ -0,0 +1,514 @@
+import { BaseRealtimeModel, type IRealtimeSession, type RealtimeSessionParams, type RealtimeToolDefinition, type RealtimeTranscript, type RealtimeToolCall, type RealtimeUsage, type RealtimeSessionError, type JSONObject, type JSONValue } from '@memberjunction/ai';
+/** The Inworld Realtime API WebSocket endpoint. Auth rides as a `?token=` query parameter. */
+export declare const INWORLD_REALTIME_WS_URL = "wss://api.inworld.ai/v1/realtime";
+/**
+ * Default underlying LLM Inworld brokers when {@link RealtimeSessionParams.Model} is empty. Inworld
+ * selects the reasoning model via `modelId` (e.g. `anthropic/claude-sonnet-4-6`); the STT engine and
+ * TTS voice are configured independently in the audio block.
+ */
+export declare const INWORLD_DEFAULT_MODEL_ID = "anthropic/claude-sonnet-4-6";
+/**
+ * Default semantic-VAD eagerness applied to turn-taking when the caller supplies none. Inworld's
+ * turn detection is semantic VAD with adjustable eagerness; `medium` balances responsiveness against
+ * premature turn-ends. Overridable via `Config.turn_detection.eagerness` (or the whole block).
+ */
+export declare const INWORLD_DEFAULT_VAD_EAGERNESS = "medium";
+/**
+ * A parsed inbound Inworld Realtime WebSocket frame.
+ *
+ * The Inworld protocol multiplexes server events on a `type` discriminator (mirroring the
+ * `session.update` request shape it accepts), so a single interface carries every inbound field the
+ * driver reads. Fields are optional because which ones are present depends on `type`.
+ *
+ * @remarks Wire-format binding point — the precise inbound `type` strings and field names are mapped
+ * to the documented protocol shape and centralized in {@link InworldRealtimeSession.classifyServerEvent};
+ * verify the exact discriminators against a live Inworld endpoint.
+ */
+export interface InworldServerEvent {
+    /** The event discriminator (e.g. `session.updated`, `output_audio.delta`, `response.done`). */
+    type?: string;
+    /** Provider-assigned session id, surfaced on the session-ready frame. */
+    session_id?: string;
+    /** A base64-encoded chunk of synthesized output audio (Realtime TTS-2). */
+    audio?: string;
+    /** Transcribed text for a transcript frame (user STT or assistant TTS transcript). */
+    text?: string;
+    /** A correlation id for a tool call, echoed back on the tool result. */
+    call_id?: string;
+    /** The tool name on a tool-call frame. */
+    name?: string;
+    /**
+     * Tool-call arguments. Inworld may emit these either pre-parsed (object) or as a JSON string; the
+     * driver normalizes both to the Core contract's JSON-string `Arguments` shape.
+     */
+    arguments?: JSONValue;
+    /** Provider error code on an error frame. */
+    code?: string;
+    /** Human-readable message on an error frame. */
+    message?: string;
+    /** Whether the provider classified an error frame as fatal (transport/credential death). */
+    fatal?: boolean;
+    /** Incremental input-token count on a usage frame. */
+    input_tokens?: number;
+    /** Incremental output-token count on a usage frame. */
+    output_tokens?: number;
+}
+/** The minimal outbound surface of the realtime WebSocket the session depends on. */
+export interface InworldRealtimeSocket {
+    /** Sends one JSON-serialized client frame. */
+    send(data: string): void;
+    /** Terminates the underlying connection. */
+    close(): void;
+}
+/**
+ * Arguments handed to {@link InworldRealtime.connectRealtimeSocket}: the authenticated URL plus the
+ * lifecycle callbacks. The seam owns the entire WebSocket dance so tests substitute it wholesale with
+ * an in-memory fake — no network, no real socket.
+ */
+export interface InworldConnectArgs {
+    /** The full `wss://…?token=…` URL. */
+    Url: string;
+    /** Invoked with each parsed inbound frame. */
+    OnMessage: (event: InworldServerEvent) => void;
+    /** Invoked on a WebSocket-level error (fatal — the session is unusable). */
+    OnError: (message: string) => void;
+    /** Invoked when the WebSocket closes. */
+    OnClose: (code?: number, reason?: string) => void;
+}
+/**
+ * Real-time, full-duplex driver for the **Inworld Realtime API**, implementing the Core
+ * {@link BaseRealtimeModel} primitive. Registers as `InworldRealtime` and is resolved for
+ * `MJ: AI Models` typed `Realtime` (API-key env alias: `AI_VENDOR_API_KEY__InworldRealtime`).
+ *
+ * **What the provider is:** a single-WebSocket speech-to-speech stack. Sessions initialize with a
+ * `session.update` frame carrying model selection, instructions, audio settings, STT/TTS config, and
+ * tools; components are swappable mid-session without reconnect. Input is streamed audio (server-side
+ * STT with voice profiling); output is synthesized speech (Realtime TTS-2) supporting inline steering
+ * tags like `[laugh]`. Turn-taking is semantic VAD with adjustable eagerness, handling barge-in.
+ *
+ * **Model resolution:** Inworld brokers hundreds of LLMs; the reasoning model is selected via
+ * `modelId` (e.g. `anthropic/claude-sonnet-4-6`) carried from {@link RealtimeSessionParams.Model}
+ * (falling back to {@link INWORLD_DEFAULT_MODEL_ID}). STT engine and TTS voice are configured
+ * independently via `Config`.
+ *
+ * **Topology:** server-bridged only ({@link StartSession}) — the driver opens the WebSocket, sends the
+ * session config, and resolves only once the provider confirms the config is applied (driver
+ * obligation #7). Inworld does not expose a documented ephemeral-token mint for browser-direct
+ * sessions, so {@link SupportsClientDirect} stays `false` (inherited).
+ *
+ * **Tool calling:** "fluent tool calling" — functions declared at startup (or added mid-session via
+ * {@link IRealtimeSession.RegisterTools}) and executed mid-conversation; results fed back via
+ * {@link IRealtimeSession.SendToolResult} complete the loop.
+ */
+export declare class InworldRealtime extends BaseRealtimeModel {
+    /**
+     * Opens a server-bridged session: connects the realtime WebSocket authenticated with the API
+     * key, sends the full session config as the FIRST frame (`session.update` — model, instructions,
+     * audio/STT/TTS, tools, semantic-VAD turn-taking), and resolves only once the provider's
+     * session-ready confirmation arrives (driver obligation #7 — "ready only after the config is
+     * applied"). Mic frames sent before that would be dropped by the provider, and `StartSession`
+     * not resolving until ready makes that unrepresentable for consumers.
+     *
+     * @param params Session configuration (model, system prompt, tools, initial context, config bag).
+     * @returns A promise resolving to the live {@link IRealtimeSession} handle, post-ready.
+     */
+    StartSession(params: RealtimeSessionParams): Promise<IRealtimeSession>;
+    /**
+     * Builds the authenticated WebSocket URL. Auth rides as a `?token=` query parameter (the
+     * server-side API key for the server-bridged topology).
+     *
+     * @returns The full `wss://…?token=…` connect URL.
+     * @remarks Wire-format binding point — confirm the auth query-parameter name (`token`) against a
+     * live Inworld endpoint; some deployments authenticate via an `Authorization` header instead.
+     */
+    protected buildConnectUrl(): string;
+    /**
+     * Transport seam for the realtime WebSocket. Production speaks the raw Inworld Realtime protocol
+     * over the platform-global `WebSocket` (browsers / Node 22+) and resolves once the socket is
+     * OPEN. Unit tests override this to return an in-memory fake — no network.
+     *
+     * @param args The authenticated URL plus inbound-message / error / close callbacks.
+     * @returns A promise resolving to the connected {@link InworldRealtimeSocket} once open.
+     */
+    protected connectRealtimeSocket(args: InworldConnectArgs): Promise<InworldRealtimeSocket>;
+    /**
+     * Maps a Core {@link RealtimeToolDefinition} up to an Inworld realtime `function` tool schema —
+     * the shape Inworld's "fluent tool calling" `tools[]` slot accepts. Shared by the initial
+     * `session.update` and by mid-session {@link IRealtimeSession.RegisterTools} so both expose
+     * byte-for-byte identical tool schemas.
+     *
+     * @param tool The Core tool definition to map.
+     * @returns The Inworld realtime function-tool object.
+     */
+    static MapToolToFunction(tool: RealtimeToolDefinition): JSONObject;
+    /**
+     * Canonical, order-insensitive fingerprint of a tool set (same scheme as the OpenAI / Gemini /
+     * AssemblyAI realtime drivers) — used by {@link InworldRealtimeSession.RegisterTools} to no-op
+     * identical re-registrations per the contract's idempotency rule.
+     *
+     * @param tools The tool set to fingerprint.
+     * @returns A stable string fingerprint independent of tool ordering.
+     */
+    static ToolSetFingerprint(tools: RealtimeToolDefinition[]): string;
+}
+/**
+ * Concrete {@link IRealtimeSession} backed by a raw Inworld Realtime WebSocket.
+ *
+ * Owns the inbound translation (Inworld wire events → Core events) and the outbound translation
+ * (Core calls → wire frames). Created by {@link InworldRealtime.StartSession}; never instantiated
+ * directly by consumers.
+ *
+ * Provider-behavior notes (the contract deltas a consumer should know):
+ * - **`session.update` is the universal config channel.** Model, instructions, audio/STT/TTS, tools,
+ *   and turn-taking are all carried by `session.update` — at connect time AND mid-session. Components
+ *   are swappable without reconnect, so {@link RegisterTools} and {@link SendContextNote} are native
+ *   config writes (never interrupting generation).
+ * - **Semantic VAD owns turn detection / barge-in.** A raw "speech started" is NOT an interruption;
+ *   the provider's true-barge-in signal (it tracks its own output emission) is surfaced only when it
+ *   cuts off an ACTIVE response, gated on {@link responseActive} per the base contract.
+ * - **Output supports inline steering tags** (e.g. `[laugh]`) — passed through verbatim in
+ *   instructions; the driver does not parse or strip them.
+ * - **Tool results must reach the model.** `SendToolResult` is sent immediately (the provider owns the
+ *   spoken continuation) and marks a response active eagerly so a queued narration can't slip ahead.
+ * - **{@link RequestSpokenUpdate} queues behind an in-flight response** per the collision rule; a
+ *   `tool.call` clears the busy flag WITHOUT draining the queue (deadlock guard, obligation #2).
+ */
+export declare class InworldRealtimeSession implements IRealtimeSession {
+    private socket;
+    private outputHandler;
+    private transcriptHandler;
+    private toolCallHandler;
+    private interruptionHandler;
+    private usageHandler;
+    private errorHandler;
+    private closeHandler;
+    /** True once {@link Close} ran — an expected close must not surface as a fatal error. */
+    private closedByConsumer;
+    /** Resolves when the session-ready frame arrives; rejects on transport death. */
+    private readyPromise;
+    private resolveReady;
+    private rejectReady;
+    private readyReceived;
+    /** The session params the connect-time `session.update` is built from. */
+    private params;
+    /** The base system prompt (with InitialContext folded in) — context notes append to it. */
+    private basePrompt;
+    /** Accumulated {@link SendContextNote} texts, re-sent with the full prompt each time. */
+    private contextNotes;
+    /**
+     * Whether a model response is currently in flight. Set when output audio / a response-started
+     * frame arrives (and eagerly when this session triggers its own response); cleared on a
+     * response-done frame; a tool-call clears it WITHOUT draining (deadlock guard). Consumed by
+     * {@link enqueueOrRun} so a native {@link RequestSpokenUpdate} never collides with an active
+     * response, and by {@link handleSpeechStarted} to gate true-barge-in.
+     */
+    private responseActive;
+    /** Sends deferred while a response is in flight; drained in order at the next boundary. */
+    private queuedSends;
+    /**
+     * Fingerprint of the tool set currently declared on the session; {@link RegisterTools} compares
+     * against it to no-op identical re-registrations.
+     */
+    private currentToolsFingerprint;
+    /**
+     * @param params The session parameters (model, system prompt, tools, initial context, config bag).
+     */
+    constructor(params: RealtimeSessionParams);
+    /** Binds the underlying socket. Called by the driver once the WebSocket is open. */
+    AttachSocket(socket: InworldRealtimeSocket): void;
+    /**
+     * Sends the initial `session.update` frame carrying the full server-authored session config
+     * (model, instructions, audio/STT/TTS, tools, semantic-VAD turn-taking). Always the FIRST client
+     * frame — the provider drops audio sent before the session is configured.
+     */
+    SendSessionUpdate(): void;
+    /**
+     * Resolves once the provider's session-ready confirmation arrives (its acknowledgment that the
+     * session config is applied); rejects if the transport dies first. Awaited by
+     * {@link InworldRealtime.StartSession} so the session is never handed to a consumer before it is
+     * actually configured (driver obligation #7).
+     *
+     * @returns A promise resolving on session-ready and rejecting on pre-ready transport death.
+     */
+    WaitForReady(): Promise<void>;
+    /** @inheritdoc — streams one client media frame as a base64 input audio-append frame. */
+    SendInput(chunk: ArrayBuffer): void;
+    /**
+     * @inheritdoc
+     *
+     * Inworld's `tools` are a MUTABLE `session.update` field (components are swappable mid-session
+     * without reconnect), so re-declaration is native: an identical set (order-insensitively) is a
+     * silent no-op per the contract's idempotency rule; a genuinely different set is applied to the
+     * live session immediately.
+     *
+     * @param tools The tools to expose to the model.
+     */
+    RegisterTools(tools: RealtimeToolDefinition[]): Promise<void>;
+    /** @inheritdoc */
+    OnOutput(handler: (chunk: ArrayBuffer) => void): void;
+    /** @inheritdoc */
+    OnTranscript(handler: (t: RealtimeTranscript) => void): void;
+    /** @inheritdoc */
+    OnToolCall(handler: (call: RealtimeToolCall) => void): void;
+    /** @inheritdoc */
+    OnInterruption(handler: () => void): void;
+    /** @inheritdoc */
+    OnUsage(handler: (u: RealtimeUsage) => void): void;
+    /** @inheritdoc */
+    OnError(handler: (error: RealtimeSessionError) => void): void;
+    /** @inheritdoc */
+    OnClose(handler: () => void): void;
+    /**
+     * @inheritdoc
+     *
+     * Completes the tool-call loop: sends a tool-result frame correlated by `call_id`. Sent
+     * IMMEDIATELY (never queued) — the provider asked for it and owns the spoken continuation. The
+     * busy flag is set eagerly so a queued narration can't slip in before the spoken result (driver
+     * obligation #5 — the result must EVENTUALLY be voiced and never be dropped).
+     *
+     * @param callID The `CallID` from the originating {@link RealtimeToolCall}.
+     * @param output The tool's result as a JSON-stringified string.
+     */
+    SendToolResult(callID: string, output: string): Promise<void>;
+    /**
+     * @inheritdoc
+     *
+     * EMULATED via the mutable system prompt: Inworld has no purpose-built non-interrupting context
+     * channel, but `session.update` may rewrite instructions mid-session WITHOUT triggering
+     * generation. The note is appended under a "Background updates" heading and the full prompt is
+     * re-sent — a config write, so it never interrupts and is sent immediately even mid-response. The
+     * model sees the notes the next time it speaks.
+     *
+     * @param text The context note to append to the conversation.
+     */
+    SendContextNote(text: string): void;
+    /**
+     * @inheritdoc
+     *
+     * Triggers ONE short spoken update via a response-create frame carrying per-response
+     * instructions. **Collision behavior: queue.** A response-create sent mid-response would collide
+     * with the in-flight generation (the provider rejects overlapping triggers), so the send is
+     * deferred until the active response completes and drained at the next boundary.
+     *
+     * @param instructions Instructions for the single spoken update.
+     */
+    RequestSpokenUpdate(instructions: string): void;
+    /**
+     * @inheritdoc
+     *
+     * Closes the session: sends a session-close frame BEFORE closing the socket so the provider
+     * tears the session down promptly rather than holding it, then releases the socket and drops all
+     * handlers so no stale callback fires afterward.
+     */
+    Close(): Promise<void>;
+    /**
+     * Entry point for an inbound WebSocket frame. Classifies the raw frame to a semantic kind via
+     * {@link classifyServerEvent}, then routes to a focused per-concern handler so each translation
+     * unit stays small and testable.
+     *
+     * @param event The parsed Inworld server event.
+     */
+    HandleServerEvent(event: InworldServerEvent): void;
+    /** Resolves the ready wait so {@link InworldRealtime.StartSession} can hand back the session. */
+    private handleReady;
+    /** Decodes one base64 output-audio frame, marks a response active, and forwards the raw bytes. */
+    private handleOutputAudio;
+    /**
+     * Surfaces a `tool.call` to the consumer. The model has yielded the floor pending the result, so
+     * the busy flag is cleared (deadlock guard — driver obligation #2) WITHOUT draining the queue (a
+     * queued narration must not trigger a response between the tool call and its result; it drains at
+     * the next real response boundary). Inworld may emit `arguments` pre-parsed or as a JSON string;
+     * {@link normalizeToolArguments} normalizes both to the Core contract's JSON-string shape.
+     *
+     * @param event The inbound tool-call frame.
+     */
+    private handleToolCall;
+    /**
+     * A raw "speech started" frame. Per the base contract this is NOT itself an interruption — a user
+     * taking their normal turn while the model is idle must not be reported. It is surfaced as a
+     * true barge-in only when a model response is actually in flight (semantic VAD owns turn
+     * detection; {@link responseActive} is the server-bridged proxy for "model output in flight").
+     */
+    private handleSpeechStarted;
+    /**
+     * Surfaces a TRUE barge-in: user speech that cut off active model output. Fires the interruption
+     * handler, then releases the floor and drains queued sends. (Reached either from an explicit
+     * provider interruption frame or from a `responseActive`-gated speech-started.)
+     */
+    private handleInterruption;
+    /** Translates an incremental usage frame into a {@link RealtimeUsage} update. */
+    private handleUsage;
+    /**
+     * Classifies a provider error frame's fatality and forwards it. The provider's own `fatal` flag
+     * (when present) is authoritative — a fatal frame means credential/transport death (driver
+     * obligation #6) and the consumer should finalize; otherwise it is a recoverable error frame and
+     * the session stays open (`Fatal: false`).
+     *
+     * @param event The inbound error frame.
+     */
+    private handleProviderError;
+    /**
+     * Surfaces a WebSocket-level failure as a FATAL session error — the transport is gone, so the
+     * consumer should finalize cleanly instead of idling on a dead socket (driver obligation #6).
+     *
+     * @param message The transport error message.
+     */
+    HandleTransportError(message: string): void;
+    /**
+     * Surfaces an UNEXPECTED socket close as a fatal error (expected closes — the consumer called
+     * {@link Close} — are silent). The provider hard-closes at token expiry and when it ends the
+     * session itself, so this is also how credential / session death reaches the consumer. The close
+     * handler fires after the error so consumers driving finalization from either signal converge.
+     *
+     * @param code Optional WebSocket close code.
+     * @param reason Optional WebSocket close reason.
+     */
+    HandleTransportClose(code?: number, reason?: string): void;
+    /**
+     * Builds the initial `session.update` frame: model selection, instructions, audio settings, STT
+     * engine, TTS voice, tools, and semantic-VAD turn-taking with adjustable eagerness. Recognized
+     * `Config` keys pass through to their wire slots; the whole `Config` bag also spreads onto the
+     * session so a per-conversation override can replace any block.
+     *
+     * @param tools The tools to declare at connect time.
+     * @returns The `session.update` client frame.
+     * @remarks Wire-format binding point — the `session.update` envelope and the exact key names for
+     * `model` / `instructions` / `audio` / `voice` / `stt` / `turn_detection.eagerness` are mapped to
+     * Inworld's documented protocol shape; verify each key against a live Inworld endpoint.
+     */
+    private buildSessionUpdateFrame;
+    /**
+     * Builds the audio block (input STT + output TTS voice). Recognized shorthand `Config` keys:
+     * `voice` → `output.voice`, `stt` → `input.model`, `language` → `input.language`.
+     *
+     * @param config The caller's config bag.
+     * @returns The wire `audio` config object.
+     * @remarks Wire-format binding point — the `audio.{input,output}` sub-shape is mapped to the
+     * documented STT-in / TTS-2-out description; verify exact key names against a live endpoint.
+     */
+    private buildAudioConfig;
+    /**
+     * Builds the semantic-VAD turn-detection block. If the caller supplies a full `turn_detection`
+     * object it is used verbatim; otherwise an `eagerness` shorthand (or the default) is applied.
+     *
+     * @param config The caller's config bag.
+     * @returns The wire `turn_detection` object.
+     * @remarks Wire-format binding point — `turn_detection.type = 'semantic_vad'` and the `eagerness`
+     * field are mapped to the documented "semantic VAD with adjustable eagerness"; verify exact key
+     * names / allowed values against a live endpoint.
+     */
+    private buildTurnDetection;
+    /**
+     * Spreads caller-supplied raw `Config` overrides onto the session object, skipping the shorthand
+     * keys already consumed by {@link buildAudioConfig} / {@link buildTurnDetection} so they don't
+     * double-write. Lets a per-conversation config replace a whole block (e.g. a fully-specified
+     * `audio` object) while shorthands stay convenient.
+     *
+     * @param session The session object being built (mutated in place).
+     * @param config The caller's config bag.
+     */
+    private applyRawConfigOverrides;
+    /**
+     * Builds an input audio-append frame from a raw media chunk (base64-encoded over the single WS,
+     * full-duplex).
+     *
+     * @param chunk The raw media frame.
+     * @returns The audio-append client frame.
+     * @remarks Wire-format binding point — the `input_audio.append` type and the `audio` base64 key
+     * are mapped to the documented full-duplex streamed-audio input; verify against a live endpoint.
+     */
+    private buildAudioAppendFrame;
+    /**
+     * Builds a mid-session `session.update` frame that re-declares only the tools (components are
+     * swappable without reconnect).
+     *
+     * @param tools The new tool set to declare.
+     * @returns The tools-only `session.update` client frame.
+     * @remarks Wire-format binding point — re-declaring tools via a partial `session.update` follows
+     * the documented "components swappable mid-session" model; verify the partial-update semantics
+     * against a live endpoint.
+     */
+    private buildToolsUpdateFrame;
+    /**
+     * Builds a tool-result frame correlated by `call_id`. The Core contract's `output` is already a
+     * JSON string, which is passed through verbatim in the `result` slot.
+     *
+     * @param callID The originating call id.
+     * @param output The tool result as a JSON string.
+     * @returns The tool-result client frame.
+     * @remarks Wire-format binding point — the `tool.result` type and the `call_id` / `result` keys
+     * are mapped to the documented fluent-tool-calling result flow; verify against a live endpoint.
+     */
+    private buildToolResultFrame;
+    /**
+     * Builds a response-create frame carrying one-off per-response instructions (the instructed
+     * spoken update). Output supports inline steering tags like `[laugh]`, which pass through in the
+     * instructions verbatim.
+     *
+     * @param instructions Instructions for the single spoken response.
+     * @returns The response-create client frame.
+     * @remarks Wire-format binding point — the `response.create` type and the `instructions` key are
+     * mapped to the documented instructed-response capability; verify against a live endpoint.
+     */
+    private buildResponseCreateFrame;
+    /**
+     * Builds the non-interrupting context-item frame. Emulated via the mutable instructions: the full
+     * prompt (base + accumulated notes) is re-sent via `session.update`, which never triggers
+     * generation.
+     *
+     * @param fullPrompt The full instructions (base prompt + background-update notes).
+     * @returns The context-item client frame (a `session.update` that rewrites instructions).
+     * @remarks Wire-format binding point — using a partial `session.update` of `instructions` as the
+     * non-interrupting context channel follows the documented "components swappable mid-session"
+     * model; verify against a live endpoint.
+     */
+    private buildContextItemFrame;
+    /**
+     * Builds the session-close frame sent before the socket is torn down.
+     *
+     * @returns The session-close client frame.
+     * @remarks Wire-format binding point — the `session.close` type is mapped to a graceful teardown;
+     * verify against a live endpoint (some deployments rely on the socket close alone).
+     */
+    private buildSessionCloseFrame;
+    /**
+     * Classifies a raw inbound frame to a semantic kind the dispatcher routes on. Centralizing the
+     * `type`-string mapping here keeps {@link HandleServerEvent} stable even if the precise wire
+     * discriminators differ from the assumed shape.
+     *
+     * @param event The parsed inbound frame.
+     * @returns The semantic kind for {@link HandleServerEvent}.
+     * @remarks Wire-format binding point — the inbound `type` strings (e.g. `session.updated`,
+     * `output_audio.delta`, `input_audio_transcription.delta`, `response.done`, `tool.call`,
+     * `input_audio.speech_started`, `interrupted`, `usage`, `error`) are mapped to the documented
+     * protocol shape; verify the exact discriminators against a live Inworld endpoint.
+     */
+    private classifyServerEvent;
+    /** Resolves the underlying LLM id Inworld brokers (param model, falling back to the default). */
+    private resolveModelId;
+    /** Emits a transcript event (drops empty/whitespace-only text so no blank turns are persisted). */
+    private emitTranscript;
+    /** Response boundary: releases the busy flag and drains queued sends in order. */
+    private completeResponse;
+    /** Runs a send immediately when idle; otherwise queues it for the next response boundary. */
+    private enqueueOrRun;
+    /** The base prompt plus every accumulated context note under a "Background updates" heading. */
+    private composePromptWithNotes;
+    /** JSON-serializes and sends one client frame (throws if the socket was never attached). */
+    private sendFrame;
+    /** Rejects a still-pending ready wait (transport death / consumer close during startup). */
+    private failReadyWait;
+    /** Drops all registered handlers + queued sends so a closed session can't fire stale callbacks. */
+    private clearHandlers;
+    /** Folds optional prior context into the system prompt (Inworld has no separate history channel). */
+    private static composeSystemPrompt;
+    /**
+     * Normalizes tool-call arguments to the Core contract's JSON-string shape. Inworld may emit them
+     * pre-parsed (object) or already as a JSON string; both are coerced to a JSON string so consumers
+     * always parse the same shape.
+     */
+    private static normalizeToolArguments;
+    /** Decodes a base64 audio payload into a freshly-allocated `ArrayBuffer`. */
+    private static base64ToArrayBuffer;
+}
+//# sourceMappingURL=inworldRealtime.d.ts.map

package/dist/inworldRealtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inworldRealtime.d.ts","sourceRoot":"","sources":["../src/inworldRealtime.ts"],"names":[],"mappings":"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"}