Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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:
```ts
chatSdkChannel({
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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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;
}