The Open Framework for Building Agents
Clarify X Chat SDK setup (#2446)
OwenKephart80571ee6116b
diff --git a/.changeset/quiet-cobras-smile.md b/.changeset/quiet-cobras-smile.mdnew file mode 100644index 000000000..24ae38262--- /dev/null+++ b/.changeset/quiet-cobras-smile.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Show declared environment variables and an eve setup link after adding a registry integration from the dev TUI. Chat SDK adapter links open the integration page's Configure section.diff --git a/apps/docs/app/[lang]/integrations/[slug]/page.tsx b/apps/docs/app/[lang]/integrations/[slug]/page.tsxindex 32196dd38..dae32f0bb 100644--- a/apps/docs/app/[lang]/integrations/[slug]/page.tsx+++ b/apps/docs/app/[lang]/integrations/[slug]/page.tsx@@ -54,8 +54,16 @@ export const generateMetadata = async ({};};-const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (- <section className="flex flex-col gap-2 border-t py-8 first:border-t-0 first:pt-0">+const Section = ({+ id,+ title,+ children,+}: {+ id?: string;+ title: string;+ children: React.ReactNode;+}) => (+ <section className="flex flex-col gap-2 border-t py-8 first:border-t-0 first:pt-0" id={id}><h2 className="text-gray-1000 text-heading-20">{title}</h2>{children}</section>@@ -148,7 +156,7 @@ const IntegrationDetailPage = async ({ params }: PageProps<"/[lang]/integrations</Markdown>)}</Section>- <Section title="Configure">+ <Section id="configure" title="Configure">{setup ? (<Suspensefallback={diff --git a/apps/docs/lib/integrations/data.ts b/apps/docs/lib/integrations/data.tsindex 8d0708d78..01a20247c 100644--- a/apps/docs/lib/integrations/data.ts+++ b/apps/docs/lib/integrations/data.ts@@ -495,6 +495,8 @@ export const { bot, channel, send } = chatSdkChannel({userName: "My Agent",adapters: { x: createXAdapter() },state: createMemoryState(),+ // X buffers replies and posts once rather than editing a streamed message.+ streaming: false,});bot.onNewMention(async (thread: Thread, message: Message) => {@@ -502,6 +504,10 @@ bot.onNewMention(async (thread: Thread, message: Message) => {await send(message.text, { thread });});+bot.onDirectMessage(async (thread: Thread, message: Message) => {+ await send(message.text, { thread });+});+bot.onSubscribedMessage(async (thread: Thread, message: Message) => {await send(message.text, { thread });});@@ -509,8 +515,8 @@ bot.onSubscribedMessage(async (thread: Thread, message: Message) => {export default channel;\`\`\`-Credentials come from the \`createXAdapter\` config or the adapter's environment variables; see the [X adapter docs](https://chat-sdk.dev/adapters/official/x).`,- configure: `The adapter mounts its webhook at \`/eve/v1/x\`. Point your X account activity webhook at it. The adapter owns provider auth, verification, and delivery, while eve owns session dispatch, streaming, typing, and human-in-the-loop. See the [Chat SDK channel docs](/docs/channels/chat-sdk) for routes, streaming, and state options.`,+For a DM-only agent, keep \`bot.onDirectMessage\` and remove the \`bot.onNewMention\` and \`bot.onSubscribedMessage\` handlers. Configure the app's credentials and webhook before deploying.`,+ configure: `Follow the [X adapter documentation](https://chat-sdk.dev/adapters/official/x) to configure authentication, webhook verification, and Activity API subscriptions. Register the deployed agent's \`/eve/v1/x\` route as the X webhook URL. See the [Chat SDK channel docs](/docs/channels/chat-sdk) for eve route and state options.`,},"chat-sdk-messenger": {logo: "messenger",diff --git a/apps/docs/registry.json b/apps/docs/registry.jsonindex a74d6a20d..101552423 100644--- a/apps/docs/registry.json+++ b/apps/docs/registry.json@@ -1671,7 +1671,7 @@},"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-gchat#configure","implementation": "chat-sdk"}}@@ -1697,7 +1697,7 @@},"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-whatsapp#configure","implementation": "chat-sdk"}}@@ -1721,7 +1721,7 @@},"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-x#configure","implementation": "chat-sdk"}}@@ -1746,7 +1746,7 @@},"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-messenger#configure","implementation": "chat-sdk"}}@@ -1770,7 +1770,7 @@],"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-zernio#configure","implementation": "chat-sdk"}}@@ -1794,7 +1794,7 @@],"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-velt#configure","implementation": "chat-sdk"}}@@ -1819,7 +1819,7 @@],"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-sendblue#configure","implementation": "chat-sdk"}}@@ -1843,7 +1843,7 @@},"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-novu#configure","implementation": "chat-sdk"}}@@ -1867,7 +1867,7 @@],"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-liveblocks#configure","implementation": "chat-sdk"}}@@ -1912,7 +1912,7 @@],"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-kapso#configure","implementation": "chat-sdk"}}@@ -1957,7 +1957,7 @@],"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-dial#configure","implementation": "chat-sdk"}}@@ -1982,7 +1982,7 @@],"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-agentphone#configure","implementation": "chat-sdk"}}@@ -2006,7 +2006,7 @@],"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-lark#configure","implementation": "chat-sdk"}}@@ -2030,7 +2030,7 @@},"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-beeper#configure","implementation": "chat-sdk"}}@@ -2055,7 +2055,7 @@],"meta": {"eve": {- "docs": "/docs/channels/chat-sdk",+ "docs": "/integrations/chat-sdk-resend#configure","implementation": "chat-sdk"}}diff --git a/apps/docs/registry/channels/chat-sdk-x.ts b/apps/docs/registry/channels/chat-sdk-x.tsindex a163e1e0d..d5ab68fc7 100644--- a/apps/docs/registry/channels/chat-sdk-x.ts+++ b/apps/docs/registry/channels/chat-sdk-x.ts@@ -7,6 +7,8 @@ export const { bot, channel, send } = chatSdkChannel({userName: "My Agent",adapters: { x: createXAdapter() },state: createMemoryState(),+ // X buffers replies and posts once rather than editing a streamed message.+ streaming: false,});bot.onNewMention(async (thread: Thread, message: Message) => {@@ -14,6 +16,10 @@ bot.onNewMention(async (thread: Thread, message: Message) => {await send(message.text, { thread });});+bot.onDirectMessage(async (thread: Thread, message: Message) => {+ await send(message.text, { thread });+});+bot.onSubscribedMessage(async (thread: Thread, message: Message) => {await send(message.text, { thread });});diff --git a/docs/channels/chat-sdk.mdx b/docs/channels/chat-sdk.mdxindex 2a82aa7cc..86fd6f001 100644--- a/docs/channels/chat-sdk.mdx+++ b/docs/channels/chat-sdk.mdx@@ -63,7 +63,7 @@ eve deploy## Configure the webhook route-Each adapter mounts one `POST` route at `/eve/v1/{adapterName}`, so the `resend` adapter above is served at `/eve/v1/resend`. Point your provider's webhook (the Resend inbound address, the Slack Event Subscriptions URL, etc.) at that path.+Each adapter registers `GET` and `POST` handlers at `/eve/v1/{adapterName}`, so the `resend` adapter above is served at `/eve/v1/resend`. Point your provider's webhook (the Resend inbound address, the Slack Event Subscriptions URL, etc.) at that path. The adapter handles the incoming method. For example, X sends its webhook-verification challenge with `GET` and delivers events with `POST`.Override the base path for every adapter with `route`, or pin an individual adapter's path with `routes`:diff --git a/packages/eve/src/setup/flows/registry.test.ts b/packages/eve/src/setup/flows/registry.test.tsindex c1a7ad92f..b8ae662a6 100644--- a/packages/eve/src/setup/flows/registry.test.ts+++ b/packages/eve/src/setup/flows/registry.test.ts@@ -59,11 +59,11 @@ describe("runRegistryFlow", () => {address: "extension/agent-browser",title: "Agent Browser",facts: [],- output: [],+ output: ["Environment: AGENT_BROWSER_TOKEN"],},],facts: [],- output: [],+ output: ["Environment: AGENT_BROWSER_TOKEN"],});expect(flowDeps.installRegistryItem).toHaveBeenCalledWith(APP_ROOT,@@ -124,6 +124,35 @@ describe("runRegistryFlow", () => {});});+ it("prints an installed registry item's environment and documentation", async () => {+ const answers = ["category:extension", "item:0", "add"];+ const fake = createFakePrompter({ single: () => answers.shift()! });++ await expect(+ runRegistryFlow({+ appRoot: APP_ROOT,+ prompter: fake.prompter,+ deps: deps({+ getRegistryItemManifest: vi.fn(async () => ({+ description: "Browser automation",+ envVars: { BROWSER_TOKEN: "", BROWSER_URL: "" },+ meta: { eve: { docs: "/integrations/browser" } },+ name: "extension/agent-browser",+ })),+ }),+ }),+ ).resolves.toMatchObject({+ items: [+ {+ output: [+ "Environment: BROWSER_TOKEN, BROWSER_URL",+ "Setup: https://eve.dev/integrations/browser",+ ],+ },+ ],+ });+ });+it("uses the registry title when labeling an item", async () => {const answers = ["category:channel", "action:back", "action:done"];const prompts: unknown[] = [];diff --git a/packages/eve/src/setup/flows/registry.ts b/packages/eve/src/setup/flows/registry.tsindex d3ddf4f16..9de7f5aea 100644--- a/packages/eve/src/setup/flows/registry.ts+++ b/packages/eve/src/setup/flows/registry.ts@@ -1,3 +1,4 @@+import { z } from "#compiled/zod/index.js";import type { RegistryCatalogItem } from "#cli/commands/registry.js";import type {Prompter,@@ -162,12 +163,33 @@ function manifestRecord(manifest: unknown): Record<string, unknown> {: {};}+const RegistryDocumentationSchema = z.object({+ meta: z+ .object({+ eve: z.object({ docs: z.string().min(1).optional() }).optional(),+ })+ .optional(),+});++function documentationLink(manifest: Record<string, unknown>): string | undefined {+ const docs = RegistryDocumentationSchema.safeParse(manifest).data?.meta?.eve?.docs;+ if (docs === undefined) return undefined;+ return docs.startsWith("/") ? `https://eve.dev${docs}` : docs;+}+function summarizeDetails(values: readonly string[], limit = 3): string {const visible = values.slice(0, limit);const remaining = values.length - visible.length;return remaining > 0 ? `${visible.join(", ")} … (+${remaining} more)` : visible.join(", ");}+function environmentVariables(manifest: Record<string, unknown>): string[] {+ const envVars = manifest.envVars;+ return typeof envVars === "object" && envVars !== null && !Array.isArray(envVars)+ ? Object.keys(envVars)+ : [];+}+function itemDetails(item: RegistryCatalogItem,manifest: Record<string, unknown>,@@ -180,10 +202,9 @@ function itemDetails(];if (dependencies.length > 0)details.push({ label: "Packages", value: summarizeDetails(dependencies) });- const envVars = manifest.envVars;- if (typeof envVars === "object" && envVars !== null && !Array.isArray(envVars)) {- const names = Object.keys(envVars);- if (names.length > 0) details.push({ label: "Environment", value: summarizeDetails(names) });+ const environment = environmentVariables(manifest);+ if (environment.length > 0) {+ details.push({ label: "Environment", value: summarizeDetails(environment) });}const files = Array.isArray(manifest.files) ? manifest.files : [];const targets = files.flatMap((file) => {@@ -206,6 +227,8 @@ async function inspectItem(| {kind: "added";output: readonly string[];+ documentation?: string;+ environment?: readonly string[];setup?: Awaited<ReturnType<RegistryFlowDeps["installRegistryItem"]>>["setup"];}| { kind: "back" }@@ -241,7 +264,12 @@ async function inspectItem(signal,});const result = await (prompter.withExclusiveTerminal?.(install) ?? install());- return { kind: "added", ...result };+ return {+ kind: "added",+ documentation: documentationLink(manifest),+ environment: environmentVariables(manifest),+ ...result,+ };} finally {spinner?.stop();}@@ -288,7 +316,14 @@ async function offerItem(input.signal,);if (inspected.kind !== "added") return undefined;- session.add(item.address, itemLabel(item), inspected.output, inspected.setup);+ const output = [...inspected.output];+ if (inspected.environment !== undefined && inspected.environment.length > 0) {+ output.push(`Environment: ${inspected.environment.join(", ")}`);+ }+ if (inspected.documentation !== undefined) {+ output.push(`Setup: ${inspected.documentation}`);+ }+ session.add(item.address, itemLabel(item), output, inspected.setup);const next = await session.continueAfterInstall({appRoot: input.appRoot,prompter: input.prompter,