@hydraharness/harness-spill-local 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,32 @@
+# @hydraharness/harness-spill-local
+
+The **local-filesystem** implementation of the [`@hydraharness/harness-spill`](../spill) storage seam. Registers as `ctx.spillStore` and persists a tool's oversized text to a private, session-scoped file; its locator is the file path and its retrieval hint tells the model to use `read` or `grep` on that path.
+
+## Storage layout
+
+Files land at `<root>/session-<hash>/​<random>-<safeName>`:
+
+- **`root`** — the config `root` (resolved to absolute), or a lazily-created private (0700) per-process directory under the OS temp dir when omitted. A predictable, world-readable root would let other local users read spilled tool output or plant symlinks.
+- **`session-<hash>`** — a short `sha256(sessionId)` prefix, so a session's spill files group together and a future cleanup can drop them per session.
+- **`<random>-<safeName>`** — an unpredictable hex prefix (defeats symlink planting in a shared root) plus the caller's `suggestedName` sanitized to one safe path segment (traversal-proof; mirrors the JSONL persistence backend's `encodeSegment`). The write is exclusive + owner-only (`open(path, 'wx', 0o600)`): it fails on any pre-existing path, symlink or not, so a planted target cannot redirect it.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `root` | private 0700 temp dir | Root directory for spill files. Set to keep them under a known location. |
+
+`saveText` rejects on a real storage failure (permissions, ENOSPC); the spill policy treats a rejection as best-effort and keeps the inline result. See the seam README for the vocabulary and the [tool output spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) for the design.
+
+## Model Experience
+
+Indirectly, through spill consumers that render the local path and `read`/`grep` retrieval guidance.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Local spill files persist until external cleanup** — the backend has no session-lifecycle deletion or age-based retention policy, because persisted, resumed, and forked sessions may still reference a path.
+- **Locators require a co-located filesystem consumer** — a remote or virtual deployment needs another `SpillStore` backend whose locator and retrieval hint are meaningful there.

package/lib/index.js

