Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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>(