@alexkroman1/aai 0.4.0 → 0.6.0

package/dist/sdk/session.js

@@ -0,0 +1,324 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * S2S session — relays audio between the client and AssemblyAI's
+ * Speech-to-Speech API, intercepting only tool calls for local execution.
+ *
+ * Cross-runtime: accepts Logger, Metrics, and a WebSocket factory via
+ * dependency injection.
+ *
+ * @module
+ */
+import { HOOK_TIMEOUT_MS } from "./protocol.js";
+import { consoleLogger, noopMetrics } from "./runtime.js";
+import { connectS2s, } from "./s2s.js";
+import { buildSystemPrompt } from "./system_prompt.js";
+export const _internals = {
+    connectS2s,
+};
+/** Create an S2S-backed session with the same interface as the STT+LLM+TTS session. */
+export function createS2sSession(opts) {
+    const { id, agent, client, toolSchemas, apiKey, s2sConfig, executeTool, createWebSocket, hookInvoker, logger: log = consoleLogger, metrics = noopMetrics, } = opts;
+    const agentLabel = { agent };
+    const agentConfig = opts.skipGreeting ? { ...opts.agentConfig, greeting: "" } : opts.agentConfig;
+    // Build system prompt
+    const hasTools = toolSchemas.length > 0 || (agentConfig.builtinTools?.length ?? 0) > 0;
+    const systemPrompt = buildSystemPrompt(agentConfig, {
+        hasTools,
+        voice: true,
+    });
+    // toolSchemas already includes both agent-defined and builtin tools
+    const s2sTools = toolSchemas.map((ts) => ({
+        type: "function",
+        name: ts.name,
+        description: ts.description,
+        parameters: ts.parameters,
+    }));
+    let s2s = null;
+    const sessionAbort = new AbortController();
+    let audioReady = false;
+    let toolCallCount = 0;
+    let turnPromise = null;
+    let conversationMessages = [];
+    let s2sSessionId = null;
+    let pendingTools = [];
+    async function resolveTurnConfig() {
+        if (!hookInvoker)
+            return null;
+        try {
+            return await hookInvoker.resolveTurnConfig(id, HOOK_TIMEOUT_MS);
+        }
+        catch {
+            return null;
+        }
+    }
+    async function invokeHook(hook, ...args) {
+        if (!hookInvoker)
+            return;
+        try {
+            switch (hook) {
+                case "onConnect":
+                    await hookInvoker.onConnect(id, HOOK_TIMEOUT_MS);
+                    break;
+                case "onDisconnect":
+                    await hookInvoker.onDisconnect(id, HOOK_TIMEOUT_MS);
+                    break;
+                case "onTurn":
+                    await hookInvoker.onTurn(id, args[0], HOOK_TIMEOUT_MS);
+                    break;
+                case "onError":
+                    await hookInvoker.onError(id, args[0], HOOK_TIMEOUT_MS);
+                    break;
+                case "onStep":
+                    await hookInvoker.onStep(id, args[0], HOOK_TIMEOUT_MS);
+                    break;
+            }
+        }
+        catch (err) {
+            log.warn(`${hook} hook failed`, {
+                err: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    async function handleToolCall(detail) {
+        const { call_id, name, args: parsedArgs } = detail;
+        // Emit tool_call_start to client
+        client.event({
+            type: "tool_call_start",
+            toolCallId: call_id,
+            toolName: name,
+            args: parsedArgs,
+        });
+        // Resolve turn config for maxSteps / activeTools
+        const turnConfig = await resolveTurnConfig();
+        const maxSteps = turnConfig?.maxSteps ?? agentConfig.maxSteps;
+        toolCallCount++;
+        // Check maxSteps
+        if (maxSteps !== undefined && toolCallCount > maxSteps) {
+            log.info("maxSteps exceeded, refusing tool call", {
+                toolCallCount,
+                maxSteps,
+            });
+            pendingTools.push({
+                call_id,
+                result: "Maximum tool steps reached. Please respond to the user now.",
+            });
+            client.event({ type: "tool_call_done", toolCallId: call_id, result: "" });
+            return;
+        }
+        // Check activeTools filter
+        if (turnConfig?.activeTools && !turnConfig.activeTools.includes(name)) {
+            log.info("Tool filtered by activeTools", { name });
+            const errResult = JSON.stringify({
+                error: `Tool "${name}" is not available at this step.`,
+            });
+            pendingTools.push({ call_id, result: errResult });
+            client.event({
+                type: "tool_call_done",
+                toolCallId: call_id,
+                result: errResult,
+            });
+            return;
+        }
+        // Fire onStep hook
+        invokeHook("onStep", {
+            stepNumber: toolCallCount - 1,
+            toolCalls: [{ toolName: name, args: parsedArgs }],
+            text: "",
+        });
+        log.info("S2S tool call", { tool: name, call_id, args: parsedArgs, agent });
+        // Execute — all tools (custom + builtin) run via the executor
+        let result;
+        try {
+            result = await executeTool(name, parsedArgs, id, conversationMessages);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log.error("Tool execution failed", { tool: name, error: msg });
+            result = JSON.stringify({ error: msg });
+        }
+        log.info("S2S tool result", {
+            tool: name,
+            call_id,
+            resultLength: result.length,
+        });
+        // Accumulate — don't send yet. Results are sent after reply.done.
+        pendingTools.push({ call_id, result });
+        client.event({ type: "tool_call_done", toolCallId: call_id, result });
+    }
+    async function connectAndSetup() {
+        try {
+            const handle = await _internals.connectS2s({
+                apiKey,
+                config: s2sConfig,
+                createWebSocket,
+                logger: log,
+            });
+            // Send session.update immediately on connect — before session.ready.
+            if (s2sSessionId) {
+                log.info("Attempting S2S session resume", {
+                    session_id: s2sSessionId,
+                });
+                handle.resumeSession(s2sSessionId);
+            }
+            // Send config with greeting on initial connect.
+            // Audio may arrive before the client is ready — the client buffers it.
+            handle.updateSession({
+                system_prompt: systemPrompt,
+                tools: s2sTools,
+                ...(agentConfig.greeting ? { greeting: agentConfig.greeting } : {}),
+            });
+            handle.addEventListener("ready", ((e) => {
+                s2sSessionId = e.detail.session_id;
+                log.info("S2S session ready", { session_id: s2sSessionId });
+            }));
+            handle.addEventListener("session_expired", (() => {
+                log.info("S2S session expired, reconnecting fresh");
+                s2sSessionId = null;
+                handle.close();
+            }));
+            handle.addEventListener("speech_started", () => {
+                client.event({ type: "speech_started" });
+            });
+            handle.addEventListener("speech_stopped", () => {
+                client.event({ type: "speech_stopped" });
+            });
+            handle.addEventListener("user_transcript_delta", ((e) => {
+                client.event({
+                    type: "transcript",
+                    text: e.detail.text,
+                    isFinal: false,
+                });
+            }));
+            handle.addEventListener("user_transcript", ((e) => {
+                const { text } = e.detail;
+                log.info("S2S user transcript", { text });
+                client.event({ type: "transcript", text, isFinal: true });
+                client.event({ type: "turn", text });
+                conversationMessages.push({ role: "user", content: text });
+                invokeHook("onTurn", text);
+            }));
+            handle.addEventListener("reply_started", () => {
+                toolCallCount = 0;
+            });
+            handle.addEventListener("audio", ((e) => {
+                client.playAudioChunk(e.detail.audio);
+            }));
+            handle.addEventListener("agent_transcript", ((e) => {
+                const { text } = e.detail;
+                client.event({ type: "chat", text });
+                conversationMessages.push({ role: "assistant", content: text });
+            }));
+            handle.addEventListener("tool_call", ((e) => {
+                const p = handleToolCall(e.detail).catch((err) => {
+                    log.error("Tool call handler failed", {
+                        err: err instanceof Error ? err.message : String(err),
+                    });
+                });
+                const prev = turnPromise;
+                turnPromise = (prev ?? Promise.resolve())
+                    .then(() => p)
+                    .finally(() => {
+                    turnPromise = null;
+                });
+            }));
+            handle.addEventListener("reply_done", ((e) => {
+                if (e.detail.status === "interrupted") {
+                    log.info("S2S reply interrupted (barge-in)");
+                    // Discard pending tool results on interruption.
+                    pendingTools = [];
+                    client.event({ type: "cancelled" });
+                }
+                else {
+                    // Send all accumulated tool results after reply.done.
+                    if (pendingTools.length > 0) {
+                        for (const tool of pendingTools) {
+                            s2s?.sendToolResult(tool.call_id, tool.result);
+                        }
+                        pendingTools = [];
+                    }
+                    else {
+                        client.playAudioDone();
+                        client.event({ type: "tts_done" });
+                    }
+                }
+            }));
+            handle.addEventListener("error", ((e) => {
+                log.error("S2S error", {
+                    code: e.detail.code,
+                    message: e.detail.message,
+                });
+                client.event({
+                    type: "error",
+                    code: "internal",
+                    message: e.detail.message,
+                });
+            }));
+            handle.addEventListener("close", () => {
+                log.info("S2S closed");
+                s2s = null;
+                if (!sessionAbort.signal.aborted) {
+                    log.info("Attempting S2S reconnect");
+                    connectAndSetup().catch((err) => {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        log.error("S2S reconnect failed", { error: msg });
+                    });
+                }
+            });
+            s2s = handle;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            log.error("S2S connect failed", { error: msg });
+            client.event({ type: "error", code: "internal", message: msg });
+        }
+    }
+    return {
+        async start() {
+            metrics.sessionsTotal.inc(agentLabel);
+            metrics.sessionsActive.inc(agentLabel);
+            invokeHook("onConnect");
+            await connectAndSetup();
+        },
+        async stop() {
+            if (sessionAbort.signal.aborted)
+                return;
+            sessionAbort.abort();
+            metrics.sessionsActive.dec(agentLabel);
+            if (turnPromise)
+                await turnPromise;
+            s2s?.close();
+            invokeHook("onDisconnect");
+        },
+        onAudio(data) {
+            s2s?.sendAudio(data);
+        },
+        onAudioReady() {
+            if (audioReady)
+                return;
+            audioReady = true;
+            // Greeting audio + transcript come from S2S automatically.
+        },
+        onCancel() {
+            // S2S handles barge-in natively.
+            client.event({ type: "cancelled" });
+        },
+        onReset() {
+            conversationMessages = [];
+            toolCallCount = 0;
+            pendingTools = [];
+            s2sSessionId = null;
+            s2s?.close();
+            // Reconnect happens via the close handler.
+            client.event({ type: "reset" });
+        },
+        onHistory(incoming) {
+            for (const msg of incoming) {
+                conversationMessages.push({ role: msg.role, content: msg.text });
+            }
+        },
+        waitForTurn() {
+            return turnPromise ?? Promise.resolve();
+        },
+    };
+}
+//# sourceMappingURL=session.js.map

package/dist/sdk/session.js.map

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

package/dist/sdk/system_prompt.d.ts

@@ -0,0 +1,6 @@
+import type { AgentConfig } from "./_internal_types.ts";
+export declare function buildSystemPrompt(config: AgentConfig, opts: {
+    hasTools: boolean;
+    voice?: boolean;
+}): string;
+//# sourceMappingURL=system_prompt.d.ts.map

package/dist/sdk/system_prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system_prompt.d.ts","sourceRoot":"","sources":["../../sdk/system_prompt.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAexD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3C,MAAM,CA0BR"}

package/dist/sdk/system_prompt.js

@@ -0,0 +1,35 @@
+// Copyright 2025 the AAI authors. MIT license.
+import { DEFAULT_INSTRUCTIONS } from "./types.js";
+const VOICE_RULES = "\n\nCRITICAL OUTPUT RULES — you MUST follow these for EVERY response:\n" +
+    "Your response will be spoken aloud by a TTS system and displayed as plain text.\n" +
+    "- NEVER use markdown: no **, no *, no _, no #, no `, no [](), no ---\n" +
+    "- NEVER use bullet points (-, *, •) or numbered lists (1., 2.)\n" +
+    "- NEVER use code blocks or inline code\n" +
+    "- NEVER mention tools, search, APIs, or technical failures to the user. " +
+    "If a tool returns no results, just answer naturally without explaining why.\n" +
+    "- Write exactly as you would say it out loud to a friend\n" +
+    '- Use short conversational sentences. To list things, say "First," "Next," "Finally,"\n' +
+    "- Keep responses concise — 1 to 3 sentences max";
+export function buildSystemPrompt(config, opts) {
+    const { hasTools } = opts;
+    const agentInstructions = config.instructions
+        ? `\n\nAgent-Specific Instructions:\n${config.instructions}`
+        : "";
+    const toolPreamble = hasTools
+        ? "\n\nWhen you decide to use a tool, ALWAYS say a brief natural phrase BEFORE the tool call " +
+            '(e.g. "Let me look that up" or "One moment while I check"). ' +
+            "This fills silence while the tool executes. Keep preambles to one short sentence."
+        : "";
+    const today = new Date().toLocaleDateString("en-US", {
+        weekday: "long",
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+    });
+    return (DEFAULT_INSTRUCTIONS +
+        `\n\nToday's date is ${today}.` +
+        agentInstructions +
+        toolPreamble +
+        (opts?.voice ? VOICE_RULES : ""));
+}
+//# sourceMappingURL=system_prompt.js.map

package/dist/sdk/system_prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system_prompt.js","sourceRoot":"","sources":["../../sdk/system_prompt.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAG/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,GACf,yEAAyE;IACzE,mFAAmF;IACnF,wEAAwE;IACxE,kEAAkE;IAClE,0CAA0C;IAC1C,0EAA0E;IAC1E,+EAA+E;IAC/E,4DAA4D;IAC5D,yFAAyF;IACzF,iDAAiD,CAAC;AAEpD,MAAM,UAAU,iBAAiB,CAC/B,MAAmB,EACnB,IAA4C;IAE5C,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAC1B,MAAM,iBAAiB,GAAG,MAAM,CAAC,YAAY;QAC3C,CAAC,CAAC,qCAAqC,MAAM,CAAC,YAAY,EAAE;QAC5D,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,YAAY,GAAG,QAAQ;QAC3B,CAAC,CAAC,4FAA4F;YAC5F,8DAA8D;YAC9D,mFAAmF;QACrF,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,kBAAkB,CAAC,OAAO,EAAE;QACnD,OAAO,EAAE,MAAM;QACf,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,MAAM;QACb,GAAG,EAAE,SAAS;KACf,CAAC,CAAC;IAEH,OAAO,CACL,oBAAoB;QACpB,uBAAuB,KAAK,GAAG;QAC/B,iBAAiB;QACjB,YAAY;QACZ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CACjC,CAAC;AACJ,CAAC"}