@memberjunction/ai-assemblyai 0.0.1 → 5.41.0

package/dist/assemblyAIRealtime.d.ts

@@ -0,0 +1,367 @@
+import { BaseRealtimeModel, type ClientRealtimeSessionConfig, type IRealtimeSession, type RealtimeSessionParams, type RealtimeToolDefinition, type RealtimeTranscript, type RealtimeToolCall, type RealtimeUsage, type RealtimeSessionError, type JSONObject } from '@memberjunction/ai';
+/** The single Voice Agent websocket endpoint (auth rides as a `?token=` query parameter). */
+export declare const ASSEMBLYAI_AGENT_WS_URL = "wss://agents.assemblyai.com/v1/ws";
+/** REST endpoint that mints one-time, short-lived client tokens for browser-direct sessions. */
+export declare const ASSEMBLYAI_TOKEN_URL = "https://agents.assemblyai.com/v1/token";
+/**
+ * Lifetime requested for the one-time client token minted by {@link AssemblyAIRealtime.CreateClientSession}.
+ * The token is single-use: it authenticates ONE websocket open within this window; an
+ * already-open session continues past it.
+ */
+export declare const ASSEMBLYAI_TOKEN_TTL_SECONDS = 300;
+/**
+ * The Voice Agent wire format: 16-bit signed little-endian PCM, mono, 24 kHz, base64-encoded,
+ * in BOTH directions (`input.audio` up, `reply.audio` down).
+ */
+export declare const ASSEMBLYAI_PCM_SAMPLE_RATE = 24000;
+/** A parsed inbound websocket frame. The Voice Agent protocol multiplexes on `type`. */
+export interface AssemblyAIServerEvent {
+    type?: string;
+    /** `session.ready` — the provider-assigned session id (also used by `session.resume`). */
+    session_id?: string;
+    /** `transcript.user[.delta]` / `transcript.agent` — the transcribed text. */
+    text?: string;
+    /** `transcript.*` — provider conversation-item id. */
+    item_id?: string;
+    /** `reply.started` / `transcript.agent` — id of the reply the frame belongs to. */
+    reply_id?: string;
+    /** `transcript.agent` — true when the turn was cut off by a barge-in. */
+    interrupted?: boolean;
+    /** `reply.audio` — one base64 PCM16 chunk of the agent's spoken output. */
+    data?: string;
+    /** `reply.done` — `'interrupted'` when the user barged in mid-reply; absent otherwise. */
+    status?: string;
+    /** `tool.call` — correlation id the result must echo. */
+    call_id?: string;
+    /** `tool.call` — the tool name. */
+    name?: string;
+    /** `tool.call` — the arguments, ALREADY PARSED into an object by the provider. */
+    arguments?: JSONObject;
+    /** `session.error` — provider error code. */
+    code?: string;
+    /** `session.error` — human-readable error message. */
+    message?: string;
+    /** `session.error` — the offending parameter, when applicable. */
+    param?: string;
+    /** `session.updated` — echo of the applied session object. */
+    session?: JSONObject;
+    /** `session.ended` — total billable session seconds. */
+    session_duration_seconds?: number;
+}
+/**
+ * The minimal outbound surface of the agent websocket the session depends on. Declaring the
+ * seam as an interface lets unit tests inject a fully in-memory fake that captures outbound
+ * frames and drives {@link AssemblyAIRealtimeSession.HandleServerEvent} with provider-shaped
+ * events — no websocket, no network.
+ */
+export interface AssemblyAIRealtimeSocket {
+    /** Sends one JSON-serialized client frame. */
+    send(data: string): void;
+    /** Terminates the underlying connection. */
+    close(): void;
+}
+/**
+ * Arguments handed to {@link AssemblyAIRealtime.connectAgentSocket}: the authenticated URL
+ * plus the lifecycle callbacks, so the seam owns the entire websocket dance and tests
+ * substitute it wholesale.
+ */
+export interface AssemblyAIConnectArgs {
+    /** The full `wss://…?token=…` URL (API key for server-bridged, temp token for client-direct). */
+    Url: string;
+    /** Invoked with each parsed inbound frame. */
+    OnMessage: (event: AssemblyAIServerEvent) => 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 **AssemblyAI Voice Agent API** (launched April 2026),
+ * implementing the Core {@link BaseRealtimeModel} primitive. Registers as `AssemblyAIRealtime`
+ * and is resolved for `MJ: AI Models` typed `Realtime` (API-key env alias:
+ * `AI_VENDOR_API_KEY__AssemblyAIRealtime`).
+ *
+ * **What the provider is:** a single-websocket speech-to-speech stack — Universal-3 Pro
+ * streaming ASR, server-side turn detection / barge-in, LLM reasoning, JSON-Schema tool
+ * calling, and conversational TTS — billed flat per session-hour. Unlike ElevenLabs there is
+ * no server-side agent object to manage: the ENTIRE session config (prompt, tools, voice,
+ * turn detection) is supplied per-session via the first `session.update` frame, so MJ's
+ * prompt/tool authority is native here, with no managed-agent ensure flow.
+ *
+ * **Model resolution:** the Voice Agent API exposes ONE endpoint and no model selection;
+ * `params.Model` is carried through to {@link ClientRealtimeSessionConfig.Model} for
+ * bookkeeping but plays no wire role.
+ *
+ * **Topologies:**
+ * - Server-bridged ({@link StartSession}): the driver opens the websocket itself
+ *   (`?token=<api key>`), sends the session config, and resolves only after `session.ready`.
+ * - Client-direct ({@link CreateClientSession}): the driver mints a ONE-TIME, short-lived
+ *   client token (`GET /v1/token`) — the browser opens its own socket with it (no API key
+ *   ever leaves the server) and applies the server-built session object from the
+ *   `SessionConfig` pact.
+ *
+ * **No usage events:** billing is a flat hourly session rate; the websocket reports no token
+ * usage, so sessions never emit {@link IRealtimeSession.OnUsage}. (The terminal
+ * `session.ended` frame carries duration seconds, but by then the consumer has typically
+ * closed — duration accounting lives in the provider dashboard.)
+ */
+export declare class AssemblyAIRealtime extends BaseRealtimeModel {
+    /**
+     * Opens a server-bridged session: connects the agent websocket authenticated with the
+     * API key, sends the full session config as the FIRST frame (`session.update` — prompt,
+     * tools, voice, turn detection), and resolves only once the server's `session.ready`
+     * confirms the config is applied (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.
+     */
+    StartSession(params: RealtimeSessionParams): Promise<IRealtimeSession>;
+    /**
+     * AssemblyAI supports the client-direct topology natively: a one-time temp token minted
+     * server-side authenticates the browser's own websocket.
+     */
+    get SupportsClientDirect(): boolean;
+    /**
+     * Mints the client-direct config: a ONE-TIME client token (connect window
+     * {@link ASSEMBLYAI_TOKEN_TTL_SECONDS}s) plus the **private pact** `SessionConfig` the
+     * same-keyed `'assemblyai'` client driver consumes: `{ session, config }`, where
+     * `session` is the wire-shaped `session.update` payload (server-authored system prompt,
+     * tools, voice, turn detection) and `config` passes `params.Config` through opaquely.
+     */
+    CreateClientSession(params: RealtimeSessionParams): Promise<ClientRealtimeSessionConfig>;
+    /**
+     * Builds the `session` object for the `session.update` frame from the Core params:
+     * - `system_prompt`: the session system prompt, with `InitialContext` folded in under a
+     *   "Prior context" heading — the protocol has no history-seeding channel, so prior
+     *   conversation context rides the prompt.
+     * - `tools`: the Core tool set mapped to the provider's `{ type: 'function', … }` schema.
+     * - Recognized `params.Config` keys pass through to their wire slots: `voice` →
+     *   `output.voice`, `greeting` (spoken on connect; omitted = no auto-greeting),
+     *   `turn_detection` → `input.turn_detection`, `keyterms` → `input.keyterms`.
+     */
+    static BuildSessionObject(params: RealtimeSessionParams): JSONObject;
+    /** Folds optional prior context into the system prompt (no history channel exists). */
+    static ComposeSystemPrompt(systemPrompt: string, initialContext?: string): string;
+    /** Maps a Core tool definition up to a Voice Agent `function` tool schema. */
+    static MapToolToFunction(tool: RealtimeToolDefinition): JSONObject;
+    /**
+     * Canonical, order-insensitive fingerprint of a tool set (same scheme as the Gemini and
+     * ElevenLabs realtime drivers) — used by {@link AssemblyAIRealtimeSession.RegisterTools}
+     * to no-op identical re-registrations.
+     */
+    static ToolSetFingerprint(tools: RealtimeToolDefinition[]): string;
+    /**
+     * REST seam: mints a ONE-TIME client token for a browser-direct session
+     * (`GET /v1/token?expires_in_seconds=…` with `Authorization: Bearer <api key>`).
+     */
+    protected mintClientToken(expiresInSeconds: number): Promise<string>;
+    /**
+     * Transport seam for the server-bridged agent websocket. Production speaks the raw Voice
+     * Agent protocol over the platform-global `WebSocket` (browsers / Node 22+). Resolves
+     * once the socket is OPEN; unit tests override this to return an in-memory fake.
+     */
+    protected connectAgentSocket(args: AssemblyAIConnectArgs): Promise<AssemblyAIRealtimeSocket>;
+}
+/**
+ * Concrete {@link IRealtimeSession} backed by a raw AssemblyAI Voice Agent websocket.
+ *
+ * Owns the inbound translation (flat snake_case wire events → Core events) and the outbound
+ * translation (Core calls → wire frames). Created by {@link AssemblyAIRealtime.StartSession};
+ * never instantiated directly by consumers.
+ *
+ * Provider-behavior notes (the contract deltas a consumer should know):
+ * - **User transcripts have DELTAS, agent transcripts are FINAL-only.** The socket emits
+ *   `transcript.user.delta` fragments followed by a final `transcript.user`; agent turns
+ *   arrive as one final `transcript.agent` (carrying `interrupted: true` after a barge-in,
+ *   in which case the text reflects the truncated turn — already the authoritative record,
+ *   no ElevenLabs-style correction event follows).
+ * - **Interruption signal is `reply.done` with `status: 'interrupted'`** — the provider owns
+ *   turn detection AND tracks its own audio emission, so this is the authoritative "user
+ *   speech cut off active model output" signal (raw `input.speech.started` fires on EVERY
+ *   user utterance and is NOT an interruption per the base contract; the server bridge also
+ *   cannot see host-side playback, so it defers to the provider's verdict).
+ * - **No usage events** — see the driver-level note.
+ * - **{@link RequestSpokenUpdate} is NATIVE** (`reply.create` carries per-response
+ *   instructions — no ElevenLabs-style user-turn emulation, no fidelity caveat), queued
+ *   behind any in-flight response per the contract's collision rule.
+ * - **{@link SendContextNote} is EMULATED via the mutable `system_prompt`**: the protocol
+ *   has no non-interrupting context channel, but `session.update` may rewrite the prompt
+ *   mid-session without triggering generation — notes are appended under a "Background
+ *   updates" heading and the full prompt is re-sent. Never interrupts; the model sees the
+ *   notes the next time it speaks.
+ * - **{@link RegisterTools} re-declares NATIVELY**: `tools` is a mutable `session.update`
+ *   field, so (unlike ElevenLabs) a genuinely different post-start set is applied to the
+ *   live session; an identical set is a silent no-op per the idempotency rule.
+ */
+export declare class AssemblyAIRealtimeSession implements IRealtimeSession {
+    private socket;
+    private outputHandler;
+    private transcriptHandler;
+    private toolCallHandler;
+    private interruptionHandler;
+    private errorHandler;
+    /** True once Close() ran — an expected close must not surface as a fatal error. */
+    private closedByConsumer;
+    /** Resolves when `session.ready` arrives; rejects on transport death. */
+    private readyPromise;
+    private resolveReady;
+    private rejectReady;
+    private readyReceived;
+    /** The wire-shaped `session` object sent in the initial `session.update`. */
+    private sessionObject;
+    /** 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 an agent reply is currently in flight (`reply.started` / first `reply.audio`
+     * sets it; `reply.done` clears it; a `tool.call` clears it WITHOUT draining — deadlock
+     * guard). Consumed by {@link enqueueOrRun} so the native {@link RequestSpokenUpdate}
+     * never triggers a `reply.create` into — and thereby collides with — an active reply.
+     */
+    private responseActive;
+    /** Sends deferred while a reply 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;
+    constructor(sessionObject: JSONObject);
+    /** Binds the underlying socket. Called by the driver once the websocket is open. */
+    AttachSocket(socket: AssemblyAIRealtimeSocket): void;
+    /**
+     * Sends the initial `session.update` frame carrying the full server-authored session
+     * config (prompt, tools, voice, turn detection). Always the FIRST client frame — the
+     * provider drops audio sent before the session is configured and ready.
+     */
+    SendSessionUpdate(): void;
+    /**
+     * Resolves once the server's `session.ready` arrives (the provider's confirmation that
+     * the session config is applied); rejects if the transport dies first. Awaited by
+     * {@link AssemblyAIRealtime.StartSession} so the session is never handed to a consumer
+     * before it is actually configured.
+     */
+    WaitForReady(): Promise<void>;
+    /** @inheritdoc — streams one PCM16 (24 kHz mono) frame as a base64 `input.audio` chunk. */
+    SendInput(chunk: ArrayBuffer): void;
+    /**
+     * @inheritdoc
+     *
+     * `tools` is a MUTABLE `session.update` field on this provider, so re-declaration is
+     * native: an identical set (order-insensitively) is a silent no-op per the contract's
+     * idempotency rule; a different set is applied to the live session immediately.
+     */
+    RegisterTools(tools: RealtimeToolDefinition[]): Promise<void>;
+    /** Records the tool set declared at connect time. Called by {@link AssemblyAIRealtime.StartSession}. */
+    SetConnectTimeTools(tools: RealtimeToolDefinition[]): 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
+     *
+     * Never fires: the Voice Agent websocket reports no token usage — billing is a flat
+     * hourly session rate (see the driver-level note).
+     */
+    OnUsage(_handler: (u: RealtimeUsage) => void): void;
+    /** @inheritdoc */
+    OnError(handler: (error: RealtimeSessionError) => void): void;
+    /**
+     * Surfaces a websocket-level failure as a FATAL session error — the transport is gone,
+     * so the consumer should finalize cleanly instead of idling (driver obligation #6).
+     */
+    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.
+     */
+    HandleTransportClose(code?: number, reason?: string): void;
+    /**
+     * @inheritdoc
+     *
+     * Sends `tool.result` correlated by `call_id`. Sent IMMEDIATELY (never queued): the
+     * provider's own guidance is "send it the moment your tool returns — no buffering, no
+     * waiting on reply.done"; it owns the continuation and speaks the result as soon as the
+     * floor allows. The wire `result` slot expects a JSON-STRING (not an object), which is
+     * exactly the contract's `output` shape — it passes through verbatim. The reply flag is
+     * set eagerly so a queued narration can't slip in before the spoken result.
+     */
+    SendToolResult(callID: string, output: string): Promise<void>;
+    /**
+     * @inheritdoc
+     *
+     * EMULATED via the mutable `system_prompt` (the protocol has no purpose-built context
+     * channel): the note is appended under a "Background updates" heading and the FULL
+     * prompt is re-sent via `session.update` — a config write, so it never triggers or
+     * disturbs generation and is sent immediately even mid-reply. The model has the notes
+     * available the next time it speaks.
+     */
+    SendContextNote(text: string): void;
+    /**
+     * @inheritdoc
+     *
+     * NATIVE on this provider: `reply.create` carries one-off per-response instructions.
+     * **Collision behavior: queue.** A `reply.create` sent mid-reply would collide with the
+     * in-flight generation, so the send is deferred until the active reply completes.
+     */
+    RequestSpokenUpdate(instructions: string): void;
+    /**
+     * @inheritdoc
+     *
+     * Sends `session.end` BEFORE closing the socket — without it the provider holds the
+     * session (billable) for a 30-second resume window.
+     */
+    Close(): Promise<void>;
+    /**
+     * Entry point for an inbound websocket frame. Multiplexes on `type` to focused
+     * per-concern handlers so each translation unit stays small and testable.
+     */
+    HandleServerEvent(event: AssemblyAIServerEvent): void;
+    /** Decodes one base64 reply-audio frame and forwards it as a raw `ArrayBuffer`. */
+    private handleReplyAudio;
+    /**
+     * Reply boundary. `status: 'interrupted'` is the provider's authoritative true-barge-in
+     * verdict (user speech cut off active output — see the class note) and is surfaced via
+     * {@link OnInterruption} BEFORE the boundary releases the floor and drains queued sends.
+     */
+    private handleReplyDone;
+    /**
+     * 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 reply between the tool call
+     * and its result; it drains at the next real reply boundary). The provider emits
+     * `arguments` ALREADY PARSED, so it is re-stringified to honor the Core contract's
+     * JSON-string `Arguments` shape.
+     */
+    private handleToolCall;
+    /**
+     * The provider ended the session itself. After a consumer {@link Close} (which sends
+     * `session.end`) this is the expected acknowledgment and stays silent; otherwise it is
+     * surfaced as FATAL so the consumer finalizes instead of idling on a dying socket.
+     */
+    private handleSessionEnded;
+    /** Reply boundary: releases the busy flag and drains queued sends in order. */
+    private completeResponse;
+    /** Emits a transcript event (user turns have deltas; agent turns are final-only). */
+    private emitTranscript;
+    /** Runs a send immediately when idle; otherwise queues it for the next reply 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 so a closed session can't fire stale callbacks. */
+    private clearHandlers;
+    /** Decodes a base64 audio payload into a freshly-allocated `ArrayBuffer`. */
+    private static Base64ToArrayBuffer;
+}
+//# sourceMappingURL=assemblyAIRealtime.d.ts.map

package/dist/assemblyAIRealtime.d.ts.map

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

package/dist/assemblyAIRealtime.js

@@ -0,0 +1,631 @@
+// AssemblyAI Voice Agent API — realtime (voice) driver.
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var AssemblyAIRealtime_1;
+// MemberJunction AI core contract
+import { BaseRealtimeModel, } from '@memberjunction/ai';
+import { RegisterClass } from '@memberjunction/global';
+/** The single Voice Agent websocket endpoint (auth rides as a `?token=` query parameter). */
+export const ASSEMBLYAI_AGENT_WS_URL = 'wss://agents.assemblyai.com/v1/ws';
+/** REST endpoint that mints one-time, short-lived client tokens for browser-direct sessions. */
+export const ASSEMBLYAI_TOKEN_URL = 'https://agents.assemblyai.com/v1/token';
+/**
+ * Lifetime requested for the one-time client token minted by {@link AssemblyAIRealtime.CreateClientSession}.
+ * The token is single-use: it authenticates ONE websocket open within this window; an
+ * already-open session continues past it.
+ */
+export const ASSEMBLYAI_TOKEN_TTL_SECONDS = 300;
+/**
+ * The Voice Agent wire format: 16-bit signed little-endian PCM, mono, 24 kHz, base64-encoded,
+ * in BOTH directions (`input.audio` up, `reply.audio` down).
+ */
+export const ASSEMBLYAI_PCM_SAMPLE_RATE = 24000;
+/**
+ * Real-time, full-duplex driver for the **AssemblyAI Voice Agent API** (launched April 2026),
+ * implementing the Core {@link BaseRealtimeModel} primitive. Registers as `AssemblyAIRealtime`
+ * and is resolved for `MJ: AI Models` typed `Realtime` (API-key env alias:
+ * `AI_VENDOR_API_KEY__AssemblyAIRealtime`).
+ *
+ * **What the provider is:** a single-websocket speech-to-speech stack — Universal-3 Pro
+ * streaming ASR, server-side turn detection / barge-in, LLM reasoning, JSON-Schema tool
+ * calling, and conversational TTS — billed flat per session-hour. Unlike ElevenLabs there is
+ * no server-side agent object to manage: the ENTIRE session config (prompt, tools, voice,
+ * turn detection) is supplied per-session via the first `session.update` frame, so MJ's
+ * prompt/tool authority is native here, with no managed-agent ensure flow.
+ *
+ * **Model resolution:** the Voice Agent API exposes ONE endpoint and no model selection;
+ * `params.Model` is carried through to {@link ClientRealtimeSessionConfig.Model} for
+ * bookkeeping but plays no wire role.
+ *
+ * **Topologies:**
+ * - Server-bridged ({@link StartSession}): the driver opens the websocket itself
+ *   (`?token=<api key>`), sends the session config, and resolves only after `session.ready`.
+ * - Client-direct ({@link CreateClientSession}): the driver mints a ONE-TIME, short-lived
+ *   client token (`GET /v1/token`) — the browser opens its own socket with it (no API key
+ *   ever leaves the server) and applies the server-built session object from the
+ *   `SessionConfig` pact.
+ *
+ * **No usage events:** billing is a flat hourly session rate; the websocket reports no token
+ * usage, so sessions never emit {@link IRealtimeSession.OnUsage}. (The terminal
+ * `session.ended` frame carries duration seconds, but by then the consumer has typically
+ * closed — duration accounting lives in the provider dashboard.)
+ */
+let AssemblyAIRealtime = AssemblyAIRealtime_1 = class AssemblyAIRealtime extends BaseRealtimeModel {
+    /**
+     * Opens a server-bridged session: connects the agent websocket authenticated with the
+     * API key, sends the full session config as the FIRST frame (`session.update` — prompt,
+     * tools, voice, turn detection), and resolves only once the server's `session.ready`
+     * confirms the config is applied (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.
+     */
+    async StartSession(params) {
+        const session = new AssemblyAIRealtimeSession(AssemblyAIRealtime_1.BuildSessionObject(params));
+        session.SetConnectTimeTools(params.Tools ?? []);
+        const socket = await this.connectAgentSocket({
+            Url: `${ASSEMBLYAI_AGENT_WS_URL}?token=${encodeURIComponent(this.apiKey)}`,
+            OnMessage: (event) => session.HandleServerEvent(event),
+            OnError: (message) => session.HandleTransportError(message),
+            OnClose: (code, reason) => session.HandleTransportClose(code, reason),
+        });
+        session.AttachSocket(socket);
+        session.SendSessionUpdate();
+        await session.WaitForReady();
+        return session;
+    }
+    /**
+     * AssemblyAI supports the client-direct topology natively: a one-time temp token minted
+     * server-side authenticates the browser's own websocket.
+     */
+    get SupportsClientDirect() {
+        return true;
+    }
+    /**
+     * Mints the client-direct config: a ONE-TIME client token (connect window
+     * {@link ASSEMBLYAI_TOKEN_TTL_SECONDS}s) plus the **private pact** `SessionConfig` the
+     * same-keyed `'assemblyai'` client driver consumes: `{ session, config }`, where
+     * `session` is the wire-shaped `session.update` payload (server-authored system prompt,
+     * tools, voice, turn detection) and `config` passes `params.Config` through opaquely.
+     */
+    async CreateClientSession(params) {
+        const token = await this.mintClientToken(ASSEMBLYAI_TOKEN_TTL_SECONDS);
+        return {
+            Provider: 'assemblyai',
+            Model: params.Model,
+            EphemeralToken: token,
+            ExpiresAt: new Date(Date.now() + ASSEMBLYAI_TOKEN_TTL_SECONDS * 1000).toISOString(),
+            SessionConfig: {
+                session: AssemblyAIRealtime_1.BuildSessionObject(params),
+                config: params.Config ?? {},
+            },
+        };
+    }
+    // ── Session-object construction (the wire-shaped `session.update` payload) ──
+    /**
+     * Builds the `session` object for the `session.update` frame from the Core params:
+     * - `system_prompt`: the session system prompt, with `InitialContext` folded in under a
+     *   "Prior context" heading — the protocol has no history-seeding channel, so prior
+     *   conversation context rides the prompt.
+     * - `tools`: the Core tool set mapped to the provider's `{ type: 'function', … }` schema.
+     * - Recognized `params.Config` keys pass through to their wire slots: `voice` →
+     *   `output.voice`, `greeting` (spoken on connect; omitted = no auto-greeting),
+     *   `turn_detection` → `input.turn_detection`, `keyterms` → `input.keyterms`.
+     */
+    static BuildSessionObject(params) {
+        const session = {
+            system_prompt: AssemblyAIRealtime_1.ComposeSystemPrompt(params.SystemPrompt, params.InitialContext),
+        };
+        const tools = params.Tools ?? [];
+        if (tools.length > 0) {
+            session['tools'] = tools.map((tool) => AssemblyAIRealtime_1.MapToolToFunction(tool));
+        }
+        const config = params.Config ?? {};
+        if (typeof config['greeting'] === 'string') {
+            session['greeting'] = config['greeting'];
+        }
+        if (typeof config['voice'] === 'string') {
+            session['output'] = { voice: config['voice'] };
+        }
+        const input = {};
+        if (config['turn_detection'] !== null && typeof config['turn_detection'] === 'object' && !Array.isArray(config['turn_detection'])) {
+            input['turn_detection'] = config['turn_detection'];
+        }
+        if (Array.isArray(config['keyterms'])) {
+            input['keyterms'] = config['keyterms'];
+        }
+        if (Object.keys(input).length > 0) {
+            session['input'] = input;
+        }
+        return session;
+    }
+    /** Folds optional prior context into the system prompt (no history channel exists). */
+    static ComposeSystemPrompt(systemPrompt, initialContext) {
+        const context = initialContext?.trim();
+        return context ? `${systemPrompt}\n\n## Prior context\n${context}` : systemPrompt;
+    }
+    /** Maps a Core tool definition up to a Voice Agent `function` tool schema. */
+    static MapToolToFunction(tool) {
+        return {
+            type: 'function',
+            name: tool.Name,
+            description: tool.Description,
+            // The Core ParametersSchema is a JSON-schema object — the same shape the Voice
+            // Agent's `tools[].parameters` slot accepts.
+            parameters: tool.ParametersSchema,
+        };
+    }
+    /**
+     * Canonical, order-insensitive fingerprint of a tool set (same scheme as the Gemini and
+     * ElevenLabs realtime drivers) — used by {@link AssemblyAIRealtimeSession.RegisterTools}
+     * to no-op identical re-registrations.
+     */
+    static ToolSetFingerprint(tools) {
+        return JSON.stringify([...tools]
+            .sort((a, b) => a.Name.localeCompare(b.Name))
+            .map((t) => ({ Name: t.Name, Description: t.Description, ParametersSchema: t.ParametersSchema })));
+    }
+    // ── Overridable REST / transport seams (tests inject fakes — no network) ──
+    /**
+     * REST seam: mints a ONE-TIME client token for a browser-direct session
+     * (`GET /v1/token?expires_in_seconds=…` with `Authorization: Bearer <api key>`).
+     */
+    async mintClientToken(expiresInSeconds) {
+        const fetchFn = globalThis.fetch;
+        if (!fetchFn) {
+            throw new Error('AssemblyAIRealtime.CreateClientSession requires a global fetch (Node 18+ or a browser runtime).');
+        }
+        const response = await fetchFn(`${ASSEMBLYAI_TOKEN_URL}?expires_in_seconds=${expiresInSeconds}`, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${this.apiKey}` },
+        });
+        if (!response.ok) {
+            throw new Error(`AssemblyAI token mint failed with HTTP ${response.status}`);
+        }
+        const body = (await response.json());
+        if (!body.token) {
+            throw new Error('AssemblyAI token mint returned no token');
+        }
+        return body.token;
+    }
+    /**
+     * Transport seam for the server-bridged agent websocket. Production speaks the raw Voice
+     * Agent protocol over the platform-global `WebSocket` (browsers / Node 22+). Resolves
+     * once the socket is OPEN; unit tests override this to return an in-memory fake.
+     */
+    async connectAgentSocket(args) {
+        const WS = globalThis.WebSocket;
+        if (!WS) {
+            throw new Error('AssemblyAIRealtime.StartSession requires a global WebSocket (Node 22+ or a browser runtime).');
+        }
+        return new Promise((resolve, reject) => {
+            const ws = new WS(args.Url);
+            let opened = false;
+            ws.onopen = () => {
+                opened = true;
+                resolve({ send: (data) => ws.send(data), close: () => ws.close() });
+            };
+            ws.onmessage = (event) => {
+                try {
+                    args.OnMessage(JSON.parse(String(event.data)));
+                }
+                catch {
+                    /* non-JSON frame — ignore */
+                }
+            };
+            ws.onerror = () => {
+                args.OnError('AssemblyAI agent websocket error');
+                if (!opened) {
+                    reject(new Error('AssemblyAI agent websocket failed to open'));
+                }
+            };
+            ws.onclose = (event) => {
+                args.OnClose(event.code, event.reason);
+                if (!opened) {
+                    reject(new Error('AssemblyAI agent websocket closed before opening'));
+                }
+            };
+        });
+    }
+};
+AssemblyAIRealtime = AssemblyAIRealtime_1 = __decorate([
+    RegisterClass(BaseRealtimeModel, 'AssemblyAIRealtime')
+], AssemblyAIRealtime);
+export { AssemblyAIRealtime };
+/**
+ * Concrete {@link IRealtimeSession} backed by a raw AssemblyAI Voice Agent websocket.
+ *
+ * Owns the inbound translation (flat snake_case wire events → Core events) and the outbound
+ * translation (Core calls → wire frames). Created by {@link AssemblyAIRealtime.StartSession};
+ * never instantiated directly by consumers.
+ *
+ * Provider-behavior notes (the contract deltas a consumer should know):
+ * - **User transcripts have DELTAS, agent transcripts are FINAL-only.** The socket emits
+ *   `transcript.user.delta` fragments followed by a final `transcript.user`; agent turns
+ *   arrive as one final `transcript.agent` (carrying `interrupted: true` after a barge-in,
+ *   in which case the text reflects the truncated turn — already the authoritative record,
+ *   no ElevenLabs-style correction event follows).
+ * - **Interruption signal is `reply.done` with `status: 'interrupted'`** — the provider owns
+ *   turn detection AND tracks its own audio emission, so this is the authoritative "user
+ *   speech cut off active model output" signal (raw `input.speech.started` fires on EVERY
+ *   user utterance and is NOT an interruption per the base contract; the server bridge also
+ *   cannot see host-side playback, so it defers to the provider's verdict).
+ * - **No usage events** — see the driver-level note.
+ * - **{@link RequestSpokenUpdate} is NATIVE** (`reply.create` carries per-response
+ *   instructions — no ElevenLabs-style user-turn emulation, no fidelity caveat), queued
+ *   behind any in-flight response per the contract's collision rule.
+ * - **{@link SendContextNote} is EMULATED via the mutable `system_prompt`**: the protocol
+ *   has no non-interrupting context channel, but `session.update` may rewrite the prompt
+ *   mid-session without triggering generation — notes are appended under a "Background
+ *   updates" heading and the full prompt is re-sent. Never interrupts; the model sees the
+ *   notes the next time it speaks.
+ * - **{@link RegisterTools} re-declares NATIVELY**: `tools` is a mutable `session.update`
+ *   field, so (unlike ElevenLabs) a genuinely different post-start set is applied to the
+ *   live session; an identical set is a silent no-op per the idempotency rule.
+ */
+export class AssemblyAIRealtimeSession {
+    constructor(sessionObject) {
+        this.socket = null;
+        this.outputHandler = null;
+        this.transcriptHandler = null;
+        this.toolCallHandler = null;
+        this.interruptionHandler = null;
+        this.errorHandler = null;
+        /** True once Close() ran — an expected close must not surface as a fatal error. */
+        this.closedByConsumer = false;
+        this.resolveReady = null;
+        this.rejectReady = null;
+        this.readyReceived = false;
+        /** Accumulated {@link SendContextNote} texts, re-sent with the full prompt each time. */
+        this.contextNotes = [];
+        /**
+         * Whether an agent reply is currently in flight (`reply.started` / first `reply.audio`
+         * sets it; `reply.done` clears it; a `tool.call` clears it WITHOUT draining — deadlock
+         * guard). Consumed by {@link enqueueOrRun} so the native {@link RequestSpokenUpdate}
+         * never triggers a `reply.create` into — and thereby collides with — an active reply.
+         */
+        this.responseActive = false;
+        /** Sends deferred while a reply is in flight; drained in order at the next boundary. */
+        this.queuedSends = [];
+        /**
+         * Fingerprint of the tool set currently declared on the session;
+         * {@link RegisterTools} compares against it to no-op identical re-registrations.
+         */
+        this.currentToolsFingerprint = AssemblyAIRealtime.ToolSetFingerprint([]);
+        this.sessionObject = sessionObject;
+        this.basePrompt = typeof sessionObject['system_prompt'] === 'string' ? sessionObject['system_prompt'] : '';
+        this.readyPromise = new Promise((resolve, reject) => {
+            this.resolveReady = resolve;
+            this.rejectReady = reject;
+        });
+        // The promise is always consumed by WaitForReady before any rejection can fire
+        // (StartSession awaits it immediately), but guard against unhandled-rejection noise
+        // if a transport error lands between construction and the await.
+        this.readyPromise.catch(() => undefined);
+    }
+    /** Binds the underlying socket. Called by the driver once the websocket is open. */
+    AttachSocket(socket) {
+        this.socket = socket;
+    }
+    /**
+     * Sends the initial `session.update` frame carrying the full server-authored session
+     * config (prompt, tools, voice, turn detection). Always the FIRST client frame — the
+     * provider drops audio sent before the session is configured and ready.
+     */
+    SendSessionUpdate() {
+        this.sendFrame({ type: 'session.update', session: this.sessionObject });
+    }
+    /**
+     * Resolves once the server's `session.ready` arrives (the provider's confirmation that
+     * the session config is applied); rejects if the transport dies first. Awaited by
+     * {@link AssemblyAIRealtime.StartSession} so the session is never handed to a consumer
+     * before it is actually configured.
+     */
+    WaitForReady() {
+        return this.readyPromise;
+    }
+    /** @inheritdoc — streams one PCM16 (24 kHz mono) frame as a base64 `input.audio` chunk. */
+    SendInput(chunk) {
+        this.sendFrame({ type: 'input.audio', audio: Buffer.from(new Uint8Array(chunk)).toString('base64') });
+    }
+    /**
+     * @inheritdoc
+     *
+     * `tools` is a MUTABLE `session.update` field on this provider, so re-declaration is
+     * native: an identical set (order-insensitively) is a silent no-op per the contract's
+     * idempotency rule; a different set is applied to the live session immediately.
+     */
+    async RegisterTools(tools) {
+        const fingerprint = AssemblyAIRealtime.ToolSetFingerprint(tools);
+        if (fingerprint === this.currentToolsFingerprint) {
+            return; // identical to the declared set — silent no-op
+        }
+        this.currentToolsFingerprint = fingerprint;
+        this.sendFrame({
+            type: 'session.update',
+            session: { tools: tools.map((tool) => AssemblyAIRealtime.MapToolToFunction(tool)) },
+        });
+    }
+    /** Records the tool set declared at connect time. Called by {@link AssemblyAIRealtime.StartSession}. */
+    SetConnectTimeTools(tools) {
+        this.currentToolsFingerprint = AssemblyAIRealtime.ToolSetFingerprint(tools);
+    }
+    /** @inheritdoc */
+    OnOutput(handler) {
+        this.outputHandler = handler;
+    }
+    /** @inheritdoc */
+    OnTranscript(handler) {
+        this.transcriptHandler = handler;
+    }
+    /** @inheritdoc */
+    OnToolCall(handler) {
+        this.toolCallHandler = handler;
+    }
+    /** @inheritdoc */
+    OnInterruption(handler) {
+        this.interruptionHandler = handler;
+    }
+    /**
+     * @inheritdoc
+     *
+     * Never fires: the Voice Agent websocket reports no token usage — billing is a flat
+     * hourly session rate (see the driver-level note).
+     */
+    OnUsage(_handler) {
+        // intentionally unbound — no usage events exist on this provider surface
+    }
+    /** @inheritdoc */
+    OnError(handler) {
+        this.errorHandler = handler;
+    }
+    /**
+     * Surfaces a websocket-level failure as a FATAL session error — the transport is gone,
+     * so the consumer should finalize cleanly instead of idling (driver obligation #6).
+     */
+    HandleTransportError(message) {
+        this.failReadyWait(message);
+        this.errorHandler?.({ Message: message, Fatal: true });
+    }
+    /**
+     * 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.
+     */
+    HandleTransportClose(code, reason) {
+        if (this.closedByConsumer) {
+            return;
+        }
+        const detail = [code != null ? `code ${code}` : null, reason || null].filter(Boolean).join(' — ');
+        const message = `AssemblyAI agent session closed unexpectedly${detail ? ` (${detail})` : ''}`;
+        this.failReadyWait(message);
+        this.errorHandler?.({ Message: message, Fatal: true });
+    }
+    /**
+     * @inheritdoc
+     *
+     * Sends `tool.result` correlated by `call_id`. Sent IMMEDIATELY (never queued): the
+     * provider's own guidance is "send it the moment your tool returns — no buffering, no
+     * waiting on reply.done"; it owns the continuation and speaks the result as soon as the
+     * floor allows. The wire `result` slot expects a JSON-STRING (not an object), which is
+     * exactly the contract's `output` shape — it passes through verbatim. The reply flag is
+     * set eagerly so a queued narration can't slip in before the spoken result.
+     */
+    async SendToolResult(callID, output) {
+        this.sendFrame({ type: 'tool.result', call_id: callID, result: output });
+        this.responseActive = true; // the result's spoken continuation is imminent
+    }
+    /**
+     * @inheritdoc
+     *
+     * EMULATED via the mutable `system_prompt` (the protocol has no purpose-built context
+     * channel): the note is appended under a "Background updates" heading and the FULL
+     * prompt is re-sent via `session.update` — a config write, so it never triggers or
+     * disturbs generation and is sent immediately even mid-reply. The model has the notes
+     * available the next time it speaks.
+     */
+    SendContextNote(text) {
+        this.contextNotes.push(text);
+        this.sendFrame({ type: 'session.update', session: { system_prompt: this.composePromptWithNotes() } });
+    }
+    /**
+     * @inheritdoc
+     *
+     * NATIVE on this provider: `reply.create` carries one-off per-response instructions.
+     * **Collision behavior: queue.** A `reply.create` sent mid-reply would collide with the
+     * in-flight generation, so the send is deferred until the active reply completes.
+     */
+    RequestSpokenUpdate(instructions) {
+        this.enqueueOrRun(() => {
+            this.responseActive = true; // the instructed reply is now in flight
+            this.sendFrame({ type: 'reply.create', instructions });
+        });
+    }
+    /**
+     * @inheritdoc
+     *
+     * Sends `session.end` BEFORE closing the socket — without it the provider holds the
+     * session (billable) for a 30-second resume window.
+     */
+    async Close() {
+        this.closedByConsumer = true;
+        this.failReadyWait('session closed by consumer before session.ready arrived');
+        if (this.socket) {
+            try {
+                this.sendFrame({ type: 'session.end' });
+            }
+            catch {
+                /* socket already dead — closing anyway */
+            }
+        }
+        this.socket?.close();
+        this.socket = null;
+        this.clearHandlers();
+    }
+    /**
+     * Entry point for an inbound websocket frame. Multiplexes on `type` to focused
+     * per-concern handlers so each translation unit stays small and testable.
+     */
+    HandleServerEvent(event) {
+        switch (event.type) {
+            case 'session.ready':
+                this.readyReceived = true;
+                this.resolveReady?.();
+                break;
+            case 'session.updated':
+                break; // config-apply confirmation — nothing to surface
+            case 'reply.started':
+                this.responseActive = true;
+                break;
+            case 'reply.audio':
+                this.handleReplyAudio(event.data);
+                break;
+            case 'transcript.user.delta':
+                this.emitTranscript('user', event.text, false);
+                break;
+            case 'transcript.user':
+                this.emitTranscript('user', event.text, true);
+                break;
+            case 'transcript.agent':
+                this.emitTranscript('assistant', event.text, true);
+                break;
+            case 'reply.done':
+                this.handleReplyDone(event.status);
+                break;
+            case 'tool.call':
+                this.handleToolCall(event);
+                break;
+            case 'input.speech.started':
+            case 'input.speech.stopped':
+                break; // raw VAD telemetry — NOT an interruption signal (see the class note)
+            case 'session.error':
+                this.errorHandler?.({
+                    Message: event.message ?? 'AssemblyAI session error',
+                    Code: event.code,
+                    Fatal: false,
+                });
+                break;
+            case 'session.ended':
+                this.handleSessionEnded();
+                break;
+            default:
+                break; // unknown / future frame types are ignored
+        }
+    }
+    /** Decodes one base64 reply-audio frame and forwards it as a raw `ArrayBuffer`. */
+    handleReplyAudio(audioBase64) {
+        if (!audioBase64) {
+            return;
+        }
+        this.responseActive = true;
+        this.outputHandler?.(AssemblyAIRealtimeSession.Base64ToArrayBuffer(audioBase64));
+    }
+    /**
+     * Reply boundary. `status: 'interrupted'` is the provider's authoritative true-barge-in
+     * verdict (user speech cut off active output — see the class note) and is surfaced via
+     * {@link OnInterruption} BEFORE the boundary releases the floor and drains queued sends.
+     */
+    handleReplyDone(status) {
+        if (status === 'interrupted') {
+            this.interruptionHandler?.();
+        }
+        this.completeResponse();
+    }
+    /**
+     * 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 reply between the tool call
+     * and its result; it drains at the next real reply boundary). The provider emits
+     * `arguments` ALREADY PARSED, so it is re-stringified to honor the Core contract's
+     * JSON-string `Arguments` shape.
+     */
+    handleToolCall(event) {
+        this.responseActive = false;
+        this.toolCallHandler?.({
+            CallID: event.call_id ?? '',
+            ToolName: event.name ?? '',
+            Arguments: JSON.stringify(event.arguments ?? {}),
+        });
+    }
+    /**
+     * The provider ended the session itself. After a consumer {@link Close} (which sends
+     * `session.end`) this is the expected acknowledgment and stays silent; otherwise it is
+     * surfaced as FATAL so the consumer finalizes instead of idling on a dying socket.
+     */
+    handleSessionEnded() {
+        if (this.closedByConsumer) {
+            return;
+        }
+        const message = 'AssemblyAI agent session ended by the provider';
+        this.failReadyWait(message);
+        this.errorHandler?.({ Message: message, Fatal: true });
+    }
+    /** Reply boundary: releases the busy flag and drains queued sends in order. */
+    completeResponse() {
+        this.responseActive = false;
+        while (!this.responseActive && this.queuedSends.length > 0) {
+            const send = this.queuedSends.shift();
+            send?.();
+        }
+    }
+    /** Emits a transcript event (user turns have deltas; agent turns are final-only). */
+    emitTranscript(role, text, isFinal) {
+        if (!this.transcriptHandler || !text || text.trim().length === 0) {
+            return;
+        }
+        this.transcriptHandler({ Role: role, Text: text, IsFinal: isFinal });
+    }
+    /** Runs a send immediately when idle; otherwise queues it for the next reply boundary. */
+    enqueueOrRun(send) {
+        if (this.responseActive) {
+            this.queuedSends.push(send);
+            return;
+        }
+        send();
+    }
+    /** The base prompt plus every accumulated context note under a "Background updates" heading. */
+    composePromptWithNotes() {
+        if (this.contextNotes.length === 0) {
+            return this.basePrompt;
+        }
+        return `${this.basePrompt}\n\n## Background updates\n${this.contextNotes.map((n) => `- ${n}`).join('\n')}`;
+    }
+    /** JSON-serializes and sends one client frame (throws if the socket was never attached). */
+    sendFrame(frame) {
+        if (!this.socket) {
+            throw new Error('AssemblyAI realtime session is not open (no socket attached or it was closed).');
+        }
+        this.socket.send(JSON.stringify(frame));
+    }
+    /** Rejects a still-pending ready wait (transport death / consumer close during startup). */
+    failReadyWait(message) {
+        if (!this.readyReceived && this.rejectReady) {
+            const reject = this.rejectReady;
+            this.rejectReady = null;
+            this.resolveReady = null;
+            this.readyReceived = true; // nothing further can resolve/reject it
+            reject(new Error(message));
+        }
+    }
+    /** Drops all registered handlers so a closed session can't fire stale callbacks. */
+    clearHandlers() {
+        this.outputHandler = null;
+        this.transcriptHandler = null;
+        this.toolCallHandler = null;
+        this.interruptionHandler = null;
+        this.queuedSends = [];
+        this.responseActive = false;
+    }
+    /** Decodes a base64 audio payload into a freshly-allocated `ArrayBuffer`. */
+    static Base64ToArrayBuffer(base64) {
+        const bytes = Buffer.from(base64, 'base64');
+        const out = new ArrayBuffer(bytes.byteLength);
+        new Uint8Array(out).set(bytes);
+        return out;
+    }
+}
+//# sourceMappingURL=assemblyAIRealtime.js.map

package/dist/assemblyAIRealtime.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './assemblyAIRealtime.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,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+// AssemblyAI Voice Agent API — realtime (voice) driver. BaseRealtimeModel implementation.
+export * from './assemblyAIRealtime.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,0FAA0F;AAC1F,cAAc,sBAAsB,CAAC"}

package/package.json

@@ -1,10 +1,29 @@
 {
   "name": "@memberjunction/ai-assemblyai",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @memberjunction/ai-assemblyai",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "type": "module",
+  "version": "5.41.0",
+  "description": "MemberJunction Wrapper for AssemblyAI - Voice Agent API realtime driver",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist"
+  ],
+  "scripts": {
+    "build": "tsc && tsc-alias -f",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "author": "MemberJunction.com",
+  "license": "ISC",
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@memberjunction/ai": "5.41.0",
+    "@memberjunction/global": "5.41.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MemberJunction/MJ"
+  }
 }

package/readme.md

@@ -0,0 +1,48 @@
+# @memberjunction/ai-assemblyai
+
+MemberJunction provider package for **AssemblyAI**, currently exposing the **Voice Agent API**
+(launched April 2026) as a realtime, full-duplex, tool-calling model.
+
+## What this package provides
+
+- **`AssemblyAIRealtime`** — a `BaseRealtimeModel` driver (registered via
+  `@RegisterClass(BaseRealtimeModel, 'AssemblyAIRealtime')`) for AssemblyAI's single-websocket
+  speech-to-speech stack: Universal-3 Pro streaming ASR, server-side turn detection and
+  barge-in, LLM reasoning, JSON-Schema tool calling, and conversational TTS.
+- **`AssemblyAIRealtimeSession`** — the `IRealtimeSession` implementation backing the
+  server-bridged topology.
+
+The matching **browser-direct client driver** (`AssemblyAIRealtimeClient`, ClassFactory key
+`'assemblyai'`) ships in `@memberjunction/ai-realtime-client`.
+
+## Provider characteristics
+
+| Concern | How this provider does it |
+| --- | --- |
+| Endpoint | One websocket: `wss://agents.assemblyai.com/v1/ws?token=…` |
+| Session config | Native per-session `session.update` (prompt, tools, voice, turn detection) — no server-side agent object to manage |
+| Audio | PCM16 mono **24 kHz**, base64, both directions (fixed — no negotiation) |
+| Tool calling | JSON-Schema `function` tools; `tool.call` arguments arrive parsed; `tool.result` takes a JSON **string** |
+| Tools mid-session | **Mutable** — `RegisterTools` re-declares natively via `session.update` |
+| Narration (`RequestSpokenUpdate`) | **Native** via `reply.create` instructions |
+| Context notes (`SendContextNote`) | Emulated via the **mutable `system_prompt`** ("Background updates" section) |
+| Typed text (client `SendText`) | Emulated via `reply.create` instructions (no typed-input wire event) |
+| Interruption | `reply.done` `status: 'interrupted'` (authoritative); the client driver also flushes on `input.speech.started` while output is active for snappier barge-in |
+| Usage events | **None** — flat hourly session billing ($4.50/hr); `OnUsage` never fires |
+| Client-direct | Supported — one-time temp token minted via `GET /v1/token` (Bearer API key) |
+| Session end | `Close()`/`Disconnect()` send `session.end` first — skipping it leaves a billable 30-second resume hold |
+
+## Configuration
+
+- API key env alias: `AI_VENDOR_API_KEY__AssemblyAIRealtime`
+- `RealtimeSessionParams.Config` passthrough keys: `voice`, `greeting`, `turn_detection`
+  (object), `keyterms` (string array)
+- `Model` / `APIName` plays no wire role (single endpoint, no model selection) — the metadata
+  row uses `voice-agent`
+
+## Docs
+
+- Product: https://www.assemblyai.com/products/voice-agent-api
+- API reference: https://www.assemblyai.com/docs/voice-agents/voice-agent-api
+- Token endpoint: `GET https://agents.assemblyai.com/v1/token?expires_in_seconds=…`
+- Full MJ realtime architecture (topologies, co-agent model, four-provider capability matrix): [guides/REALTIME_CO_AGENTS_GUIDE.md](../../../../guides/REALTIME_CO_AGENTS_GUIDE.md)

package/README.md

@@ -1,45 +0,0 @@
-# @memberjunction/ai-assemblyai
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/ai-assemblyai`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**