Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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 is
To 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 servers
diff --git a/e2e/fixtures/agent-workflow-tools/agent/agent.ts b/e2e/fixtures/agent-workflow-tools/agent/agent.ts
index 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/ev
function 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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",