@deepseek-ai/dsh-workflow 0.0.1-rc.1 → 0.0.1-rc.5

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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: 0de661423206cc71eb4669bc8ddb2419202bcb4a
-README.zh.md: 62abd00c013d054f4111a2db2ce72c58d3514087
+README.md: cc2c24f62512273ea1657542d0d904b0b870e236
+README.zh.md: 22bda1bd33bc6350c8ff51f27538258bee872fdb

package/README.md

@@ -2,13 +2,15 @@
 
 English | [中文](README.zh.md)
 
-The workflow seam (`ctx.workflows`) executes a model-written orchestration script that can fan out subagents. The seam defines the script, run, result, error, and event contracts; an engine decides how to isolate and execute the script.
+The workflow seam (`ctx.workflowEngine`) executes a model-written orchestration script that can fan out subagents. The seam defines the script, run, result, error, and event contracts; an engine decides how to isolate and execute the script.
 
-`@deepseek-ai/dsh-workflow-workerthread` is the current engine and `@deepseek-ai/dsh-tool-workflow` is the model-facing consumer. A future process or sandbox engine can replace the implementation without changing the tool.
+`@deepseek-ai/dsh-workflow-worker-thread` is the current engine and `@deepseek-ai/dsh-tool-workflow` is the model-facing consumer. A future process or sandbox engine can replace the implementation without changing the tool.
+
+The package root is the Host face. The browser-safe `@deepseek-ai/dsh-workflow/types` subpath contains run identities, metadata, results, and observe-only lifecycle payloads without importing `Agent`, Cordis services, or Host context declarations; Host-only `WorkflowStartRequest` and `WorkflowRun` live behind the package root.
 
 ## Service and run contract
 
-`WorkflowService.start(request): WorkflowRun` validates enough synchronously to reject a malformed meta block, unparseable script, unavailable provider route, or unsupported per-run limit before a run exists. Once returned, `WorkflowRun.result` never rejects: execution failures resolve with `stopReason: 'error'`, and cancellation resolves with `cancelled` within the engine's bounded grace.
+`WorkflowEngine.start(request): WorkflowRun` validates enough synchronously to reject a malformed meta block, unparseable script, unavailable provider route, or unsupported per-run limit before a run exists. Once returned, `WorkflowRun.result` never rejects: execution failures resolve with `stopReason: 'error'`, and cancellation resolves with `cancelled` within the engine's bounded grace.
 
 A run is holder-owned. Engine-plugin unload prevents new starts but does not revoke accepted runs. The holder must call `dispose()` on every path; disposal cancels remaining work and reaches or abandons quiescence within the documented bound.
 
@@ -56,4 +58,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 - **No token-budget vocabulary** — engines cap concurrency, items, and children, but neither the request nor 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.
 
-See the [dynamic-workflows Agent Note](../../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) for the deferred workflow surface.
+See the [dynamic-workflows Agent Note](../../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md) for the deferred workflow API.

package/README.zh.md

@@ -2,13 +2,15 @@
 
 [English](README.md) | 中文
 
-工作流 seam（`ctx.workflows`）执行由模型编写、可扇出 subagent 的编排脚本。该 seam 定义脚本、运行、结果、错误和事件约定；引擎负责决定如何隔离并执行脚本。
+工作流 seam（扩展点，`ctx.workflowEngine`）执行由模型编写、可扇出 subagent 的编排脚本。该 seam 定义脚本、运行、结果、错误和事件契约；引擎负责决定如何隔离并执行脚本。
 
-`@deepseek-ai/dsh-workflow-workerthread` 是当前引擎，`@deepseek-ai/dsh-tool-workflow` 是面向模型的消费方。未来的进程或沙箱引擎可以替换实现，而无需更改工具。
+`@deepseek-ai/dsh-workflow-worker-thread` 是当前引擎，`@deepseek-ai/dsh-tool-workflow` 是面向模型的消费方。未来的进程或沙箱引擎可以替换实现，而无需更改工具。
 
-## 服务与运行约定
+包根是 Host face。浏览器安全的 `@deepseek-ai/dsh-workflow/types` 子路径包含运行身份、元数据、结果和仅供观察的生命周期 payload，不导入 `Agent`、Cordis service 或 Host Context 声明；Host 专用的 `WorkflowStartRequest` 与 `WorkflowRun` 只从包根提供。
 
