@bugabinga/pi-ext-ctx 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - 2026-05-21
+
+- a40a427 prepare extensions for npm release
+- 44eb82c feat(ctx): add context indexing extension
+

package/README.md

@@ -0,0 +1,15 @@
+# ctx
+
+Off-context execution and large-output search for Pi.
+
+Runs JS, Python, and shell analysis outside the main conversation and searches stored outputs.
+
+## Tools
+
+- `ctx`
+
+## Demo
+
+<!-- demo:tools_suite:start -->
+![Tools suite](assets/tools_suite.gif)
+<!-- demo:tools_suite:end -->

package/TODO.md

@@ -0,0 +1,5 @@
+# ctx TODO
+
+- Real-LLM behavior eval: does model choose `ctx` naturally vs `bash`/`read`?
+- Tune thresholds/snippets after actual use.
+- Replace git-pinned `@marcfargas/pi-test-harness` fork once upstream PR/package exists.

package/__tests__/ctx.test.ts

@@ -0,0 +1,152 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CtxStore, defaultDbPath, executeCtxOperation, handleBashToolResult, registerCtxExtension, type CtxToolParams } from "../index.js";
+
+let dir: string;
+let dbPath: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), "pi-ctx-test-"));
+  dbPath = join(dir, "ctx.db");
+  process.env.PI_CTX_DB_PATH = dbPath;
+});
+
+afterEach(() => {
+  delete process.env.PI_CTX_DB_PATH;
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("ctx DB path", () => {
+  test("defaults under current Pi session dir", () => {
+    delete process.env.PI_CTX_DB_PATH;
+    const sessionFile = join(dir, "sessions", "session.jsonl");
+    const path = defaultDbPath("/repo/project", {
+      sessionManager: { getSessionFile: () => sessionFile },
+    });
+    expect(path).toStartWith(join(dir, "sessions", "ctx"));
+    expect(path).toEndWith(".db");
+  });
+
+  test("uses SessionManager sessionDir when no session file exists", () => {
+    delete process.env.PI_CTX_DB_PATH;
+    const path = defaultDbPath("/repo/project", {
+      sessionManager: { getSessionDir: () => join(dir, "session-dir") },
+    });
+    expect(path).toStartWith(join(dir, "session-dir", "ctx"));
+    expect(path).toEndWith(".db");
+  });
+});
+
+describe("CtxStore", () => {
+  test("indexes and searches chunks", () => {
+    const store = new CtxStore(dbPath);
+    const indexed = store.indexText({ kind: "test", label: "sample", text: "alpha beta\npanic stack trace\nomega" });
+    expect(indexed.chunkCount).toBeGreaterThan(0);
+    const hits = store.search(["panic trace"], { limit: 3 });
+    expect(hits).toContain("panic stack trace");
+    store.close();
+  });
+
+  test("purges project DB content", () => {
+    const store = new CtxStore(dbPath);
+    store.indexText({ kind: "test", label: "sample", text: "alpha beta" });
+    expect(store.stats().sources).toBe(1);
+    store.purge();
+    expect(store.stats().sources).toBe(0);
+    store.close();
+  });
+});
+
+describe("ctx operations", () => {
+  test("run-js returns printed findings", async () => {
+    const store = new CtxStore(dbPath);
+    const result = await executeCtxOperation(store, {
+      op: "run-js",
+      code: "console.log('answer', 41 + 1)",
+    } satisfies CtxToolParams, dir);
+    expect(result.isError).toBeFalsy();
+    expect(result.content[0].text).toContain("answer 42");
+    store.close();
+  });
+
+  test("file-py reads file as text", async () => {
+    const file = join(dir, "data.txt");
+    writeFileSync(file, "one\ntwo\nthree\n", "utf8");
+    const store = new CtxStore(dbPath);
+    const result = await executeCtxOperation(store, {
+      op: "file-py",
+      path: file,
+      code: "print(len(text.splitlines()))",
+    } satisfies CtxToolParams, dir);
+    expect(result.content[0].text.trim()).toBe("3");
+    store.close();
+  });
+
+  test("large run output is indexed and returns pointer", async () => {
+    const store = new CtxStore(dbPath);
+    const result = await executeCtxOperation(store, {
+      op: "run-js",
+      code: "console.log('x'.repeat(110_000))",
+    } satisfies CtxToolParams, dir);
+    expect(result.content[0].text).toContain("ctx:stored");
+    expect(result.content[0].text).toContain("Use ctx search");
+    expect(store.stats().sources).toBe(1);
+    store.close();
+  });
+});
+
+describe("bash auto-collapse", () => {
+  test("uses fullOutputPath, stores raw, returns bounded replacement", () => {
+    const full = join(dir, "bash.log");
+    const raw = "CTX_RAW_SENTINEL ".repeat(10_000);
+    writeFileSync(full, raw, "utf8");
+    const store = new CtxStore(dbPath);
+    const patch = handleBashToolResult(store, {
+      toolName: "bash",
+      input: { command: "python noisy.py" },
+      content: [{ type: "text", text: "[truncated]" }],
+      details: { fullOutputPath: full, truncation: { truncated: true } },
+      isError: false,
+    });
+    expect(patch).toBeDefined();
+    const text = patch!.content[0].text;
+    expect(text).toContain("ctx:stored");
+    expect(text).not.toContain("CTX_RAW_SENTINEL");
+    expect(store.search(["CTX_RAW_SENTINEL"], { limit: 1 })).toContain("CTX_RAW_SENTINEL");
+    store.close();
+  });
+
+  test("large error output is searched for failures", () => {
+    const full = join(dir, "bash-error.log");
+    writeFileSync(full, `${"noise\n".repeat(1000)}panic: exploded\nstack trace here\n`, "utf8");
+    const store = new CtxStore(dbPath);
+    const patch = handleBashToolResult(store, {
+      toolName: "bash",
+      input: { command: "failing" },
+      content: [{ type: "text", text: "[truncated]" }],
+      details: { fullOutputPath: full },
+      isError: true,
+    });
+    expect(patch?.content[0].text).toContain("matched");
+    expect(patch?.content[0].text).toContain("panic");
+    store.close();
+  });
+});
+
+describe("extension registration", () => {
+  test("registers one tool and one command", () => {
+    const tools: any[] = [];
+    const commands: Record<string, any> = {};
+    const handlers: Record<string, Function[]> = {};
+    registerCtxExtension({
+      registerTool: (tool: any) => tools.push(tool),
+      registerCommand: (name: string, command: any) => { commands[name] = command; },
+      on: (name: string, handler: Function) => { (handlers[name] ??= []).push(handler); },
+    });
+    expect(tools.map(t => t.name)).toEqual(["ctx"]);
+    expect(Object.keys(commands)).toEqual(["ctx"]);
+    expect(Object.keys(handlers)).toContain("tool_result");
+  });
+});

package/__tests__/harness.test.ts

@@ -0,0 +1,296 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path, { join } from "node:path";
+import { createTestSession, type TestSession } from "@marcfargas/pi-test-harness";
+
+const CTX_COMMIT = "0cb5ce5f10fb18c9a80e904e2e3310cc98a28e29";
+
+let root: string;
+let sessionDir: string;
+let t: TestSession | undefined;
+
+function ctxPath(): string {
+  return path.resolve(import.meta.dir, "../index.ts");
+}
+
+function ctxTool() {
+  return t!.session.extensionRunner.getToolDefinition("ctx");
+}
+
+function ctxExec(params: Record<string, unknown>) {
+  return ctxTool().execute(
+    `call-${crypto.randomUUID()}`,
+    params,
+    undefined,
+    undefined,
+    t!.session.extensionRunner.createContext(),
+  );
+}
+
+function textOf(result: any): string {
+  return result.content.map((part: { text?: string }) => part.text ?? "").join("\n");
+}
+
+function dbFiles(): string[] {
+  const dir = join(sessionDir, "ctx");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((name) => name.endsWith(".db"));
+}
+
+beforeEach(async () => {
+  root = mkdtempSync(join(tmpdir(), "pi-ctx-harness-"));
+  sessionDir = join(root, "session");
+  process.env.PI_CODING_AGENT_SESSION_DIR = sessionDir;
+  delete process.env.PI_CTX_DB_PATH;
+  t = await createTestSession({ extensions: [ctxPath()] });
+});
+
+afterEach(() => {
+  t?.dispose();
+  t = undefined;
+  delete process.env.PI_CODING_AGENT_SESSION_DIR;
+  delete process.env.PI_CTX_DB_PATH;
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("ctx harness integration", () => {
+  it("loads from git pi-test-harness fork pinned to source-export commit", async () => {
+    const pkg = await import("@marcfargas/pi-test-harness");
+    expect(typeof pkg.createTestSession).toBe("function");
+    const lock = readFileSync(path.resolve(import.meta.dir, "../bun.lock"), "utf8");
+    expect(lock).toContain(CTX_COMMIT);
+  });
+
+  it("registers exactly one ctx tool and one ctx command", () => {
+    const [extension] = t!.session.extensionRunner.extensions;
+    expect([...extension.tools.keys()]).toEqual(["ctx"]);
+    expect([...extension.commands.keys()]).toEqual(["ctx"]);
+  });
+
+  it("runs JS off-context, stores oversized output, and retrieves exact needles later", async () => {
+    const result = await ctxExec({
+      op: "run-js",
+      query: "ctxneedle12345",
+      code: `
+        for (let i = 0; i < 9000; i++) console.log('noise line ' + i + ' ' + 'x'.repeat(20));
+        console.log('ctxneedle12345 fatal failure in generated report');
+        for (let i = 0; i < 9000; i++) console.log('tail noise ' + i + ' ' + 'y'.repeat(20));
+      `,
+    });
+
+    const text = textOf(result);
+    expect(text).toContain("ctx:stored");
+    expect(text).toContain("matched");
+    expect(text.length).toBeLessThan(2_000);
+    expect(text).not.toContain("tail noise 8999");
+    expect(dbFiles()).toHaveLength(1);
+
+    const search = await ctxExec({ op: "search", query: "ctxneedle12345", limit: 1 });
+    const searchText = textOf(search);
+    expect(searchText).toContain("ctxneedle12345 fatal failure");
+  });
+
+  it("analyzes a huge file without returning the file body or indexing small findings", async () => {
+    const file = join(root, "huge.log");
+    const lines = Array.from({ length: 25_000 }, (_, i) => `row ${i} boring payload ${"z".repeat(40)}`);
+    lines[19_876] = "ctxfilemarker67890 ERROR customer=42 shard=west";
+    writeFileSync(file, `${lines.join("\n")}\n`, "utf8");
+
+    const result = await ctxExec({
+      op: "file-js",
+      path: file,
+      code: `
+        const hit = text.split(/\\n/).find(line => line.includes('ctxfilemarker67890'));
+        console.log(hit);
+      `,
+    });
+
+    const out = textOf(result);
+    expect(out.trim()).toBe("ctxfilemarker67890 ERROR customer=42 shard=west");
+    expect(out).not.toContain("row 0 boring payload");
+    const [extension] = t!.session.extensionRunner.extensions;
+    const stats = await extension.commands.get("ctx").handler("", t!.session.extensionRunner.createContext());
+    expect(stats.text).toContain("ctx: 0 sources");
+  });
+
+  it("collapses huge bash tool_result using fullOutputPath before it reaches the transcript", async () => {
+    const raw = [
+      "header",
+      ...Array.from({ length: 5 }, (_, i) => `bash noise ${i} ${"a".repeat(30)}`),
+      "bashneedle24680 terminal fact hidden in full log",
+      ...Array.from({ length: 7_500 }, (_, i) => `bash tail ${i} ${"a".repeat(30)}`),
+    ].join("\n");
+    const full = join(root, "bash-full.log");
+    writeFileSync(full, raw, "utf8");
+
+    const patched = await t!.session.extensionRunner.emitToolResult({
+      type: "tool_result",
+      toolName: "bash",
+      input: { command: "generate massive report" },
+      content: [{ type: "text", text: "[pi truncated visible output]" }],
+      details: { fullOutputPath: full, truncation: { truncated: true } },
+      isError: false,
+    });
+
+    const text = textOf(patched);
+    expect(text).toContain("ctx:stored");
+    expect(text).toContain("Use ctx search");
+    expect(text).not.toContain("bashneedle24680");
+    expect(patched.details.ctxStored).toBe(true);
+    expect(statSync(join(sessionDir, "ctx", dbFiles()[0])).size).toBeGreaterThan(0);
+
+    const search = await ctxExec({ op: "search", query: "bashneedle24680", limit: 1 });
+    expect(textOf(search)).toContain("bashneedle24680 terminal fact");
+  });
+
+  it("extracts searchable failure context for huge failing bash output and keeps isError", async () => {
+    const full = join(root, "bash-error.log");
+    writeFileSync(full, `${"boring\n".repeat(5_000)}panic ctxboom999 exploded\nstack trace line\n`, "utf8");
+
+    const patched = await t!.session.extensionRunner.emitToolResult({
+      type: "tool_result",
+      toolName: "bash",
+      input: { command: "run failing suite" },
+      content: [{ type: "text", text: "[truncated]" }],
+      details: { fullOutputPath: full },
+      isError: true,
+    });
+
+    expect(patched.isError).toBe(true);
+    expect(textOf(patched)).toContain("ctx:stored");
+    expect(textOf(patched)).toContain("matched");
+
+    const search = await ctxExec({ op: "search", query: "ctxboom999", limit: 1 });
+    expect(textOf(search)).toContain("panic ctxboom999 exploded");
+  });
+
+  it("search returns the matching region when a hit is buried deep inside a chunk", async () => {
+    const filler = Array.from({ length: 180 }, (_, i) => `preface ${i} ${"p".repeat(80)}`).join("\n");
+    await ctxExec({
+      op: "run-js",
+      query: "buriedneedle424242",
+      code: `console.log(${JSON.stringify(`${filler}\nburiedneedle424242 exact match near end of chunk\n${"tail ".repeat(5_000)}`)})`,
+    });
+
+    const search = await ctxExec({ op: "search", query: "buriedneedle424242", limit: 1 });
+    const out = textOf(search);
+    expect(out).toContain("buriedneedle424242 exact match");
+    expect(out.length).toBeLessThan(3_000);
+  });
+
+  it("collapses actual built-in bash execution output using Pi fullOutputPath metadata", async () => {
+    const bash = (t!.session.agent as any).state.tools.find((tool: any) => tool.name === "bash");
+    expect(bash).toBeDefined();
+    const command = `python3 - <<'PY'\nfor i in range(7000): print(f'realbashneedle777 line {i}')\nPY`;
+    const raw = await bash.execute("bash-real-1", { command }, undefined, undefined, t!.session.extensionRunner.createContext());
+    expect(typeof raw.details?.fullOutputPath).toBe("string");
+    expect(raw.details?.truncation?.truncated).toBe(true);
+
+    try {
+      const patched = await t!.session.extensionRunner.emitToolResult({
+        type: "tool_result",
+        toolCallId: "bash-real-1",
+        toolName: "bash",
+        input: { command },
+        content: raw.content,
+        details: raw.details,
+        isError: raw.isError,
+      });
+
+      expect(textOf(patched)).toContain("ctx:stored");
+      expect(textOf(patched)).not.toContain("realbashneedle777 line 6999");
+      const search = await ctxExec({ op: "search", query: "realbashneedle777", limit: 1 });
+      expect(textOf(search)).toContain("realbashneedle777 line");
+    } finally {
+      rmSync(raw.details?.fullOutputPath, { force: true });
+    }
+  });
+
+  it("falls back to visible bash content when fullOutputPath is absent", async () => {
+    const visible = `${"visible filler\n".repeat(9_000)}visibleonly333 final line`;
+    const patched = await t!.session.extensionRunner.emitToolResult({
+      type: "tool_result",
+      toolCallId: "bash-visible-1",
+      toolName: "bash",
+      input: { command: "already truncated elsewhere" },
+      content: [{ type: "text", text: visible }],
+      details: { truncation: { truncated: true } },
+      isError: false,
+    });
+
+    expect(textOf(patched)).toContain("ctx:stored");
+    expect(textOf(patched)).not.toContain("visibleonly333");
+    const search = await ctxExec({ op: "search", query: "visibleonly333", limit: 1 });
+    expect(textOf(search)).toContain("visibleonly333 final line");
+  });
+
+  it("handles concurrent ctx writes without lock errors or lost sources", async () => {
+    const count = 8;
+    const results = await Promise.all(Array.from({ length: count }, (_, i) => ctxExec({
+      op: "run-js",
+      code: `console.log('concurrentneedle${i} ' + '${"x".repeat(130_000)}')`,
+    })));
+
+    for (const result of results) expect(textOf(result)).toContain("ctx:stored");
+    const [extension] = t!.session.extensionRunner.extensions;
+    const stats = await extension.commands.get("ctx").handler("", t!.session.extensionRunner.createContext());
+    expect(stats.text).toContain(`ctx: ${count} sources`);
+
+    for (let i = 0; i < count; i++) {
+      const search = await ctxExec({ op: "search", query: `concurrentneedle${i}`, limit: 1 });
+      expect(textOf(search)).toContain(`concurrentneedle${i}`);
+    }
+  });
+
+  it("keeps unicode output valid while using byte thresholds conservatively", async () => {
+    const marker = "unicodeNeedle555 測試 ✅";
+    const result = await ctxExec({
+      op: "run-js",
+      code: `console.log('${"😀".repeat(40_000)} ${marker}')`,
+    });
+
+    expect(textOf(result)).toContain("ctx:stored");
+    const search = await ctxExec({ op: "search", query: "unicodeNeedle555", limit: 1 });
+    expect(textOf(search)).toContain(marker);
+    expect(textOf(search)).not.toContain("�");
+  });
+
+  it("closes ctx resources so session directory can be removed after dispose", async () => {
+    await ctxExec({ op: "run-js", code: "console.log('cleanupneedle ' + 'x'.repeat(120_000))" });
+    expect(dbFiles()).toHaveLength(1);
+    t!.dispose();
+    t = undefined;
+    rmSync(root, { recursive: true, force: true });
+    expect(existsSync(root)).toBe(false);
+  });
+
+  it("does not touch small bash output, then /ctx reports, searches, and purges stored data", async () => {
+    const unchanged = await t!.session.extensionRunner.emitToolResult({
+      type: "tool_result",
+      toolName: "bash",
+      input: { command: "echo small" },
+      content: [{ type: "text", text: "small output" }],
+      details: {},
+      isError: false,
+    });
+    expect(unchanged).toBeUndefined();
+
+    await ctxExec({ op: "run-js", code: "console.log('cmdneedle13579 ' + 'q'.repeat(120_000))" });
+    const [extension] = t!.session.extensionRunner.extensions;
+    const command = extension.commands.get("ctx");
+
+    const stats = await command.handler("", t!.session.extensionRunner.createContext());
+    expect(stats.text).toContain("ctx: 1 sources");
+    expect(stats.text).toContain("recent:");
+
+    const found = await command.handler("cmdneedle13579", t!.session.extensionRunner.createContext());
+    expect(found.text).toContain("cmdneedle13579");
+
+    const purged = await command.handler("--purge", t!.session.extensionRunner.createContext());
+    expect(purged.text).toBe("ctx purged");
+
+    const empty = await command.handler("", t!.session.extensionRunner.createContext());
+    expect(empty.text).toContain("ctx: 0 sources");
+  });
+});