@crewhaus/tool-result-store 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@crewhaus/tool-result-store",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Persist large tool results to disk and return a preview the model can re-read",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/tool-catalog": "0.0.0",
+    "@crewhaus/tool-executor": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-result-store"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-result-store#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,183 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ToolResult } from "@crewhaus/tool-executor";
+import {
+  DEFAULT_PREVIEW_LINES,
+  DEFAULT_THRESHOLD_BYTES,
+  resolveStoragePath,
+  storeAndPreview,
+} from "./index";
+
+const TMP_ROOTS: string[] = [];
+function newTempRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "crewhaus-result-store-"));
+  TMP_ROOTS.push(dir);
+  return dir;
+}
+afterAll(() => {
+  for (const dir of TMP_ROOTS) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function makeResult(content: string, isError = false): ToolResult {
+  return { toolUseId: "tu_X", content, isError };
+}
+
+describe("storeAndPreview — under threshold", () => {
+  test("small content is returned verbatim, no file written", async () => {
+    const rootDir = newTempRoot();
+    const out = await storeAndPreview(makeResult("tiny output"), {
+      runId: "run_a",
+      toolUseId: "tu_1",
+      rootDir,
+    });
+    expect(out.persisted).toBe(false);
+    expect(out.fullPath).toBeNull();
+    expect(out.previewContent).toBe("tiny output");
+  });
+
+  test("exactly at threshold is still treated as small", async () => {
+    const rootDir = newTempRoot();
+    const content = "a".repeat(DEFAULT_THRESHOLD_BYTES);
+    const out = await storeAndPreview(makeResult(content), {
+      runId: "run_a",
+      toolUseId: "tu_1",
+      rootDir,
+    });
+    expect(out.persisted).toBe(false);
+    expect(out.fullPath).toBeNull();
+    expect(out.previewContent).toBe(content);
+  });
+});
+
+describe("storeAndPreview — over threshold", () => {
+  test("large content is persisted; preview shows first N lines + marker", async () => {
+    const rootDir = newTempRoot();
+    const lines = Array.from({ length: 250 }, (_, i) => `line ${i + 1}`);
+    const content = lines.join("\n");
+    // pad past the byte threshold so the persistence path fires
+    const padded = `${content}\n${"x".repeat(DEFAULT_THRESHOLD_BYTES)}`;
+    expect(Buffer.byteLength(padded, "utf8")).toBeGreaterThan(DEFAULT_THRESHOLD_BYTES);
+    const out = await storeAndPreview(makeResult(padded), {
+      runId: "run_b",
+      toolUseId: "tu_2",
+      rootDir,
+    });
+    expect(out.persisted).toBe(true);
+    expect(out.fullPath).not.toBeNull();
+    if (out.fullPath === null) throw new Error("unreachable");
+    expect(statSync(out.fullPath).size).toBe(Buffer.byteLength(padded, "utf8"));
+
+    // Preview = first DEFAULT_PREVIEW_LINES lines + truncation marker.
+    if (typeof out.previewContent !== "string") throw new Error("expected string preview");
+    const previewLines = out.previewContent.split("\n");
+    // last line should be the marker, the line before that may be partial.
+    expect(previewLines[previewLines.length - 1]).toContain("[truncated, full output at ");
+    expect(previewLines[previewLines.length - 1]).toContain(out.fullPath);
+    expect(previewLines.length).toBe(DEFAULT_PREVIEW_LINES + 1);
+    // First preview line should be the very first line of input.
+    expect(previewLines[0]).toBe("line 1");
+  });
+
+  test("custom previewLines, thresholdBytes, rootDir overrides honored", async () => {
+    const rootDir = newTempRoot();
+    const content = "line a\nline b\nline c\nline d\nline e\nline f";
+    const out = await storeAndPreview(makeResult(content), {
+      runId: "run_c",
+      toolUseId: "tu_3",
+      rootDir,
+      thresholdBytes: 5,
+      previewLines: 2,
+    });
+    expect(out.persisted).toBe(true);
+    expect(out.previewContent).toContain("line a\nline b\n[truncated, full output at ");
+    expect(out.fullPath).toContain(rootDir);
+  });
+
+  test("idempotent on retry — second call with same ids returns same path without throwing", async () => {
+    const rootDir = newTempRoot();
+    const content = "x".repeat(DEFAULT_THRESHOLD_BYTES + 10);
+    const first = await storeAndPreview(makeResult(content), {
+      runId: "run_d",
+      toolUseId: "tu_4",
+      rootDir,
+    });
+    const second = await storeAndPreview(makeResult(content), {
+      runId: "run_d",
+      toolUseId: "tu_4",
+      rootDir,
+    });
+    expect(first.fullPath).toBe(second.fullPath);
+    if (first.fullPath === null) throw new Error("unreachable");
+    // File still exists and has the original content.
+    expect(readFileSync(first.fullPath, "utf8")).toBe(content);
+  });
+
+  test("multi-byte UTF-8 byte length, not character length, drives the threshold", async () => {
+    const rootDir = newTempRoot();
+    // 5000 emoji × 4 bytes each = 20_000 bytes (over threshold) but only 5000 chars.
+    const content = "🌟".repeat(5000);
+    expect(content.length).toBe(10000); // emoji is 2 surrogate code units in JS
+    expect(Buffer.byteLength(content, "utf8")).toBeGreaterThan(DEFAULT_THRESHOLD_BYTES);
+    const out = await storeAndPreview(makeResult(content), {
+      runId: "run_e",
+      toolUseId: "tu_5",
+      rootDir,
+    });
+    expect(out.persisted).toBe(true);
+  });
+
+  test("error results (isError: true) also get persisted when large", async () => {
+    const rootDir = newTempRoot();
+    const stack = `Error: boom\n${"    at foo\n".repeat(5000)}`;
+    const out = await storeAndPreview(makeResult(stack, true), {
+      runId: "run_f",
+      toolUseId: "tu_6",
+      rootDir,
+    });
+    expect(out.persisted).toBe(true);
+    expect(out.fullPath).toContain(`${rootDir}/run_f/tu_6.txt`);
+  });
+});
+
+describe("storeAndPreview — path traversal guard", () => {
+  test("runId with .. is rejected", async () => {
+    const rootDir = newTempRoot();
+    const big = "x".repeat(DEFAULT_THRESHOLD_BYTES + 10);
+    await expect(
+      storeAndPreview(makeResult(big), {
+        runId: "../escape",
+        toolUseId: "tu_7",
+        rootDir,
+      }),
+    ).rejects.toThrow(/runId/);
+  });
+
+  test("toolUseId with slash is rejected", async () => {
+    const rootDir = newTempRoot();
+    const big = "x".repeat(DEFAULT_THRESHOLD_BYTES + 10);
+    await expect(
+      storeAndPreview(makeResult(big), {
+        runId: "ok",
+        toolUseId: "etc/passwd",
+        rootDir,
+      }),
+    ).rejects.toThrow(/toolUseId/);
+  });
+
+  test("empty runId is rejected", async () => {
+    const rootDir = newTempRoot();
+    const big = "x".repeat(DEFAULT_THRESHOLD_BYTES + 10);
+    await expect(
+      storeAndPreview(makeResult(big), { runId: "", toolUseId: "tu", rootDir }),
+    ).rejects.toThrow(/runId/);
+  });
+
+  test("resolveStoragePath returns a path under rootDir", () => {
+    const path = resolveStoragePath("run_x", "tu_y", "/tmp/cr-test");
+    expect(path).toContain("/tmp/cr-test/run_x/tu_y.txt");
+  });
+});

package/src/index.ts

@@ -0,0 +1,134 @@
+/**
+ * Catalog R3 `tool-result-store` — persist large tool outputs to disk
+ * and return a preview the model can re-read via the `Read` tool. This
+ * keeps wide messages out of the conversation context (cheaper, faster)
+ * while preserving full output for any later look-up.
+ *
+ * Default policy:
+ *   - Threshold: 10240 bytes (10 KB) of UTF-8.
+ *   - Storage path: `<rootDir>/<runId>/<toolUseId>.txt`
+ *     (rootDir defaults to `.crewhaus/tool-results` under cwd).
+ *   - Preview: first 100 lines + `[truncated, full output at <fullPath>]`
+ *
+ * Idempotent writes: the file is created with `flag: "wx"` (write-
+ * exclusive). If a previous run already wrote the same `(runId,
+ * toolUseId)` pair we treat that as success and reuse the existing file.
+ *
+ * Path traversal: `runId` and `toolUseId` are joined under `rootDir`
+ * after rejecting any value containing path separators or `..` to
+ * prevent a tool-result from escaping its run directory.
+ *
+ * Reference: `claude-code/utils/toolResultStorage.ts` — uses
+ * `<persisted-output>` XML wrappers, a per-tool size budget, and a
+ * GrowthBook flag to override per tool. We collapse to a single global
+ * threshold and a plain-text marker.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve, sep } from "node:path";
+import { RuntimeError } from "@crewhaus/errors";
+import type { ToolExecuteResult } from "@crewhaus/tool-catalog";
+import type { ToolResult } from "@crewhaus/tool-executor";
+
+export type StoreOptions = {
+  readonly runId: string;
+  readonly toolUseId: string;
+  readonly thresholdBytes?: number;
+  readonly previewLines?: number;
+  readonly rootDir?: string;
+};
+
+export type StoredResult = {
+  readonly previewContent: ToolExecuteResult;
+  readonly fullPath: string | null;
+  readonly persisted: boolean;
+};
+
+export const DEFAULT_THRESHOLD_BYTES = 10240;
+export const DEFAULT_PREVIEW_LINES = 100;
+export const DEFAULT_ROOT_DIR = ".crewhaus/tool-results";
+
+/**
+ * If `result.content` is at or under threshold, return it unchanged.
+ * Otherwise persist the full text under `<rootDir>/<runId>/<toolUseId>.txt`
+ * and return `{ previewContent, fullPath, persisted: true }`. Errors
+ * (`isError: true`) follow the same path so large stack traces are
+ * captured.
+ */
+export async function storeAndPreview(
+  result: ToolResult,
+  opts: StoreOptions,
+): Promise<StoredResult> {
+  const thresholdBytes = opts.thresholdBytes ?? DEFAULT_THRESHOLD_BYTES;
+  const previewLines = opts.previewLines ?? DEFAULT_PREVIEW_LINES;
+  const rootDir = opts.rootDir ?? DEFAULT_ROOT_DIR;
+
+  // Section 14 — non-string content (image content arrays) bypasses
+  // persistence entirely. The blocks are forwarded as-is to the model so
+  // it can see the image; size capping happens inside the producing tool
+  // (e.g. tool-image enforces a 5 MB per-image limit on disk).
+  if (typeof result.content !== "string") {
+    return { previewContent: result.content, fullPath: null, persisted: false };
+  }
+
+  const byteLength = Buffer.byteLength(result.content, "utf8");
+  if (byteLength <= thresholdBytes) {
+    return { previewContent: result.content, fullPath: null, persisted: false };
+  }
+
+  rejectUnsafeSegment("runId", opts.runId);
+  rejectUnsafeSegment("toolUseId", opts.toolUseId);
+
+  const fullPath = join(rootDir, opts.runId, `${opts.toolUseId}.txt`);
+  await mkdir(dirname(fullPath), { recursive: true });
+  try {
+    await writeFile(fullPath, result.content, { flag: "wx" });
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "EEXIST") throw err;
+    // Another run already persisted this exact (runId, toolUseId) — treat
+    // as success. The body is identical because tool_use_id is unique.
+  }
+
+  const lines = result.content.split("\n");
+  const head = lines.slice(0, previewLines).join("\n");
+  const previewContent = `${head}\n[truncated, full output at ${fullPath}]`;
+
+  return { previewContent, fullPath, persisted: true };
+}
+
+function rejectUnsafeSegment(label: string, value: string): void {
+  if (
+    value === "" ||
+    value === "." ||
+    value === ".." ||
+    value.includes("/") ||
+    value.includes("\\") ||
+    value.includes("\0") ||
+    value.includes("..")
+  ) {
+    throw new RuntimeError(
+      `tool-result-store: ${label} "${value}" contains path-traversal characters`,
+    );
+  }
+}
+
+/**
+ * Used by tests to confirm the resolved storage location for a given
+ * runId/toolUseId pair. Performs the same traversal rejection as
+ * `storeAndPreview()` so callers see the same errors.
+ */
+export function resolveStoragePath(
+  runId: string,
+  toolUseId: string,
+  rootDir: string = DEFAULT_ROOT_DIR,
+): string {
+  rejectUnsafeSegment("runId", runId);
+  rejectUnsafeSegment("toolUseId", toolUseId);
+  const abs = resolve(rootDir, runId, `${toolUseId}.txt`);
+  // Sanity: the resolved path must still live under rootDir.
+  const root = resolve(rootDir);
+  if (!abs.startsWith(`${root}${sep}`)) {
+    throw new RuntimeError("tool-result-store: resolved path escapes rootDir");
+  }
+  return abs;
+}