feat(agent): split a step into a model call, its tool calls and a seal

[moedash]

What changed?

AgentSession.modelCall(), runToolCall(id) and sealStep(results) split one step into three, and turn.steps hands the same three to a registered executor. modelCall() reports the calls the model asked for, recorded and not run. runToolCall() settles one and reports its result without entering it in the transcript. sealStep() records the results in the order the model asked for the calls, and says whether the turn keeps going.

runSingleTurn is those three composed, so a turn pi runs itself and a turn driven from outside stay one implementation. mustRunToolCallsInOrder and unknownToolCallOutcome are exported: a caller that fans the calls out cannot otherwise know a tool declared itself sequential, and prepareStep() held the unknown-outcome wording privately.

Stacked on #3, which added registerTurnExecutor. Two fixes ride along on its branch: two extension-runner test doubles predate getTurnExecutor() and fail as soon as a turn is driven, and createProvider inferred the Cloudflare gateway's api map from whichever models the fetched catalog listed, so a catalog that dropped one stopped the build.

Why?

A step was one function: stream the assistant message, run its whole tool batch, decide whether to continue. Nothing could sit between the model asking for a tool and the tool running, so a per-tool retry policy, a timeout, an approval or a budget had nowhere to live. beforeToolCall is no help, because it runs inside the same step.

The results go in together on purpose. A caller running calls concurrently settles them out of order, and the session file is a tree whose entries take their parent from the leaf their writer last saw, so two writers appending as they finish branch it. Pi's own parallel path already appends in call order after the batch, so reporting a result and letting the seal record them leaves the transcript the one pi would have written anyway.

replayed is the other half. Without it a caller that lost its record of the step pays for the response twice, and the first response's calls are left for the next resume to report as unknown outcomes when nothing ran them.

How did you test it?

• Unit Tests
• Staging
• End to End Tests

npm run check passes and both suites are green. New tests cover each part on its own, and two catch drift: a turn split into three parts and a turn the loop runs itself leave the same transcript, checked at the loop level, at the session file, and in turn-executor.test.ts through the executor seam.

Review went seven rounds and each found something. Everything below has a test that fails without its fix.

The post-run pass never ran on a seal. _lastAssistantMessage comes from an event the seal's session does not see, so a provider error never retried and a full context never compacted. Both seal paths share _postSealPass now. The retry budget goes with it: its counter lives on a session the worker path rebuilds per activity, so it read zero every time and a failing provider would have been asked again until the step ceiling. It is counted off the transcript instead, and _countTrailingFailures says out loud that keeping error entries is a contract, not an accident. A retry the pass already decided on is carried rather than re-derived, because _prepareRetry takes the errored message out of memory and a second attempt of that seal cannot see what the first one chose.

An abort reached only the unit running at the time, so a stepped turn took another model call after the user stopped it. The flag lives on Agent rather than AgentSession, because Escape calls Agent.abort() directly. prompt() and continue()'s drain branches clear it, since each starts a turn.

Smaller: a replayed model call opened no turn but its seal still ended one; a second modelCall() on an open step answered "the response ended the run", which had the caller seal a step it never opened; and clearInterrupt is called optionally, so an older build of the core package degrades instead of killing every turn.

Later rounds moved three things out of the loop and into the caller. The seal is told which step it closes, by the call ids, and refuses a message that asked for a different set, because on a durable driver the model call and the seal are separate units of work minutes apart. It takes the retry count from the caller too, since the transcript it otherwise derives it from is something a compaction rewrites, and it hands back what the step spent so a caller that outlives the session can carry it. postRun: false closes a step without deciding whether to retry or compact, which is work nobody asked for on a turn the user just stopped. abandonStep() is for a driver that gives up between the model call and the seal, which would otherwise leave the session unable to be interrupted, resumed or stepped again.

Driven live against gpt-4o-mini through temporalio/pi-temporal. A two-file turn cost a model call, two overlapping tool calls and a seal, then a model call and a seal. I killed the process between a tool starting and its result landing: the call came back as an unknown outcome, and the tool did not run a second time.

Since this description was written

Every session write can be guarded. SessionManager.setWriteGuard lets a driver refuse an append that is no longer its own. The driver that needs it holds a lock beside the session file, and the write it has to guard is the assistant message at the end of a stream that runs for minutes: an awaited check before the model call is not a check on that write at all. The guard is called on the single append funnel, so an extension writing from a tool callback is covered by the same rule as the driver.