The Open Framework for Building Agents
fix(eve): skip skill announcements on subagent events (#3670)
Ruiebab950ccae4
diff --git a/.changeset/fix-subagent-dynamic-skill-events.md b/.changeset/fix-subagent-dynamic-skill-events.mdnew file mode 100644index 000000000..8dc8ca1d5--- /dev/null+++ b/.changeset/fix-subagent-dynamic-skill-events.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Fix subagent delegation failing with `Context key "eve.sandbox" is not set` when the parent has dynamic skills. Skill announcements are rebuilt at model preparation boundaries, so subagent notifications no longer require sandbox access.diff --git a/docs/skills.mdx b/docs/skills.mdxindex 8130e0b7a..a13355faf 100644--- a/docs/skills.mdx+++ b/docs/skills.mdx@@ -91,6 +91,8 @@ The handle exposes the skill's `name` and `file(relativePath)`; file content isTo serve a different skill per principal, tenant, or channel (the caller's own team playbook, say), wrap `defineSkill` in a `defineDynamic` resolver keyed on `ctx.session.auth`. See [Dynamic capabilities](./guides/dynamic-capabilities).+Subagent lifecycle events do not re-run skill resolvers. The parent's resolved dynamic skills remain available when it resumes after delegation.+## What to read next- [Connections](./connections): add tools from external MCP and OpenAPI serversdiff --git a/e2e/fixtures/agent-workflow-tools/agent/agent.ts b/e2e/fixtures/agent-workflow-tools/agent/agent.tsindex 41e189991..3ddc64142 100644--- a/e2e/fixtures/agent-workflow-tools/agent/agent.ts+++ b/e2e/fixtures/agent-workflow-tools/agent/agent.ts@@ -9,11 +9,21 @@ import { mockModel, type MockModelRequest, type MockModelResponse } from "eve/evfunction respond(request: MockModelRequest): MockModelResponse | string {const hookScenario = request.userMessages.find((entry) => entry.includes("SUBAGENT-HOOKS:"));if (hookScenario !== undefined) {+ const auditing = request.lastUserMessage?.includes("SUBAGENT-HOOKS:AUDIT");+ const skillCallId = auditing ? "audit-policy" : "initial-policy";+ if (!request.toolResults.some((entry) => entry.id === skillCallId)) {+ return {+ toolCalls: [{ id: skillCallId, name: "load_skill", input: { skill: "delegation-policy" } }],+ };+ }const mode = /SUBAGENT-HOOKS:(direct|waiting|background)/u.exec(hookScenario)?.[1];- if (request.lastUserMessage?.includes("SUBAGENT-HOOKS:AUDIT")) {- const audit = request.toolResults.find((entry) => entry.name === "read_subagent_hooks");+ if (auditing) {+ const auditTool = request.lastUserMessage?.includes("DYNAMIC-SKILL-CONTEXT")+ ? "read_dynamic_skill_context"+ : "read_subagent_hooks";+ const audit = request.toolResults.find((entry) => entry.name === auditTool);return audit === undefined- ? { toolCalls: [{ name: "read_subagent_hooks", input: {} }] }+ ? { toolCalls: [{ name: auditTool, input: {} }] }: JSON.stringify(audit.output);}const tool =diff --git a/e2e/fixtures/agent-workflow-tools/agent/channels/skill-context.ts b/e2e/fixtures/agent-workflow-tools/agent/channels/skill-context.tsnew file mode 100644index 000000000..1acd909fd--- /dev/null+++ b/e2e/fixtures/agent-workflow-tools/agent/channels/skill-context.ts@@ -0,0 +1,38 @@+import { defineChannel, POST } from "eve/channels";+import { z } from "zod";++const requestBody = z.strictObject({+ threadId: z.string().min(1).max(100),+ message: z.string().min(1).max(1_000),+ actor: z.enum(["alice", "bob"]),+});++export default defineChannel({+ state: { topic: "delegated-report", labels: ["context-contract"] },+ metadata: (state) => ({ topic: state.topic, labels: state.labels }),+ audience: () => "private",+ routes: [+ POST("/skill-context/send", async (request, { from }) => {+ const { threadId, message, actor } = requestBody.parse(await request.json());+ const session = await from(threadId).send(message, {+ auth: {+ principalId: actor === "alice" ? "workflow-e2e-user" : "workflow-e2e-reviewer",+ principalType: "user",+ authenticator: "e2e-fixture",+ issuer: "context-fixture",+ subject: actor,+ attributes: { actor, groups: ["reports", "reviewers"] },+ },+ });+ return Response.json({+ sessionId: session.id,+ environment:+ process.env.EVE_DEV === "1" || process.env.VERCEL_ENV === "development"+ ? "development"+ : process.env.VERCEL_ENV === "preview"+ ? "preview"+ : "production",+ });+ }),+ ],+});diff --git a/e2e/fixtures/agent-workflow-tools/agent/skills/context-contract.ts b/e2e/fixtures/agent-workflow-tools/agent/skills/context-contract.tsnew file mode 100644index 000000000..f8e9d1835--- /dev/null+++ b/e2e/fixtures/agent-workflow-tools/agent/skills/context-contract.ts@@ -0,0 +1,17 @@+import { defineDynamic, defineSkill, type DynamicResolveContext } from "eve/skills";+import { recordDynamicSkillContext } from "../../dynamic-skill-context-audit";++function resolve(event: "session.started" | "turn.started", ctx: DynamicResolveContext) {+ recordDynamicSkillContext(event, ctx);+ return defineSkill({+ description: "Policy for auditing dynamic skill context.",+ markdown: "Read the recorded resolver context when asked to audit it.",+ });+}++export default defineDynamic({+ events: {+ "session.started": (_event, ctx) => resolve("session.started", ctx),+ "turn.started": (_event, ctx) => resolve("turn.started", ctx),+ },+});diff --git a/e2e/fixtures/agent-workflow-tools/agent/skills/delegation-policy.ts b/e2e/fixtures/agent-workflow-tools/agent/skills/delegation-policy.tsnew file mode 100644index 000000000..1dd3e30b9--- /dev/null+++ b/e2e/fixtures/agent-workflow-tools/agent/skills/delegation-policy.ts@@ -0,0 +1,11 @@+import { defineDynamic, defineSkill } from "eve/skills";++export default defineDynamic({+ events: {+ "session.started": () =>+ defineSkill({+ description: "Policy for auditing delegated reports.",+ markdown: "DELEGATION-POLICY: preserve the child's exact report in the parent response.",+ }),+ },+});diff --git a/e2e/fixtures/agent-workflow-tools/agent/tools/read_dynamic_skill_context.ts b/e2e/fixtures/agent-workflow-tools/agent/tools/read_dynamic_skill_context.tsnew file mode 100644index 000000000..56e54ac2a--- /dev/null+++ b/e2e/fixtures/agent-workflow-tools/agent/tools/read_dynamic_skill_context.ts@@ -0,0 +1,9 @@+import { defineTool } from "eve/tools";+import { z } from "zod";+import { dynamicSkillContextAudit } from "../../dynamic-skill-context-audit";++export default defineTool({+ description: "Read the dynamic skill resolver's durable context observations.",+ inputSchema: z.strictObject({}),+ execute: () => dynamicSkillContextAudit.get(),+});diff --git a/e2e/fixtures/agent-workflow-tools/dynamic-skill-context-audit.ts b/e2e/fixtures/agent-workflow-tools/dynamic-skill-context-audit.tsnew file mode 100644index 000000000..6062387f4--- /dev/null+++ b/e2e/fixtures/agent-workflow-tools/dynamic-skill-context-audit.ts@@ -0,0 +1,40 @@+import { defineState } from "eve/context";+import type { DynamicResolveContext } from "eve/skills";++function snapshot(ctx: DynamicResolveContext) {+ return {+ abortSignal: ctx.abortSignal === undefined ? null : { aborted: ctx.abortSignal.aborted },+ model: ctx.model,+ session: {+ id: ctx.session.id,+ auth: ctx.session.auth,+ } satisfies Record<keyof DynamicResolveContext["session"], unknown>,+ channel: {+ kind: ctx.channel.kind ?? null,+ continuationToken: ctx.channel.continuationToken ?? null,+ metadata: ctx.channel.metadata ?? null,+ } satisfies Record<keyof DynamicResolveContext["channel"], unknown>,+ conversation: ctx.conversation ?? null,+ messages: ctx.messages,+ } satisfies Record<keyof DynamicResolveContext, unknown>;+}++export interface DynamicSkillContextObservation {+ readonly event: "session.started" | "turn.started";+ readonly context: ReturnType<typeof snapshot>;+}++export const dynamicSkillContextAudit = defineState<DynamicSkillContextObservation[]>(+ "workflow-fixture.dynamic-skill-context-audit",+ () => [],+);++export function recordDynamicSkillContext(+ event: DynamicSkillContextObservation["event"],+ ctx: DynamicResolveContext,+): void {+ dynamicSkillContextAudit.update((observations) => [+ ...observations,+ { event, context: snapshot(ctx) },+ ]);+}diff --git a/e2e/fixtures/agent-workflow-tools/evals/dynamic-skill-context.eval.ts b/e2e/fixtures/agent-workflow-tools/evals/dynamic-skill-context.eval.tsnew file mode 100644index 000000000..3c54278e9--- /dev/null+++ b/e2e/fixtures/agent-workflow-tools/evals/dynamic-skill-context.eval.ts@@ -0,0 +1,156 @@+import { defineEval, type EveEvalTargetHandle } from "eve/evals";+import { equals } from "eve/evals/expect";+import type { DynamicSkillContextObservation } from "../dynamic-skill-context-audit";++async function send(+ target: EveEvalTargetHandle,+ threadId: string,+ actor: "alice" | "bob",+ message: string,+): Promise<{ sessionId: string; environment: "development" | "preview" | "production" }> {+ const response = await target.fetch("/skill-context/send", {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify({ threadId, actor, message }),+ });+ if (!response.ok) throw new Error(`Skill context channel returned ${response.status}.`);+ return await response.json();+}++function expectedAuth(actor: "alice" | "bob") {+ return {+ principalId: actor === "alice" ? "workflow-e2e-user" : "workflow-e2e-reviewer",+ principalType: "user",+ authenticator: "e2e-fixture",+ issuer: "context-fixture",+ subject: actor,+ attributes: { actor, groups: ["reports", "reviewers"] },+ };+}++export default (["direct", "waiting", "background"] as const).map((mode) =>+ defineEval({+ description: `${mode} delegation preserves every dynamic-skill resolver context field across session start and later turns.`,+ async test(t) {+ const threadId = crypto.randomUUID();+ const firstMessage = `Alice asks Bob to review a report. SUBAGENT-HOOKS:${mode}`;+ const followUp =+ "Bob reviews Alice's completed report and the resolver context. SUBAGENT-HOOKS:AUDIT DYNAMIC-SKILL-CONTEXT";+ const started = await send(t.target, threadId, "alice", firstMessage);+ const initial = await t.target.watchTurn(started.sessionId).result();+ initial.expectOk();+ initial.calledTool("load_skill", { count: 1, status: "completed" });+ const completed =+ mode === "waiting"+ ? initial+ : await t.target+ .watchTurn(started.sessionId, { startIndex: initial.session.state.streamIndex })+ .result();+ completed.expectOk();+ const marker =+ mode === "direct"+ ? "Alice's hook audit"+ : `hook-audit:${mode === "waiting" ? "blocking" : "background"}`;+ const completion = [...initial.events, ...completed.events].find(+ (event) => event.type === "subagent.completed",+ );+ if (completion?.type !== "subagent.completed")+ throw new Error("The delegated child's completion event is missing.");+ const childOutput = completion.data.output;+ t.check(childOutput.startsWith("WORKFLOW-CHILD:"), equals(true)).label(+ "child returned its report",+ );+ t.check(childOutput.includes(marker), equals(true)).label("child report includes its task");+ completed.messageIncludes(childOutput);++ const startIndex = completed.session.state.streamIndex;+ const resumed = await send(t.target, threadId, "bob", followUp);+ t.check(resumed.sessionId, equals(started.sessionId)).label(+ "same parent session after delegation",+ );+ const audit = await t.target.watchTurn(resumed.sessionId, { startIndex }).result();+ audit.expectOk();+ audit.calledTool("load_skill", { count: 1, status: "completed" });+ audit.calledTool("read_dynamic_skill_context", { count: 1, status: "completed" });+ const output = audit.toolCalls.find(+ (call) => call.name === "read_dynamic_skill_context",+ )?.output;+ if (!Array.isArray(output))+ throw new Error("Dynamic skill resolver observations are missing.");+ const observations = output as DynamicSkillContextObservation[];+ t.check(+ observations.map((entry) => entry.event),+ equals([+ "session.started",+ "turn.started",+ ...(mode === "waiting" ? [] : ["turn.started"]),+ "turn.started",+ ]),+ ).label("resolver runs once at session start and at every parent turn boundary");++ for (const [index, { context, event }] of observations.entries()) {+ const last = index === observations.length - 1;+ const label = `${event}[${index}]`;+ const expected: Omit<typeof context, "messages"> = {+ abortSignal: null,+ model: { id: "eve-mock/model" },+ session: {+ id: started.sessionId,+ auth: {+ current: expectedAuth(last ? "bob" : "alice"),+ initiator: expectedAuth("alice"),+ },+ },+ channel: {+ kind: "channel:skill-context",+ continuationToken: `skill-context:${threadId}`,+ metadata: { topic: "delegated-report", labels: ["context-contract"] },+ },+ conversation: {+ audience: "private",+ channel: { kind: "channel:skill-context", name: "skill-context" },+ mode: "conversation",+ environment: started.environment,+ principalType: "user",+ },+ };+ const { messages, ...actual } = context;+ for (const key of Object.keys(expected) as (keyof typeof expected)[]) {+ t.check(actual[key], equals(expected[key])).label(`${label}: ctx.${key}`);+ }+ if (event === "session.started") {+ t.check(messages, equals([])).label(`${label}: ctx.messages precedes the first turn`);+ continue;+ }+ const userMessages = messages.filter((message) => message.role === "user");+ t.check(+ userMessages.some((message) => message.content === firstMessage),+ equals(true),+ ).label(`${label}: ctx.messages contains the original request`);+ t.check(+ userMessages.some((message) => message.content === followUp),+ equals(last),+ ).label(`${label}: ctx.messages includes the follow-up only after delivery`);+ if (last) {+ const replies = messages+ .filter((message) => message.role === "assistant")+ .map((message) =>+ typeof message.content === "string"+ ? message.content+ : message.content+ .filter((part) => part.type === "text")+ .map((part) => part.text)+ .join(""),+ );+ t.check(+ replies.some((reply) => reply.includes(childOutput)),+ equals(true),+ ).label(`${label}: ctx.messages retains the delivered child result`);+ }+ }+ t.notEvent("session.failed");+ t.noFailedActions();+ t.succeeded();+ },+ }),+);diff --git a/e2e/fixtures/agent-workflow-tools/evals/subagent-hook-context.eval.ts b/e2e/fixtures/agent-workflow-tools/evals/subagent-hook-context.eval.tsindex f0e8907b7..2b10b6455 100644--- a/e2e/fixtures/agent-workflow-tools/evals/subagent-hook-context.eval.ts+++ b/e2e/fixtures/agent-workflow-tools/evals/subagent-hook-context.eval.ts@@ -3,12 +3,13 @@ import type { SubagentHookObservation } from "../subagent-hook-audit";export default (["direct", "waiting", "background"] as const).map((mode) =>defineEval({- description: `${mode} subagent delegation delivers typed and wildcard hooks with the parent session context.`,+ description: `${mode} subagent delegation preserves dynamic skills and delivers hooks with the parent session context.`,async test(t) {const initial = await t.send(`Alice asks Bob to review a short report and return his result. SUBAGENT-HOOKS:${mode}`,);initial.expectOk();+ initial.calledTool("load_skill", { count: 1, status: "completed" });const marker =mode === "direct"? "Alice's hook audit"@@ -26,6 +27,14 @@ export default (["direct", "waiting", "background"] as const).map((mode) =>"Alice reviews the recorded hook observations for Bob's completed report. SUBAGENT-HOOKS:AUDIT",);audit.expectOk();+ audit.calledTool("load_skill", { count: 1, status: "completed" });+ t.eventsSatisfy("the parent's dynamic skill remains loadable after delegation", () =>+ [initial, audit].every((turn) =>+ String(turn.toolCalls.find((call) => call.name === "load_skill")?.output).includes(+ "DELEGATION-POLICY:",+ ),+ ),+ );audit.calledTool("read_subagent_hooks", { count: 1, status: "completed" });const observations = audit.toolCalls.find((call) => call.name === "read_subagent_hooks",diff --git a/packages/eve/src/context/dynamic-skill-lifecycle.test.ts b/packages/eve/src/context/dynamic-skill-lifecycle.test.tsindex 6d2f019ae..dcf83268e 100644--- a/packages/eve/src/context/dynamic-skill-lifecycle.test.ts+++ b/packages/eve/src/context/dynamic-skill-lifecycle.test.ts@@ -1,4 +1,4 @@-import { describe, expect, it } from "vitest";+import { describe, expect, it, vi } from "vitest";import { ContextContainer } from "#context/container.js";import {@@ -47,7 +47,7 @@ function createCtx(authoredSkillNames: readonly string[] = []) {});ctx.set(StaticModelReferenceKey, { id: "openai/gpt-5.5" });ctx.set(SessionIdKey, "test-session");- ctx.set(SandboxKey, sandbox.access);+ ctx.setVirtualContext(SandboxKey, sandbox.access);ctx.set(BundleKey, createMockBundle(authoredSkillNames));return { ctx, sandbox };}@@ -87,6 +87,51 @@ function makeSkill(description: string, markdown = description): SkillPackageDef}describe("dispatchDynamicSkillEvent", () => {+ it.each(["subagent.called", "subagent.completed", "turn.completed"] as const)(+ "does not access the sandbox to rebuild announcements on %s",+ async (type) => {+ const ctx = new ContextContainer();+ const manifest = { policy: [{ name: "policy", description: "Tenant policy" }] };+ ctx.set(DynamicSkillManifestKey, manifest);++ await dispatchDynamicSkillEvent({+ ctx,+ event: { type, data: {} } as UnstampedMessageStreamEvent,+ messages: [],+ resolvers: [],+ });++ expect(ctx.get(DynamicSkillManifestKey)).toEqual(manifest);+ expect(ctx.has(PendingSkillAnnouncementKey)).toBe(false);+ },+ );++ it("restores the skill announcement at the next model step without resolving skills again", async () => {+ const { ctx, sandbox } = createCtx();+ const handler = vi.fn(() => makeSkill("Tenant policy"));+ const resolver = createResolver("policy", handler);+ await dispatchDynamicSkillEvent({+ ctx,+ event: makeEvent(),+ messages: [],+ resolvers: [resolver],+ });+ const announcement = ctx.get(PendingSkillAnnouncementKey);+ expect(announcement).toContain("policy: Tenant policy");+ ctx.clearVirtualContext();+ ctx.setVirtualContext(SandboxKey, sandbox.access);++ await dispatchDynamicSkillEvent({+ ctx,+ event: { type: "step.started", data: {} } as UnstampedMessageStreamEvent,+ messages: [],+ resolvers: [resolver],+ });++ expect(ctx.get(PendingSkillAnnouncementKey)).toBe(announcement);+ expect(handler).toHaveBeenCalledOnce();+ });+it("announces when all dynamic skills are withdrawn", async () => {const { ctx, sandbox } = createCtx();let enabled = true;diff --git a/packages/eve/src/context/dynamic-skill-lifecycle.ts b/packages/eve/src/context/dynamic-skill-lifecycle.tsindex 58c46ac2d..b005fb800 100644--- a/packages/eve/src/context/dynamic-skill-lifecycle.ts+++ b/packages/eve/src/context/dynamic-skill-lifecycle.ts@@ -114,6 +114,10 @@ export async function dispatchDynamicSkillEvent(input: {}): Promise<void> {const { ctx, resolvers, event, messages } = input;+ // Subagent event steps do not initialize sandbox access.+ // Rebuild announcements only at boundaries that prepare model context.+ if (!ALLOWED_DYNAMIC_SKILL_EVENTS.has(event.type) && event.type !== "step.started") return;+// Build phase: rebuild announcement from durable manifest when the// virtual key is empty (step boundary crossed). Sandbox files persist;// only the announcement needs rebuilding.diff --git a/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts b/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.tsindex 1d9a2207c..c1b404b26 100644--- a/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts+++ b/packages/eve/src/execution/tools/subagent/emit-event-step.integration.test.ts@@ -1,7 +1,14 @@import { beforeEach, expect, it, vi } from "vitest";import { ContextContainer, loadContext } from "#context/container.js";-import { AuthKey, SessionIdKey, SessionKey, SessionTitleKey } from "#context/keys.js";+import {+ AuthKey,+ DynamicSkillManifestKey,+ SandboxKey,+ SessionIdKey,+ SessionKey,+ SessionTitleKey,+} from "#context/keys.js";import { deserializeContext, serializeContext } from "#context/serialize.js";import { emitSubagentEventStep } from "#execution/tools/subagent/emit-event-step.js";import { createTestSessionState } from "#internal/testing/session-state.js";@@ -55,8 +62,12 @@ it.each(const ctx = new ContextContainer();ctx.set(SessionIdKey, "parent");ctx.set(AuthKey, null);+ ctx.set(DynamicSkillManifestKey, {+ policy: [{ name: "policy", description: "Parent delegation policy" }],+ });// SessionKey is virtual: a production deserializer cannot restore it.expect(ctx.has(SessionKey)).toBe(false);+ expect(ctx.has(SandboxKey)).toBe(false);ctx.set(ChannelKey, {kind: "test",state: {},@@ -120,6 +131,9 @@ it.each(const result = await emitted;expect(result.serializedContext[SessionTitleKey.name]).toBe("Research event received");expect(result.serializedContext[SessionKey.name]).toBeUndefined();+ expect(result.serializedContext[DynamicSkillManifestKey.name]).toEqual(+ ctx.require(DynamicSkillManifestKey),+ );expect(ctx.require(ChannelKey).state).toEqual({ delivered: true });expect(calls).toEqual(["adapter",