-`WorkflowService.start(request): WorkflowRun` 会同步完成足够多的校验，在运行创建前拒绝格式错误的 meta 块、无法解析的脚本、不可用的提供方路由或不受支持的单次运行限制。返回后，`WorkflowRun.result` 绝不拒绝：执行失败以 `stopReason: 'error'` 兑现，取消则在引擎有限的宽限时间内以 `cancelled` 兑现。
+## 服务与运行契约
+
+`WorkflowEngine.start(request): WorkflowRun` 会同步完成足够多的校验，在运行创建前拒绝格式错误的 meta 块、无法解析的脚本、不可用的提供方路由或不受支持的单次运行限制。返回后，`WorkflowRun.result` 绝不拒绝：执行失败以 `stopReason: 'error'` 兑现，取消则在引擎有限的宽限时间内以 `cancelled` 兑现。
 
 运行由持有方负责。引擎插件卸载会阻止新的启动，但不会撤销已接受的运行。持有方必须在每条路径上调用 `dispose()`；dispose（资源释放）会取消剩余工作，并在文档规定的期限内达到或放弃完全停稳。
 
@@ -24,19 +26,19 @@
 - `workflow/phase` 和 `workflow/log` 公开脚本叙述；
 - `workflow/agent-start` / `workflow/agent-end` 按 `seq` 为每次子 agent 调用配对；提供方的异步启动调用被拒绝时，该子 agent 不会发出其中任何一个事件。
 
-同进程事件 payload 是借用的不可变值。每个监听器都独立隔离：同步抛出异常或返回的 promise 被拒绝时，只会记录日志，不会阻塞同级监听器或改变执行。
+同进程事件 payload 是以不可变方式借用的值。每个监听器都独立隔离：同步抛出异常或返回的 promise 被拒绝时，只会记录日志，不会阻塞同级监听器或改变执行。
 
 ## 失败纪律
 
 `WorkflowError` 携带一个代码和 `fatal` 标志。致命错误总会逸出 `parallel()` 和 `pipeline()`，而不会变成普通的逐项 `null`：
 
 - `SCRIPT_PARSE` / `META_INVALID`：工作流无法启动；
-- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA`：钩子调用违反引擎约定；
+- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA`：钩子调用违反引擎契约；
 - `AGENT_CAP` / `ITEM_CAP`：超过已配置的安全上限；
 - `AGENT_START`：提供方的异步启动调用被拒绝；
 - `AGENT_RESULT`：已发布子 agent 的结果因基础设施故障而被拒绝；
 - `RESULT_UNSERIALIZABLE`：脚本/worker 值不是普通 JSON 数据；
-- `CANCELLED`：取消会接管该运行，待处理和后续的钩子调用都会被拒绝。
+- `CANCELLED`：取消会接管该运行，待处理和未来的钩子都会拒绝。
 
 子 agent 若以非完成的结束原因正常兑现，并不属于基础设施异常：`agent()` 返回 `null`，使脚本可以处理普通的子 agent 失败。
 
@@ -56,4 +58,4 @@
 - **没有 token 预算词汇**：引擎会限制并发、条目和子 agent，但请求与结果都不会统计跨子 agent 的模型 token。
 - **运行由持有方负责，不由服务跟踪**：卸载引擎不会发现独立的活动句柄；每个消费方都必须 dispose 自己启动的运行。
 
