@guava-ai/guava-sdk 0.18.0 → 0.20.0

package/dist/src/agent.js

@@ -66,6 +66,58 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -76,16 +128,15 @@ const index_ts_1 = require("./index.js");
 const logging_ts_1 = require("./logging.js");
 const utils_ts_1 = require("./utils.js");
 const webrtc_helper_ts_1 = require("./webrtc-helper.js");
-const z = __importStar(require("zod"));
 const commands_ts_1 = require("./commands.js");
 const events_ts_1 = require("./events.js");
 const telemetry_ts_1 = require("./telemetry.js");
-/**
- * @description convenience function for stringifying data according to a schema
- */
-function stringifyZod(schema, data) {
-    return JSON.stringify(schema.parse(data));
-}
+const client_ts_1 = require("./socket/client.js");
+const ListenInbound = __importStar(require("./socket/listen-inbound.js"));
+const session_ts_1 = require("./testing/session.js");
+const protocol_ts_1 = require("./testing/protocol.js");
+const chat_ts_1 = require("./testing/chat.js");
+const llm_ts_1 = require("./helpers/llm.js");
 let Agent = (() => {
     let _classDecorators = [telemetry_ts_1.telemetryClient.trackClass()];
     let _classDescriptor;
@@ -119,6 +170,7 @@ let Agent = (() => {
         _onActionGeneric;
         _onActionHandlers = {};
         _onSessionEnd;
+        _onDtmf;
         constructor(args) {
             this._name = args?.name;
             this._organization = args?.organization;
@@ -175,16 +227,71 @@ let Agent = (() => {
         onSessionEnd(callback) {
             this._onSessionEnd = callback;
         }
+        onDtmf(callback) {
+            this._onDtmf = callback;
+        }
+        get handlers() {
+            return {
+                onCallReceived: (callInfo) => this._onCallReceived(callInfo),
+                onCallStart: (call) => {
+                    if (!this._onCallStart)
+                        throw new Error("No onCallStart handler registered.");
+                    return this._onCallStart(call);
+                },
+                onCallerSpeech: (call, event) => {
+                    if (!this._onCallerSpeech)
+                        throw new Error("No onCallerSpeech handler registered.");
+                    return this._onCallerSpeech(call, event);
+                },
+                onAgentSpeech: (call, event) => {
+                    if (!this._onAgentSpeech)
+                        throw new Error("No onAgentSpeech handler registered.");
+                    return this._onAgentSpeech(call, event);
+                },
+                onQuestion: (call, question) => {
+                    if (!this._onQuestion)
+                        throw new Error("No onQuestion handler registered.");
+                    return this._onQuestion(call, question);
+                },
+                onTaskComplete: (taskId, 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, call, query) => {
+                    if (!(fieldKey in this._searchQueryHandlers))
+                        throw new Error(`No onSearchQuery handler registered for field '${fieldKey}'.`);
+                    return this._searchQueryHandlers[fieldKey](call, query);
+                },
+                onActionRequest: (call, intentSummary) => {
+                    if (!this._onActionRequested)
+                        throw new Error("No onActionRequest handler registered.");
+                    return this._onActionRequested(call, intentSummary);
+                },
+                onAction: (actionKey, 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, event) => {
+                    if (!this._onSessionEnd)
+                        throw new Error("No onSessionEnd handler registered.");
+                    return this._onSessionEnd(call, event);
+                },
+            };
+        }
         onReachPerson(callback) {
             this.onTaskComplete("reach_person", async (call) => {
                 const availability = (await call.getField("contact_availability"));
                 await callback(call, availability);
             });
         }
-        listenPhone(phoneNumber) {
-            return this._listenInbound({
-                agent_number: phoneNumber,
-            });
+        async listenPhone(phoneNumber) {
+            return this._listenInbound({ agent_number: phoneNumber });
         }
         async listenWebrtc(webrtcCode) {
             if (!webrtcCode) {
@@ -195,10 +302,12 @@ let Agent = (() => {
         }
         async callLocal() {
             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 (0, webrtc_helper_ts_1.runWebrtcHelper)(webrtcCode, (0, utils_ts_1.getBaseUrl)());
         }
-        async _dispatchEvent(call, event) {
+        async _dispatchEvent(call, event, testSession) {
             if (event.event_type === "caller-speech") {
                 if (this._onCallerSpeech !== undefined) {
                     await this._onCallerSpeech(call, event);
@@ -209,19 +318,6 @@ let Agent = (() => {
                     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(commands_ts_1.AcceptInboundCallCommand, { command_type: "accept-inbound" });
-                }
-                else {
-                    call.sendCommand(commands_ts_1.RejectInboundCallCommand, { command_type: "reject-inbound" });
-                }
-            }
             else if (event.event_type === "task-done") {
                 this._logger.info(`Task ${event.task_id} completed.`);
                 if (this._onTaskCompleteGeneric !== undefined) {
@@ -245,7 +341,7 @@ let Agent = (() => {
                         this._logger.error(`Error occurred while answering question: ${err}`);
                         answer = "An error occurred and the question could not be answered.";
                     }
-                    call.sendCommand(commands_ts_1.AnswerQuestionCommand, {
+                    await call.sendCommand(commands_ts_1.AnswerQuestionCommand, {
                         command_type: "answer-question",
                         question_id: event.question_id,
                         answer,
@@ -253,7 +349,7 @@ let Agent = (() => {
                 }
                 else {
                     this._logger.warn(`Received question but no onQuestion handler is registered: ${event.question}`);
-                    call.sendCommand(commands_ts_1.AnswerQuestionCommand, {
+                    await call.sendCommand(commands_ts_1.AnswerQuestionCommand, {
                         command_type: "answer-question",
                         question_id: event.question_id,
                         answer: "I don't have an answer to that question.",
@@ -261,7 +357,6 @@ let Agent = (() => {
                 }
             }
             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") {
@@ -272,7 +367,7 @@ let Agent = (() => {
                 }
                 else {
                     const [matchedChoices, otherChoices] = await handler(call, event.query);
-                    call.sendCommand(commands_ts_1.ChoiceResultCommand, {
+                    await call.sendCommand(commands_ts_1.ChoiceResultCommand, {
                         command_type: "choice-query-result",
                         field_key: event.field_key,
                         query_id: event.query_id,
@@ -287,7 +382,7 @@ let Agent = (() => {
                 if (this._onActionRequested !== undefined) {
                     suggestion = await this._onActionRequested(call, event.intent_summary);
                 }
-                call.sendCommand(commands_ts_1.ActionSuggestionCommand, {
+                await call.sendCommand(commands_ts_1.ActionSuggestionCommand, {
                     command_type: "action-suggestion",
                     intent_id: event.intent_id,
                     action_key: suggestion?.key ?? null,
@@ -296,6 +391,9 @@ let 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;
                 if (this._onActionGeneric !== undefined) {
                     onActionFunc = () => this._onActionGeneric(call, event.action_key);
@@ -311,9 +409,15 @@ let Agent = (() => {
                 }
             }
             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") {
@@ -323,14 +427,14 @@ let Agent = (() => {
                 this._logger.warn(`The Guava agent reported a warning: ${event.content}`);
             }
         }
-        async _startCall(variables = {}) {
+        async _initCall(variables = {}) {
             const call = new index_ts_1.Call(variables);
-            call.setPersona({
+            await call.setPersona({
                 agentName: this._name,
                 agentPurpose: this._purpose,
                 organizationName: this._organization,
             });
-            call.sendCommand(commands_ts_1.RegisteredHooksCommand, {
+            await call.sendCommand(commands_ts_1.RegisteredHooksCommand, {
                 command_type: "registered-hooks",
                 has_on_question: this._onQuestion !== undefined,
                 has_on_intent: false,
@@ -341,111 +445,291 @@ let Agent = (() => {
             }
             return call;
         }
-        _listenInbound(conn) {
-            const calls = {};
-            // return a way to *stop* listening
-            const url = new URL("v1/listen-inbound", this._client.getWebsocketBase());
-            const ws = new ws_1.default(url, {
-                headers: this._client.headers(),
-            });
-            let agent_number;
-            let webrtc_code;
-            if ("agent_number" in conn) {
-                agent_number = conn.agent_number;
+        async _attachToCall(callId, initialVariables = {}, testSession) {
+            const env_1 = { stack: [], error: void 0, hasError: false };
+            try {
+                const call = await this._initCall(initialVariables);
+                const url = new URL(`v2/connect-call/${callId}`, this._client.getWebsocketBase());
+                const socket = __addDisposableResource(env_1, await new client_ts_1.GuavaSocket(`call-connection-${callId}`, url.toString(), this._client, (cmd) => cmd, (payload) => (0, events_ts_1.decodeEventDict)(payload), 18000).connect(), true);
+                await call.setDrain(async (commands) => {
+                    for (const command of commands.splice(0)) {
+                        socket.send(command);
+                    }
+                });
+                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 client_ts_1.GuavaSocketClosedError))
+                        throw e;
+                }
             }
-            else {
-                webrtc_code = conn.webrtc_code;
+            catch (e_1) {
+                env_1.error = e_1;
+                env_1.hasError = true;
             }
-            this._logger.info(`Listening for calls to ${agent_number ?? webrtc_code}`);
-            if (webrtc_code) {
-                const debugurl = new URL(`debug-webrtc?webrtc_code=${webrtc_code}`, this._client.getHttpBase());
-                this._logger.info(`Call your agent at: ${debugurl}`);
+            finally {
+                const result_1 = __disposeResources(env_1);
+                if (result_1)
+                    await result_1;
             }
-            ws.addEventListener("open", (_ev) => {
-                ws.send(stringifyZod(commands_ts_1.ListenInboundCommand, {
-                    command_type: "listen-inbound",
-                    agent_number: agent_number,
-                    webrtc_code: webrtc_code,
-                }));
-            });
-            ws.addEventListener("close", (_ev) => {
-                ws.removeAllListeners();
-            });
-            ws.addEventListener("message", async (ev) => {
-                this._logger.debug("Received message: %s", ev.data.toString("utf8"));
-                const tunnel_event = events_ts_1.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 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(commands_ts_1.InboundTunnelCommand, {
-                                call_id: tunnel_event.call_id,
-                                command,
-                            }));
+        }
+        async _listenInbound(conn) {
+            const env_2 = { stack: [], error: void 0, hasError: false };
+            try {
+                const url = new URL("v2/listen-inbound", this._client.getWebsocketBase());
+                if ("agent_number" in conn) {
+                    url.searchParams.set("phone_number", conn.agent_number);
+                }
+                else {
+                    url.searchParams.set("webrtc_code", conn.webrtc_code);
+                }
+                const socket = __addDisposableResource(env_2, await new client_ts_1.GuavaSocket("listen-inbound", url.toString(), this._client, (msg) => msg, ListenInbound.decodeServerMessage).connect(), true);
+                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;
+                            }
                         }
-                    });
-                    calls[tunnel_event.call_id] = call;
+                    }
                 }
-                this._dispatchEvent(calls[tunnel_event.call_id], tunnel_event.event);
-            });
-            return new InboundListener(ws);
+                catch (e) {
+                    if (!(e instanceof client_ts_1.GuavaSocketClosedError))
+                        throw e;
+                }
+            }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
+            }
+            finally {
+                const result_2 = __disposeResources(env_2);
+                if (result_2)
+                    await result_2;
+            }
+        }
+        async _handleAssignedCall(callId, callInfo, socket, initialVariables = {}) {
+            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);
+            }
         }
         /**
          * @description use the Guava API to call out to a number
          */
         async callPhone(fromNumber, toNumber, variables = {}) {
-            const url = new URL("v1/create-outbound", this._client.getWebsocketBase());
-            const ws = new ws_1.default(url, {
-                headers: this._client.headers(),
+            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 (0, utils_ts_1.fetchOrThrow)(url, {
+                method: "POST",
+                headers: await this._client.headers(),
             });
-            const call = await this._startCall(variables);
-            let socketInitialized = false;
-            ws.addEventListener("open", async (_ev) => {
-                ws.send(stringifyZod(commands_ts_1.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 { call_id } = (await response.json());
+            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, variables = {}) {
+            const url = new URL("v1/test-agent", this._client.getWebsocketBase());
+            const headers = await this._client.headers();
+            const ws = new ws_1.default(url.toString(), { headers });
+            await new Promise((resolve, reject) => {
+                ws.once("open", resolve);
+                ws.once("error", reject);
+            });
+            const rawFirst = await new Promise((resolve, reject) => {
+                ws.once("message", (data) => resolve(data.toString()));
+                ws.once("error", reject);
             });
-            ws.addEventListener("message", (ev) => {
-                if (socketInitialized) {
-                    const session_started = z
-                        .union([events_ts_1.SessionStartedEvent, events_ts_1.ErrorEvent])
-                        .parse(JSON.parse(ev.data.toString("utf8")));
-                    if (session_started.event_type === "error") {
-                        throw new Error(`Outbound call failed: ${session_started.content}`);
+            const sessionStarted = protocol_ts_1.SessionStarted.parse(JSON.parse(rawFirst));
+            const testSession = new session_ts_1.TestSession(ws, this._client);
+            const attachPromise = this._attachToCall(sessionStarted.session_id, variables, testSession).catch((err) => {
+                this._logger.error("Error in _attachToCall during test: %s", err);
+            });
+            try {
+                await callback(testSession);
+            }
+            finally {
+                ws.close();
+                await attachPromise;
+            }
+            return testSession;
+        }
+        /**
+         * 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 testRoleplay(roleplayPrompt, variables = {}) {
+            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 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.`;
+                        const raw = await (0, llm_ts_1._generate)(this._client, prompt, roleplaySchema);
+                        const action = JSON.parse(raw);
+                        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.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 = (0, events_ts_1.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 = {}) {
+            await this.test(async (session) => {
+                await (0, chat_ts_1.runChat)(session);
+            }, variables);
+        }
+        /**
+         * 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() {
+            const cloned = new Agent({
+                name: this._name,
+                organization: this._organization,
+                purpose: this._purpose,
             });
-            ws.addEventListener("close", (_ev) => {
-                // we are closing the socket, so don't trigger any other listeners
-                ws.removeAllListeners();
-            });
+            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) {
+        async inboundPhone(phoneNumber) {
             return this.listenPhone(phoneNumber);
         }
         /** @deprecated Use {@link callPhone} instead. */
@@ -456,13 +740,4 @@ let Agent = (() => {
     return Agent = _classThis;
 })();
 exports.Agent = Agent;
-class InboundListener {
-    ws;
-    constructor(ws) {
-        this.ws = ws;
-    }
-    close() {
-        this.ws.close();
-    }
-}
 //# sourceMappingURL=agent.js.map