@xrkseek/harness 0.6.21 → 0.7.0-rc.1

package/node_modules/@xrkseek/xrk-token-meter/lib/types/usage-projection.js

@@ -0,0 +1,161 @@
+/**
+ * Pure folds for durable provider-reported token usage and context occupancy.
+ */
+import { z } from 'zod';
+import { foldSurfaceProjection } from "./surface-projection.js";
+const zeroBuckets = () => ({
+    uncachedInputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+});
+const bucketsFrom = (usage) => ({
+    uncachedInputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    cacheReadTokens: usage.cacheReadTokens ?? 0,
+    cacheWriteTokens: usage.cacheWriteTokens ?? 0,
+});
+const bucketsEqual = (left, right) => left.uncachedInputTokens === right.uncachedInputTokens
+    && left.outputTokens === right.outputTokens
+    && left.cacheReadTokens === right.cacheReadTokens
+    && left.cacheWriteTokens === right.cacheWriteTokens;
+const addReplacing = (totals, previous, next) => ({
+    uncachedInputTokens: totals.uncachedInputTokens - (previous?.uncachedInputTokens ?? 0) + next.uncachedInputTokens,
+    outputTokens: totals.outputTokens - (previous?.outputTokens ?? 0) + next.outputTokens,
+    cacheReadTokens: totals.cacheReadTokens - (previous?.cacheReadTokens ?? 0) + next.cacheReadTokens,
+    cacheWriteTokens: totals.cacheWriteTokens - (previous?.cacheWriteTokens ?? 0) + next.cacheWriteTokens,
+});
+const projectionSchema = z.object({
+    uncachedInputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+    cacheReadTokens: z.number().int().nonnegative(),
+    cacheWriteTokens: z.number().int().nonnegative(),
+}).strict();
+// Cast for the optional values: under exactOptionalPropertyTypes zod infers
+// `number | undefined` where the interface declares absent-or-number fields.
+const pressureSchema = z.object({
+    pressureTokens: z.number().int().nonnegative().optional(),
+    projectedTokens: z.number().int().nonnegative().optional(),
+    contextWindow: z.number().int().positive().optional(),
+}).strict();
+/** Prompt-side pressure: uncached + cacheRead (not cacheWrite; not output). */
+const pressureFrom = (usage) => usage.inputTokens + (usage.cacheReadTokens ?? 0);
+/** The usage a chunk or finalized message reports for its step, if any. */
+const usageOf = (event) => event.type === 'assistant/chunk' && event.data.chunk.type === 'usage'
+    ? event.data.chunk.usage
+    : event.type === 'assistant/message'
+        ? event.data.usage
+        : undefined;
+/**
+ * Token-meter's session projection unit.
+ *
+ * Usage chunks provide an early sample that survives a later request failure;
+ * an assistant message provides the final sample for the same turn/step. A
+ * repeated sample replaces that step's earlier value instead of double
+ * counting it. The single `last` slot relies on the session-log invariant
+ * that usage reports for one turn/step are adjacent: once a later step begins,
+ * a legal log never reports usage for an earlier step again.
+ */
+export const tokenUsageProjectionDefinition = {
+    key: 'tokenUsage',
+    schema: projectionSchema,
+    init: () => ({ totals: zeroBuckets(), last: null }),
+    apply: (state, event) => {
+        let turn;
+        let step;
+        let usage;
+        if (event.type === 'assistant/chunk' && event.data.chunk.type === 'usage') {
+            ;
+            ({ turn, step } = event.data);
+            usage = event.data.chunk.usage;
+        }
+        else if (event.type === 'assistant/message' && event.data.usage !== undefined) {
+            ;
+            ({ turn, step, usage } = event.data);
+        }
+        else {
+            return state;
+        }
+        const buckets = bucketsFrom(usage);
+        const previous = state.last !== null
+            && state.last.turn === turn
+            && state.last.step === step
+            ? state.last.buckets
+            : undefined;
+        if (previous !== undefined && bucketsEqual(previous, buckets))
+            return state;
+        return {
+            totals: addReplacing(state.totals, previous, buckets),
+            last: { turn, step, buckets },
+        };
+    },
+    view: state => state.totals,
+    stateVersion: 1,
+};
+/**
+ * Token-meter's context-occupancy projection unit.
+ *
+ * Independent last-wins slots: the newest usage sample supplies the provider
+ * numerator, the newest `request/context` record the denominator. Both are
+ * whole values, so replay order alone decides the result and no cross-field
+ * consistency is claimed — the pair is explicitly not one atomic request
+ * observation (see {@link ContextPressureProjection}).
+ *
+ * `pressureTokens` is prompt-side only, so it holds still while a turn streams
+ * and steps forward once the next request reports its usage. Because nothing
+ * but a request reports usage, it also cannot see a compaction: the fold
+ * therefore carries a running surface total alongside it and publishes
+ * `projectedTokens` — the sample plus the surface's signed movement since it
+ * was taken — so occupancy answers for the next request rather than the last
+ * one. The total rides {@link foldSurfaceProjection}, so the state stays O(1)
+ * and a replacement shrinks it by its logged shadow price. A replacement
+ * without a claim preserves the previous total. A usage sample is stamped
+ * BEFORE the same event joins the surface, so an `assistant/message` anchors
+ * against the surface its own request saw.
+ */
+export const contextPressureProjectionDefinition = {
+    key: 'contextPressure',
+    schema: pressureSchema,
+    init: () => ({ surfaceTokens: 0 }),
+    apply: (state, event) => {
+        const fold = foldSurfaceProjection(state.claim, event);
+        let next = state;
+        if (event.type === 'request/context') {
+            const contextWindow = event.data.contextWindow;
+            if (contextWindow !== state.contextWindow) {
+                if (contextWindow !== undefined) {
+                    next = { ...next, contextWindow };
+                }
+                else {
+                    const { contextWindow: _removed, ...withoutContextWindow } = next;
+                    next = withoutContextWindow;
+                }
+            }
+        }
+        const usage = usageOf(event);
+        if (usage !== undefined) {
+            const pressureTokens = pressureFrom(usage);
+            if (pressureTokens !== next.pressureTokens || next.sampledSurfaceTokens !== next.surfaceTokens) {
+                next = { ...next, pressureTokens, sampledSurfaceTokens: next.surfaceTokens };
+            }
+        }
+        if (fold.deltaTokens !== 0) {
+            next = { ...next, surfaceTokens: next.surfaceTokens + fold.deltaTokens };
+        }
+        // A defined fold.claim is always freshly built, so presence decides claim
+        // bookkeeping: no claim before or after this event leaves `next` as is.
+        if (state.claim === undefined && fold.claim === undefined)
+            return next;
+        const { claim: _expired, ...withoutClaim } = next;
+        return fold.claim === undefined ? withoutClaim : { ...withoutClaim, claim: fold.claim };
+    },
+    view: ({ contextWindow, pressureTokens, surfaceTokens, sampledSurfaceTokens }) => ({
+        ...contextWindow === undefined ? {} : { contextWindow },
+        ...pressureTokens === undefined ? {} : { pressureTokens },
+        ...pressureTokens === undefined || sampledSurfaceTokens === undefined
+            ? {}
+            : { projectedTokens: Math.max(0, pressureTokens + surfaceTokens - sampledSurfaceTokens) },
+    }),
+    stateVersion: 4,
+};
+//# sourceMappingURL=usage-projection.js.map