-暂缓实现的工作流接口见[动态工作流 Agent Note](../../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。
+暂缓实现的工作流接口见[动态工作流 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.md)。

package/lib/index.js

@@ -56,9 +56,9 @@ function isFatalWorkflowError(error) {
 * listener failures are contained, and `workflow/end` fires exactly once as the
 * result settles.
 */
-var WorkflowService = class extends Service {
+var WorkflowEngine = class extends Service {
 	constructor(ctx) {
-		super(ctx, "workflows");
+		super(ctx, "workflowEngine");
 	}
 	/**
 	* Emit a lifecycle event while containing and logging each listener failure.
@@ -89,4 +89,4 @@ function renderListenerError(error) {
 	}
 }
 //#endregion
-export { WorkflowError, WorkflowRunId, WorkflowService, WorkflowService as default, isFatalWorkflowError };
+export { WorkflowEngine, WorkflowEngine as default, WorkflowError, WorkflowRunId, isFatalWorkflowError };

package/lib/types/index.d.ts

@@ -5,12 +5,14 @@
  */
 import { Context, Service } from '@deepseek-ai/cordis';
 import { HarnessError } from '@deepseek-ai/dsh-llm';
-import type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowResultInfo, WorkflowRun, WorkflowRunInfo, WorkflowStartRequest } from './types.ts';
+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, WorkflowRun, WorkflowRunInfo, WorkflowStartRequest, WorkflowStopReason, } 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 '@deepseek-ai/cordis' {
     interface Context {
-        workflows: WorkflowService;
+        workflowEngine: WorkflowEngine;
     }
     interface Events {
         /**
@@ -68,7 +70,7 @@ declare module '@deepseek-ai/cordis' {
         'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void;
     }
 }
-/** The full set of `workflow/*` event names {@link WorkflowService.emitWorkflowEvent} dispatches. */
+/** 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,
@@ -106,7 +108,7 @@ export declare function isFatalWorkflowError(error: unknown): boolean;
  * listener failures are contained, and `workflow/end` fires exactly once as the
  * result settles.
  */
-export declare abstract class WorkflowService extends Service {
+export declare abstract class WorkflowEngine extends Service {
     constructor(ctx: Context);
     /**
      * Parse and execute a workflow script.
@@ -122,5 +124,5 @@ export declare abstract class WorkflowService extends Service {
      */
     protected emitWorkflowEvent(name: WorkflowEventName, ...args: unknown[]): void;
 }
-export default WorkflowService;
+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 @deepseek-ai/dsh-workflow
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { HarnessError } from '@deepseek-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.js

@@ -0,0 +1,118 @@
+/** Package-owned workflow lifecycle invariants. @module @deepseek-ai/dsh-workflow/invariant */
+const PACKAGE_NAME = '@deepseek-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 @deepseek-ai/dsh-workflow
+ */
+import type { Agent } from '@deepseek-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 @deepseek-ai/dsh-workflow
+ */
+export {};
+//# sourceMappingURL=runtime-types.js.map

package/lib/types/types.d.ts

@@ -6,8 +6,7 @@
  * @module @deepseek-ai/dsh-workflow/types
  */
 import type { Branded } from '@deepseek-ai/dsh-brand';
-import type { Agent } from '@deepseek-ai/dsh-agent';
-import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
 /** Identifies one workflow run. */
 export type WorkflowRunId = Branded<'WorkflowRunId'>;
 /**
@@ -47,37 +46,6 @@ export interface WorkflowMeta {
     /** Optional phase declarations matched by `phase()` calls. */
     phases?: WorkflowPhase[];
 }
-/**
- * What a caller asks for when starting a workflow run. `meta` and `args` are
- * plain JSON DATA by the seam contract (the tool builds both from the model's schema-validated call;
- * the engine validates `meta` against its schema and rejects loud
- * before anything runs) — an engine never evaluates script text to obtain
- * them. `parent` is REQUIRED — every `agent()` the script spawns is
- * attributed to it (cwd, lineage, depth flow through the subagent seam).
- */
-export interface WorkflowStartRequest {
-    /** The plain-JS script body (top-level await allowed; ends with `return <json-value>`). */
-    script: string;
-    /** The workflow's identity fields as plain JSON data, 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. The workflow
-     * script cannot observe or replace it; omission uses the engine's configured
-     * provider.
-     */
-    subagentProvider?: string;
-    /**
-     * Optional per-run total-child ceiling. Implementations reject values above
-     * their deployment ceiling before publishing the run.
-     */
-    maxTotalAgents?: number;
-    /** The agent on whose behalf the run executes (parent of every child). */
-    parent: Agent;
-    /** Cancels the run when aborted (the tool's `exec.signal`). */
-    signal?: AbortSignal;
-}
 /**
  * Why a run settled. CLOSED union (engine-owned, consumers may exhaust):
  * `completed` = the script ran to its final `return`; `cancelled` = the run
@@ -86,7 +54,7 @@ export interface WorkflowStartRequest {
  */
 export type WorkflowStopReason = 'completed' | 'cancelled' | 'error';
 /**
- * The outcome of one run, resolved by {@link WorkflowRun.result}. `value` is
+ * 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
@@ -108,22 +76,6 @@ export interface WorkflowResult {
      */
     agentsStarted: number;
 }
-/**
- * Holder-owned live workflow. `result` never rejects and settles within the
- * engine's cancellation grace; failures resolve through `stopReason`. Consumers
- * may cancel and must call idempotent `dispose()` on every path to await bounded
- * script settlement and child quiescence.
- */
-export interface WorkflowRun {
-    readonly id: WorkflowRunId;
-    /** The validated meta block (available before the body runs). */
-    readonly meta: WorkflowMeta;
-    readonly result: Promise<WorkflowResult>;
-    /** Cancel the run: children abort, pending hooks reject, the script dies at its next await (or is force-settled at the grace). */
-    cancel(reason?: string): void;
-    /** Cancel + bounded-grace settle; safe to call on every path (idempotent). */
-    dispose(): Promise<void>;
-}
 /** 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. */

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 @deepseek-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

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-workflow",
-  "description": "Workflow capability seam: ctx.workflows service, run vocabulary, and workflow/* events",
-  "version": "0.0.1-rc.1",
+  "description": "Workflow capability seam: ctx.workflowEngine service, run vocabulary, and workflow/* events",
+  "version": "0.0.1-rc.5",
   "publishConfig": {
     "access": "restricted"
   },
@@ -22,29 +22,34 @@
       "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": "BSD-3-Clause",
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.5",
+    "@deepseek-ai/cordis": "^4.0.1-rc.4"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1"
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.5",
+    "@deepseek-ai/cordis": "^4.0.1-rc.4"
   }
 }