feat: flow engine quick wins — outputSchema, bash env, conditional retry, escape pipes

[moekatib]

Summary

Bundles five flow-engine quick wins into a single PR. Closes #59, #54, #53, #61, #58.

• [Feature Request] Step output type declarations for safer wiring #59 outputSchema — declare a step's output shape so downstream $.steps.X.output.field references are validated at flow load time. Catches typo'd field names — the most common wiring bug in complex flows.
• Structured data passing for bash steps (JSON-safe variables) #54 bash env JSON-safe injection — bash step env values now accept { json: ... } (JSON-serialized to a temp file, env var holds the path, auto-cleaned after the step) and { shell: ... } (resolved + safely word-split via bash double-quotes). Eliminates the file-write → bash workaround pattern.
• Intelligent error recovery: conditional retry + Handlebars context escaping #53 conditional retry — onError supports retryOn / failFastOn so transient errors (429, 502, ETIMEDOUT) and permanent errors (401, 403, 404) are handled differently. failFastOn takes precedence; retryOn (when set) requires a match.
• Intelligent error recovery: conditional retry + Handlebars context escaping #53 Handlebars escape pipes — {{ $.x | json|shell|url|md|html }} for context-aware escaping at the template level. Removes the need for per-call sanitization steps.
• [Feature Request] Dynamic flow dispatch — Handlebars in flow.key #61 dynamic flow.key dispatch — flow.key accepts a selector or Handlebars interpolation, so a single orchestrator can route to different sub-flows at runtime. Verified end-to-end with new tests.
• [Feature Request] Parallel step partial results on timeout #58 parallel partial results — $.steps.X.status / errorCode / durationMs / error are exposed on parallel substeps so downstream gates can branch on timeout vs failure; covered by new tests.

Stress testing

After implementation, 6 parallel sub-agents ran adversarial test suites against each new feature plus a regression sweep. They found two real bugs, both fixed in this PR:

1. validateOutputSchemas was double-reporting errors for selectors inside loop/condition/parallel substeps (walkValue recursed into nested step arrays that walkSteps also visited). Fix: skip nested-steps fields in walkValue.
2. resolveValue's routing check (value.includes('{{$.')) silently ignored the space-padded pipe form {{ $.x | json }}. Fix: routing check now uses a regex that allows optional whitespace.

Both bugs have regression tests.

Test plan

• npx tsx test-flow-features.ts — 70 tests, 69 passing (1 pre-existing While Loop failure unrelated to this change)
• npm run typecheck — only pre-existing errors in relay.ts / flow-runner.ts remain
• npm run build — clean
• 23 new unit tests covering each feature, edge cases, and the two stress-found bugs
• Manual smoke test in a downstream flow once merged

Docs

• skills/one/references/flows.md — new sections on bash structured env, conditional retry, escape pipes, dynamic flow.key, and outputSchema
• src/lib/flow-schema.ts — auto-generated guide picks up outputSchema in the common-fields table and gets new prose sections for the same features

Version

Bumped to 1.27.0 (minor — additive features, no breaking changes).

🤖 Generated with Claude Code