goatcode-sh 0.0.1 → 0.1.2

package/src/hooks/tool-output-truncator/handler.ts

@@ -0,0 +1,83 @@
+import type { PluginHookContributions } from "../../types/hook";
+import { log } from "../../shared/logger";
+import { writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const MAX_BYTES = 51_200;
+const MAX_LINES = 2_000;
+
+const TRUNCATABLE_TOOLS = new Set([
+  "grep",
+  "Grep",
+  "safe_grep",
+  "glob",
+  "Glob",
+  "safe_glob",
+  "lsp_diagnostics",
+  "ast_grep_search",
+  "interactive_bash",
+  "Interactive_bash",
+  "skill_mcp",
+  "webfetch",
+  "WebFetch",
+  "bash",
+  "Bash",
+]);
+
+type PostToolUseHook = NonNullable<PluginHookContributions["tool.execute.after"]>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+async function writeTruncatedOutput(content: string, tool: string): Promise<string> {
+  const filename = `goatcode-truncated-${tool}-${Date.now()}.txt`;
+  const filePath = join(tmpdir(), filename);
+  try {
+    await writeFile(filePath, content);
+    return filePath;
+  } catch {
+    log("[tool-output-truncator] failed to write truncated output file", { filePath });
+    return filePath;
+  }
+}
+
+async function truncateOutput(output: string, tool: string): Promise<string> {
+  const lines = output.split("\n");
+  const byteLength = Buffer.byteLength(output, "utf8");
+
+  if (byteLength <= MAX_BYTES && lines.length <= MAX_LINES) {
+    return output;
+  }
+
+  const filePath = await writeTruncatedOutput(output, tool);
+
+  const kept = lines.slice(0, MAX_LINES);
+  const truncatedBytes = Buffer.byteLength(kept.join("\n"), "utf8");
+  const finalLines =
+    truncatedBytes > MAX_BYTES
+      ? lines.slice(0, Math.floor(MAX_LINES * (MAX_BYTES / truncatedBytes)))
+      : kept;
+
+  const notice = `\n[Output truncated: ${lines.length} lines / ${byteLength} bytes exceeded limit. Full output written to ${filePath}. Use Read with offset/limit to access specific sections.]`;
+  return finalLines.join("\n") + notice;
+}
+
+export function createToolOutputTruncatorHandler(): PostToolUseHook {
+  return async (input: unknown, output: unknown) => {
+    if (!isRecord(input) || !isRecord(output)) return;
+
+    const tool = input.tool;
+    const toolOutput = output.output;
+
+    if (typeof tool !== "string" || !TRUNCATABLE_TOOLS.has(tool)) return;
+    if (typeof toolOutput !== "string") return;
+
+    const truncated = await truncateOutput(toolOutput, tool);
+    if (truncated !== toolOutput) {
+      output.output = truncated;
+      log("[tool-output-truncator] truncated output", { tool, originalLength: toolOutput.length });
+    }
+  };
+}

package/src/hooks/tool-output-truncator/index.ts

@@ -0,0 +1,2 @@
+export { toolOutputTruncatorPlugin } from "./plugin";
+export { createToolOutputTruncatorHandler } from "./handler";

package/src/hooks/tool-output-truncator/plugin.ts

@@ -0,0 +1,18 @@
+import { definePlugin } from "../../plugin-api/define-plugin";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createToolOutputTruncatorHandler } from "./handler";
+
+const toolExecuteAfterHook = safeCreateHook(
+  "tool-output-truncator",
+  createToolOutputTruncatorHandler,
+);
+
+export const toolOutputTruncatorPlugin = definePlugin({
+  name: "tool-output-truncator",
+  version: "0.1.0",
+  hooks: toolExecuteAfterHook
+    ? {
+        "tool.execute.after": toolExecuteAfterHook,
+      }
+    : {},
+});

package/src/hooks/tool-output.test.ts

