@deepseek-ai/dsh-subagent-fork-in-process 0.0.1-rc.3

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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/subagent/subagent-fork-in-process/README.md
+README.md: 74c27ff10c76aa711ed3e954e806c00a27aacfa5
+README.zh.md: bca890769bab1f898abd0b71fc8aa321b66e93c8

package/README.md

@@ -0,0 +1,61 @@
+# @deepseek-ai/dsh-subagent-fork-in-process
+
+English | [中文](README.zh.md)
+
+The fork provider creates an in-process child seeded with the parent's completed conversation turns. It shares all run mechanics with spawn; the session seed is the only behavioral difference.
+
+## Seed boundary
+
+The parent's current tool-calling turn is still open when a subagent starts: its log contains the assistant tool call but not the matching tool result or `turn/end`. Copying that raw log would give the child an invalid, unbalanced session.
+
+Fork therefore computes the contiguous prefix ending at the last `turn/end`. The child sees all completed parent turns and none of the in-flight turn. If the parent has not completed a turn yet, the seed is empty and the child behaves like a fresh spawn.
+
+The seed transfers conversation history only. The child still receives a fresh flat registration scope; it does not inherit the parent's tool restrictions or authority.
+
+## Start and capabilities
+
+`start(request)` passes the completed-turn seed to [`startInProcessRun`](../subagent-in-process-driver/README.md) and awaits child publication. The shared driver owns cancellation, depth, customization, result reading, and disposal.
+
+Fork advertises `{ outputSchema: true, depthLimit: true, toolFilter: true, persona: true }`, identical to spawn.
+
+## Config
+
+| Key | Meaning |
+|---|---|
+| `providerName` | Registry name on `ctx.subagents` (default `fork`). |
+See [`dsh-subagent-spawn-in-process`](../subagent-spawn-in-process/README.md) for the run lifecycle, model inheritance, and depth tracking — all shared.
+
+## Model Experience
+
+### Child-agent history and envelope
+
+#### What the model sees
+
+The child receives the parent's balanced completed-turn surface prefix, then the new task content verbatim. A configured persona shadows prompt text in the child's fresh scope; a tool restriction filters its global wire schemas, executable lookup, and Code Mode SDK bindings but not standalone guidance. The parent's tool view and authority are not inherited. An optional structured-output request adds its child-only contract. The parent's current in-flight turn is excluded.
+
+#### Token effect
+
+Forking duplicates retained completed history into separate child requests; the child then accumulates its own tokens independently. Persona changes repeated prompt cost, filtering changes schema or generated SDK cost, and a first-turn fork has no inherited history.
+
+#### KV Cache effect
+
+The child may reuse the inherited byte-identical prefix under the same provider and model. Persona, tool-filter, generated-SDK, or route changes may invalidate reuse before inherited history; later child history is append-only. Shipped compositions therefore bind this provider to `backgroundMode: one-shot`, because a continuable child additionally carries the child-scoped `report` tool and its prompt section — deltas that precede the inherited history and so invalidate all of it ([the fork-one-shot Agent Note](../../../.agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.md)).
+
+### Parent tool result, indirectly
+
+#### What the model sees
+
+The parent receives only the child's own final output through `dsh-tool-subagent`, not the inherited prefix or intermediate work.
+
+#### Token effect
+
+Parent input grows by one data-dependent final result retained until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **The seed is a one-time snapshot** — the child sees the parent's completed turns as of the fork and nothing the parent logs afterwards; there is no live context sharing.
+- **No shipped composition creates a continuable fork child** — `prepareContinuable` remains implemented and the seam accepts it, but every shipped `cordis.yml` sets `backgroundMode: one-shot` on the fork delegation tool, so the provider's continuable path has no production caller. Reopening it requires the child's system prompt and tool schemas to match the parent's byte for byte, which the [`report` return channel](../tool-subagent-report/README.md) currently prevents. Rationale and the reintroduction condition: [the fork-one-shot Agent Note](../../../.agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.md).

package/README.zh.md

