@hydraharness/harness-subagent-fork-in-process 0.1.1-rc.6

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.md

@@ -0,0 +1,59 @@
+# @hydraharness/harness-subagent-fork-in-process
+
+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 [`@hydraharness/harness-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 `@hydraharness/harness-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/lib/index.js

@@ -0,0 +1,59 @@
+import z from "@hydraharness/schemastery";
+import { startInProcessRun } from "@hydraharness/harness-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 @hydraharness/harness-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 `@hydraharness/harness-subagent-fork-in-process`.
+* @module @hydraharness/harness-subagent-fork-in-process/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-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 @hydraharness/harness-subagent-fork-in-process
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/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 `@hydraharness/harness-subagent-fork-in-process`.
+ * @module @hydraharness/harness-subagent-fork-in-process/invariant
+ */
+import type { Context } from '@hydraharness/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,63 @@
+{
+  "name": "@hydraharness/harness-subagent-fork-in-process",
+  "description": "In-process fork subagent backend: runs a child agent seeded with a prefix of the parent's log",
+  "hydra": {
+    "plugin": {
+      "application": "Start a child agent with a copy of the parent conversation up to the fork point."
+    }
+  },
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-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": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/harness-subagent-in-process-driver": "^0.1.1-rc.6",
+    "@hydraharness/harness-subagent": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent-loop": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent-loop-testkit": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/harness-subagent-in-process-driver": "^0.1.1-rc.6",
+    "@hydraharness/harness-subagent-spawn-in-process": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-subagent": "^0.1.1-rc.6"
+  }
+}