@prettier-ai/dsh-workflow 0.1.2-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/workflow/workflow/README.md
+README.md: 80b9f1a912f9f58432d2fff1fc76615c04cd2751
+README.zh.md: e692081d99021b7ed6059af61527e551517c9eea

package/README.md

@@ -0,0 +1,143 @@
+---
+description: "The workflow orchestration capability: run a model-written script that fans out subagents, for users and maintainers choosing or building on ctx.workflowEngine."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-workflow
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-workflow` runs a plain-JavaScript orchestration script and gives the caller a live run whose result resolves with the script's final JSON value. The script can fan out subagents with `agent()`, combine independent work with `parallel()` and `pipeline()`, and narrate progress with `phase()` and `log()`; agents normally drive this through the `workflow` tool from `dsh-tool-workflow`. A run is holder-owned: its result never rejects, cancellation and disposal are bounded, and every child is attributed to the invoking agent. The package ships no execution engine — `dsh-workflow-worker-thread` is the current one — so a different isolation strategy can replace it without changing what callers or the model see.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Run a workflow when a task decomposes into many independent pieces that one script should coordinate — an audit across many files, a migration, multi-angle research — and the model explicitly asks for workflow-style orchestration. For one or two delegations, prefer a plain subagent call.
+
+### The model-facing path
+
+The model reaches the capability through the `workflow` tool from `dsh-tool-workflow`, which owns the call schema and result envelope; the engine supplies the execution underneath. A tool call submits `meta`, `script`, and optional `args` and returns `{ runId, agentsStarted, result }` when the run completes. The tool blocks the parent turn until the whole workflow settles, so the model sees one final outcome, never intermediate child messages.
+
+### Running a workflow script
+
+An orchestration script is a plain JavaScript body (not TypeScript) that runs with top-level `await` and ends with `return <json-value>`. The `meta` identity block and any `args` arrive as plain JSON data — never evaluated code. During execution the script calls the provided hooks: `agent(prompt, opts)` starts one subagent and resolves with its final text or, with a schema, a validated structured value; `parallel()` and `pipeline()` combine independent work; `phase()` and `log()` narrate progress for observers.
+
+```text
+// Script body — runs with top-level await, ends with a JSON return value:
+const reviews = await parallel([
+  () => agent('Review src/a.ts for correctness'),
+  () => agent('Review src/b.ts for correctness'),
+])
+return { reviewed: reviews.length }
+```
+
+When the script settles, the run's result resolves with the returned value, the stop reason, and the number of children started. A script that returns nothing yields `null`.
+
+### Programmatic runs
+
+Plugin consumers can start a run directly: `ctx.workflowEngine.start({ script, meta, args?, parent, signal? })`. `parent` attributes every child to the invoking agent; `signal` cancels the run when aborted. `start()` validates the meta block and parses the script before a run exists, so a malformed request fails immediately with a violation list.
+
+A returned run exposes `id`, `meta`, `result`, `cancel(reason?)`, and `dispose()`. The result never rejects: a script failure resolves with `stopReason: 'error'`, cancellation with `'cancelled'`. The caller owns the run — call `dispose()` on every path; it cancels remaining work and waits for script and children to settle within a bounded grace.
+
+### Failures and recovery
+
+A script that does not parse, a malformed meta block, an unavailable provider route, or an unsupported per-run limit is rejected synchronously before a run exists; the `workflow` tool reports these as errors the model can correct from. During execution, hook misuse — bad arguments, unknown options, unsupported schemas, tripped caps — kills the script loudly rather than dissolving into a per-item `null`. An ordinary child failure is not an infrastructure error: `agent()` resolves `null` and the script decides how to handle it.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains how the capability is split and where the contracts live; observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The package separates the script, run, result, and event contracts from execution: any engine can implement `ctx.workflowEngine` behind the same vocabulary, and one engine serves a context at a time — loading a second engine fails loud, so swapping engines means changing which engine plugin the composition loads. The `workflow/*` events are observe-only: payloads carry run identity snapshots, never the live run, so listeners cannot acquire cancellation or disposal authority.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Service definition, `workflow/*` event declarations, `WorkflowError` and its fatal flag |
+| [`src/types.ts`](src/types.ts) | Browser-safe vocabulary: `WorkflowMeta`, `WorkflowResult`, run and agent event info |
+| [`src/runtime-types.ts`](src/runtime-types.ts) | Host-only `WorkflowStartRequest` and `WorkflowRun` handles |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion: event pairing and identity checks |
+
+### Lifecycle and ownership
+
+A run is holder-owned: engine-plugin unload prevents new starts but does not revoke accepted runs, and the caller must dispose every run it starts. `dispose()` cancels if needed and awaits script and child quiescence within the engine's documented bound, so a consumer awaiting `result` is never wedged past a cancellation.
+
+`workflow/start` and `workflow/end` pair the run; `workflow/phase` and `workflow/log` carry script narration; `workflow/agent-start` and `workflow/agent-end` pair each child call by `seq`. Every listener is independently contained: a throwing listener is logged without starving peers or changing execution, and each receives its own payload clone.
+
+### Failure discipline
+
+`WorkflowError` carries a machine-routable code and a `fatal` flag; every code is fatal, and `parallel()` and `pipeline()` re-throw fatal errors instead of mapping the item to `null` — a typo'd option must kill the script loudly. Codes cover start failures, contract violations, exceeded caps, provider and result faults, unserializable values, and cancellation; the exact set and meanings live in [`src/index.ts`](src/index.ts).
+
+The per-item `null` is reserved for child-run failures and ordinary in-stage script errors, so a child that resolves normally with a non-completed stop reason is not an infrastructure exception: `agent()` returns `null`, letting the script handle an ordinary child failure.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the shared workflow model to the current engine and the model-facing consumers.
+
+- [Workflow subsystem](../../../docs/subsystems/workflow.md) — the full type vocabulary, start request, and event payloads.
+- [Group map](../README.md) — the workflow capability family and its packages.
+- [workflow tool](../tool-workflow/README.md) — the model-facing consumer that owns the call schema and result envelope.
+- [Worker-thread engine](../workflow-worker-thread/README.md) — the current execution engine and its isolation boundary.
+- [Dynamic workflows Agent Note](../../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) — the seam design and its decisions.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through its consumer `dsh-tool-workflow` and a workflow engine, which render the parent tool result and the child-agent requests.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer and engine own any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define what the capability does not yet support. They are current constraints, not a task backlog.
+
+- **Foreground collection only** — the caller owns one live run and awaits it; background start/poll, spill handles, and detached collection are deferred.
+- **No journaling or resume** — scripts, child progress, and intermediate values are not checkpointed, so a process restart cannot continue a run.
+- **No saved or nested workflows** — the capability starts caller-supplied scripts only, and a workflow script receives no `workflow()` hook for recursive orchestration.
+- **No token-budget vocabulary** — engines cap concurrency, items, and children, but neither the request nor the result accounts for model tokens across children.
+- **Runs are holder-owned, not service-tracked** — unloading the engine does not discover independent live handles; every consumer must dispose the run it started.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: open directions that are not decided. It is explicitly non-authoritative — shipped behavior, limits, and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
+
+Deferred directions: a background start/poll API with spill handles and detached collection; saved and nested workflows; a token-budget vocabulary across children; and the seam's promise that a future process or sandbox engine can replace the worker-thread engine without changing the model-facing surface.
+
+</details>

package/README.zh.md

@@ -0,0 +1,143 @@
+---
+description: "工作流编排能力：运行由模型编写的、扇出 subagent 的脚本，供选择或构建在 ctx.workflowEngine 之上的用户与维护者阅读。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-workflow
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-workflow` 运行一段纯 JavaScript 编排脚本，并交给调用方一个活动运行，其 result 在脚本结算时以脚本的最终 JSON 值兑现。脚本可以用 `agent()` 扇出 subagent，用 `parallel()` 和 `pipeline()` 组合独立工作，用 `phase()` 和 `log()` 叙述进度；agent 通常通过 `dsh-tool-workflow` 的 `workflow` 工具驱动这一切。运行由持有方负责：其 result 绝不拒绝，取消与 dispose（资源释放）有界，每个子 agent 都归属于调用它的 agent。本包不附带执行引擎——当前引擎是 `dsh-workflow-worker-thread`——因此可以用不同的隔离策略替换它，而不改变调用方或模型看到的内容。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当任务分解为许多独立部分、适合用一段脚本统一协调——例如跨多个文件的审计、一次迁移、多角度研究——且模型明确要求工作流式编排时，运行工作流。一两项委派时，优先使用普通 subagent 调用。
+
+### 模型侧路径
+
+模型通过 `dsh-tool-workflow` 的 `workflow` 工具触达该能力；该工具拥有调用 schema 与结果包络，引擎提供其下的执行。一次工具调用提交 `meta`、`script` 与可选 `args`，运行完成时返回 `{ runId, agentsStarted, result }`。工具会阻塞父级轮次直到整个工作流结算，因此模型只看到最终结果，永远不会看到中间子 agent 消息。
+
+### 运行工作流脚本
+
+编排脚本是纯 JavaScript 脚本体（不是 TypeScript），以顶层 `await` 运行并以 `return <json-value>` 结尾。`meta` 身份块与任何 `args` 都以普通 JSON 数据到达——绝不作为代码求值。执行期间脚本调用提供的钩子：`agent(prompt, opts)` 启动一个 subagent，并以其最终文本、或在提供 schema 时以经过校验的结构化值兑现；`parallel()` 与 `pipeline()` 组合独立工作；`phase()` 与 `log()` 为观察者叙述进度。
+
+```text
+// Script body — runs with top-level await, ends with a JSON return value:
+const reviews = await parallel([
+  () => agent('Review src/a.ts for correctness'),
+  () => agent('Review src/b.ts for correctness'),
+])
+return { reviewed: reviews.length }
+```
+
+脚本结算时，运行的 result 以返回值、结束原因和已启动的子 agent 数量兑现。脚本不返回值时得到 `null`。
+
+### 编程方式运行
+
+插件消费方可以直接启动运行：`ctx.workflowEngine.start({ script, meta, args?, parent, signal? })`。`parent` 把每个子 agent 归属于调用它的 agent；`signal` 在中止时取消运行。`start()` 在运行存在之前校验 meta 块并解析脚本，因此格式错误的请求会立即以违规清单失败。
+
+返回的运行公开 `id`、`meta`、`result`、`cancel(reason?)` 与 `dispose()`。result 绝不拒绝：脚本失败以 `stopReason: 'error'` 兑现，取消以 `'cancelled'` 兑现。调用方拥有该运行——每条路径都要调用 `dispose()`；它会取消剩余工作，并在有界宽限期内等待脚本与子 agent 完全停稳。
+
+### 失败与恢复
+
+无法解析的脚本、格式错误的 meta 块、不可用的提供方路由或不受支持的单次运行限制，都会在运行存在之前被同步拒绝；`workflow` 工具把这些报告为模型可以修正的错误。执行期间，钩子误用——错误参数、未知选项、不支持的 schema、超出上限——会响亮地终止脚本，而不会溶解为逐项 `null`。普通子 agent 失败不是基础设施错误：`agent()` 以 `null` 兑现，由脚本决定如何处理。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释能力如何拆分、契约位于何处；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+本包把脚本、运行、结果与事件契约同执行分开：任何引擎都可以在同一词汇背后实现 `ctx.workflowEngine`，一个上下文同时只有一个引擎——加载第二个引擎会立即失败，因此更换引擎意味着更改组合所加载的引擎插件。`workflow/*` 事件只供观察：payload 携带运行身份快照，绝不携带活动运行，因此监听器无法取得取消或 dispose 权限。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 服务定义、`workflow/*` 事件声明、`WorkflowError` 及其 fatal 标志 |
+| [`src/types.ts`](src/types.ts) | 浏览器安全词汇：`WorkflowMeta`、`WorkflowResult`、运行与 agent 事件信息 |
+| [`src/runtime-types.ts`](src/runtime-types.ts) | 仅宿主的 `WorkflowStartRequest` 与 `WorkflowRun` 句柄 |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件：事件配对与身份校验 |
+
+### 生命周期与归属
+
+运行由持有方负责：引擎插件卸载会阻止新的启动，但不会撤销已接受的运行，调用方必须 dispose 自己启动的每个运行。`dispose()` 在需要时取消，并在引擎文档规定的期限内等待脚本与子 agent 完全停稳，因此等待 `result` 的消费方绝不会因取消而卡死。
+
+`workflow/start` 与 `workflow/end` 为运行配对；`workflow/phase` 与 `workflow/log` 携带脚本叙述；`workflow/agent-start` 与 `workflow/agent-end` 按 `seq` 为每次子 agent 调用配对。每个监听器都独立隔离：抛错的监听器只记录日志，不会饿死同级监听器或改变执行，并且每个监听器都会收到自己的 payload 副本。
+
+### 失败纪律
+
+`WorkflowError` 携带机器可路由的 code 与 `fatal` 标志；每个 code 都是致命的，`parallel()` 与 `pipeline()` 会重新抛出致命错误，而不是把条目映射为 `null`——拼错的选项必须响亮地终止脚本。code 覆盖启动失败、契约违规、超出上限、提供方与结果故障、不可序列化值与取消；完整集合与含义见 [`src/index.ts`](src/index.ts)。
+
+逐项 `null` 只保留给子运行失败与阶段内普通脚本错误，因此以非完成结束原因正常结算的子 agent 不属于基础设施异常：`agent()` 返回 `null`，让脚本处理普通子 agent 失败。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级契约不够用时阅读以下页面。它们从共享工作流模型逐步进入当前引擎与面向模型的消费方。
+
+- [工作流子系统](../../../docs/subsystems/workflow.zh.md)——完整类型词汇、启动请求与事件载荷。
+- [组地图](../README.zh.md)——工作流能力家族及其包。
+- [workflow 工具](../tool-workflow/README.zh.md)——拥有调用 schema 与结果包络的模型侧消费方。
+- [worker-thread 引擎](../workflow-worker-thread/README.zh.md)——当前执行引擎及其隔离边界。
+- [动态工作流 Agent Note](../../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md)——seam 设计及其决策。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+间接地，通过其消费方 `dsh-tool-workflow` 与一个工作流引擎，由它们渲染父级工具结果与子 agent 请求。
+
+#### KV Cache 影响
+
+不会直接导致失效；请求前缀的任何变化均由上述消费方与引擎负责。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明该能力尚未支持什么。它们是当前约束，不是任务积压。
+
+- **仅支持前台收集**——调用方拥有一个活动运行并等待它；后台启动／轮询、spill 句柄与分离收集均暂缓。
+- **没有日志化或恢复**——脚本、子 agent 进度与中间值均不设检查点，因此进程重启后无法继续运行。
+- **没有已保存或嵌套工作流**——该能力只启动调用方提供的脚本，工作流脚本不会收到用于递归编排的 `workflow()` 钩子。
+- **没有 token 预算词汇**——引擎限制并发、条目与子 agent，但请求与结果都不会统计跨子 agent 的模型 token。
+- **运行由持有方负责，不由服务跟踪**——卸载引擎不会发现独立的活动句柄；每个消费方都必须 dispose 自己启动的运行。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：尚未决定的开放方向。它明确不具权威性——已交付的行为、限制与既定理由以上文、包代码与相关 Agent Note 为准。
+
+暂缓的方向：带 spill 句柄与分离收集的后台启动／轮询 API；已保存与嵌套工作流；跨子 agent 的 token 预算词汇；以及该 seam 的承诺——未来的进程或沙箱引擎可以在不改变模型侧表面的前提下替换 worker-thread 引擎。
+
+</details>

package/lib/index.js

@@ -0,0 +1,92 @@
+import { Service } from "@prettier-ai/cordis";
+import { HarnessError } from "@prettier-ai/dsh-llm";
+//#region lib/types/types.js
+/**
+* Workflow seam vocabulary: the request/run/result types a workflow engine
+* consumes and produces, plus the fields in the `workflow/*` event payloads.
+* Types only (plus the id-brand factory), per the package convention.
+*
+* @module @prettier-ai/dsh-workflow/types
+*/
+/**
+* Brand a string as a {@link WorkflowRunId}.
+* @param id - the raw id string (the engine mints UUIDs; tests may pass fixtures).
+* @returns the same string, branded.
+*/
+function WorkflowRunId(id) {
+	return id;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Service Definition for the workflow capability seam. Service Providers execute orchestration scripts;
+* observe-only lifecycle events never expose run control.
+* @module @prettier-ai/dsh-workflow
+*/
+/**
+* Typed error for workflow-seam failures. Extends {@link HarnessError}, so the
+* `code` is machine-routable taxonomy. `fatal` drives the combinator
+* discipline: `parallel()`/`pipeline()` re-throw a fatal error (a typo'd
+* option or a tripped cap must kill the script loudly), and reserve the
+* per-item `null` for child-run failures and ordinary in-stage script errors.
+* Every {@link WorkflowErrorCode} is fatal; the flag exists so the
+* distinction is explicit at every catch site rather than implied.
+*/
+var WorkflowError = class extends HarnessError {
+	/** Whether combinators must propagate this error instead of nulling the item. */
+	fatal;
+	constructor(message, code, options) {
+		super(message, code, options);
+		this.name = "WorkflowError";
+		this.fatal = options?.fatal ?? true;
+	}
+};
+/**
+* Whether combinators must re-throw `error` instead of mapping the item to `null`.
+* @param error - any thrown value; fatality is host `instanceof` (unforgeable from a script realm).
+* @returns true iff `error` is a {@link WorkflowError} whose `fatal` flag is set.
+*/
+function isFatalWorkflowError(error) {
+	return error instanceof WorkflowError && error.fatal;
+}
+/**
+* Workflow Service Definition contract. Invalid requests throw before publication; a live
+* run is holder-owned, its result never rejects, cancellation and disposal are
+* bounded, and disposal waits for child cleanup within that bound. Lifecycle
+* listener failures are contained, and `workflow/end` fires exactly once as the
+* result settles.
+*/
+var WorkflowEngine = class extends Service {
+	constructor(ctx) {
+		super(ctx, "workflowEngine");
+	}
+	/**
+	* Emit a lifecycle event while containing and logging each listener failure.
+	* @param name - the `workflow/*` event to dispatch.
+	* @param args - the event's payload, matching its declared signature.
+	*/
+	emitWorkflowEvent(name, ...args) {
+		for (const callback of this.ctx.events.dispatch("emit", [name, ...args])) try {
+			const returned = callback(...args);
+			Promise.resolve(returned).catch((error) => {
+				this.ctx.logger.warn(`workflow: ${name} listener rejected: ${renderListenerError(error)}`);
+			});
+		} catch (error) {
+			this.ctx.logger.warn(`workflow: ${name} listener threw: ${renderListenerError(error)}`);
+		}
+	}
+};
+/**
+* Render any thrown value without violating listener containment.
+* @param error - any thrown value.
+* @returns `String(error)`, or a fixed label when even coercion throws.
+*/
+function renderListenerError(error) {
+	try {
+		return String(error);
+	} catch {
+		return "[unrenderable thrown value]";
+	}
+}
+//#endregion
+export { WorkflowEngine, WorkflowEngine as default, WorkflowError, WorkflowRunId, isFatalWorkflowError };

package/lib/invariant.js

@@ -0,0 +1,100 @@
+//#region lib/types/invariant.js
+/** Package-owned workflow lifecycle invariants. @module @prettier-ai/dsh-workflow/invariant */
+const PACKAGE_NAME = "@prettier-ai/dsh-workflow";
+/** Cordis companion plugin name. */
+const name = "workflow-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** Require every event for a run to retain its validated identity snapshot. */
+function traceFor(traces, info, fail) {
+	const trace = traces.get(info.id);
+	if (trace === void 0) fail(`workflow event has no matching workflow/start for run ${JSON.stringify(info.id)}`);
+	if (trace.meta !== JSON.stringify(info.meta)) fail(`workflow event meta diverges from workflow/start for run ${JSON.stringify(info.id)}`);
+	return trace;
+}
+/** Assert the immutable identity fields shared by an agent pair. */
+function validateAgentEnd(start, end, fail) {
+	if (start.label !== end.label || start.phase !== end.phase || start.childId !== end.childId) fail(`workflow/agent-end identity diverges from workflow/agent-start for seq ${end.seq}`);
+	const outcome = end.outcome;
+	if (outcome !== "completed" && outcome !== "failed" && outcome !== "cancelled") fail(`workflow/agent-end carries unknown outcome ${JSON.stringify(outcome)}`);
+}
+/** Validate a terminal result against the accumulated run trace. */
+function validateWorkflowEnd(trace, result, fail) {
+	if (trace.agents.size > 0) fail(`workflow/end has ${trace.agents.size} agent call(s) without workflow/agent-end`);
+	if (!Number.isSafeInteger(result.agentsStarted) || result.agentsStarted < trace.starts) fail("workflow/end agentsStarted must be a safe integer covering every observed agent start");
+	if (result.stopReason === "completed" ? result.error !== void 0 : typeof result.error !== "string") fail("workflow/end error must be absent exactly for completed runs");
+}
+/** Install workflow start/end and child-call pairing checks. */
+const install = (ctx, fail) => {
+	const traces = /* @__PURE__ */ new Map();
+	const stagedStarts = /* @__PURE__ */ new WeakSet();
+	const stagedAgentStarts = /* @__PURE__ */ new WeakSet();
+	const stagedAgentEnds = /* @__PURE__ */ new WeakSet();
+	const stagedEnds = /* @__PURE__ */ new WeakSet();
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName === "workflow/start") {
+			const info = args[0];
+			if (String(info.id).length === 0 || info.meta.name.length === 0 || info.meta.description.length === 0) fail("workflow/start id, meta.name, and meta.description must be non-empty");
+			if (traces.has(info.id)) fail(`workflow/start repeated run id ${JSON.stringify(info.id)}`);
+			stagedStarts.add(info);
+			return;
+		}
+		if (!eventName.startsWith("workflow/")) return;
+		const info = args[0];
+		const trace = traceFor(traces, info, fail);
+		if (eventName === "workflow/agent-start") {
+			const agent = args[1];
+			if (!Number.isSafeInteger(agent.seq) || agent.seq < 1 || String(agent.childId).length === 0) fail("workflow/agent-start seq must be positive and childId must be non-empty");
+			if (trace.agents.has(agent.seq)) fail(`workflow/agent-start repeated seq ${agent.seq}`);
+			stagedAgentStarts.add(agent);
+			return;
+		}
+		if (eventName === "workflow/agent-end") {
+			const agent = args[1];
+			const start = trace.agents.get(agent.seq);
+			if (start === void 0) return fail(`workflow/agent-end has no matching start for seq ${agent.seq}`);
+			validateAgentEnd(start, agent, fail);
+			stagedAgentEnds.add(agent);
+			return;
+		}
+		if (eventName === "workflow/end") {
+			const result = args[1];
+			validateWorkflowEnd(trace, result, fail);
+			stagedEnds.add(result);
+		}
+	}, { global: true });
+	ctx.on("workflow/start", (info) => {
+		/* v8 ignore next -- internal/dispatch stages the same run-info object */
+		if (!stagedStarts.delete(info)) return;
+		traces.set(info.id, {
+			meta: JSON.stringify(info.meta),
+			agents: /* @__PURE__ */ new Map(),
+			starts: 0
+		});
+	}, { global: true });
+	ctx.on("workflow/agent-start", (info, agent) => {
+		/* v8 ignore next -- internal/dispatch stages the same agent object */
+		if (!stagedAgentStarts.delete(agent)) return;
+		const trace = traceFor(traces, info, fail);
+		trace.agents.set(agent.seq, agent);
+		trace.starts += 1;
+	}, { global: true });
+	ctx.on("workflow/agent-end", (info, agent) => {
+		/* v8 ignore next -- internal/dispatch stages the same agent object */
+		if (!stagedAgentEnds.delete(agent)) return;
+		traceFor(traces, info, fail).agents.delete(agent.seq);
+	}, { global: true });
+	ctx.on("workflow/end", (info, result) => {
+		/* v8 ignore next -- internal/dispatch stages the same result object */
+		if (!stagedEnds.delete(result)) return;
+		traces.delete(info.id);
+	}, { global: true });
+};
+/**
+* Register the workflow invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Service Definition for the workflow capability seam. Service Providers execute orchestration scripts;
+ * observe-only lifecycle events never expose run control.
+ * @module @prettier-ai/dsh-workflow
+ */
+import { Context, Service } from '@prettier-ai/cordis';
+import { HarnessError } from '@prettier-ai/dsh-llm';
+import type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowResultInfo, WorkflowRunInfo } from './types.ts';
+import type { WorkflowRun, WorkflowStartRequest } from './runtime-types.ts';
+export { WorkflowRunId } from './types.ts';
+export type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowAgentOutcome, WorkflowMeta, WorkflowPhase, WorkflowResult, WorkflowResultInfo, WorkflowRunInfo, WorkflowStopReason, } from './types.ts';
+export type { WorkflowRun, WorkflowStartRequest } from './runtime-types.ts';
+declare module '@prettier-ai/cordis' {
+    interface Context {
+        workflowEngine: WorkflowEngine;
+    }
+    interface Events {
+        /**
+         * A workflow run started — the script's meta block validated, the body
+         * about to execute. Paired with {@link Events['workflow/end']}.
+         * @param info - the run's identity snapshot (id + meta).
+         * @mode emit
+         */
+        'workflow/start'(info: WorkflowRunInfo): void;
+        /**
+         * The script entered a phase (a `phase(title)` call) — progress grouping
+         * for observers; no execution semantics.
+         * @param info - the run's identity snapshot.
+         * @param title - the phase title, verbatim.
+         * @mode emit
+         */
+        'workflow/phase'(info: WorkflowRunInfo, title: string): void;
+        /**
+         * The script emitted a narration line (a `log(message)` call).
+         * @param info - the run's identity snapshot.
+         * @param message - the logged message, verbatim.
+         * @mode emit
+         */
+        'workflow/log'(info: WorkflowRunInfo, message: string): void;
+        /**
+         * One `agent()` call established a published child run. Paired with
+         * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
+         * receives a published run from the provider emits neither
+         * event in this pair.
+         * @param info - the run's identity snapshot.
+         * @param agent - the call's sequence number, label, phase, and child id.
+         * @mode emit
+         */
+        'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void;
+        /**
+         * One `agent()` call settled (clean result, child failure, or run
+         * cancellation). Paired with {@link Events['workflow/agent-start']} by
+         * `agent.seq`, exactly once per started call on every stop path — on an
+         * engine termination path (a worker killed past its grace) the end is
+         * engine-synthesized with outcome `'cancelled'`.
+         * @param info - the run's identity snapshot.
+         * @param agent - the call identity plus its outcome.
+         * @mode emit
+         */
+        'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void;
+        /**
+         * A workflow run settled (any stop reason). Fired when
+         * {@link WorkflowRun.result} resolves. Paired with
+         * {@link Events['workflow/start']}.
+         * @param info - the run's identity snapshot.
+         * @param result - the outcome data (stop reason, error, agent count) —
+         *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
+         * @mode emit
+         */
+        'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void;
+    }
+}
+/** The full set of `workflow/*` event names {@link WorkflowEngine.emitWorkflowEvent} dispatches. */
+export type WorkflowEventName = 'workflow/start' | 'workflow/phase' | 'workflow/log' | 'workflow/agent-start' | 'workflow/agent-end' | 'workflow/end';
+/**
+ * Machine-routable fatal workflow failures: parse/meta/argument/schema errors,
+ * resource caps, subagent infrastructure failures, unserializable boundary
+ * values, and cancellation. An ordinary child failure resolves its item to
+ * `null` and is not one of these fatal codes.
+ */
+export type WorkflowErrorCode = 'SCRIPT_PARSE' | 'META_INVALID' | 'INVALID_ARGUMENT' | 'UNSUPPORTED_OPTION' | 'UNSUPPORTED_SCHEMA' | 'AGENT_CAP' | 'ITEM_CAP' | 'AGENT_START' | 'AGENT_RESULT' | 'RESULT_UNSERIALIZABLE' | 'CANCELLED';
+/**
+ * Typed error for workflow-seam failures. Extends {@link HarnessError}, so the
+ * `code` is machine-routable taxonomy. `fatal` drives the combinator
+ * discipline: `parallel()`/`pipeline()` re-throw a fatal error (a typo'd
+ * option or a tripped cap must kill the script loudly), and reserve the
+ * per-item `null` for child-run failures and ordinary in-stage script errors.
+ * Every {@link WorkflowErrorCode} is fatal; the flag exists so the
+ * distinction is explicit at every catch site rather than implied.
+ */
+export declare class WorkflowError extends HarnessError {
+    /** Whether combinators must propagate this error instead of nulling the item. */
+    readonly fatal: boolean;
+    constructor(message: string, code: WorkflowErrorCode, options?: ErrorOptions & {
+        fatal?: boolean;
+    });
+}
+/**
+ * Whether combinators must re-throw `error` instead of mapping the item to `null`.
+ * @param error - any thrown value; fatality is host `instanceof` (unforgeable from a script realm).
+ * @returns true iff `error` is a {@link WorkflowError} whose `fatal` flag is set.
+ */
+export declare function isFatalWorkflowError(error: unknown): boolean;
+/**
+ * Workflow Service Definition contract. Invalid requests throw before publication; a live
+ * run is holder-owned, its result never rejects, cancellation and disposal are
+ * bounded, and disposal waits for child cleanup within that bound. Lifecycle
+ * listener failures are contained, and `workflow/end` fires exactly once as the
+ * result settles.
+ */
+export declare abstract class WorkflowEngine extends Service {
+    constructor(ctx: Context);
+    /**
+     * Parse and execute a workflow script.
+     * @param request - the script, its `args`, the parent agent, and an
+     *   optional cancel signal.
+     * @returns the live run; its `result` resolves when the script settles.
+     */
+    abstract start(request: WorkflowStartRequest): WorkflowRun;
+    /**
+     * Emit a lifecycle event while containing and logging each listener failure.
+     * @param name - the `workflow/*` event to dispatch.
+     * @param args - the event's payload, matching its declared signature.
+     */
+    protected emitWorkflowEvent(name: WorkflowEventName, ...args: unknown[]): void;
+}
+export default WorkflowEngine;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,80 @@
+/**
+ * Service Definition for the workflow capability seam. Service Providers execute orchestration scripts;
+ * observe-only lifecycle events never expose run control.
+ * @module @prettier-ai/dsh-workflow
+ */
+import { Service } from '@prettier-ai/cordis';
+import { HarnessError } from '@prettier-ai/dsh-llm';
+export { WorkflowRunId } from "./types.js";
+/**
+ * Typed error for workflow-seam failures. Extends {@link HarnessError}, so the
+ * `code` is machine-routable taxonomy. `fatal` drives the combinator
+ * discipline: `parallel()`/`pipeline()` re-throw a fatal error (a typo'd
+ * option or a tripped cap must kill the script loudly), and reserve the
+ * per-item `null` for child-run failures and ordinary in-stage script errors.
+ * Every {@link WorkflowErrorCode} is fatal; the flag exists so the
+ * distinction is explicit at every catch site rather than implied.
+ */
+export class WorkflowError extends HarnessError {
+    /** Whether combinators must propagate this error instead of nulling the item. */
+    fatal;
+    constructor(message, code, options) {
+        super(message, code, options);
+        this.name = 'WorkflowError';
+        this.fatal = options?.fatal ?? true;
+    }
+}
+/**
+ * Whether combinators must re-throw `error` instead of mapping the item to `null`.
+ * @param error - any thrown value; fatality is host `instanceof` (unforgeable from a script realm).
+ * @returns true iff `error` is a {@link WorkflowError} whose `fatal` flag is set.
+ */
+export function isFatalWorkflowError(error) {
+    return error instanceof WorkflowError && error.fatal;
+}
+/**
+ * Workflow Service Definition contract. Invalid requests throw before publication; a live
+ * run is holder-owned, its result never rejects, cancellation and disposal are
+ * bounded, and disposal waits for child cleanup within that bound. Lifecycle
+ * listener failures are contained, and `workflow/end` fires exactly once as the
+ * result settles.
+ */
+export class WorkflowEngine extends Service {
+    constructor(ctx) {
+        super(ctx, 'workflowEngine');
+    }
+    /**
+     * Emit a lifecycle event while containing and logging each listener failure.
+     * @param name - the `workflow/*` event to dispatch.
+     * @param args - the event's payload, matching its declared signature.
+     */
+    emitWorkflowEvent(name, ...args) {
+        for (const callback of this.ctx.events.dispatch('emit', [name, ...args])) {
+            try {
+                const returned = callback(...args);
+                void Promise.resolve(returned).catch((error) => {
+                    this.ctx.logger.warn(`workflow: ${name} listener rejected: ${renderListenerError(error)}`);
+                });
+            }
+            catch (error) {
+                this.ctx.logger.warn(`workflow: ${name} listener threw: ${renderListenerError(error)}`);
+            }
+        }
+    }
+}
+/**
+ * Render any thrown value without violating listener containment.
+ * @param error - any thrown value.
+ * @returns `String(error)`, or a fixed label when even coercion throws.
+ */
+function renderListenerError(error) {
+    try {
+        return String(error);
+    }
+    catch {
+        // String coercion itself may throw.
+        return '[unrenderable thrown value]';
+    }
+}
+export default WorkflowEngine;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned workflow lifecycle invariants. @module @prettier-ai/dsh-workflow/invariant */
+import type { Context } from '@prettier-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "workflow-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the workflow invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,118 @@
+/** Package-owned workflow lifecycle invariants. @module @prettier-ai/dsh-workflow/invariant */
+const PACKAGE_NAME = '@prettier-ai/dsh-workflow';
+/** Cordis companion plugin name. */
+export const name = 'workflow-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/** Require every event for a run to retain its validated identity snapshot. */
+function traceFor(traces, info, fail) {
+    const trace = traces.get(info.id);
+    if (trace === undefined)
+        fail(`workflow event has no matching workflow/start for run ${JSON.stringify(info.id)}`);
+    if (trace.meta !== JSON.stringify(info.meta)) {
+        fail(`workflow event meta diverges from workflow/start for run ${JSON.stringify(info.id)}`);
+    }
+    return trace;
+}
+/** Assert the immutable identity fields shared by an agent pair. */
+function validateAgentEnd(start, end, fail) {
+    if (start.label !== end.label || start.phase !== end.phase || start.childId !== end.childId) {
+        fail(`workflow/agent-end identity diverges from workflow/agent-start for seq ${end.seq}`);
+    }
+    const outcome = end.outcome;
+    if (outcome !== 'completed' && outcome !== 'failed' && outcome !== 'cancelled') {
+        fail(`workflow/agent-end carries unknown outcome ${JSON.stringify(outcome)}`);
+    }
+}
+/** Validate a terminal result against the accumulated run trace. */
+function validateWorkflowEnd(trace, result, fail) {
+    if (trace.agents.size > 0)
+        fail(`workflow/end has ${trace.agents.size} agent call(s) without workflow/agent-end`);
+    if (!Number.isSafeInteger(result.agentsStarted) || result.agentsStarted < trace.starts) {
+        fail('workflow/end agentsStarted must be a safe integer covering every observed agent start');
+    }
+    if (result.stopReason === 'completed' ? result.error !== undefined : typeof result.error !== 'string') {
+        fail('workflow/end error must be absent exactly for completed runs');
+    }
+}
+/** Install workflow start/end and child-call pairing checks. */
+const install = (ctx, fail) => {
+    const traces = new Map();
+    const stagedStarts = new WeakSet();
+    const stagedAgentStarts = new WeakSet();
+    const stagedAgentEnds = new WeakSet();
+    const stagedEnds = new WeakSet();
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName === 'workflow/start') {
+            const info = args[0];
+            if (String(info.id).length === 0 || info.meta.name.length === 0 || info.meta.description.length === 0) {
+                fail('workflow/start id, meta.name, and meta.description must be non-empty');
+            }
+            if (traces.has(info.id))
+                fail(`workflow/start repeated run id ${JSON.stringify(info.id)}`);
+            stagedStarts.add(info);
+            return;
+        }
+        if (!eventName.startsWith('workflow/'))
+            return;
+        const info = args[0];
+        const trace = traceFor(traces, info, fail);
+        if (eventName === 'workflow/agent-start') {
+            const agent = args[1];
+            if (!Number.isSafeInteger(agent.seq) || agent.seq < 1 || String(agent.childId).length === 0) {
+                fail('workflow/agent-start seq must be positive and childId must be non-empty');
+            }
+            if (trace.agents.has(agent.seq))
+                fail(`workflow/agent-start repeated seq ${agent.seq}`);
+            stagedAgentStarts.add(agent);
+            return;
+        }
+        if (eventName === 'workflow/agent-end') {
+            const agent = args[1];
+            const start = trace.agents.get(agent.seq);
+            if (start === undefined)
+                return fail(`workflow/agent-end has no matching start for seq ${agent.seq}`);
+            validateAgentEnd(start, agent, fail);
+            stagedAgentEnds.add(agent);
+            return;
+        }
+        if (eventName === 'workflow/end') {
+            const result = args[1];
+            validateWorkflowEnd(trace, result, fail);
+            stagedEnds.add(result);
+        }
+    }, { global: true });
+    ctx.on('workflow/start', (info) => {
+        /* v8 ignore next -- internal/dispatch stages the same run-info object */
+        if (!stagedStarts.delete(info))
+            return;
+        traces.set(info.id, { meta: JSON.stringify(info.meta), agents: new Map(), starts: 0 });
+    }, { global: true });
+    ctx.on('workflow/agent-start', (info, agent) => {
+        /* v8 ignore next -- internal/dispatch stages the same agent object */
+        if (!stagedAgentStarts.delete(agent))
+            return;
+        const trace = traceFor(traces, info, fail);
+        trace.agents.set(agent.seq, agent);
+        trace.starts += 1;
+    }, { global: true });
+    ctx.on('workflow/agent-end', (info, agent) => {
+        /* v8 ignore next -- internal/dispatch stages the same agent object */
+        if (!stagedAgentEnds.delete(agent))
+            return;
+        traceFor(traces, info, fail).agents.delete(agent.seq);
+    }, { global: true });
+    ctx.on('workflow/end', (info, result) => {
+        /* v8 ignore next -- internal/dispatch stages the same result object */
+        if (!stagedEnds.delete(result))
+            return;
+        traces.delete(info.id);
+    }, { global: true });
+};
+/**
+ * Register the workflow invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/runtime-types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Host-only workflow request and live-run handles. The browser-safe durable
+ * vocabulary remains in `./types` so Client programs never import Agent or
+ * host Cordis context declarations.
+ *
+ * @module @prettier-ai/dsh-workflow
+ */
+import type { Agent } from '@prettier-ai/dsh-agent';
+import type { WorkflowMeta, WorkflowResult, WorkflowRunId } from './types.ts';
+/**
+ * What a caller asks for when starting a workflow run. `meta` and `args` are
+ * plain JSON data by the seam contract. `parent` is required because every
+ * `agent()` spawned by the script is attributed to that live Agent.
+ */
+export interface WorkflowStartRequest {
+    /** The plain-JS script body (top-level await allowed; ends with `return <json-value>`). */
+    script: string;
+    /** The workflow's identity block, as plain JSON data (shape-validated by the engine). */
+    meta: WorkflowMeta;
+    /** Optional input exposed verbatim to the script as the `args` global. */
+    args?: unknown;
+    /** Optional engine-wide child-provider override for this run. */
+    subagentProvider?: string;
+    /** Optional per-run total-child ceiling. */
+    maxTotalAgents?: number;
+    /** The agent on whose behalf the run executes (parent of every child). */
+    parent: Agent;
+    /** Cancels the run when aborted. */
+    signal?: AbortSignal;
+}
+/**
+ * Holder-owned live workflow. `result` never rejects; consumers may cancel
+ * and must call idempotent `dispose()` to await script and child quiescence.
+ */
+export interface WorkflowRun {
+    readonly id: WorkflowRunId;
+    /** The validated meta block available before the script body runs. */
+    readonly meta: WorkflowMeta;
+    readonly result: Promise<WorkflowResult>;
+    /** Cancel the run and its children. */
+    cancel(reason?: string): void;
+    /** Cancel if needed and await bounded settlement and cleanup. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=runtime-types.d.ts.map

package/lib/types/runtime-types.js

@@ -0,0 +1,9 @@
+/**
+ * Host-only workflow request and live-run handles. The browser-safe durable
+ * vocabulary remains in `./types` so Client programs never import Agent or
+ * host Cordis context declarations.
+ *
+ * @module @prettier-ai/dsh-workflow
+ */
+export {};
+//# sourceMappingURL=runtime-types.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Workflow seam vocabulary: the request/run/result types a workflow engine
+ * consumes and produces, plus the fields in the `workflow/*` event payloads.
+ * Types only (plus the id-brand factory), per the package convention.
+ *
+ * @module @prettier-ai/dsh-workflow/types
+ */
+import type { Branded } from '@prettier-ai/dsh-brand';
+import type { SessionId } from '@prettier-ai/dsh-session/types';
+/** Identifies one workflow run. */
+export type WorkflowRunId = Branded<'WorkflowRunId'>;
+/**
+ * Brand a string as a {@link WorkflowRunId}.
+ * @param id - the raw id string (the engine mints UUIDs; tests may pass fixtures).
+ * @returns the same string, branded.
+ */
+export declare function WorkflowRunId(id: string): WorkflowRunId;
+/**
+ * One phase declared in a script's `meta.phases` (progress vocabulary only —
+ * phases group agents in observers/UIs; they impose no execution structure).
+ */
+export interface WorkflowPhase {
+    /** The phase title; `phase()` calls match against it by exact string. */
+    title: string;
+    /** Optional one-line description of what the phase does. */
+    detail?: string;
+    /** Optional provider override this phase is expected to use (informational). */
+    provider?: string;
+    /** Optional model override this phase is expected to use (informational). */
+    model?: string;
+}
+/**
+ * The script's identity block, provided as plain JSON data alongside the
+ * script body (the model-facing tool carries it as its `meta` parameter) and
+ * validated by the engine before the body runs. `name`/`description` are
+ * required; the rest is optional annotation. The field vocabulary matches the
+ * Claude Code dynamic-workflows meta block.
+ */
+export interface WorkflowMeta {
+    /** Short kebab-case workflow name (display + persistence key). */
+    name: string;
+    /** One-line description of what the workflow does. */
+    description: string;
+    /** Optional guidance on when this workflow applies (shown in listings). */
+    whenToUse?: string;
+    /** Optional phase declarations matched by `phase()` calls. */
+    phases?: WorkflowPhase[];
+}
+/**
+ * Why a run settled. CLOSED union (engine-owned, consumers may exhaust):
+ * `completed` = the script ran to its final `return`; `cancelled` = the run
+ * was cancelled (caller `cancel()`/signal); `error` = the script threw, a
+ * fatal `WorkflowError` propagated, or the result failed materialization.
+ */
+export type WorkflowStopReason = 'completed' | 'cancelled' | 'error';
+/**
+ * The outcome resolved by a live workflow run. `value` is
+ * the script's materialized return value (plain host-realm JSON data; `null`
+ * when the script returned `undefined`) — meaningful only for `completed`.
+ * A non-`completed` reason carries the failure in `error`; the consumer maps
+ * it to an `isError` tool result rather than reporting partial output.
+ */
+export interface WorkflowResult {
+    /** The script's return value (host JSON data; `null` for no return). */
+    value: unknown;
+    /** Why the run settled. */
+    stopReason: WorkflowStopReason;
+    /** The failure message (present iff `stopReason` is not `completed`). */
+    error?: string;
+    /**
+     * How many `agent()` calls the run accepted over its whole lifetime. On a
+     * graceful settlement this is the script-side count (calls still queued for
+     * a concurrency slot included); on a termination path (grace force-settle,
+     * worker death) it degrades to the host-observed count — calls queued
+     * inside a terminated script are unknowable then.
+     */
+    agentsStarted: number;
+}
+/** Identifying detail for a run, carried by every `workflow/*` event as borrowed immutable data, never the live run. */
+export interface WorkflowRunInfo {
+    /** The run's id. */
+    id: WorkflowRunId;
+    /** The run's validated meta block. */
+    meta: WorkflowMeta;
+}
+/** One `agent()` call's identity within a run (the `workflow/agent-start` payload). */
+export interface WorkflowAgentInfo {
+    /** 1-based sequence number of this `agent()` call within the run. */
+    seq: number;
+    /** The display label (the `label` option, or a prompt snippet). */
+    label: string;
+    /** The phase this agent belongs to (the `phase` option, else the current `phase()` title). */
+    phase?: string;
+    /** The child agent's id on the subagent seam. */
+    childId: SessionId;
+}
+/** How one `agent()` call settled: clean result, child failure (script sees `null`), or run cancellation. */
+export type WorkflowAgentOutcome = 'completed' | 'failed' | 'cancelled';
+/** One `agent()` call's settlement (the `workflow/agent-end` payload). */
+export interface WorkflowAgentEndInfo extends WorkflowAgentInfo {
+    /** How the call settled. */
+    outcome: WorkflowAgentOutcome;
+}
+/**
+ * A settled run's outcome as event data (the `workflow/end` payload): the
+ * {@link WorkflowResult} minus `value` (a listener observing outcomes must not
+ * receive a mutable alias of the caller's result value; a consumer that needs
+ * the value holds the run and awaits `result`).
+ */
+export interface WorkflowResultInfo {
+    /** Why the run settled. */
+    stopReason: WorkflowStopReason;
+    /** The failure message (present iff `stopReason` is not `completed`). */
+    error?: string;
+    /** How many `agent()` calls the run accepted (see {@link WorkflowResult.agentsStarted}). */
+    agentsStarted: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,16 @@
+/**
+ * Workflow seam vocabulary: the request/run/result types a workflow engine
+ * consumes and produces, plus the fields in the `workflow/*` event payloads.
+ * Types only (plus the id-brand factory), per the package convention.
+ *
+ * @module @prettier-ai/dsh-workflow/types
+ */
+/**
+ * Brand a string as a {@link WorkflowRunId}.
+ * @param id - the raw id string (the engine mints UUIDs; tests may pass fixtures).
+ * @returns the same string, branded.
+ */
+export function WorkflowRunId(id) {
+    return id;
+}
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@prettier-ai/dsh-workflow",
+  "description": "Workflow capability seam: ctx.workflowEngine service, run vocabulary, and workflow/* events",
+  "version": "0.1.2-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/workflow/workflow"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@prettier-ai/dsh-agent": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-invariants": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-brand": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-llm": "^0.1.2-alpha.1",
+    "@prettier-ai/cordis": "^4.0.1",
+    "@prettier-ai/dsh-session": "^0.1.2-alpha.1"
+  },
+  "devDependencies": {
+    "@prettier-ai/dsh-agent": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-brand": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-invariants": "^0.1.2-alpha.1",
+    "@prettier-ai/cordis": "^4.0.1",
+    "@prettier-ai/dsh-session": "^0.1.2-alpha.1",
+    "@prettier-ai/dsh-llm": "^0.1.2-alpha.1"
+  }
+}