package/node_modules/@xrkseek/xrk-token-meter/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@xrkseek/xrk-token-meter",
+  "description": "Replay-aware token measurement service (ctx.tokenMeter) for the DeepSeek Harness",
+  "version": "0.1.0-rc.8",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xrkseek/XRK-harness.git",
+    "directory": "packages/llm/token-meter"
+  },
+  "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"
+    },
+    "./client": {
+      "types": "./lib/types/client.d.ts",
+      "default": "./lib/types/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@xrkseek/xrk-compaction": "workspace:^",
+    "@xrkseek/xrk-invariants": "workspace:^",
+    "@xrkseek/xrk-llm": "workspace:^",
+    "@xrkseek/xrk-session": "workspace:^",
+    "@xrkseek/xrk-session-projection": "workspace:^",
+    "@xrkseek/cordis": "workspace:^"
+  },
+  "dependencies": {
+    "@xrkseek/schemastery": "workspace:^",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@xrkseek/xrk-compaction": "workspace:^",
+    "@xrkseek/xrk-invariants": "workspace:^",
+    "@xrkseek/xrk-llm": "workspace:^",
+    "@xrkseek/xrk-session": "workspace:^",
+    "@xrkseek/xrk-session-projection": "workspace:^",
+    "@xrkseek/cordis": "workspace:^"
+  },
+  "private": true
+}