@@ -0,0 +1,61 @@
+# @deepseek-ai/dsh-subagent-fork-in-process
+
+[English](README.md) | 中文
+
+fork 提供方会创建一个进程内子 agent（智能体），并以父 agent 已完成的对话轮次作为初始内容。它与 spawn 共用全部运行机制；唯一的行为差异是会话初始内容。
+
+## 初始内容边界
+
+subagent 启动时，父 agent 当前的工具调用轮次仍未结束：其日志包含 assistant 工具调用，但尚无匹配的工具结果或 `turn/end`。直接复制这份原始日志会给子 agent 一个无效且不平衡的会话。
+
+因此，fork 会计算截至最后一个 `turn/end` 的连续前缀。子 agent 能看到父 agent 所有已完成轮次，但看不到进行中的轮次。如果父 agent 尚未完成任何轮次，初始内容为空，子 agent 的行为与全新 spawn 相同。
+
+初始内容只传递对话历史。子 agent 仍会获得全新的扁平注册作用域；它不继承父 agent 的工具限制或权限。
+
+## 启动与能力
+
+`start(request)` 将已完成轮次的初始内容传给 [`startInProcessRun`](../subagent-in-process-driver/README.md)，并等待子 agent 发布。共享驱动器负责取消、深度、定制、结果读取和 dispose（资源释放）。
+
+fork 声明 `{ outputSchema: true, depthLimit: true, toolFilter: true, persona: true }`，与 spawn 相同。
+
+## 配置
+
+| 键 | 含义 |
+|---|---|
+| `providerName` | `ctx.subagents` 上的注册表名称（默认 `fork`）。 |
+运行生命周期、模型继承与深度跟踪均为共享行为，见 [`dsh-subagent-spawn-in-process`](../subagent-spawn-in-process/README.md)。
+
+## 模型体验
+
+### 子 agent 历史与包络
+
+#### 模型看到的内容
+
+子 agent 先接收由父 agent 已配平的已完成轮次构成的表层前缀，再逐字接收新的任务内容。配置的 persona 会在子 agent 的全新作用域中遮蔽提示词文本；工具限制会过滤其全局协议 schema、可执行工具查找和 Code Mode SDK 绑定，但不影响独立的指导内容。父 agent 的工具视图与权限不会被继承。可选的结构化输出请求会添加仅属于子 agent 的约定。父 agent 当前进行中的轮次会被排除。
+
+#### Token 影响
+
+fork 会把保留的已完成历史复制到独立的子 agent 请求中；随后子 agent 独立累积自己的 token。persona 会改变重复提示词的成本，过滤会改变 schema 或生成 SDK 的成本，而首轮 fork 没有继承历史。
+
+#### KV Cache 影响
+
+在提供方和模型相同的前提下，子 agent 可以复用继承的逐字节相同前缀。persona、工具过滤、生成 SDK 或路由变化可能在继承历史之前使复用失效；后续子 agent 历史仅追加。因此随附组合把本提供方绑定为 `backgroundMode: one-shot`：可继续子 agent 还会额外携带作用域局部的 `report` 工具及其提示词 section，而这些增量位于继承历史之前，会使继承历史整体失效（见 [fork 保持 one-shot 的 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.md)）。
+
+### 父 agent 工具结果（间接）
+
+#### 模型看到的内容
+
+父 agent 只通过 `dsh-tool-subagent` 接收子 agent 自身的最终输出，不接收继承的前缀或中间工作。
+
+#### Token 影响
+
+父 agent 输入会增加一个取决于数据的最终结果，并保留到压缩（compaction）为止。
+
+#### KV Cache 影响
+
+仅追加；新增可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **初始内容是一次性快照**：子 agent 只能看到 fork 时父 agent 已完成的轮次，看不到父 agent 此后记录的任何内容；不会实时共享上下文。
+- **没有任何随附组合会创建可继续的 fork 子 agent**：`prepareContinuable` 仍然实现完好，seam 也接受它，但每份随附的 `cordis.yml` 都在 fork 委派工具上设置 `backgroundMode: one-shot`，因此该提供方的可继续路径没有生产调用方。重新开放它需要子 agent 的系统提示词与工具 schema 与父 agent 逐字节一致，而这一点目前被 [`report` 返回通道](../tool-subagent-report/README.md)阻止。理由与重新开放条件见 [fork 保持 one-shot 的 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-10-fork-children-stay-one-shot.md)。

