The Open Framework for Building Agents
feat(eve): add name-addressed workspace agents (#3175)
OwenKepharteaf88957253a
diff --git a/.changeset/workspace-agent.md b/.changeset/workspace-agent.mdnew file mode 100644index 000000000..96e04da0a--- /dev/null+++ b/.changeset/workspace-agent.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Add `defineWorkspaceAgent()` for delegating to a workspace peer by name. It selects Vercel routing and OIDC automatically on Vercel, accepts explicit transport overrides elsewhere, and uses the peer agent's description by default.diff --git a/docs/subagents/index.mdx b/docs/subagents/index.mdxindex f70f8949e..e3403dd4f 100644--- a/docs/subagents/index.mdx+++ b/docs/subagents/index.mdx@@ -67,6 +67,37 @@ export default defineAgent({A mounted extension can also contribute declared subagents from `extension/subagents/`. The mount namespace prefixes the subagent visible to the consuming agent node: mounting an extension as `crm` exposes its `reviewer` subagent as `crm__reviewer`. The contributed subagent keeps its own isolated tools, connections, skills, hooks, instructions, sandbox, and nested subagents, and its modules can read configuration from the extension handle. See [Extensions](./extensions#add-a-subagent) for the authoring and override behavior.+### Vercel workspace peers++In a Vercel agent workspace, expose one other workspace member as a remote subagent with `defineWorkspaceAgent`. Create an ordinary file under the caller's `agent/subagents/` directory. Its filename gives the model-visible tool name; `name` identifies the peer under `agents/`.++```ts title="agents/foreman/agent/subagents/research.ts"+import { defineWorkspaceAgent } from "eve";++export default defineWorkspaceAgent({+ name: "research",+});+```++The helper uses the peer's root `defineAgent({ description })` value as the model-visible tool description. Pass `description` to override it for this caller. When `transport` is omitted, eve selects the built-in transport for the runtime environment. Vercel deployments route through the current deployment and authenticate with the caller's Vercel OIDC token. Outside Vercel, provide an explicit transport with `url` and optional `auth` or `headers`:++```ts title="agents/foreman/agent/subagents/research.ts"+import { defineWorkspaceAgent } from "eve";+import { bearer } from "eve/agents/auth";++export default defineWorkspaceAgent({+ name: "research",+ transport: {+ url: () => process.env.RESEARCH_AGENT_URL!,+ auth: bearer(() => process.env.RESEARCH_AGENT_TOKEN!),+ },+});+```++An explicit transport replaces the environment default completely. The receiving peer must still accept the transport's credentials through its channel authentication policy. Set `forwardPrincipal: true` only when the peer trusts the caller to forward user identity, as described in [Remote agents](./guides/remote-agents#forward-the-callers-identity).++Use the peer's directory name under `agents/`. eve requires an exact workspace-member match, so add another declared subagent file for each additional peer. `eve dev` does not provide local workspace routing; configure an explicit transport to target a separately running peer.+### Conditional availabilityTo expose a declared subagent only for certain sessions or turns, exportdiff --git a/packages/eve/extension-contracts/compatibility/subagent/v12.ts b/packages/eve/extension-contracts/compatibility/subagent/v12.tsnew file mode 100644index 000000000..8148f4be2--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/subagent/v12.ts@@ -0,0 +1,12 @@+import { defineAgent } from "#public/index.js";++/** Epoch 12 added workflow retention to authored subagent definitions. */+export default defineAgent({+ description: "Delegate ephemeral research tasks.",+ experimental: {+ workflow: {+ retention: 0,+ },+ },+ model: "anthropic/claude-sonnet-5",+});diff --git a/packages/eve/extension-contracts/entrypoints/subagent.ts b/packages/eve/extension-contracts/entrypoints/subagent.tsindex 91cd73327..5e0a57360 100644--- a/packages/eve/extension-contracts/entrypoints/subagent.ts+++ b/packages/eve/extension-contracts/entrypoints/subagent.ts@@ -8,7 +8,10 @@ export {type DynamicSubagentDefinition,type RemoteAgentDefinition,type RemoteAgentDefinitionInput,+ type WorkspaceAgentDefinition,+ type WorkspaceAgentTransport,defineAgent,defineDynamic,defineRemoteAgent,+ defineWorkspaceAgent,} from "../../src/public/index.ts";diff --git a/packages/eve/extension-contracts/reports/subagent/v13.json b/packages/eve/extension-contracts/reports/subagent/v13.jsonnew file mode 100644index 000000000..83524a7c7--- /dev/null+++ b/packages/eve/extension-contracts/reports/subagent/v13.json@@ -0,0 +1,23 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "subagent",+ "epoch": 13,+ "sha256": "61b87a936e6ec9a287e322e08f55f3dea886ab7275dc89de7f3f7ea26039cec7",+ "exports": [+ "AgentCompactionDefinition",+ "AgentDefinition",+ "AgentModelDefinition",+ "AgentStaticModelDefinition",+ "DefinedAgent",+ "DynamicLocalSubagentDefinition",+ "DynamicSubagentDefinition",+ "RemoteAgentDefinition",+ "RemoteAgentDefinitionInput",+ "WorkspaceAgentDefinition",+ "WorkspaceAgentTransport",+ "defineAgent",+ "defineDynamic",+ "defineRemoteAgent",+ "defineWorkspaceAgent"+ ]+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex dbe7fc787..f918b885c 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -72,8 +72,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},subagent: {- current: 12,- supported: [3, 4, 6, 7, 8, 9, 10, 11, 12],+ current: 13,+ supported: [3, 4, 6, 7, 8, 9, 10, 11, 12, 13],dropped: {1: "Persistent subagent sessions are now the default and the experimental opt-in was removed",2: "Persistent subagent sessions are now the default and the experimental opt-in was removed",diff --git a/packages/eve/src/compiler/normalize-manifest-helpers.ts b/packages/eve/src/compiler/normalize-manifest-helpers.tsindex 60b296070..ee89efb2c 100644--- a/packages/eve/src/compiler/normalize-manifest-helpers.ts+++ b/packages/eve/src/compiler/normalize-manifest-helpers.ts@@ -6,6 +6,7 @@ import type {CompiledAgentDefinition,CompiledExtensionMount,CompiledRemoteAgentNode,+ CompiledSubagentNode,} from "#compiler/manifest.js";import { ROOT_COMPILED_AGENT_NODE_ID } from "#compiler/manifest.js";import type { ModuleSourceRef } from "#shared/source-ref.js";@@ -104,6 +105,17 @@ export function assertUniqueBy<T>(}}+export function withDiagnosticsSummary(+ subagents: readonly CompiledSubagentNode[],+ diagnosticsSummary: import("#discover/diagnostics.js").DiscoverDiagnosticsSummary,+): CompiledSubagentNode[] {+ return subagents.map((subagent) =>+ subagent.configResolver === undefined+ ? { ...subagent, agent: { ...subagent.agent, diagnosticsSummary } }+ : { ...subagent, agent: { ...subagent.agent, diagnosticsSummary } },+ );+}+export function expectSubagentDescription(config: CompiledAgentDefinition,source: LocalSubagentSourceRef,diff --git a/packages/eve/src/compiler/normalize-manifest.ts b/packages/eve/src/compiler/normalize-manifest.tsindex f9507de5f..b7c044299 100644--- a/packages/eve/src/compiler/normalize-manifest.ts+++ b/packages/eve/src/compiler/normalize-manifest.ts@@ -44,6 +44,8 @@ import {loadModuleBackedDefinition,type ManifestCompileContext,} from "#compiler/normalize-helpers.js";+import { resolveWorkspaceSubagentDefinition } from "#compiler/resolve-workspace-subagent.js";+import { workspaceSubagentName } from "#public/definitions/workspace-agent.js";import { compileHookEntry } from "#compiler/normalize-hook.js";import { compileInstructionsEntry } from "#compiler/normalize-instructions.js";import { compileMemoryDefinition, deriveMemorySlot } from "#compiler/normalize-memory.js";@@ -75,6 +77,7 @@ import {expectSubagentDescription,mergeExternalDependencies,collectSelectedSourceIds,+ withDiagnosticsSummary,withExtensionNamespace,} from "#compiler/normalize-manifest-helpers.js";import { summarizeCompilerDiagnostics, type CompilerDiagnostic } from "#compiler/diagnostics.js";@@ -143,17 +146,7 @@ export async function compileAgentManifest(});const diagnosticsSummary = summarizeCompilerDiagnostics(diagnostics);- const subagents: CompiledSubagentNode[] = root.descendants.map((subagent) =>- subagent.configResolver === undefined- ? {- ...subagent,- agent: { ...subagent.agent, diagnosticsSummary },- }- : {- ...subagent,- agent: { ...subagent.agent, diagnosticsSummary },- },- );+ const subagents = withDiagnosticsSummary(root.descendants, diagnosticsSummary);return createCompiledAgentManifest({...root.manifest,diagnosticsSummary,@@ -254,6 +247,16 @@ class AgentGraphCompiler {);if (normalized.kind === "remote") {+ const workspaceName = workspaceSubagentName(phaseOne.selectedConfig.definition);+ const remoteDefinition =+ workspaceName === undefined+ ? normalized+ : await resolveWorkspaceSubagentDefinition({+ definition: normalized,+ name: workspaceName,+ registries: this.registries,+ source,+ });assertRemoteAgentDefinitionHasNoLocalPackageEntries(source);const sourceId = phaseOne.selectedConfig.source.sourceId;phaseOne.evaluation.setBindings({ [sourceId]: phaseOne.selectedConfig.binding });@@ -265,7 +268,7 @@ class AgentGraphCompiler {remoteAgents.push(createCompiledRemoteAgent({binding,- definition: normalized,+ definition: remoteDefinition,nodeId,owner: projected.owner,parentNodeId: input.nodeId,diff --git a/packages/eve/src/compiler/resolve-workspace-subagent.ts b/packages/eve/src/compiler/resolve-workspace-subagent.tsnew file mode 100644index 000000000..8ae2bc38f--- /dev/null+++ b/packages/eve/src/compiler/resolve-workspace-subagent.ts@@ -0,0 +1,65 @@+import { discoverAgent } from "#discover/discover-agent.js";+import type { LocalSubagentSourceRef } from "#discover/manifest.js";+import { findEveProjectContext } from "#internal/project-context.js";+import { normalizeAgentDefinition } from "#internal/authored-definition/core.js";+import { createCompiledBindingNamespaceLoader } from "#compiler/load-binding-namespace.js";+import { loadModuleBackedDefinition } from "#compiler/normalize-helpers.js";+import type { NormalizedSubagentConfig } from "#compiler/normalize-subagent.js";+import type { AgentSourceRegistry } from "#compiler/source-graph.js";++export async function resolveWorkspaceSubagentDefinition(input: {+ readonly definition: Extract<NormalizedSubagentConfig, { readonly kind: "remote" }>;+ readonly name: string;+ readonly registries: readonly AgentSourceRegistry[];+ readonly source: LocalSubagentSourceRef;+}): Promise<Extract<NormalizedSubagentConfig, { readonly kind: "remote" }>> {+ const workspaceContext = await findEveProjectContext(input.source.rootPath);+ if (workspaceContext?.kind !== "workspace-member") {+ throw new Error(+ `Workspace subagent "${input.source.logicalPath}" must be authored by an agent workspace member.`,+ );+ }+ const member = workspaceContext.workspace.members.find(+ (candidate) => candidate.name === input.name,+ );+ if (member === undefined) {+ throw new Error(+ `Workspace subagent "${input.source.logicalPath}" targets unknown workspace member ${JSON.stringify(input.name)}.`,+ );+ }+ if (input.definition.description.trim().length > 0) return input.definition;+ const { resolveDiscoveryProject } = await import("#discover/project.js");+ const project = await resolveDiscoveryProject(member.appRoot);+ const peer = await discoverAgent({ agentRoot: project.agentRoot, appRoot: project.appRoot });+ const configSource = peer.manifest.configModule;+ if (configSource === undefined) {+ throw new Error(`Workspace member ${JSON.stringify(input.name)} has no agent config module.`);+ }+ const binding = {+ backing: {+ externalDependencies: [],+ kind: "filesystem" as const,+ sourcePath: `${project.agentRoot}/${configSource.logicalPath}`,+ },+ logicalPath: configSource.logicalPath,+ owner: { kind: "application" as const },+ };+ const definition = normalizeAgentDefinition(+ await loadModuleBackedDefinition({+ binding,+ kind: "agent config",+ loadNamespace: createCompiledBindingNamespaceLoader({+ bindings: { [configSource.sourceId]: binding },+ registries: input.registries,+ }),+ source: configSource,+ }),+ `Expected workspace member ${JSON.stringify(input.name)} agent config to match the public eve shape.`,+ );+ if (definition.description === undefined || definition.description.trim().length === 0) {+ throw new Error(+ `Workspace member ${JSON.stringify(input.name)} must define a non-empty description.`,+ );+ }+ return { ...input.definition, description: definition.description };+}diff --git a/packages/eve/src/compiler/workspace-agent.scenario.test.ts b/packages/eve/src/compiler/workspace-agent.scenario.test.tsnew file mode 100644index 000000000..7568092cb--- /dev/null+++ b/packages/eve/src/compiler/workspace-agent.scenario.test.ts@@ -0,0 +1,89 @@+import { join } from "node:path";++import { describe, expect, it } from "vitest";++import { compileAgent } from "#compiler/compile-agent.js";+import { useScenarioApp } from "#internal/testing/scenario-app.js";++const rootConfig =+ "export default { model: 'openai/gpt-5.5', modelContextWindowTokens: 200000 };\n";+const peerConfig =+ "export default { description: 'Research product questions.', model: 'openai/gpt-5.5', modelContextWindowTokens: 200000 };\n";++function workspaceFiles(subagent: string) {+ return {+ "agents/research/agent/agent.ts": peerConfig,+ "agents/support/agent/agent.ts": rootConfig,+ "agents/support/agent/instructions.md": "Support users.\n",+ "agents/support/agent/subagents/research.ts": subagent,+ };+}++describe("Vercel workspace subagent compilation", () => {+ const scenarioApp = useScenarioApp();++ it("uses the addressed peer's description by default", async () => {+ const app = await scenarioApp({+ installDependencies: true,+ name: "workspace-subagent-description",+ files: workspaceFiles(+ [+ 'import { defineWorkspaceAgent } from "eve";',+ 'export default defineWorkspaceAgent({ name: "research" });',+ "",+ ].join("\n"),+ ),+ });++ const result = await compileAgent({ startPath: join(app.appRoot, "agents", "support") });+ expect(result.manifest.remoteAgents).toEqual([+ expect.objectContaining({ description: "Research product questions.", name: "research" }),+ ]);+ });++ it("uses an authored description override", async () => {+ const app = await scenarioApp({+ installDependencies: true,+ name: "workspace-subagent-description-override",+ files: workspaceFiles(+ [+ 'import { defineWorkspaceAgent } from "eve";',+ "export default defineWorkspaceAgent({",+ ' description: "Research urgent support escalations.",',+ ' name: "research",',+ "});",+ "",+ ].join("\n"),+ ),+ });++ const result = await compileAgent({ startPath: join(app.appRoot, "agents", "support") });+ expect(result.manifest.remoteAgents).toEqual([+ expect.objectContaining({+ description: "Research urgent support escalations.",+ name: "research",+ }),+ ]);+ });++ it("rejects an unknown peer even with a description override", async () => {+ const app = await scenarioApp({+ installDependencies: true,+ name: "workspace-subagent-unknown-peer",+ files: workspaceFiles(+ [+ 'import { defineWorkspaceAgent } from "eve";',+ "export default defineWorkspaceAgent({",+ ' description: "Research urgent support escalations.",',+ ' name: "missing",',+ "});",+ "",+ ].join("\n"),+ ),+ });++ await expect(+ compileAgent({ startPath: join(app.appRoot, "agents", "support") }),+ ).rejects.toThrow('targets unknown workspace member "missing"');+ });+});diff --git a/packages/eve/src/public/definitions/workspace-agent.test.ts b/packages/eve/src/public/definitions/workspace-agent.test.tsnew file mode 100644index 000000000..a0646971a--- /dev/null+++ b/packages/eve/src/public/definitions/workspace-agent.test.ts@@ -0,0 +1,57 @@+import { afterEach, describe, expect, it, vi } from "vitest";++import { defineWorkspaceAgent } from "./workspace-agent.js";++vi.mock("#compiled/@vercel/oidc/index.js", () => ({+ getVercelOidcToken: vi.fn().mockResolvedValue("oidc-token"),+}));++afterEach(() => vi.unstubAllEnvs());++describe("defineWorkspaceAgent", () => {+ it("selects Vercel transport in a Vercel environment", async () => {+ vi.stubEnv("VERCEL", "1");+ vi.stubEnv("VERCEL_ENV", "preview");+ vi.stubEnv("VERCEL_URL", "preview.example.com");+ const subagent = defineWorkspaceAgent({ name: "research" });++ expect(subagent).toMatchObject({ description: "", kind: "remote", path: "/eve/v1/session" });+ expect(await (subagent.url as () => Promise<string>)()).toBe(+ "https://preview.example.com/research",+ );+ await expect(subagent.auth?.()).resolves.toEqual({+ headers: {+ authorization: "Bearer oidc-token",+ "x-vercel-trusted-oidc-idp-token": "oidc-token",+ },+ });+ });++ it("requires an explicit transport outside Vercel", async () => {+ vi.stubEnv("VERCEL", undefined);+ const subagent = defineWorkspaceAgent({ name: "research" });++ expect(() => (subagent.url as () => string)()).toThrow(+ "No default workspace-agent transport is available",+ );+ });++ it("uses an explicit transport instead of the environment default", async () => {+ vi.stubEnv("VERCEL", undefined);+ const auth = vi.fn(async () => ({ headers: { authorization: "Bearer custom" } }));+ const subagent = defineWorkspaceAgent({+ name: "research",+ transport: {+ auth,+ headers: { "x-workspace": "custom" },+ url: "https://research.internal",+ },+ });++ expect(subagent).toMatchObject({+ auth,+ headers: { "x-workspace": "custom" },+ url: "https://research.internal",+ });+ });+});diff --git a/packages/eve/src/public/definitions/workspace-agent.ts b/packages/eve/src/public/definitions/workspace-agent.tsnew file mode 100644index 000000000..83eb8a50a--- /dev/null+++ b/packages/eve/src/public/definitions/workspace-agent.ts@@ -0,0 +1,88 @@+import type { StandardJSONSchemaV1 } from "#compiled/@standard-schema/spec/index.js";++import type { HeadersValue } from "#client/types.js";+import { type OutboundAuthFn, vercelOidc } from "#public/agents/auth.js";+import {+ defineRemoteAgent,+ type RemoteAgentDefinition,+ type RemoteAgentUrl,+} from "#public/definitions/remote-agent.js";+import type { JsonObject } from "#shared/json.js";++const WORKSPACE_AGENT_NAME = Symbol.for("eve.workspace-agent.name");++type BrandedWorkspaceSubagent = RemoteAgentDefinition & {+ readonly [WORKSPACE_AGENT_NAME]: string;+};++/** Runtime transport for one workspace peer. */+export interface WorkspaceAgentTransport {+ readonly auth?: OutboundAuthFn;+ readonly headers?: HeadersValue;+ readonly url: RemoteAgentUrl;+}++/** A workspace peer exposed as one remote subagent. */+export interface WorkspaceAgentDefinition {+ /** Overrides the peer agent's description in the parent's tool definition. */+ readonly description?: string;+ readonly forwardPrincipal?: boolean;+ readonly outputSchema?: StandardJSONSchemaV1<unknown, unknown> | JsonObject;+ /** Name of the peer workspace member, such as `research`. */+ readonly name: string;+ /** Overrides environment-aware workspace routing and service authentication. */+ readonly transport?: WorkspaceAgentTransport;+}++/** Defines one workspace peer as a remote subagent. */+export function defineWorkspaceAgent(definition: WorkspaceAgentDefinition): RemoteAgentDefinition {+ const transport = definition.transport ?? defaultWorkspaceAgentTransport(definition.name);+ const remote = defineRemoteAgent({+ auth: transport.auth,+ description: definition.description ?? "",+ forwardPrincipal: definition.forwardPrincipal,+ headers: transport.headers,+ outputSchema: definition.outputSchema,+ url: transport.url,+ }) as BrandedWorkspaceSubagent;+ Object.defineProperty(remote, WORKSPACE_AGENT_NAME, { value: definition.name });+ return remote;+}++export function workspaceSubagentName(value: unknown): string | undefined {+ return isBrandedWorkspaceSubagent(value) ? value[WORKSPACE_AGENT_NAME] : undefined;+}++function isBrandedWorkspaceSubagent(value: unknown): value is BrandedWorkspaceSubagent {+ return typeof value === "object" && value !== null && Reflect.has(value, WORKSPACE_AGENT_NAME);+}++function defaultWorkspaceAgentTransport(name: string): WorkspaceAgentTransport {+ const auth = vercelOidc();+ return {+ auth: async () => {+ requireVercelWorkspaceEnvironment();+ return auth();+ },+ url: () => {+ requireVercelWorkspaceEnvironment();+ const host =+ process.env.VERCEL_ENV === "production"+ ? process.env.VERCEL_PROJECT_PRODUCTION_URL+ : process.env.VERCEL_URL;+ if (host === undefined || host.length === 0) {+ throw new Error(+ "The default workspace-agent transport requires VERCEL_URL, or VERCEL_PROJECT_PRODUCTION_URL in production.",+ );+ }+ return `https://${host}/${name}`;+ },+ };+}++function requireVercelWorkspaceEnvironment(): void {+ if (process.env.VERCEL) return;+ throw new Error(+ "No default workspace-agent transport is available in this environment. Provide transport to defineWorkspaceAgent().",+ );+}diff --git a/packages/eve/src/public/index.ts b/packages/eve/src/public/index.tsindex f1b318c57..7eaefc265 100644--- a/packages/eve/src/public/index.ts+++ b/packages/eve/src/public/index.ts@@ -21,6 +21,11 @@ export {defineDynamic,} from "#public/definitions/agent.js";export type { DynamicResolveContext, DynamicSentinel } from "#dynamic/definition.js";+export {+ defineWorkspaceAgent,+ type WorkspaceAgentDefinition,+ type WorkspaceAgentTransport,+} from "#public/definitions/workspace-agent.js";export {type RemoteAgentDefinition,type RemoteAgentDefinitionInput,