db4a39b024
Three review findings on the engine's child seam, one mechanism each: - Cancellation now bridges to run.cancel() on every in-flight child, not just the shared request signal — the subagent seam leaves a provider free to honor either channel, so the consumer drives both (listener removed in the child finally). - A child result REJECTION (an infrastructure fault the seam allows) now emits the paired workflow/agent-end before propagating, and propagates as a fatal WorkflowError with the new AGENT_RESULT code — previously it skipped agent-end (permanently open child for seq-matching observers) and dissolved to a per-item null inside parallel()/pipeline(), letting a broken provider read as an ordinary failed child. A rejection landing after cancel stays a cancellation (cancelled outcome + CANCELLED). - Every hook now guards its entry with a shared throwIfCancelled(): phase()/log() no longer emit observer events after a script caught an earlier cancelled rejection, and parallel()/pipeline() refuse entry — cancellation is the next HOOK boundary, not just the next agent().
@deepseek-ai/dsh-workflow
The workflow seam (ctx.workflows): an abstract service defining WHAT a workflow engine does — execute a model-written orchestration script that fans out subagents — without saying HOW. The bash-shaped third of the workflow family: implementations subclass WorkflowService and register as the workflows service (one per context); dsh-workflow-vm is the first, and dsh-tool-workflow is the model-facing consumer.
Service: WorkflowService (abstract)
start(request: WorkflowStartRequest): WorkflowRun — parse and execute a script. Throws synchronously (SCRIPT_PARSE/META_INVALID) for a script that cannot begin; once a run is returned, its result NEVER rejects — every failure resolves with stopReason: 'error' (or 'cancelled') — and once the run is cancelled, result settles within the implementation's bounded grace even if the script itself never settles (a consumer awaiting result must never be wedged past a cancellation). dispose() must reach quiescence within a bounded grace (cancel → wait for the script to settle and its children to finish disposing → abandon), never hanging its caller.
The protected emitWorkflowEvent helper dispatches the workflow/* events with PER-LISTENER containment and PER-LISTENER payload snapshots (a throwing subscriber is logged, never propagated, and cannot starve later listeners; each subscriber gets its own clone of the payload, so mutating it corrupts neither the engine nor other listeners) — the same containment guarantee as the subagent seam's lifecycle emits.
Vocabulary
WorkflowStartRequest—{ script, args?, parent: Agent, signal? }.parentis REQUIRED: every child the script spawns is attributed to it.argsmust be plain host-realm JSON data.WorkflowMeta/WorkflowPhase— the script's validatedexport const metablock (Claude Code format: requiredname/description, optionalwhenToUse/phases).WorkflowRun—{ id, meta, result, cancel(reason?), dispose() }; the consumer awaitsresultand MUSTdisposeon every path.WorkflowResult—{ value, stopReason: 'completed'|'cancelled'|'error', error?, agentsStarted };valueis the script's materialized return (plain JSON data;nullfor no return).WorkflowError—HarnessErrorwith aWorkflowErrorCodeand afatalflag driving the combinator discipline: a fatal error (bad hook arguments, unsupported options/schemas, tripped caps, seam start failures, cancellation) always propagates throughparallel()/pipeline()instead of dissolving into a per-itemnull.isFatalWorkflowError(error)is the catch-site predicate.
Events
All observe-only emits carrying DATA SNAPSHOTS (WorkflowRunInfo = id + meta) — never the live WorkflowRun, so a listener cannot gain cancel/dispose; control stays with the start() caller:
workflow/start(info) /workflow/end(info, resultInfo) — run lifecycle;resultInfodeliberately omits the value.workflow/phase(info, title) /workflow/log(info, message) — script narration.workflow/agent-start(info, agent) /workflow/agent-end(info, agent + outcome) — one pair peragent()call, correlated byseq.
Non-goals (this cut)
Background collection, journaling/resume, saved workflows, nested workflow(), token budgets — see the RFC's deferred section.