Summary

This PR adds a Chat SDK messenger example and the managed fiber APIs needed to make webhook-driven AI replies durable, idempotent, inspectable, and recoverable.

The example uses Chat SDK as the messenger abstraction, Telegram as the current adapter, Agents subagents for Chat SDK state, and a Think-backed conversation subagent for AI replies. The core Agents SDK gains startFiber() and related APIs so application-owned jobs, such as webhook reply work, can be accepted once, deduped across retries, inspected later, cancelled, cleaned up, and explicitly recovered after eviction.

Why

Webhook-driven chat integrations have an awkward failure boundary:

• Providers can retry the same webhook after a timeout.
• LLM turns can run longer than webhook deadlines.
• A Durable Object can be evicted while a visible reply is mid-stream.
• Retrying blindly can duplicate replies.
• Returning quickly without a retained job record makes status and recovery opaque.
• Raw runFiber() is useful for crash recovery, but it does not provide a stable public job identity, idempotency key, retained terminal status, or an explicit application recovery result.

This PR adds a higher-level managed fiber layer on top of runFiber() for those application-owned jobs, then uses it in the Chat SDK messenger example.

What Changed

Chat SDK messenger example

Adds examples/chat-sdk-messenger, a server-only Worker example that demonstrates:

• Chat SDK webhook ingress using Telegram as the current provider adapter.
• A Chat SDK StateAdapter backed by an Agents subagent.
• A Think-backed ConversationAgent subagent for AI replies.
• Streaming AI text into Chat SDK message updates.
• Recovery behavior for interrupted reply jobs.
• Documentation that frames Chat SDK as the core abstraction and Telegram as a replaceable adapter.

The example intentionally keeps provider-specific behavior thin so future adapters can reuse the same shape.

Think streaming and cancellation

The Think path now supports RPC-safe streamed turns for this use case:

• chat() streams text deltas through a serializable callback target.
• The callback receives a start event with a request ID.
• Callers can cancel with cancelChat(requestId) / cancelAllChats() instead of passing non-serializable AbortSignals across Durable Object RPC.
• Streaming edge cases are handled in the messenger example, including empty responses, partial failures, post failures, and cancellation.

Managed fiber jobs

Adds a retained managed job layer to Agent:

• startFiber() durably accepts a background job.
• idempotencyKey dedupes retries.
• fiberId gives stable identity.
• inspectFiber() / inspectFiberByKey() expose retained status.
• listFibers() supports status inspection.
• cancelFiber() / cancelFiberByKey() record cooperative cancellation.
• deleteFibers() cleans up retained terminal rows.
• resolveFiber() lets app-level recovery resolve interrupted jobs.
• onFiberRecovered() can return a FiberRecoveryResult to record explicit recovery policy.

Managed fibers retain terminal status separately from the transient cf_agents_runs rows used by raw fibers. This gives callers a durable job ledger without breaking the existing runFiber() primitive.

waitForCompletion

Adds waitForCompletion: true to startFiber() for cases where the caller should wait until the retained job reaches a terminal status.

The messenger example uses this to preserve Chat SDK's visible reply serialization semantics. Without it, durable acceptance would return quickly and allow multiple visible replies to overlap in the same thread.

The implementation waits on managed fiber terminal ledger status, not just the callback promise, so cancellation and recovery unblock waiters correctly.

Recovery semantics

Managed fiber recovery is explicit:

• Successful execution records completed.
• Thrown callbacks record error.
• Cancellation records aborted.
• Eviction or lost execution records interrupted.
• onFiberRecovered() may return { status: "completed" | "error" | "aborted" | "interrupted" }.
• Returning undefined leaves the row interrupted.
• Throwing during recovery leaves the row interrupted and records the recovery error.
• resolveFiber() only updates currently interrupted rows.

deleteFibers() defaults to deleting completed, error, and aborted rows, while preserving interrupted rows for inspection or manual/application-level resolution.

Public API Notes

New managed fiber APIs are additive and backward-compatible with existing runFiber() usage.

Important naming choices:

• Public inspection uses settledAt, because the timestamp applies to any terminal state, not only successful completion.
• Cleanup uses settledBefore for the same reason.
• The database column remains internal and does not affect the public API.

Documentation

Updates docs for:

• Durable execution and managed fiber recipes.
• Agent class reference.
• Long-running agent guidance.
• Think turn API selection.
• Think programmatic submissions.
• Webhook and server-driven message guidance.
• Chat SDK messenger production behavior and future TODOs.
• Think package and example README references.

The docs clarify the intended boundary:

• submitMessages() owns durable Think conversation admission.
• startFiber() owns external application jobs around a turn.
• Workflows own multi-step orchestration.
• Think/AIChat internals continue using raw runFiber() for stream recovery because those are internal recovery fibers, not externally inspectable application jobs.

Tests

Adds and updates unit and E2E coverage for managed fibers and the messenger example.

Covered cases include:

• New managed fiber acceptance.
• Duplicate idempotency keys.
• Explicit fiberId behavior.
• Cancellation.
• Callback failures.
• waitForCompletion for new and duplicate jobs.
• Waiters resolving after cancellation.
• Default cleanup preserving interrupted rows.
• Managed fiber recovery result application.
• Sub-agent managed fiber recovery.
• Process-kill E2E recovery through wrangler dev.
• Duplicate waitForCompletion after restart/stale ledger recovery.
• Messenger state adapter behavior.
• Messenger AI reply policy helpers.

Verification

Ran:

• npm run test:workers -w agents -- "src/tests/run-fiber.test.ts"
• npm run test:e2e -w agents
• npm run test -w @cloudflare/agents-chat-sdk-messenger
• npm run check

Note: one npm run check attempt hit a transient experimental/gadgets-chat agents/react type resolution failure. Rerunning npm run check passed with all 85 projects typechecking successfully.

Review Focus

Suggested review areas:

• Managed fiber API shape and naming.
• waitForCompletion semantics, especially duplicate calls, cancellation, and recovery.
• Whether interrupted should remain excluded from default cleanup.
• Messenger example architecture: Chat SDK as core, Telegram as adapter, Agents subagents for state, Think subagent for intelligence.
• Recovery policy DX: whether FiberRecoveryResult is explicit enough for applications.
• Docs clarity around runFiber() vs startFiber() vs submitMessages() vs Workflows.

Follow-Ups

Not included in this PR:

• Telegram-specific retry buttons or admin commands.
• Messenger-specific process-kill E2E tests.
• Moving Think or AIChat internals from raw runFiber() to managed fibers.
• Production bot features such as operator dashboards or provider-specific recovery UI.

Made with Cursor