@crewhaus/compaction-snip 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/compaction-snip",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pure middle-message removal with tool-use/result orphan defense",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.96.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/compaction-snip"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/compaction-snip#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,159 @@
+import { describe, expect, test } from "bun:test";
+import type Anthropic from "@anthropic-ai/sdk";
+import { snip } from "./index";
+
+function userMsg(text: string): Anthropic.MessageParam {
+  return { role: "user", content: text };
+}
+
+function asstMsg(text: string): Anthropic.MessageParam {
+  return { role: "assistant", content: text };
+}
+
+describe("snip", () => {
+  test("returns a copy unchanged when input fits in head+tail", () => {
+    const messages = [userMsg("a"), asstMsg("b"), userMsg("c")];
+    const out = snip(messages, 2, 2);
+    expect(out).toEqual(messages);
+    expect(out).not.toBe(messages); // copy, not the same reference
+  });
+
+  test("removes middle and inserts marker with correct N", () => {
+    const messages = [
+      userMsg("u1"),
+      asstMsg("a1"),
+      userMsg("u2"),
+      asstMsg("a2"),
+      userMsg("u3"),
+      asstMsg("a3"),
+    ];
+    // keepHead=2, keepTail=2 → drop 2 middle messages
+    const out = snip(messages, 2, 2);
+    expect(out.length).toBe(5);
+    expect(out[0]).toEqual(userMsg("u1"));
+    expect(out[1]).toEqual(asstMsg("a1"));
+    expect(out[2]).toEqual({
+      role: "assistant",
+      content: "[Context compacted: 2 messages removed]",
+    });
+    expect(out[3]).toEqual(userMsg("u3"));
+    expect(out[4]).toEqual(asstMsg("a3"));
+  });
+
+  test("marker text reports the correct N", () => {
+    const messages = Array.from({ length: 10 }, (_, i) => userMsg(`m${i}`));
+    const out = snip(messages, 1, 1);
+    // 10 - 1 - 1 = 8 removed
+    expect(out[1]).toEqual({
+      role: "assistant",
+      content: "[Context compacted: 8 messages removed]",
+    });
+    expect(out.length).toBe(3);
+  });
+
+  test("does not mutate the input array", () => {
+    const messages = [userMsg("a"), userMsg("b"), userMsg("c"), userMsg("d")];
+    const len = messages.length;
+    snip(messages, 1, 1);
+    expect(messages.length).toBe(len);
+  });
+
+  test("rejects negative keepHead/keepTail", () => {
+    expect(() => snip([], -1, 1)).toThrow(RangeError);
+    expect(() => snip([], 1, -1)).toThrow(RangeError);
+  });
+
+  test("orphan defense: pulls tailStart back to keep tool_use's result", () => {
+    // u(0), a:tool_use tu_1 (1), u:tool_result tu_1 (2), a(3), u(4), a(5), u(6), a(7)
+    // Naive snip with keepHead=2, keepTail=2 cuts [2..6), orphaning tu_1's result at index 2.
+    const messages: Anthropic.MessageParam[] = [
+      userMsg("u0"),
+      {
+        role: "assistant",
+        content: [{ type: "tool_use", id: "tu_1", name: "Bash", input: { cmd: "ls" } }],
+      },
+      {
+        role: "user",
+        content: [{ type: "tool_result", tool_use_id: "tu_1", content: "ok" }],
+      },
+      asstMsg("a3"),
+      userMsg("u4"),
+      asstMsg("a5"),
+      userMsg("u6"),
+      asstMsg("a7"),
+    ];
+
+    const out = snip(messages, 2, 2);
+    // Boundary should pull back so tool_result for tu_1 (index 2) is kept inside head.
+    // After adjustment headEnd should be at least 3, tailStart at least 6.
+    // Result must contain the tool_use at index 1 AND its matching tool_result at index 2.
+    const flat = out.flatMap((m) => (typeof m.content === "string" ? [] : m.content));
+    const hasUse = flat.some((b) => b.type === "tool_use" && b.id === "tu_1");
+    const hasResult = flat.some((b) => b.type === "tool_result" && b.tool_use_id === "tu_1");
+    expect(hasUse).toBe(true);
+    expect(hasResult).toBe(true);
+  });
+
+  test("orphan defense: pulls headEnd forward to keep tool_result's use", () => {
+    // u(0), a(1), u(2), a:tool_use tu_2 (3), u:tool_result tu_2 (4), a(5)
+    // Naive snip with keepHead=2, keepTail=2 cuts [2..4), losing tu_2's tool_use.
+    const messages: Anthropic.MessageParam[] = [
+      userMsg("u0"),
+      asstMsg("a1"),
+      userMsg("u2"),
+      {
+        role: "assistant",
+        content: [{ type: "tool_use", id: "tu_2", name: "Read", input: { path: "/x" } }],
+      },
+      {
+        role: "user",
+        content: [{ type: "tool_result", tool_use_id: "tu_2", content: "file content" }],
+      },
+      asstMsg("a5"),
+    ];
+
+    const out = snip(messages, 2, 2);
+    const flat = out.flatMap((m) => (typeof m.content === "string" ? [] : m.content));
+    const hasUse = flat.some((b) => b.type === "tool_use" && b.id === "tu_2");
+    const hasResult = flat.some((b) => b.type === "tool_result" && b.tool_use_id === "tu_2");
+    expect(hasUse).toBe(true);
+    expect(hasResult).toBe(true);
+  });
+
+  test("orphan defense can collapse to no-op when adjustments meet", () => {
+    // Conversation entirely composed of tool pairs that all reference each other —
+    // the boundary should walk to either end and nothing gets snipped.
+    const messages: Anthropic.MessageParam[] = [
+      {
+        role: "assistant",
+        content: [{ type: "tool_use", id: "tu_A", name: "X", input: {} }],
+      },
+      {
+        role: "user",
+        content: [{ type: "tool_result", tool_use_id: "tu_A", content: "x" }],
+      },
+      {
+        role: "assistant",
+        content: [{ type: "tool_use", id: "tu_B", name: "Y", input: {} }],
+      },
+      {
+        role: "user",
+        content: [{ type: "tool_result", tool_use_id: "tu_B", content: "y" }],
+      },
+    ];
+    // keepHead=1, keepTail=1 would cut 2 middle, but both halves orphan their counterparts.
+    const out = snip(messages, 1, 1);
+    // After defense, the snip should either produce a valid pair-preserving result or
+    // collapse to the original. Either way, every tool_result has a matching tool_use.
+    const flat = out.flatMap((m) => (typeof m.content === "string" ? [] : m.content));
+    const useIds = new Set(
+      flat.filter((b) => b.type === "tool_use").map((b) => (b as { id: string }).id),
+    );
+    const resultIds = flat
+      .filter((b) => b.type === "tool_result")
+      .map((b) => (b as { tool_use_id: string }).tool_use_id);
+    for (const id of resultIds) {
+      expect(useIds.has(id)).toBe(true);
+    }
+  });
+});

