The Open Framework for Building Agents
feat(eve): extensions - support channels (#2097)
Andrew Barba89043928091b
diff --git a/.changeset/calm-channels-compose.md b/.changeset/calm-channels-compose.mdnew file mode 100644index 000000000..eb25c3a15--- /dev/null+++ b/.changeset/calm-channels-compose.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Extensions can now contribute channels. Mounted channel IDs receive the extension namespace while their authored route paths remain unchanged.diff --git a/docs/channels/custom.mdx b/docs/channels/custom.mdxindex fa8b644e6..e5c2bc2c1 100644--- a/docs/channels/custom.mdx+++ b/docs/channels/custom.mdx@@ -7,7 +7,7 @@ When eve doesn't ship a channel for your surface, you build one. Custom channels## File location and identity-Custom channels live in `agent/channels/` at the root agent. Local subagents do not declare channels today.+Custom channels live in `agent/channels/` at the root agent or in an [extension](../extensions) mounted there. Local subagents do not declare channels today.The channel file stem becomes the channel id, so `agent/channels/internal-webhook.ts` is addressed as `internal-webhook`. Export the channel definition as the module's default export.diff --git a/docs/channels/overview.mdx b/docs/channels/overview.mdxindex efd34138d..3a0e11091 100644--- a/docs/channels/overview.mdx+++ b/docs/channels/overview.mdx@@ -36,7 +36,7 @@ Each channel has its own provider terms, data flow, auth model, and user-consent## Where channels live-Channel files live under `agent/channels/` in the root agent. The file stem is the channel id: `agent/channels/intake.ts` is addressed as `intake`. Export the channel as the module's default export. Local subagents do not declare channels.+Channel files live under `agent/channels/` in the root agent or come from an [extension](../extensions) mounted there. The file stem is the channel id: `agent/channels/intake.ts` is addressed as `intake`. An extension mount prefixes its contributed channel IDs but does not change their route paths. Local subagents do not declare channels.```textagent/diff --git a/docs/extensions.md b/docs/extensions.mdindex bcb9b39fa..ba9d80eb9 100644--- a/docs/extensions.md+++ b/docs/extensions.md@@ -3,7 +3,7 @@ title: "Extensions"description: "Package reusable eve capabilities and mount them from npm or a monorepo workspace."----Extensions package eve tools, connections, skills, instruction fragments, and hooks. An author builds an extension package; each agent that uses it declares the package as a dependency and mounts it. The package can be published to a package registry or kept private inside a monorepo workspace.+Extensions package eve tools, channels, connections, skills, instruction fragments, and hooks. An author builds an extension package; each agent that uses it declares the package as a dependency and mounts it. The package can be published to a package registry or kept private inside a monorepo workspace.Ready-made extensions can also be distributed through an eve integration registry. See [Add Integrations](./install-integrations) to discover and add one with `eve add`; this page explains how extension packages are authored, mounted, configured, and overridden.@@ -29,6 +29,7 @@ An extension uses the same file conventions as an agent for its contributions:extension/extension.tstools/search.ts+ channels/webhook.tsconnections/api.tsskills/triage/SKILL.mdinstructions.md@@ -38,7 +39,7 @@ An extension uses the same file conventions as an agent for its contributions:Each listed slot accepts the same authored forms as its agent counterpart. Static and dynamic tools, skills, and instructions all work in an extension: `extension/instructions.ts` is as valid as `extension/instructions.md`, and `extension/tools/` can contain `defineDynamic(...)`.-Names come from paths, so call the tool `search`, not `crm_search`; the consumer's mount adds the `crm__` prefix. Keep shared code in `extension/lib/`.+Names come from paths, so call the tool `search`, not `crm_search`; the consumer's mount adds the `crm__` prefix. The same prefix applies to channel IDs, while channel route paths stay unchanged. Keep shared code in `extension/lib/`.Keep agent configuration, sandboxes, schedules, and nested extensions in the consumer's agent.@@ -168,7 +169,7 @@ export default crm({ apiKey: process.env.CRM_API_KEY! });Set `CRM_API_KEY` in the consumer's environment, such as `.env.local` for local development.-The mount adds `crm__` to named contributions: `tools/search.ts` becomes `crm__search`, and `connections/api.ts` becomes `crm__api`.+The mount adds `crm__` to named contributions: `tools/search.ts` becomes `crm__search`, `channels/webhook.ts` becomes `crm__webhook`, and `connections/api.ts` becomes `crm__api`. A channel keeps the route paths declared in its `defineChannel(...)` definition.For an extension with no configuration, mount its default export directly:@@ -274,7 +275,7 @@ import crm from "@acme/crm";export default crm({ apiKey: process.env.CRM_API_KEY! });```-A same-named consumer tool, connection, or skill wins. To adjust an extension tool, import it from the package's `./tools` export and define it again:+A same-named consumer channel, tool, connection, or skill wins. To adjust an extension tool, import it from the package's `./tools` export and define it again:```ts title="agent/extensions/crm/tools/search.ts"import { search } from "@acme/crm/tools";@@ -329,4 +330,5 @@ At build time, eve checks the extension's generated capability metadata. If the- [Instructions](/docs/instructions): static and TypeScript instructions- [Skills](/docs/skills): package procedures and supporting files- [Connections](/docs/connections): integrate external services+- [Channels](/docs/channels/overview): receive messages and expose routes- [Hooks](/docs/guides/hooks): observe agent eventsdiff --git a/packages/eve/extension-contracts/entrypoints/channel.ts b/packages/eve/extension-contracts/entrypoints/channel.tsnew file mode 100644index 000000000..dd9a5e823--- /dev/null+++ b/packages/eve/extension-contracts/entrypoints/channel.ts@@ -0,0 +1,11 @@+export {+ DELETE,+ GET,+ PATCH,+ POST,+ PUT,+ WS,+ createWebSocketUpgradeServer,+ defineChannel,+ isChannel,+} from "../../src/public/channels/index.ts";diff --git a/packages/eve/extension-contracts/reports/channel/v1.json b/packages/eve/extension-contracts/reports/channel/v1.jsonnew file mode 100644index 000000000..5a4074a3c--- /dev/null+++ b/packages/eve/extension-contracts/reports/channel/v1.json@@ -0,0 +1,17 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "channel",+ "epoch": 1,+ "sha256": "f33b228efb97796242fdeea0d89ab9f6806e49f94fd61831c5bdbfcfc9991fb6",+ "exports": [+ "DELETE",+ "GET",+ "PATCH",+ "POST",+ "PUT",+ "WS",+ "createWebSocketUpgradeServer",+ "defineChannel",+ "isChannel"+ ]+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex 6ebebf389..99e621fab 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -27,6 +27,7 @@ const EXTENSION_CAPABILITY_CONTRACTS = {supported: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17],dropped: {},},+ channel: { current: 1, supported: [1], dropped: {} },connection: { current: 5, supported: [1, 2, 3, 4, 5], dropped: {} },hook: {current: 13,diff --git a/packages/eve/src/compiler/normalize-extension.test.ts b/packages/eve/src/compiler/normalize-extension.test.tsindex 051645966..423132535 100644--- a/packages/eve/src/compiler/normalize-extension.test.ts+++ b/packages/eve/src/compiler/normalize-extension.test.ts@@ -12,6 +12,7 @@ function contributions(overrides: Partial<CompiledExtensionContributions>,): CompiledExtensionContributions {return {+ channels: [],tools: [],dynamicTools: [],hooks: [],@@ -27,12 +28,20 @@ function contributions(describe("mergeContributions", () => {it("keeps the primary (consumer override) entry when a named contribution collides", () => {const primary = contributions({+ channels: [+ { name: "crm__webhook", logicalPath: "override", method: "GET" },+ { name: "crm__webhook", logicalPath: "override", method: "POST" },+ ] as never,tools: [{ name: "crm__search", logicalPath: "override" }] as never,connections: [{ connectionName: "crm__api", logicalPath: "override" }] as never,skills: [{ name: "crm__lookup", logicalPath: "override" }] as never,dynamicTools: [{ slug: "crm__dynamic", logicalPath: "override" }] as never,});const secondary = contributions({+ channels: [+ { name: "crm__webhook", logicalPath: "extension", method: "POST" },+ { name: "crm__status", logicalPath: "extension", method: "GET" },+ ] as never,tools: [{ name: "crm__search", logicalPath: "extension" },{ name: "crm__list", logicalPath: "extension" },@@ -44,6 +53,11 @@ describe("mergeContributions", () => {const merged = mergeContributions(primary, secondary);+ expect(merged.channels).toEqual([+ { name: "crm__webhook", logicalPath: "override", method: "GET" },+ { name: "crm__webhook", logicalPath: "override", method: "POST" },+ { name: "crm__status", logicalPath: "extension", method: "GET" },+ ]);expect(merged.tools).toEqual([{ name: "crm__search", logicalPath: "override" },{ name: "crm__list", logicalPath: "extension" },diff --git a/packages/eve/src/compiler/normalize-extension.ts b/packages/eve/src/compiler/normalize-extension.tsindex 82d05899c..6bcb7b1fb 100644--- a/packages/eve/src/compiler/normalize-extension.ts+++ b/packages/eve/src/compiler/normalize-extension.ts@@ -2,6 +2,7 @@ import { join as joinPath, relative as relativePath } from "node:path";import type { AgentSourceManifest, ResolvedExtensionMount } from "#discover/manifest.js";import type {+ CompiledChannelEntry,CompiledConnectionDefinition,CompiledDynamicInstructionsDefinition,CompiledDynamicSkillDefinition,@@ -11,6 +12,7 @@ import type {CompiledSkillDefinition,CompiledToolDefinition,} from "#compiler/manifest.js";+import { compileChannelDefinition } from "#compiler/normalize-channel.js";import { compileConnectionDefinition } from "#compiler/normalize-connection.js";import type { ManifestCompileContext } from "#compiler/normalize-helpers.js";import { compileHookEntry } from "#compiler/normalize-hook.js";@@ -23,6 +25,7 @@ import { compileToolEntry } from "#compiler/normalize-tool.js";* already namespaced by the mount and rebased onto the consumer's agent root.*/export interface CompiledExtensionContributions {+ readonly channels: CompiledChannelEntry[];readonly tools: CompiledToolDefinition[];readonly dynamicTools: CompiledDynamicToolDefinition[];readonly hooks: CompiledHookDefinition[];@@ -172,6 +175,27 @@ async function composeManifestContributions(input: {const rebase = (logicalPath: string): string =>relativePath(consumerAgentRoot, joinPath(sourceRoot, logicalPath)).replaceAll("\\", "/");+ const channels = (+ await Promise.all(+ manifest.channels.map((source) => compileChannelDefinition(sourceRoot, source, options)),+ )+ )+ .flat()+ .map((channel): CompiledChannelEntry =>+ channel.kind === "disabled"+ ? {+ ...channel,+ name: `${prefix}${channel.name}`,+ logicalPath: rebase(channel.logicalPath),+ }+ : {+ ...channel,+ name: `${prefix}${channel.name}`,+ sourceId: scopeSourceId(channel.sourceId),+ logicalPath: rebase(channel.logicalPath),+ },+ );+const tools: CompiledToolDefinition[] = [];const dynamicTools: CompiledDynamicToolDefinition[] = [];const disabledToolTargets: DisabledToolTarget[] = [];@@ -279,6 +303,7 @@ async function composeManifestContributions(input: {return {contributions: {+ channels,tools,dynamicTools,hooks,@@ -304,10 +329,11 @@ function describeExtensionSource(/*** Merges two composed contribution sets with earlier-set-wins precedence per- * composed name. Named contributions (tools, connections, skills, dynamic- * tools) dedup by their model-facing identifier so an override shadows the- * extension's same-named entry; unnamed contributions (hooks, dynamic skills,- * dynamic instructions, static instructions) simply concatenate.+ * composed name. Named contributions dedup by their model-facing identifier so+ * an override shadows the extension's same-named entry. Channel entries dedup+ * as a group so every route from the winning channel is preserved. Unnamed+ * contributions (hooks, dynamic skills, dynamic instructions, static+ * instructions) simply concatenate.** Exported for unit testing: passing the consumer overrides as `primary` and* the extension's own contributions as `secondary` yields consumer-wins@@ -317,7 +343,12 @@ export function mergeContributions(primary: CompiledExtensionContributions,secondary: CompiledExtensionContributions,): CompiledExtensionContributions {+ const primaryChannelNames = new Set(primary.channels.map((channel) => channel.name));return {+ channels: [+ ...primary.channels,+ ...secondary.channels.filter((channel) => !primaryChannelNames.has(channel.name)),+ ],tools: dedupeBy([...primary.tools, ...secondary.tools], (tool) => tool.name),dynamicTools: dedupeBy([...primary.dynamicTools, ...secondary.dynamicTools],diff --git a/packages/eve/src/compiler/normalize-manifest.ts b/packages/eve/src/compiler/normalize-manifest.tsindex 9181a3a08..0c85fdb09 100644--- a/packages/eve/src/compiler/normalize-manifest.ts+++ b/packages/eve/src/compiler/normalize-manifest.ts@@ -205,6 +205,7 @@ async function compileAgentResources(consumerAgentRoot: manifest.agentRoot,externalDependencies,});+ compiledChannels.push(...contributions.channels);for (const tool of contributions.tools) {if (!toolNames.has(tool.name)) {toolNames.add(tool.name);diff --git a/packages/eve/src/internal/nitro/host/extension-capability-requirements.ts b/packages/eve/src/internal/nitro/host/extension-capability-requirements.tsindex ed6be0d69..941cc9a4e 100644--- a/packages/eve/src/internal/nitro/host/extension-capability-requirements.ts+++ b/packages/eve/src/internal/nitro/host/extension-capability-requirements.ts@@ -44,6 +44,7 @@ export async function deriveExtensionCapabilityRequirements(input: {if (tools.length > 0) required.add("tool");if (tools.some((entry) => entry.kind === "dynamic-tool")) required.add("dynamicTool");+ if (input.manifest.channels.length > 0) required.add("channel");if (input.manifest.connections.length > 0) required.add("connection");if (input.manifest.hooks.length > 0) required.add("hook");if (skills.length > 0) required.add("skill");diff --git a/packages/eve/src/setup/scaffold/create/extension.ts b/packages/eve/src/setup/scaffold/create/extension.tsindex 3e28bdadd..8d91d419a 100644--- a/packages/eve/src/setup/scaffold/create/extension.ts+++ b/packages/eve/src/setup/scaffold/create/extension.ts@@ -131,9 +131,9 @@ distconst AGENTS_MD_TEMPLATE = `# eve Extension Package-This package is an eve extension — a reusable package of tools, connections,-skills, hooks, and instruction fragments that a consuming agent mounts under-\`agent/extensions/\`.+This package is an eve extension — a reusable package of tools, channels,+connections, skills, hooks, and instruction fragments that a consuming agent+mounts under \`agent/extensions/\`.Before writing code, read the Extensions guide from the installed eve packagedocs. In most installs, those docs are at \`node_modules/eve/docs/extensions.md\`.@@ -145,9 +145,9 @@ unavailable, use https://eve.dev/docs/extensions as a fallback.- Declare the extension in \`extension/extension.ts\` with \`defineExtension\` from\`eve/extension\`. Config is optional; read bound values via the handle's- \`.config\` in tools and hooks.+ \`.config\` in tools, channels, and hooks.- Add contributions under \`extension/\` the same way as in an agent:- \`tools/\`, \`connections/\`, \`skills/\`, \`hooks/\`, and optional instruction+ \`tools/\`, \`channels/\`, \`connections/\`, \`skills/\`, \`hooks/\`, and optional instructionfragments. Names come from file paths; the mount supplies the namespace, soname tools for what they do (\`search\`, not \`crm_search\`).- An extension cannot declare \`agent.ts\`, \`sandbox\`, \`schedules\`, or nesteddiff --git a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.tsindex 961ac5b2a..86a0e726f 100644--- a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts+++ b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts@@ -76,6 +76,16 @@ const EXT_TREE: Readonly<Record<string, string>> = {"});","",].join("\n"),+ "extension/channels/status.ts": [+ 'import { defineChannel, GET } from "eve/channels";',+ 'import extension from "../extension.js";',+ "export default defineChannel({",+ " routes: [",+ ' GET("/crm/status", async () => new Response(extension.config.apiKey)),',+ " ],",+ "});",+ "",+ ].join("\n"),"extension/skills/notes.ts": ['import { defineSkill } from "eve/skills";',"export default defineSkill({",@@ -197,6 +207,9 @@ describe("mounted extension installed under node_modules", () => {expect(Object.keys(extensionFiles)).toContain(`node_modules/${PACKAGE_NAME}/dist/extension/_manifest.json`,);+ expect(+ JSON.parse(extensionFiles[`node_modules/${PACKAGE_NAME}/dist/extension/_manifest.json`]!),+ ).toMatchObject({ requires: { channel: 1 } });const app = await scenarioApp({name: "mounted-extension-installed",installDependencies: true,@@ -232,6 +245,20 @@ describe("mounted extension installed under node_modules", () => {apiKey: "SK-INSTALLED",});+ const status = graph.root.agent.channels.find((entry) => entry.name === "crm__status");+ expect(status).toMatchObject({+ method: "GET",+ sourceId: "ext:crm:channels/status.mjs",+ urlPath: "/crm/status",+ });+ if (status === undefined) throw new Error("Expected the extension channel to resolve.");+ const response = await status.fetch(new Request("https://example.com/crm/status"), {+ params: {},+ requestIp: null,+ waitUntil() {},+ });+ await expect(response.text()).resolves.toBe("sk-installed");+expect(graph.root.agent.skills.map((skill) => skill.name)).toEqual(expect.arrayContaining(["crm__notes", "crm__research", "crm__guide"]),);diff --git a/scripts/extension-contracts/configuration.mjs b/scripts/extension-contracts/configuration.mjsindex add7dd120..2fce514cb 100644--- a/scripts/extension-contracts/configuration.mjs+++ b/scripts/extension-contracts/configuration.mjs@@ -18,6 +18,7 @@ export const COMPATIBILITY_FIXTURE_PLACEHOLDER = "REPLACE_WITH_RETAINED_AUTHORINexport const PUBLIC_SURFACES = [{ path: "src/public/extension/index.ts", capabilities: ["extension", "config"] },+ { path: "src/public/channels/index.ts", capabilities: ["channel"] },{ path: "src/public/tools/index.ts", capabilities: ["tool", "dynamicTool"] },{ path: "src/public/connections/index.ts", capabilities: ["connection"] },{ path: "src/public/hooks/index.ts", capabilities: ["hook"] },