The Open Framework for Building Agents
fix(twilio): send questions and tool approvals by SMS (#4169)
Ben Pankow46f8a6ec5024
diff --git a/.changeset/twilio-ask-question.md b/.changeset/twilio-ask-question.mdnew file mode 100644index 000000000..d7753e7dd--- /dev/null+++ b/.changeset/twilio-ask-question.md@@ -0,0 +1,5 @@+---+"eve": patch+---++The Twilio channel now sends `ask_question` prompts and tool approvals by SMS with numbered options, so a person can answer by replying with an option's number or label (for example `approve` or `cancel`). Previously the request was never sent and the session stayed parked.diff --git a/docs/channels/twilio.mdx b/docs/channels/twilio.mdxindex e7fffa402..0359434b2 100644--- a/docs/channels/twilio.mdx+++ b/docs/channels/twilio.mdx@@ -62,7 +62,7 @@ The default `message.completed` handler sends the reply as SMS through Twilio's### Human-in-the-loop (HITL)-SMS and voice have no native button or card affordance, so HITL prompts do not render as interactive controls. The agent's `input.requested` event reaches your `events["input.requested"]` handler if you declare one. Handle it by sending the prompt as text and mapping the caller's reply back to the input request yourself.+SMS has no buttons or cards, so the default `input.requested` handler sends each question and tool approval as an SMS with its options numbered. A reply with an option's number or label answers the pending request, so `1` or `approve` runs an approval-gated tool and `2` or `cancel` stops it. If the question allows a custom answer, any other text is taken as that answer. Callers on a voice call get the question by SMS too. To render questions differently, declare your own `events["input.requested"]` handler.### Proactive sessionsdiff --git a/packages/eve/src/channel/resolve-text.ts b/packages/eve/src/channel/resolve-text.tsindex d042c9967..8be25505d 100644--- a/packages/eve/src/channel/resolve-text.ts+++ b/packages/eve/src/channel/resolve-text.ts@@ -7,6 +7,27 @@ interface TextResolvableRequest {readonly requestId: string;}+/**+ * Renders a request's prompt and numbered options as the plain text that+ * {@link resolveTextToResponse} parses, so a reply with the number, label, or+ * id answers it. Channels append their own reply instructions.+ */+export function renderTextInputRequest(+ request: TextResolvableRequest & { readonly prompt: string },+): string {+ const lines = [request.prompt];+ if (request.options !== undefined && request.options.length > 0) {+ lines.push(+ "",+ ...request.options.map((option, index) => {+ const description = option.description ? ` - ${option.description}` : "";+ return `${index + 1}. ${option.label}${description}`;+ }),+ );+ }+ return lines.join("\n");+}+/*** Maps freeform text to an {@link InputResponse} for a single request.*diff --git a/packages/eve/src/internal/testing/channel-conformance/conformance.ts b/packages/eve/src/internal/testing/channel-conformance/conformance.tsindex 434484cce..48c3763eb 100644--- a/packages/eve/src/internal/testing/channel-conformance/conformance.ts+++ b/packages/eve/src/internal/testing/channel-conformance/conformance.ts@@ -80,35 +80,7 @@ const hitlConformance = {},},],- twilio: [- {- driver: twilioDriver,- broken: {- "a rendered question shows every option a person can choose": {- reason: "the channel never sends the question (no input.requested handler)",- symptom:- /Timed out waiting for the question "Which day works for the review\?" on twilio/,- },- "a text reply matching an option answers the only pending question": {- reason: "the channel never sends the question (no input.requested handler)",- symptom:- /Timed out waiting for the question "Which day works for the review\?" on twilio/,- },- "a tool approval shows Approve and Cancel": {- reason: "the channel never sends the approval (no input.requested handler)",- symptom: /Timed out waiting for the question "Approve Deploy release\?" on twilio/,- },- "a text reply of approve runs the gated tool": {- reason: "the channel never sends the approval (no input.requested handler)",- symptom: /Timed out waiting for the question "Approve Deploy release\?" on twilio/,- },- "a text reply of cancel stops the gated tool without running it": {- reason: "the channel never sends the approval (no input.requested handler)",- symptom: /Timed out waiting for the question "Approve Deploy release\?" on twilio/,- },- },- },- ],+ twilio: [{ driver: twilioDriver }],} satisfies Record<string, readonly ConformanceChannel[]>;/**diff --git a/packages/eve/src/internal/testing/channel-conformance/twilio-driver.ts b/packages/eve/src/internal/testing/channel-conformance/twilio-driver.tsindex 1a46ad828..5fab69691 100644--- a/packages/eve/src/internal/testing/channel-conformance/twilio-driver.ts+++ b/packages/eve/src/internal/testing/channel-conformance/twilio-driver.ts@@ -62,6 +62,7 @@ export function twilioDriver(): ChannelDriver {return body.Body.split("\n").map((line) => /^\s*\d+[.)]\s*(.+?)\s*$/u.exec(line)?.[1]).filter((label): label is string => label !== undefined)+ .map((line) => line.split(" - ", 1)[0]!).map((label) => ({ handle: label, label }));},press: () => {diff --git a/packages/eve/src/public/channels/github/defaults.ts b/packages/eve/src/public/channels/github/defaults.tsindex 2fa4a0bb2..920f86fe4 100644--- a/packages/eve/src/public/channels/github/defaults.ts+++ b/packages/eve/src/public/channels/github/defaults.ts@@ -3,6 +3,7 @@ import type { SandboxSession } from "#shared/sandbox-session.js";type NetworkPolicySandboxSession = SandboxSession & {setNetworkPolicy(policy: SandboxNetworkPolicy): Promise<void>;};+import { renderTextInputRequest } from "#channel/resolve-text.js";import type { SessionAuthContext } from "#channel/types.js";import { createLogger, extractErrorId, formatErrorHint, logError } from "#internal/logging.js";@@ -143,20 +144,10 @@ export function createDefaultEvents(options: GitHubDefaultEventOptions = {}): Gi}function renderInputRequest(request: InputRequest): string {- const lines = [request.prompt];- if (request.options !== undefined && request.options.length > 0) {- lines.push(- "",- ...request.options.map((option, index) => {- const description = option.description ? ` - ${option.description}` : "";- return `${index + 1}. ${option.label}${description}`;- }),- );- }- if (request.allowFreeform === true) {- lines.push("", "You can also reply with a custom answer.");- }- return lines.join("\n");+ const body = renderTextInputRequest(request);+ return request.allowFreeform === true+ ? `${body}\n\nYou can also reply with a custom answer.`+ : body;}// The default onComment hook only dispatches comments that @mention the bot,diff --git a/packages/eve/src/public/channels/linear/hitl.ts b/packages/eve/src/public/channels/linear/hitl.tsindex 20c1b7907..f2fc0d825 100644--- a/packages/eve/src/public/channels/linear/hitl.ts+++ b/packages/eve/src/public/channels/linear/hitl.ts@@ -1,3 +1,4 @@+import { renderTextInputRequest } from "#channel/resolve-text.js";import type { InputRequest } from "#shared/input.js";import type { JsonObject } from "#shared/json.js";@@ -26,18 +27,8 @@ export function linearInputRequestSignal(requests: readonly InputRequest[]): {}function renderLinearInputRequest(request: InputRequest): string {- const lines = [request.prompt];- if (request.options !== undefined && request.options.length > 0) {- lines.push(- "",- ...request.options.map((option, index) => {- const description = option.description ? ` - ${option.description}` : "";- return `${index + 1}. ${option.label}${description}`;- }),- );- }- if (request.allowFreeform === true) {- lines.push("", "You can also reply with a custom answer.");- }- return lines.join("\n");+ const body = renderTextInputRequest(request);+ return request.allowFreeform === true+ ? `${body}\n\nYou can also reply with a custom answer.`+ : body;}diff --git a/packages/eve/src/public/channels/twilio/defaults.ts b/packages/eve/src/public/channels/twilio/defaults.tsindex 164129851..0f3e604cf 100644--- a/packages/eve/src/public/channels/twilio/defaults.ts+++ b/packages/eve/src/public/channels/twilio/defaults.ts@@ -1,3 +1,4 @@+import { renderTextInputRequest } from "#channel/resolve-text.js";import type { SessionAuthContext } from "#channel/types.js";import { extractErrorId, formatErrorHint } from "#internal/logging.js";@@ -12,6 +13,7 @@ import type {TwilioInboundResult,TwilioVoiceResult,} from "#public/channels/twilio/twilioChannel.js";+import type { InputRequest } from "#shared/input.js";/** Default phone-number auth projection for Twilio webhook actors. */function defaultTwilioAuth(input: {@@ -74,6 +76,11 @@ export const defaultEvents: TwilioChannelEvents = {await channel.twilio.sendMessage(event.message);},+ async "input.requested"(event, channel, _ctx) {+ if (event.requests.length === 0) return;+ await channel.twilio.sendMessage(renderTwilioInputRequests(event.requests));+ },+async "turn.failed"(event, channel, _ctx) {const hint = formatErrorHint(event);const errorId = extractErrorId(event.details);@@ -100,3 +107,22 @@ export const defaultEvents: TwilioChannelEvents = {);},};++// SMS has no buttons, so options are numbered. The batch goes out as one message+// because a text reply resolves against every pending request at once.+function renderTwilioInputRequests(requests: readonly InputRequest[]): string {+ const sections = requests.map(renderTextInputRequest);+ const hasOptions = requests.some((request) => (request.options ?? []).length > 0);+ if (hasOptions) {+ const freeform = requests.some((request) => request.allowFreeform === true);+ sections.push(+ [+ freeform+ ? "Reply with a number, or with your own answer."+ : "Reply with a number to choose.",+ ...(requests.length > 1 ? ["Your reply answers each of these."] : []),+ ].join(" "),+ );+ }+ return sections.join("\n\n");+}diff --git a/packages/eve/src/public/channels/twilio/twilioChannel.test.ts b/packages/eve/src/public/channels/twilio/twilioChannel.test.tsindex 06f0dce24..d3e6b68c3 100644--- a/packages/eve/src/public/channels/twilio/twilioChannel.test.ts+++ b/packages/eve/src/public/channels/twilio/twilioChannel.test.ts@@ -663,6 +663,70 @@ describe("twilioChannel() default event handlers", () => {});});+ it("input.requested sends a batch of approvals as one SMS, since one reply answers them all", async () => {+ const bodies: string[] = [];+ const fetchMock: typeof fetch = async (_input, init) => {+ bodies.push(new URLSearchParams(String(init?.body)).get("Body") ?? "");+ return new Response(JSON.stringify({ sid: "SM999" }), {+ headers: { "content-type": "application/json" },+ });+ };+ const adapter = withState(+ getAdapter(+ twilioChannel({+ allowFrom: "*",+ api: { apiBaseUrl: "https://twilio.test", fetch: fetchMock },+ messaging: { from: "+15557654321" },+ }),+ ),+ { from: "+15551234567", lastCallSid: null, lastMessageSid: "SM123", to: "+15557654321" },+ );++ await callEvent(+ adapter,+ makeEvent("input.requested", {+ requests: [+ {+ action: { callId: "call_1", input: {}, kind: "tool-call", toolName: "deploy_release" },+ allowFreeform: false,+ display: "confirmation",+ kind: "tool-approval",+ options: [+ { id: "approve", label: "Approve" },+ { id: "cancel", label: "Cancel" },+ ],+ prompt: "Approve Deploy release?",+ requestId: "approval_1",+ },+ {+ action: { callId: "call_2", input: {}, kind: "tool-call", toolName: "rotate_keys" },+ allowFreeform: false,+ display: "confirmation",+ kind: "tool-approval",+ options: [+ { id: "approve", label: "Approve" },+ { id: "cancel", label: "Cancel" },+ ],+ prompt: "Approve Rotate keys?",+ requestId: "approval_2",+ },+ ],+ sequence: 0,+ stepIndex: 0,+ turnId: "t1",+ }),+ buildAdapterContext(adapter, stubAccessor()),+ );++ expect(bodies).toEqual([+ [+ "Approve Deploy release?\n\n1. Approve\n2. Cancel",+ "Approve Rotate keys?\n\n1. Approve\n2. Cancel",+ "Reply with a number to choose. Your reply answers each of these.",+ ].join("\n\n"),+ ]);+ });+it("receive starts a phone-pair session with an explicit continuation token", async () => {const channel = twilioChannel({allowFrom: "*",