@@ -0,0 +1,138 @@
+import { join, resolve } from "node:path";
+import z from "@hydraharness/schemastery";
+import { SpillLocator, SpillStore } from "@hydraharness/harness-spill";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdtempSync } from "node:fs";
+import { mkdir, open } from "node:fs/promises";
+import { tmpdir } from "node:os";
+//#region lib/types/store.js
+/**
+* Cordis-free storage mechanics for the local spill backend: private
+* session-scoped directory selection, safe-name derivation, path-traversal
+* protection, and the exclusive owner-only write. Kept out of the service class
+* (like `@hydraharness/harness-bash-local`'s `run.ts`) so the filesystem behavior is unit-testable
+* without a `ctx` and without the OS temp dir.
+*
+* @module @hydraharness/harness-spill-local/store
+*/
+let defaultRoot;
+/**
+* The default spill root: a private (0700) per-process directory under the OS
+* tmpdir, created lazily. Predictable world-readable paths would let other
+* local users read spilled tool output or pre-create symlinks; `mkdtemp` gives
+* an unpredictable suffix and 0700 semantics.
+*
+* @returns The lazily-created private spill root.
+*/
+function privateRoot() {
+	defaultRoot ??= mkdtempSync(join(tmpdir(), "hydra-spill-"));
+	return defaultRoot;
+}
+/**
+* Encode an arbitrary string as one safe path segment, injectively over ALL JS
+* (UTF-16) strings. A session id / suggested name is untrusted input, so this
+* neutralizes `../`, absolute paths, NUL, and separators before any filesystem
+* use. Each code unit is kept literal (`[A-Za-z0-9._-]`, minus `~`) or escaped
+* as `~XXXX`; `~` is itself escaped, so the mapping is reversible and distinct
+* inputs never collide. The whole-segment tokens `.`/`..` are escaped so they
+* can never traverse. An empty string encodes to `~` (never an empty segment).
+* (Mirrors the JSONL persistence backend's `encodeSegment`.)
+*
+* @param raw The untrusted string to encode as one safe path segment.
+* @returns An injective, filesystem-safe single path segment.
+*/
+function encodeSegment(raw) {
+	if (raw.length === 0) return "~";
+	if (raw === ".") return "~002E";
+	if (raw === "..") return "~002E~002E";
+	let out = "";
+	for (let i = 0; i < raw.length; i++) {
+		const code = raw.charCodeAt(i);
+		const ch = String.fromCharCode(code);
+		if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) out += ch;
+		else out += "~" + code.toString(16).toUpperCase().padStart(4, "0");
+	}
+	return out;
+}
+/**
+* The session-scoped directory: `<root>/session-<hash(sessionId)>`, a short stable hash.
+*
+* @param root The spill root directory.
+* @param sessionId The owning session id to hash into a stable directory name.
+* @returns The absolute session-scoped spill directory path.
+*/
+function sessionDir(root, sessionId) {
+	return join(root, `session-${createHash("sha256").update(sessionId).digest("hex").slice(0, 12)}`);
+}
+/**
+* Write `content` to a fresh file under the session-scoped directory and return
+* its path + byte length. The filename is a random hex prefix plus the
+* sanitized `suggestedName`, so it is unpredictable (defeats symlink planting in
+* a shared root) AND stays readable. The open is exclusive + owner-only
+* (`'wx', 0o600`): it fails on any existing path — symlink or not — so a
+* pre-planted target cannot redirect the write.
+*
+* @param options The resolved root and request fields required to save the file.
+* @returns The written file path and UTF-8 byte length.
+*/
+async function saveTextFile(options) {
+	const dir = sessionDir(options.root, options.sessionId);
+	await mkdir(dir, {
+		recursive: true,
+		mode: 448
+	});
+	const safeName = encodeSegment(options.suggestedName);
+	const path = join(dir, `${randomBytes(6).toString("hex")}-${safeName}`);
+	const bytes = Buffer.byteLength(options.content, "utf8");
+	const handle = await open(path, "wx", 384);
+	try {
+		await handle.writeFile(options.content);
+	} finally {
+		await handle.close();
+	}
+	return {
+		path,
+		bytes
+	};
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* `LocalSpillStore`: the host-filesystem implementation of the
+* `@hydraharness/harness-spill` storage seam. Persists a tool's oversized text to a
+* private, session-scoped file (see `./store.ts` for the traversal-safe naming
+* and exclusive owner-only write) and returns a path locator plus local
+* read/grep retrieval guidance.
+*
+* @module @hydraharness/harness-spill-local
+*/
+/**
+* Local-filesystem spill backend. Files land under `<root>/session-<hash>/…`
+* with unpredictable names, an exclusive owner-only (0600) write, and a private
+* (0700) root — a spilled tool result must not be readable by other local users
+* or redirectable via a planted symlink.
+*/
+var LocalSpillStore = class extends SpillStore {
+	static Config = z.object({ root: z.string() });
+	/** Resolved absolute spill root (config `root`, else the private default), fixed at construction. */
+	root;
+	constructor(ctx, config) {
+		super(ctx);
+		this.root = config.root !== void 0 ? resolve(config.root) : privateRoot();
+	}
+	async saveText(input) {
+		const saved = await saveTextFile({
+			root: this.root,
+			sessionId: input.owner.sessionId,
+			suggestedName: input.suggestedName,
+			content: input.content
+		});
+		return {
+			locator: SpillLocator(saved.path),
+			bytes: saved.bytes,
+			retrievalHint: "Use read with offset/limit, or grep this path to search within it."
+		};
+	}
+};
+//#endregion
+export { LocalSpillStore, LocalSpillStore as default, encodeSegment, privateRoot, saveTextFile, sessionDir };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-spill-local`.
+* @module @hydraharness/harness-spill-local/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-spill-local";
+/** Cordis companion plugin name. */
+const name = "spill-local-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,39 @@
+/**
+ * `LocalSpillStore`: the host-filesystem implementation of the
+ * `@hydraharness/harness-spill` storage seam. Persists a tool's oversized text to a
+ * private, session-scoped file (see `./store.ts` for the traversal-safe naming
+ * and exclusive owner-only write) and returns a path locator plus local
+ * read/grep retrieval guidance.
+ *
+ * @module @hydraharness/harness-spill-local
+ */
+import { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+import { SpillStore } from '@hydraharness/harness-spill';
+import type { SaveTextSpill, SpillRef } from '@hydraharness/harness-spill';
+export { encodeSegment, privateRoot, saveTextFile, sessionDir } from './store.ts';
+export type { SavedText, SaveTextOptions } from './store.ts';
+/** Plugin config (all optional — `static Config` supplies the defaults). */
+export interface Config {
+    /**
+     * Root directory for spill files. Omitted uses a lazily-created private
+     * (0700) per-process directory under the OS temp dir — the safe default for
+     * a local deployment. Set it to keep spill files under a known location.
+     */
+    root?: string;
+}
+/**
+ * Local-filesystem spill backend. Files land under `<root>/session-<hash>/…`
+ * with unpredictable names, an exclusive owner-only (0600) write, and a private
+ * (0700) root — a spilled tool result must not be readable by other local users
+ * or redirectable via a planted symlink.
+ */
+export declare class LocalSpillStore extends SpillStore {
+    static Config: z<Config>;
+    /** Resolved absolute spill root (config `root`, else the private default), fixed at construction. */
+    readonly root: string;
+    constructor(ctx: Context, config: Config);
+    saveText(input: SaveTextSpill): Promise<SpillRef>;
+}
+export default LocalSpillStore;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-spill-local`.
+ * @module @hydraharness/harness-spill-local/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "spill-local-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/lib/types/store.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Cordis-free storage mechanics for the local spill backend: private
+ * session-scoped directory selection, safe-name derivation, path-traversal
+ * protection, and the exclusive owner-only write. Kept out of the service class
+ * (like `@hydraharness/harness-bash-local`'s `run.ts`) so the filesystem behavior is unit-testable
+ * without a `ctx` and without the OS temp dir.
+ *
+ * @module @hydraharness/harness-spill-local/store
+ */
+/**
+ * The default spill root: a private (0700) per-process directory under the OS
+ * tmpdir, created lazily. Predictable world-readable paths would let other
+ * local users read spilled tool output or pre-create symlinks; `mkdtemp` gives
+ * an unpredictable suffix and 0700 semantics.
+ *
+ * @returns The lazily-created private spill root.
+ */
+export declare function privateRoot(): string;
+/**
+ * Encode an arbitrary string as one safe path segment, injectively over ALL JS
+ * (UTF-16) strings. A session id / suggested name is untrusted input, so this
+ * neutralizes `../`, absolute paths, NUL, and separators before any filesystem
+ * use. Each code unit is kept literal (`[A-Za-z0-9._-]`, minus `~`) or escaped
+ * as `~XXXX`; `~` is itself escaped, so the mapping is reversible and distinct
+ * inputs never collide. The whole-segment tokens `.`/`..` are escaped so they
+ * can never traverse. An empty string encodes to `~` (never an empty segment).
+ * (Mirrors the JSONL persistence backend's `encodeSegment`.)
+ *
+ * @param raw The untrusted string to encode as one safe path segment.
+ * @returns An injective, filesystem-safe single path segment.
+ */
+export declare function encodeSegment(raw: string): string;
+/**
+ * The session-scoped directory: `<root>/session-<hash(sessionId)>`, a short stable hash.
+ *
+ * @param root The spill root directory.
+ * @param sessionId The owning session id to hash into a stable directory name.
+ * @returns The absolute session-scoped spill directory path.
+ */
+export declare function sessionDir(root: string, sessionId: string): string;
+/** Options for {@link saveTextFile} — the resolved root and the request fields the store needs. */
+export interface SaveTextOptions {
+    /** The spill root directory (configured or the lazy private default). */
+    root: string;
+    /** The owning session id (scopes the directory). */
+    sessionId: string;
+    /** Caller-suggested base name; sanitized to one safe segment before use. */
+    suggestedName: string;
+    /** The full text to persist. */
+    content: string;
+}
+/** A written spill file. */
+export interface SavedText {
+    path: string;
+    bytes: number;
+}
+/**
+ * Write `content` to a fresh file under the session-scoped directory and return
+ * its path + byte length. The filename is a random hex prefix plus the
+ * sanitized `suggestedName`, so it is unpredictable (defeats symlink planting in
+ * a shared root) AND stays readable. The open is exclusive + owner-only
+ * (`'wx', 0o600`): it fails on any existing path — symlink or not — so a
+ * pre-planted target cannot redirect the write.
+ *
+ * @param options The resolved root and request fields required to save the file.
+ * @returns The written file path and UTF-8 byte length.
+ */
+export declare function saveTextFile(options: SaveTextOptions): Promise<SavedText>;
+//# sourceMappingURL=store.d.ts.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@hydraharness/harness-spill-local",
+  "description": "Local-filesystem implementation of the Hydra harness spill storage seam (private session-scoped files)",
+  "hydra": {
+    "plugin": {
+      "application": "Store large tool output privately on disk for later retrieval within the session."
+    }
+  },
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/spill/spill-local"
+  },
+  "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-invariants": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-spill": "^0.1.1-rc.6"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-brand": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-spill": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}