feat(workflow): stable script-thrown error contract

[Waishnav]

Summary

• keep the Dynamic Workflow primitive set unchanged
• normalize errors thrown by agent() and nested workflow() into WorkflowScriptRuntimeError
• expose stable provider-independent kind, message, and retryable fields to normal JavaScript try/catch
• preserve existing Claude-like defaults: direct calls throw and parallel() / pipeline() still map uncaught branch failures to null
• teach local attempt() helpers for failure-aware fan-out without adding a new primitive

Stack

• Base: pr/dw-9-resume-iteration-inspection (PR feat(workflow): script iteration, replay provenance, and call inspection #108)
• Branch: pr/dw-10-script-error-contract
• This is the sibling alternative to PR feat(workflow): opt-in settled result API #109. Review both and merge only the preferred approach.

Commit structure

1. feat(workflow): define script error contract
2. feat(workflow): normalize script-thrown errors
3. test(workflow): cover script error handling
4. docs(workflow): teach typed error handling

Test plan

• npm run typecheck
• npm test
• npm run build
• git diff --check
• tests cover provider fallback through try/catch
• tests cover retryable provider failures preserved inside parallel fan-out
• tests verify journaled failure kinds remain accurate
• existing nested-workflow and cancellation behavior remains covered

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 84cee33f-840d-4cf6-8039-94f1299108e0

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch pr/dw-10-script-error-contract

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}