package/src/index.ts

@@ -0,0 +1,147 @@
+/**
+ * Catalog R6 `compaction-snip` — pure transformation that drops middle
+ * messages and inserts a one-line marker at the snip point. No model
+ * call. The Anthropic API rejects a tool_result whose tool_use_id has
+ * no matching tool_use earlier in the array, so the snip boundary is
+ * widened when the naive cut would orphan a pair.
+ *
+ * Reference: claude-code/services/compact/snipCompact.ts
+ */
+import type Anthropic from "@anthropic-ai/sdk";
+
+const MARKER_PREFIX = "[Context compacted: ";
+const MARKER_SUFFIX = " messages removed]";
+
+/**
+ * Keep the first `keepHead` and last `keepTail` messages, replace
+ * everything in between with one assistant marker. Returns a copy
+ * (does not mutate the input).
+ *
+ * If the requested boundary would split a tool_use/tool_result pair,
+ * the head boundary advances forward and the tail boundary retreats
+ * backward until both halves are self-contained. Worst case the input
+ * is returned unchanged.
+ */
+export function snip(
+  messages: ReadonlyArray<Anthropic.MessageParam>,
+  keepHead: number,
+  keepTail: number,
+): Anthropic.MessageParam[] {
+  if (keepHead < 0 || keepTail < 0) {
+    throw new RangeError(`keepHead/keepTail must be >= 0 (got ${keepHead}, ${keepTail})`);
+  }
+  const total = messages.length;
+  if (total <= keepHead + keepTail) {
+    return [...messages];
+  }
+
+  // Naive cut: keep [0, headEnd), drop [headEnd, tailStart), keep [tailStart, total).
+  let headEnd = keepHead;
+  let tailStart = total - keepTail;
+
+  // Defend against orphaning: ensure no tool_result in the kept tail
+  // references a tool_use that was dropped, and no tool_use in the
+  // kept head has its tool_result inside the dropped middle.
+  const adjusted = adjustForToolPairing(messages, headEnd, tailStart);
+  headEnd = adjusted.headEnd;
+  tailStart = adjusted.tailStart;
+
+  if (headEnd >= tailStart) {
+    // Adjustment collapsed the snip — nothing to remove.
+    return [...messages];
+  }
+
+  const removed = tailStart - headEnd;
+  const marker: Anthropic.MessageParam = {
+    role: "assistant",
+    content: `${MARKER_PREFIX}${removed}${MARKER_SUFFIX}`,
+  };
+  return [...messages.slice(0, headEnd), marker, ...messages.slice(tailStart)];
+}
+
+function adjustForToolPairing(
+  messages: ReadonlyArray<Anthropic.MessageParam>,
+  initialHeadEnd: number,
+  initialTailStart: number,
+): { headEnd: number; tailStart: number } {
+  let headEnd = initialHeadEnd;
+  let tailStart = initialTailStart;
+
+  // Iterate until both boundaries stop moving. Each pass either pulls
+  // a stranded tool_use/tool_result back into the kept range or stops.
+  for (let i = 0; i < messages.length; i++) {
+    const headIds = collectToolUseIds(messages.slice(0, headEnd));
+    const tailIds = collectToolResultIds(messages.slice(tailStart));
+
+    // tool_use in head whose tool_result lives in dropped middle —
+    // pull tailStart back so the result is preserved.
+    let moved = false;
+    for (const id of headIds) {
+      const resultIdx = findToolResultIndex(messages, id);
+      if (resultIdx >= 0 && resultIdx >= headEnd && resultIdx < tailStart) {
+        // Pull the boundary back to include up through resultIdx.
+        tailStart = resultIdx;
+        moved = true;
+      }
+    }
+
+    // tool_result in tail whose tool_use lives in dropped middle —
+    // pull headEnd forward so the use is preserved.
+    for (const id of tailIds) {
+      const useIdx = findToolUseIndex(messages, id);
+      if (useIdx >= 0 && useIdx >= headEnd && useIdx < tailStart) {
+        headEnd = useIdx + 1;
+        moved = true;
+      }
+    }
+
+    if (!moved) break;
+    if (headEnd >= tailStart) break;
+  }
+
+  return { headEnd, tailStart };
+}
+
+function collectToolUseIds(messages: ReadonlyArray<Anthropic.MessageParam>): string[] {
+  const ids: string[] = [];
+  for (const msg of messages) {
+    if (typeof msg.content === "string") continue;
+    for (const block of msg.content) {
+      if (block.type === "tool_use") ids.push(block.id);
+    }
+  }
+  return ids;
+}
+
+function collectToolResultIds(messages: ReadonlyArray<Anthropic.MessageParam>): string[] {
+  const ids: string[] = [];
+  for (const msg of messages) {
+    if (typeof msg.content === "string") continue;
+    for (const block of msg.content) {
+      if (block.type === "tool_result") ids.push(block.tool_use_id);
+    }
+  }
+  return ids;
+}
+
+function findToolUseIndex(messages: ReadonlyArray<Anthropic.MessageParam>, id: string): number {
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (!m || typeof m.content === "string") continue;
+    for (const block of m.content) {
+      if (block.type === "tool_use" && block.id === id) return i;
+    }
+  }
+  return -1;
+}
+
+function findToolResultIndex(messages: ReadonlyArray<Anthropic.MessageParam>, id: string): number {
+  for (let i = 0; i < messages.length; i++) {
+    const m = messages[i];
+    if (!m || typeof m.content === "string") continue;
+    for (const block of m.content) {
+      if (block.type === "tool_result" && block.tool_use_id === id) return i;
+    }
+  }
+  return -1;
+}