The Open Framework for Building Agents
feat(eve): render authorization prompts in private Chat SDK channels (e.g. iMessage DMs) (#2503)
Ben Pankow2a34f75e9ef8
diff --git a/.changeset/chat-sdk-authorization.md b/.changeset/chat-sdk-authorization.mdnew file mode 100644index 000000000..bb04e88c4--- /dev/null+++ b/.changeset/chat-sdk-authorization.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Chat SDK direct-message channels now support HITL authorization challenges.diff --git a/packages/eve/src/public/channels/chat-sdk/authorization.ts b/packages/eve/src/public/channels/chat-sdk/authorization.tsnew file mode 100644index 000000000..04957085f--- /dev/null+++ b/packages/eve/src/public/channels/chat-sdk/authorization.ts@@ -0,0 +1,101 @@+import type { Thread } from "#compiled/chat/index.js";+import { isNotImplemented } from "#public/channels/chat-sdk/notImplemented.js";+import type { ChatSdkChannelEvents } from "#public/channels/chat-sdk/chatSdkChannel.js";++/** Built-in connection authorization handlers for Chat SDK threads. */+export function defaultAuthorizationEvents(): Pick<+ ChatSdkChannelEvents,+ "authorization.completed" | "authorization.required"+> {+ return {+ async "authorization.required"(event, channel, _ctx) {+ if (!channel.thread || event.candidateId !== undefined) return;+ const pending = channel.state.pendingAuthMessageIds ?? {};+ if (pending[event.name] !== undefined) return;++ const displayName = authorizationDisplayName(event.name, event.authorization?.displayName);+ const message = channel.thread.isDM+ ? authorizationPrompt({+ displayName,+ instructions: event.authorization?.instructions,+ url: event.authorization?.url,+ userCode: event.authorization?.userCode,+ })+ : `Authorization required for ${displayName}. Continue in a direct message with this agent.`;+ const posted = await channel.thread.post({ markdown: message });+ if (posted.id) {+ channel.state.pendingAuthMessageIds = { ...pending, [event.name]: posted.id };+ }+ },++ async "authorization.completed"(event, channel, _ctx) {+ if (!channel.thread || event.candidateId !== undefined) return;+ const pending = channel.state.pendingAuthMessageIds ?? {};+ const messageId = pending[event.name];+ if (messageId === undefined) return;++ const message = authorizationCompleted({+ displayName: authorizationDisplayName(event.name, event.authorization?.displayName),+ outcome: event.outcome,+ reason: event.reason,+ });+ try {+ await editMessage(channel.thread, messageId, message);+ } catch (error) {+ if (!isNotImplemented(error)) throw error;+ channel.state.editSupported = false;+ await channel.thread.post({ markdown: message });+ }+ const next = { ...pending };+ delete next[event.name];+ channel.state.pendingAuthMessageIds = next;+ if (event.outcome === "authorized")+ await safeStartTyping(channel.thread, "Connected. Resuming...");+ },+ };+}++async function safeStartTyping(thread: Thread, status: string): Promise<void> {+ try {+ await thread.startTyping(status);+ } catch (error) {+ if (!isNotImplemented(error)) throw error;+ }+}++async function editMessage(thread: Thread, messageId: string, markdown: string): Promise<void> {+ await thread.adapter.editMessage(thread.id, messageId, { markdown });+}++function authorizationDisplayName(name: string, displayName: string | undefined): string {+ if (displayName !== undefined) return displayName;+ if (name.length === 0) return name;+ return name.charAt(0).toUpperCase() + name.slice(1);+}++function authorizationPrompt(input: {+ readonly displayName: string;+ readonly instructions?: string;+ readonly url?: string;+ readonly userCode?: string;+}): string {+ return [+ `Authorization required for ${input.displayName}.`,+ input.instructions,+ input.userCode === undefined ? undefined : `Code: ${input.userCode}`,+ input.url,+ ]+ .filter((part): part is string => part !== undefined && part.length > 0)+ .join("\n\n");+}++function authorizationCompleted(input: {+ readonly displayName: string;+ readonly outcome: "authorized" | "declined" | "failed" | "timed-out";+ readonly reason?: string;+}): string {+ if (input.outcome === "authorized") return `${input.displayName} connected.`;+ const reason = input.reason === undefined ? "" : ` (${input.reason})`;+ const outcome = input.outcome === "timed-out" ? "timed out" : input.outcome;+ return `${input.displayName} authorization ${outcome}${reason}.`;+}diff --git a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.tsindex 0ff5f4039..966e33095 100644--- a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts+++ b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.test.ts@@ -388,6 +388,101 @@ describe("chatSdkChannel", () => {]);});+ it("renders an authorization challenge in a direct-message thread and updates it on completion", async () => {+ const adapter = testAdapter();+ const bridge = chatSdkChannel({+ adapters: { test: adapter },+ state: memoryState(),+ userName: "bot",+ });+ const state: ChatSdkChannelState = { thread: serializedThread({ isDM: true }) };+ const channelAdapter = withState(getAdapter(bridge.channel), state);+ const ctx = buildAdapterContext(channelAdapter, stubAccessor());++ await callEvent(+ channelAdapter,+ makeEvent("authorization.required", {+ authorization: {+ displayName: "Notion Workspace",+ instructions: "Choose a workspace.",+ url: "https://connect.example.com/a/sca_1",+ userCode: "ABC-123",+ },+ name: "notion",+ sequence: 0,+ stepIndex: 0,+ turnId: "turn-1",+ }),+ ctx,+ );++ expect(adapter.posted).toEqual([+ {+ message: {+ markdown:+ "Authorization required for Notion Workspace.\n\nChoose a workspace.\n\nCode: ABC-123\n\nhttps://connect.example.com/a/sca_1",+ },+ threadId: THREAD_ID,+ },+ ]);+ expect(state.pendingAuthMessageIds).toEqual({ notion: "posted-1" });++ await callEvent(+ channelAdapter,+ makeEvent("authorization.completed", {+ authorization: { displayName: "Notion Workspace" },+ name: "notion",+ outcome: "authorized",+ sequence: 1,+ stepIndex: 0,+ turnId: "turn-1",+ }),+ ctx,+ );++ expect(adapter.edited).toEqual([+ {+ message: { markdown: "Notion Workspace connected." },+ messageId: "posted-1",+ threadId: THREAD_ID,+ },+ ]);+ expect(state.pendingAuthMessageIds).toEqual({});+ });++ it("keeps authorization challenges link-free outside direct messages", async () => {+ const adapter = testAdapter();+ const bridge = chatSdkChannel({+ adapters: { test: adapter },+ state: memoryState(),+ userName: "bot",+ });+ const channelAdapter = withState(getAdapter(bridge.channel), { thread: serializedThread() });+ const ctx = buildAdapterContext(channelAdapter, stubAccessor());++ await callEvent(+ channelAdapter,+ makeEvent("authorization.required", {+ authorization: { url: "https://connect.example.com/a/sca_1", userCode: "ABC-123" },+ name: "notion",+ sequence: 0,+ stepIndex: 0,+ turnId: "turn-1",+ }),+ ctx,+ );++ expect(adapter.posted).toEqual([+ {+ message: {+ markdown:+ "Authorization required for Notion. Continue in a direct message with this agent.",+ },+ threadId: THREAD_ID,+ },+ ]);+ });+it("does not throw when the adapter's startTyping is not implemented", async () => {const adapter = testAdapter();adapter.startTypingError = new NotImplementedError("startTyping");@@ -872,14 +967,14 @@ function message(text: string): Message {});}-function serializedThread() {+function serializedThread(overrides: { readonly isDM?: boolean } = {}) {return {_type: "chat:Thread",adapterName: "test",channelId: CHANNEL_ID,channelVisibility: "workspace",id: THREAD_ID,- isDM: false,+ isDM: overrides.isDM ?? false,} as const;}diff --git a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.ts b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.tsindex e280a7275..ed970d85f 100644--- a/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.ts+++ b/packages/eve/src/public/channels/chat-sdk/chatSdkChannel.ts@@ -32,6 +32,7 @@ import {Message,ThreadImpl,} from "#compiled/chat/index.js";+import { defaultAuthorizationEvents } from "#public/channels/chat-sdk/authorization.js";import { isNotImplemented } from "#public/channels/chat-sdk/notImplemented.js";import {defineChannel,@@ -83,6 +84,8 @@ export interface ChatSdkChannelState extends Record<string, unknown> {lastEditAtMs?: number | null;/** Buffered first line of a tool-call message, surfaced as typing status. */pendingToolCallMessage?: string | null;+ /** Authorization status messages, keyed by connection name. */+ pendingAuthMessageIds?: Record<string, string>;/** Step index the current stream anchor belongs to (resets per step). */streamStepIndex?: number | null;}@@ -349,6 +352,7 @@ function defaultEvents<TAdapters extends ChatSdkAdapters>(inputActionPrefix: string,): ChatSdkChannelEvents<TAdapters> {return {+ ...defaultAuthorizationEvents(),async "turn.started"(_event, channel, _ctx) {channel.state.pendingToolCallMessage = null;clearStream(channel.state);@@ -577,7 +581,7 @@ async function bridgeSend<TAdapters extends ChatSdkAdapters>(}function initialState(): ChatSdkChannelState {- return { thread: null };+ return { pendingAuthMessageIds: {}, thread: null };}function threadFromState<TAdapters extends ChatSdkAdapters>(