Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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 availability
To expose a declared subagent only for certain sessions or turns, export
diff --git a/packages/eve/extension-contracts/compatibility/subagent/v12.ts b/packages/eve/extension-contracts/compatibility/subagent/v12.ts
new file mode 100644
index 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.ts
index 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.json
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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,