Fix agent-tool recovery startup wedges

[threepointone]

Summary

• Move stale agent-tool run reconciliation out of the Agent startup gate so parent Durable Objects can boot even when child facets are stuck or recursively recovering.
• Snapshot only rows that were stale before user onStart runs, then reconcile that snapshot in ctx.waitUntil with a single-flight guard.
• Bound child inspection and recovery chunk replay; timed-out or uninspectable rows are terminal-finalized as interrupted so future wakes do not retry the same wedged recovery cascade.
• Reuse the already-resolved child adapter for recovery chunk replay to avoid an extra child facet initialization during reconciliation.
• Add AIChat and Think coverage for completed, running, stuck, scheduled, single-flight, and Think startup-ordering recovery scenarios.

Why

Issue #1595 reports parent Agent Durable Objects becoming permanently wedged when startup recovery encounters stale cf_agent_tool_runs rows. The old startup path awaited _reconcileAgentToolRuns() inside PartyServer's blockConcurrencyWhile startup gate. Reconciliation synchronously resolved child facets via _cf_resolveSubAgent() / _cf_initAsFacet(), which forces the child through its own startup and can recursively drive more recovery. If that tree exceeds the runtime startup budget, the parent resets before marking rows terminal, so the same stale rows wedge every subsequent wake.

This change keeps parent startup live by making startup recovery asynchronous and bounded. It preserves best-effort recovery of completed child results, but prioritizes liveness by interrupting rows that cannot be inspected promptly.

Behavior changes

• onStart() may now observe stale agent-tool rows that recovery will finalize shortly afterward.
• Recovered onAgentToolFinish() hooks now run after startup, not before user onStart() completes.
• Clients may briefly replay a stale running tool before receiving the recovered terminal event.
• Recovery is scoped to rows that were already stale before user startup began, so tool runs created during onStart() or immediately after startup are not accidentally interrupted by the startup recovery task.

Test plan

• npx nx run agents:build
• cd packages/ai-chat && npm run test:workers -- src/tests/agent-tools.test.ts
• cd packages/think && npm run test:workers -- src/tests/agent-tools.test.ts
• npm run check

Notes: npm run check passes. Sherif still reports the existing warnings for example workspace folders that do not have package.json files:

• examples/agent-skills/package.json
• examples/think-tanstack-start/package.json
• examples/think-react-router/package.json

Coverage added

• AIChat parent recovery finalizes stuck child facet startup via timeout.
• AIChat scheduled recovery finalizes stale rows and remains single-flight.
• Think parent runAgentTool(ThinkTestAgent, ...) happy path.
• Think completed child recovery preserves completed terminal state.
• Think still-running child recovery becomes interrupted.
• Think stuck child facet startup times out and finalizes as interrupted.
• Think scheduled recovery finalizes stale rows and remains single-flight.
• Think startup-ordering test proves startup returns while stale rows are still running, then background recovery finalizes only the pre-startup snapshot.
• Think startup snapshot test proves rows created during user onStart() are not interrupted by startup recovery.

Made with Cursor

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 52fa2e8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agents	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[devin-ai-integration]

Devin Review found 1 potential issue.

View 5 additional findings in Devin Review.

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@1604

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@1604

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@1604

hono-agents

npm i https://pkg.pr.new/hono-agents@1604

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@1604

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@1604

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@1604

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@1604

commit: 52fa2e8