Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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.mdx
index 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.
```text
agent/
diff --git a/docs/extensions.md b/docs/extensions.md
index 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.ts
tools/search.ts
+ channels/webhook.ts
connections/api.ts
skills/triage/SKILL.md
instructions.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 events
diff --git a/packages/eve/extension-contracts/entrypoints/channel.ts b/packages/eve/extension-contracts/entrypoints/channel.ts
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 @@ dist
const 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 package
docs. 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 instruction
fragments. Names come from file paths; the mount supplies the namespace, so
name tools for what they do (\`search\`, not \`crm_search\`).
- An extension cannot declare \`agent.ts\`, \`sandbox\`, \`schedules\`, or nested
diff --git a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts
index 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.mjs
index 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_AUTHORIN
export 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"] },