Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

perf(eve): remove durable steps from ordinary session turns (#4188)

Andrew Barba528483fad06a
diff --git a/.changeset/fewer-durable-steps.md b/.changeset/fewer-durable-steps.md
new file mode 100644
index 000000000..7e2b89cad
--- /dev/null
+++ b/.changeset/fewer-durable-steps.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Session turns, cancellations, and session endings run fewer durable workflow steps, so replies arrive sooner, especially for subagent sessions and sessions that do not start background work.
diff --git a/packages/eve/src/execution/session/entry.integration.test.ts b/packages/eve/src/execution/session/entry.integration.test.ts
index 3b9b2d426..e4f1ea542 100644
--- a/packages/eve/src/execution/session/entry.integration.test.ts
+++ b/packages/eve/src/execution/session/entry.integration.test.ts
@@ -33,6 +33,7 @@ import {
expectHookClaims,
expectSingleTurn,
listCallerStepNames,
+ listConditionalStepNames,
withTimeout,
} from "#internal/testing/entry-test-helpers.js";
import { captureConsoleOutput, workflowSdkNotice } from "#internal/testing/log-records.js";
@@ -270,6 +271,8 @@ describe("workflowEntry integration", () => {
await expect(run.returnValue).resolves.toEqual({ output: "" });
completed = true;
expect(await listCallerStepNames(run.runId)).toEqual([]);
+ // Two ordinary turns and a reset have no runs, tasks, or caller to act on.
+ expect(await listConditionalStepNames(run.runId)).toEqual([]);
} finally {
stream.dispose();
if (!completed) await run.cancel();
@@ -577,8 +580,6 @@ describe("workflowEntry integration", () => {
],
});
expect(await listCallerStepNames(child.runId)).toEqual([
- "bindTurnCallerContextStep",
- "bindTurnCallerContextStep",
"notifyTurnCallerStep",
"notifyTurnCallerStep",
"resolveInitialTurnCallerStep",
diff --git a/packages/eve/src/execution/session/entry.ts b/packages/eve/src/execution/session/entry.ts
index 174b41d71..91227f2e0 100644
--- a/packages/eve/src/execution/session/entry.ts
+++ b/packages/eve/src/execution/session/entry.ts
@@ -92,7 +92,7 @@ async function bootInitialOwner(
nodeId?: string;
};
try {
- const [sessionCreation, stableClaim, aliasClaim] = await Promise.allSettled([
+ const [sessionCreation, stableClaim, aliasClaim, callerResolution] = await Promise.allSettled([
createSessionStep({
compiledArtifactsSource: serializedBundle.source,
continuationToken,
@@ -107,6 +107,9 @@ async function bootInitialOwner(
}),
inbox.claimSessionHook(sessionCommandHookToken(sessionId)),
continuationToken === "" ? Promise.resolve() : inbox.claimSessionHook(continuationToken),
+ hasDelegatedSessionContext(serializedContext)
+ ? resolveInitialTurnCallerStep({ serializedContext })
+ : Promise.resolve(undefined),
]);
if (sessionCreation.status === "rejected") throw sessionCreation.reason;
if (stableClaim.status === "rejected") throw stableClaim.reason;
@@ -121,13 +124,12 @@ async function bootInitialOwner(
await inbox.dispose();
return undefined;
}
+ if (callerResolution.status === "rejected") throw callerResolution.reason;
return {
inbox,
session: {
anchor: { kind: "self" },
- caller: hasDelegatedSessionContext(serializedContext)
- ? await resolveInitialTurnCallerStep({ serializedContext })
- : undefined,
+ caller: callerResolution.value,
capabilities: serializedContext["eve.capabilities"] as SessionCapabilities | undefined,
deploymentId: input.ownerDeploymentId,
history: sessionCreation.value.history,
diff --git a/packages/eve/src/execution/session/finalization.test.ts b/packages/eve/src/execution/session/finalization.test.ts
index 36c98bf1c..604bef6e6 100644
--- a/packages/eve/src/execution/session/finalization.test.ts
+++ b/packages/eve/src/execution/session/finalization.test.ts
@@ -1,6 +1,8 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
import { finalizeSession } from "#execution/session/finalization.js";
import { createDurableSessionState } from "#execution/durable-session-store.js";
+import { writeTaskTable } from "#execution/tasks/table.js";
+import { terminateChildSessionsStep } from "#execution/terminate-child-sessions-step.js";
import { setTurnUsageState, takeSessionUsageDelta } from "#harness/turn-tag-state.js";
import type { HarnessSession } from "#harness/types.js";
import { emitTerminalSessionCompletionStep } from "#execution/terminal-session-completion-step.js";
@@ -32,18 +34,40 @@ function withUsage(session: HarnessSession, inputTokens: number): HarnessSession
return setTurnUsageState(session, { ...totals, session: totals, turnId: "current" });
}
-function sessionWithUnreportedUsage() {
- const session: HarnessSession = {
+function baseSession(): HarnessSession {
+ return {
agent: { modelReference: { id: "unused" }, system: "", tools: [] },
compaction: { recentWindowSize: 10, threshold: 100_000 },
continuationToken: "detector",
history: [],
sessionId: "detector",
};
+}
+
+function sessionWithUnreportedUsage() {
+ const session = baseSession();
const previouslySettled = takeSessionUsageDelta(withUsage(session, 100)).session;
return createDurableSessionState({ session: withUsage(previouslySettled, 250) });
}
+function sessionWithTaskRun() {
+ return createDurableSessionState({
+ session: writeTaskTable(baseSession(), {
+ tasks: [
+ {
+ calls: [{ callId: "call-1", turnId: "turn_0" }],
+ id: "task-1",
+ kind: "agent",
+ name: "researcher",
+ resumable: false,
+ results: [],
+ run: { hookToken: "hook-1", runId: "run-1", started: true },
+ },
+ ],
+ }),
+ });
+}
+
beforeEach(() => vi.clearAllMocks());
describe("session finalization with an unsettled caller", () => {
@@ -105,6 +129,19 @@ describe("session finalization with an unsettled caller", () => {
});
});
+ it("terminates child sessions when a task run is live", async () => {
+ const sessionState = sessionWithTaskRun();
+ await finalizeSession(
+ { kind: "expired" },
+ {
+ caller: undefined,
+ cursor: { serializedContext: {}, sessionState },
+ sessionWritable: new WritableStream(),
+ },
+ );
+ expect(terminateChildSessionsStep).toHaveBeenCalledExactlyOnceWith({ sessionState });
+ });
+
it("does not notify again when an already settled conversation expires", async () => {
const result = await finalizeSession(
{ kind: "expired" },
diff --git a/packages/eve/src/execution/session/finalization.ts b/packages/eve/src/execution/session/finalization.ts
index 80c66f18c..4befac6bd 100644
--- a/packages/eve/src/execution/session/finalization.ts
+++ b/packages/eve/src/execution/session/finalization.ts
@@ -3,6 +3,7 @@ import type { DurableSessionState } from "#execution/durable-session-store.js";
import { emitTerminalSessionCompletionStep } from "#execution/terminal-session-completion-step.js";
import { emitTerminalSessionFailureStep } from "#execution/terminal-session-failure-step.js";
import { terminateChildSessionsStep } from "#execution/terminate-child-sessions-step.js";
+import { liveTaskRuns, readTaskTable } from "#execution/tasks/table.js";
import type { TurnOutcome } from "#execution/session/turn-step-types.js";
import { normalizeSerializableError } from "#execution/workflow-errors.js";
import type { WorkflowEntryResult } from "#execution/session/entry-input.js";
@@ -34,7 +35,11 @@ export async function finalizeSession(
context: SessionFinalizationContext,
): Promise<WorkflowEntryResult> {
const { serializedContext, sessionState } = context.cursor;
- if (sessionState !== undefined) {
+ // Most sessions end with no task run, so the step that would find nothing to stop is skipped.
+ if (
+ sessionState !== undefined &&
+ liveTaskRuns(readTaskTable(sessionState.snapshot?.session?.state)).length > 0
+ ) {
await terminateChildSessionsStep({ sessionState });
}
const session = sessionState?.snapshot.session;
diff --git a/packages/eve/src/execution/session/pending-turn-state.test.ts b/packages/eve/src/execution/session/pending-turn-state.test.ts
new file mode 100644
index 000000000..9f4c41ef7
--- /dev/null
+++ b/packages/eve/src/execution/session/pending-turn-state.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import type { ModelMessage } from "ai";
+import { derivePendingState } from "#execution/session/pending-turn-state.js";
+import { setPendingCoordinationBatch } from "#harness/coordination.js";
+import type { HarnessSession } from "#harness/types.js";
+import type { RuntimeWorkflowTaskRequest } from "#shared/action-types.js";
+import { TASK_WAIT_TOOL_NAME } from "#protocol/task-tools.js";
+
+const session: HarnessSession = {
+ agent: { modelReference: { id: "test-model" }, system: "", tools: [] },
+ compaction: { recentWindowSize: 10, threshold: 100_000 },
+ continuationToken: "http:test-session",
+ history: [],
+ sessionId: "test-session",
+};
+
+const waitCall: ModelMessage = {
+ content: [
+ { input: {}, toolCallId: "wait-call", toolName: TASK_WAIT_TOOL_NAME, type: "tool-call" },
+ ],
+ role: "assistant",
+};
+
+const deployRun: RuntimeWorkflowTaskRequest = {
+ callId: "deploy-call",
+ entry: { entryPoint: "execute" },
+ input: { service: "api" },
+ kind: "workflow-task",
+ toolName: "deploy",
+ workflowId: "workflow//./agent/tools/deploy//execute",
+};
+
+function parked(tasks: readonly RuntimeWorkflowTaskRequest[]): HarnessSession {
+ return setPendingCoordinationBatch({
+ event: { sequence: 0, stepIndex: 0, turnId: "turn_0" },
+ responseMessages: [waitCall],
+ session,
+ tasks,
+ });
+}
+
+describe("derivePendingState", () => {
+ it("waits on a task tool call without dispatching anything", () => {
+ expect(derivePendingState(parked([]))).toMatchObject({
+ hasRunsToDispatch: false,
+ pendingCoordinationCallIds: ["wait-call"],
+ });
+ });
+
+ it("dispatches the workflow tool runs a batch holds beside its task tool calls", () => {
+ expect(derivePendingState(parked([deployRun]))).toMatchObject({
+ hasRunsToDispatch: true,
+ pendingCoordinationCallIds: ["deploy-call", "wait-call"],
+ });
+ });
+});
diff --git a/packages/eve/src/execution/session/pending-turn-state.ts b/packages/eve/src/execution/session/pending-turn-state.ts
index 64ae7ab2f..8f3bb51ef 100644
--- a/packages/eve/src/execution/session/pending-turn-state.ts
+++ b/packages/eve/src/execution/session/pending-turn-state.ts
@@ -9,6 +9,8 @@ export function derivePendingState(session: HarnessSession): {
readonly authorizationAttemptIds?: readonly string[];
readonly hasPendingAuthorization: boolean;
readonly hasPendingInputBatch: boolean;
+ /** The pending batch has workflow tool runs to start; task tool calls are answered by the session. */
+ readonly hasRunsToDispatch?: boolean;
readonly pendingCoordinationCallIds?: readonly string[];
readonly pendingTaskToolCalls?: readonly TaskToolCall[];
} {
@@ -24,6 +26,7 @@ export function derivePendingState(session: HarnessSession): {
if (batch === undefined) return base;
return {
...base,
+ hasRunsToDispatch: batch.tasks.length > 0,
pendingCoordinationCallIds: pendingCoordinationCallIds(batch),
pendingTaskToolCalls: pendingTaskToolCalls(batch.responseMessages),
};
diff --git a/packages/eve/src/execution/session/program.ts b/packages/eve/src/execution/session/program.ts
index 69e60620e..69f061d2e 100644
--- a/packages/eve/src/execution/session/program.ts
+++ b/packages/eve/src/execution/session/program.ts
@@ -1,7 +1,6 @@
import type { DeliverHookPayload, SessionCapabilities, TurnCaller } from "#channel/types.js";
import type { AgentWorkflowRetentionDefinition } from "#shared/agent-definition.js";
import {
- bindTurnCallerContextStep,
notifyCancelledTaskCallerStep,
notifyTurnCallerStep,
resolveInitialTurnCallerStep,
@@ -9,7 +8,6 @@ import {
import type { DurableSessionState } from "#execution/durable-session-store.js";
import type { HarnessModelMessage } from "#harness/messages.js";
import { nextTurnDelivery, type NextTurnInstruction } from "#execution/session/next-input.js";
-import { cancelDescendantTurnsStep } from "#execution/cancel-descendant-turns-step.js";
import { SessionInputQueue } from "#execution/session/input-queue.js";
import { SessionExecution } from "#execution/session/turn.js";
import { SessionStateCursor } from "#execution/session/state-cursor.js";
@@ -236,11 +234,6 @@ async function runSessionLoop(
let turnIndex = 0;
const runTurn = async (payload: TurnStepPayload | undefined): Promise<TurnOutcome> => {
const caller = progress.caller;
- if (caller !== undefined) {
- await cursor.advance((state) =>
- bindTurnCallerContextStep({ caller, serializedContext: state.serializedContext }),
- );
- }
progress.turnId = `turn_${String(turnIndex++)}`;
const outcome = await execution.runTurn(payload, { caller });
if (outcome.caller !== undefined) progress.caller = outcome.caller;
@@ -308,13 +301,14 @@ async function runSessionLoop(
}
if (action.cancelled === true) {
- const cancelledCaller = { caller: progress.caller, sessionId: boot.sessionId };
- const settled = await settleCancelledTurn(progress.caller !== undefined);
- await notifyCancelledTaskCallerStep(
- settled.usage === undefined
- ? cancelledCaller
- : { ...cancelledCaller, usage: settled.usage },
- );
+ const { caller } = progress;
+ const settled = await settleCancelledTurn(caller !== undefined);
+ if (caller !== undefined) {
+ const notification = { caller, sessionId: boot.sessionId };
+ await notifyCancelledTaskCallerStep(
+ settled.usage === undefined ? notification : { ...notification, usage: settled.usage },
+ );
+ }
} else if (action.settled !== undefined) {
if (progress.caller !== undefined) {
await notifyTurnCallerStep({
@@ -339,10 +333,7 @@ async function runSessionLoop(
action = await runTurn({ control: next.kind });
continue;
case "cancel-turn":
- await cancelDescendantTurnsStep({
- sessionState: cursor.sessionState,
- });
- await cancelWorkingTasks(cursor, "turn_cancelled");
+ await execution.cancelTurnWork();
await settleCancelledTurn(false);
// Cancellation consumes any outstanding caller; do not report the prior turn.
action = { ...action, settled: undefined };
diff --git a/packages/eve/src/execution/session/turn-step-result.ts b/packages/eve/src/execution/session/turn-step-result.ts
index 0d4fab4bb..c32eef643 100644
--- a/packages/eve/src/execution/session/turn-step-result.ts
+++ b/packages/eve/src/execution/session/turn-step-result.ts
@@ -49,10 +49,9 @@ export function resolveSessionStepResult(
}
if (stepResult.next === null) {
- const { pendingCoordinationCallIds, pendingTaskToolCalls } = derivePendingState(
- stepResult.session,
- );
- const pending = { pendingCoordinationCallIds, pendingTaskToolCalls };
+ const { hasRunsToDispatch, pendingCoordinationCallIds, pendingTaskToolCalls } =
+ derivePendingState(stepResult.session);
+ const pending = { hasRunsToDispatch, pendingCoordinationCallIds, pendingTaskToolCalls };
// Usage stays unreported until the turn settles, so the caller's result includes all of it.
if (stepResult.settledTurn !== undefined) {
diff --git a/packages/eve/src/execution/session/turn-step-types.ts b/packages/eve/src/execution/session/turn-step-types.ts
index 9b92b080d..d1d2dac55 100644
--- a/packages/eve/src/execution/session/turn-step-types.ts
+++ b/packages/eve/src/execution/session/turn-step-types.ts
@@ -29,6 +29,8 @@ export interface TurnStepPayload {
/** Input for one atomic, session-owner-executed turn step. */
export interface TurnStepInput {
readonly abortSignal?: AbortSignal;
+ /** The delegated caller to bind into the context before the step runs; sent on a turn's first step. */
+ readonly caller?: TurnCaller;
readonly steeringSignal?: AbortSignal;
readonly input: TurnStepPayload | undefined;
readonly sessionWritable: WritableStream<Uint8Array>;
@@ -66,6 +68,11 @@ export type DurableStepResult = (
}
| {
readonly action: "park";
+ /**
+ * `false` when every pending call is a task tool call the session answers
+ * itself, so the dispatch step can be skipped. Absent, the step runs.
+ */
+ readonly hasRunsToDispatch?: boolean;
readonly pendingCoordinationCallIds?: readonly string[];
readonly pendingTaskToolCalls?: readonly TaskToolCall[];
readonly settled?: SettledTurn;
diff --git a/packages/eve/src/execution/session/turn-step.ts b/packages/eve/src/execution/session/turn-step.ts
index 49c18657b..02b833488 100644
--- a/packages/eve/src/execution/session/turn-step.ts
+++ b/packages/eve/src/execution/session/turn-step.ts
@@ -80,6 +80,7 @@ import {
} from "#execution/durable-session-store.js";
import { buildRuntimeIdentity, createExecutionNodeStep } from "#execution/node-step.js";
import { prepareWorkflowPreambleTrace } from "#execution/workflow-trace-context.js";
+import { bindTurnCallerContext } from "#subagents/parent-notification.js";
import { resolveEffectiveAgentRuntime } from "#execution/effective-agent-config.js";
import { reconcileSessionContinuationToken } from "#execution/reconcile-session-continuation-token.js";
import { hydrateDurableSession, refreshSessionFromTurnAgent } from "#execution/session.js";
@@ -105,7 +106,12 @@ export type { TurnStepInput };
/** Runs a bounded batch of harness model steps inside one durable `"use step"` boundary. */
export async function turnStep(input: TurnStepInput): Promise<TurnStepResult> {
"use step";
- return await withSessionStateDelta(input, runSessionStep);
+ return await withSessionStateDelta(input, (state) =>
+ runSessionStep({
+ ...state,
+ serializedContext: bindTurnCallerContext(state.caller, state.serializedContext),
+ }),
+ );
}
async function runSessionStep(input: TurnStepInput): Promise<DurableStepResult> {
diff --git a/packages/eve/src/execution/session/turn.test.ts b/packages/eve/src/execution/session/turn.test.ts
index d436d74ba..5ed262294 100644
--- a/packages/eve/src/execution/session/turn.test.ts
+++ b/packages/eve/src/execution/session/turn.test.ts
@@ -138,6 +138,40 @@ describe("SessionExecution checkpoints", () => {
await createExecution({ inbox, sessionState: state("") }).runTurn(undefined);
expect(turnStep).toHaveBeenCalledTimes(2);
});
+ it("binds the delegated caller on the turn's first step only", async () => {
+ const inbox: SessionInbox = {
+ claimedTokens: [],
+ claimSessionHook: vi.fn(),
+ claimSessionHooks: vi.fn(),
+ drain: () => [],
+ hasPending: () => false,
+ whenPending: () => new Promise<void>(() => {}),
+ next: vi.fn(),
+ restore: vi.fn(),
+ onDelivery: () => () => {},
+ onInterrupt: () => () => {},
+ };
+ const caller: TurnCaller = {
+ callId: "call-1",
+ replyTo: { kind: "hook", token: "parent" },
+ subagentName: "researcher",
+ };
+ const callers: (TurnCaller | undefined)[] = [];
+ vi.mocked(turnStep)
+ .mockReset()
+ .mockImplementation(
+ turnStepWork(async (input) => {
+ callers.push(input.caller);
+ return {
+ action: callers.length === 1 ? "continue" : "done",
+ serializedContext: input.serializedContext,
+ sessionState: input.sessionState,
+ };
+ }),
+ );
+ await createExecution({ inbox, sessionState: state("") }).runTurn(undefined, { caller });
+ expect(callers).toEqual([caller, undefined]);
+ });
it.each(["cancel", "reset"] as const)(
"gives %s precedence over generation steering",
async (kind) => {
@@ -427,7 +461,7 @@ describe("SessionExecution checkpoints", () => {
},
);
it("cancels an admitted workflow action when cancellation already arrived at the step boundary", async () => {
- const sessionState = state("");
+ const sessionState = stateWithBlockingRun();
const inbox: SessionInbox = {
claimedTokens: [],
claimSessionHook: vi.fn(),
@@ -927,19 +961,15 @@ describe("SessionExecution checkpoints", () => {
.mockImplementation(
turnStepWork(async () => ({
action: "park",
+ hasRunsToDispatch: false,
pendingCoordinationCallIds: ["wait-call"],
pendingTaskToolCalls: [{ callId: "wait-call", kind: "task_wait" }],
serializedContext: {},
sessionState,
})),
);
- vi.mocked(dispatchCoordinationStep).mockImplementation(
- dispatchWork(async () => ({
- results: [],
- serializedContext: {},
- sessionState,
- })),
- );
+ vi.mocked(dispatchCoordinationStep).mockClear();
+ vi.mocked(cancelDescendantTurnsStep).mockClear();
await expect(
createExecution({ inbox, sessionState }).runTurn({
@@ -949,6 +979,10 @@ describe("SessionExecution checkpoints", () => {
expect(publishTurnWaitingStep).toHaveBeenCalledTimes(1);
expect(publishTurnWaitingStep).toHaveBeenCalledWith(expect.objectContaining({ sessionState }));
+ // Only a task tool call is pending: nothing is dispatched, and the cancel has
+ // no workflow tool run to stop.
+ expect(dispatchCoordinationStep).not.toHaveBeenCalled();
+ expect(cancelDescendantTurnsStep).not.toHaveBeenCalled();
});
it("admits an idle agent task's usage report while the turn waits and counts it", async () => {
@@ -1185,6 +1219,7 @@ describe("SessionExecution checkpoints", () => {
.mockImplementationOnce(
turnStepWork(async () => ({
action: "park",
+ hasRunsToDispatch: false,
pendingCoordinationCallIds: ["wait-call"],
pendingTaskToolCalls: [{ callId: "wait-call", kind: "task_wait" }],
serializedContext: {},
@@ -1263,7 +1298,7 @@ describe("SessionExecution checkpoints", () => {
it("announces a child opened before a cancel ahead of cancelling the turn's work", async () => {
const { inbox, planner } = boundaryRunMessages();
- const sessionState = state("");
+ const sessionState = stateWithBlockingRun();
let interrupt: (payload: SessionInboxPayload) => void = () => {};
inbox.onInterrupt = (handler) => {
interrupt = handler;
@@ -1407,6 +1442,22 @@ function createExecution(input: {
});
}
+/** A session whose turn waits on a workflow tool run, so cancelling it has a run to cancel. */
+function stateWithBlockingRun(): DurableSessionState {
+ const base = state("");
+ return {
+ ...base,
+ snapshot: {
+ session: registerWorkflowToolRun(base.snapshot.session, {
+ address: { hookToken: "hold-control", runId: "hold-run" },
+ callId: "hold-call",
+ origin: { stepIndex: 0, turnId: "turn_0" },
+ toolName: "hold",
+ }),
+ },
+ };
+}
+
function state(continuationToken: string): DurableSessionState {
return createTestSessionState({
continuationToken,
diff --git a/packages/eve/src/execution/session/turn.ts b/packages/eve/src/execution/session/turn.ts
index 7a305760c..9b19f242f 100644
--- a/packages/eve/src/execution/session/turn.ts
+++ b/packages/eve/src/execution/session/turn.ts
@@ -1,6 +1,7 @@
import { sleep } from "#compiled/@workflow/core/index.js";
import type { DeliverHookPayload, SessionCapabilities, TurnCaller } from "#channel/types.js";
+import type { DurableSessionState } from "#execution/durable-session-store.js";
import { cancelDescendantTurnsStep } from "#execution/cancel-descendant-turns-step.js";
import { dispatchCoordinationStep } from "#execution/coordination-dispatch-step.js";
import type { SessionInputQueue } from "#execution/session/input-queue.js";
@@ -39,6 +40,7 @@ import { turnStep } from "#execution/session/turn-step.js";
import { ActiveTurn } from "#execution/session/active-turn.js";
import {
findBlockingWorkflowToolRun,
+ getBlockingWorkflowToolRuns,
isInboxToolResultFromRecordedWorkflowToolRun,
} from "#harness/workflow-tool-runs.js";
import { resolveRuntimeActionResultsForCallIds } from "#runtime/actions/results.js";
@@ -86,8 +88,8 @@ export class SessionExecution {
delivery: TurnStepPayload | undefined,
options: {
/**
- * The delegated caller the turn answers. The session binds it before the
- * turn, including for a first turn whose input carries no caller.
+ * The delegated caller the turn answers, including for a first turn whose
+ * input carries no caller. The turn's first step binds it into the context.
*/
readonly caller?: TurnCaller;
} = {},
@@ -138,13 +140,20 @@ export class SessionExecution {
delivery: TurnStepPayload | undefined,
): Promise<TurnOutcome> {
let nextStepInput: TurnStepPayload | undefined = delivery;
+ // Only the first step binds the caller. A caller that steers in mid-turn is
+ // replied to at its own address (`TurnOutcome.caller`) and is bound by the
+ // next turn, so this turn's forwarding keeps its original caller.
+ let bindCaller = turn.caller;
while (true) {
const { cursor } = this.input;
+ const caller = bindCaller;
+ bindCaller = undefined;
const result = await cursor.advanceWithHistory((state) =>
turnStep({
...state,
abortSignal: turn.signal,
+ caller,
input: nextStepInput,
steeringSignal: turn.steeringSignal,
}),
@@ -194,20 +203,12 @@ export class SessionExecution {
}
if (pendingCallIds !== undefined && result.action === "park") {
- const dispatchResult = await cursor.advance((state) =>
- dispatchCoordinationStep({
- action: result.action,
- workflowToolRunOwner: {
- inbox: sessionInboxHookToken(sessionCommandHookToken(this.input.sessionId)),
- },
- ...state,
- }),
- );
- const initialAcceptedAtMs = dispatchResult.results.length === 0 ? undefined : Date.now();
+ const dispatchResults = result.hasRunsToDispatch === false ? [] : await this.dispatchRuns();
+ const initialAcceptedAtMs = dispatchResults.length === 0 ? undefined : Date.now();
const runtimeResults = await this.waitForRuntimeActionResults({
initialAcceptedAtMs,
- initialResults: dispatchResult.results,
+ initialResults: dispatchResults,
taskToolCalls: result.pendingTaskToolCalls ?? [],
pendingCallIds,
turn,
@@ -226,6 +227,24 @@ export class SessionExecution {
}
}
+ /**
+ * Starts the workflow tool runs a parked step requested, and returns the
+ * results of any that settled at once. Task tool calls need no dispatch: the
+ * session answers them itself.
+ */
+ private async dispatchRuns(): Promise<readonly RuntimeActionResult[]> {
+ const dispatched = await this.input.cursor.advance((state) =>
+ dispatchCoordinationStep({
+ action: "park",
+ workflowToolRunOwner: {
+ inbox: sessionInboxHookToken(sessionCommandHookToken(this.input.sessionId)),
+ },
+ ...state,
+ }),
+ );
+ return dispatched.results;
+ }
+
async handleWorkflowMessage(
message: WorkflowToolRunMessage,
): Promise<RuntimeActionResult | undefined> {
@@ -239,15 +258,24 @@ export class SessionExecution {
});
}
+ /**
+ * Stops the work a cancelled turn leaves behind: the workflow tool runs it
+ * waits on and every working task. A turn that waits on no run, the common
+ * case, skips that durable step.
+ */
+ async cancelTurnWork(): Promise<void> {
+ const { cursor } = this.input;
+ if (mayWaitOnWorkflowToolRuns(cursor.sessionState)) {
+ await cancelDescendantTurnsStep({ sessionState: cursor.sessionState });
+ }
+ await cancelWorkingTasks(cursor, "turn_cancelled");
+ }
+
/** `session.cancel()` stops the turn, the calls it waits on, and every working task. */
private async finishCancelledTurn(turn: ActiveTurn): Promise<TurnOutcome> {
- const { cursor } = this.input;
// A child a run opened before the cancel appears before its task settles as cancelled.
await this.handleBoundaryMessages(turn.takeBoundaryMessages("agent-started"));
- await cancelDescendantTurnsStep({
- sessionState: cursor.sessionState,
- });
- await cancelWorkingTasks(cursor, "turn_cancelled");
+ await this.cancelTurnWork();
return { cancelled: true, kind: "park" };
}
@@ -466,3 +494,12 @@ function startTaskWait(call: Extract<TaskToolCall, { readonly kind: "task_wait"
const timer = timeoutMs === undefined ? undefined : sleep(timeoutMs).then(() => callId);
return { callId, startedAtMs: Date.now(), timedOut: false, timer };
}
+
+/** An unreadable run registry counts as waiting, so the step runs and logs it. */
+function mayWaitOnWorkflowToolRuns(sessionState: DurableSessionState): boolean {
+ try {
+ return getBlockingWorkflowToolRuns(sessionState.snapshot?.session?.state).length > 0;
+ } catch {
+ return true;
+ }
+}
diff --git a/packages/eve/src/internal/testing/entry-test-helpers.ts b/packages/eve/src/internal/testing/entry-test-helpers.ts
index 7683ac1f9..dd20a1985 100644
--- a/packages/eve/src/internal/testing/entry-test-helpers.ts
+++ b/packages/eve/src/internal/testing/entry-test-helpers.ts
@@ -69,14 +69,26 @@ export function expectSingleTurn(events: readonly MessageStreamEvent[], turnId:
expect(new Set(eventTurnIds)).toEqual(new Set([turnId]));
}
-const CALLER_STEP_NAMES = new Set([
- "bindTurnCallerContextStep",
- "notifyTurnCallerStep",
- "resolveInitialTurnCallerStep",
+const CALLER_STEP_NAMES = new Set(["notifyTurnCallerStep", "resolveInitialTurnCallerStep"]);
+
+/** Steps that run only when a session has workflow tool runs, tasks, or a caller to act on. */
+const CONDITIONAL_STEP_NAMES = new Set([
+ "cancelDescendantTurnsStep",
+ "dispatchCoordinationStep",
+ "notifyCancelledTaskCallerStep",
+ "terminateChildSessionsStep",
]);
export async function listCallerStepNames(runId: string): Promise<string[]> {
- return (await listStepNames(runId)).filter((name) => CALLER_STEP_NAMES.has(name)).sort();
+ return await listStepNamesIn(runId, CALLER_STEP_NAMES);
+}
+
+export async function listConditionalStepNames(runId: string): Promise<string[]> {
+ return await listStepNamesIn(runId, CONDITIONAL_STEP_NAMES);
+}
+
+async function listStepNamesIn(runId: string, names: ReadonlySet<string>): Promise<string[]> {
+ return (await listStepNames(runId)).filter((name) => names.has(name)).sort();
}
async function listStepNames(runId: string): Promise<string[]> {
diff --git a/packages/eve/src/subagents/adapter.test.ts b/packages/eve/src/subagents/adapter.test.ts
index 963b829cb..37a4d762c 100644
--- a/packages/eve/src/subagents/adapter.test.ts
+++ b/packages/eve/src/subagents/adapter.test.ts
@@ -8,8 +8,7 @@ import { ContinuationTokenKey, SessionIdKey, SessionInboxKey } from "#context/ke
import { ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
import type { InputRequest } from "#shared/input.js";
import { SUBAGENT_ADAPTER } from "#subagents/adapter.js";
-import { bindTurnCallerContextStep } from "#subagents/parent-notification.js";
-import { runSessionStateStep } from "#internal/testing/session-state-step.js";
+import { bindTurnCallerContext } from "#subagents/parent-notification.js";
const SUBAGENT_INPUT_REQUESTED = SUBAGENT_ADAPTER["input.requested"];
const SUBAGENT_AUTHORIZATION_REQUIRED = SUBAGENT_ADAPTER["authorization.required"];
@@ -160,24 +159,21 @@ describe("SUBAGENT_ADAPTER input.requested handler", () => {
it("forwards continuation HITL to the newly bound parent turn", async () => {
resumeHookMock.mockClear();
- const rebound = await runSessionStateStep(
+ const rebound = bindTurnCallerContext(
{
- caller: {
- callId: "call-continued",
- replyTo: { kind: "hook", token: "parent-token-current" },
- subagentName: "linear",
- },
- serializedContext: {
- [ChannelKey.name]: {
- kind: "subagent",
- state: makeContext().state,
- },
+ callId: "call-continued",
+ replyTo: { kind: "hook", token: "parent-token-current" },
+ subagentName: "linear",
+ },
+ {
+ [ChannelKey.name]: {
+ kind: "subagent",
+ state: makeContext().state,
},
},
- bindTurnCallerContextStep,
);
const base = makeContext();
- const channel = rebound.serializedContext[ChannelKey.name] as {
+ const channel = rebound[ChannelKey.name] as {
readonly state: Record<string, unknown>;
};
diff --git a/packages/eve/src/subagents/parent-notification.test.ts b/packages/eve/src/subagents/parent-notification.test.ts
index bd5673834..249ac0f27 100644
--- a/packages/eve/src/subagents/parent-notification.test.ts
+++ b/packages/eve/src/subagents/parent-notification.test.ts
@@ -6,11 +6,10 @@ import { SessionCallbackKey, SessionIdKey } from "#context/keys.js";
import { BundleKey, ChannelKey } from "#runtime/sessions/runtime-context-keys.js";
import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";
import {
- bindTurnCallerContextStep,
+ bindTurnCallerContext,
notifyTurnCallerStep,
resolveInitialTurnCallerStep,
} from "#subagents/parent-notification.js";
-import { runSessionStateStep } from "#internal/testing/session-state-step.js";
import { SUBAGENT_ADAPTER } from "#subagents/adapter.js";
import { SUBAGENT_ADAPTER_KIND } from "#subagents/adapter-state.js";
import { HookNotFoundError } from "#compiled/@workflow/errors/index.js";
@@ -344,69 +343,59 @@ describe("turn caller notification", () => {
});
describe("turn caller binding", () => {
- it("rebinds local adapter forwarding to a continuation caller", async () => {
- await expect(
- runSessionStateStep(
+ it("rebinds local adapter forwarding to a continuation caller", () => {
+ expect(
+ bindTurnCallerContext(
{
- caller: {
- callId: "call-new",
- replyTo: { kind: "hook", token: "turn-new" },
- subagentName: "research",
- },
- serializedContext: {
- [ChannelKey.name]: {
- kind: SUBAGENT_ADAPTER_KIND,
- state: {
- callId: "call-old",
- parentContinuationToken: "turn-old",
- parentSessionId: "parent",
- subagentName: "research",
- },
+ callId: "call-new",
+ replyTo: { kind: "hook", token: "turn-new" },
+ subagentName: "research",
+ },
+ {
+ [ChannelKey.name]: {
+ kind: SUBAGENT_ADAPTER_KIND,
+ state: {
+ callId: "call-old",
+ parentContinuationToken: "turn-old",
+ parentSessionId: "parent",
+ subagentName: "research",
},
},
},
- bindTurnCallerContextStep,
),
- ).resolves.toEqual({
- serializedContext: {
- [ChannelKey.name]: {
- kind: SUBAGENT_ADAPTER_KIND,
- state: {
- callId: "call-new",
- parentContinuationToken: "turn-new",
- parentSessionId: "parent",
- subagentName: "research",
- },
+ ).toEqual({
+ [ChannelKey.name]: {
+ kind: SUBAGENT_ADAPTER_KIND,
+ state: {
+ callId: "call-new",
+ parentContinuationToken: "turn-new",
+ parentSessionId: "parent",
+ subagentName: "research",
},
},
});
});
- it("rebinds remote callback forwarding to a continuation caller", async () => {
- await expect(
- runSessionStateStep(
+ it("rebinds remote callback forwarding to a continuation caller", () => {
+ expect(
+ bindTurnCallerContext(
{
- caller: {
- callId: "call-new",
- replyTo: {
- kind: "callback",
- token: "turn-new",
- url: "https://parent.example/eve/v1/callback/turn-new",
- },
- subagentName: "research",
- },
- serializedContext: {},
- },
- bindTurnCallerContextStep,
- ),
- ).resolves.toEqual({
- serializedContext: {
- [SessionCallbackKey.name]: {
callId: "call-new",
+ replyTo: {
+ kind: "callback",
+ token: "turn-new",
+ url: "https://parent.example/eve/v1/callback/turn-new",
+ },
subagentName: "research",
- token: "turn-new",
- url: "https://parent.example/eve/v1/callback/turn-new",
},
+ {},
+ ),
+ ).toEqual({
+ [SessionCallbackKey.name]: {
+ callId: "call-new",
+ subagentName: "research",
+ token: "turn-new",
+ url: "https://parent.example/eve/v1/callback/turn-new",
},
});
});
diff --git a/packages/eve/src/subagents/parent-notification.ts b/packages/eve/src/subagents/parent-notification.ts
index 9f30a07a3..f18974a59 100644
--- a/packages/eve/src/subagents/parent-notification.ts
+++ b/packages/eve/src/subagents/parent-notification.ts
@@ -19,10 +19,6 @@ import { parseJsonValue } from "#shared/json.js";
import type { TokenUsage } from "#shared/token-usage.js";
import { resumeHook } from "#internal/workflow/runtime.js";
import { postSessionCallbackRequest } from "#execution/session-callback-request.js";
-import {
- withSessionStateDelta,
- type SessionStateTransition,
-} from "#execution/session/state-delta.js";
const log = createLogger("execution.delegated-parent-notification");
@@ -86,13 +82,12 @@ export async function notifyTurnCallerStep(input: {
/** Settles a workflow-owned caller after the child turn is cooperatively cancelled. */
export async function notifyCancelledTaskCallerStep(input: {
- readonly caller: TurnCaller | undefined;
+ readonly caller: TurnCaller;
readonly sessionId: string;
readonly usage?: TokenUsage;
}): Promise<void> {
"use step";
- if (input.caller === undefined) return;
const usageDelta = input.usage ?? ZERO_TOKEN_USAGE;
const error = {
code: SUBAGENT_EXECUTION_FAILED,
@@ -207,19 +202,12 @@ export async function resolveInitialTurnCallerStep(input: {
};
}
-/** Rebinds child event forwarding to the caller that owns the next accepted turn. */
-export async function bindTurnCallerContextStep(input: {
- readonly caller: TurnCaller | undefined;
- readonly serializedContext: Record<string, unknown>;
-}): Promise<SessionStateTransition> {
- "use step";
-
- return await withSessionStateDelta(input, async ({ caller, serializedContext }) => ({
- serializedContext: bindTurnCallerContext(caller, serializedContext),
- }));
-}
-
-function bindTurnCallerContext(
+/**
+ * Points child event forwarding at the caller that owns the next accepted turn,
+ * so the turn's input requests and progress reach that caller and not the
+ * previous one.
+ */
+export function bindTurnCallerContext(
caller: TurnCaller | undefined,
serializedContext: Record<string, unknown>,
): Record<string, unknown> {
diff --git a/research/turn-performance.md b/research/turn-performance.md
index 17aa5f65b..fe7ab2522 100644
--- a/research/turn-performance.md
+++ b/research/turn-performance.md
@@ -1,7 +1,7 @@
---
issue: https://github.com/vercel/eve/issues/876
status: proposed
-last_updated: "2026-09-04"
+last_updated: "2026-10-02"
---
# Turn performance and Workflow overhead
@@ -393,6 +393,9 @@ and crash-cleanup behavior remains on the existing path.
This is the lowest-risk structural change. Prove exact step-count reduction and no change to root,
subagent, task, failure, and cancellation results.
+Follow-up: `bindTurnCallerContextStep` has since been removed. A turn's first `turnStep` now binds
+the delegated caller, so delegated turns no longer pay that step either.
+
#### Hosted result
Two Vercel stress runs of the isolated change reproduced a material improvement against a