Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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 sessions
diff --git a/packages/eve/src/channel/resolve-text.ts b/packages/eve/src/channel/resolve-text.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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: "*",