@alexkroman1/aai 1.4.5 → 1.5.0

package/host/s2s.ts

@@ -4,7 +4,6 @@
  */
 
 import type { JSONSchema7 } from "json-schema";
-import { createNanoEvents, type Emitter, type Unsubscribe } from "nanoevents";
 import WsWebSocket from "ws";
 import { z } from "zod";
 import { WS_OPEN } from "../sdk/constants.ts";
@@ -94,71 +93,64 @@ type DispatchContext = {
 };
 
 function dispatchS2sMessage(
-  emitter: Emitter<S2sEvents>,
+  callbacks: S2sCallbacks,
   msg: S2sServerMessage,
   state: DispatchState,
-  dispatchCtx: DispatchContext,
+  ctx: DispatchContext,
 ): void {
   switch (msg.type) {
     case "session.ready":
-      emitter.emit("ready", { sessionId: msg.session_id });
+      callbacks.onSessionReady(msg.session_id);
       break;
     case "session.updated":
       break;
     case "input.speech.started":
       if (!state.speechActive) {
         state.speechActive = true;
-        emitter.emit("event", { type: "speech_started" });
+        callbacks.onSpeechStarted();
       }
       break;
     case "input.speech.stopped":
       if (state.speechActive) {
         state.speechActive = false;
-        emitter.emit("event", { type: "speech_stopped" });
+        callbacks.onSpeechStopped();
       }
       break;
     case "transcript.user":
-      emitter.emit("event", { type: "user_transcript", text: msg.text });
+      callbacks.onUserTranscript(msg.text);
       break;
     case "reply.started":
-      emitter.emit("replyStarted", { replyId: msg.reply_id });
+      callbacks.onReplyStarted(msg.reply_id);
       break;
     case "transcript.agent":
-      emitter.emit("event", {
-        type: "agent_transcript",
-        text: msg.text,
-        _interrupted: msg.interrupted,
-      });
+      callbacks.onAgentTranscript(msg.text, msg.interrupted);
       break;
     case "tool.call":
-      emitter.emit("event", {
-        type: "tool_call",
-        toolCallId: msg.call_id,
-        toolName: msg.name,
-        args: msg.args,
-      });
+      callbacks.onToolCall(msg.call_id, msg.name, msg.args);
       break;
     case "reply.done":
       // Log every raw reply.done arrival from the S2S service — one line per
       // event, before any client-facing dedup — so we can cross-check which
       // stalled sessions actually received reply.done for their turn.
-      dispatchCtx.log.info("S2S << reply.done", {
-        ...(dispatchCtx.sid !== undefined ? { sid: dispatchCtx.sid } : {}),
+      ctx.log.info("S2S << reply.done", {
+        ...(ctx.sid !== undefined ? { sid: ctx.sid } : {}),
         status: msg.status ?? "completed",
       });
       if (msg.status === "interrupted") {
-        emitter.emit("event", { type: "cancelled" });
+        callbacks.onCancelled();
       } else {
-        emitter.emit("event", { type: "reply_done" });
+        callbacks.onReplyDone();
       }
       break;
     case "session.error":
-      if (msg.code === "session_not_found" || msg.code === "session_forbidden")
-        emitter.emit("sessionExpired");
-      else emitter.emit("error", new Error(msg.message));
+      if (msg.code === "session_not_found" || msg.code === "session_forbidden") {
+        callbacks.onSessionExpired();
+      } else {
+        callbacks.onError(new Error(msg.message));
+      }
       break;
     case "error":
-      emitter.emit("error", new Error(msg.message));
+      callbacks.onError(new Error(msg.message));
       break;
     default:
       break;
@@ -178,18 +170,24 @@ export type S2sToolSchema = {
   parameters: JSONSchema7;
 };
 
-export type S2sEvents = {
-  ready: (detail: { sessionId: string }) => void;
-  replyStarted: (detail: { replyId: string }) => void;
-  sessionExpired: () => void;
-  event: (event: S2sEvent) => void;
-  audio: (detail: { audio: Uint8Array }) => void;
-  error: (err: Error) => void;
-  close: (code: number, reason: string) => void;
+/** Callbacks fired into the owning session at construction time. */
+export type S2sCallbacks = {
+  onSessionReady(sessionId: string): void;
+  onReplyStarted(replyId: string): void;
+  onReplyDone(): void;
+  onCancelled(): void;
+  onAudio(bytes: Uint8Array): void;
+  onUserTranscript(text: string): void;
+  onAgentTranscript(text: string, interrupted: boolean): void;
+  onToolCall(callId: string, name: string, args: Record<string, unknown>): void;
+  onSpeechStarted(): void;
+  onSpeechStopped(): void;
+  onSessionExpired(): void;
+  onError(err: Error): void;
+  onClose(code: number, reason: string): void;
 };
 
 export type S2sHandle = {
-  on<K extends keyof S2sEvents>(event: K, cb: S2sEvents[K]): Unsubscribe;
   sendAudio(audio: Uint8Array): void;
   /**
    * Send a pre-encoded audio wire frame. For perf-critical callers (load tests)
@@ -206,6 +204,7 @@ export type ConnectS2sOptions = {
   apiKey: string;
   config: S2SConfig;
   createWebSocket: CreateS2sWebSocket;
+  callbacks: S2sCallbacks;
   logger?: Logger;
   /**
    * Session id attached to diagnostic log lines (e.g. raw `reply.done`
@@ -216,7 +215,7 @@ export type ConnectS2sOptions = {
 };
 
 export function connectS2s(opts: ConnectS2sOptions): Promise<S2sHandle> {
-  const { apiKey, config, createWebSocket, logger: log = consoleLogger, sid } = opts;
+  const { apiKey, config, createWebSocket, callbacks, logger: log = consoleLogger, sid } = opts;
 
   return new Promise((resolve, reject) => {
     log.info("S2S connecting", { url: config.wssUrl });
@@ -225,7 +224,6 @@ export function connectS2s(opts: ConnectS2sOptions): Promise<S2sHandle> {
       headers: { Authorization: `Bearer ${apiKey}` },
     });
 
-    const emitter = createNanoEvents<S2sEvents>();
     const dispatchState: DispatchState = { speechActive: false };
     const dispatchCtx: DispatchContext = sid !== undefined ? { log, sid } : { log };
     let opened = false;
@@ -247,8 +245,6 @@ export function connectS2s(opts: ConnectS2sOptions): Promise<S2sHandle> {
     }
 
     const handle: S2sHandle = {
-      on: emitter.on.bind(emitter),
-
       sendAudio(audio: Uint8Array): void {
         if (ws.readyState !== WS_OPEN) {
           log.debug("S2S sendAudio dropped: socket not open");
@@ -263,9 +259,8 @@ export function connectS2s(opts: ConnectS2sOptions): Promise<S2sHandle> {
       },
 
       sendToolResult(callId: string, result: string): void {
-        const msg = { type: "tool.result", call_id: callId, result };
         log.info("S2S >> tool.result", { call_id: callId, resultLength: result.length });
-        send(msg);
+        send({ type: "tool.result", call_id: callId, result });
       },
 
       updateSession(sessionConfig: S2sSessionConfig): void {
@@ -299,8 +294,7 @@ export function connectS2s(opts: ConnectS2sOptions): Promise<S2sHandle> {
 
     function handleAudioFastPath(obj: { type?: unknown; data?: unknown }): boolean {
       if (obj.type === "reply.audio" && typeof obj.data === "string") {
-        const audioBytes = base64ToUint8(obj.data);
-        emitter.emit("audio", { audio: audioBytes });
+        callbacks.onAudio(base64ToUint8(obj.data));
         return true;
       }
       return false;
@@ -309,13 +303,13 @@ export function connectS2s(opts: ConnectS2sOptions): Promise<S2sHandle> {
     function logIncoming(obj: { type?: unknown }): void {
       // reply.audio and input.audio are ~95% of traffic — skip logging.
       if (obj.type === "reply.audio" || obj.type === "input.audio") return;
-      // reply.done gets a richer log (sid + status) inside dispatchS2sMessage;
+      // reply.done gets a richer log (sid + status) inside dispatch;
       // skip the generic line here to avoid a duplicate.
       if (obj.type === "reply.done") return;
       log.info(`S2S << ${obj.type}`);
     }
 
-    function handleS2sMessage(ev: { data: unknown }): void {
+    ws.addEventListener("message", (ev) => {
       const raw = tryParseJson(ev.data);
       if (raw === undefined) return;
 
@@ -334,10 +328,8 @@ export function connectS2s(opts: ConnectS2sOptions): Promise<S2sHandle> {
         );
         return;
       }
-      dispatchS2sMessage(emitter, parsed, dispatchState, dispatchCtx);
-    }
-
-    ws.addEventListener("message", handleS2sMessage);
+      dispatchS2sMessage(callbacks, parsed, dispatchState, dispatchCtx);
+    });
 
     ws.addEventListener("close", (ev) => {
       const code = ev.code ?? 0;
@@ -346,7 +338,7 @@ export function connectS2s(opts: ConnectS2sOptions): Promise<S2sHandle> {
       if (!opened) {
         reject(new Error(`WebSocket closed before open (code: ${code})`));
       }
-      emitter.emit("close", code, reason);
+      callbacks.onClose(code, reason);
     });
 
     ws.addEventListener("error", (ev) => {
@@ -356,7 +348,7 @@ export function connectS2s(opts: ConnectS2sOptions): Promise<S2sHandle> {
       if (!opened) {
         reject(errObj);
       } else {
-        emitter.emit("error", errObj);
+        callbacks.onError(errObj);
       }
     });
   });

package/host/session-core.test.ts

@@ -0,0 +1,257 @@
+import { describe, expect, test, vi } from "vitest";
+import type { ClientEvent, ClientSink } from "../sdk/protocol.ts";
+import { DEFAULT_SYSTEM_PROMPT } from "../sdk/types.ts";
+import { flush } from "./_test-utils.ts";
+import type { SessionCore, SessionCoreOptions } from "./session-core.ts";
+import { createSessionCore } from "./session-core.ts";
+import type { Transport } from "./transports/types.ts";
+
+function makeSink(): {
+  events: ClientEvent[];
+  audioChunks: Uint8Array[];
+  audioDoneCount: number;
+  sink: ClientSink;
+} {
+  const events: ClientEvent[] = [];
+  const audioChunks: Uint8Array[] = [];
+  let audioDoneCount = 0;
+  return {
+    events,
+    audioChunks,
+    get audioDoneCount() {
+      return audioDoneCount;
+    },
+    sink: {
+      get open() {
+        return true;
+      },
+      event: (e) => {
+        events.push(e);
+      },
+      playAudioChunk: (chunk) => {
+        audioChunks.push(chunk);
+      },
+      playAudioDone: () => {
+        audioDoneCount++;
+      },
+    } satisfies ClientSink,
+  };
+}
+
+function makeTransport(): Transport & { starts: number; stops: number } {
+  let starts = 0,
+    stops = 0;
+  return {
+    start: async () => {
+      starts++;
+    },
+    stop: async () => {
+      stops++;
+    },
+    sendUserAudio: vi.fn(),
+    sendToolResult: vi.fn(),
+    cancelReply: vi.fn(),
+    get starts() {
+      return starts;
+    },
+    get stops() {
+      return stops;
+    },
+  };
+}
+
+function makeCore(overrides: Partial<SessionCoreOptions> = {}): {
+  core: SessionCore;
+  sink: ReturnType<typeof makeSink>;
+  transport: ReturnType<typeof makeTransport>;
+} {
+  const sink = makeSink();
+  const transport = makeTransport();
+  const core = createSessionCore({
+    id: "s-test",
+    agent: "test-agent",
+    client: sink.sink,
+    agentConfig: { name: "test", systemPrompt: DEFAULT_SYSTEM_PROMPT, greeting: "" },
+    executeTool: vi.fn(async () => "ok"),
+    transport,
+    ...overrides,
+  });
+  return { core, sink, transport };
+}
+
+describe("createSessionCore — lifecycle", () => {
+  test("start/stop calls transport", async () => {
+    const { core, transport } = makeCore();
+    await core.start();
+    expect(transport.starts).toBe(1);
+    await core.stop();
+    expect(transport.stops).toBe(1);
+  });
+  test("stop is idempotent", async () => {
+    const { core, transport } = makeCore();
+    await core.start();
+    await core.stop();
+    await core.stop();
+    expect(transport.stops).toBe(1);
+  });
+  test("post-stop onAudio does not reschedule the idle timer", async () => {
+    vi.useFakeTimers();
+    try {
+      const { core, sink } = makeCore({
+        agentConfig: {
+          name: "test",
+          systemPrompt: DEFAULT_SYSTEM_PROMPT,
+          greeting: "",
+          idleTimeoutMs: 1000,
+        } as unknown as SessionCoreOptions["agentConfig"],
+      });
+      await core.start();
+      await core.stop();
+      core.onAudio(new Uint8Array([1]));
+      vi.advanceTimersByTime(5000);
+      expect(sink.events.some((e) => e.type === "idle_timeout")).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe("createSessionCore — client inbound", () => {
+  test("onAudio forwards to transport", async () => {
+    const { core, transport } = makeCore();
+    await core.start();
+    const audio = new Uint8Array([1, 2, 3]);
+    core.onAudio(audio);
+    expect(transport.sendUserAudio).toHaveBeenCalledWith(audio);
+  });
+  test("onCancel cancels the reply and emits cancelled", async () => {
+    const { core, transport, sink } = makeCore();
+    await core.start();
+    core.onCancel();
+    expect(transport.cancelReply).toHaveBeenCalledOnce();
+    expect(sink.events.some((e) => e.type === "cancelled")).toBe(true);
+  });
+  test("onReset emits reset", async () => {
+    const { core, sink } = makeCore();
+    await core.start();
+    core.onReset();
+    expect(sink.events.some((e) => e.type === "reset")).toBe(true);
+  });
+});
+
+describe("createSessionCore — transport inbound (basic)", () => {
+  test("onAudioChunk forwards to sink", async () => {
+    const { core, sink } = makeCore();
+    await core.start();
+    const pcm = new Uint8Array([9, 8, 7]);
+    core.onAudioChunk(pcm);
+    expect(sink.audioChunks).toContain(pcm);
+  });
+  test("onUserTranscript pushes to history and emits", async () => {
+    const { core, sink } = makeCore();
+    await core.start();
+    core.onUserTranscript("hello");
+    expect(sink.events.some((e) => e.type === "user_transcript")).toBe(true);
+  });
+});
+
+describe("createSessionCore — reply dedup", () => {
+  test("first reply_done emits reply_done + audio_done", async () => {
+    const { core, sink } = makeCore();
+    await core.start();
+    core.onReplyStarted("r1");
+    core.onReplyDone();
+    expect(sink.events.some((e) => e.type === "reply_done")).toBe(true);
+    expect(sink.audioDoneCount).toBeGreaterThanOrEqual(1);
+  });
+  test("duplicate reply_done is dropped", async () => {
+    const { core, sink } = makeCore();
+    await core.start();
+    core.onReplyStarted("r1");
+    core.onReplyDone();
+    core.onReplyDone();
+    const dones = sink.events.filter((e) => e.type === "reply_done");
+    expect(dones).toHaveLength(1);
+  });
+  test("onCancelled clears currentReplyId so subsequent replyDone is dropped", async () => {
+    const { core, sink } = makeCore();
+    await core.start();
+    core.onReplyStarted("r1");
+    core.onCancelled();
+    core.onReplyDone();
+    expect(sink.events.filter((e) => e.type === "reply_done")).toHaveLength(0);
+  });
+});
+
+describe("createSessionCore — tool call pending results", () => {
+  test("tool_call executes, tool_call_done fires, reply_done forwards results to transport", async () => {
+    const executeTool = vi.fn(async () => "tool-output");
+    const { core, sink, transport } = makeCore({ executeTool });
+    await core.start();
+    core.onReplyStarted("r1");
+    core.onToolCall("cid", "my_tool", {});
+    // Let the async tool IIFE settle and push to pendingTools
+    await flush();
+    core.onReplyDone();
+    // Poll until tool results are forwarded and toolCallDone fires
+    await vi.waitFor(() =>
+      expect(transport.sendToolResult).toHaveBeenCalledWith("cid", "tool-output"),
+    );
+    expect(sink.events.some((e) => e.type === "tool_call_done")).toBe(true);
+  });
+});
+
+describe("createSessionCore — idle timeout", () => {
+  test("emits idle_timeout after agentConfig.idleTimeoutMs of no audio", async () => {
+    vi.useFakeTimers();
+    try {
+      const { core, sink } = makeCore({
+        agentConfig: {
+          name: "t",
+          systemPrompt: DEFAULT_SYSTEM_PROMPT,
+          greeting: "",
+          idleTimeoutMs: 1000,
+        } as unknown as SessionCoreOptions["agentConfig"],
+      });
+      await core.start();
+      expect(sink.events.filter((e) => e.type === "idle_timeout")).toHaveLength(0);
+      vi.advanceTimersByTime(1001);
+      expect(sink.events.filter((e) => e.type === "idle_timeout")).toHaveLength(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+  test("onAudio resets the idle timer", async () => {
+    vi.useFakeTimers();
+    try {
+      const { core, sink } = makeCore({
+        agentConfig: {
+          name: "t",
+          systemPrompt: DEFAULT_SYSTEM_PROMPT,
+          greeting: "",
+          idleTimeoutMs: 1000,
+        } as unknown as SessionCoreOptions["agentConfig"],
+      });
+      await core.start();
+      vi.advanceTimersByTime(500);
+      core.onAudio(new Uint8Array([1]));
+      vi.advanceTimersByTime(800);
+      expect(sink.events.filter((e) => e.type === "idle_timeout")).toHaveLength(0);
+      vi.advanceTimersByTime(300);
+      expect(sink.events.filter((e) => e.type === "idle_timeout")).toHaveLength(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe("createSessionCore — history", () => {
+  test("onHistory appends and onUserTranscript pushes user messages", async () => {
+    const { core } = makeCore();
+    await core.start();
+    core.onHistory([{ role: "user", content: "prior" }]);
+    core.onUserTranscript("now");
+    // No direct introspection — but onReset clears history and replay should see no effect on subsequent behavior.
+    core.onReset();
+  });
+});