DSH plugin workflow: results, fatal rules, and run records
Incomplete workflow results usually mean the caller treated partial output as success, not that the script was wrong. DSH plugin's workflow seam is explicit: any result that is not completed must become an isError tool result rather than a half-reported payload. Read that discipline first, then every WorkflowResult field makes sense.
Start request: meta and args are plain data
The engine validates data and never evaluates script text to obtain arguments.(source)
WorkflowStartRequest carries script (a plain JS body, top-level await allowed, ending in return <json-value>), meta, optional args, optional subagentProvider, optional maxTotalAgents, required parent, and optional signal.
The ordinary workflow tool builds this request from the model's { script, meta, args } call plus the invoking agent. Specialized consumers may also choose an engine-level subagentProvider for a run and lower maxTotalAgents, but scripts can neither observe nor replace those policies.
meta and args are plain JSON data; the engine validates meta against a schema and rejects invalid data with an explicit error before any work begins. It never obtains them by evaluating script text.
parent is mandatory: every sub-agent a script starts belongs to it, with cwd, lineage, and depth flowing through the subagent seam. "Who spawned this sub-agent" is therefore structural, not conventional.
WorkflowMeta itself is identity and presentation only: name is a short kebab-case name used for display and persistence keys, description is one line, optional whenToUse appears in listings, and optional phases serves progress display only — phase() calls and title matching exist for observers and imply no execution structure.
The four facts of WorkflowResult
value is meaningful only under completed; the other three carry distinct information.(source)
value— the script's materialized return value, plain host-domain JSON,nullwhen the script returns nothing.stopReason— a closed union:completed,cancelled, orerror.error— failure information, present exactly whenstopReasonis notcompleted.agentsStarted— the number ofagent()calls accepted over the run's lifetime.
agentsStarted has a nuance: on graceful settlement it is the script-side count, including calls still queued for a concurrency slot; on termination paths (cancellation or process failure) it degrades to the host-observed count, since calls queued inside a terminated script are unknowable.
The mapping requirement is firm: a non-completed reason must carry failure information in error, and consumers must map it to an isError tool result rather than reporting partial output as success.
WorkflowRun: result never rejects
Cancellation and disposal are the holder's responsibility, on every path.(source)
WorkflowRun exposes id, meta (available before script execution), result, cancel(reason?), and dispose().
Three contracts:
resultnever rejects — script failure settles asstopReason: 'error'and cancellation as'cancelled';- consumers may call
cancelwhile running, and must call the idempotentdispose()on every path; - the PTC engine has no overall elapsed deadline, and cancellation immediately aborts managed processes.
dispose() awaits process and sub-agent cleanup per each provider's contract, with no separate workflow cleanup deadline. That means "it runs too long" is not solved by a workflow-layer timeout; it belongs to caller cancellation or an outer budget.
fatal discipline: misspelled options must blow up
An error with fatal: true may never be swallowed into null by a combinator.(source)
Hook misuse inside a script throws a WorkflowError with fatal: true: wrong arguments, unknown or late agent() options, schemas outside the structured-output subset, exceeded caps, seam launch failures, cancellation.
parallel() and pipeline() rethrow fatal errors instead of mapping that item to null. The reasoning is blunt: a misspelled option must fail loudly and terminate the script, never dissolving into something that looks like an ordinary sub-agent failure.
Per-item null is reserved for two cases: failed child runs (a non-completed stop reason) and ordinary script errors inside a phase. So when reading results, first decide "fatal or degradable," then decide whether to continue.
Events observe; they hand out snapshots
Subscribers receive id + meta, never a live handle.(source)
workflow/* events (start, phase, log, agent-start, agent-end, end) are observation-only emits carrying data snapshots: every payload begins with WorkflowRunInfo (id plus meta) rather than a live WorkflowRun, so subscribers cannot reach cancel or dispose.
workflow/end deliberately omits the result value — listeners observing an outcome must not receive a mutable alias of the caller's result. That prevents an observer from casually rewriting data the caller needs.
Each emit is isolated per listener: a throwing subscriber is logged without propagating, and later-registered listeners still receive their event; every listener gets its own payload clone. The isolation matches subagent/start and subagent/end.
Pairing matters too: workflow/agent-end pairs with workflow/agent-start by agent.seq, every started call produces exactly one end on every stop path, and on engine termination the end is synthesized with outcome: 'cancelled'.
Four protocols for persistent chat records
Records project display facts and never change execution ownership.(source)
The top-level dsh-tool-workflow consumer projects display facts into the invoking parent Session without changing execution ownership. Once a run is accepted it writes tool-workflow/run-start, pairs member starts and ends by runId plus seq, and writes tool-workflow/run-end only after the result is obtained and dispose fully settles. Nested transport calls write no records.
Four record protocols: exactly one start per run; member sequences positive and unique; member ends must pair; a run may not end with open members, and must not be updated after ending.
A failed first append disables all later writes for that run, so the log stays empty or a legal contiguous prefix and the tool result is unchanged. A log tail missing member ends or run end is valid interruption evidence rather than corruption — so "half a record after a crash" is not a data problem.
On the client side, dsh-client-ui-workflow-run folds the four event kinds into one workflow-run Chat node through the Conversation Node engine, anchored after the original workflow tool node by run-start sequence. Phase groups come only from members that actually started and preserve exact strings, including the difference between an absent field and an empty one; with Location off, a missing endpoint renders as interrupted.
Verification: recoverable versus fatal failure
Verify that failed child runs degrade while fatal errors terminate; they behave completely differently.(source)
- Submit a request whose
metalacksnameand assert rejection before any work begins. - Let one
agent()child run fail and assert a per-item null appears while the script continues. - Pass a misspelled option to
agent()and assert afatal: truethrow thatparallel()does not turn into null. return { ok: true }in a script and assertstopReasoniscompletedandvalueis host JSON.- Call
cancel()during a run and assertresultsettles ascancelledrather than rejecting, thendispose()waits for sub-agent cleanup. - With event listeners, make one throw and assert the others still receive cloned payloads and
workflow/endcarries no value.
If step 3 degrades to null, the combinator treated fatal as an ordinary child failure, which silences typos in production.
For workflows that never fire, see workflow not triggering; for script export and canvas handoff, see workflow YAML export.
One line to close: meta is data rather than code, result never rejects, fatal must blow up, events hand out snapshots only, and records close only after the result arrives and disposal settles.
FAQ
No. DSH plugin reserves engine-level subagentProvider and maxTotalAgents for consumers. DSH plugin scripts can neither observe nor replace those policies and must use the caller's configuration.
No. DSH plugin's result never rejects. DSH plugin settles script failure as a result with stopReason error and cancellation as cancelled, leaving consumers to map that into an isError tool result.
No. DSH plugin rethrows fatal errors directly. DSH plugin reserves per-item null for failed child runs and ordinary in-phase script errors; a misspelled option must terminate the script.
No. DSH plugin event payloads start with WorkflowRunInfo, giving subscribers only id and meta snapshots, never the live run handle, so cancel and dispose stay out of reach.
Related Terms
- WorkflowStartRequest
- WorkflowStartRequest starts one workflow run: script, meta, optional args, parent agent, and cancellation signal.— packages/workflow/workflow/src/runtime-types.ts
- WorkflowResult
- WorkflowResult is a run's terminal outcome: value, stopReason, optional error, and agentsStarted.— packages/workflow/workflow/src/runtime-types.ts
- WorkflowRun
- WorkflowRun is the owner-held live run exposing id, meta, result, cancel, and an idempotent dispose.— packages/workflow/workflow/src/runtime-types.ts
- WorkflowError.fatal
- The fatal flag on WorkflowError marks an error that must terminate the script, such as hook misuse, a misspelled option, or an exceeded cap.— DeepSeek Harness reference - Workflow
Sources
- DeepSeek Harness reference - Workflow· deepseek-ai
- packages/workflow/workflow/src/runtime-types.ts· deepseek-ai