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

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: af61308b99bffb290fe2a11cb6c3ccd228cbfaf6
+README.zh.md: 6d85c3b7e847b8c6176d4c1938805c22c543678b

package/README.md

@@ -6,6 +6,8 @@ The workflow seam (`ctx.workflows`) executes a model-written orchestration scrip
 
 `@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.
 
+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.
@@ -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

@@ -6,6 +6,8 @@
 
 `@deepseek-ai/dsh-workflow-workerthread` 是当前引擎，`@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` 兑现。

package/lib/types/index.d.ts

@@ -5,9 +5,11 @@
  */
 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;

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 WorkflowService extends Service {
+    constructor(ctx) {
+        super(ctx, 'workflows');
+    }
+    /**
+     * 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 WorkflowService;
+//# 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",
+  "version": "0.0.1-rc.2",
   "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/dsh-agent": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1-rc.1"
   },
   "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-brand": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
   }
 }