Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): hydrate dynamic session tools on durable continuations (#2209)

Ben Pankow2c01eab36d46
diff --git a/.changeset/refresh-cold-dynamic-approvals.md b/.changeset/refresh-cold-dynamic-approvals.md
new file mode 100644
index 000000000..0e38d37ce
--- /dev/null
+++ b/.changeset/refresh-cold-dynamic-approvals.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Rebuild untransformed session-scoped dynamic tool executors and approval policies on durable continuations so dependency-created tools remain available after replay.
diff --git a/docs/guides/dynamic-capabilities.md b/docs/guides/dynamic-capabilities.md
index 688b148b8..aaf75be8f 100644
--- a/docs/guides/dynamic-capabilities.md
+++ b/docs/guides/dynamic-capabilities.md
@@ -160,9 +160,11 @@ export default defineDynamic({
});
```
-### `execute` must be an inline function
+### Prefer an inline `execute` function
-Write `execute` as an inline function expression, arrow, or method shorthand placed directly as the property value. The bundler transform does not detect `execute: myFn` or `execute: makeFn()`, so those tools work on the first step but do not survive replay (re-running a step after a crash or resume; see [Execution model & durability](../concepts/execution-model-and-durability)). On later steps the transform reconstructs each `execute` from its stored closure variables instead of re-running the resolver, which is why it has to be inline.
+Write `execute` as an inline function expression, arrow, or method shorthand placed directly as the property value. The bundler transform stores the function and its closure variables for durable replay without rerunning the resolver.
+
+The transform does not detect `execute: myFn`, `execute: makeFn()`, or executors created inside an imported dependency. For a `session.started` tool, eve can reconstruct these live functions by rerunning the owning resolver after a durable resume. Keep session resolvers idempotent and avoid unnecessary side effects. A `turn.started` tool still requires an inline executor to survive a fresh runtime.
### Naming
@@ -179,11 +181,13 @@ A dynamic tool or skill whose name matches an **authored** one **overrides** it
### Events
-| Event | Resolver runs | Tools available for |
-| ----------------- | ---------------------- | ------------------------------- |
-| `session.started` | Once per session | Every model call in the session |
-| `turn.started` | Once per turn | Every model call in the turn |
-| `step.started` | Before each model call | That model call |
+| Event | Resolver runs | Tools available for |
+| ----------------- | ------------------------------------------ | ------------------------------- |
+| `session.started` | At session start; sometimes after a pause¹ | Every model call in the session |
+| `turn.started` | Once per turn | Every model call in the turn |
+| `step.started` | Before each model call | That model call |
+
+¹ If a session pauses to wait for approval or other input, eve may run the resolver again when the session continues. Design session resolvers so they can safely run more than once. They do not run before every model call.
### Execution order
diff --git a/packages/eve/src/context/build-dynamic-tools.ts b/packages/eve/src/context/build-dynamic-tools.ts
index 220454c7c..13e04e51a 100644
--- a/packages/eve/src/context/build-dynamic-tools.ts
+++ b/packages/eve/src/context/build-dynamic-tools.ts
@@ -1,6 +1,6 @@
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import type { HarnessToolMap } from "#harness/types.js";
-import type { ContextKey } from "#context/key.js";
+import type { ContextReader } from "#context/key.js";
import {
SessionDynamicToolMetadataKey,
TurnDynamicToolMetadataKey,
@@ -116,12 +116,11 @@ function buildReplayedApproval(
* so they win on name collision (the tool-loop uses `??=` for dedup).
*
* Step tools are live closures (re-resolved every step via
- * `LiveStepToolsKey`). Session/turn tools are replayed from durable
- * metadata via the bundler's registered step functions.
+ * `LiveStepToolsKey`). Session and turn tools replay durable metadata.
*/
export function buildResponseAuthorizationTools(input: {
readonly authoredTools: HarnessToolMap;
- readonly context?: { get<T>(key: ContextKey<T>): T | undefined };
+ readonly context?: ContextReader;
}): HarnessToolMap {
const tools = new Map<string, HarnessToolDefinition>();
for (const tool of input.context === undefined ? [] : buildDynamicTools(input.context)) {
@@ -133,9 +132,7 @@ export function buildResponseAuthorizationTools(input: {
return tools;
}
-export function buildDynamicTools(ctx: {
- get<T>(key: ContextKey<T>): T | undefined;
-}): readonly HarnessToolDefinition[] {
+export function buildDynamicTools(ctx: ContextReader): readonly HarnessToolDefinition[] {
const step = ctx.get(LiveStepToolsKey) ?? [];
const turn = replayTools(ctx.get(TurnDynamicToolMetadataKey) ?? []);
const session = replayTools(ctx.get(SessionDynamicToolMetadataKey) ?? []);
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
index 8b2593953..d5ae4d7d1 100644
--- a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
+++ b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
@@ -18,12 +18,14 @@ vi.mock("#context/build-callback-context.js", () => ({
const {
replayDynamicSessionTools,
dispatchDynamicToolEvent,
+ hydrateDynamicSessionTools,
refreshDynamicSessionToolsForRuntimeRevision,
} = await import("#context/dynamic-tool-lifecycle.js");
const { buildDynamicTools, buildResponseAuthorizationTools } =
await import("#context/build-dynamic-tools.js");
import { ContextContainer } from "#context/container.js";
+import { deserializeContext, serializeContext } from "#context/serialize.js";
import {
LiveStepToolsKey,
SessionIdKey,
@@ -450,9 +452,10 @@ function createResolver(
};
}
-function createCtx(): ContextContainer {
+let contextCounter = 0;
+function createCtx(sessionId = `test-session-${++contextCounter}`): ContextContainer {
const ctx = new ContextContainer();
- ctx.set(SessionIdKey, "test-session");
+ ctx.set(SessionIdKey, sessionId);
return ctx;
}
@@ -483,6 +486,21 @@ const registrySym = Symbol.for("@workflow/core//registeredSteps");
const testRegistry = getOrCreateStepRegistry(registrySym);
let stepCounter = 0;
+function simulateColdStart(ctx: ContextContainer): void {
+ for (const metadata of ctx.get(SessionDynamicToolMetadataKey) ?? []) {
+ if (metadata.executeStepFnName?.startsWith("eve:framework-dynamic:")) {
+ testRegistry.delete(metadata.executeStepFnName);
+ }
+ if (metadata.approvalStepFnName !== undefined) {
+ testRegistry.delete(metadata.approvalStepFnName);
+ }
+ if (metadata.approvalResponseStepFnName !== undefined) {
+ testRegistry.delete(metadata.approvalResponseStepFnName);
+ }
+ }
+ ctx.clearVirtualContext();
+}
+
/**
* Creates a tool entry with bundler-injected step function fields so
* `buildDynamicTools` can replay it from durable metadata.
@@ -565,6 +583,278 @@ describe("dispatchDynamicToolEvent", () => {
expect(handler).toHaveBeenCalledOnce();
});
+ it("reuses registered session callbacks without rerunning the resolver", async () => {
+ let ctx = createCtx();
+ const handler = vi.fn(() => ({ tool: createFrameworkTool("cached live tool") }));
+ const resolver = createResolver("live", ["session.started"], handler);
+ ctx.set(SessionDynamicToolRuntimeRevisionKey, "deployment:dpl_current");
+
+ await dispatchDynamicToolEvent({
+ ctx,
+ resolvers: [resolver],
+ messages: [],
+ event: makeEvent("session.started"),
+ });
+ ctx = await deserializeContext(serializeContext(ctx));
+
+ await hydrateDynamicSessionTools({
+ ctx,
+ resolvers: [resolver],
+ messages: [],
+ event: createSessionStartedEvent(),
+ });
+
+ expect(handler).toHaveBeenCalledOnce();
+ expect(buildDynamicTools(ctx).map((tool) => tool.name)).toEqual(["tool"]);
+ });
+
+ it("rebuilds a missing approval callback after a same-revision cold start", async () => {
+ const ctx = createCtx();
+ const stepId = `test-step-${++stepCounter}`;
+ const stableStepId = `test-step-${++stepCounter}`;
+ testRegistry.set(stepId, () => ({ ok: true }));
+ testRegistry.set(stableStepId, () => ({ ok: true }));
+ let approvalStepFnName: string | undefined;
+ let resolutionCount = 0;
+ const handler = vi.fn(() => {
+ resolutionCount++;
+ const entry = defineTool({
+ description: resolutionCount === 1 ? "approval policy" : "changed approval policy",
+ inputSchema: { type: "object" },
+ approval: () => "not-applicable" as const,
+ execute: async (): Promise<unknown> => ({ ok: true }),
+ });
+ Object.assign(entry, {
+ __executeStepFn: { stepId },
+ __closureVars: {},
+ });
+ return { governed: entry };
+ });
+ const resolver = createResolver("governed", ["session.started"], handler);
+ const stableHandler = vi.fn(() => {
+ const entry = defineTool({
+ description: "stable tool",
+ inputSchema: { type: "object" },
+ execute: async (): Promise<unknown> => ({ ok: true }),
+ });
+ Object.assign(entry, {
+ __executeStepFn: { stepId: stableStepId },
+ __closureVars: {},
+ });
+ return { stable: entry };
+ });
+ const stableResolver = createResolver("stable", ["session.started"], stableHandler);
+
+ try {
+ await dispatchDynamicToolEvent({
+ ctx,
+ resolvers: [resolver, stableResolver],
+ messages: [],
+ event: makeEvent("session.started"),
+ });
+ ctx.set(SessionDynamicToolRuntimeRevisionKey, "deployment:dpl_current");
+
+ approvalStepFnName = ctx.get(SessionDynamicToolMetadataKey)?.[0]?.approvalStepFnName;
+ expect(approvalStepFnName).toBe(
+ `eve:dynamic-tool-approval:${ctx.get(SessionIdKey)}:governed:governed`,
+ );
+ simulateColdStart(ctx);
+
+ await hydrateDynamicSessionTools({
+ ctx,
+ resolvers: [
+ createResolver("governed", ["session.started"], handler),
+ createResolver("stable", ["session.started"], stableHandler),
+ ],
+ messages: [],
+ event: createSessionStartedEvent(),
+ });
+
+ expect(handler).toHaveBeenCalledTimes(2);
+ expect(stableHandler).toHaveBeenCalledOnce();
+ expect(ctx.get(SessionDynamicToolMetadataKey)?.map((entry) => entry.name)).toEqual([
+ "governed",
+ "stable",
+ ]);
+ const tool = buildDynamicTools(ctx)[0]!;
+ expect(tool.description).toBe("approval policy");
+ await expect(
+ resolveApprovalPolicy(tool.approval!)(createApprovalContext({ toolName: tool.name })),
+ ).resolves.toBe("not-applicable");
+ } finally {
+ testRegistry.delete(stepId);
+ testRegistry.delete(stableStepId);
+ if (approvalStepFnName !== undefined) testRegistry.delete(approvalStepFnName);
+ }
+ });
+
+ it("rejects ownership changes while hydrating session callbacks", async () => {
+ const ctx = createCtx();
+ const original = [
+ createResolver("alpha", ["session.started"], () => ({ a: createFrameworkTool() })),
+ createResolver("beta", ["session.started"], () => ({ b: createFrameworkTool() })),
+ ];
+ await dispatchDynamicToolEvent({
+ ctx,
+ resolvers: original,
+ messages: [],
+ event: makeEvent("session.started"),
+ });
+ simulateColdStart(ctx);
+
+ await expect(
+ hydrateDynamicSessionTools({
+ ctx,
+ resolvers: [
+ createResolver("alpha", ["session.started"], () => ({ a: createFrameworkTool() })),
+ createResolver("beta", ["session.started"], () => ({ a: createFrameworkTool() })),
+ ],
+ messages: [],
+ event: createSessionStartedEvent(),
+ }),
+ ).rejects.toThrow('Dynamic tool "a" from resolver "beta" collides');
+ });
+
+ it("keeps replay callbacks isolated between sessions", async () => {
+ const sessionIds = ["session-a", "session-b"] as const;
+ const resolver = createResolver("governed", ["session.started"], (_event, resolveCtx) => {
+ const sessionId = (resolveCtx as { session: { id: string } }).session.id;
+ return {
+ governed: defineTool({
+ description: "session policy",
+ inputSchema: { type: "object" },
+ approval: () => (sessionId === "session-a" ? "not-applicable" : "user-approval"),
+ execute: async (): Promise<unknown> => ({ sessionId }),
+ }),
+ };
+ });
+
+ const contexts = sessionIds.map((sessionId) => createCtx(sessionId));
+ for (const ctx of contexts) {
+ await dispatchDynamicToolEvent({
+ ctx,
+ resolvers: [resolver],
+ messages: [],
+ event: makeEvent("session.started"),
+ });
+ }
+
+ const sessionATool = buildDynamicTools(contexts[0]!)[0]!;
+ const sessionBTool = buildDynamicTools(contexts[1]!)[0]!;
+ await expect(
+ resolveApprovalPolicy(sessionATool.approval!)(
+ createApprovalContext({ toolName: sessionATool.name }),
+ ),
+ ).resolves.toBe("not-applicable");
+ await expect(
+ resolveApprovalPolicy(sessionBTool.approval!)(
+ createApprovalContext({ toolName: sessionBTool.name }),
+ ),
+ ).resolves.toBe("user-approval");
+ });
+
+ it("evicts callback groups deterministically and rehydrates them on demand", async () => {
+ const session = createCtx("bounded-session");
+ let version = 0;
+ const handler = vi.fn(() => {
+ const current = ++version;
+ return {
+ governed: defineTool({
+ description: `version ${current}`,
+ inputSchema: { type: "object" },
+ approval: () => (current === 1 ? "user-approval" : "not-applicable"),
+ execute: async (): Promise<unknown> => current,
+ }),
+ };
+ });
+ const resolver = createResolver("bounded", ["session.started"], handler);
+
+ await dispatchDynamicToolEvent({
+ ctx: session,
+ resolvers: [resolver],
+ messages: [],
+ event: makeEvent("session.started"),
+ });
+ await dispatchDynamicToolEvent({
+ ctx: session,
+ resolvers: [resolver],
+ messages: [],
+ event: makeEvent("session.started"),
+ });
+
+ for (let index = 0; index < 255; index++) {
+ await dispatchDynamicToolEvent({
+ ctx: createCtx(`bounded-filler-${index}`),
+ resolvers: [
+ createResolver("filler", ["session.started"], () => ({
+ tool: createFrameworkTool(),
+ })),
+ ],
+ messages: [],
+ event: makeEvent("session.started"),
+ });
+ }
+
+ const retained = buildDynamicTools(session)[0]!;
+ await expect(retained.execute!({}, executeOptions)).resolves.toBe(2);
+ await expect(
+ resolveApprovalPolicy(retained.approval!)(createApprovalContext({ toolName: retained.name })),
+ ).resolves.toBe("not-applicable");
+
+ await dispatchDynamicToolEvent({
+ ctx: createCtx("bounded-evictor"),
+ resolvers: [
+ createResolver("evictor", ["session.started"], () => ({
+ tool: createFrameworkTool(),
+ })),
+ ],
+ messages: [],
+ event: makeEvent("session.started"),
+ });
+
+ expect(buildDynamicTools(session)).toEqual([]);
+ await expect(retained.execute!({}, executeOptions)).resolves.toBe(2);
+
+ await hydrateDynamicSessionTools({
+ ctx: session,
+ resolvers: [resolver],
+ messages: [],
+ event: createSessionStartedEvent(),
+ });
+ await expect(buildDynamicTools(session)[0]!.execute!({}, executeOptions)).resolves.toBe(3);
+ });
+
+ it("preserves metadata and retries when cold hydration fails", async () => {
+ const ctx = createCtx();
+ const handler = vi
+ .fn()
+ .mockImplementationOnce(() => ({ tool: createFrameworkTool("live tool") }))
+ .mockRejectedValue(new Error("temporary resolver failure"));
+ const resolver = createResolver("live", ["session.started"], handler);
+
+ await dispatchDynamicToolEvent({
+ ctx,
+ resolvers: [resolver],
+ messages: [],
+ event: makeEvent("session.started"),
+ });
+ ctx.set(SessionDynamicToolRuntimeRevisionKey, "deployment:dpl_current");
+ const originalMetadata = ctx.get(SessionDynamicToolMetadataKey);
+
+ for (let attempt = 0; attempt < 2; attempt++) {
+ simulateColdStart(ctx);
+ await hydrateDynamicSessionTools({
+ ctx,
+ resolvers: [createResolver("live", ["session.started"], handler)],
+ messages: [],
+ event: createSessionStartedEvent(),
+ });
+ expect(ctx.get(SessionDynamicToolMetadataKey)).toEqual(originalMetadata);
+ }
+
+ expect(handler).toHaveBeenCalledTimes(3);
+ });
+
it("clears removed session resolvers on a new runtime revision", async () => {
const ctx = createCtx();
const oldResolver = createResolver("old", ["session.started"], () => ({
@@ -1067,7 +1357,9 @@ describe("framework dynamic tools (no bundler transform)", () => {
const metadata = ctx.get(SessionDynamicToolMetadataKey);
expect(metadata).toHaveLength(1);
- expect(metadata![0]!.executeStepFnName).toBe("eve:framework-dynamic:fwk:search");
+ expect(metadata![0]!.executeStepFnName).toBe(
+ `eve:framework-dynamic:${ctx.get(SessionIdKey)}:fwk:search`,
+ );
expect(metadata![0]!.closureVars).toEqual({});
const tools = buildDynamicTools(ctx);
@@ -1075,7 +1367,6 @@ describe("framework dynamic tools (no bundler transform)", () => {
expect(tools[0]!.name).toBe("search");
// Simulate step boundary — virtual context cleared, durable survives
- ctx.clearVirtualContext();
const replayedTools = buildDynamicTools(ctx);
expect(replayedTools).toHaveLength(1);
@@ -1133,8 +1424,6 @@ describe("framework dynamic tools (no bundler transform)", () => {
const metadata = ctx.get(SessionDynamicToolMetadataKey);
expect(metadata).toHaveLength(2);
- ctx.clearVirtualContext();
-
const tools = buildDynamicTools(ctx);
expect(tools).toHaveLength(2);
expect(tools.map((t) => t.name).sort()).toEqual(["query", "search"]);
@@ -1153,8 +1442,6 @@ describe("framework dynamic tools (no bundler transform)", () => {
event: makeEvent("session.started"),
});
- ctx.clearVirtualContext();
-
const tools = buildDynamicTools(ctx);
expect(tools).toHaveLength(1);
expect(tools[0]!.name).toBe("analytics");
@@ -1210,8 +1497,6 @@ describe("framework dynamic tools (no bundler transform)", () => {
event: makeEvent("session.started"),
});
- ctx.clearVirtualContext();
-
const tools = buildDynamicTools(ctx);
expect(tools).toHaveLength(1);
expect(tools[0]!.name).toBe("guarded");
@@ -1286,21 +1571,20 @@ describe("framework dynamic tools (no bundler transform)", () => {
expect(tools.get("guarded")?.description).toBe("step");
});
- it("replays response authorization from session-scoped dynamic tools", async () => {
+ it("rehydrates an untransformed executor and approval policies after a cold start", async () => {
const ctx = createCtx();
+ const execute = vi.fn(async () => ({ ok: true }));
+ const request = vi.fn(async () => "user-approval" as const);
const response = vi.fn(async () => ({ status: "allowed" }) as const);
- const entry: DynamicToolEntry = defineTool({
- approval: {
- request: async () => "user-approval" as const,
- response,
- },
- description: "destructive op",
- execute: async (): Promise<unknown> => ({ ok: true }),
- inputSchema: { type: "object" },
- });
- const resolver = createResolver("session_guard", ["session.started"], () => ({
- guarded: entry,
+ const handler = vi.fn(() => ({
+ guarded: defineTool({
+ approval: { request, response },
+ description: "dependency-created destructive op",
+ execute,
+ inputSchema: { type: "object" },
+ }),
}));
+ const resolver = createResolver("session_guard", ["session.started"], handler);
await dispatchDynamicToolEvent({
ctx,
@@ -1308,12 +1592,29 @@ describe("framework dynamic tools (no bundler transform)", () => {
messages: [],
resolvers: [resolver],
});
- ctx.clearVirtualContext();
+ ctx.set(SessionDynamicToolRuntimeRevisionKey, "deployment:dpl_current");
- const approval = buildDynamicTools(ctx)[0]!.approval;
+ simulateColdStart(ctx);
+ await hydrateDynamicSessionTools({
+ ctx,
+ event: createSessionStartedEvent(),
+ messages: [],
+ resolvers: [createResolver("session_guard", ["session.started"], handler)],
+ });
+
+ expect(handler).toHaveBeenCalledTimes(2);
+ const tool = buildDynamicTools(ctx)[0]!;
+ await expect(tool.execute!({}, executeOptions)).resolves.toEqual({ ok: true });
+ expect(execute).toHaveBeenCalledOnce();
+
+ const approval = tool.approval;
if (approval === undefined || typeof approval === "function") {
- throw new Error("Expected replayed approval configuration.");
+ throw new Error("Expected rehydrated approval configuration.");
}
+ const approvalCtx = createApprovalContext({ toolName: "guarded" });
+ await expect(approval.request(approvalCtx)).resolves.toBe("user-approval");
+ expect(request).toHaveBeenCalledExactlyOnceWith(approvalCtx);
+
const responseCtx = {
auth: {
getToken: vi.fn(),
@@ -1371,8 +1672,6 @@ describe("framework dynamic tools (no bundler transform)", () => {
const metadata = ctx.get(SessionDynamicToolMetadataKey);
expect(metadata?.[0]?.outputSchema).toEqual(outputSchema);
- ctx.clearVirtualContext();
-
const tools = buildDynamicTools(ctx);
expect(tools).toHaveLength(1);
expect(serializeOutputSchema(tools[0]!.outputSchema as ToolSchema)).toEqual(outputSchema);
@@ -1414,7 +1713,6 @@ describe("framework dynamic tools (no bundler transform)", () => {
event: makeEvent("session.started"),
});
- ctx.clearVirtualContext();
let tools = buildDynamicTools(ctx);
const result1 = await tools[0]!.execute!({}, executeOptions);
expect(result1).toEqual({ version: 1 });
@@ -1427,7 +1725,6 @@ describe("framework dynamic tools (no bundler transform)", () => {
event: makeEvent("session.started"),
});
- ctx.clearVirtualContext();
tools = buildDynamicTools(ctx);
expect(tools[0]!.description).toBe("v2");
const result2 = await tools[0]!.execute!({}, executeOptions);
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.ts b/packages/eve/src/context/dynamic-tool-lifecycle.ts
index e41e69ac4..9f19b285a 100644
--- a/packages/eve/src/context/dynamic-tool-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-tool-lifecycle.ts
@@ -26,6 +26,7 @@ import type { ContextKey } from "#context/key.js";
import {
SessionDynamicToolMetadataKey,
SessionDynamicToolRuntimeRevisionKey,
+ SessionIdKey,
TurnDynamicToolMetadataKey,
LiveStepToolsKey,
} from "#context/keys.js";
@@ -158,8 +159,48 @@ function lookupStepFunction(stepId: string): ((...args: unknown[]) => unknown) |
}
}
-function registerStepFunction(stepId: string, fn: Function): void {
- getStepRegistry().set(stepId, fn);
+function hasMissingProcessCallback(metadata: DurableDynamicToolMetadata): boolean {
+ return (
+ (metadata.executeStepFnName?.startsWith("eve:framework-dynamic:") === true &&
+ lookupStepFunction(metadata.executeStepFnName) === null) ||
+ (metadata.approvalStepFnName !== undefined &&
+ lookupStepFunction(metadata.approvalStepFnName) === null) ||
+ (metadata.approvalResponseStepFnName !== undefined &&
+ lookupStepFunction(metadata.approvalResponseStepFnName) === null)
+ );
+}
+
+const MAX_PROCESS_CALLBACK_GROUPS = 256;
+interface ProcessCallbackGroup {
+ readonly id: string;
+ readonly callbackIds: Set<string>;
+}
+const processCallbackQueue: ProcessCallbackGroup[] = [];
+const processCallbackGroups = new Map<string, ProcessCallbackGroup>();
+
+function registerProcessCallbacks(groupId: string, callbacks: ReadonlyMap<string, Function>): void {
+ const registry = getStepRegistry();
+ const previous = processCallbackGroups.get(groupId);
+ if (previous !== undefined) {
+ for (const callbackId of previous.callbackIds) registry.delete(callbackId);
+ }
+
+ if (callbacks.size === 0) {
+ processCallbackGroups.delete(groupId);
+ return;
+ }
+
+ const group = { id: groupId, callbackIds: new Set(callbacks.keys()) };
+ processCallbackGroups.set(groupId, group);
+ processCallbackQueue.push(group);
+ for (const [callbackId, callback] of callbacks) registry.set(callbackId, callback);
+
+ while (processCallbackQueue.length > MAX_PROCESS_CALLBACK_GROUPS) {
+ const evicted = processCallbackQueue.shift()!;
+ if (processCallbackGroups.get(evicted.id) !== evicted) continue;
+ processCallbackGroups.delete(evicted.id);
+ for (const callbackId of evicted.callbackIds) registry.delete(callbackId);
+ }
}
function safeSerialize(obj: Record<string, unknown>): Record<string, unknown> {
@@ -187,16 +228,6 @@ function durableKeyForEvent(
}
}
-// ---------------------------------------------------------------------------
-// Build: assemble live tools from all scoped durable keys
-// ---------------------------------------------------------------------------
-
-/**
- * Builds live dynamic tool definitions from session + turn + step
- * durable metadata keys. Session-scoped tools appear first, then
- * turn, then step. The tool-loop calls this right before the model
- * call — no virtual key needed.
- */
// ---------------------------------------------------------------------------
// Resolve: run resolver handlers, capture closures, write durable metadata
// ---------------------------------------------------------------------------
@@ -268,6 +299,7 @@ async function resolveToolsFromEvent(
const { resolver, entries, isSingle } = outcome.value;
const named = qualifyDynamicToolNames(resolver, isSingle, entries);
+ const processCallbacks = new Map<string, Function>();
for (const { name, entryKey, entry } of named) {
const previousOwner = dynamicToolOwners.get(name);
if (previousOwner !== undefined && previousOwner !== resolver.slug) {
@@ -295,14 +327,11 @@ async function resolveToolsFromEvent(
let serializedClosureVars =
closureVars !== undefined ? safeSerialize(closureVars) : undefined;
- // Framework tools skip the bundler AST transform, so they carry
- // no __executeStepFn/__closureVars. Register the live execute
- // closure in the step registry so session/turn-scoped metadata
- // can replay them the same way as authored tools.
+ const callbackScope = event.type === "session.started" ? `${ctx.require(SessionIdKey)}:` : "";
if (executeStepFnName === undefined) {
- const syntheticId = `eve:framework-dynamic:${resolver.slug}:${entryKey}`;
+ const syntheticId = `eve:framework-dynamic:${callbackScope}${resolver.slug}:${entryKey}`;
const originalExecute = entry.execute.bind(entry);
- registerStepFunction(syntheticId, (_closureVars: unknown, input: unknown, ctx: unknown) =>
+ processCallbacks.set(syntheticId, (_closureVars: unknown, input: unknown, ctx: unknown) =>
originalExecute(
input as Record<string, unknown>,
ctx as Parameters<typeof entry.execute>[1],
@@ -315,17 +344,17 @@ async function resolveToolsFromEvent(
let approvalStepFnName: string | undefined;
let approvalResponseStepFnName: string | undefined;
if (entry.approval !== undefined) {
- approvalStepFnName = `eve:dynamic-tool-approval:${resolver.slug}:${entryKey}`;
+ approvalStepFnName = `eve:dynamic-tool-approval:${callbackScope}${resolver.slug}:${entryKey}`;
const originalApproval = resolveApprovalPolicy(entry.approval).bind(entry);
- registerStepFunction(approvalStepFnName, (_closureVars: unknown, approvalCtx: unknown) =>
+ processCallbacks.set(approvalStepFnName, (_closureVars: unknown, approvalCtx: unknown) =>
originalApproval(approvalCtx as ApprovalContext),
);
const responsePolicy =
typeof entry.approval === "function" ? undefined : entry.approval.response;
if (responsePolicy !== undefined) {
- approvalResponseStepFnName = `eve:dynamic-tool-approval-response:${resolver.slug}:${entryKey}`;
- registerStepFunction(
+ approvalResponseStepFnName = `eve:dynamic-tool-approval-response:${callbackScope}${resolver.slug}:${entryKey}`;
+ processCallbacks.set(
approvalResponseStepFnName,
(_closureVars: unknown, responseCtx: unknown) =>
responsePolicy(responseCtx as ApprovalResponseContext),
@@ -346,6 +375,14 @@ async function resolveToolsFromEvent(
closureVars: serializedClosureVars,
});
}
+
+ if (event.type === "session.started") {
+ registerProcessCallbacks(`${ctx.require(SessionIdKey)}:${resolver.slug}`, processCallbacks);
+ } else {
+ for (const [callbackId, callback] of processCallbacks) {
+ getStepRegistry().set(callbackId, callback);
+ }
+ }
}
return { metadata, liveTools };
@@ -467,3 +504,37 @@ export async function refreshDynamicSessionToolsForRuntimeRevision(input: {
input.ctx.set(SessionDynamicToolMetadataKey, metadata);
input.ctx.set(SessionDynamicToolRuntimeRevisionKey, input.runtimeRevision);
}
+
+/** Re-registers missing process-local session callbacks in a fresh runtime. */
+export async function hydrateDynamicSessionTools(input: {
+ readonly ctx: ContextContainer;
+ readonly resolvers: readonly ResolvedDynamicToolResolver[];
+ readonly event: SessionStartedStreamEvent;
+ readonly messages: readonly ModelMessage[];
+}): Promise<void> {
+ const storedMetadata = input.ctx.get(SessionDynamicToolMetadataKey) ?? [];
+ const missing = storedMetadata.filter(hasMissingProcessCallback);
+ if (missing.length === 0) return;
+
+ const owners = new Set(missing.map((entry) => entry.resolverSlug));
+ const matching = input.resolvers.filter(
+ (resolver) => resolver.eventNames.includes("session.started") && owners.has(resolver.slug),
+ );
+ const { metadata } =
+ matching.length === 0
+ ? { metadata: [] }
+ : await resolveToolsFromEvent(input.ctx, matching, input.event, input.messages);
+ const durableOwners = new Map(storedMetadata.map((entry) => [entry.name, entry.resolverSlug]));
+ const resolvedOwners = new Map(metadata.map((entry) => [entry.name, entry.resolverSlug]));
+ if (metadata.some((entry) => durableOwners.get(entry.name) !== entry.resolverSlug)) {
+ throw new Error("Dynamic session tool callback hydration changed durable ownership.");
+ }
+ if (
+ missing.some(
+ (entry) =>
+ resolvedOwners.get(entry.name) !== entry.resolverSlug || hasMissingProcessCallback(entry),
+ )
+ ) {
+ log.warn("Dynamic session tool callback hydration did not reproduce durable ownership.");
+ }
+}
diff --git a/packages/eve/src/execution/workflow-steps.test.ts b/packages/eve/src/execution/workflow-steps.test.ts
index 3b1e0565e..ff2ddf4cf 100644
--- a/packages/eve/src/execution/workflow-steps.test.ts
+++ b/packages/eve/src/execution/workflow-steps.test.ts
@@ -2294,13 +2294,25 @@ describe("turnStep", () => {
it("refreshes session-scoped dynamic tools from the current deployment", async () => {
vi.stubEnv("VERCEL_DEPLOYMENT_ID", "dpl_new");
- const handler = vi.fn(() => ({
- current_tool: defineTool({
- description: "Current deployment tool",
- inputSchema: { type: "object" },
- execute: async () => ({ ok: true }),
- }),
- }));
+ const lifecycleOrder: string[] = [];
+ const originalClearVirtualContext = ContextContainer.prototype.clearVirtualContext;
+ vi.spyOn(ContextContainer.prototype, "clearVirtualContext").mockImplementation(
+ function (this: ContextContainer) {
+ lifecycleOrder.push("clear");
+ originalClearVirtualContext.call(this);
+ },
+ );
+ const handler = vi.fn(() => {
+ lifecycleOrder.push("refresh");
+ return {
+ current_tool: defineTool({
+ description: "Current deployment tool",
+ inputSchema: { type: "object" },
+ approval: () => "not-applicable" as const,
+ execute: async () => ({ ok: true }),
+ }),
+ };
+ });
const dynamicToolResolver = {
eventNames: ["session.started"],
events: { "session.started": handler },
@@ -2334,10 +2346,13 @@ describe("turnStep", () => {
} as never;
vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(compiledBundle);
vi.mocked(createExecutionNodeStep).mockImplementation(() => {
- return async (session): Promise<StepResult> => ({
- next: { done: true, output: "ok" },
- session,
- });
+ return async (session): Promise<StepResult> => {
+ lifecycleOrder.push("execute");
+ return {
+ next: { done: true, output: "ok" },
+ session,
+ };
+ };
});
const session = createStubSession({
@@ -2390,6 +2405,7 @@ describe("turnStep", () => {
});
expect(handler).toHaveBeenCalledOnce();
+ expect(lifecycleOrder).toEqual(["refresh", "clear", "execute"]);
expect(result.serializedContext[SessionDynamicToolRuntimeRevisionKey.name]).toBe(
"deployment:dpl_new",
);
diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.ts
index 7625889c0..643795626 100644
--- a/packages/eve/src/execution/workflow-steps.ts
+++ b/packages/eve/src/execution/workflow-steps.ts
@@ -17,6 +17,7 @@ import {
} from "#context/dynamic-subagent-lifecycle.js";
import {
dispatchDynamicToolEvent,
+ hydrateDynamicSessionTools,
refreshDynamicSessionToolsForRuntimeRevision,
} from "#context/dynamic-tool-lifecycle.js";
import {
@@ -103,14 +104,8 @@ const TASK_DONE_WITH_PENDING_INPUT_ERROR_MESSAGE =
"Task mode cannot complete while input requests remain pending.";
/**
- * Result of one durable harness step, consumed by the turn workflow.
- *
- * `park` carries the pending fields needed to choose a
- * {@link import("#execution/next-driver-action.js").NextDriverAction} without re-reading state.
- *
- * `cancelled` converts the harness's cancellation throw into a *returned*
- * result so workflow-core never classifies the abort as a step failure or
- * retries it; the epilogue runs in `settleCancelledTurnStep`.
+ * Result of one durable harness step. `cancelled` is returned so workflow-core
+ * does not retry it; `park` carries the pending state needed by the next action.
*/
export type DurableStepResult =
| {
@@ -206,13 +201,8 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
// Outside a workflow context (e.g. tests) — getHookUrl will return undefined.
}
- // Authorization callback. If the delivery carries an
- // `authorizationCallback` and there's a pending authorization on
- // session state, extract it, build AuthorizationResult entries, and
- // populate PendingAuthorizationResultKey so tools can complete auth.
- // Strip the callback from the delivery so the adapter doesn't see it.
- // Completion event names are collected here; emission happens after
- // the `emit` function is created below.
+ // Resolve authorization callbacks before the adapter sees the delivery.
+ // Completion events are emitted after `emit` is created below.
const pendingAuth = getPendingAuthorization(durableSession.state);
let completedAuths: ReturnType<typeof matchAuthorizationCallbacks>["matches"] | undefined;
if (pendingAuth && input.input?.kind === "deliver") {
@@ -386,6 +376,12 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu
runtimeRevision: dynamicRuntimeRevision,
}),
]);
+ await hydrateDynamicSessionTools({
+ ctx,
+ resolvers: dynamicToolResolvers,
+ event: refreshEvent,
+ messages: initialSession.history,
+ });
}
} catch (error) {
await failChannelDeliveries(error);