goatcode-sh 0.0.1 → 0.1.3

package/src/hooks/edit-error/handler.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "bun:test";
+
+import { createEditErrorHandler, EDIT_ERROR_RECOVERY_MESSAGE } from "./handler";
+
+type UnknownHandler = (input: unknown, output: unknown) => Promise<void>;
+
+describe("createEditErrorHandler", () => {
+  describe("#given a handler instance", () => {
+    const handler = createEditErrorHandler() as unknown as UnknownHandler;
+
+    describe("#when input.tool is 'edit' and output contains 'oldString not found'", () => {
+      it("#then appends EDIT_ERROR_RECOVERY_MESSAGE to output.output", async () => {
+        const input = { tool: "edit" };
+        const output = { output: "oldString not found in file" };
+        await handler(input, output);
+        expect(output.output).toContain("[EDIT ERROR RECOVERY]");
+        expect(output.output).toBe(`oldString not found in file\n${EDIT_ERROR_RECOVERY_MESSAGE}`);
+      });
+    });
+
+    describe("#when input.tool is 'edit' and output contains 'oldString found multiple times'", () => {
+      it("#then appends EDIT_ERROR_RECOVERY_MESSAGE", async () => {
+        const input = { tool: "edit" };
+        const output = { output: "oldString found multiple times in file content" };
+        await handler(input, output);
+        expect(output.output).toContain("[EDIT ERROR RECOVERY]");
+      });
+    });
+
+    describe("#when input.tool is not 'edit'", () => {
+      it("#then output.output remains unchanged", async () => {
+        const input = { tool: "bash" };
+        const output = { output: "oldString not found in file" };
+        await handler(input, output);
+        expect(output.output).toBe("oldString not found in file");
+      });
+    });
+
+    describe("#when output already contains recovery marker", () => {
+      it("#then does not double-append", async () => {
+        const input = { tool: "edit" };
+        const output = {
+          output: `oldString not found in file\n${EDIT_ERROR_RECOVERY_MESSAGE}`,
+        };
+        const before = output.output;
+        await handler(input, output);
+        expect(output.output).toBe(before);
+      });
+    });
+
+    describe("#when output.output is not a string", () => {
+      it("#then no-op", async () => {
+        const input = { tool: "edit" };
+        const output = { output: 42 };
+        await handler(input, output);
+        expect(output.output).toBe(42);
+      });
+    });
+
+    describe("#when input or output is not a record", () => {
+      it("#then no-op for non-object input", async () => {
+        const output = { output: "oldString not found" };
+        await handler(null, output);
+        expect(output.output).toBe("oldString not found");
+      });
+
+      it("#then no-op for non-object output", async () => {
+        const input = { tool: "edit" };
+        await handler(input, "not-an-object");
+      });
+    });
+
+    describe("#when input.tool is 'Edit' (case-insensitive)", () => {
+      it("#then still triggers recovery", async () => {
+        const input = { tool: "Edit" };
+        const output = { output: "oldString not found in file" };
+        await handler(input, output);
+        expect(output.output).toContain("[EDIT ERROR RECOVERY]");
+      });
+    });
+  });
+});

package/src/hooks/edit-error/handler.ts

@@ -0,0 +1,50 @@
+import type { PluginHookContributions } from "../../types/hook";
+import { log } from "../../shared/logger";
+
+export const EDIT_ERROR_PATTERNS = [
+  /oldstring and newstring must be different/i,
+  /oldstring not found/i,
+  /oldstring found multiple times/i,
+  /string to replace not found/i,
+] as const;
+
+const EDIT_ERROR_RECOVERY_MARKER = "[EDIT ERROR RECOVERY]";
+
+export const EDIT_ERROR_RECOVERY_MESSAGE = `${EDIT_ERROR_RECOVERY_MARKER}\nEdit failed because the target text did not match the current file state. Re-read the file, copy the exact current content, and retry the edit with an unambiguous oldString.`;
+
+type PostToolUseHook = NonNullable<PluginHookContributions["tool.execute.after"]>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function createEditErrorHandler(): 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" || tool.toLowerCase() !== "edit") {
+      return;
+    }
+
+    if (typeof toolOutput !== "string") {
+      return;
+    }
+
+    if (toolOutput.includes(EDIT_ERROR_RECOVERY_MARKER)) {
+      return;
+    }
+
+    const hasEditError = EDIT_ERROR_PATTERNS.some((pattern) => pattern.test(toolOutput));
+    if (!hasEditError) {
+      return;
+    }
+
+    output.output = `${toolOutput}\n${EDIT_ERROR_RECOVERY_MESSAGE}`;
+    log("[edit-error] injected edit recovery message");
+  };
+}

