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

Summary by CodeRabbit

• New Features
  • Added a stable, structured error contract for workflow failures, including error type, category, message, and retryability.
  • Workflows can now catch errors and choose provider fallbacks based on the error category.
  • Parallel tasks preserve individual success and failure results instead of failing as a group.
• Documentation
  • Added guidance and examples for handling, branching on, and retaining workflow errors, including behavior after resume.

[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:

• ✅ Review completed - (🔄 Check again to review again)

✨ 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.}

[coderabbitai]

🧹 Nitpick comments (1)

src/workflow-engine.test.ts (1)

594-594: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert the cancellation error fields.

This only verifies the runtime class; assert kind === "cancelled" and retryable === false so the script-visible contract is covered.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/workflow-engine.test.ts` at line 594, Extend the rejection assertion for
api.agent("x") to validate the WorkflowScriptRuntimeError fields, asserting kind
is "cancelled" and retryable is false in addition to the runtime class.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/workflow-engine.test.ts`:
- Line 594: Extend the rejection assertion for api.agent("x") to validate the
WorkflowScriptRuntimeError fields, asserting kind is "cancelled" and retryable
is false in addition to the runtime class.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 50575161-a375-4678-a74b-4c04745c4107

📥 Commits

Reviewing files that changed from the base of the PR and between 058297b and 7c65743.

📒 Files selected for processing (8)

• skills/dynamic-workflows/SKILL.md
• src/workflow-api.ts
• src/workflow-contracts.ts
• src/workflow-engine.test.ts
• src/workflow-engine.ts
• src/workflow-errors.ts
• src/workflow-tools.ts
• src/workflow-types.ts

[greptile-apps]

Nested failure kinds become internal

When a nested workflow has a parsing, metadata, script-size, or determinism failure, this catch passes the original WorkflowScriptError or WorkflowDeterminismError through a converter that does not recognize those classes and assigns kind: "internal", preventing parent scripts from branching on the established kind and recording an incorrect run failure classification.

[greptile-apps]

Greptile Summary

This PR introduces a stable script-visible runtime error contract for agent and nested-workflow failures.

• Adds WorkflowScriptRuntimeError with provider-independent kind, message, and retryable fields.
• Normalizes errors crossing from agent() and workflow() into workflow JavaScript.
• Preserves normalized failure kinds in agent-call journaling and top-level engine mapping.
• Adds fallback and failure-aware fan-out tests and documentation.

Confidence Score: 3/5

The nested-error classification defect should be fixed before merging because valid workflow failure kinds are currently exposed and recorded as internal failures.

The new catch around nested workflow execution normalizes error classes that the converter does not recognize, losing syntax, metadata, script-size, and determinism classifications that the engine otherwise preserves.

Files Needing Attention: src/workflow-api.ts

Important Files Changed

Filename	Overview
src/workflow-api.ts	Adds host-to-script error normalization, but nested script and determinism errors are incorrectly collapsed to internal.
src/workflow-errors.ts	Defines the stable script-visible runtime error class and its typed fields.
src/workflow-engine.ts	Preserves WorkflowScriptRuntimeError.kind when classifying uncaught workflow failures.
src/workflow-engine.test.ts	Covers provider fallback, retryability, journaling, nesting limits, and cancellation, but not nested parse or determinism classification.
src/workflow-contracts.ts	Adds the public TypeScript interface for script-thrown workflow errors.
skills/dynamic-workflows/SKILL.md	Documents typed error handling, fallback, fan-out retention, and resume retry behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[agent or nested workflow] --> B{Operation succeeds?}
  B -->|Yes| C[Return result]
  B -->|No| D[toWorkflowScriptRuntimeError]
  D --> E[WorkflowScriptRuntimeError]
  E --> F{Script catches error?}
  F -->|Yes| G[Fallback or retained fan-out result]
  F -->|No| H[Engine maps failure kind]

Loading

_{Reviews (1): Last reviewed commit: "docs(workflow): teach typed error handli..." | Re-trigger Greptile}