ref(chat): Decompose agent executor into chat/agent phase modules

[dcramer]

executeAgentRunInPrivacyContext was a ~2,100-line function whose dozen mutable closure variables existed so the catch block could persist yield, timeout, and auth-pause continuations. This completes the #746 contract cleanup by decomposing the executor into a chat/agent/ module — the module path names the subsystem (the agent), while run/slice vocabulary stays in function and type names (executeAgentRun, AgentRunOutcome):

• request.ts — the six role-group types plus routing interpretation (requester derivation, surface inference, destination asserts, session identifiers)
• resume.ts — run resumability: safe-boundary checkpoints, the durable input commit, resume snapshots, and translation of expected endings into AgentRunOutcome values, so the executor catch block is a thin translation plus genuine-error guards
• tools.ts — sandbox executor, MCP/plugin auth orchestration, provider restoration from durable history, and the Pi tool surfaces behind one params/return contract
• prompt.ts — user-turn content parts, steering message shape, resume-safe history trimming, and full prompt assembly
• skills.ts, session.ts, sandbox.ts — the remaining phases; index.ts stays the composition root with the provider retry loop inline to preserve abort-settlement, usage, and span ordering

Behavior is unchanged: persistence ordering, telemetry keys, and delivery semantics are preserved, and the existing yield/timeout/auth-pause integration tests plus the full suite pass unmodified except where the request shape below moved.

Two request-contract cleanups deferred from the earlier phases land here. The private flattenAgentRunRequest shim is dissolved — phases consume the role groups directly. And persisted sandbox reuse state (sandboxId, dependency profile hash) moves from the policy group to state.sandbox, with the egress trace override staying in policy as sandboxTracePropagation; all request producers are updated and the resume paths rebuild this from thread state, so nothing persisted changes shape.

agent-run-helpers.ts is dissolved along domain lines: Pi transcript predicates and runtime-turn-context manipulation move to chat/pi/transcript.ts (they were consumed by seven services/runtime modules, nothing agent-specific), the reply-quality text classifiers become private to services/turn-result.ts (their only consumer), summarizeMessageText joins chat/logging, and the prompt/skill helpers join their phase modules. Two exports with no production callers (getSuccessfulToolCalls, prependMissingRuntimeTurnContext) are deleted with their tests.

Review order: start with chat/agent/index.ts (the orchestration skeleton and the slimmed catch block), then resume.ts against the old inline persistence branches, then tools.ts/prompt.ts which are mostly code motion behind explicit contracts. The first commit is a pure file move; the second is the decomposition.

Fixes #746

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
junior-docs	Ready	Preview, Comment	Jul 5, 2026 12:53am