package/src/hooks/edit-error/index.ts

@@ -0,0 +1,6 @@
+export { editErrorPlugin } from "./plugin";
+export {
+  createEditErrorHandler,
+  EDIT_ERROR_PATTERNS,
+  EDIT_ERROR_RECOVERY_MESSAGE,
+} from "./handler";

package/src/hooks/edit-error/plugin.ts

@@ -0,0 +1,15 @@
+import { definePlugin } from "../../plugin-api/define-plugin";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createEditErrorHandler } from "./handler";
+
+const toolExecuteAfterHook = safeCreateHook("edit-error", createEditErrorHandler);
+
+export const editErrorPlugin = definePlugin({
+  name: "edit-error",
+  version: "0.1.0",
+  hooks: toolExecuteAfterHook
+    ? {
+        "tool.execute.after": toolExecuteAfterHook,
+      }
+    : {},
+});

package/src/hooks/empty-response-detector/handler.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "bun:test";
+
+import { createEmptyResponseDetectorHandler, EMPTY_RESPONSE_WARNING } from "./handler";
+
+describe("createEmptyResponseDetectorHandler", () => {
+  describe("#given a task tool with empty output", () => {
+    describe("#when the output string is empty", () => {
+      it("#then replaces output with the warning message", async () => {
+        const handler = createEmptyResponseDetectorHandler();
+        const input = { tool: "task", sessionID: "s1", callID: "c1", args: {} };
+        const output = { title: "task", output: "", metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(EMPTY_RESPONSE_WARNING);
+      });
+    });
+  });
+
+  describe("#given a task tool with near-empty output", () => {
+    describe("#when the output is under the threshold length", () => {
+      it("#then replaces output with the warning message", async () => {
+        const handler = createEmptyResponseDetectorHandler();
+        const input = { tool: "task", sessionID: "s1", callID: "c1", args: {} };
+        const output = { title: "task", output: "short", metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(EMPTY_RESPONSE_WARNING);
+      });
+    });
+  });
+
+  describe("#given a task tool with whitespace-only output", () => {
+    describe("#when the output is tabs and spaces", () => {
+      it("#then replaces output with the warning message", async () => {
+        const handler = createEmptyResponseDetectorHandler();
+        const input = { tool: "task", sessionID: "s1", callID: "c1", args: {} };
+        const output = { title: "task", output: "  \t\t  ", metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(EMPTY_RESPONSE_WARNING);
+      });
+    });
+  });
+
+  describe("#given a task tool with null output", () => {
+    describe("#when output.output is null", () => {
+      it("#then sets output to the warning message", async () => {
+        const handler = createEmptyResponseDetectorHandler();
+        const input = { tool: "task", sessionID: "s1", callID: "c1", args: {} };
+        const output = { title: "task", output: null as unknown as string, metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(EMPTY_RESPONSE_WARNING);
+      });
+    });
+  });
+
+  describe("#given a task tool with undefined output", () => {
+    describe("#when output.output is undefined", () => {
+      it("#then sets output to the warning message", async () => {
+        const handler = createEmptyResponseDetectorHandler();
+        const input = { tool: "task", sessionID: "s1", callID: "c1", args: {} };
+        const output = { title: "task", output: undefined as unknown as string, metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(EMPTY_RESPONSE_WARNING);
+      });
+    });
+  });
+
+  describe("#given a task tool with meaningful content", () => {
+    describe("#when the output has substantial text", () => {
+      it("#then does not modify the output", async () => {
+        const handler = createEmptyResponseDetectorHandler();
+        const input = { tool: "task", sessionID: "s1", callID: "c1", args: {} };
+        const original = "The agent completed all requested changes to the codebase.";
+        const output = { title: "task", output: original, metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(original);
+      });
+    });
+  });
+
+  describe("#given a task tool with output already containing the marker", () => {
+    describe("#when the output has EMPTY_RESPONSE_WARNING already", () => {
+      it("#then does not double-inject the warning", async () => {
+        const handler = createEmptyResponseDetectorHandler();
+        const input = { tool: "task", sessionID: "s1", callID: "c1", args: {} };
+        const output = { title: "task", output: EMPTY_RESPONSE_WARNING, metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(EMPTY_RESPONSE_WARNING);
+      });
+    });
+  });
+
+  describe("#given a non-task tool", () => {
+    describe("#when the tool is Bash with empty output", () => {
+      it("#then does not modify the output", async () => {
+        const handler = createEmptyResponseDetectorHandler();
+        const input = { tool: "Bash", sessionID: "s1", callID: "c1", args: {} };
+        const output = { title: "Bash", output: "", metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe("");
+      });
+    });
+  });
+
+  describe("#given a task tool with output exactly at threshold boundary", () => {
+    describe("#when the trimmed output is exactly 10 characters", () => {
+      it("#then does not replace the output", async () => {
+        const handler = createEmptyResponseDetectorHandler();
+        const input = { tool: "task", sessionID: "s1", callID: "c1", args: {} };
+        const original = "1234567890";
+        const output = { title: "task", output: original, metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(original);
+      });
+    });
+  });
+});

package/src/hooks/empty-response-detector/handler.ts

@@ -0,0 +1,62 @@
+import type { PluginHookContributions } from "../../types/hook";
+import { log } from "../../shared/logger";
+
+type PostToolUseHook = NonNullable<PluginHookContributions["tool.execute.after"]>;
+
+const EMPTY_RESPONSE_MARKER = "[EMPTY RESPONSE WARNING]";
+
+export const EMPTY_RESPONSE_WARNING = `${EMPTY_RESPONSE_MARKER}
+Task invocation completed but returned no response. This indicates the agent either:
+- Failed to execute properly
+- Did not terminate correctly
+- Returned an empty result
+
+Note: The call has already completed - you are NOT waiting for a response. Proceed accordingly.`;
+
+const NEAR_EMPTY_THRESHOLD = 10;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isTaskTool(tool: string): boolean {
+  return tool.toLowerCase() === "task";
+}
+
+function isEmptyOrNearEmpty(text: string): boolean {
+  const trimmed = text.trim();
+  return trimmed.length === 0 || trimmed.length < NEAR_EMPTY_THRESHOLD;
+}
+
+export function createEmptyResponseDetectorHandler(): PostToolUseHook {
+  return async (input: unknown, output: unknown) => {
+    if (!isRecord(input) || !isRecord(output)) {
+      return;
+    }
+
+    const tool = input.tool;
+    if (typeof tool !== "string" || !isTaskTool(tool)) {
+      return;
+    }
+
+    const toolOutput = output.output;
+    if (typeof toolOutput !== "string") {
+      if (toolOutput === undefined || toolOutput === null) {
+        output.output = EMPTY_RESPONSE_WARNING;
+        log("[empty-response-detector] injected warning for undefined/null output");
+      }
+      return;
+    }
+
+    if (toolOutput.includes(EMPTY_RESPONSE_MARKER)) {
+      return;
+    }
+
+    if (!isEmptyOrNearEmpty(toolOutput)) {
+      return;
+    }
+
+    output.output = EMPTY_RESPONSE_WARNING;
+    log("[empty-response-detector] injected warning for empty/near-empty output");
+  };
+}

package/src/hooks/empty-response-detector/index.ts

@@ -0,0 +1,2 @@
+export { emptyResponseDetectorPlugin } from "./plugin";
+export { createEmptyResponseDetectorHandler, EMPTY_RESPONSE_WARNING } from "./handler";

package/src/hooks/empty-response-detector/plugin.ts

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

package/src/hooks/error-diagnostics/error-diagnostics.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from "bun:test";
+
+import { createEventErrorHandler, createToolErrorHandler } from "./handler";
+import { matchDiagnostic } from "./patterns";
+import type { ErrorCategory } from "./types";
+
+describe("error-diagnostics", () => {
+  describe("matchDiagnostic", () => {
+    it("matches each category", () => {
+      const cases: Array<{ input: string; category: ErrorCategory }> = [
+        { input: "Error 429: too many requests", category: "rate-limit" },
+        { input: "authentication failed with invalid API key", category: "auth" },
+        { input: "request ETIMEDOUT after 30000ms", category: "timeout" },
+        { input: "EACCES: permission denied, open '/tmp/file'", category: "permission" },
+        { input: "ENOENT: no such file or directory", category: "file-system" },
+        { input: "fetch failed due to ECONNREFUSED", category: "network" },
+        { input: "JavaScript heap out of memory", category: "memory" },
+        { input: "SyntaxError: unexpected token ;", category: "syntax" },
+        { input: "TypeError: value is not a function", category: "type-error" },
+      ];
+
+      for (const testCase of cases) {
+        const result = matchDiagnostic(testCase.input);
+        expect(result).not.toBeNull();
+        expect(result?.category).toBe(testCase.category);
+      }
+    });
+
+    it("returns null for unknown text", () => {
+      const result = matchDiagnostic("all operations completed successfully");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("createToolErrorHandler", () => {
+    it("injects diagnostic block into matched tool output", async () => {
+      const handler = createToolErrorHandler() as (
+        input: unknown,
+        output: unknown,
+      ) => Promise<void> | void;
+      const output = { output: "Request failed with 429 too many requests" };
+
+      await handler({}, output);
+
+      expect(output.output).toContain("[ERROR DIAGNOSTIC]");
+      expect(output.output).toContain("Category: rate-limit");
+      expect(output.output).toContain("Severity: warning");
+      expect(output.output).toContain("Suggestion:");
+    });
+
+    it("skips non-error output", async () => {
+      const handler = createToolErrorHandler() as (
+        input: unknown,
+        output: unknown,
+      ) => Promise<void> | void;
+      const output = { output: "everything is healthy and complete" };
+
+      await handler({}, output);
+
+      expect(output.output).toBe("everything is healthy and complete");
+    });
+
+    it("skips output that already contains diagnostics", async () => {
+      const handler = createToolErrorHandler() as (
+        input: unknown,
+        output: unknown,
+      ) => Promise<void> | void;
+      const output = {
+        output:
+          "Error 429: too many requests\n[ERROR DIAGNOSTIC]\nCategory: rate-limit\nSeverity: warning\nSuggestion: wait",
+      };
+
+      await handler({}, output);
+
+      const markerCount = (output.output.match(/\[ERROR DIAGNOSTIC\]/g) ?? []).length;
+      expect(markerCount).toBe(1);
+    });
+  });
+
+  describe("createEventErrorHandler", () => {
+    it("processes session.error and appends recoveryContext diagnostic", async () => {
+      const handler = createEventErrorHandler() as (input: unknown) => Promise<void> | void;
+      const payload = {
+        event: {
+          type: "session.error",
+          properties: {
+            error: "Permission denied while accessing /tmp",
+          },
+        },
+      };
+
+      await handler(payload);
+
+      const properties = payload.event.properties as { recoveryContext?: string };
+      expect(properties.recoveryContext).toContain("[ERROR DIAGNOSTIC]");
+      expect(properties.recoveryContext).toContain("Category: permission");
+    });
+
+    it("ignores non-session.error event types", async () => {
+      const handler = createEventErrorHandler() as (input: unknown) => Promise<void> | void;
+      const payload = {
+        event: {
+          type: "session.idle",
+          properties: {
+            error: "Permission denied while accessing /tmp",
+          },
+        },
+      };
+
+      await handler(payload);
+
+      const properties = payload.event.properties as { recoveryContext?: string };
+      expect(properties.recoveryContext).toBeUndefined();
+    });
+  });
+});

package/src/hooks/error-diagnostics/handler.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from "bun:test";
+
+import { createToolErrorHandler, createEventErrorHandler } from "./handler";
+
+type UnknownToolHandler = (input: unknown, output: unknown) => Promise<void>;
+type UnknownEventHandler = (input: unknown) => Promise<void>;
+
+describe("createToolErrorHandler", () => {
+  describe("#given a handler instance", () => {
+    const handler = createToolErrorHandler() as unknown as UnknownToolHandler;
+
+    describe("#when output contains a known error pattern (rate limit)", () => {
+      it("#then appends diagnostic with category, severity, suggestion", async () => {
+        const input = {};
+        const output = { output: "Error: rate limit exceeded, try again later" };
+        await handler(input, output);
+        expect(output.output).toContain("[ERROR DIAGNOSTIC]");
+        expect(output.output).toContain("Category: rate-limit");
+        expect(output.output).toContain("Severity: warning");
+        expect(output.output).toContain("Suggestion:");
+      });
+    });
+
+    describe("#when output contains a permission error pattern", () => {
+      it("#then appends diagnostic with category permission", async () => {
+        const input = {};
+        const output = { output: "EACCES: permission denied, open '/etc/shadow'" };
+        await handler(input, output);
+        expect(output.output).toContain("[ERROR DIAGNOSTIC]");
+        expect(output.output).toContain("Category: permission");
+        expect(output.output).toContain("Severity: error");
+      });
+    });
+
+    describe("#when output does not match any error pattern", () => {
+      it("#then no-op", async () => {
+        const input = {};
+        const output = { output: "success: operation completed" };
+        await handler(input, output);
+        expect(output.output).toBe("success: operation completed");
+      });
+    });
+
+    describe("#when output already contains diagnostic marker", () => {
+      it("#then does not double-append", async () => {
+        const input = {};
+        const output = {
+          output:
+            "rate limit exceeded\n[ERROR DIAGNOSTIC]\nCategory: rate-limit\nSeverity: warning\nSuggestion: Wait.",
+        };
+        const before = output.output;
+        await handler(input, output);
+        expect(output.output).toBe(before);
+      });
+    });
+
+    describe("#when output.output is not a string", () => {
+      it("#then no-op", async () => {
+        const input = {};
+        const output = { output: 999 };
+        await handler(input, output);
+        expect(output.output).toBe(999);
+      });
+    });
+
+    describe("#when output is not a record", () => {
+      it("#then no-op", async () => {
+        await handler({}, "not-a-record");
+      });
+    });
+  });
+});
+
+describe("createEventErrorHandler", () => {
+  describe("#given a handler instance", () => {
+    const handler = createEventErrorHandler() as unknown as UnknownEventHandler;
+
+    describe("#when event is session.error with a matching error pattern", () => {
+      it("#then sets recoveryContext with diagnostic", async () => {
+        const properties: Record<string, unknown> = { error: "ECONNREFUSED: connection refused" };
+        const input = {
+          event: { type: "session.error", properties },
+        };
+        await handler(input);
+        expect(properties.recoveryContext).toContain("[ERROR DIAGNOSTIC]");
+        expect(properties.recoveryContext).toContain("Category: network");
+        expect(properties.recoveryContext).toContain("Severity: error");
+      });
+    });
+
+    describe("#when event is session.error with timeout error", () => {
+      it("#then sets recoveryContext with timeout diagnostic", async () => {
+        const properties: Record<string, unknown> = { error: "request timed out" };
+        const input = {
+          event: { type: "session.error", properties },
+        };
+        await handler(input);
+        expect(properties.recoveryContext).toContain("[ERROR DIAGNOSTIC]");
+        expect(properties.recoveryContext).toContain("Category: timeout");
+      });
+    });
+
+    describe("#when event type is not session.error", () => {
+      it("#then no-op", async () => {
+        const properties: Record<string, unknown> = { error: "ECONNREFUSED" };
+        const input = {
+          event: { type: "session.idle", properties },
+        };
+        await handler(input);
+        expect(properties.recoveryContext).toBeUndefined();
+      });
+    });
+
+    describe("#when event error does not match any pattern", () => {
+      it("#then no recoveryContext set", async () => {
+        const properties: Record<string, unknown> = { error: "something completely normal" };
+        const input = {
+          event: { type: "session.error", properties },
+        };
+        await handler(input);
+        expect(properties.recoveryContext).toBeUndefined();
+      });
+    });
+
+    describe("#when recoveryContext already contains diagnostic marker", () => {
+      it("#then does not double-append", async () => {
+        const existingDiag =
+          "[ERROR DIAGNOSTIC]\nCategory: network\nSeverity: error\nSuggestion: Check.";
+        const properties: Record<string, unknown> = {
+          error: "ECONNREFUSED",
+          recoveryContext: existingDiag,
+        };
+        const input = {
+          event: { type: "session.error", properties },
+        };
+        await handler(input);
+        expect(properties.recoveryContext).toBe(existingDiag);
+      });
+    });
+
+    describe("#when input is not a record", () => {
+      it("#then no-op", async () => {
+        await handler(null);
+      });
+    });
+  });
+});