@hasna-internal/kai-workflow 0.1.1-rc.2

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: cc2c24f62512273ea1657542d0d904b0b870e236
+README.zh.md: 0b02cea896b3cb64559ce110c0da2478728f513c

package/README.md

@@ -0,0 +1,61 @@
+# @hasna-internal/kai-workflow
+
+English | [中文](README.zh.md)
+
+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.
+
+`@hasna-internal/kai-workflow-worker-thread` is the current engine and `@hasna-internal/kai-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 `@hasna-internal/kai-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
+
+`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.
+
+`WorkflowStartRequest` contains `{ meta, script, args?, subagentProvider?, maxTotalAgents?, parent, signal? }`. `parent` attributes every child agent to the invoking agent. `subagentProvider` optionally routes every child in that run without exposing provider choice to the script; omission uses the engine's configured provider. `maxTotalAgents` optionally lowers the engine's deployment ceiling for one run and is likewise invisible to the script. An implementation rejects invalid routes and limits synchronously. `meta` and `args` are plain data, not script fragments.
+
+`WorkflowRun` exposes `{ id, meta, result, cancel(reason?), dispose() }`. `WorkflowResult` contains `{ value, stopReason, error?, agentsStarted }`; `value` is plain JSON data or `null`.
+
+## Events
+
+Workflow events are observe-only. They carry `WorkflowRunInfo` (`id` plus `meta`) rather than the live run, so listeners cannot acquire cancellation or disposal authority.
+
+- `workflow/start` / `workflow/end` pair the run.
+- `workflow/phase` and `workflow/log` expose script narration.
+- `workflow/agent-start` / `workflow/agent-end` pair each child call by `seq`; a child whose async provider start rejects emits neither.
+
+Same-process event payloads are borrowed immutable values. Every listener is independently contained: a synchronous throw or rejected returned promise is logged without starving peers or changing execution.
+
+## Failure discipline
+
+`WorkflowError` carries a code and a `fatal` flag. Fatal errors always escape `parallel()` and `pipeline()` instead of becoming an ordinary per-item `null`:
+
+- `SCRIPT_PARSE` / `META_INVALID` — the workflow cannot start.
+- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA` — a hook call violates the engine contract.
+- `AGENT_CAP` / `ITEM_CAP` — configured safety limits were exceeded.
+- `AGENT_START` — the provider's async start rejected.
+- `AGENT_RESULT` — a published child's result rejected with an infrastructure fault.
+- `RESULT_UNSERIALIZABLE` — a script/worker value is not plain JSON data.
+- `CANCELLED` — cancellation owns the run and pending/future hooks reject.
+
+A child that resolves normally with a non-completed stop reason is not an infrastructure exception: `agent()` returns `null`, allowing the script to handle an ordinary child failure.
+
+## Model Experience
+
+Indirectly, through `dsh-tool-workflow` and a workflow engine, which create child-agent requests and return a retained parent tool result.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **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 seam 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 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 API.

package/README.zh.md

