Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.tsx
index 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 ? (
<Suspense
fallback={
diff --git a/apps/docs/lib/integrations/data.ts b/apps/docs/lib/integrations/data.ts
index 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.json
index 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.ts
index 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.mdx
index 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.ts
index 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.ts
index 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,