The Open Framework for Building Agents
feat(eve): workflow checkpoints - batch model calls (#3034)
Andrew Barba2b2ad19d937e
diff --git a/.changeset/quick-tools-batch.md b/.changeset/quick-tools-batch.mdnew file mode 100644index 000000000..ed8ce8f23--- /dev/null+++ b/.changeset/quick-tools-batch.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Add an experimental `workflow.modelCallsPerStep` agent option for batching sequential model and inline tool cycles into fewer Workflow checkpoints. Raising it above one reduces checkpoint overhead while widening the retry and replay unit.diff --git a/docs/agent-config.md b/docs/agent-config.mdindex 9b72447cf..48e88a1a0 100644--- a/docs/agent-config.md+++ b/docs/agent-config.md@@ -247,18 +247,54 @@ putting the connection string or credentials in the env vars it reads. If theinstalled package must stay external in hosted output, list it in`build.externalDependencies`.+## Workflow checkpoint batching++By default, eve commits a durable Workflow step after every model call and its+inline tool calls. You can experimentally let one Workflow step run several+sequential model calls:++```ts title="agent/agent.ts"+import { defineAgent } from "eve";++export default defineAgent({+ model: "anthropic/claude-opus-4.8",+ experimental: {+ workflow: {+ modelCallsPerStep: 4,+ },+ },+});+```++`experimental.workflow.modelCallsPerStep` is a positive-integer ceiling. It defaults to+`1` and applies independently to each root agent or declared subagent. A higher+value can reduce Workflow checkpoint overhead in sequential tool loops, but it+widens the replay unit: if the Workflow step is interrupted, its earlier model+calls and inline tool executions can run again. That can repeat provider costs,+events, and side effects. Use stable idempotency keys for non-idempotent tools.++eve ends a batch before it waits for input, authorization, or blocking+coordination, and before it acknowledges a background task. A batch can also+end below the configured ceiling when the turn completes. Steering cancels the+active model-and-tool cycle, commits earlier completed cycles in the batch, and+starts the replacement turn from that state. It does not roll the session back+to the beginning of the batch. This option is experimental and may change or+disappear in any release. See [Execution model and+durability](./concepts/execution-model-and-durability#resuming-after-a-crash)+for the retry behavior.+## Other defineAgent fields`defineAgent` takes a few more fields, all optional. For the exported types, see the [TypeScript API Reference](./reference/typescript-api).-| Field | Type | Default | Description |-| -------------- | --------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `reasoning` | `AgentReasoningDefinition` | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls. |-| `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call. |-| `limits` | `AgentLimitsDefinition` | field-specific | Framework-owned runtime limits. Sessions complete after 30 days by default; usage-limit defaults and inheritance are described above. Set a limit to `false` to disable it. |-| `experimental` | `{ workflow?: { world?: string } }` | unset | Opt-in settings that can change or disappear in any release. Treat them as unstable. `workflow.world` selects the Workflow world package backing session state, queues, hooks, and streams on the root agent. |-| `outputSchema` | Standard Schema or a JSON Schema object | none | Structured return type for function-like invocations such as a subagent turn, schedule, or remote job. Ordinary interactive turns ignore it unless the client supplies a per-message schema. |-| `build` | `{ externalDependencies?: string[] }` | none | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output. |+| Field | Type | Default | Description |+| -------------- | --------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `reasoning` | `AgentReasoningDefinition` | provider default | Provider-agnostic reasoning effort forwarded to the agent's turn model calls. |+| `modelOptions` | `AgentModelOptionsDefinition` | none | Provider option overrides forwarded to the model call. |+| `limits` | `AgentLimitsDefinition` | field-specific | Framework-owned runtime limits. Sessions complete after 30 days by default; usage-limit defaults and inheritance are described above. Set a limit to `false` to disable it. |+| `experimental` | `AgentExperimentalDefinition` | unset | Unstable opt-ins. `workflow.world` selects the Workflow world package on the root agent; `workflow.modelCallsPerStep` batches sequential model calls into a wider replay unit. |+| `outputSchema` | Standard Schema or a JSON Schema object | none | Structured return type for function-like invocations such as a subagent turn, schedule, or remote job. Ordinary interactive turns ignore it unless the client supplies a per-message schema. |+| `build` | `{ externalDependencies?: string[] }` | none | Hosted-build packaging controls. `externalDependencies` keeps listed packages external while eve compiles authored modules such as tools and channels, and traces those packages into the hosted output. |`externalDependencies` is a packaging control only. It keeps selected packages as runtime dependencies in the hosted output; it does not authorize, configure, or review any third-party service those packages may call.diff --git a/docs/concepts/execution-model-and-durability.mdx b/docs/concepts/execution-model-and-durability.mdxindex c64b860a3..8d5521fd5 100644--- a/docs/concepts/execution-model-and-durability.mdx+++ b/docs/concepts/execution-model-and-durability.mdx@@ -11,10 +11,16 @@ Work nests in three levels:- **session**: the whole durable conversation or task. It's long-lived and can span many requests over days or weeks without losing context.- **turn**: one user message and all the work it triggers (model calls, tool calls, reasoning) until the agent produces its response.-- **step**: a durable checkpoint inside a turn (one model call and the tool calls it makes).+- **step**: a durable checkpoint inside a turn. By default, it contains one model call and the inline tool calls that follow it.Every turn runs as a durable workflow, built on the open-source [Workflow SDK](https://workflow-sdk.dev/) (Vercel Workflow when you deploy on Vercel). eve checkpoints progress and serializes durable state at each step boundary. Your code runs inside a managed step, so tools, the sandbox, and subagents feel synchronous even though the session underneath them is durable.+The experimental+[`workflow.modelCallsPerStep`](../agent-config#workflow-checkpoint-batching)+agent setting can group several sequential model-and-tool cycles into one+Workflow step. This reduces checkpoint overhead but makes the entire group one+replay unit.+The Workflow SDK is not inherently tied to Vercel. In local development and in a self-deployed `eve start` process, eve uses the SDK's local world by default; that world persists workflow runs on disk under `.eve/.workflow-data` and dispatches through the same Nitro-hosted workflow routes. On Vercel, the same workflow code runs against Vercel Workflow instead, which adds platform features such as latest production deployment routing and dashboard run metadata.When a Vercel production deployment changes, the next model turn in an existing session uses that deployment's current system-role instructions, model, and tools. Static user-role instructions stay pinned in the durable conversation history and are not seeded again. Identity-based channels such as Telegram private chats and Twilio phone-number conversations therefore adopt agent behavior updates without duplicating or rewriting their existing context.@@ -58,7 +64,19 @@ Provider keys, tool secrets, and MCP, OpenAPI, and connection credentials stay iCrash the process, hit a timeout, or redeploy mid-turn, and the run picks up from the last completed step rather than replaying the whole turn. Completed steps never re-run; eve replays the recorded result. A step interrupted mid-execution re-runs, so make non-idempotent side effects like charges or emails idempotent, or gate them with approval. Whatever that step already wrote to the session stream stays there, and the re-run emits its events again under new ids, so a stream consumer sees both attempts — see [the event envelope](./sessions-runs-and-streaming#the-event-envelope).-There's nothing to configure. eve owns the workflow lifecycle, and sessions are durable by default.+With `experimental.workflow.modelCallsPerStep` greater than `1`, an+interrupted Workflow step can also repeat earlier model calls and inline tool+executions from the same batch. Approval, input, blocking coordination, and+background-task boundaries still force a checkpoint before eve waits or+acknowledges the work.++Steering does not replay or discard the whole batch. eve aborts the active+model-and-tool cycle, commits earlier completed cycles in the batch, and starts+the replacement turn from that state in the next Workflow step.++Durability itself needs no configuration. eve owns the workflow lifecycle, and+sessions are durable by default; checkpoint batching is an explicit+experimental opt-in.For ordinary tools, eve manages the workflow around your executor. Use [`defineWorkflowTool`](../tools/workflows) when your own tool body needs durable waits, such as a timer, webhook, or human answer. Two surfaces give your own code session data: tools read the current session's metadata (id, turn, auth, parent lineage) via `ctx.session`, and [`defineState`](./state) reads or writes session-scoped durable state. See [State](./state) for the read/write model.diff --git a/docs/subagents/index.mdx b/docs/subagents/index.mdxindex e9c4591ee..0703b8be6 100644--- a/docs/subagents/index.mdx+++ b/docs/subagents/index.mdx@@ -183,7 +183,7 @@ Each delegated subagent spins up its own child session and stream. The parent stA background task that was already admitted survives cancellation of the turn that started it; background work that has not yet been admitted is rejected with the cancelled step. Use `task_cancel` to stop an admitted task. Cancellation delivers the task's final notification to an active parent even if the task must be stopped forcibly. Parent-session finalization cancels remaining live tasks.-Subagent model calls automatically retry classified transient provider failures, including overload errors delivered after a stream starts. eve makes at most three fresh model-call attempts, repeating only the current uncommitted call so completed earlier steps, tool results, and sandbox work remain available to the child. Other recoverable task errors fall back to Workflow's durable step retry from the last committed session snapshot. Exhausting the transient model-call attempts or the dedicated empty-response reissue returns one failed task result instead of stacking both retry budgets; terminal errors fail immediately.+Subagent model calls automatically retry classified transient provider failures, including overload errors delivered after a stream starts. eve makes at most three fresh model-call attempts, repeating only the current uncommitted call by default so completed earlier Workflow steps, tool results, and sandbox work remain available to the child. A declared subagent that opts into [Workflow checkpoint batching](./agent-config#workflow-checkpoint-batching) can instead repeat the uncommitted calls and inline tool executions in its current batch. Other recoverable task errors fall back to Workflow's durable step retry from the last committed session snapshot. Exhausting the transient model-call attempts or the dedicated empty-response reissue returns one failed task result instead of stacking both retry budgets; terminal errors fail immediately.## Agent messagingdiff --git a/e2e/fixtures/agent-tools/agent/agent.ts b/e2e/fixtures/agent-tools/agent/agent.tsindex 4b6547e54..6db5aea44 100644--- a/e2e/fixtures/agent-tools/agent/agent.ts+++ b/e2e/fixtures/agent-tools/agent/agent.ts@@ -1,18 +1,27 @@import { e2eAgentConfig } from "@eve-e2e/config";import { defineAgent } from "eve";-export default defineAgent({- ...e2eAgentConfig({- mock(request) {- if (request.lastUserMessage?.includes("`callback_identity`")) {- const roles = request.messages.map((message) => message.role);- if (roles.lastIndexOf("tool") <= roles.lastIndexOf("user")) {- return { toolCalls: [{ name: "callback_identity", input: {} }] };- }- return "Callback identity checked.";+const base = e2eAgentConfig({+ mock(request) {+ if (request.lastUserMessage?.includes("`callback_identity`")) {+ const roles = request.messages.map((message) => message.role);+ if (roles.lastIndexOf("tool") <= roles.lastIndexOf("user")) {+ return { toolCalls: [{ name: "callback_identity", input: {} }] };}- return `Mock reply: ${request.lastUserMessage ?? ""}`;+ return "Callback identity checked.";+ }+ return `Mock reply: ${request.lastUserMessage ?? ""}`;+ },+});++export default defineAgent({+ ...base,+ experimental: {+ ...base.experimental,+ workflow: {+ ...base.experimental?.workflow,+ modelCallsPerStep: 3,},- }),+ },reasoning: "high",});diff --git a/e2e/fixtures/agent-tools/evals/static-tools/multi-step-loop.eval.ts b/e2e/fixtures/agent-tools/evals/static-tools/multi-step-loop.eval.tsindex b1d02a96d..3e133a279 100644--- a/e2e/fixtures/agent-tools/evals/static-tools/multi-step-loop.eval.ts+++ b/e2e/fixtures/agent-tools/evals/static-tools/multi-step-loop.eval.ts@@ -7,7 +7,7 @@ const MULTI_STEP_FINAL_VALUE = "phoenix-rising-9F2X";// user-visible reply.export default defineEval({tags: ["real-model"],- description: "Static tools smoke: deterministic two-step tool loop.",+ description: "Static tools smoke: batched deterministic two-step tool loop.",async test(t) {await t.send([diff --git a/packages/eve/extension-contracts/compatibility/subagent/v10.ts b/packages/eve/extension-contracts/compatibility/subagent/v10.tsnew file mode 100644index 000000000..344e5db11--- /dev/null+++ b/packages/eve/extension-contracts/compatibility/subagent/v10.ts@@ -0,0 +1,6 @@+import { defineAgent } from "#public/index.js";++export default defineAgent({+ description: "Delegate research tasks.",+ model: "anthropic/claude-sonnet-5",+});diff --git a/packages/eve/extension-contracts/reports/subagent/v11.json b/packages/eve/extension-contracts/reports/subagent/v11.jsonnew file mode 100644index 000000000..e79a2f15f--- /dev/null+++ b/packages/eve/extension-contracts/reports/subagent/v11.json@@ -0,0 +1,20 @@+{+ "kind": "eve-extension-capability-contract",+ "capability": "subagent",+ "epoch": 11,+ "sha256": "790a033e5ac2b3fb16a187624bc33c1657a64f6892761953efdb833fd7fd9191",+ "exports": [+ "AgentCompactionDefinition",+ "AgentDefinition",+ "AgentModelDefinition",+ "AgentStaticModelDefinition",+ "DefinedAgent",+ "DynamicLocalSubagentDefinition",+ "DynamicSubagentDefinition",+ "RemoteAgentDefinition",+ "RemoteAgentDefinitionInput",+ "defineAgent",+ "defineDynamic",+ "defineRemoteAgent"+ ]+}diff --git a/packages/eve/src/compiler/extension-compatibility.ts b/packages/eve/src/compiler/extension-compatibility.tsindex d80b2c093..bc0fccf23 100644--- a/packages/eve/src/compiler/extension-compatibility.ts+++ b/packages/eve/src/compiler/extension-compatibility.ts@@ -70,8 +70,8 @@ const EXTENSION_CAPABILITY_CONTRACTS = {},},subagent: {- current: 10,- supported: [3, 4, 6, 7, 8, 9, 10],+ current: 11,+ supported: [3, 4, 6, 7, 8, 9, 10, 11],dropped: {1: "Persistent subagent sessions are now the default and the experimental opt-in was removed",2: "Persistent subagent sessions are now the default and the experimental opt-in was removed",diff --git a/packages/eve/src/compiler/manifest.test.ts b/packages/eve/src/compiler/manifest.test.tsindex a647273f2..e4477528a 100644--- a/packages/eve/src/compiler/manifest.test.ts+++ b/packages/eve/src/compiler/manifest.test.ts@@ -14,13 +14,18 @@ import {describe("compiled agent manifest v48", () => {it("round-trips a real compiled graph through the serialized schema", async () => {const { manifest } = await compileFromMemory({- limits: { maxTokenCostUsdPerSession: 1.5 },+ agent: {+ experimental: { workflow: { modelCallsPerStep: 4 } },+ limits: { maxTokenCostUsdPerSession: 1.5 },+ model: "openai/gpt-5.4",+ },model: "openai/gpt-5.4",tools: [{ name: "weather" }],});const parsed = compiledAgentManifestSchema.parse(JSON.parse(JSON.stringify(manifest)));expect(parsed.version).toBe(COMPILED_AGENT_MANIFEST_VERSION);+ expect(parsed.config.experimental?.workflow?.modelCallsPerStep).toBe(4);expect(parsed.config.limits?.maxTokenCostUsdPerSession).toBe(1.5);expect(() => validateCompiledAgentManifest(parsed)).not.toThrow();});diff --git a/packages/eve/src/compiler/manifest.ts b/packages/eve/src/compiler/manifest.tsindex 82cd143b7..39467ceb5 100644--- a/packages/eve/src/compiler/manifest.ts+++ b/packages/eve/src/compiler/manifest.ts@@ -569,6 +569,7 @@ const compiledAgentWorkflowWorldDefinitionSchema = z.string();const compiledAgentWorkflowDefinitionSchema = z.object({+ modelCallsPerStep: z.number().int().positive().optional(),world: compiledAgentWorkflowWorldDefinitionSchema.optional(),}).strict();@@ -1214,6 +1215,7 @@ function cloneCompiledAgentDefinition(config: CompiledAgentDefinition): Compiledconfig.experimental.workflow === undefined? undefined: {+ modelCallsPerStep: config.experimental.workflow.modelCallsPerStep,world: config.experimental.workflow.world,},},diff --git a/packages/eve/src/compiler/normalize-agent-config.ts b/packages/eve/src/compiler/normalize-agent-config.tsindex 1e28c85e6..145fbdd50 100644--- a/packages/eve/src/compiler/normalize-agent-config.ts+++ b/packages/eve/src/compiler/normalize-agent-config.ts@@ -188,6 +188,7 @@ function normalizeExperimentalDefinition(if (experimental.workflow !== undefined) {compiledExperimental.workflow = {+ modelCallsPerStep: experimental.workflow.modelCallsPerStep,world: experimental.workflow.world,};}diff --git a/packages/eve/src/compiler/normalize-manifest-helpers.ts b/packages/eve/src/compiler/normalize-manifest-helpers.tsindex c0012f772..60b296070 100644--- a/packages/eve/src/compiler/normalize-manifest-helpers.ts+++ b/packages/eve/src/compiler/normalize-manifest-helpers.ts@@ -29,9 +29,9 @@ export function assertRootOnlyConfig(agentId: string,): void {if (isRoot) return;- if (config.experimental?.workflow !== undefined) {+ if (config.experimental?.workflow?.world !== undefined) {throw new Error(- `Workflow runtime configuration is only supported on the root agent config. Remove "experimental.workflow" from "${agentId}".`,+ `Workflow world configuration is only supported on the root agent config. Remove "experimental.workflow.world" from "${agentId}".`,);}}diff --git a/packages/eve/src/compiler/normalize-manifest.test.ts b/packages/eve/src/compiler/normalize-manifest.test.tsindex 2c47385ba..20b8740bd 100644--- a/packages/eve/src/compiler/normalize-manifest.test.ts+++ b/packages/eve/src/compiler/normalize-manifest.test.ts@@ -11,6 +11,7 @@ import {type ProgrammaticAgentModule,} from "#compiler/source-graph.js";import { compileAgentManifest } from "#compiler/normalize-manifest.js";+import { assertRootOnlyConfig } from "#compiler/normalize-manifest-helpers.js";import type { CompilerDiagnostic } from "#compiler/diagnostics.js";import { createProgrammaticCompiledModuleMap } from "#compiler/module-map.js";import { validateCompiledModuleMap } from "#compiler/validate-artifact.js";@@ -54,6 +55,26 @@ function registry(modules: readonly ProgrammaticAgentModule[]) {}describe("compileAgentManifest source graph", () => {+ it("allows subagents to configure Workflow model calls per step", () => {+ expect(() =>+ assertRootOnlyConfig(+ { experimental: { workflow: { modelCallsPerStep: 4 } } } as never,+ false,+ "child",+ ),+ ).not.toThrow();+ });++ it("keeps Workflow world selection root-only", () => {+ expect(() =>+ assertRootOnlyConfig(+ { experimental: { workflow: { world: "@workflow/world-postgres" } } } as never,+ false,+ "child",+ ),+ ).toThrow('Remove "experimental.workflow.world" from "child".');+ });+it("freezes source metadata behind an immutable registry map", () => {const sourceRegistry = registry([]);diff --git a/packages/eve/src/execution/cancelled-model-call-batch.ts b/packages/eve/src/execution/cancelled-model-call-batch.tsnew file mode 100644index 000000000..975f3323d--- /dev/null+++ b/packages/eve/src/execution/cancelled-model-call-batch.ts@@ -0,0 +1,61 @@+import { contextStorage, type ContextContainer } from "#context/container.js";+import { TurnDeliveryIdsKey } from "#context/keys.js";+import { preserveSerializedSessionDynamicModelSelection } from "#context/serialized-dynamic-model-selection.js";+import { serializeContext } from "#context/serialize.js";+import { preserveCancelledTurnMessage } from "#execution/cancelled-turn-message.js";+import { createDurableSessionState } from "#execution/durable-session-store.js";+import type { DurableStepResult } from "#execution/next-driver-action.js";+import { readRetainedBackgroundToolResult } from "#execution/tasks/parent/tool-execution.js";+import type { HarnessSession, StepInput, StepResult } from "#harness/types.js";+import { preserveSerializedInstrumentationState } from "#instrumentation/state.js";+import { preserveSerializedAgentTraceState } from "#tracing/agent-trace-context-store.js";++export interface CompletedModelCallCheckpoint {+ readonly result: StepResult;+ readonly serializedContext: Record<string, unknown>;+}++/** Builds the successful step result that commits a cancelled batch's completed model calls. */+export async function createCancelledModelCallBatchResult(input: {+ readonly beforeBatchContext: Record<string, unknown>;+ readonly checkpoint: CompletedModelCallCheckpoint | undefined;+ readonly ctx: ContextContainer;+ readonly initialSession: HarnessSession;+ readonly stepInput: StepInput | undefined;+}): Promise<DurableStepResult> {+ const interruptedContext = serializeContext(input.ctx);+ const retained = readRetainedBackgroundToolResult(input.ctx);+ const backgroundTaskSession =+ retained?.backgroundTaskSession ?? input.checkpoint?.result.backgroundTaskSession;+ const backgroundTasks = retained?.backgroundTasks ?? input.checkpoint?.result.backgroundTasks;+ const checkpointSession =+ backgroundTaskSession ?? input.checkpoint?.result.session ?? input.initialSession;+ const cancelledSession =+ input.checkpoint === undefined+ ? await contextStorage.run(input.ctx, () =>+ preserveCancelledTurnMessage(checkpointSession, input.stepInput),+ )+ : checkpointSession;+ const checkpointContext = {+ ...(input.checkpoint?.serializedContext ?? input.beforeBatchContext),+ [TurnDeliveryIdsKey.name]: interruptedContext[TurnDeliveryIdsKey.name],+ };++ return {+ action: "cancelled",+ ...(backgroundTaskSession === undefined || backgroundTasks === undefined+ ? {}+ : {+ backgroundTaskState: createDurableSessionState({ session: cancelledSession }),+ backgroundTasks,+ }),+ serializedContext: preserveSerializedInstrumentationState(+ preserveSerializedAgentTraceState(+ preserveSerializedSessionDynamicModelSelection(checkpointContext, interruptedContext),+ interruptedContext,+ ),+ interruptedContext,+ ),+ sessionState: createDurableSessionState({ session: cancelledSession }),+ };+}diff --git a/packages/eve/src/execution/model-call-batching.ts b/packages/eve/src/execution/model-call-batching.tsnew file mode 100644index 000000000..9d11328ce--- /dev/null+++ b/packages/eve/src/execution/model-call-batching.ts@@ -0,0 +1,61 @@+import { derivePendingState } from "#execution/pending-turn-state.js";+import { getPendingWorkflowInterrupt } from "#harness/workflow-interrupt-state.js";+import type { HarnessSession, StepInput, StepResult } from "#harness/types.js";++export async function runModelCallBatch(input: {+ readonly initialInput: StepInput | undefined;+ readonly initialSession: HarnessSession;+ readonly modelCallsPerStep: number;+ readonly runStep: (input: {+ readonly firstCall: boolean;+ readonly session: HarnessSession;+ readonly stepInput: StepInput | undefined;+ }) => Promise<StepResult>;+}): Promise<StepResult> {+ let session = input.initialSession;+ let stepInput = input.initialInput;+ let completedModelCalls = 0;++ while (true) {+ const result = await input.runStep({+ firstCall: completedModelCalls === 0,+ session,+ stepInput,+ });+ completedModelCalls++;+ if (+ !shouldRunAnotherModelCall({+ completedModelCalls,+ modelCallsPerStep: input.modelCallsPerStep,+ result,+ })+ ) {+ return result;+ }+ session = result.session;+ stepInput = undefined;+ }+}++function shouldRunAnotherModelCall(input: {+ readonly completedModelCalls: number;+ readonly modelCallsPerStep: number;+ readonly result: StepResult;+}): boolean {+ if (+ input.completedModelCalls >= input.modelCallsPerStep ||+ typeof input.result.next !== "function" ||+ input.result.backgroundTaskSession !== undefined ||+ input.result.backgroundTasks !== undefined ||+ getPendingWorkflowInterrupt(input.result.session.state) !== undefined+ ) {+ return false;+ }++ const pending = derivePendingState(input.result.session);+ return (+ !pending.hasPendingAuthorization &&+ !pending.hasPendingInputBatch &&+ (pending.pendingCoordinationCallIds?.length ?? 0) === 0+ );+}diff --git a/packages/eve/src/execution/turn-workflow.test.ts b/packages/eve/src/execution/turn-workflow.test.tsindex 827cecc65..748dc3ddb 100644--- a/packages/eve/src/execution/turn-workflow.test.ts+++ b/packages/eve/src/execution/turn-workflow.test.ts@@ -1,7 +1,6 @@import { afterEach, describe, expect, it, vi } from "vitest";import type { HookPayload } from "#channel/types.js";-import { SessionDynamicModelReferenceKey } from "#context/keys.js";import { cancelDescendantTurnsStep } from "#execution/cancel-descendant-turns-step.js";import { dispatchCoordinationStep } from "#execution/coordination-dispatch-step.js";import type { DurableSessionState } from "#execution/durable-session-store.js";@@ -174,7 +173,7 @@ describe("turnWorkflow", () => {);});- it("keeps earlier inline state when cancellation wins over a completed step", async () => {+ it("checkpoints completed inline state when cancellation wins", async () => {const initialState = createSessionState({ continuationToken: "http:initial" });const beforeStepState = createSessionState({ continuationToken: "http:inline-checkpoint" });const completedState = createSessionState({ continuationToken: "http:completed" });@@ -202,8 +201,8 @@ describe("turnWorkflow", () => {});expect(cancelDescendantTurnsStep).toHaveBeenCalledWith({- serializedContext: { state: "inline-checkpoint" },- sessionState: beforeStepState,+ serializedContext: { state: "done" },+ sessionState: completedState,});expect(resumeHookMock).toHaveBeenCalledWith("turn-token",@@ -211,7 +210,7 @@ describe("turnWorkflow", () => {action: expect.objectContaining({cancelled: true,kind: "park",- sessionState: beforeStepState,+ sessionState: completedState,}),kind: "turn-result",}),@@ -457,23 +456,16 @@ describe("turnWorkflow", () => {});});- it("honors cancellation observed while a durable turn step returns", async () => {+ it("checkpoints a durable turn step that finishes as cancellation arrives", async () => {const sessionState = createSessionState();- const sessionModel = {- id: "openai/gpt-5.6-sol",- contextWindowTokens: 1_000_000,- };+ const completedState = createSessionState({ continuationToken: "completed-state" });installInbox([], { cancelPayloads: [{}] });vi.mocked(turnStep).mockImplementationOnce(async (stepInput) => {await vi.waitFor(() => expect(stepInput.abortSignal?.aborted).toBe(true));return {- action: "done",- output: "must not complete",- serializedContext: {- state: "done",- [SessionDynamicModelReferenceKey.name]: sessionModel,- },- sessionState,+ action: "continue",+ serializedContext: { state: "completed" },+ sessionState: completedState,};});@@ -483,20 +475,16 @@ describe("turnWorkflow", () => {});await turnWorkflow(input);- const cancelledContext = {- state: "start",- [SessionDynamicModelReferenceKey.name]: sessionModel,- };expect(cancelDescendantTurnsStep).toHaveBeenCalledWith({- serializedContext: cancelledContext,- sessionState,+ serializedContext: { state: "completed" },+ sessionState: completedState,});expect(resumeHookMock).toHaveBeenCalledWith("turn-token", {action: {cancelled: true,kind: "park",- serializedContext: cancelledContext,- sessionState,+ serializedContext: { state: "completed" },+ sessionState: completedState,},kind: "turn-result",});diff --git a/packages/eve/src/execution/turn-workflow.ts b/packages/eve/src/execution/turn-workflow.tsindex e4afe0d9e..68710bf54 100644--- a/packages/eve/src/execution/turn-workflow.ts+++ b/packages/eve/src/execution/turn-workflow.ts@@ -9,7 +9,6 @@ import {import { createHook, getWorkflowMetadata } from "#compiled/@workflow/core/index.js";import type { DeliverHookPayload } from "#channel/types.js";-import { preserveSerializedSessionDynamicModelSelection } from "#context/serialized-dynamic-model-selection.js";import { cancelDescendantTurnsStep } from "#execution/cancel-descendant-turns-step.js";import { cancelAllIndexedSessionTasksStep } from "#execution/cancel-indexed-session-tasks-step.js";import { sendTurnControlStep, type TurnInboxPayload } from "#execution/turn-control-protocol.js";@@ -154,10 +153,9 @@ export async function runTurnOwnedWorkflow(// step may have missed the abort and completed normally. Pending// runtime-action batches are exempt — their wait observes the signal.if (result.action === "cancelled") {- // The cancelled step returns only the context carve-outs required by- // the driver epilogue and later turns, plus the accepted user input in- // durable history. Adopt those before settling so a steered replacement- // keeps the interrupted request without committing partial model output.+ // The cancelled step returns its latest safe checkpoint: completed+ // model calls survive, while the active model-and-tool cycle does not.+ // Adopt it before the driver emits the cancellation epilogue.await cursor.adopt({serializedContext: result.serializedContext,sessionState: result.backgroundTaskState ?? result.sessionState,@@ -170,15 +168,12 @@ export async function runTurnOwnedWorkflow(cancellation?.signal.aborted === true &&(pendingCallIds === undefined || hasBackgroundTasks)) {- // Some worlds cannot interrupt a running step, so it can complete- // normally after the workflow observes cancellation. Roll that result- // back except for a session model selected by its one-time preamble.+ // Some worlds cannot interrupt a running step, so it may complete just+ // as cancellation arrives. Its successful return is already a durable+ // boundary: preserve it, then settle cancellation before another step.await cursor.adopt({- serializedContext: preserveSerializedSessionDynamicModelSelection(- beforeStep.serializedContext,- result.serializedContext,- ),- sessionState: cursor.sessionState,+ serializedContext: result.serializedContext,+ sessionState: result.backgroundTaskState ?? result.sessionState,});// No `canPark` check here: that gate rejects model-authored waits// (`next: null`) in task mode, whereas every session can resume bydiff --git a/packages/eve/src/execution/workflow-steps.test.ts b/packages/eve/src/execution/workflow-steps.test.tsindex 68dd25948..a1406ff98 100644--- a/packages/eve/src/execution/workflow-steps.test.ts+++ b/packages/eve/src/execution/workflow-steps.test.ts@@ -34,7 +34,7 @@ import { TurnCancelledError } from "#harness/turn-cancellation.js";import { getPendingAuthorization, setPendingAuthorization } from "#harness/authorization.js";import { getProxyInputRequests, upsertProxyInputRequests } from "#harness/proxy-input-requests.js";import { appendPendingInputBatch } from "#harness/input-requests.js";-import type { HarnessSession, StepResult } from "#harness/types.js";+import type { HarnessSession, StepFn, StepResult } from "#harness/types.js";import { createEmptyHookRegistry } from "#runtime/hooks/registry.js";import { createActionsRequestedEvent, createInputRequestedEvent } from "#protocol/message.js";import { getCompiledRuntimeAgentBundle } from "#runtime/sessions/compiled-agent-cache.js";@@ -183,6 +183,27 @@ const TestTurnAgent = {workspaceSpec: {} as never,};+function createTurnStepTestBundle(modelCallsPerStep?: number) {+ const config =+ modelCallsPerStep === undefined ? {} : { experimental: { workflow: { modelCallsPerStep } } };+ return {+ adapterRegistry: {+ adaptersByKind: new Map([[threadContextAdapter.kind, threadContextAdapter]]),+ },+ compiledArtifactsSource: {},+ graph: {+ nodesByNodeId: new Map(),+ root: { sandboxRegistry: { sandbox: null }, turnAgent: TestTurnAgent },+ },+ hookRegistry: createEmptyHookRegistry(),+ moduleMap: { nodes: {} },+ resolvedAgent: { config },+ subagentRegistry: {},+ toolRegistry: {},+ turnAgent: TestTurnAgent,+ } as never;+}+const threadContextAdapter: ChannelAdapter = {kind: "thread-context",deliver(payload: DeliverPayload, adapterCtx: ChannelAdapterContext) {@@ -1170,6 +1191,196 @@ describe("dispatchCoordinationStep", () => {});describe("turnStep", () => {+ it("runs the configured number of model calls inside one Workflow step", async () => {+ const bundle = createTurnStepTestBundle(3);+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(bundle);+ installSessionStoreMocks([createStubSession()]);++ const stepInputs: Array<Parameters<StepFn>[1]> = [];+ let callCount = 0;+ const continueStep: StepFn = async (session) => ({ next: null, session });+ vi.mocked(createExecutionNodeStep).mockImplementation(() => {+ return async (session, stepInput): Promise<StepResult> => {+ callCount++;+ stepInputs.push(stepInput);+ const nextSession = {+ ...session,+ history: [+ ...session.history,+ { content: `model call ${String(callCount)}`, role: "assistant" as const },+ ],+ };+ return {+ next: callCount === 3 ? { done: true, output: "three calls complete" } : continueStep,+ session: nextSession,+ };+ };+ });++ const result = await turnStep({+ input: { kind: "deliver", payloads: [{ message: "run the chain" }] },+ parentWritable: createTestWritable(),+ serializedContext: createSerializedContext(),+ sessionState: createStubSessionState(),+ });++ expect(result).toMatchObject({ action: "done", output: "three calls complete" });+ expect(callCount).toBe(3);+ expect(stepInputs).toEqual([+ { message: "thread=unset; user=run the chain" },+ undefined,+ undefined,+ ]);+ expect(result.sessionState.snapshot?.session.history).toEqual([+ { content: "model call 1", role: "assistant" },+ { content: "model call 2", role: "assistant" },+ { content: "model call 3", role: "assistant" },+ ]);+ });++ it("checkpoints completed batched model calls when steering cancels the active call", async () => {+ const bundle = createTurnStepTestBundle(100);+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(bundle);+ installSessionStoreMocks([createStubSession()]);++ const controller = new AbortController();+ const continueStep: StepFn = async (session) => ({ next: null, session });+ let callCount = 0;+ vi.mocked(createExecutionNodeStep).mockImplementation(() => {+ return async (session): Promise<StepResult> => {+ callCount++;+ if (callCount === 51) {+ loadContext().set(ThreadKey, "discarded call 51");+ controller.abort(new TurnCancelledError());+ return {+ next: continueStep,+ session: {+ ...session,+ history: [+ ...session.history,+ { content: "discarded model call 51", role: "assistant" as const },+ ],+ },+ };+ }+ loadContext().set(ThreadKey, `completed call ${String(callCount)}`);+ return {+ next: continueStep,+ session: {+ ...session,+ history: [+ ...session.history,+ { content: `model call ${String(callCount)}`, role: "assistant" as const },+ ],+ },+ };+ };+ });++ const result = await turnStep({+ abortSignal: controller.signal,+ input: { kind: "deliver", payloads: [{ message: "run a long chain" }] },+ parentWritable: createTestWritable(),+ serializedContext: createSerializedContext(),+ sessionState: createStubSessionState(),+ });++ expect(result.action).toBe("cancelled");+ expect(callCount).toBe(51);+ expect(result.serializedContext).toMatchObject({ [ThreadKey.name]: "completed call 50" });+ expect(result.sessionState.snapshot?.session.history).toHaveLength(50);+ expect(result.sessionState.snapshot?.session.history.at(-1)).toEqual({+ content: "model call 50",+ role: "assistant",+ });+ });++ it("keeps one model call per Workflow step by default", async () => {+ const bundle = createTurnStepTestBundle();+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(bundle);+ installSessionStoreMocks([createStubSession()]);++ const continueStep: StepFn = async (session) => ({ next: null, session });+ const execute = vi.fn(async (session: HarnessSession): Promise<StepResult> => ({+ next: continueStep,+ session,+ }));+ vi.mocked(createExecutionNodeStep).mockImplementation(() => execute);++ const result = await turnStep({+ input: { kind: "deliver", payloads: [{ message: "one call" }] },+ parentWritable: createTestWritable(),+ serializedContext: createSerializedContext(),+ sessionState: createStubSessionState(),+ });++ expect(result.action).toBe("continue");+ expect(execute).toHaveBeenCalledOnce();+ });++ it("checkpoints before continuing past a pending input request", async () => {+ const bundle = createTurnStepTestBundle(3);+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(bundle);+ installSessionStoreMocks([createStubSession()]);++ const continueStep: StepFn = async (session) => ({ next: null, session });+ const execute = vi.fn(async (session: HarnessSession): Promise<StepResult> => ({+ next: continueStep,+ session: appendPendingInputBatch({+ requests: [+ {+ action: { callId: "call-confirm", input: {}, kind: "tool-call", toolName: "confirm" },+ kind: "question",+ prompt: "Continue?",+ requestId: "request-confirm",+ },+ ],+ responseMessages: [],+ session,+ }),+ }));+ vi.mocked(createExecutionNodeStep).mockImplementation(() => execute);++ const result = await turnStep({+ input: { kind: "deliver", payloads: [{ message: "ask first" }] },+ parentWritable: createTestWritable(),+ serializedContext: createSerializedContext(),+ sessionState: createStubSessionState(),+ });++ expect(result.action).toBe("continue");+ expect(execute).toHaveBeenCalledOnce();+ });++ it("checkpoints before persisting a background-task state transition", async () => {+ const bundle = createTurnStepTestBundle(3);+ vi.mocked(getCompiledRuntimeAgentBundle).mockResolvedValue(bundle);+ const session = createStubSession();+ installSessionStoreMocks([session]);++ const continueStep: StepFn = async (current) => ({ next: null, session: current });+ const execute = vi.fn(async (current: HarnessSession): Promise<StepResult> => ({+ backgroundTasks: [],+ backgroundTaskSession: current,+ next: continueStep,+ session: current,+ }));+ vi.mocked(createExecutionNodeStep).mockImplementation(() => execute);++ const result = await turnStep({+ input: { kind: "deliver", payloads: [{ message: "delegate" }] },+ parentWritable: createTestWritable(),+ serializedContext: createSerializedContext(),+ sessionState: createStubSessionState(),+ });++ expect(result).toMatchObject({+ action: "continue",+ backgroundTasks: [],+ });+ expect(execute).toHaveBeenCalledOnce();+ });+it("retains coalesced delivery ownership across steps and replaces it for the next message", async () => {const session = createStubSession({state: {diff --git a/packages/eve/src/execution/workflow-steps.ts b/packages/eve/src/execution/workflow-steps.tsindex 9b3b83f44..002d2e033 100644--- a/packages/eve/src/execution/workflow-steps.ts+++ b/packages/eve/src/execution/workflow-steps.ts@@ -9,7 +9,6 @@ import {prepareDynamicInstructionPreamble,} from "#context/dynamic-instruction-lifecycle.js";import { dispatchDynamicModelEvent } from "#context/dynamic-model-lifecycle.js";-import { preserveSerializedSessionDynamicModelSelection } from "#context/serialized-dynamic-model-selection.js";import { dispatchDynamicSkillEvent } from "#context/dynamic-skill-lifecycle.js";import {dispatchDynamicSubagentEvent,@@ -41,9 +40,7 @@ import {setHarnessEmissionState,} from "#harness/emission.js";import { bindSessionInstrumentation } from "#instrumentation/runtime.js";-import { preserveSerializedInstrumentationState } from "#instrumentation/state.js";import { RuntimeActionSettlementTimesKey } from "#harness/runtime-action-settlement-state.js";-import { preserveSerializedAgentTraceState } from "#tracing/agent-trace-context-store.js";import { matchAuthorizationCallbacks } from "#execution/authorization-callback-match.js";import { isTurnCancellation, throwIfTurnAborted } from "#harness/turn-cancellation.js";import { setChannelContext } from "#execution/channel-context.js";@@ -82,10 +79,7 @@ import {resolveInitiatingTaskContext,resolveTaskDeliveryContext,} from "#tasks/delivery-context.js";-import {- readRetainedBackgroundToolResult,- runBackgroundStep,-} from "#execution/tasks/parent/tool-execution.js";+import { runBackgroundStep } from "#execution/tasks/parent/tool-execution.js";import { TASK_UPDATE_SESSION_INSTRUCTION } from "#tools/framework/task-update.js";import { prepareWorkflowPreambleTrace } from "#execution/workflow-trace-context.js";import { resolveEffectiveAgentRuntime } from "#execution/effective-agent-config.js";@@ -95,8 +89,12 @@ import { createExecutionHistoryView } from "#execution/history-view.js";import { resolveRuntimeCompiledArtifactsVersionedCacheKey } from "#runtime/cache-key.js";import { createWorkflowRuntime } from "#execution/workflow-runtime.js";import { bindDynamicConnections } from "#execution/dynamic-connections.js";-import { preserveCancelledTurnMessage } from "#execution/cancelled-turn-message.js";import { deferMismatchedInlineTurnStep } from "#execution/accepted-delivery-deployment.js";+import { runModelCallBatch } from "#execution/model-call-batching.js";+import {+ createCancelledModelCallBatchResult,+ type CompletedModelCallCheckpoint,+} from "#execution/cancelled-model-call-batch.js";import * as activityCohort from "#execution/activity-cohort.js";const TASK_DONE_WITH_PENDING_INPUT_ERROR_MESSAGE =@@ -112,7 +110,7 @@ function channelDeliveryErrorCode(error: unknown): string {export type { TurnStepInput };-/** Runs one atomic harness step inside a durable `"use step"` boundary. */+/** Runs a bounded batch of harness model steps inside one durable `"use step"` boundary. */export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResult> {"use step";@@ -457,109 +455,123 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResu};const mode = ctx.require(ModeKey);+ const modelCallsPerStep =+ bundle.resolvedAgent.config?.experimental?.workflow?.modelCallsPerStep ?? 1;+ const capabilities = ctx.get(CapabilitiesKey);++ const runHarnessStep = async (+ lifecycleSession: HarnessSession,+ stepInput: StepInput | undefined,+ ): Promise<StepResult> => {+ const refreshedSession = refreshSessionFromTurnAgent({+ compactionOverrides: {+ thresholdPercent: effectiveAgent.thresholdPercent,+ },+ session: lifecycleSession,+ systemPromptAdditions: taskUpdatesEnabled ? [TASK_UPDATE_SESSION_INSTRUCTION] : undefined,+ turnAgent: effectiveAgent.turnAgent,+ });+ const modelSession = refreshedSession;+ const step = createExecutionNodeStep({+ abortSignal: input.abortSignal,+ capabilities,+ clearOnly: input.input?.kind === "clear",+ compactOnly: input.input?.kind === "compact",+ createRuntime: createWorkflowRuntime,+ handleEvent,+ historyProjector: history.projector,+ historyView: history.prepare(modelSession),+ instrumentation,+ mode,+ modelResolutionScope: {+ moduleMap: bundle.moduleMap,+ nodeId: bundle.nodeId,+ },+ node: effectiveNode,+ workflowMaxSubagents: refreshedSession.workflowMaxSubagents,+ });+ return step(modelSession, stepInput);+ };++ let completedModelCall: CompletedModelCallCheckpoint | undefined;let stepResult: StepResult;try {// A signal already aborted at entry (cancellation during an in-line// runtime-action wait) must settle before the park-resume stages run,// or the pending batch would re-park and later re-dispatch.throwIfTurnAborted(input.abortSignal);- stepResult = await runBackgroundStep(ctx, initialSession, async (enrichedSession) => {- ctx.setVirtualContext(HandleEventKey, handleEvent);- let schemaSession = resolveEffectiveOutputSchema({- agentOutputSchema: effectiveAgent.turnAgent.outputSchema,- input: resolved,- mode,- session: enrichedSession,- });- await dynamicConnections.rehydrate(- initialEmissionState,- runtimeIdentity,- isHarnessBetweenTurns(schemaSession),- );- if (completedAuths) {- let emissionState = getHarnessEmissionState(schemaSession.state);- if (isHarnessBetweenTurns(schemaSession)) {- prepareDynamicInstructionPreamble(ctx, history.messages(schemaSession));- let instructionMessages: readonly import("ai").ModelMessage[] = [];- const traceContext = await prepareWorkflowPreambleTrace({- emissionState,- instrumentation,- });- try {- emissionState = await emitTurnPreamble(- handleEvent,- {},- emissionState,- runtimeIdentity,- traceContext,- );- } finally {- instructionMessages = drainDynamicInstructionUserMessages(ctx);- schemaSession = {- ...schemaSession,- history: [...schemaSession.history, ...instructionMessages],- };- }- schemaSession = setHarnessEmissionState(schemaSession, emissionState);- }- for (const { authorization, result } of completedAuths) {- const candidateId = pendingAuth?.challenges.find(- (challenge) => challenge.attemptId === result.attemptId,- )?.candidateId;- await handleEvent(- createAuthorizationCompletedEvent({- attemptId: result.attemptId,- authorization,- candidateId,- name: result.name,- outcome: "authorized",- sequence: emissionState.sequence,- stepIndex: emissionState.stepIndex,- turnId: emissionState.turnId,- }),+ stepResult = await runModelCallBatch({+ initialInput: resolved,+ initialSession,+ modelCallsPerStep,+ runStep: async ({ firstCall, session, stepInput }) => {+ const result = await runBackgroundStep(ctx, session, async (enrichedSession) => {+ ctx.setVirtualContext(HandleEventKey, handleEvent);+ let schemaSession = firstCall+ ? resolveEffectiveOutputSchema({+ agentOutputSchema: effectiveAgent.turnAgent.outputSchema,+ input: resolved,+ mode,+ session: enrichedSession,+ })+ : enrichedSession;+ await dynamicConnections.rehydrate(+ getHarnessEmissionState(schemaSession.state),+ runtimeIdentity,+ isHarnessBetweenTurns(schemaSession),);- }- }+ if (firstCall && completedAuths) {+ let emissionState = getHarnessEmissionState(schemaSession.state);+ if (isHarnessBetweenTurns(schemaSession)) {+ prepareDynamicInstructionPreamble(ctx, history.messages(schemaSession));+ let instructionMessages: readonly import("ai").ModelMessage[] = [];+ const traceContext = await prepareWorkflowPreambleTrace({+ emissionState,+ instrumentation,+ });+ try {+ emissionState = await emitTurnPreamble(+ handleEvent,+ {},+ emissionState,+ runtimeIdentity,+ traceContext,+ );+ } finally {+ instructionMessages = drainDynamicInstructionUserMessages(ctx);+ schemaSession = {+ ...schemaSession,+ history: [...schemaSession.history, ...instructionMessages],+ };+ }+ schemaSession = setHarnessEmissionState(schemaSession, emissionState);+ }+ for (const { authorization, result } of completedAuths) {+ const candidateId = pendingAuth?.challenges.find(+ (challenge) => challenge.attemptId === result.attemptId,+ )?.candidateId;+ await handleEvent(+ createAuthorizationCompletedEvent({+ attemptId: result.attemptId,+ authorization,+ candidateId,+ name: result.name,+ outcome: "authorized",+ sequence: emissionState.sequence,+ stepIndex: emissionState.stepIndex,+ turnId: emissionState.turnId,+ }),+ );+ }+ }- const capabilities = ctx.get(CapabilitiesKey);-- const runHarnessStep = async (- lifecycleSession: HarnessSession,- stepInput: StepInput | undefined,- ): Promise<StepResult> => {- const refreshedSession = refreshSessionFromTurnAgent({- compactionOverrides: {- thresholdPercent: effectiveAgent.thresholdPercent,- },- session: lifecycleSession,- systemPromptAdditions: taskUpdatesEnabled ? [TASK_UPDATE_SESSION_INSTRUCTION] : undefined,- turnAgent: effectiveAgent.turnAgent,- });- const modelSession = refreshedSession;-- const step = createExecutionNodeStep({- abortSignal: input.abortSignal,- capabilities,- clearOnly: input.input?.kind === "clear",- compactOnly: input.input?.kind === "compact",- createRuntime: createWorkflowRuntime,- handleEvent,- historyProjector: history.projector,- historyView: history.prepare(modelSession),- instrumentation,- mode,- modelResolutionScope: {- moduleMap: bundle.moduleMap,- nodeId: bundle.nodeId,- },- node: effectiveNode,- workflowMaxSubagents: refreshedSession.workflowMaxSubagents,+ return runHarnessStep(schemaSession, stepInput);});- return step(modelSession, stepInput);- };-- return runHarnessStep(schemaSession, resolved);+ throwIfTurnAborted(input.abortSignal);+ completedModelCall = { result, serializedContext: serializeContext(ctx) };+ return result;+ },});} catch (error) {if (!isTurnCancellation(error) && input.abortSignal?.aborted !== true) {@@ -567,43 +579,13 @@ export async function turnStep(rawInput: TurnStepInput): Promise<DurableStepResuthrow error;}writer.releaseLock();- // Trace and instrumentation state are needed by the cancellation- // epilogue to close the operation the discarded step opened.- // The session model is also kept because `session.started` is not emitted- // again after this cancellation settles.- const interrupted = serializeContext(ctx);- const retained = readRetainedBackgroundToolResult(ctx);- // Runs inside the ALS scope: preserving the message stages its- // attachments, and `stageAttachmentsToSandbox` reads the sandbox off the- // active context. The harness step's own scope closed when it threw, so- // without this the cancellation epilogue fails with "No active eve- // context" whenever the discarded turn carried a file part.- const cancelledSession = await contextStorage.run(ctx, () =>- preserveCancelledTurnMessage(retained?.backgroundTaskSession ?? initialSession, resolved),- );- return {- action: "cancelled",- ...(retained === undefined- ? {}- : {- backgroundTaskState: createDurableSessionState({ session: cancelledSession }),- backgroundTasks: retained.backgroundTasks,- }),- serializedContext: preserveSerializedInstrumentationState(- preserveSerializedAgentTraceState(- preserveSerializedSessionDynamicModelSelection(- {- ...input.serializedContext,- [TurnDeliveryIdsKey.name]: interrupted[TurnDeliveryIdsKey.name],- },- interrupted,- ),- interrupted,- ),- interrupted,- ),- sessionState: createDurableSessionState({ session: cancelledSession }),- };+ return createCancelledModelCallBatchResult({+ beforeBatchContext: input.serializedContext,+ checkpoint: completedModelCall,+ ctx,+ initialSession,+ stepInput: resolved,+ });}// Re-stamp if a handler called `session.continuation.rekey(...)` (eg. Slack auto-anchor).diff --git a/packages/eve/src/internal/authored-definition/core.test.ts b/packages/eve/src/internal/authored-definition/core.test.tsindex 7df139524..3d9903b65 100644--- a/packages/eve/src/internal/authored-definition/core.test.ts+++ b/packages/eve/src/internal/authored-definition/core.test.ts@@ -227,6 +227,41 @@ describe("normalizeAgentDefinition", () => {expect(definition.experimental?.workflow).toEqual({ world: "@workflow/world-postgres" });});+ it("accepts a positive model-call batch size", () => {+ const definition = normalizeAgentDefinition(+ {+ model: "openai/gpt-5.5",+ experimental: {+ workflow: {+ modelCallsPerStep: 4,+ },+ },+ },+ FAILURE_MESSAGE,+ );++ expect(definition.experimental?.workflow?.modelCallsPerStep).toBe(4);+ });++ it.each([0, 1.5, -1, Number.POSITIVE_INFINITY, "4"])(+ "rejects invalid model-call batch size %j",+ (value) => {+ expect(() =>+ normalizeAgentDefinition(+ {+ model: "openai/gpt-5.5",+ experimental: {+ workflow: {+ modelCallsPerStep: value,+ },+ },+ },+ FAILURE_MESSAGE,+ ),+ ).toThrow(FAILURE_MESSAGE);+ },+ );+it("rejects non-string workflow world values", () => {expect(() =>normalizeAgentDefinition(diff --git a/packages/eve/src/internal/authored-definition/core.ts b/packages/eve/src/internal/authored-definition/core.tsindex 033628ad2..f3e41287f 100644--- a/packages/eve/src/internal/authored-definition/core.ts+++ b/packages/eve/src/internal/authored-definition/core.ts@@ -258,9 +258,16 @@ function normalizeAgentWorkflowDefinition(message: string,): AgentWorkflowDefinition {const record = expectObjectRecord(value, message);- expectOnlyKnownKeys(record, ["world"], message);+ expectOnlyKnownKeys(record, ["modelCallsPerStep", "world"], message);const normalizedDefinition: Mutable<AgentWorkflowDefinition> = {};+ if (record.modelCallsPerStep !== undefined) {+ normalizedDefinition.modelCallsPerStep = expectPositiveInteger(+ record.modelCallsPerStep,+ message,+ );+ }+if (record.world !== undefined) {normalizedDefinition.world = normalizeAgentWorkflowWorldDefinition(record.world, message);}diff --git a/packages/eve/src/public/definitions/exact.test.ts b/packages/eve/src/public/definitions/exact.test.tsindex 94a121aac..b4490cc9a 100644--- a/packages/eve/src/public/definitions/exact.test.ts+++ b/packages/eve/src/public/definitions/exact.test.ts@@ -37,6 +37,11 @@ describe("definition helper exact inputs", () => {it("preserves literal inference for valid definitions", () => {const agent = defineAgent({description: "type-test",+ experimental: {+ workflow: {+ modelCallsPerStep: 4,+ },+ },limits: {maxInputTokensPerSession: 200_000,maxOutputTokensPerSession: 20_000,@@ -52,6 +57,7 @@ describe("definition helper exact inputs", () => {});expect(agent.description).toBe("type-test");+ expect(agent.experimental.workflow.modelCallsPerStep).toBe(4);expect(agent.limits.maxInputTokensPerSession).toBe(200_000);expect(agent.limits.maxOutputTokensPerSession).toBe(20_000);expect(agent.limits.maxTokenCostUsdPerSession).toBe(1.5);diff --git a/packages/eve/src/runtime/resolve-agent.ts b/packages/eve/src/runtime/resolve-agent.tsindex 6b1b9f811..e3dd94557 100644--- a/packages/eve/src/runtime/resolve-agent.ts+++ b/packages/eve/src/runtime/resolve-agent.ts@@ -245,7 +245,10 @@ function createResolvedAgentConfig(workflow:manifest.config.experimental.workflow === undefined? undefined- : { world: manifest.config.experimental.workflow.world },+ : {+ modelCallsPerStep: manifest.config.experimental.workflow.modelCallsPerStep,+ world: manifest.config.experimental.workflow.world,+ },};}diff --git a/packages/eve/src/shared/agent-definition.ts b/packages/eve/src/shared/agent-definition.tsindex 253100374..8ec938e78 100644--- a/packages/eve/src/shared/agent-definition.ts+++ b/packages/eve/src/shared/agent-definition.ts@@ -221,8 +221,7 @@ export interface AgentExperimentalDefinition {*/readonly tasks?: boolean;/**- * Durable Workflow runtime configuration. Root agents may use this to select- * the Workflow world backing sessions and runs.+ * Durable Workflow runtime configuration.*/readonly workflow?: AgentWorkflowDefinition;}@@ -259,6 +258,16 @@ export type AgentWorkflowWorldDefinition = string;* Advanced durable-runtime configuration for eve's Workflow SDK integration.*/export interface AgentWorkflowDefinition {+ /**+ * Maximum number of turn-model calls eve may run inside one durable Workflow step.+ *+ * Values greater than one reduce Workflow checkpoint overhead but widen the+ * replay unit: if the Workflow step is interrupted, earlier model calls and+ * inline tool executions in the same step may run again.+ *+ * @default 1+ */+ readonly modelCallsPerStep?: number;/*** Workflow world module used for durable workflow storage, queueing, hooks,* and streaming.diff --git a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.tsindex ca7b6280f..73a3e1c88 100644--- a/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts+++ b/packages/eve/test/scenarios/mounted-extension-installed.scenario.test.ts@@ -249,7 +249,7 @@ describe("mounted extension installed under node_modules", () => {);expect(JSON.parse(extensionFiles[`node_modules/${PACKAGE_NAME}/dist/extension/_manifest.json`]!),- ).toMatchObject({ requires: { channel: 19, schedule: 11, subagent: 10 } });+ ).toMatchObject({ requires: { channel: 19, schedule: 11, subagent: 11 } });const app = await scenarioApp({name: "mounted-extension-installed",installDependencies: true,diff --git a/research/multi-call-workflow-steps.md b/research/multi-call-workflow-steps.mdnew file mode 100644index 000000000..633f258ed--- /dev/null+++ b/research/multi-call-workflow-steps.md@@ -0,0 +1,148 @@+---+issue: https://github.com/vercel/eve/issues/876+status: implemented+last_updated: "2026-09-09"+---++# Multi-call Workflow steps++## Summary++Today one eve model step — one turn-model call and the inline tool calls it+makes — runs in one durable Workflow step. This gives every model step its own+checkpoint, but it also pays Workflow scheduling and persistence overhead+between sequential tool cycles.++Add an experimental per-agent option that runs up to N adjacent model steps in+one Workflow step:++```ts+import { defineAgent } from "eve";++export default defineAgent({+ model: "openai/gpt-5.6-luna",+ experimental: {+ workflow: {+ modelCallsPerStep: 4,+ },+ },+});+```++The default remains `1`. The value is a positive integer and is a ceiling: a+turn that finishes or must park after fewer calls exits the Workflow step+immediately.++This option deliberately widens the replay unit. If call 3 is interrupted,+calls 1–3 in that Workflow step may run again, including their inline tools.+Authors opting in must make affected side effects idempotent and must accept+duplicate model spend and stream events after recovery.++## Execution boundary++Keep `createToolLoopHarness` at `stopWhen: isStepCount(1)`. It remains the owner+of exactly one logical eve step, including step events, tool execution,+compaction, dynamic capability resolution, session limits, and result handling.++Add only a bounded loop around the existing harness invocation in+`turnStep`:++```text+one durable Workflow turnStep+ ├─ existing harness step 0+ ├─ existing harness step 1+ ├─ ... up to configured N+ └─ return one durable result to the turn workflow+```++After each model call, run the existing framework context-provider commit in+memory and feed its returned session into the next call. These intermediate+sessions are visible to later calls in the same batch but are not durable until+`turnStep` returns successfully.++Continue inside the current Workflow step only when all are true:++- the harness returned `next: runStep` with no pending input request;+- fewer than N model calls have run; and+- the result did not start a background task that needs the parent commit+ barrier.++Every other result returns to the turn workflow immediately. Existing paths+therefore keep a durable boundary before external coordination:++- approval, question, and authorization parks;+- blocking workflow-tool and subagent dispatch;+- background-task acknowledgement;+- cancellation, failure, and terminal turn settlement.++Provider-executed tools and ordinary authored tools remain inline and do not+force an early checkpoint. eve does not attempt to infer whether a tool is+idempotent; the agent-level opt-in is the entire policy.++## Observable semantics++Logical eve steps do not change. Each model call still increments `stepIndex`+and emits its own `step.started`, action events, `step.completed`, usage, and+instrumentation. History and state observed by the next model call are the same+as with `1`.++Only durability changes:++| Behavior | Default (`1`) | Experimental (`N > 1`) |+| ------------------------ | ----------------------------------------- | --------------------------------------------------- |+| Workflow checkpoint | after every model call | after at most N model calls |+| Crash replay | current model/tool cycle | every uncommitted cycle in the batch |+| Inline tool side effects | may repeat for the interrupted cycle | may repeat for earlier cycles in the batch |+| Model charges | current interrupted call may repeat | earlier calls in the batch may also repeat |+| Stream recovery | interrupted step events may be duplicated | events from the uncommitted batch may be duplicated |+| Approval/auth/task waits | durable boundary | unchanged durable boundary |++Compaction summary calls and in-process retries do not consume the N budget;+the setting counts completed turn-model steps. Crash recovery replays the+uncommitted batch. Steering instead aborts the active model-and-tool cycle,+commits earlier completed cycles in the batch, and starts the replacement turn+from that state in the next Workflow step.++## Implementation++1. Add `experimental.workflow.modelCallsPerStep?: number` to the public agent+ definition and carry it through compiled-manifest validation, cloning, and+ runtime resolution. Reject non-positive, non-integer values. Static root and+ subagent definitions may select it; dynamic subagent configuration continues+ to reject all experimental fields.+2. In `execution/workflow-steps.ts`, extract the current single harness+ invocation into a small helper and call it in a bounded loop. Re-enter+ `runBackgroundStep` for every logical model step so session, connection,+ sandbox, and background-tool providers retain their existing per-step+ lifecycle. Stop before another model call when the result carries+ `backgroundTasks` or its session still has a pending input batch.+3. Leave the harness, `StepResult`, turn-workflow protocol, durable session+ schema, stream protocol, and AI SDK `stopWhen` unchanged. No scheduler,+ batch object, tool annotation, or recovery path is added.+4. Document the option beside Workflow configuration and replace the blanket+ one-call durability statement with the default plus the explicit opt-in+ replay tradeoff. Add a patch changeset.++## Verification++- Public-definition and manifest tests accept positive integers, reject invalid+ values, and preserve the default when omitted.+- Focused `turnStep` tests prove a configured batch can complete three ordered+ model steps in one call, the omitted option preserves one step, and pending+ input or a background task ends the batch. Cancellation coverage proves+ steering retains completed calls in a batch while discarding the active call.+- The `agent-tools` end-to-end fixture enables a three-call ceiling and runs its+ deterministic sequential two-tool eval through the compiled public config.+- Before the option is recommended beyond experiments, a hosted paired runtime+ benchmark should compare `1`, `2`, `4`, and `8` on a deterministic sequential+ tool chain. It should show the expected reduction in `turnStep` count and a+ material latency improvement without changing model call count or protocol+ output.++## Out of scope++- Automatic idempotency, exactly-once side effects, or per-tool eligibility.+- Batching across a park, background-task commit barrier, or runtime-action+ dispatch.+- Changing model parallel tool-call behavior within one model response.+- Changing the default from `1` or promising a stable experimental API.diff --git a/research/turn-performance.md b/research/turn-performance.mdindex 6f95c59ad..17aa5f65b 100644--- a/research/turn-performance.md+++ b/research/turn-performance.md@@ -1,7 +1,7 @@---issue: https://github.com/vercel/eve/issues/876status: proposed-last_updated: "2026-09-01"+last_updated: "2026-09-04"---# Turn performance and Workflow overhead@@ -659,9 +659,10 @@ Expose slow-provider diagnostics. Separate internal network exporter drain fromprovider `flush()` contract, move only the exporter drain to a host-retained boundary, and keepauthored flush awaited at actual park/done/error transitions.-Do not combine side-effectful tool cycles into one replayable step unless each tool invocation-keeps an independent durable idempotency checkpoint. Faster retries that repeat external effects-are a correctness regression.+Keep one model/tool cycle per durable step by default. The opt-in+[multi-call Workflow step proposal](./multi-call-workflow-steps.md) deliberately widens that replay+unit for applications willing to trade repeated model calls, tool side effects, and stream events+after an interruption for lower sequential-cycle latency.#### Instrumentation flush audit