package/node_modules/@xrkseek/xrk-tools/lib/index.js

@@ -1 +1 @@
-export * from './types/index.js'
+export * from "./types/index.js";

package/node_modules/@xrkseek/xrk-tools/lib/invariant.js

@@ -1 +1 @@
-export * from './types/invariant.js'
+export * from "./types/invariant.js";

package/node_modules/@xrkseek/xrk-tools/src/presentation.ts

@@ -1,39 +1,39 @@
-/**
- * Tool render-intent vocabulary — single source of truth: `@xrkseek/core-tools`.
- * This Cordis stub package re-exports so remotes stay on
- * `@xrkseek/xrk-tools/presentation` without a second FileDiff / card fork.
- */
-export type {
-  DiffCallView,
-  DiffResultView,
-  FileDiff,
-  FileLocation,
-  GenericCallView,
-  GenericResultView,
-  ParsedExitStatus,
-  PresentableToolResult,
-  ReadFileLine,
-  ReadResultView,
-  SearchFileMatches,
-  SearchLineMatch,
-  SearchMatchesResultView,
-  SearchPathsResultView,
-  TerminalCallView,
-  TerminalResultView,
-  TextBlock,
-  ToolCallKind,
-  ToolCallView,
-  ToolEventView,
-  ToolResultView,
-  WebFetchResultView,
-  WebResultView,
-  WebSearchResultView,
-  WebSource,
-} from "@xrkseek/core-tools";
-
-export { parseExitStatus } from "@xrkseek/core-tools";
-
-/** Discriminated search result union (matches + paths). */
-export type SearchResultView =
-  | import("@xrkseek/core-tools").SearchMatchesResultView
-  | import("@xrkseek/core-tools").SearchPathsResultView;
+/**
+ * Tool render-intent vocabulary — single source of truth: `@xrkseek/core-tools`.
+ * This Cordis stub package re-exports so remotes stay on
+ * `@xrkseek/xrk-tools/presentation` without a second FileDiff / card fork.
+ */
+export type {
+  DiffCallView,
+  DiffResultView,
+  FileDiff,
+  FileLocation,
+  GenericCallView,
+  GenericResultView,
+  ParsedExitStatus,
+  PresentableToolResult,
+  ReadFileLine,
+  ReadResultView,
+  SearchFileMatches,
+  SearchLineMatch,
+  SearchMatchesResultView,
+  SearchPathsResultView,
+  TerminalCallView,
+  TerminalResultView,
+  TextBlock,
+  ToolCallKind,
+  ToolCallView,
+  ToolEventView,
+  ToolResultView,
+  WebFetchResultView,
+  WebResultView,
+  WebSearchResultView,
+  WebSource,
+} from "@xrkseek/core-tools";
+
+export { parseExitStatus } from "@xrkseek/core-tools";
+
+/** Discriminated search result union (matches + paths). */
+export type SearchResultView =
+  | import("@xrkseek/core-tools").SearchMatchesResultView
+  | import("@xrkseek/core-tools").SearchPathsResultView;

package/node_modules/@xrkseek/xrk-typert-protocol/lib/index.js

@@ -1 +1 @@
-export * from './types/index.js'
+export * from "./types/index.js";

package/node_modules/@xrkseek/xrk-typert-protocol/lib/invariant.js

@@ -0,0 +1 @@
+export * from "./types/invariant.js";

package/node_modules/@xrkseek/xrk-workflow/README.md

