The Open Framework for Building Agents
[6/6] fix(chat-sdk): show approval and question options on text-only adapters (#4208)
Ben Pankow1360a1f4eb37
diff --git a/.changeset/chat-sdk-hitl-text-fallback.md b/.changeset/chat-sdk-hitl-text-fallback.mdnew file mode 100644index 000000000..0de080d44--- /dev/null+++ b/.changeset/chat-sdk-hitl-text-fallback.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Chat SDK adapters without card support, such as Photon iMessage and Linq, now show `ask_question` prompts and tool approvals with numbered options, so a person can answer by replying with an option's number or label (for example `approve` or `cancel`). Freeform questions now ask for a typed reply on every adapter instead of pointing to the eve session UI.diff --git a/docs/channels/chat-sdk.mdx b/docs/channels/chat-sdk.mdxindex 2ad31b650..dd0db412e 100644--- a/docs/channels/chat-sdk.mdx+++ b/docs/channels/chat-sdk.mdx@@ -179,7 +179,7 @@ chatSdkChannel({### Human-in-the-loop (HITL)-HITL prompts render as a Chat SDK `Card` with buttons. Button clicks resume the parked session automatically — the channel wires `bot.onAction` to `respond` for you. Change the action-id prefix with `inputActionPrefix` (default `eve_input:`) if your app already uses it, and provide `resolveInputAuth` to carry user or tenant auth across the resume:+HITL prompts render as a Chat SDK `Card` with buttons. Button clicks resume the parked session automatically — the channel wires `bot.onAction` to `respond` for you. Adapters that can't render cards, such as Photon iMessage, get fallback text with the options numbered. A reply forwarded through `send` 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, or has no options, the message asks for a typed reply and any other text is taken as that answer. Change the action-id prefix with `inputActionPrefix` (default `eve_input:`) if your app already uses it, and provide `resolveInputAuth` to carry user or tenant auth across the resume:```tschatSdkChannel({diff --git a/packages/eve/src/internal/testing/channel-conformance/chat-sdk-driver.ts b/packages/eve/src/internal/testing/channel-conformance/chat-sdk-driver.tsindex 80a48a68b..f0fea5d0e 100644--- a/packages/eve/src/internal/testing/channel-conformance/chat-sdk-driver.ts+++ b/packages/eve/src/internal/testing/channel-conformance/chat-sdk-driver.ts@@ -11,7 +11,11 @@ import {toPlainText,} from "#compiled/chat/index.js";import { createMemoryState } from "#compiled/@chat-adapter/state-memory/index.js";-import type { ChannelDriver, PlatformCall } from "#internal/testing/channel-conformance/harness.js";+import {+ type ChannelDriver,+ type PlatformCall,+ numberedOptions,+} from "#internal/testing/channel-conformance/harness.js";const ADAPTER = "conformance";const PERSON = { fullName: "Alice", isBot: false, isMe: false, userId: "alice", userName: "alice" };@@ -76,11 +80,7 @@ export function chatSdkTextDriver(): ChannelDriver {if (!isPost(call) || typeof call.body !== "string" || !call.body.includes(prompt)) {return undefined;}- // #3715's fallback lists each choice as `"<id>" (<label>)`.- return [...call.body.matchAll(/"[^"]+" \(([^)]+)\)/gu)].map(([, label]) => ({- handle: label,- label: label!,- }));+ return numberedOptions(call.body);},press() {throw new Error("A text-only Chat SDK adapter has nothing to press.");diff --git a/packages/eve/src/internal/testing/channel-conformance/conformance.ts b/packages/eve/src/internal/testing/channel-conformance/conformance.tsindex 48c3763eb..7fedf9793 100644--- a/packages/eve/src/internal/testing/channel-conformance/conformance.ts+++ b/packages/eve/src/internal/testing/channel-conformance/conformance.ts@@ -41,22 +41,7 @@ interface ConformanceChannel {* failure (such as harness breakage) both turn it red.*/const hitlConformance = {- "chat-sdk": [- { driver: chatSdkDriver },- {- driver: chatSdkTextDriver,- broken: {- "a rendered question shows every option a person can choose": {- reason: "#3712: the card's fallback text is only the prompt",- symptom: /the question showed \[\]/,- },- "a tool approval shows Approve and Cancel": {- reason: "#3712: the card's fallback text is only the prompt",- symptom: /the approval showed \[\]/,- },- },- },- ],+ "chat-sdk": [{ driver: chatSdkDriver }, { driver: chatSdkTextDriver }],discord: [{ driver: discordDriver }],github: [{ driver: githubDriver }],linear: [{ driver: linearDriver }],diff --git a/packages/eve/src/internal/testing/channel-conformance/harness.ts b/packages/eve/src/internal/testing/channel-conformance/harness.tsindex 24b749c47..9f278958e 100644--- a/packages/eve/src/internal/testing/channel-conformance/harness.ts+++ b/packages/eve/src/internal/testing/channel-conformance/harness.ts@@ -26,6 +26,16 @@ export interface RenderedOption {readonly handle: unknown;}+/** Reads text-only options rendered as `1. Label` or `1. Label - description` lines. */+export function numberedOptions(text: string): RenderedOption[] {+ return text+ .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 }));+}+/*** What a platform can do for a person, independent of eve. A rule that needs a* capability a driver lacks is skipped for that channel as "not supported".diff --git a/packages/eve/src/internal/testing/channel-conformance/linq-driver.ts b/packages/eve/src/internal/testing/channel-conformance/linq-driver.tsindex 2d1c0a19b..a18d1c8a3 100644--- a/packages/eve/src/internal/testing/channel-conformance/linq-driver.ts+++ b/packages/eve/src/internal/testing/channel-conformance/linq-driver.ts@@ -4,6 +4,7 @@ import { linqChannel } from "#public/channels/linq/index.js";import {type ChannelDriver,type PlatformCall,+ numberedOptions,recordingFetch,} from "#internal/testing/channel-conformance/harness.js";@@ -95,11 +96,8 @@ export function linqDriver(): ChannelDriver {findOptions(call, prompt) {if (!call.method.endsWith("/messages") || !postedText(call)?.includes(prompt))return undefined;- const text = postedText(call)!;- const options = text.match(/Options:\s*(.+)$/u)?.[1];- return options === undefined- ? []- : options.split(",").map((label) => ({ handle: label.trim(), label: label.trim() }));+ // The Chat SDK bridge's fallback text replaces Linq's own `Options:` card flattening.+ return numberedOptions(postedText(call)!);},press() {throw new Error("Linq has no pressable HITL controls.");diff --git a/packages/eve/src/internal/testing/channel-conformance/twilio-driver.ts b/packages/eve/src/internal/testing/channel-conformance/twilio-driver.tsindex 5fab69691..7b9a86e99 100644--- a/packages/eve/src/internal/testing/channel-conformance/twilio-driver.ts+++ b/packages/eve/src/internal/testing/channel-conformance/twilio-driver.ts@@ -3,6 +3,7 @@ import { signTwilioRequest } from "#public/channels/twilio/verify.js";import {type ChannelDriver,type PlatformCall,+ numberedOptions,recordingFetch,} from "#internal/testing/channel-conformance/harness.js";@@ -59,11 +60,7 @@ export function twilioDriver(): ChannelDriver {if (call.method !== "Messages.json") return undefined;const body = call.body as { readonly Body?: unknown };if (typeof body.Body !== "string" || !body.Body.includes(prompt)) return undefined;- 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 }));+ return numberedOptions(body.Body);},press: () => {throw new Error("Twilio SMS does not support pressing options.");diff --git a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.tsindex 747c67a8d..5c604fe97 100644--- a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts+++ b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts@@ -718,7 +718,7 @@ describe("chatSdkChannel", () => {expect(state.pendingToolCallMessage).toBe("Let me check that.");});- it("renders input requests as Chat SDK cards with one button per option", async () => {+ it("renders input requests as Chat SDK cards with buttons and a text fallback naming each reply", async () => {const adapter = testAdapter();const bridge = chatSdkChannel({adapters: { test: adapter },@@ -754,31 +754,91 @@ describe("chatSdkChannel", () => {ctx,);- const card = adapter.posted[0]?.message as AdapterPostableMessage;- expect(card).toMatchObject({- children: [- { content: "Deploy?", type: "text" },- {- children: [- {- id: "eve_input:request-1:approve",- label: "Approve",- style: "primary",- type: "button",- value: "approve",- },- {- id: "eve_input:request-1:cancel",- label: "Cancel",- style: "danger",- type: "button",- value: "cancel",- },- ],- type: "actions",- },- ],- type: "card",+ const posted = adapter.posted[0]?.message as AdapterPostableMessage;+ expect(posted).toMatchObject({+ card: {+ children: [+ { content: "Deploy?", type: "text" },+ {+ children: [+ {+ id: "eve_input:request-1:approve",+ label: "Approve",+ style: "primary",+ type: "button",+ value: "approve",+ },+ {+ id: "eve_input:request-1:cancel",+ label: "Cancel",+ style: "danger",+ type: "button",+ value: "cancel",+ },+ ],+ type: "actions",+ },+ ],+ type: "card",+ },+ fallbackText: "Deploy?\n\n1. Approve\n2. Cancel\n\nReply with a number to choose.",+ });+ });++ it("asks for a typed reply when an input request accepts a freeform answer", async () => {+ const adapter = testAdapter();+ const bridge = chatSdkChannel({+ adapters: { test: adapter },+ concurrency: "concurrent",+ state: memoryState(),+ logger: "warn",+ userName: "bot",+ });+ const channelAdapter = withState(getAdapter(bridge.channel), {+ thread: serializedThread(),+ });+ const ctx = buildAdapterContext(channelAdapter, stubAccessor());++ await callEvent(+ channelAdapter,+ makeEvent("input.requested", {+ requests: [+ {+ action: { callId: "call-1", name: "ask", type: "tool-call" },+ display: "text",+ prompt: "Which region?",+ requestId: "request-1",+ },+ {+ action: { callId: "call-2", name: "ask", type: "tool-call" },+ allowFreeform: true,+ display: "select",+ options: [{ id: "iad1", label: "Washington" }],+ prompt: "Which zone?",+ requestId: "request-2",+ },+ ],+ sequence: 1,+ stepIndex: 0,+ turnId: "turn-1",+ }),+ ctx,+ );++ const posted = adapter.posted[0]?.message as AdapterPostableMessage;+ expect(posted).toMatchObject({+ card: {+ children: [+ { content: "Which region?", type: "text" },+ { content: "Reply with your answer.", type: "text" },+ { content: "Which zone?", type: "text" },+ { type: "actions" },+ { content: "Or reply with your own answer.", type: "text" },+ ],+ },+ fallbackText:+ "Which region?\n\nReply with your answer.\n\n" ++ "Which zone?\n\n1. Washington\n\nReply with a number, or with your own answer.",});});});diff --git a/packages/eve/src/public/channels/chat-sdk/input-actions.ts b/packages/eve/src/public/channels/chat-sdk/input-actions.tsindex 0708fb903..0423ed9b1 100644--- a/packages/eve/src/public/channels/chat-sdk/input-actions.ts+++ b/packages/eve/src/public/channels/chat-sdk/input-actions.ts@@ -2,11 +2,39 @@ import type { InputRequest } from "#shared/input.js";import type { CardChild } from "#compiled/chat/index.js";import { Actions, Button, Card, CardText } from "#compiled/chat/index.js";-/** Renders pending input requests as a Chat SDK card with one button per option. */+// A text reply answers a pending request: an option's number, label, or id, or+// any text when the request has no options or allows a freeform answer.+const FREEFORM_HINT = "Reply with your answer.";++/**+ * Renders pending input requests as a Chat SDK card with one button per option,+ * plus fallback text for adapters without cards (such as Photon iMessage).+ */export function renderInputRequests(requests: readonly InputRequest[], inputActionPrefix: string) {- return Card({- children: requests.flatMap((request) => renderInputRequest(request, inputActionPrefix)),- });+ return {+ card: Card({+ children: requests.flatMap((request) => renderInputRequest(request, inputActionPrefix)),+ }),+ fallbackText: requests.map(renderInputRequestText).join("\n\n"),+ };+}++// The SDK's card fallback drops buttons, so the options are numbered instead.+function renderInputRequestText(request: InputRequest): string {+ const options = request.options ?? [];+ if (options.length === 0) return `${request.prompt}\n\n${FREEFORM_HINT}`;+ return [+ request.prompt,+ "",+ ...options.map((option, index) => {+ const description = option.description ? ` - ${option.description}` : "";+ return `${index + 1}. ${option.label}${description}`;+ }),+ "",+ request.allowFreeform === true+ ? "Reply with a number, or with your own answer."+ : "Reply with a number to choose.",+ ].join("\n");}function renderInputRequest(request: InputRequest, inputActionPrefix: string) {@@ -24,11 +52,10 @@ function renderInputRequest(request: InputRequest, inputActionPrefix: string) {),),);+ if (request.allowFreeform === true) children.push(CardText("Or reply with your own answer."));return children;}- children.push(- CardText("This request needs a freeform answer. Continue from the eve session UI."),- );+ children.push(CardText(FREEFORM_HINT));return children;}