@guava-ai/guava-sdk 0.18.0 → 0.20.0

package/src/agent.ts

@@ -1,35 +1,33 @@
 import WebSocket from "ws";
 import { Call, Client } from "./index.ts";
 import { getDefaultLogger, type Logger } from "./logging.ts";
-import { getBaseUrl } from "./utils.ts";
+import { getBaseUrl, fetchOrThrow } from "./utils.ts";
 import { runWebrtcHelper } from "./webrtc-helper.ts";
-import * as z from "zod";
 import {
-  ListenInboundCommand,
-  InboundTunnelCommand,
   AnswerQuestionCommand,
   ChoiceResultCommand,
   RegisteredHooksCommand,
-  AcceptInboundCallCommand,
-  RejectInboundCallCommand,
-  StartOutboundCallCommand,
   ActionSuggestionCommand,
+  type Command,
 } from "./commands.ts";
 import {
   type GuavaEvent,
   type CallerSpeechEvent,
   type AgentSpeechEvent,
-  InboundTunnelEvent,
-  ErrorEvent,
-  SessionStartedEvent,
-  decodeEvent,
+  type BotSessionEnded,
+  type DTMFPressedEvent,
+  decodeEventDict,
 } from "./events.ts";
 import { telemetryClient } from "./telemetry.ts";
+import { GuavaSocket, GuavaSocketClosedError } from "./socket/client.ts";
+import * as ListenInbound from "./socket/listen-inbound.ts";
+import type { CallInfo } from "./socket/call-info.ts";
+import { TestSession } from "./testing/session.ts";
+import { SessionStarted } from "./testing/protocol.ts";
+import { runChat } from "./testing/chat.ts";
+import { _generate } from "./helpers/llm.ts";
 
-export interface CallInfo {
-  caller_number: string | null;
-  agent_number: string | null;
-}
+export type { CallInfo } from "./socket/call-info.ts";
 
 export type IncomingCallAction = { action: "accept" } | { action: "decline" };
 
@@ -38,13 +36,6 @@ export interface SuggestedAction {
   description?: string;
 }
 
-/**
- * @description convenience function for stringifying data according to a schema
- */
-function stringifyZod<Schema extends z.ZodType>(schema: Schema, data: z.input<Schema>): string {
-  return JSON.stringify(schema.parse(data));
-}
-
 export type InboundConnection = { agent_number: string } | { webrtc_code: string };
 
 @telemetryClient.trackClass()
@@ -75,7 +66,8 @@ export class Agent {
   ) => Promise<SuggestedAction | undefined>;
   private _onActionGeneric?: (call: Call, actionKey: string) => Promise<void>;
   private _onActionHandlers: Record<string, (call: Call) => Promise<void>> = {};
-  private _onSessionEnd?: (call: Call) => Promise<void>;
+  private _onSessionEnd?: (call: Call, event: BotSessionEnded) => Promise<void>;
+  private _onDtmf?: (call: Call, event: DTMFPressedEvent) => Promise<void>;
 
   constructor(args?: { name?: string; organization?: string; purpose?: string }) {
     this._name = args?.name;
@@ -149,10 +141,60 @@ export class Agent {
     }
   }
 