package/lib/index.js

@@ -0,0 +1,59 @@
+import z from "@deepseek-ai/schemastery";
+import { startInProcessRun } from "@deepseek-ai/dsh-subagent-in-process-driver";
+//#region lib/types/index.js
+/**
+* The in-process FORK subagent backend: registers a {@link SubagentProvider} on
+* `ctx.subagents` that runs each child as a child {@link Agent} SEEDED with a prefix of the
+* parent's session log — so the child inherits the parent's conversation context instead of
+* starting fresh. The seed ends at the last `turn/end`: the current tool-call turn is
+* unbalanced and cannot be replayed as a valid child session.
+* @module @deepseek-ai/dsh-subagent-fork-in-process
+*/
+const name = "subagent-fork-in-process";
+const inject = ["subagents"];
+const Config = z.object({ providerName: z.string().default("fork") });
+/**
+* The balanced completed-turn prefix of `parent`'s log: every event up to and including the
+* last `turn/end`. The in-flight turn is excluded; before any completed turn the child starts
+* fresh. Because live sequence numbers equal array indexes, the result remains a valid seed
+* beginning at sequence zero.
+* @param parent - the agent whose session log to slice.
+* @returns the seed events, contiguous from seq 0; empty when no turn has completed.
+*/
+function completedTurnPrefix(parent) {
+	const events = parent.session.events;
+	const lastEnd = events.findLast((e) => e.type === "turn/end");
+	if (lastEnd === void 0) return [];
+	return events.slice(0, lastEnd.seq + 1);
+}
+/**
+* The fork provider. Supports `depthLimit` and `outputSchema` (via the shared
+* in-process structured runtime), plus `toolFilter`/`persona` (scoped
+* restrict() and a scoped shadowing persona section).
+*/
+var ForkInProcessProvider = class {
+	name;
+	capabilities = {
+		outputSchema: true,
+		depthLimit: true,
+		toolFilter: true,
+		persona: true
+	};
+	inheritsParentContext = true;
+	constructor(name) {
+		this.name = name;
+	}
+	start(request) {
+		const seed = completedTurnPrefix(request.parent);
+		return startInProcessRun(request, { ...seed.length > 0 ? { seed } : {} });
+	}
+	prepareContinuable(request) {
+		const seed = completedTurnPrefix(request.parent);
+		return Promise.resolve(seed.length > 0 ? { seed } : {});
+	}
+};
+function apply(ctx, config) {
+	ctx.subagents.registerProvider(new ForkInProcessProvider(config.providerName));
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-subagent-fork-in-process`.
+* @module @deepseek-ai/dsh-subagent-fork-in-process/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-subagent-fork-in-process";
+/** Cordis companion plugin name. */
+const name = "subagent-fork-in-process-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+const install = () => {};
+/**
+* Register this package's 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,20 @@
+/**
+ * The in-process FORK subagent backend: registers a {@link SubagentProvider} on
+ * `ctx.subagents` that runs each child as a child {@link Agent} SEEDED with a prefix of the
+ * parent's session log — so the child inherits the parent's conversation context instead of
+ * starting fresh. The seed ends at the last `turn/end`: the current tool-call turn is
+ * unbalanced and cannot be replayed as a valid child session.
+ * @module @deepseek-ai/dsh-subagent-fork-in-process
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "subagent-fork-in-process";
+export declare const inject: string[];
+/** Config: the registry name to register the provider under. */
+export interface Config {
+    /** Provider name on `ctx.subagents` (default `fork`). */
+    providerName: string;
+}
+export declare const Config: z<Config>;
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subagent-fork-in-process`.
+ * @module @deepseek-ai/dsh-subagent-fork-in-process/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "subagent-fork-in-process-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's 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/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@deepseek-ai/dsh-subagent-fork-in-process",
+  "description": "In-process fork subagent backend: runs a child agent seeded with a prefix of the parent's log",
+  "version": "0.0.1-rc.3",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/subagent/subagent-fork-in-process"
+  },
+  "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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-subagent": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-subagent-in-process-driver": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-agent-loop": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-subagent": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-subagent-in-process-driver": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-subagent-spawn-in-process": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}