@@ -1,73 +1,73 @@
-# @xrkseek/xrk-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.
-
-`@xrkseek/xrk-workflow` ships the abstract {@link WorkflowEngine} seam **and**
-{@link InProcessWorkflowEngine} (AsyncFunction Provider) plus
-{@link IsolatingWorkflowEngine} (worker_threads script-body isolation;
-optional `createAgent` bridge via parentPort RPC — cloneable return values;
-without a bridge `agent()` is still `null`; optional {@link WorkflowToolBridge}
-for `await tools.name(args)` — Code Mode shape). Full sandboxed Node PTC
-process confinement is **not** claimed. Product Host mounts Isolating by default
-(`hostPublic.workflowEngine`, Face `session.create` / `prompt` / drain as the
-createAgent bridge, Face standing tool registry as tools.*). Cordis compositions
-still need `tool-workflow` for the model-facing `workflow` tool. Product Face
-boot uses the Face-native **`ralph`** tool for fresh-agent iteration.
-
-`@xrkseek/xrk-tool-workflow` is the model-facing Cordis consumer.
-
-The package root is the Host face. The browser-safe `@xrkseek/xrk-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.
+# @xrkseek/xrk-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.
+
+`@xrkseek/xrk-workflow` ships the abstract {@link WorkflowEngine} seam **and**
+{@link InProcessWorkflowEngine} (AsyncFunction Provider) plus
+{@link IsolatingWorkflowEngine} (worker_threads script-body isolation;
+optional `createAgent` bridge via parentPort RPC — cloneable return values;
+without a bridge `agent()` is still `null`; optional {@link WorkflowToolBridge}
+for `await tools.name(args)` — Code Mode shape). Full sandboxed Node PTC
+process confinement is **not** claimed. Product Host mounts Isolating by default
+(`hostPublic.workflowEngine`, Face `session.create` / `prompt` / drain as the
+createAgent bridge, Face standing tool registry as tools.*). Cordis compositions
+still need `tool-workflow` for the model-facing `workflow` tool. Product Face
+boot uses the Face-native **`ralph`** tool for fresh-agent iteration.
+
+`@xrkseek/xrk-tool-workflow` is the model-facing Cordis consumer.
+
+The package root is the Host face. The browser-safe `@xrkseek/xrk-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/node_modules/@xrkseek/xrk-workflow/README.zh.md

@@ -1,72 +1,72 @@
-# @xrkseek/xrk-workflow
-
-[English](README.md) | 中文
-
-工作流 seam（扩展点，`ctx.workflowEngine`）执行由模型编写、可扇出 subagent 的编排脚本。该 seam 定义脚本、运行、结果、错误和事件契约；引擎负责决定如何隔离并执行脚本。
-
-`@xrkseek/xrk-workflow` 提供抽象 {@link WorkflowEngine} seam **以及**
-{@link InProcessWorkflowEngine}（AsyncFunction Provider）与
-{@link IsolatingWorkflowEngine}（worker_threads 脚本体隔离；可选
-`createAgent` 经 parentPort RPC 回桥，返回值须可 structuredClone；无桥时
-`agent()` 仍为 null；可选 {@link WorkflowToolBridge} 提供
-`await tools.name(args)`，与 Code Mode 同形）。完整沙箱 Node PTC 进程隔离
-**未声称**。产品 Host 默认挂载 Isolating（`hostPublic.workflowEngine`，Face
-`session.create` / `prompt` / drain 作 createAgent 回桥，站立工具表作
-tools.*）。Cordis 组合另挂 `tool-workflow` 后，模型面 `workflow` 工具才可见。
-产品 Face boot 用 Face 原生 **`ralph`** 工具做新鲜子代理迭代。
-
-`@xrkseek/xrk-tool-workflow` 是面向模型的 Cordis 消费方。
-
-包根是 Host face。浏览器安全的 `@xrkseek/xrk-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.md)。
+# @xrkseek/xrk-workflow
+
+[English](README.md) | 中文
+
+工作流 seam（扩展点，`ctx.workflowEngine`）执行由模型编写、可扇出 subagent 的编排脚本。该 seam 定义脚本、运行、结果、错误和事件契约；引擎负责决定如何隔离并执行脚本。
+
+`@xrkseek/xrk-workflow` 提供抽象 {@link WorkflowEngine} seam **以及**
+{@link InProcessWorkflowEngine}（AsyncFunction Provider）与
+{@link IsolatingWorkflowEngine}（worker_threads 脚本体隔离；可选
+`createAgent` 经 parentPort RPC 回桥，返回值须可 structuredClone；无桥时
+`agent()` 仍为 null；可选 {@link WorkflowToolBridge} 提供
+`await tools.name(args)`，与 Code Mode 同形）。完整沙箱 Node PTC 进程隔离
+**未声称**。产品 Host 默认挂载 Isolating（`hostPublic.workflowEngine`，Face
+`session.create` / `prompt` / drain 作 createAgent 回桥，站立工具表作
+tools.*）。Cordis 组合另挂 `tool-workflow` 后，模型面 `workflow` 工具才可见。
+产品 Face boot 用 Face 原生 **`ralph`** 工具做新鲜子代理迭代。
+
+`@xrkseek/xrk-tool-workflow` 是面向模型的 Cordis 消费方。
+
+包根是 Host face。浏览器安全的 `@xrkseek/xrk-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.md)。