-  onSessionEnd(callback: (call: Call) => Promise<void>): void {
+  onSessionEnd(callback: (call: Call, event: BotSessionEnded) => Promise<void>): void {
     this._onSessionEnd = callback;
   }
 
+  onDtmf(callback: (call: Call, event: DTMFPressedEvent) => Promise<void>): void {
+    this._onDtmf = callback;
+  }
+
+  get handlers() {
+    return {
+      onCallReceived: (callInfo: CallInfo) => this._onCallReceived(callInfo),
+      onCallStart: (call: Call) => {
+        if (!this._onCallStart) throw new Error("No onCallStart handler registered.");
+        return this._onCallStart(call);
+      },
+      onCallerSpeech: (call: Call, event: CallerSpeechEvent) => {
+        if (!this._onCallerSpeech) throw new Error("No onCallerSpeech handler registered.");
+        return this._onCallerSpeech(call, event);
+      },
+      onAgentSpeech: (call: Call, event: AgentSpeechEvent) => {
+        if (!this._onAgentSpeech) throw new Error("No onAgentSpeech handler registered.");
+        return this._onAgentSpeech(call, event);
+      },
+      onQuestion: (call: Call, question: string) => {
+        if (!this._onQuestion) throw new Error("No onQuestion handler registered.");
+        return this._onQuestion(call, question);
+      },
+      onTaskComplete: (taskId: string, call: Call) => {
+        if (this._onTaskCompleteGeneric) return this._onTaskCompleteGeneric(call, taskId);
+        if (taskId in this._onTaskCompleteHandlers)
+          return this._onTaskCompleteHandlers[taskId](call);
+        throw new Error(`No onTaskComplete handler registered for task '${taskId}'.`);
+      },
+      onSearchQuery: (fieldKey: string, call: Call, query: string) => {
+        if (!(fieldKey in this._searchQueryHandlers))
+          throw new Error(`No onSearchQuery handler registered for field '${fieldKey}'.`);
+        return this._searchQueryHandlers[fieldKey](call, query);
+      },
+      onActionRequest: (call: Call, intentSummary: string) => {
+        if (!this._onActionRequested) throw new Error("No onActionRequest handler registered.");
+        return this._onActionRequested(call, intentSummary);
+      },
+      onAction: (actionKey: string, call: Call) => {
+        if (this._onActionGeneric) return this._onActionGeneric(call, actionKey);
+        if (actionKey in this._onActionHandlers) return this._onActionHandlers[actionKey](call);
+        throw new Error(`No onAction handler registered for action '${actionKey}'.`);
+      },
+      onSessionEnd: (call: Call, event: BotSessionEnded) => {
+        if (!this._onSessionEnd) throw new Error("No onSessionEnd handler registered.");
+        return this._onSessionEnd(call, event);
+      },
+    };
+  }
+
   onReachPerson(callback: (call: Call, availability: string) => Promise<void>): void {
     this.onTaskComplete("reach_person", async (call) => {
       const availability = (await call.getField("contact_availability")) as string;
@@ -160,13 +202,11 @@ export class Agent {
     });
   }
 
-  listenPhone(phoneNumber: string): InboundListener {
-    return this._listenInbound({
-      agent_number: phoneNumber,
-    });
+  async listenPhone(phoneNumber: string): Promise<void> {
+    return this._listenInbound({ agent_number: phoneNumber });
   }
 
-  async listenWebrtc(webrtcCode?: string): Promise<InboundListener> {
+  async listenWebrtc(webrtcCode?: string): Promise<void> {
     if (!webrtcCode) {
       this._logger.info("No WebRTC code provided. Creating a temporary one.");
       webrtcCode = await this._client.createWebrtcAgent(3600);
@@ -176,11 +216,13 @@ export class Agent {
 
   async callLocal(): Promise<void> {
     const webrtcCode = await this._client.createWebrtcAgent(300);
-    this._listenInbound({ webrtc_code: webrtcCode });
+    this._listenInbound({ webrtc_code: webrtcCode }).catch((err) => {
+      this._logger.error("Listen loop error: %s", err);
+    });
     await runWebrtcHelper(webrtcCode, getBaseUrl());
   }
 
-  private async _dispatchEvent(call: Call, event: GuavaEvent) {
+  private async _dispatchEvent(call: Call, event: GuavaEvent, testSession?: TestSession) {
     if (event.event_type === "caller-speech") {
       if (this._onCallerSpeech !== undefined) {
         await this._onCallerSpeech(call, event);
@@ -189,17 +231,6 @@ export class Agent {
       if (this._onAgentSpeech !== undefined) {
         await this._onAgentSpeech(call, event);
       }
-    } else if (event.event_type === "inbound-call") {
-      this._logger.info(`Received inbound call from ${event.caller_number ?? "unknown"}`);
-      const action = await this._onCallReceived({
-        caller_number: event.caller_number,
-        agent_number: event.agent_number,
-      });
-      if (action.action === "accept") {
-        call.sendCommand(AcceptInboundCallCommand, { command_type: "accept-inbound" });
-      } else {
-        call.sendCommand(RejectInboundCallCommand, { command_type: "reject-inbound" });
-      }
     } else if (event.event_type === "task-done") {
       this._logger.info(`Task ${event.task_id} completed.`);
       if (this._onTaskCompleteGeneric !== undefined) {
@@ -219,7 +250,7 @@ export class Agent {
           this._logger.error(`Error occurred while answering question: ${err}`);
           answer = "An error occurred and the question could not be answered.";
         }
-        call.sendCommand(AnswerQuestionCommand, {
+        await call.sendCommand(AnswerQuestionCommand, {
           command_type: "answer-question",
           question_id: event.question_id,
           answer,
@@ -228,14 +259,13 @@ export class Agent {
         this._logger.warn(
           `Received question but no onQuestion handler is registered: ${event.question}`,
         );
-        call.sendCommand(AnswerQuestionCommand, {
+        await call.sendCommand(AnswerQuestionCommand, {
           command_type: "answer-question",
           question_id: event.question_id,
           answer: "I don't have an answer to that question.",
         });
       }
     } else if (event.event_type === "action-item-done") {
-      this._logger.info(`Action item '${event.key}' completed.`);
       call._fieldValues[event.key] = event.payload;
     } else if (event.event_type === "choice-query") {
       this._logger.info(`Received search query for field '${event.field_key}': ${event.query}`);
@@ -246,7 +276,7 @@ export class Agent {
         );
       } else {
         const [matchedChoices, otherChoices] = await handler(call, event.query);
-        call.sendCommand(ChoiceResultCommand, {
+        await call.sendCommand(ChoiceResultCommand, {
           command_type: "choice-query-result",
           field_key: event.field_key,
           query_id: event.query_id,
@@ -260,7 +290,7 @@ export class Agent {
       if (this._onActionRequested !== undefined) {
         suggestion = await this._onActionRequested(call, event.intent_summary);
       }
-      call.sendCommand(ActionSuggestionCommand, {
+      await call.sendCommand(ActionSuggestionCommand, {
         command_type: "action-suggestion",
         intent_id: event.intent_id,
         action_key: suggestion?.key ?? null,
@@ -268,6 +298,9 @@ export class Agent {
       });
     } else if (event.event_type === "execute-action") {
       this._logger.info(`Executing action '${event.action_key}'`);
+      if (testSession) {
+        testSession.executedActions.push(event.action_key);
+      }
       let onActionFunc: (() => Promise<void>) | undefined;
       if (this._onActionGeneric !== undefined) {
         onActionFunc = () => this._onActionGeneric!(call, event.action_key);
@@ -280,9 +313,14 @@ export class Agent {
         this._logger.warn(`No handler registered for action '${event.action_key}'`);
       }
     } else if (event.event_type === "bot-session-ended") {
-      this._logger.info("Session ended.");
-      if (this._onSessionEnd !== undefined) {
-        await this._onSessionEnd(call);
+      this._logger.info(`Session ended: ${event.termination_reason}`);
+      if (testSession) {
+        testSession.terminationReason = event.termination_reason;
+      }
+      await this._onSessionEnd?.(call, event);
+    } else if (event.event_type === "dtmf") {
+      if (this._onDtmf !== undefined) {
+        await this._onDtmf(call, event);
       }
     } else if (event.event_type === "error") {
       this._logger.error(`The Guava agent reported an error: ${event.content}`);
@@ -291,14 +329,14 @@ export class Agent {
     }
   }
 
-  async _startCall(variables: Record<string, any> = {}): Promise<Call> {
+  async _initCall(variables: Record<string, any> = {}): Promise<Call> {
     const call = new Call(variables);
-    call.setPersona({
+    await call.setPersona({
       agentName: this._name,
       agentPurpose: this._purpose,
       organizationName: this._organization,
     });
-    call.sendCommand(RegisteredHooksCommand, {
+    await call.sendCommand(RegisteredHooksCommand, {
       command_type: "registered-hooks",
       has_on_question: this._onQuestion !== undefined,
       has_on_intent: false,
@@ -310,142 +348,335 @@ export class Agent {
     return call;
   }
 
-  _listenInbound(conn: InboundConnection): InboundListener {
-    const calls: Record<string, Call> = {};
-
-    // return a way to *stop* listening
-    const url = new URL("v1/listen-inbound", this._client.getWebsocketBase());
-    const ws = new WebSocket(url, {
-      headers: this._client.headers(),
+  async _attachToCall(
+    callId: string,
+    initialVariables: Record<string, any> = {},
+    testSession?: TestSession,
+  ): Promise<void> {
+    const call = await this._initCall(initialVariables);
+
+    const url = new URL(`v2/connect-call/${callId}`, this._client.getWebsocketBase());
+    await using socket = await new GuavaSocket<Command, GuavaEvent | null>(
+      `call-connection-${callId}`,
+      url.toString(),
+      this._client,
+      (cmd) => cmd as unknown as Record<string, unknown>,
+      (payload) => decodeEventDict(payload),
+      18000,
+    ).connect();
+
+    await call.setDrain(async (commands) => {
+      for (const command of commands.splice(0)) {
+        socket.send(command);
+      }
     });
-    let agent_number: string | undefined;
-    let webrtc_code: string | undefined;
+
+    try {
+      for await (const event of socket) {
+        if (event === null) continue;
+        await this._dispatchEvent(call, event, testSession);
+        if (
+          event.event_type === "bot-session-ended" ||
+          event.event_type === "outbound-call-failed"
+        ) {
+          break;
+        }
+      }
+    } catch (e) {
+      if (!(e instanceof GuavaSocketClosedError)) throw e;
+    }
+  }
+
+  async _listenInbound(conn: InboundConnection): Promise<void> {
+    const url = new URL("v2/listen-inbound", this._client.getWebsocketBase());
     if ("agent_number" in conn) {
-      agent_number = conn.agent_number;
+      url.searchParams.set("phone_number", conn.agent_number);
     } else {
-      webrtc_code = conn.webrtc_code;
+      url.searchParams.set("webrtc_code", conn.webrtc_code);
     }
 
-    this._logger.info(`Listening for calls to ${agent_number ?? webrtc_code}`);
+    await using socket = await new GuavaSocket<
+      ListenInbound.ClientMessage,
+      ListenInbound.ServerMessage
+    >(
+      "listen-inbound",
+      url.toString(),
+      this._client,
+      (msg) => msg as unknown as Record<string, unknown>,
+      ListenInbound.decodeServerMessage,
+    ).connect();
+
+    try {
+      for await (const msg of socket) {
+        switch (msg.message_type) {
+          case "listen-started":
+            if ("agent_number" in conn) {
+              this._logger.info(
+                "Listening on %s (%d other listeners).",
+                conn.agent_number,
+                msg.other_listeners,
+              );
+            } else {
+              this._logger.info(
+                "Listening on WebRTC code %s (%d other listeners).",
+                conn.webrtc_code,
+                msg.other_listeners,
+              );
+              const debugUrl = new URL(
+                `debug-webrtc?webrtc_code=${conn.webrtc_code}`,
+                this._client.getHttpBase(),
+              );
+              this._logger.info("Call your agent at: %s", debugUrl);
+            }
+            break;
+          case "incoming-call":
+            socket.send({ message_type: "claim-call", call_id: msg.call_id });
+            break;
+          case "assign-call": {
+            const { call_id, call_info } = msg;
+            this._logger.info("Received call (session ID: %s)", call_id);
+            this._handleAssignedCall(call_id, call_info, socket).catch((err) => {
+              this._logger.error("Error handling assigned call %s: %s", call_id, err);
+            });
+            break;
+          }
+        }
+      }
+    } catch (e) {
+      if (!(e instanceof GuavaSocketClosedError)) throw e;
+    }
+  }
 
-    if (webrtc_code) {
-      const debugurl = new URL(
-        `debug-webrtc?webrtc_code=${webrtc_code}`,
-        this._client.getHttpBase(),
-      );
-      this._logger.info(`Call your agent at: ${debugurl}`);
+  private async _handleAssignedCall(
+    callId: string,
+    callInfo: CallInfo,
+    socket: GuavaSocket<ListenInbound.ClientMessage, ListenInbound.ServerMessage>,
+    initialVariables: Record<string, any> = {},
+  ): Promise<void> {
+    const action = await this._onCallReceived(callInfo);
+    if (action.action === "decline") {
+      this._logger.info("Declining call %s.", callId);
+      socket.send({ message_type: "decline-call", call_id: callId });
+    } else {
+      this._logger.info("Accepting call %s.", callId);
+      socket.send({ message_type: "answer-call", call_id: callId });
+      await this._attachToCall(callId, initialVariables);
     }
+  }
 
-    ws.addEventListener("open", (_ev) => {
-      ws.send(
-        stringifyZod(ListenInboundCommand, {
-          command_type: "listen-inbound",
-          agent_number: agent_number,
-          webrtc_code: webrtc_code,
-        }),
-      );
+  /**
+   * @description use the Guava API to call out to a number
+   */
+  async callPhone(
+    fromNumber: string | undefined,
+    toNumber: string,
+    variables: Record<string, any> = {},
+  ): Promise<void> {
+    const url = new URL("v2/create-outbound", this._client.getHttpBase());
+    if (fromNumber) url.searchParams.set("from_number", fromNumber);
+    url.searchParams.set("to_number", toNumber);
+
+    const response = await fetchOrThrow(url, {
+      method: "POST",
+      headers: await this._client.headers(),
     });
+    const { call_id } = (await response.json()) as { call_id: string };
 
-    ws.addEventListener("close", (_ev) => {
-      ws.removeAllListeners();
+    this._logger.info("Outbound call created with session ID: %s", call_id);
+    await this._attachToCall(call_id, variables);
+  }
+
+  /**
+   * Run the agent against a live test session.
+   *
+   * Connects to the Guava test endpoint, starts the agent's call handling, and
+   * calls `callback` with a TestSession for driving the conversation
+   * programmatically. Returns the completed TestSession after the callback and
+   * call handler both finish.
+   *
+   * @example
+   * const session = await agent.test(async (session) => {
+   *   await session.waitForTurn();
+   *   session.say("Hi, I'd like to make a purchase.");
+   *   await session.waitForEnd();
+   * });
+   * assert(session.executedActions.includes("sales"));
+   */
+  async test(
+    callback: (session: TestSession) => Promise<void>,
+    variables: Record<string, any> = {},
+  ): Promise<TestSession> {
+    const url = new URL("v1/test-agent", this._client.getWebsocketBase());
+    const headers = await this._client.headers();
+    const ws = new WebSocket(url.toString(), { headers });
+
+    await new Promise<void>((resolve, reject) => {
+      ws.once("open", resolve);
+      ws.once("error", reject);
     });
 
-    ws.addEventListener("message", async (ev) => {
-      this._logger.debug("Received message: %s", ev.data.toString("utf8"));
-      const tunnel_event = InboundTunnelEvent.parse(JSON.parse(ev.data.toString("utf8")));
-      if (!(tunnel_event.call_id in calls)) {
-        this._logger.info(
-          `Received tunnel event for new call ID: ${tunnel_event.call_id}. Creating call object.`,
-        );
+    const rawFirst = await new Promise<string>((resolve, reject) => {
+      ws.once("message", (data) => resolve(data.toString()));
+      ws.once("error", reject);
+    });
 
-        const call = await this._startCall();
-        await call.setDrain(async (commands) => {
-          for (const command of commands.splice(0)) {
-            this._logger.debug(
-              `Sending command: ${JSON.stringify(command)} for call ID: ${tunnel_event.call_id}`,
-            );
-            ws.send(
-              stringifyZod(InboundTunnelCommand, {
-                call_id: tunnel_event.call_id,
-                command,
-              }),
-            );
-          }
-        });
-        calls[tunnel_event.call_id] = call;
-      }
+    const sessionStarted = SessionStarted.parse(JSON.parse(rawFirst));
+    const testSession = new TestSession(ws, this._client);
 
-      this._dispatchEvent(calls[tunnel_event.call_id], tunnel_event.event);
+    const attachPromise = this._attachToCall(
+      sessionStarted.session_id,
+      variables,
+      testSession,
+    ).catch((err: unknown) => {
+      this._logger.error("Error in _attachToCall during test: %s", err);
     });
 
-    return new InboundListener(ws);
+    try {
+      await callback(testSession);
+    } finally {
+      ws.close();
+      await attachPromise;
+    }
+
+    return testSession;
   }
 
   /**
-   * @description use the Guava API to call out to a number
+   * Run an automated test conversation where an LLM plays the caller.
+   *
+   * Connects to the Guava test endpoint, starts the agent, then drives a
+   * back-and-forth conversation by repeatedly asking the Guava LLM to decide
+   * whether to speak or hang up based on the transcript so far.
+   *
+   * @param roleplayPrompt - Instructions for the simulated caller, e.g.
+   *   `"You are a frustrated customer trying to cancel your subscription."`
+   * @param variables - Optional initial call variables.
+   * @returns The completed TestSession. Call `session.evaluate()` to assert
+   *   pass/fail criteria, or `session.getTranscript()` to inspect the conversation.
+   *
+   * @example
+   * const session = await agent.testRoleplay(
+   *   "You are a caller trying to buy a new table.",
+   * );
+   * assert(session.executedActions.includes("sales"));
    */
-  async callPhone(
-    fromNumber: string | undefined,
-    toNumber: string,
+  async testRoleplay(
+    roleplayPrompt: string,
     variables: Record<string, any> = {},
-  ) {
-    const url = new URL("v1/create-outbound", this._client.getWebsocketBase());
-    const ws = new WebSocket(url, {
-      headers: this._client.headers(),
-    });
+  ): Promise<TestSession> {
+    const roleplaySchema = {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["speak", "hangup"] },
+        utterance: { type: "string" },
+      },
+      required: ["action"],
+      additionalProperties: false,
+    };
+
+    return this.test(async (session) => {
+      let snapshotLen = 0;
+      try {
+        while (true) {
+          await session.waitForTurn();
+
+          for (const event of session._events.slice(snapshotLen)) {
+            if (event.message_type === "bot-tts") {
+              this._logger.info("(Roleplay Session) [agent]: %s", event.transcript);
+            }
+          }
+          snapshotLen = session._events.length;
 
-    const call = await this._startCall(variables);
-    let socketInitialized = false;
-
-    ws.addEventListener("open", async (_ev) => {
-      ws.send(
-        stringifyZod(StartOutboundCallCommand, {
-          command_type: "start-outbound",
-          to_number: toNumber,
-          from_number: fromNumber,
-        }),
-      );
-
-      // set the callController drain function to send all commands
-      // through the now open websocket
-      call.setDrain(async (commands) => {
-        for (const command of commands.splice(0)) {
-          this._logger.debug(`Sending command ${JSON.stringify(command)}`);
-          ws.send(JSON.stringify(command));
-        }
-      });
-    });
+          const transcript = session.getTranscript();
+          const prompt = `${roleplayPrompt}
+
+You are roleplaying as a caller on a phone call. Decide what to do next based on the conversation so far.
+
+Conversation:
+${transcript || "(The agent has not spoken yet)"}
+
+Choose "speak" and provide your next utterance, or choose "hangup" if the conversation has naturally concluded.`;
 
-    ws.addEventListener("message", (ev) => {
-      if (socketInitialized) {
-        const session_started = z
-          .union([SessionStartedEvent, ErrorEvent])
-          .parse(JSON.parse(ev.data.toString("utf8")));
+          const raw = await _generate(this._client, prompt, roleplaySchema);
+          const action = JSON.parse(raw) as { action: string; utterance?: string };
 
-        if (session_started.event_type === "error") {
-          throw new Error(`Outbound call failed: ${session_started.content}`);
+          if (action.action === "hangup") {
+            this._logger.info("(Roleplay Session) [caller hangs up]");
+            break;
+          }
+
+          if (action.action === "speak" && action.utterance) {
+            this._logger.info("(Roleplay Session) [caller]: %s", action.utterance);
+            session.say(action.utterance);
+          }
+        }
+      } catch (err) {
+        if ((err as Error).message === "Test session WebSocket closed") {
+          this._logger.info("Roleplay session ended by server.");
         } else {
-          this._logger.info(`Started session with ID: ${session_started.session_id}`);
-          socketInitialized = true;
+          throw err;
         }
-      } else {
-        // handle the received event
-        const event = decodeEvent(ev.data);
-        if (event) {
-          this._dispatchEvent(call, event);
+      }
+
+      for (const event of session._events.slice(snapshotLen)) {
+        if (event.message_type === "bot-tts") {
+          this._logger.info("(Roleplay Session) [agent]: %s", event.transcript);
         }
       }
-    });
+    }, variables);
+  }
+
+  /**
+   * Start an interactive terminal chat session with the agent.
+   *
+   * Opens a TUI with a scrolling conversation panel and an input line.
+   * Agent responses appear in real time. Press Ctrl+C or let the agent
+   * end the session to exit.
+   *
+   * @param variables - Optional initial call variables.
+   *
+   * @example
+   * await agent.chat();
+   * // or: await agent.chat({ patient_name: "Benjamin Buttons" });
+   */
+  async chat(variables: Record<string, any> = {}): Promise<void> {
+    await this.test(async (session) => {
+      await runChat(session);
+    }, variables);
+  }
 
-    ws.addEventListener("close", (_ev) => {
-      // we are closing the socket, so don't trigger any other listeners
-      ws.removeAllListeners();
+  /**
+   * Return a shallow copy of this agent with independently overridable
+   * callbacks.
+   *
+   * Use in tests to register alternative handlers on the clone without
+   * affecting the original agent.
+   */
+  patch(): Agent {
+    const cloned = new Agent({
+      name: this._name,
+      organization: this._organization,
+      purpose: this._purpose,
     });
+    cloned._onCallReceived = this._onCallReceived;
+    cloned._onCallStart = this._onCallStart;
+    cloned._onCallerSpeech = this._onCallerSpeech;
+    cloned._onAgentSpeech = this._onAgentSpeech;
+    cloned._onQuestion = this._onQuestion;
+    cloned._onTaskCompleteGeneric = this._onTaskCompleteGeneric;
+    cloned._onTaskCompleteHandlers = { ...this._onTaskCompleteHandlers };
+    cloned._searchQueryHandlers = { ...this._searchQueryHandlers };
+    cloned._onActionRequested = this._onActionRequested;
+    cloned._onActionGeneric = this._onActionGeneric;
+    cloned._onActionHandlers = { ...this._onActionHandlers };
+    cloned._onSessionEnd = this._onSessionEnd;
+    cloned._onDtmf = this._onDtmf;
+    return cloned;
   }
 
   /* ===== Aliases to be removed at some point. ===== */
   /** @deprecated Use {@link listenPhone} instead. */
-  inboundPhone(phoneNumber: string): InboundListener {
+  async inboundPhone(phoneNumber: string): Promise<void> {
     return this.listenPhone(phoneNumber);
   }
 
@@ -458,14 +689,3 @@ export class Agent {
     return this.callPhone(fromNumber, toNumber, variables);
   }
 }
-
-class InboundListener {
-  private ws: WebSocket;
-  constructor(ws: WebSocket) {
-    this.ws = ws;
-  }
-
-  close() {
-    this.ws.close();
-  }
-}