@@ -0,0 +1,61 @@
+# @hasna-internal/kai-workflow
+
+[English](README.md) | 中文
+
+工作流 seam（扩展点，`ctx.workflowEngine`）执行由模型编写、可扇出 subagent 的编排脚本。该 seam 定义脚本、运行、结果、错误和事件契约；引擎负责决定如何隔离并执行脚本。
+
+`@hasna-internal/kai-workflow-worker-thread` 是当前引擎，`@hasna-internal/kai-tool-workflow` 是面向模型的消费方。未来的进程或沙箱引擎可以替换实现，而无需更改工具。
+
+包根是 Host face。浏览器安全的 `@hasna-internal/kai-workflow/types` 子路径包含运行身份、元数据、结果和仅供观察的生命周期 payload，不导入 `Agent`、Cordis service 或 Host Context 声明；Host 专用的 `WorkflowStartRequest` 与 `WorkflowRun` 只从包根提供。
+
+## 服务与运行契约
+
+`WorkflowEngine.start(request): WorkflowRun` 会同步完成足够多的校验，在运行创建前拒绝格式错误的 meta 块、无法解析的脚本、不可用的提供方路由或不受支持的单次运行限制。返回后，`WorkflowRun.result` 绝不拒绝：执行失败以 `stopReason: 'error'` 兑现，取消则在引擎有限的宽限时间内以 `cancelled` 兑现。
+
+运行由持有方负责。引擎插件卸载会阻止新的启动，但不会撤销已接受的运行。持有方必须在每条路径上调用 `dispose()`；dispose（资源释放）会取消剩余工作，并在文档规定的期限内达到或放弃完全停稳。
+
+`WorkflowStartRequest` 包含 `{ meta, script, args?, subagentProvider?, maxTotalAgents?, parent, signal? }`。`parent` 把每个子 agent（智能体）归属于调用 agent。`subagentProvider` 可以为该次运行的所有子 agent 指定路由，同时不向脚本公开提供方选择；省略时使用引擎配置的提供方。`maxTotalAgents` 可以为一次运行降低引擎的部署上限，同样对脚本不可见。实现会同步拒绝无效路由和限制。`meta` 与 `args` 是普通数据，不是脚本片段。
+
+`WorkflowRun` 公开 `{ id, meta, result, cancel(reason?), dispose() }`。`WorkflowResult` 包含 `{ value, stopReason, error?, agentsStarted }`；`value` 是普通 JSON 数据或 `null`。
+
+## 事件
+
+工作流事件只供观察。它们携带 `WorkflowRunInfo`（`id` 加 `meta`），而不是活动运行，因此监听器无法取得取消或 dispose 权限。
+
+- `workflow/start` / `workflow/end` 为运行配对；
+- `workflow/phase` 和 `workflow/log` 公开脚本叙述；
+- `workflow/agent-start` / `workflow/agent-end` 按 `seq` 为每次子 agent 调用配对；提供方的异步启动调用被拒绝时，该子 agent 不会发出其中任何一个事件。
+
+同进程事件 payload 是以不可变方式借用的值。每个监听器都独立隔离：同步抛出异常或返回的 promise 被拒绝时，只会记录日志，不会阻塞同级监听器或改变执行。
+
+## 失败纪律
+
+`WorkflowError` 携带一个代码和 `fatal` 标志。致命错误总会逸出 `parallel()` 和 `pipeline()`，而不会变成普通的逐项 `null`：
+
+- `SCRIPT_PARSE` / `META_INVALID`：工作流无法启动；
+- `INVALID_ARGUMENT` / `UNSUPPORTED_OPTION` / `UNSUPPORTED_SCHEMA`：钩子调用违反引擎契约；
+- `AGENT_CAP` / `ITEM_CAP`：超过已配置的安全上限；
+- `AGENT_START`：提供方的异步启动调用被拒绝；
+- `AGENT_RESULT`：已发布子 agent 的结果因基础设施故障而被拒绝；
+- `RESULT_UNSERIALIZABLE`：脚本/worker 值不是普通 JSON 数据；
+- `CANCELLED`：取消会接管该运行，待处理和未来的钩子都会拒绝。
+
+子 agent 若以非完成的结束原因正常兑现，并不属于基础设施异常：`agent()` 返回 `null`，使脚本可以处理普通的子 agent 失败。
+
+## 模型体验
+
+通过 `dsh-tool-workflow` 和工作流引擎间接产生影响；两者创建子 agent 请求，并返回保留在父级的工具结果。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀的任何变化均由上述消费方负责。
+
+## 已知限制与暂缓事项
+
+- **仅支持前台收集**：调用方负责一个活动运行并等待它；后台启动／轮询、spill 句柄和分离收集均暂缓处理。
+- **没有日志化或恢复**：脚本、子 agent 进度和中间值均不设检查点，因此进程重启后无法继续运行。
+- **没有已保存或嵌套工作流**：该 seam 只启动调用方提供的脚本，工作流脚本不会收到用于递归编排的 `workflow()` 钩子。
+- **没有 token 预算词汇**：引擎会限制并发、条目和子 agent，但请求与结果都不会统计跨子 agent 的模型 token。
+- **运行由持有方负责，不由服务跟踪**：卸载引擎不会发现独立的活动句柄；每个消费方都必须 dispose 自己启动的运行。
+
+暂缓实现的工作流接口见[动态工作流 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-05-dynamic-workflows.zh.md)。

package/lib/index.js

@@ -0,0 +1,92 @@
+import { Service } from "@deepseek-ai/cordis";
+import { HarnessError } from "@hasna-internal/kai-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 @hasna-internal/kai-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 @hasna-internal/kai-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 @hasna-internal/kai-workflow/invariant */
+const PACKAGE_NAME = "@hasna-internal/kai-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 @hasna-internal/kai-workflow
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { HarnessError } from '@hasna-internal/kai-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 '@deepseek-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 @hasna-internal/kai-workflow
+ */
+import { Service } from '@deepseek-ai/cordis';
+import { HarnessError } from '@hasna-internal/kai-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 @hasna-internal/kai-workflow/invariant */
+import type { Context } from '@deepseek-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 @hasna-internal/kai-workflow/invariant */
+const PACKAGE_NAME = '@hasna-internal/kai-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 @hasna-internal/kai-workflow
+ */
+import type { Agent } from '@hasna-internal/kai-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 @hasna-internal/kai-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 @hasna-internal/kai-workflow/types
+ */
+import type { Branded } from '@hasna-internal/kai-brand';
+import type { SessionId } from '@hasna-internal/kai-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 @hasna-internal/kai-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": "@hasna-internal/kai-workflow",
+  "description": "Workflow capability seam: ctx.workflowEngine service, run vocabulary, and workflow/* events",
+  "version": "0.1.1-rc.2",
+  "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": {
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2",
+    "@hasna-internal/kai-agent": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-llm": "^0.1.1-rc.2",
+    "@hasna-internal/kai-brand": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@hasna-internal/kai-agent": "^0.1.1-rc.2",
+    "@hasna-internal/kai-brand": "^0.1.1-rc.2",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2",
+    "@hasna-internal/kai-llm": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}