Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

fix(eve): resume sessions with legacy dynamic tool metadata (#2751)

vercel-gh-bot-2[bot]0a1ad486b676
diff --git a/.changeset/clean-tools-replay.md b/.changeset/clean-tools-replay.md
new file mode 100644
index 000000000..40111ce64
--- /dev/null
+++ b/.changeset/clean-tools-replay.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Resume sessions with dynamic tools persisted by older eve versions without crashing during callback restoration.
diff --git a/packages/eve/src/context/build-dynamic-tools.ts b/packages/eve/src/context/build-dynamic-tools.ts
index 1f7c01d2d..e77dc6e03 100644
--- a/packages/eve/src/context/build-dynamic-tools.ts
+++ b/packages/eve/src/context/build-dynamic-tools.ts
@@ -5,8 +5,12 @@ import {
SessionDynamicToolMetadataKey,
StepDynamicToolMetadataKey,
TurnDynamicToolMetadataKey,
- type DurableDynamicToolMetadata,
} from "#context/keys.js";
+import {
+ isCurrentDynamicToolMetadata,
+ type CurrentDynamicToolMetadata,
+ type PersistedDynamicToolMetadata,
+} from "#context/dynamic-tool-metadata.js";
import { createToolExecuteWithAuth } from "#execution/tool-auth.js";
import { createLogger } from "#internal/logging.js";
import type {
@@ -25,7 +29,7 @@ import { toInputSchema, toOutputSchema } from "#tools/schema.js";
const log = createLogger("dynamic-tools");
function missingCallbackError(
- metadata: DurableDynamicToolMetadata,
+ metadata: CurrentDynamicToolMetadata,
phase: DurableDynamicCallbackPhase,
): Error {
return new Error(
@@ -36,7 +40,7 @@ function missingCallbackError(
}
function buildReplayedApproval(
- metadata: DurableDynamicToolMetadata,
+ metadata: CurrentDynamicToolMetadata,
): HarnessToolDefinition["approval"] | undefined {
const requestReference = metadata.callbacks.approvalRequest;
if (requestReference === undefined) return undefined;
@@ -82,7 +86,7 @@ function buildReplayedApproval(
/** Reconstructs every callback exclusively from its durable descriptor. */
export function replayDynamicTools(
- metadata: readonly DurableDynamicToolMetadata[],
+ metadata: readonly CurrentDynamicToolMetadata[],
): HarnessToolDefinition[] {
return metadata.map((entry) => {
const executeReference = entry.callbacks.execute;
@@ -126,6 +130,18 @@ export function replayDynamicTools(
});
}
+function requireCurrentDynamicToolMetadata(
+ metadata: readonly PersistedDynamicToolMetadata[],
+): readonly CurrentDynamicToolMetadata[] {
+ const old = metadata.find((entry) => !isCurrentDynamicToolMetadata(entry));
+ if (old !== undefined) {
+ throw new Error(
+ `Dynamic tool "${old.name}" reached replay before its persisted metadata was converted to the current schema.`,
+ );
+ }
+ return metadata as readonly CurrentDynamicToolMetadata[];
+}
+
/**
* Builds live dynamic tool definitions. Narrower scopes appear first so they
* win on name collision (the tool loop uses `??=` for deduplication).
@@ -145,8 +161,14 @@ export function buildResponseAuthorizationTools(input: {
}
export function buildDynamicTools(ctx: ContextReader): readonly HarnessToolDefinition[] {
- const step = replayDynamicTools(ctx.get(StepDynamicToolMetadataKey) ?? []);
- const turn = replayDynamicTools(ctx.get(TurnDynamicToolMetadataKey) ?? []);
- const session = replayDynamicTools(ctx.get(SessionDynamicToolMetadataKey) ?? []);
+ const step = replayDynamicTools(
+ requireCurrentDynamicToolMetadata(ctx.get(StepDynamicToolMetadataKey) ?? []),
+ );
+ const turn = replayDynamicTools(
+ requireCurrentDynamicToolMetadata(ctx.get(TurnDynamicToolMetadataKey) ?? []),
+ );
+ const session = replayDynamicTools(
+ requireCurrentDynamicToolMetadata(ctx.get(SessionDynamicToolMetadataKey) ?? []),
+ );
return [...step, ...turn, ...session];
}
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
index a4a4c9a12..392e0cd18 100644
--- a/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
+++ b/packages/eve/src/context/dynamic-tool-lifecycle.test.ts
@@ -2,7 +2,12 @@ import { asSchema } from "ai";
import { describe, expect, it, vi } from "vitest";
import type { DynamicToolEntry } from "#tools/dynamic.js";
-import type { DurableDynamicToolMetadata } from "#context/keys.js";
+import {
+ isCurrentDynamicToolMetadata,
+ type CurrentDynamicToolMetadata,
+ type OldSourceOffsetDynamicToolMetadata,
+ type OldStepFunctionDynamicToolMetadata,
+} from "#context/dynamic-tool-metadata.js";
import { resolveApprovalPolicy, type ApprovalContext } from "#approval/definition.js";
import { defineTool, type ToolContext } from "#tools/definition.js";
import type { JsonObject } from "#shared/json.js";
@@ -19,6 +24,7 @@ const {
replayDynamicSessionTools,
dispatchDynamicToolEvent,
refreshDynamicSessionToolsForRuntimeRevision,
+ rebindMissingCompiledDynamicToolCallbacks,
validateDurableDynamicToolCallbacks,
} = await import("#context/dynamic-tool-lifecycle.js");
const { buildDynamicTools, buildResponseAuthorizationTools } =
@@ -39,7 +45,11 @@ import {
stampDurableDynamicToolCallbacks,
} from "#tools/durable-callbacks.js";
import type { ResolvedDynamicToolResolver } from "#runtime/types.js";
-import { createSessionStartedEvent, type UnstampedMessageStreamEvent } from "#protocol/message.js";
+import {
+ createSessionStartedEvent,
+ createStepStartedEvent,
+ type UnstampedMessageStreamEvent,
+} from "#protocol/message.js";
// Re-implement the naming logic here to test it independently
// (the production function is unexported — testing via the public behavior)
@@ -186,8 +196,21 @@ function registerTestCallback(
});
}
+function requireCurrentMetadata(
+ metadata:
+ | CurrentDynamicToolMetadata
+ | OldSourceOffsetDynamicToolMetadata
+ | OldStepFunctionDynamicToolMetadata
+ | undefined,
+): CurrentDynamicToolMetadata {
+ if (metadata === undefined || !isCurrentDynamicToolMetadata(metadata)) {
+ throw new Error("Expected current dynamic tool metadata.");
+ }
+ return metadata;
+}
+
describe("replayDynamicSessionTools", () => {
- function metadata(name: string, closure: JsonObject = {}): DurableDynamicToolMetadata {
+ function metadata(name: string, closure: JsonObject = {}): CurrentDynamicToolMetadata {
return {
callbacks: { execute: { closure } },
description: `${name} description`,
@@ -346,6 +369,14 @@ function createApprovalContext(input: {
}
function makeEvent(type: string): UnstampedMessageStreamEvent {
+ if (type === "step.started") {
+ return createStepStartedEvent({
+ modelId: "test-model",
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "test-turn",
+ });
+ }
return { type, data: {} } as UnstampedMessageStreamEvent;
}
@@ -549,6 +580,154 @@ describe("dispatchDynamicToolEvent", () => {
await expect(tool!.execute!({}, executeOptions)).resolves.toEqual({ ok: true });
});
+ it("migrates serialized legacy session metadata when the runtime revision is unchanged", async () => {
+ let ctx = createCtx();
+ ctx.set(SessionDynamicToolRuntimeRevisionKey, "deployment:dpl_current");
+ const serialized = serializeContext(ctx);
+ serialized[SessionDynamicToolMetadataKey.name] = [
+ {
+ closureVars: { version: "legacy" },
+ description: "legacy description",
+ entryKey: "tool",
+ executeStepFnName: "fn_0",
+ inputSchema: { type: "object" },
+ name: "tool",
+ resolverSlug: "legacy",
+ } satisfies OldStepFunctionDynamicToolMetadata,
+ ];
+ ctx = await deserializeContext(serialized);
+ const handler = vi.fn(() => ({ tool: createReplayableTool("current description") }));
+ const resolver = createResolver("legacy", ["session.started"], handler);
+
+ await refreshDynamicSessionToolsForRuntimeRevision({
+ ctx,
+ resolvers: [resolver],
+ messages: [],
+ event: createSessionStartedEvent(),
+ runtimeRevision: "deployment:dpl_current",
+ });
+
+ expect(handler).toHaveBeenCalledOnce();
+ expect(
+ requireCurrentMetadata(ctx.get(SessionDynamicToolMetadataKey)?.[0]).callbacks.execute.closure,
+ ).toEqual({});
+ const [tool] = buildDynamicTools(ctx);
+ await expect(tool!.execute!({}, executeOptions)).resolves.toEqual({ ok: true });
+ });
+
+ it("converts source-offset turn metadata while preserving its closure", async () => {
+ let ctx = createCtx();
+ const serialized = serializeContext(ctx);
+ serialized[TurnDynamicToolMetadataKey.name] = [
+ {
+ callbacks: {
+ execute: {
+ closure: { version: "offset" },
+ stepId: "eve:dynamic-tool//old/execute/0-100",
+ },
+ },
+ description: "legacy description",
+ entryKey: "legacy_turn_tool",
+ inputSchema: { type: "object" },
+ name: "legacy_turn_tool",
+ resolverSlug: "legacy",
+ } satisfies OldSourceOffsetDynamicToolMetadata,
+ ];
+ ctx = await deserializeContext(serialized);
+ const entry = defineTool({
+ description: "current description",
+ inputSchema: { type: "object" },
+ execute: async () => null,
+ });
+ stampDurableDynamicToolCallbacks(entry, {
+ execute: {
+ callback: (closure) => closure,
+ closure: { version: "current" },
+ },
+ });
+ const resolver = createResolver("legacy", ["turn.started"], () => ({
+ legacy_turn_tool: entry,
+ }));
+
+ await rebindMissingCompiledDynamicToolCallbacks({
+ ctx,
+ event: makeEvent("turn.started"),
+ messages: [],
+ resolvers: [resolver],
+ });
+
+ expect(
+ requireCurrentMetadata(ctx.get(TurnDynamicToolMetadataKey)?.[0]).callbacks.execute.closure,
+ ).toEqual({
+ version: "offset",
+ });
+ const [tool] = buildDynamicTools(ctx);
+ await expect(tool!.execute!({}, executeOptions)).resolves.toEqual({ version: "offset" });
+ });
+
+ it("does not use a same-named callback registered by a different owner", async () => {
+ let ctx = createCtx();
+ const serialized = serializeContext(ctx);
+ serialized[TurnDynamicToolMetadataKey.name] = [
+ {
+ callbacks: {
+ execute: { closure: {}, stepId: "old-offset" },
+ },
+ description: "old description",
+ entryKey: "tool",
+ inputSchema: { type: "object" },
+ name: "colliding_tool",
+ resolverSlug: "missing-owner",
+ } satisfies OldSourceOffsetDynamicToolMetadata,
+ ];
+ ctx = await deserializeContext(serialized);
+ registerTestCallback("colliding_tool", "execute", () => ({ wrongOwner: true }));
+
+ try {
+ await expect(
+ rebindMissingCompiledDynamicToolCallbacks({
+ ctx,
+ event: makeEvent("turn.started"),
+ messages: [],
+ resolvers: [],
+ }),
+ ).rejects.toThrow('Dynamic tool "colliding_tool" uses old persisted metadata');
+ } finally {
+ getDynamicCallbackRegistry().delete("colliding_tool");
+ }
+ });
+
+ it("replaces old step-function turn metadata without requiring cold-rebind opt-in", async () => {
+ let ctx = createCtx();
+ const serialized = serializeContext(ctx);
+ serialized[TurnDynamicToolMetadataKey.name] = [
+ {
+ closureVars: { version: "old" },
+ description: "old description",
+ entryKey: "tool",
+ executeStepFnName: "old-step-function",
+ inputSchema: { type: "object" },
+ name: "tool",
+ resolverSlug: "old",
+ } satisfies OldStepFunctionDynamicToolMetadata,
+ ];
+ ctx = await deserializeContext(serialized);
+ const resolver = createResolver("old", ["turn.started"], () => ({
+ tool: createReplayableTool("current description"),
+ }));
+
+ await rebindMissingCompiledDynamicToolCallbacks({
+ ctx,
+ event: makeEvent("turn.started"),
+ messages: [],
+ resolvers: [resolver],
+ });
+
+ expect(requireCurrentMetadata(ctx.get(TurnDynamicToolMetadataKey)?.[0]).description).toBe(
+ "current description",
+ );
+ });
+
it("rejects metadata persisted by the pre-release offset-based format", () => {
const entry = defineTool({
description: "legacy tool",
@@ -739,10 +918,12 @@ describe("dispatchDynamicToolEvent", () => {
const resolver = createResolver("api", ["step.started"], () => ({
query: createReplayableTool("cached"),
}));
- const event = {
- type: "step.started",
- data: { stepIndex: 1, turnId: "turn-1" },
- } as UnstampedMessageStreamEvent;
+ const event = createStepStartedEvent({
+ modelId: "test-model",
+ sequence: 0,
+ stepIndex: 1,
+ turnId: "turn-1",
+ });
await dispatchDynamicToolEvent({ ctx, event, messages: [], resolvers: [resolver] });
ctx.clearVirtualContext();
@@ -766,7 +947,12 @@ describe("dispatchDynamicToolEvent", () => {
ctx,
resolvers: [resolver],
messages: [],
- event: makeEvent("step.started"),
+ event: createStepStartedEvent({
+ modelId: "test-model",
+ sequence: 0,
+ stepIndex: 0,
+ turnId: "test-turn",
+ }),
});
expect(buildDynamicTools(ctx)[0]!.description).toBe("call 1");
@@ -774,7 +960,12 @@ describe("dispatchDynamicToolEvent", () => {
ctx,
resolvers: [resolver],
messages: [],
- event: makeEvent("step.started"),
+ event: createStepStartedEvent({
+ modelId: "test-model",
+ sequence: 1,
+ stepIndex: 1,
+ turnId: "test-turn",
+ }),
});
expect(buildDynamicTools(ctx)).toHaveLength(1);
expect(buildDynamicTools(ctx)[0]!.description).toBe("call 2");
@@ -899,7 +1090,9 @@ describe("dispatchDynamicToolEvent", () => {
});
expect(buildDynamicTools(ctx)).toHaveLength(1);
expect(ctx.get(SessionDynamicToolMetadataKey)).toHaveLength(1);
- expect(ctx.get(SessionDynamicToolMetadataKey)![0]!.callbacks.execute.closure).toEqual({
+ expect(
+ requireCurrentMetadata(ctx.get(SessionDynamicToolMetadataKey)?.[0]).callbacks.execute.closure,
+ ).toEqual({
apiUrl: "https://api.example.com",
});
@@ -1053,7 +1246,7 @@ describe("programmatic dynamic tools (no bundler transform)", () => {
const metadata = ctx.get(SessionDynamicToolMetadataKey);
expect(metadata).toHaveLength(1);
- expect(metadata![0]!.callbacks.execute.closure).toEqual({});
+ expect(requireCurrentMetadata(metadata?.[0]).callbacks.execute.closure).toEqual({});
const tools = buildDynamicTools(ctx);
expect(tools).toHaveLength(1);
diff --git a/packages/eve/src/context/dynamic-tool-lifecycle.ts b/packages/eve/src/context/dynamic-tool-lifecycle.ts
index 4dfc9aaa6..5800baf8e 100644
--- a/packages/eve/src/context/dynamic-tool-lifecycle.ts
+++ b/packages/eve/src/context/dynamic-tool-lifecycle.ts
@@ -1,19 +1,28 @@
import type { ModelMessage } from "ai";
import { replayDynamicTools } from "#context/build-dynamic-tools.js";
-import { contextStorage, type ContextContainer } from "#context/container.js";
+import { contextStorage, type AlsContext } from "#context/container.js";
import type { ContextKey } from "#context/key.js";
import {
SessionDynamicToolMetadataKey,
SessionDynamicToolRuntimeRevisionKey,
StepDynamicToolMetadataKey,
TurnDynamicToolMetadataKey,
- type DurableDynamicToolMetadata,
} from "#context/keys.js";
+import {
+ isCurrentDynamicToolMetadata,
+ toCurrentDynamicToolMetadataList,
+ type CurrentDynamicToolMetadata,
+ type PersistedDynamicToolMetadata,
+} from "#context/dynamic-tool-metadata.js";
import { buildResolveContext } from "#context/dynamic-resolve-context.js";
import type { HarnessToolDefinition } from "#harness/execute-tool.js";
import { createLogger } from "#internal/logging.js";
-import type { SessionStartedStreamEvent, UnstampedMessageStreamEvent } from "#protocol/message.js";
+import type {
+ SessionStartedStreamEvent,
+ StepStartedStreamEvent,
+ UnstampedMessageStreamEvent,
+} from "#protocol/message.js";
import { ALLOWED_DYNAMIC_TOOL_EVENTS } from "#dynamic/definition.js";
import { isBrandedToolEntry, type DynamicToolEntry } from "#tools/dynamic.js";
import {
@@ -55,7 +64,7 @@ function qualifyDynamicToolNames(
/** Kept as the session-specific entry point for existing runtime consumers. */
export function replayDynamicSessionTools(
- metadata: readonly DurableDynamicToolMetadata[],
+ metadata: readonly CurrentDynamicToolMetadata[],
_resolvers: readonly ResolvedDynamicToolResolver[],
): readonly HarnessToolDefinition[] {
return replayDynamicTools(metadata);
@@ -63,7 +72,7 @@ export function replayDynamicSessionTools(
function durableKeyForEvent(
eventType: string,
-): ContextKey<readonly DurableDynamicToolMetadata[]> | undefined {
+): ContextKey<readonly PersistedDynamicToolMetadata[]> | undefined {
switch (eventType) {
case "session.started":
return SessionDynamicToolMetadataKey;
@@ -217,7 +226,7 @@ function createMetadata(input: {
readonly entryKey: string;
readonly name: string;
readonly resolver: ResolvedDynamicToolResolver;
-}): DurableDynamicToolMetadata {
+}): CurrentDynamicToolMetadata {
return {
callbacks: validateDurableDynamicToolCallbacks(input.name, input.entry),
description: input.entry.description,
@@ -230,11 +239,11 @@ function createMetadata(input: {
}
interface ResolvedDynamicToolEvent {
- readonly metadata: readonly DurableDynamicToolMetadata[];
+ readonly metadata: readonly CurrentDynamicToolMetadata[];
}
async function resolveToolsFromEvent(
- ctx: ContextContainer,
+ ctx: AlsContext,
resolvers: readonly ResolvedDynamicToolResolver[],
event: UnstampedMessageStreamEvent,
messages: readonly ModelMessage[],
@@ -256,7 +265,7 @@ async function resolveToolsFromEvent(
}),
);
- const metadata: DurableDynamicToolMetadata[] = [];
+ const metadata: CurrentDynamicToolMetadata[] = [];
const dynamicToolOwners = new Map<string, string>();
for (const outcome of outcomes) {
if (outcome.status === "rejected") {
@@ -282,26 +291,34 @@ async function resolveToolsFromEvent(
}
const resolvedStepTools = new WeakMap<
- ContextContainer,
- { readonly coordinate: string; readonly metadata: readonly DurableDynamicToolMetadata[] }
+ AlsContext,
+ { readonly coordinate: string; readonly metadata: readonly CurrentDynamicToolMetadata[] }
>();
+function stepCoordinate(event: StepStartedStreamEvent): string {
+ return `${event.data.turnId}:${String(event.data.stepIndex)}`;
+}
+
+function storeResolvedStepTools(input: {
+ readonly ctx: AlsContext;
+ readonly event: StepStartedStreamEvent;
+ readonly metadata: readonly CurrentDynamicToolMetadata[];
+}): void {
+ input.ctx.set(StepDynamicToolMetadataKey, input.metadata);
+ const coordinate = stepCoordinate(input.event);
+ resolvedStepTools.set(input.ctx, { coordinate, metadata: input.metadata });
+}
+
/** Resolves step-scoped tools once for one internal policy/model pass. */
export async function resolveStepDynamicTools(input: {
- readonly ctx: ContextContainer;
+ readonly ctx: AlsContext;
readonly resolvers: readonly ResolvedDynamicToolResolver[];
- readonly event: UnstampedMessageStreamEvent;
+ readonly event: StepStartedStreamEvent;
readonly messages: readonly ModelMessage[];
}): Promise<void> {
- const data = ("data" in input.event ? input.event.data : undefined) as
- | { readonly stepIndex?: unknown; readonly turnId?: unknown }
- | undefined;
- const coordinate =
- typeof data?.turnId === "string" && typeof data.stepIndex === "number"
- ? `${data.turnId}:${String(data.stepIndex)}`
- : undefined;
+ const coordinate = stepCoordinate(input.event);
const cached = resolvedStepTools.get(input.ctx);
- if (coordinate !== undefined && cached?.coordinate === coordinate) {
+ if (cached?.coordinate === coordinate) {
input.ctx.set(StepDynamicToolMetadataKey, cached.metadata);
return;
}
@@ -313,19 +330,46 @@ export async function resolveStepDynamicTools(input: {
matching.length === 0
? { metadata: [] }
: await resolveToolsFromEvent(input.ctx, matching, input.event, input.messages);
- input.ctx.set(StepDynamicToolMetadataKey, metadata);
- if (coordinate !== undefined) resolvedStepTools.set(input.ctx, { coordinate, metadata });
+ storeResolvedStepTools({ ctx: input.ctx, event: input.event, metadata });
+}
+
+/** Converts persisted step metadata before any approval replay can read it. */
+export async function preparePersistedStepDynamicToolMetadata(input: {
+ readonly ctx: AlsContext;
+ readonly resolvers: readonly ResolvedDynamicToolResolver[];
+ readonly event: StepStartedStreamEvent;
+ readonly messages: readonly ModelMessage[];
+}): Promise<void> {
+ const persisted = input.ctx.get(StepDynamicToolMetadataKey) ?? [];
+ const current = persisted.filter(isCurrentDynamicToolMetadata);
+ if (current.length === persisted.length && !hasUnregisteredDurableDynamicCallbacks(current)) {
+ if (current.length > 0) {
+ storeResolvedStepTools({ ctx: input.ctx, event: input.event, metadata: current });
+ }
+ return;
+ }
+
+ await resolveStepDynamicTools(input);
+ const resolved = input.ctx.get(StepDynamicToolMetadataKey) ?? [];
+ storeResolvedStepTools({
+ ctx: input.ctx,
+ event: input.event,
+ metadata: toCurrentDynamicToolMetadataList(
+ persisted,
+ resolved.filter(isCurrentDynamicToolMetadata),
+ ),
+ });
}
export async function dispatchDynamicToolEvent(input: {
- readonly ctx: ContextContainer;
+ readonly ctx: AlsContext;
readonly resolvers: readonly ResolvedDynamicToolResolver[];
readonly event: UnstampedMessageStreamEvent;
readonly messages: readonly ModelMessage[];
}): Promise<void> {
if (!ALLOWED_DYNAMIC_TOOL_EVENTS.has(input.event.type)) return;
if (input.event.type === "step.started") {
- await resolveStepDynamicTools(input);
+ await resolveStepDynamicTools({ ...input, event: input.event });
return;
}
@@ -355,18 +399,21 @@ export async function dispatchDynamicToolEvent(input: {
* a crash, or a redeploy), so replay always resolves against current code.
*/
export async function refreshDynamicSessionToolsForRuntimeRevision(input: {
- readonly ctx: ContextContainer;
+ readonly ctx: AlsContext;
readonly resolvers: readonly ResolvedDynamicToolResolver[];
readonly event: SessionStartedStreamEvent;
readonly messages: readonly ModelMessage[];
readonly runtimeRevision: string;
}): Promise<void> {
+ const persisted: readonly PersistedDynamicToolMetadata[] =
+ input.ctx.get(SessionDynamicToolMetadataKey) ?? [];
+ const current = persisted.filter(isCurrentDynamicToolMetadata);
+ const hasOldMetadata = current.length !== persisted.length;
const revisionChanged =
input.ctx.get(SessionDynamicToolRuntimeRevisionKey) !== input.runtimeRevision;
- const needsRebind = hasUnregisteredDurableDynamicCallbacks(
- input.ctx.get(SessionDynamicToolMetadataKey) ?? [],
- );
- if (!revisionChanged && !needsRebind) return;
+ if (!revisionChanged && !hasOldMetadata && !hasUnregisteredDurableDynamicCallbacks(current)) {
+ return;
+ }
const matching = input.resolvers.filter((resolver) =>
resolver.eventNames.includes("session.started"),
);
@@ -374,31 +421,57 @@ export async function refreshDynamicSessionToolsForRuntimeRevision(input: {
matching.length === 0
? { metadata: [] }
: await resolveToolsFromEvent(input.ctx, matching, input.event, input.messages);
- input.ctx.set(SessionDynamicToolMetadataKey, metadata);
+ input.ctx.set(
+ SessionDynamicToolMetadataKey,
+ revisionChanged ? metadata : toCurrentDynamicToolMetadataList(persisted, metadata),
+ );
input.ctx.set(SessionDynamicToolRuntimeRevisionKey, input.runtimeRevision);
}
/** Re-registers callbacks for compiled resolvers that explicitly support cold replay. */
export async function rebindMissingCompiledDynamicToolCallbacks(input: {
- readonly ctx: ContextContainer;
+ readonly ctx: AlsContext;
readonly event: UnstampedMessageStreamEvent;
readonly messages: readonly ModelMessage[];
readonly resolvers: readonly ResolvedDynamicToolResolver[];
}): Promise<void> {
- const persisted = input.ctx.get(TurnDynamicToolMetadataKey) ?? [];
- const missing = persisted.filter((entry) => hasUnregisteredDurableDynamicCallbacks([entry]));
- if (missing.length === 0) return;
- const missingSlugs = new Set(missing.map((entry) => entry.resolverSlug));
+ const persisted: readonly PersistedDynamicToolMetadata[] =
+ input.ctx.get(TurnDynamicToolMetadataKey) ?? [];
+ const needsResolution = persisted.filter(
+ (entry) =>
+ !isCurrentDynamicToolMetadata(entry) || hasUnregisteredDurableDynamicCallbacks([entry]),
+ );
+ if (needsResolution.length === 0) return;
+ const resolverSlugs = new Set(needsResolution.map((entry) => entry.resolverSlug));
+ const oldResolverSlugs = new Set(
+ persisted
+ .filter((entry) => !isCurrentDynamicToolMetadata(entry))
+ .map((entry) => entry.resolverSlug),
+ );
const matching = input.resolvers.filter(
- (resolver) => resolver.rebindMissingCallbacks === true && missingSlugs.has(resolver.slug),
+ (resolver) =>
+ resolverSlugs.has(resolver.slug) &&
+ (oldResolverSlugs.has(resolver.slug) || resolver.rebindMissingCallbacks === true),
);
- if (matching.length === 0) return;
+ if (matching.length === 0) {
+ input.ctx.set(TurnDynamicToolMetadataKey, toCurrentDynamicToolMetadataList(persisted));
+ return;
+ }
- await contextStorage.run(
+ const resolved: ResolvedDynamicToolEvent = await contextStorage.run(
input.ctx,
async () => await resolveToolsFromEvent(input.ctx, matching, input.event, input.messages),
);
- const unresolved = missing.filter((entry) => hasUnregisteredDurableDynamicCallbacks([entry]));
+ const updated = toCurrentDynamicToolMetadataList(persisted, resolved.metadata);
+ input.ctx.set(TurnDynamicToolMetadataKey, updated);
+
+ const unresolved = updated.filter(
+ (entry) =>
+ needsResolution.some(
+ (candidate) =>
+ candidate.resolverSlug === entry.resolverSlug && candidate.name === entry.name,
+ ) && hasUnregisteredDurableDynamicCallbacks([entry]),
+ );
if (unresolved.length > 0) {
throw new Error(
`Dynamic tool callback rebind did not restore: ${unresolved.map((entry) => entry.name).join(", ")}. The tool may have been renamed or removed.`,
diff --git a/packages/eve/src/context/dynamic-tool-metadata.test.ts b/packages/eve/src/context/dynamic-tool-metadata.test.ts
new file mode 100644
index 000000000..21c6d0e5d
--- /dev/null
+++ b/packages/eve/src/context/dynamic-tool-metadata.test.ts
@@ -0,0 +1,126 @@
+import { describe, expect, it } from "vitest";
+
+import {
+ isCurrentDynamicToolMetadata,
+ isOldSourceOffsetDynamicToolMetadata,
+ toCurrentDynamicToolMetadata,
+ type CurrentDynamicToolMetadata,
+ type OldSourceOffsetDynamicToolMetadata,
+ type OldStepFunctionDynamicToolMetadata,
+ type PersistedDynamicToolMetadata,
+} from "#context/dynamic-tool-metadata.js";
+
+const base = {
+ description: "test tool",
+ entryKey: "tool",
+ inputSchema: { type: "object" },
+ name: "tool",
+ resolverSlug: "test",
+} as const;
+
+const current: CurrentDynamicToolMetadata = {
+ ...base,
+ callbacks: { execute: { closure: { source: "current" } } },
+};
+
+const currentWithEveryPhase: CurrentDynamicToolMetadata = {
+ ...current,
+ callbacks: {
+ approvalRequest: { closure: { source: "current" } },
+ approvalResponse: { closure: { source: "current" } },
+ execute: current.callbacks.execute,
+ toModelOutput: { closure: { source: "current" } },
+ },
+};
+
+const oldStepFunction: OldStepFunctionDynamicToolMetadata = {
+ ...base,
+ closureVars: { source: "step-function" },
+ executeStepFnName: "fn_0",
+};
+
+const oldSourceOffset: OldSourceOffsetDynamicToolMetadata = {
+ ...base,
+ callbacks: {
+ execute: {
+ closure: { source: "source-offset" },
+ stepId: "eve:dynamic-tool//old/execute/0-100",
+ },
+ },
+};
+
+describe("dynamic tool metadata schemas", () => {
+ it("distinguishes the current schema from both old schemas", () => {
+ expect(isCurrentDynamicToolMetadata(current)).toBe(true);
+ expect(isCurrentDynamicToolMetadata(oldStepFunction)).toBe(false);
+ expect(isCurrentDynamicToolMetadata(oldSourceOffset)).toBe(false);
+ expect(isOldSourceOffsetDynamicToolMetadata(current)).toBe(false);
+ expect(isOldSourceOffsetDynamicToolMetadata(oldSourceOffset)).toBe(true);
+ });
+
+ it("does not mistake an additive current field for a source offset", () => {
+ const additiveCurrent = {
+ ...current,
+ callbacks: {
+ execute: { ...current.callbacks.execute, futureField: true },
+ },
+ } as PersistedDynamicToolMetadata;
+
+ expect(isCurrentDynamicToolMetadata(additiveCurrent)).toBe(true);
+ expect(isOldSourceOffsetDynamicToolMetadata(additiveCurrent)).toBe(false);
+ });
+
+ it("preserves current metadata and replaces old step-function metadata", () => {
+ expect(toCurrentDynamicToolMetadata(current)).toBe(current);
+ expect(toCurrentDynamicToolMetadata(oldStepFunction, current)).toBe(current);
+ });
+
+ it("removes source offsets while preserving every callback closure", () => {
+ const converted = toCurrentDynamicToolMetadata(
+ {
+ ...oldSourceOffset,
+ callbacks: {
+ approvalRequest: { closure: { phase: "request" }, stepId: "old-request" },
+ approvalResponse: { closure: { phase: "response" }, stepId: "old-response" },
+ execute: oldSourceOffset.callbacks.execute,
+ toModelOutput: { closure: { phase: "output" }, stepId: "old-output" },
+ },
+ },
+ currentWithEveryPhase,
+ );
+
+ expect(converted.callbacks).toEqual({
+ approvalRequest: { closure: { phase: "request" } },
+ approvalResponse: { closure: { phase: "response" } },
+ execute: { closure: { source: "source-offset" } },
+ toModelOutput: { closure: { phase: "output" } },
+ });
+ });
+
+ it("fails when old step-function metadata has no current resolver replacement", () => {
+ expect(() => toCurrentDynamicToolMetadata(oldStepFunction)).toThrow(
+ 'Dynamic tool "tool" uses old persisted metadata',
+ );
+ });
+
+ it("requires a matching resolver replacement before converting source offsets", () => {
+ expect(() => toCurrentDynamicToolMetadata(oldSourceOffset)).toThrow(
+ 'Dynamic tool "tool" uses old persisted metadata',
+ );
+ expect(() =>
+ toCurrentDynamicToolMetadata(oldSourceOffset, {
+ ...current,
+ resolverSlug: "different",
+ }),
+ ).toThrow('Dynamic tool "tool" received current metadata from a different resolver');
+ });
+
+ it("refuses to drop approval phases from old step-function metadata", () => {
+ expect(() =>
+ toCurrentDynamicToolMetadata(
+ { ...oldStepFunction, approvalStepFnName: "old-approval" },
+ current,
+ ),
+ ).toThrow('Dynamic tool "tool" lost its approval-request callback');
+ });
+});
diff --git a/packages/eve/src/context/dynamic-tool-metadata.ts b/packages/eve/src/context/dynamic-tool-metadata.ts
new file mode 100644
index 000000000..d7ed25a1f
--- /dev/null
+++ b/packages/eve/src/context/dynamic-tool-metadata.ts
@@ -0,0 +1,158 @@
+import type { JsonObject } from "#shared/json.js";
+import type { DurableDynamicToolCallbacks } from "#tools/durable-callbacks.js";
+
+interface DynamicToolMetadataBase {
+ readonly name: string;
+ readonly description: string;
+ readonly inputSchema: JsonObject;
+ readonly outputSchema?: JsonObject;
+ readonly resolverSlug: string;
+ readonly entryKey: string;
+}
+
+/** Current schema: callback identity is the surrounding tool name and phase. */
+export interface CurrentDynamicToolMetadata extends DynamicToolMetadataBase {
+ readonly callbacks: DurableDynamicToolCallbacks;
+}
+
+/** Old schema written before callback descriptors existed. */
+export interface OldStepFunctionDynamicToolMetadata extends DynamicToolMetadataBase {
+ readonly callbacks?: never;
+ readonly executeStepFnName?: string;
+ readonly approvalStepFnName?: string;
+ readonly approvalResponseStepFnName?: string;
+ readonly closureVars?: Record<string, unknown>;
+}
+
+interface OldSourceOffsetDynamicCallbackReference {
+ readonly closure: JsonObject;
+ readonly stepId: string;
+}
+
+/** Old schema whose callback identity was a generated source offset. */
+export interface OldSourceOffsetDynamicToolMetadata extends DynamicToolMetadataBase {
+ readonly callbacks: {
+ readonly execute: OldSourceOffsetDynamicCallbackReference;
+ readonly approvalRequest?: OldSourceOffsetDynamicCallbackReference;
+ readonly approvalResponse?: OldSourceOffsetDynamicCallbackReference;
+ readonly toModelOutput?: OldSourceOffsetDynamicCallbackReference;
+ };
+}
+
+export type OldDynamicToolMetadata =
+ | OldStepFunctionDynamicToolMetadata
+ | OldSourceOffsetDynamicToolMetadata;
+
+export type PersistedDynamicToolMetadata = CurrentDynamicToolMetadata | OldDynamicToolMetadata;
+
+export function isOldSourceOffsetDynamicToolMetadata(
+ metadata: PersistedDynamicToolMetadata,
+): metadata is OldSourceOffsetDynamicToolMetadata {
+ return metadata.callbacks !== undefined && "stepId" in metadata.callbacks.execute;
+}
+
+export function isCurrentDynamicToolMetadata(
+ metadata: PersistedDynamicToolMetadata,
+): metadata is CurrentDynamicToolMetadata {
+ return metadata.callbacks !== undefined && !isOldSourceOffsetDynamicToolMetadata(metadata);
+}
+
+export function isOldStepFunctionDynamicToolMetadata(
+ metadata: PersistedDynamicToolMetadata,
+): metadata is OldStepFunctionDynamicToolMetadata {
+ return metadata.callbacks === undefined;
+}
+
+function withoutSourceOffset(
+ reference: OldSourceOffsetDynamicCallbackReference,
+): DurableDynamicToolCallbacks["execute"] {
+ return { closure: reference.closure };
+}
+
+function convertSourceOffsetMetadata(
+ metadata: OldSourceOffsetDynamicToolMetadata,
+): CurrentDynamicToolMetadata {
+ const callbacks: DurableDynamicToolCallbacks = {
+ execute: withoutSourceOffset(metadata.callbacks.execute),
+ ...(metadata.callbacks.approvalRequest === undefined
+ ? {}
+ : { approvalRequest: withoutSourceOffset(metadata.callbacks.approvalRequest) }),
+ ...(metadata.callbacks.approvalResponse === undefined
+ ? {}
+ : { approvalResponse: withoutSourceOffset(metadata.callbacks.approvalResponse) }),
+ ...(metadata.callbacks.toModelOutput === undefined
+ ? {}
+ : { toModelOutput: withoutSourceOffset(metadata.callbacks.toModelOutput) }),
+ };
+ return { ...metadata, callbacks };
+}
+
+/** Converts persisted metadata without changing already-persisted callback closures. */
+export function toCurrentDynamicToolMetadata(
+ persisted: PersistedDynamicToolMetadata,
+ resolved?: CurrentDynamicToolMetadata,
+): CurrentDynamicToolMetadata {
+ if (isCurrentDynamicToolMetadata(persisted)) return persisted;
+ if (resolved === undefined) {
+ throw new Error(
+ `Dynamic tool "${persisted.name}" uses old persisted metadata, but its resolver did not return a current replacement.`,
+ );
+ }
+ if (resolved.resolverSlug !== persisted.resolverSlug || resolved.name !== persisted.name) {
+ throw new Error(
+ `Dynamic tool "${persisted.name}" received current metadata from a different resolver or tool.`,
+ );
+ }
+ if (!isOldStepFunctionDynamicToolMetadata(persisted)) {
+ for (const phase of Object.keys(persisted.callbacks) as Array<
+ keyof DurableDynamicToolCallbacks
+ >) {
+ if (resolved.callbacks[phase] === undefined) {
+ throw new Error(
+ `Dynamic tool "${persisted.name}" lost its ${phase} callback while converting old persisted metadata.`,
+ );
+ }
+ }
+ return convertSourceOffsetMetadata(persisted);
+ }
+ if (
+ persisted.approvalResponseStepFnName !== undefined &&
+ persisted.approvalStepFnName === undefined
+ ) {
+ throw new Error(
+ `Dynamic tool "${persisted.name}" has an old approval-response callback without an approval-request callback.`,
+ );
+ }
+ if (
+ persisted.approvalStepFnName !== undefined &&
+ resolved.callbacks.approvalRequest === undefined
+ ) {
+ throw new Error(
+ `Dynamic tool "${persisted.name}" lost its approval-request callback while converting old persisted metadata.`,
+ );
+ }
+ if (
+ persisted.approvalResponseStepFnName !== undefined &&
+ resolved.callbacks.approvalResponse === undefined
+ ) {
+ throw new Error(
+ `Dynamic tool "${persisted.name}" lost its approval-response callback while converting old persisted metadata.`,
+ );
+ }
+ return resolved;
+}
+
+export function toCurrentDynamicToolMetadataList(
+ persisted: readonly PersistedDynamicToolMetadata[],
+ resolved: readonly CurrentDynamicToolMetadata[] = [],
+): readonly CurrentDynamicToolMetadata[] {
+ return persisted.map((entry) =>
+ toCurrentDynamicToolMetadata(
+ entry,
+ resolved.find(
+ (candidate) =>
+ candidate.resolverSlug === entry.resolverSlug && candidate.name === entry.name,
+ ),
+ ),
+ );
+}
diff --git a/packages/eve/src/context/keys.ts b/packages/eve/src/context/keys.ts
index cf959cd3c..0b0cb494b 100644
--- a/packages/eve/src/context/keys.ts
+++ b/packages/eve/src/context/keys.ts
@@ -6,7 +6,6 @@
import type { LanguageModel, ModelMessage, SystemModelMessage } from "ai";
-import type { JsonObject } from "#shared/json.js";
import type { InstrumentationDecision } from "#shared/instrumentation-decision.js";
import type {
ActivityObserverConfig,
@@ -23,7 +22,7 @@ import { ContextKey } from "#context/key.js";
import { SESSION_CALLBACK_CONTEXT_KEY_NAME } from "#context/key-names.js";
import type { InstrumentationChannelDeliveryRef } from "#instrumentation/lifecycle.js";
import type { HandleEventFn } from "#harness/types.js";
-import type { DurableDynamicToolCallbacks } from "#tools/durable-callbacks.js";
+import type { PersistedDynamicToolMetadata } from "#context/dynamic-tool-metadata.js";
import type { DynamicSubagentAgentConfig } from "#runtime/subagents/dynamic-agent-config.js";
import type { DynamicRemoteAgentConfig } from "#runtime/subagents/dynamic-remote-agent-config.js";
import type { SandboxAccess } from "#sandbox/state.js";
@@ -188,23 +187,13 @@ export const LiveStepDynamicModelSelectionKey = new ContextKey<LiveDynamicModelS
// Dynamic tool keys
// ---------------------------------------------------------------------------
-export interface DurableDynamicToolMetadata {
- readonly callbacks: DurableDynamicToolCallbacks;
- readonly name: string;
- readonly description: string;
- readonly inputSchema: JsonObject;
- readonly outputSchema?: JsonObject;
- readonly resolverSlug: string;
- readonly entryKey: string;
-}
-
/**
* Session-scoped dynamic tool metadata (from `session.started`).
* Persists for the session lifetime.
*/
-export const SessionDynamicToolMetadataKey = new ContextKey<readonly DurableDynamicToolMetadata[]>(
- "eve.sessionDynamicToolMetadata",
-);
+export const SessionDynamicToolMetadataKey = new ContextKey<
+ readonly PersistedDynamicToolMetadata[]
+>("eve.sessionDynamicToolMetadata");
/**
* Runtime revision that last resolved session-scoped dynamic tools.
@@ -218,7 +207,7 @@ export const SessionDynamicToolRuntimeRevisionKey = new ContextKey<string>(
* Turn-scoped dynamic tool metadata (from `turn.started`).
* Replaced each turn.
*/
-export const TurnDynamicToolMetadataKey = new ContextKey<readonly DurableDynamicToolMetadata[]>(
+export const TurnDynamicToolMetadataKey = new ContextKey<readonly PersistedDynamicToolMetadata[]>(
"eve.turnDynamicToolMetadata",
);
@@ -262,7 +251,7 @@ export const PreparedMemoryCompactionKey = new ContextKey<PreparedMemoryCompacti
);
/** Step-scoped dynamic tool metadata, replaced before each model step. */
-export const StepDynamicToolMetadataKey = new ContextKey<readonly DurableDynamicToolMetadata[]>(
+export const StepDynamicToolMetadataKey = new ContextKey<readonly PersistedDynamicToolMetadata[]>(
"eve.stepDynamicToolMetadata",
);
diff --git a/packages/eve/src/execution/node-step.test.ts b/packages/eve/src/execution/node-step.test.ts
index fc3d0ed5a..f907e1d17 100644
--- a/packages/eve/src/execution/node-step.test.ts
+++ b/packages/eve/src/execution/node-step.test.ts
@@ -2,8 +2,16 @@ import { ToolLoopAgent } from "ai";
import { afterEach, describe, expect, it, vi } from "vitest";
import type { Runtime } from "#channel/types.js";
import { ContextContainer, contextStorage } from "#context/container.js";
-import { AuthKey, InitiatorAuthKey, SessionIdKey, SessionKey } from "#context/keys.js";
+import type { OldSourceOffsetDynamicToolMetadata } from "#context/dynamic-tool-metadata.js";
+import {
+ AuthKey,
+ InitiatorAuthKey,
+ SessionIdKey,
+ SessionKey,
+ StepDynamicToolMetadataKey,
+} from "#context/keys.js";
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
+import { appendPendingInputBatch } from "#harness/input-requests.js";
import { getPendingRuntimeActionBatch } from "#harness/runtime-actions.js";
import { createInstrumentationHooks } from "#instrumentation/lifecycle.js";
import {
@@ -21,6 +29,8 @@ import { createExecutionNodeStep, createNodeHarnessTools } from "#execution/node
import { countLocalSubagentCalls } from "#execution/tools/subagent/local.js";
import { createSession } from "#execution/session.js";
import { createStubSandboxRegistry } from "#internal/testing/stub-sandbox-registry.js";
+import { defineTool } from "#tools/definition.js";
+import { stampDurableDynamicCallback } from "#tools/durable-callbacks.js";
import { toInputSchema } from "#tools/schema.js";
vi.mock("ai", () => ({
@@ -486,6 +496,153 @@ describe("createExecutionNodeStep", () => {
expect(stepSettled).toBe(true);
});
+ it("prepares persisted step tools with the node's dynamic resolvers", async () => {
+ const executeCallback = vi.fn(async (closure: unknown) => {
+ return (closure as { version: string }).version;
+ });
+ const handler = vi.fn(() => ({
+ wired_dynamic_tool: defineTool({
+ approval: stampDurableDynamicCallback(() => "user-approval" as const, {
+ callback: () => "user-approval" as const,
+ closure: { version: "current-request" },
+ }),
+ description: "A dynamic tool.",
+ execute: stampDurableDynamicCallback(async () => "current-execute", {
+ callback: executeCallback,
+ closure: { version: "current-execute" },
+ }),
+ inputSchema: { type: "object" },
+ }),
+ }));
+ const dynamicToolResolver = {
+ eventNames: ["step.started"],
+ events: { "step.started": handler },
+ logicalPath: "agent/tools/wired.ts",
+ slug: "wired",
+ sourceId: "test:wired-dynamic-tool",
+ sourceKind: "module",
+ } as never;
+ const baseNode = createTestNode();
+ const node = {
+ ...baseNode,
+ agent: {
+ ...baseNode.agent,
+ dynamicToolResolvers: [dynamicToolResolver],
+ },
+ };
+ setupMockAgentForToolExecution("wired_dynamic_tool", {});
+ const stepInput = {
+ createRuntime: () => createNoopRuntime(),
+ instrumentation: undefined,
+ mode: "task" as const,
+ modelResolutionScope: { moduleMap: { nodes: {} }, nodeId: undefined },
+ node,
+ };
+ const step = createExecutionNodeStep(stepInput);
+
+ const responder = {
+ attributes: {},
+ authenticator: "test",
+ issuer: "test",
+ principalId: "user-1",
+ principalType: "user" as const,
+ };
+ const ctx = new ContextContainer();
+ ctx.set(AuthKey, responder);
+ ctx.set(InitiatorAuthKey, null);
+ ctx.set(BundleKey, {
+ compiledArtifactsSource: createBundledRuntimeCompiledArtifactsSource(),
+ } as never);
+ ctx.set(ChannelKey, { kind: "http" });
+ ctx.set(SessionIdKey, "sess-dynamic");
+ ctx.set(SessionKey, {
+ auth: { current: responder, initiator: null },
+ sessionId: "sess-dynamic",
+ turn: { id: "turn-1", sequence: 1 },
+ });
+ ctx.set(StepDynamicToolMetadataKey, [
+ {
+ callbacks: {
+ approvalRequest: {
+ closure: { version: "persisted-request" },
+ stepId: "eve:dynamic-tool//old/approval-request/0-100",
+ },
+ execute: {
+ closure: { version: "persisted-execute" },
+ stepId: "eve:dynamic-tool//old/execute/0-100",
+ },
+ },
+ description: "Old dynamic tool.",
+ entryKey: "wired_dynamic_tool",
+ inputSchema: { type: "object" },
+ name: "wired_dynamic_tool",
+ resolverSlug: "wired",
+ } satisfies OldSourceOffsetDynamicToolMetadata,
+ ]);
+ const session = appendPendingInputBatch({
+ requests: [
+ {
+ action: {
+ callId: "call-wired",
+ input: {},
+ kind: "tool-call",
+ toolName: "wired_dynamic_tool",
+ },
+ allowFreeform: false,
+ display: "confirmation",
+ kind: "tool-approval",
+ options: [
+ { id: "approve", label: "Approve" },
+ { id: "cancel", label: "Cancel" },
+ ],
+ prompt: "Approve dynamic tool",
+ requestId: "approval-wired",
+ },
+ ],
+ responseMessages: [
+ {
+ content: [
+ {
+ input: {},
+ toolCallId: "call-wired",
+ toolName: "wired_dynamic_tool",
+ type: "tool-call",
+ },
+ {
+ approvalId: "approval-wired",
+ toolCallId: "call-wired",
+ type: "tool-approval-request",
+ },
+ ],
+ role: "assistant",
+ },
+ ],
+ session: createSession({
+ continuationToken: "test-dynamic",
+ sessionId: "sess-dynamic",
+ turnAgent: node.turnAgent,
+ }),
+ });
+
+ await contextStorage.run(ctx, () =>
+ step(session, {
+ attributedInputResponses: [
+ {
+ auth: responder,
+ response: { optionId: "approve", requestId: "approval-wired" },
+ },
+ ],
+ }),
+ );
+
+ expect(handler).toHaveBeenCalledOnce();
+ expect(executeCallback).toHaveBeenCalledWith(
+ { version: "persisted-execute" },
+ {},
+ expect.objectContaining({ callId: "call-wired_dynamic_tool" }),
+ );
+ });
+
it("records visible subagent tools as pending runtime actions", async () => {
setupMockAgentForToolCall("child-agent", { task: "Delegate this." });
diff --git a/packages/eve/src/execution/node-step.ts b/packages/eve/src/execution/node-step.ts
index dfe07a255..478305758 100644
--- a/packages/eve/src/execution/node-step.ts
+++ b/packages/eve/src/execution/node-step.ts
@@ -2,6 +2,7 @@ import type { LanguageModel } from "ai";
import type { Runtime, SessionCapabilities } from "#channel/types.js";
import { dispatchDynamicModelEvent } from "#context/dynamic-model-lifecycle.js";
+import { preparePersistedStepDynamicToolMetadata } from "#context/dynamic-tool-lifecycle.js";
import {
createBackgroundSubagentHarnessDefinition,
createHarnessDelegationToolDefinition,
@@ -115,6 +116,11 @@ export function createExecutionNodeStep(input: CreateExecutionNodeStepInput): St
instrumentation: sessionInstrumentation,
mode: input.mode,
onCompaction: preserveFrameworkStateOnCompaction,
+ prepareStepDynamicTools: (prepareInput) =>
+ preparePersistedStepDynamicToolMetadata({
+ ...prepareInput,
+ resolvers: input.node.agent.dynamicToolResolvers ?? [],
+ }),
dispatchDynamicModelEvent: dispatchModelEvent,
resolveModel,
runtimeIdentity: buildRuntimeIdentity(input.node),
diff --git a/packages/eve/src/harness/approval-delivery-coordinator.ts b/packages/eve/src/harness/approval-delivery-coordinator.ts
index 63f9c2c34..1a676c758 100644
--- a/packages/eve/src/harness/approval-delivery-coordinator.ts
+++ b/packages/eve/src/harness/approval-delivery-coordinator.ts
@@ -95,6 +95,29 @@ export function shouldPrepareApprovalPolicyTools(input: {
);
}
+/** Returns whether this invocation can replay a previously approved tool call. */
+export function shouldPrepareApprovalReplayTools(input: {
+ readonly now?: number;
+ readonly session: HarnessSession;
+ readonly stepInput?: StepInput;
+}): boolean {
+ if (shouldPrepareApprovalPolicyTools(input)) return true;
+
+ const approvedRequestIds = new Set(
+ [
+ ...(input.stepInput?.attributedInputResponses ?? []).map(({ response }) => response),
+ ...(input.stepInput?.inputResponses ?? []),
+ ]
+ .filter((response) => response.optionId === "approve")
+ .map((response) => response.requestId),
+ );
+ return getPendingInputBatches(input.session.state).some((batch) =>
+ batch.requests.some(
+ (request) => isApprovalRequest(request) && approvedRequestIds.has(request.requestId),
+ ),
+ );
+}
+
export async function coordinateApprovalDelivery(input: {
readonly now?: number;
readonly session: HarnessSession;
diff --git a/packages/eve/src/harness/tool-loop-generate-approval-resume.integration.test.ts b/packages/eve/src/harness/tool-loop-generate-approval-resume.integration.test.ts
index 8a2747b18..9e5fb1c72 100644
--- a/packages/eve/src/harness/tool-loop-generate-approval-resume.integration.test.ts
+++ b/packages/eve/src/harness/tool-loop-generate-approval-resume.integration.test.ts
@@ -2,10 +2,20 @@ import { jsonSchema, type LanguageModel, type ModelMessage, simulateReadableStre
import { MockLanguageModelV4 } from "ai/test";
import { describe, expect, it, vi } from "vitest";
+import { ContextContainer, contextStorage } from "#context/container.js";
+import {
+ dispatchDynamicToolEvent,
+ preparePersistedStepDynamicToolMetadata,
+} from "#context/dynamic-tool-lifecycle.js";
+import type { OldSourceOffsetDynamicToolMetadata } from "#context/dynamic-tool-metadata.js";
+import { AuthKey, SessionKey, StepDynamicToolMetadataKey } from "#context/keys.js";
+import { setHarnessEmissionState } from "#harness/emission.js";
import { appendPendingInputBatch } from "#harness/input-requests.js";
import { createToolLoopHarness } from "#harness/tool-loop.js";
import { setTurnUsageState } from "#harness/turn-tag-state.js";
import type { HarnessSession, ToolLoopHarnessConfig } from "#harness/types.js";
+import { defineTool } from "#tools/definition.js";
+import { stampDurableDynamicCallback } from "#tools/durable-callbacks.js";
const usage = {
inputTokens: {
@@ -68,7 +78,10 @@ const secondApprovalRequest = {
type: "tool-approval-request" as const,
};
-function createPendingApprovalSession(history?: readonly ModelMessage[]): HarnessSession {
+function createPendingApprovalSession(
+ history?: readonly ModelMessage[],
+ responseAuthorization = false,
+): HarnessSession {
const session: HarnessSession = {
agent: {
modelReference: { id: "generate-approval-resume-model" },
@@ -107,6 +120,9 @@ function createPendingApprovalSession(history?: readonly ModelMessage[]): Harnes
requestId: approvalRequest.approvalId,
},
],
+ responseAuthRequiredRequestIds: responseAuthorization
+ ? [approvalRequest.approvalId]
+ : undefined,
responseMessages: [
{
content: [toolCall, approvalRequest],
@@ -207,6 +223,236 @@ function findPart(
}
describe("tool loop generate approval resume (real AI SDK)", () => {
+ it.each([
+ { label: "direct", responseAuthorization: false },
+ { label: "response-authorized", responseAuthorization: true },
+ ])("keeps a migrated step callback binding through $label approval", async (testCase) => {
+ const order: string[] = [];
+ const executeCallback = vi.fn(async (closure: unknown) => {
+ const version = (closure as { version: string }).version;
+ order.push(`execute:${version}`);
+ return "/workspace";
+ });
+ const approvalResponseCallback = vi.fn(async (closure: unknown) => {
+ const version = (closure as { version: string }).version;
+ order.push(`authorize:${version}`);
+ return { status: "allowed" as const };
+ });
+ const handler = vi.fn((event: { data?: { stepIndex?: number; turnId?: string } }) => {
+ order.push(`resolve:${String(event.data?.turnId)}:${String(event.data?.stepIndex)}`);
+ return {
+ bash: defineTool({
+ approval: {
+ request: stampDurableDynamicCallback(() => "user-approval" as const, {
+ callback: () => "user-approval" as const,
+ closure: { version: "current-request" },
+ }),
+ response: stampDurableDynamicCallback(() => ({ status: "allowed" as const }), {
+ callback: approvalResponseCallback,
+ closure: { version: "current-response" },
+ }),
+ },
+ description: "Run a shell command.",
+ execute: stampDurableDynamicCallback(async () => "/current-workspace", {
+ callback: executeCallback,
+ closure: { version: "current-execute" },
+ }),
+ inputSchema: { type: "object" },
+ }),
+ };
+ });
+ const resolver = {
+ eventNames: ["step.started"],
+ events: {
+ "step.started": handler,
+ },
+ logicalPath: "agent/tools/bash.ts",
+ slug: "legacy",
+ sourceId: "test:legacy-bash",
+ sourceKind: "module",
+ } as never;
+ const ctx = new ContextContainer();
+ const responder = {
+ attributes: {},
+ authenticator: "test",
+ issuer: "test",
+ principalId: "user-1",
+ principalType: "user" as const,
+ };
+ ctx.set(AuthKey, responder);
+ ctx.set(SessionKey, {
+ auth: { current: responder, initiator: null },
+ sessionId: "generate-approval-resume-session",
+ turn: { id: "turn-1", sequence: 1 },
+ });
+ ctx.set(StepDynamicToolMetadataKey, [
+ {
+ callbacks: {
+ approvalRequest: {
+ closure: { version: "persisted-request" },
+ stepId: "eve:dynamic-tool//old/approval-request/0-100",
+ },
+ approvalResponse: {
+ closure: { version: "persisted-response" },
+ stepId: "eve:dynamic-tool//old/approval-response/0-100",
+ },
+ execute: {
+ closure: { version: "persisted-execute" },
+ stepId: "eve:dynamic-tool//old/execute/0-100",
+ },
+ },
+ description: "Old shell tool.",
+ entryKey: "bash",
+ inputSchema: { type: "object" },
+ name: "bash",
+ resolverSlug: "legacy",
+ } satisfies OldSourceOffsetDynamicToolMetadata,
+ ]);
+
+ const model = new MockLanguageModelV4({
+ doStream: textStreamResult("The command completed."),
+ modelId: "generate-approval-resume-model",
+ provider: "eve-integration-mock",
+ });
+ const config = {
+ handleEvent: async (event, messages) => {
+ await dispatchDynamicToolEvent({
+ ctx,
+ event,
+ messages: messages ?? [],
+ resolvers: [resolver],
+ });
+ if (event.type === "step.started") {
+ const metadata = ctx.get(StepDynamicToolMetadataKey) ?? [];
+ const version = (
+ metadata[0]?.callbacks?.execute?.closure as { version?: string } | undefined
+ )?.version;
+ order.push(`step.started:${String(version)}`);
+ }
+ },
+ mode: "conversation",
+ prepareStepDynamicTools: (input) =>
+ preparePersistedStepDynamicToolMetadata({ ...input, resolvers: [resolver] }),
+ resolveModel: async (): Promise<LanguageModel> => model,
+ tools: new Map(),
+ } satisfies ToolLoopHarnessConfig;
+ const session = setHarnessEmissionState(
+ createPendingApprovalSession(undefined, testCase.responseAuthorization),
+ {
+ sequence: 1,
+ sessionStarted: true,
+ stepIndex: 1,
+ turnId: "turn-1",
+ },
+ );
+ const runStep = createToolLoopHarness(config);
+
+ const first = await contextStorage.run(ctx, () =>
+ runStep(session, {
+ attributedInputResponses: [
+ {
+ auth: responder,
+ response: { optionId: "approve", requestId: approvalRequest.approvalId },
+ },
+ ],
+ }),
+ );
+ if (testCase.responseAuthorization) {
+ if (typeof first.next !== "function") {
+ throw new TypeError("Expected response authorization to schedule a continuation.");
+ }
+ const next = first.next;
+ await contextStorage.run(ctx, () => next(first.session));
+ } else {
+ expect(first.next).toBeNull();
+ }
+
+ expect(order).toEqual(
+ testCase.responseAuthorization
+ ? [
+ "resolve:turn-1:1",
+ "authorize:persisted-response",
+ "step.started:persisted-execute",
+ "execute:persisted-execute",
+ ]
+ : ["resolve:turn-1:1", "step.started:persisted-execute", "execute:persisted-execute"],
+ );
+ expect(handler).toHaveBeenCalledOnce();
+ if (testCase.responseAuthorization) {
+ expect(approvalResponseCallback).toHaveBeenCalledWith(
+ { version: "persisted-response" },
+ expect.anything(),
+ );
+ } else {
+ expect(approvalResponseCallback).not.toHaveBeenCalled();
+ }
+ expect(executeCallback).toHaveBeenCalledWith(
+ { version: "persisted-execute" },
+ toolCall.input,
+ expect.objectContaining({ callId: toolCall.toolCallId }),
+ );
+ const metadata = ctx.get(StepDynamicToolMetadataKey) ?? [];
+ expect(metadata[0]?.callbacks?.execute).toEqual({
+ closure: { version: "persisted-execute" },
+ });
+ });
+
+ it("does not resolve removed dynamic tools when an approval is cancelled", async () => {
+ const responder = {
+ attributes: {},
+ authenticator: "test",
+ issuer: "test",
+ principalId: "user-1",
+ principalType: "user" as const,
+ };
+ const ctx = new ContextContainer();
+ ctx.set(AuthKey, responder);
+ ctx.set(SessionKey, {
+ auth: { current: responder, initiator: null },
+ sessionId: "generate-approval-resume-session",
+ turn: { id: "turn-1", sequence: 1 },
+ });
+ ctx.set(StepDynamicToolMetadataKey, [
+ {
+ callbacks: {
+ execute: {
+ closure: { version: "persisted-execute" },
+ stepId: "eve:dynamic-tool//old/execute/0-100",
+ },
+ },
+ description: "Removed shell tool.",
+ entryKey: "bash",
+ inputSchema: { type: "object" },
+ name: "bash",
+ resolverSlug: "removed",
+ } satisfies OldSourceOffsetDynamicToolMetadata,
+ ]);
+ const execute = vi.fn(async () => "/workspace");
+ const prepareStepDynamicTools = vi.fn((input) =>
+ preparePersistedStepDynamicToolMetadata({ ...input, resolvers: [] }),
+ );
+ const runStep = createToolLoopHarness({
+ ...createConfig(createModel(), execute),
+ prepareStepDynamicTools,
+ });
+
+ await expect(
+ contextStorage.run(ctx, () =>
+ runStep(createPendingApprovalSession(undefined, true), {
+ attributedInputResponses: [
+ {
+ auth: responder,
+ response: { optionId: "cancel", requestId: approvalRequest.approvalId },
+ },
+ ],
+ }),
+ ),
+ ).resolves.toBeDefined();
+
+ expect(prepareStepDynamicTools).not.toHaveBeenCalled();
+ expect(execute).not.toHaveBeenCalled();
+ });
+
it("executes two approvals delivered together exactly once each", async () => {
const execute = vi.fn(async (input: unknown) =>
(input as { command: string }).command === "pwd" ? "/workspace" : "eve",
diff --git a/packages/eve/src/harness/tool-loop.ts b/packages/eve/src/harness/tool-loop.ts
index 4bce8b9fa..e22a66634 100644
--- a/packages/eve/src/harness/tool-loop.ts
+++ b/packages/eve/src/harness/tool-loop.ts
@@ -139,6 +139,7 @@ import {
import {
coordinateApprovalDelivery,
shouldPrepareApprovalPolicyTools,
+ shouldPrepareApprovalReplayTools,
} from "#harness/approval-delivery-coordinator.js";
import type { InstrumentationAttempt, InstrumentationStepScope } from "#instrumentation/runtime.js";
import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
@@ -654,11 +655,11 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
const approvalContext = contextStorage.getStore();
if (
+ shouldPrepareApprovalReplayTools({ session, stepInput: effectiveStepInput }) &&
approvalContext !== undefined &&
- config.resolveStepDynamicTools !== undefined &&
- shouldPrepareApprovalPolicyTools({ session, stepInput: effectiveStepInput })
+ config.prepareStepDynamicTools !== undefined
) {
- await config.resolveStepDynamicTools({
+ await config.prepareStepDynamicTools({
ctx: approvalContext,
event: createStepStartedEvent({
modelId: session.agent.modelReference?.id ?? "dynamic",
@@ -669,13 +670,20 @@ export function createToolLoopHarness(config: ToolLoopHarnessConfig): StepFn {
messages: projectHistory(resolvedRuntimeActions.messages, session.state),
});
}
+ // Only persisted policy work can invoke a dynamic tool's approval.response callback.
+ const responseAuthorizationTools = shouldPrepareApprovalPolicyTools({
+ session,
+ stepInput: effectiveStepInput,
+ })
+ ? buildResponseAuthorizationTools({
+ authoredTools: config.tools,
+ context: approvalContext,
+ })
+ : config.tools;
const coordinated = await coordinateApprovalDelivery({
session,
stepInput: effectiveStepInput,
- tools: buildResponseAuthorizationTools({
- authoredTools: config.tools,
- context: approvalContext,
- }),
+ tools: responseAuthorizationTools,
});
session = coordinated.session;
if (emit) {
diff --git a/packages/eve/src/harness/types.ts b/packages/eve/src/harness/types.ts
index 270f0acb0..21ab01143 100644
--- a/packages/eve/src/harness/types.ts
+++ b/packages/eve/src/harness/types.ts
@@ -2,7 +2,11 @@ import type { LanguageModel, ModelMessage, UserContent } from "ai";
import type { SessionAuthContext, SessionCapabilities } from "#channel/types.js";
import type { AlsContext } from "#context/container.js";
-import type { UnstampedMessageStreamEvent, RuntimeIdentity } from "#protocol/message.js";
+import type {
+ RuntimeIdentity,
+ StepStartedStreamEvent,
+ UnstampedMessageStreamEvent,
+} from "#protocol/message.js";
import type { RunMode } from "#shared/run-mode.js";
import type { RuntimeActionResult } from "#shared/action-types.js";
import type { RuntimeModelReference } from "#runtime/agent/bootstrap.js";
@@ -326,10 +330,10 @@ export interface ToolLoopHarnessConfig {
* compacted history.
*/
readonly onCompaction?: () => readonly ModelMessage[];
- /** Resolves step-scoped dynamic tools once for approval policy and model work. */
- readonly resolveStepDynamicTools?: (input: {
+ /** Prepares persisted step-scoped tools before an approved call is resumed. */
+ readonly prepareStepDynamicTools?: (input: {
readonly ctx: AlsContext;
- readonly event: UnstampedMessageStreamEvent;
+ readonly event: StepStartedStreamEvent;
readonly messages: readonly ModelMessage[];
}) => Promise<void>;
readonly dispatchDynamicModelEvent?: (input: {
diff --git a/packages/eve/src/tools/durable-callbacks.ts b/packages/eve/src/tools/durable-callbacks.ts
index 397190e3d..ff6b54252 100644
--- a/packages/eve/src/tools/durable-callbacks.ts
+++ b/packages/eve/src/tools/durable-callbacks.ts
@@ -17,6 +17,7 @@ export type DurableDynamicCallbackFn = (closure: JsonObject, ...args: never[]) =
*/
export interface DurableDynamicCallbackReference {
readonly closure: JsonObject;
+ readonly stepId?: never;
}
export interface DurableDynamicToolCallbacks {