@@ -0,0 +1,238 @@
+import { describe, it, expect } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createToolOutputTruncatorHandler } from "./tool-output-truncator/handler";
+import { createHashlineReadEnhancerHandler } from "./hashline-read-enhancer/handler";
+import {
+  createHashlineDiffEnhancerBeforeHandler,
+  createHashlineDiffEnhancerAfterHandler,
+} from "./hashline-diff-enhancer/handler";
+
+const HASHLINE_PATTERN = /^[0-9]+#[ZPMQVRWSNKTXJBYH]{2}\|/;
+
+describe("tool-output-truncator", () => {
+  describe("#given a grep tool with output exceeding 2000 lines", () => {
+    describe("#when the handler processes the output", () => {
+      it("#then truncates the output and appends a notice with file path", async () => {
+        const handler = createToolOutputTruncatorHandler();
+        const lines = Array.from({ length: 3000 }, (_, i) => `line ${i + 1}: some content here`);
+        const input = { tool: "grep", sessionID: "s1", callID: "c1" };
+        const output = {
+          title: "grep result",
+          output: lines.join("\n"),
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        const resultLines = output.output.split("\n");
+        expect(resultLines.length).toBeLessThan(3000);
+        expect(output.output).toContain("[Output truncated:");
+        expect(output.output).toContain("Full output written to");
+        expect(output.output).toContain("Use Read with offset/limit");
+      });
+    });
+  });
+
+  describe("#given a Read tool (not in truncatable list)", () => {
+    describe("#when the handler processes the output", () => {
+      it("#then does not truncate the output", async () => {
+        const handler = createToolOutputTruncatorHandler();
+        const lines = Array.from({ length: 3000 }, (_, i) => `line ${i + 1}: content`);
+        const original = lines.join("\n");
+        const input = { tool: "Read", sessionID: "s1", callID: "c1" };
+        const output = {
+          title: "file content",
+          output: original,
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(original);
+      });
+    });
+  });
+
+  describe("#given a bash tool with output within limits", () => {
+    describe("#when the handler processes the output", () => {
+      it("#then leaves the output unchanged", async () => {
+        const handler = createToolOutputTruncatorHandler();
+        const original = "short output";
+        const input = { tool: "bash", sessionID: "s1", callID: "c1" };
+        const output = {
+          title: "bash result",
+          output: original,
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(original);
+      });
+    });
+  });
+});
+
+describe("hashline-read-enhancer", () => {
+  describe("#given a Read tool output with content tags", () => {
+    describe("#when the handler processes the output", () => {
+      it("#then prepends LINE#ID hashes to each file line", async () => {
+        const handler = createHashlineReadEnhancerHandler();
+        const input = { tool: "read", sessionID: "s1", callID: "c1" };
+        const output = {
+          title: "demo.ts",
+          output: [
+            "<path>/tmp/demo.ts</path>",
+            "<type>file</type>",
+            "<content>",
+            "1: const x = 1",
+            "2: const y = 2",
+            "</content>",
+          ].join("\n"),
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        const lines = output.output.split("\n");
+        expect(lines[3]).toMatch(HASHLINE_PATTERN);
+        expect(lines[3]).toContain("const x = 1");
+        expect(lines[4]).toMatch(HASHLINE_PATTERN);
+        expect(lines[4]).toContain("const y = 2");
+      });
+    });
+  });
+
+  describe("#given a Read tool output without content tags", () => {
+    describe("#when the handler processes the output", () => {
+      it("#then hashifies plain numbered lines", async () => {
+        const handler = createHashlineReadEnhancerHandler();
+        const input = { tool: "read", sessionID: "s1", callID: "c1" };
+        const output = {
+          title: "README.md",
+          output: ["1: # Title", "2: Some content", "3: More content"].join("\n"),
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        const lines = output.output.split("\n");
+        expect(lines[0]).toMatch(HASHLINE_PATTERN);
+        expect(lines[0]).toContain("# Title");
+        expect(lines[1]).toMatch(HASHLINE_PATTERN);
+        expect(lines[2]).toMatch(HASHLINE_PATTERN);
+      });
+    });
+  });
+
+  describe("#given a non-Read tool", () => {
+    describe("#when the handler processes the output", () => {
+      it("#then leaves the output unchanged", async () => {
+        const handler = createHashlineReadEnhancerHandler();
+        const input = { tool: "bash", sessionID: "s1", callID: "c1" };
+        const original = "1: some output";
+        const output = {
+          title: "bash",
+          output: original,
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(original);
+      });
+    });
+  });
+
+  describe("#given a Write tool with a valid file", () => {
+    describe("#when the handler processes the output", () => {
+      it("#then replaces output with line count summary", async () => {
+        const handler = createHashlineReadEnhancerHandler();
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "hashline-write-"));
+        const filePath = path.join(tempDir, "demo.ts");
+        fs.writeFileSync(filePath, "const x = 1\nconst y = 2");
+        const input = { tool: "write", sessionID: "s1", callID: "c1" };
+        const output = {
+          title: "write",
+          output: "Wrote file successfully.",
+          metadata: { filepath: filePath },
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toContain("File written successfully.");
+        expect(output.output).toContain("2 lines written.");
+
+        fs.rmSync(tempDir, { recursive: true, force: true });
+      });
+    });
+  });
+});
+
+describe("hashline-diff-enhancer", () => {
+  describe("#given a Write tool that modifies an existing file", () => {
+    describe("#when before and after handlers both run", () => {
+      it("#then metadata contains diff and hashlined content", async () => {
+        const beforeHandler = createHashlineDiffEnhancerBeforeHandler();
+        const afterHandler = createHashlineDiffEnhancerAfterHandler();
+
+        const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "hashline-diff-"));
+        const filePath = path.join(tempDir, "test.ts");
+        fs.writeFileSync(filePath, "const a = 1\nconst b = 2\n");
+
+        const sessionID = "s1";
+        const callID = "c1";
+        const beforeInput = { tool: "write", sessionID, callID };
+        const beforeOutput = { args: { filePath } };
+
+        await beforeHandler(beforeInput, beforeOutput);
+
+        fs.writeFileSync(filePath, "const a = 1\nconst b = 2\nconst c = 3\n");
+
+        const afterInput = { tool: "write", sessionID, callID };
+        const afterOutput = {
+          title: "write",
+          output: "File written successfully.",
+          metadata: {} as Record<string, unknown>,
+        };
+
+        await afterHandler(afterInput, afterOutput);
+
+        expect(afterOutput.metadata.diff).toBeDefined();
+        expect(typeof afterOutput.metadata.diff).toBe("string");
+        expect(afterOutput.metadata.hashlined).toBeDefined();
+        const hashlined = afterOutput.metadata.hashlined as string;
+        expect(hashlined).toMatch(HASHLINE_PATTERN);
+        expect(afterOutput.title).toBe(filePath);
+
+        fs.rmSync(tempDir, { recursive: true, force: true });
+      });
+    });
+  });
+
+  describe("#given a non-Write tool", () => {
+    describe("#when the before handler processes the input", () => {
+      it("#then does not capture any state", async () => {
+        const beforeHandler = createHashlineDiffEnhancerBeforeHandler();
+        const input = { tool: "read", sessionID: "s1", callID: "c1" };
+        const output = { args: { filePath: "/some/file.ts" } };
+
+        await beforeHandler(input, output);
+
+        const afterHandler = createHashlineDiffEnhancerAfterHandler();
+        const afterInput = { tool: "read", sessionID: "s1", callID: "c1" };
+        const afterOutput = {
+          title: "read",
+          output: "file content",
+          metadata: {} as Record<string, unknown>,
+        };
+
+        await afterHandler(afterInput, afterOutput);
+
+        expect(afterOutput.metadata.diff).toBeUndefined();
+      });
+    });
+  });
+});

package/src/hooks/workflow-reminders.test.ts

@@ -0,0 +1,187 @@
+declare const require: (name: string) => any;
+
+const { describe, expect, it, mock } = require("bun:test");
+
+import { createForegroundFallbackHandler, foregroundFallbackPlugin } from "./foreground-fallback";
+import { createPhaseReminderHandler, phaseReminderPlugin, PHASE_REMINDER } from "./phase-reminder";
+import {
+  createPostReadNudgeHandler,
+  postReadNudgePlugin,
+  POST_READ_NUDGE,
+} from "./post-read-nudge";
+
+describe("foreground-fallback", () => {
+  describe("#given a session.error with rate-limit signal", () => {
+    describe("#when the handler receives a fallback chain", () => {
+      it("#then switches to the next model and requests retry", async () => {
+        const sessionModels = new Map<string, string>([["ses-foreground", "openai/gpt-5"]]);
+        const onFallbackApplied = mock(() => undefined);
+        const onRetryRequested = mock(() => undefined);
+
+        const handler = createForegroundFallbackHandler({
+          getCurrentModel: (sessionID) => sessionModels.get(sessionID),
+          setCurrentModel: (sessionID, model) => {
+            sessionModels.set(sessionID, model);
+          },
+          onFallbackApplied,
+          onRetryRequested,
+        });
+
+        const payload = {
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-foreground",
+              model: "openai/gpt-5",
+              error: { statusCode: 429, message: "Too many requests" },
+              fallbackChain: ["openai/gpt-5", "openai/gpt-4.1-mini", "anthropic/claude-3.7-sonnet"],
+            },
+          },
+        };
+
+        await handler(payload as unknown as Parameters<typeof handler>[0]);
+
+        expect(sessionModels.get("ses-foreground")).toBe("openai/gpt-4.1-mini");
+        const properties = payload.event.properties as Record<string, unknown>;
+        expect(properties.retryRequested).toBe(true);
+        expect(properties.retryWithModel).toBe("openai/gpt-4.1-mini");
+        expect(onFallbackApplied).toHaveBeenCalledTimes(1);
+        expect(onRetryRequested).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
+
+  describe("#given duplicated rate-limit events in a short window", () => {
+    describe("#when the handler receives two events within 5 seconds", () => {
+      it("#then deduplicates fallback attempts", async () => {
+        const sessionModels = new Map<string, string>([["ses-dedup", "openai/gpt-5"]]);
+        const onFallbackApplied = mock(() => undefined);
+        const now = mock(() => 1_000);
+
+        const handler = createForegroundFallbackHandler({
+          getCurrentModel: (sessionID) => sessionModels.get(sessionID),
+          setCurrentModel: (sessionID, model) => {
+            sessionModels.set(sessionID, model);
+          },
+          onFallbackApplied,
+          now,
+        });
+
+        const first = {
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-dedup",
+              model: "openai/gpt-5",
+              error: { message: "rate limit" },
+              fallbackChain: ["openai/gpt-5", "openai/gpt-4.1-mini", "openai/gpt-4.1-nano"],
+            },
+          },
+        };
+
+        const second = {
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-dedup",
+              model: "openai/gpt-4.1-mini",
+              error: { message: "rate limit" },
+              fallbackChain: ["openai/gpt-5", "openai/gpt-4.1-mini", "openai/gpt-4.1-nano"],
+            },
+          },
+        };
+
+        await handler(first as unknown as Parameters<typeof handler>[0]);
+        await handler(second as unknown as Parameters<typeof handler>[0]);
+
+        expect(onFallbackApplied).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
+
+  it("#then plugin registers an event hook", () => {
+    expect(typeof foregroundFallbackPlugin.hooks?.event).toBe("function");
+  });
+});
+
+describe("phase-reminder", () => {
+  describe("#given an orchestrator user message", () => {
+    describe("#when transform runs", () => {
+      it("#then prepends the workflow reminder", async () => {
+        const handler = createPhaseReminderHandler();
+        const output = {
+          messages: [
+            {
+              info: { role: "user", agent: "orchestrator" },
+              parts: [{ type: "text", text: "Implement this task" }],
+            },
+          ],
+        };
+
+        await handler({}, output as unknown as Parameters<typeof handler>[1]);
+
+        const text = output.messages[0].parts[0].text;
+        expect(text.startsWith(PHASE_REMINDER)).toBe(true);
+      });
+    });
+  });
+
+  describe("#given a subagent user message", () => {
+    describe("#when transform runs", () => {
+      it("#then does not inject the reminder", async () => {
+        const handler = createPhaseReminderHandler();
+        const output = {
+          messages: [
+            {
+              info: { role: "user", agent: "explore" },
+              parts: [{ type: "text", text: "Search for files" }],
+            },
+          ],
+        };
+
+        await handler({}, output as unknown as Parameters<typeof handler>[1]);
+
+        const text = output.messages[0].parts[0].text;
+        expect(text).toBe("Search for files");
+      });
+    });
+  });
+
+  it("#then plugin registers a messages transform hook", () => {
+    expect(typeof phaseReminderPlugin.hooks?.["experimental.chat.messages.transform"]).toBe(
+      "function",
+    );
+  });
+});
+
+describe("post-read-nudge", () => {
+  describe("#given a Read tool call", () => {
+    describe("#when tool.execute.after runs", () => {
+      it("#then appends the nudge", async () => {
+        const handler = createPostReadNudgeHandler();
+        const output = { title: "read", output: "file content", metadata: {} };
+
+        await handler({ tool: "Read", sessionID: "s1", callID: "c1", args: {} }, output);
+
+        expect(output.output.endsWith(POST_READ_NUDGE)).toBe(true);
+      });
+    });
+  });
+
+  describe("#given a non-read tool call", () => {
+    describe("#when tool.execute.after runs", () => {
+      it("#then leaves output unchanged", async () => {
+        const handler = createPostReadNudgeHandler();
+        const output = { title: "bash", output: "command output", metadata: {} };
+
+        await handler({ tool: "Bash", sessionID: "s1", callID: "c1", args: {} }, output);
+
+        expect(output.output).toBe("command output");
+      });
+    });
+  });
+
+  it("#then plugin registers tool.execute.after", () => {
+    expect(typeof postReadNudgePlugin.hooks?.["tool.execute.after"]).toBe("function");
+  });
+});

package/src/hooks/write-file-guard/handler.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { createWriteFileGuardHandler, BLOCK_MESSAGE } from "./handler";
+
+describe("createWriteFileGuardHandler", () => {
+  let tempDir: string;
+
+  const createFile = (relativePath: string, content = "existing"): string => {
+    const abs = join(tempDir, relativePath);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, content);
+    return abs;
+  };
+
+  const invokePreToolUse = async (
+    handler: ReturnType<typeof createWriteFileGuardHandler>,
+    opts: { tool: string; sessionID?: string; filePath: string },
+  ): Promise<void> => {
+    const input = {
+      tool: opts.tool,
+      sessionID: opts.sessionID ?? "ses_default",
+      callID: "call_1",
+    };
+    const output = { args: { filePath: opts.filePath } };
+    await handler.preToolUse(input, output);
+  };
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "wfg-handler-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe("#given a handler instance", () => {
+    describe("#when writing to an existing file without prior read", () => {
+      it("#then throws a block error", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const existingFile = createFile("no-read.txt");
+
+        await expect(
+          invokePreToolUse(handler, { tool: "write", filePath: existingFile }),
+        ).rejects.toThrow(BLOCK_MESSAGE);
+      });
+    });
+
+    describe("#when writing to a file that was read first", () => {
+      it("#then allows the write", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const existingFile = createFile("read-first.txt");
+        const sessionID = "ses_read_write";
+
+        await invokePreToolUse(handler, { tool: "read", sessionID, filePath: existingFile });
+
+        await expect(
+          invokePreToolUse(handler, { tool: "write", sessionID, filePath: existingFile }),
+        ).resolves.toBeUndefined();
+      });
+    });
+
+    describe("#when session.deleted event fires after a read", () => {
+      it("#then clears session data and blocks subsequent write", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const existingFile = createFile("cleanup.txt");
+        const sessionID = "ses_to_delete";
+
+        await invokePreToolUse(handler, { tool: "read", sessionID, filePath: existingFile });
+
+        await handler.event({
+          event: {
+            type: "session.deleted",
+            properties: { info: { id: sessionID } },
+          },
+        });
+
+        await expect(
+          invokePreToolUse(handler, { tool: "write", sessionID, filePath: existingFile }),
+        ).rejects.toThrow(BLOCK_MESSAGE);
+      });
+    });
+
+    describe("#when the tool is neither write nor read", () => {
+      it("#then does nothing", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const existingFile = createFile("ignored.txt");
+
+        await expect(
+          invokePreToolUse(handler, { tool: "bash", filePath: existingFile }),
+        ).resolves.toBeUndefined();
+      });
+    });
+
+    describe("#when writing to a file that does not exist", () => {
+      it("#then allows the write (new file creation)", async () => {
+        const handler = createWriteFileGuardHandler(tempDir);
+        const newFile = join(tempDir, "brand-new.txt");
+
+        await expect(
+          invokePreToolUse(handler, { tool: "write", filePath: newFile }),
+        ).resolves.toBeUndefined();
+      });
+    });
+  });
+});