ChatGPTClaudeGrok / X / CursorGemini

DSH plugin workflow: results, fatal rules, and run records

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessWorkflowWorkflowResultFatal errors
DSH plugin workflow: start request data boundaries, four WorkflowResult facts, non-rejecting result contracts, fatal disciplines, 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, null when the script returns nothing.
  • stopReason — a closed union: completed, cancelled, or error.
  • error — failure information, present exactly when stopReason is not completed.
  • agentsStarted — the number of agent() 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:

  1. result never rejects — script failure settles as stopReason: 'error' and cancellation as 'cancelled';
  2. consumers may call cancel while running, and must call the idempotent dispose() on every path;
  3. 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)

  1. Submit a request whose meta lacks name and assert rejection before any work begins.
  2. Let one agent() child run fail and assert a per-item null appears while the script continues.
  3. Pass a misspelled option to agent() and assert a fatal: true throw that parallel() does not turn into null.
  4. return { ok: true } in a script and assert stopReason is completed and value is host JSON.
  5. Call cancel() during a run and assert result settles as cancelled rather than rejecting, then dispose() waits for sub-agent cleanup.
  6. With event listeners, make one throw and assert the others still receive cloned payloads and workflow/end carries 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.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Can a DSH plugin script change subagentProvider?

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.

Does a throwing DSH plugin script make result reject?

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.

Does DSH plugin parallel turn fatal errors into null?

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.

Can a DSH plugin workflow event reach cancel?

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