Skip to content

Add onError callback to durable agent stream calls - #200

Open
TommyBez wants to merge 2 commits into
mainfrom
claude/agent-onerror-callback-lwnhnm
Open

Add onError callback to durable agent stream calls#200
TommyBez wants to merge 2 commits into
mainfrom
claude/agent-onerror-callback-lwnhnm

Conversation

@TommyBez

@TommyBez TommyBez commented Jun 8, 2026

Copy link
Copy Markdown
Owner

The DurableAgent.stream() options expose an onError callback that fires on
streaming errors. Wire it up for the invocation and heartbeat handlers to log
the error and emit a best-effort activity breadcrumb. The realtime ToolLoopAgent
runner does not expose onError, so it is left unchanged.

Summary by CodeRabbit

  • New Features

    • Added user-friendly error messages for agent runtime failures, replacing generic technical errors with actionable guidance for authentication issues, rate limiting, and temporary failures.
  • Bug Fixes

    • Improved error handling in chat streaming to prevent raw provider errors from reaching users and to properly intercept stream failures with contextual logging.
  • Tests

    • Added test coverage for error handling workflows across agent streaming components.

claude added 2 commits June 8, 2026 22:35
The DurableAgent.stream() options expose an onError callback that fires on
streaming errors. Wire it up for the invocation and heartbeat handlers to log
the error and emit a best-effort activity breadcrumb. The realtime ToolLoopAgent
runner does not expose onError, so it is left unchanged.
…ages

ToolLoopAgent.stream() does not expose an onError option, so non-fatal errors
arrive as 'error' parts on the fullStream rather than thrown. Intercept them in
the tap, log them, and swallow the raw chunk so channels never render provider
internals.

Add a shared humanReadableAgentError() helper that maps known errors (missing
credentials, provider 401/403/429/5xx, aborts) to concise user-facing text and
falls back to a generic message instead of leaking raw provider output. Wire it
into the web chat UI streams (createUIMessageStream + createAgentUIStream
onError, replacing the SDK default 'An error occurred.') and the channel
text-only path (posted via postText).
@vercel

vercel Bot commented Jun 8, 2026

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
outname Ready Ready Preview, Comment, Open in v0 Jun 8, 2026 10:54pm
outname-api Ready Ready Preview, Comment Jun 8, 2026 10:54pm
outname-app Ready Ready Preview, Comment Jun 8, 2026 10:54pm

Request Review

@coderabbitai

coderabbitai Bot commented Jun 8, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1947b193-952d-4619-90f1-1efd7d873be0

📥 Commits

Reviewing files that changed from the base of the PR and between 453e0fb and 22e3de6.

📒 Files selected for processing (6)
  • packages/ai/agent-runtime/server/human-readable-error.test.ts
  • packages/ai/agent-runtime/server/human-readable-error.ts
  • packages/ai/agent-runtime/server/realtime-chat-runner.test.ts
  • packages/ai/agent-runtime/server/realtime-chat-runner.ts
  • packages/ai/agent-runtime/workflows/session/handlers/handle-heartbeat.ts
  • packages/ai/agent-runtime/workflows/session/handlers/handle-invocation.ts

Walkthrough

The PR adds human-readable error handling throughout the agent runtime's streaming infrastructure. A new utility converts agent errors into safe user messages, then integrates that utility into realtime chat streaming with error callbacks for both UI and text-only channels, and extends workflow handlers to report stream failures gracefully.

Changes

Agent streaming error handling

Layer / File(s) Summary
Human-readable error utility
packages/ai/agent-runtime/server/human-readable-error.ts, packages/ai/agent-runtime/server/human-readable-error.test.ts
New module humanReadableAgentError converts errors to user-safe messages: passes through missing credential errors, maps API status codes (401/403→credentials, 429→rate-limit, 5xx→temporary), reports abort errors distinctly, and falls back to a generic message. Test coverage validates each error branch.
Chat runner streaming integration
packages/ai/agent-runtime/server/realtime-chat-runner.ts
UI and text-only streaming paths add error callbacks. UI stream logs errors and converts them via humanReadableAgentError. Text-only stream uses tapFullStream with an onError callback to intercept and suppress error chunks while preserving already-streamed text, then posts a human-readable notice after streaming. tapFullStreamGenerator is extended to accept onError and swallow error chunks.
Chat runner test coverage
packages/ai/agent-runtime/server/realtime-chat-runner.test.ts
Tests verify that tapFullStream invokes the error callback and suppresses error chunks while continuing to accumulate text. An integration test simulates a provider error chunk, asserts error chunks are not forwarded to the channel, a human-readable notice is posted, and errors are logged.
Workflow handler error callbacks
packages/ai/agent-runtime/workflows/session/handlers/handle-heartbeat.ts, packages/ai/agent-runtime/workflows/session/handlers/handle-invocation.ts
Heartbeat and invocation handlers add onError callbacks to stream invocations. Each callback logs the error with context, emits a best-effort activity update, and suppresses emission failures to allow run-finalization logic to proceed.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 When streams run wild with errors deep,
A rabbit's fix will make 'em weep,
With human words, not code so grim,
We surface truths, not error whim,
Through callbacks wrapped with loving care!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 15.38% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately reflects the primary change: adding onError callbacks to durable agent stream calls across handlers, which is the core technical objective of this PR.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch claude/agent-onerror-callback-lwnhnm

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants