goatcode-sh 0.0.1 → 0.1.2

package/src/hooks/delegate-retry/handler.test.ts

@@ -0,0 +1,212 @@
+import { describe, expect, it } from "bun:test";
+
+import { createDelegateRetryHandler, detectDelegateTaskError, buildRetryGuidance } from "./handler";
+
+describe("createDelegateRetryHandler", () => {
+  describe("#given a task tool with an error output", () => {
+    describe("#when the output contains [ERROR] and run_in_background pattern", () => {
+      it("#then injects retry guidance with the correct error type", async () => {
+        const handler = createDelegateRetryHandler();
+        const input = { tool: "task", sessionID: "s1", callID: "c1", args: {} };
+        const output = {
+          title: "task",
+          output: "[ERROR] Invalid arguments: run_in_background is required",
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toContain("[task CALL FAILED - IMMEDIATE RETRY REQUIRED]");
+        expect(output.output).toContain("missing_run_in_background");
+        expect(output.output).toContain("Action");
+      });
+    });
+
+    describe("#when the output contains Invalid arguments with Unknown agent", () => {
+      it("#then injects guidance for unknown_agent error", async () => {
+        const handler = createDelegateRetryHandler();
+        const input = { tool: "task", sessionID: "s1", callID: "c1", args: {} };
+        const output = {
+          title: "task",
+          output: "Invalid arguments: Unknown agent 'badagent'. Available agents: explore, oracle",
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toContain("unknown_agent");
+        expect(output.output).toContain("Available Options");
+        expect(output.output).toContain("explore, oracle");
+      });
+    });
+
+    describe("#when the output contains Cannot call primary agent", () => {
+      it("#then injects guidance for primary_agent error", async () => {
+        const handler = createDelegateRetryHandler();
+        const input = { tool: "Task", sessionID: "s1", callID: "c1", args: {} };
+        const output = {
+          title: "task",
+          output: "[ERROR] Cannot call primary agent directly.",
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toContain("primary_agent");
+        expect(output.output).toContain("subagent");
+      });
+    });
+  });
+
+  describe("#given a task tool with a successful output", () => {
+    describe("#when the output has no error markers", () => {
+      it("#then does not modify the output", async () => {
+        const handler = createDelegateRetryHandler();
+        const input = { tool: "task", sessionID: "s1", callID: "c1", args: {} };
+        const original = "Agent completed the work successfully. Session ID: ses_abc";
+        const output = { title: "task", output: original, metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(original);
+      });
+    });
+  });
+
+  describe("#given a task tool with output that has no string output field", () => {
+    describe("#when output.output is undefined", () => {
+      it("#then does not modify the output", async () => {
+        const handler = createDelegateRetryHandler();
+        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).toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given a task tool with case-insensitive matching", () => {
+    describe("#when the tool name is TASK in uppercase", () => {
+      it("#then still detects the error and injects guidance", async () => {
+        const handler = createDelegateRetryHandler();
+        const input = { tool: "TASK", sessionID: "s1", callID: "c1", args: {} };
+        const output = {
+          title: "task",
+          output: "[ERROR] Agent name cannot be empty",
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toContain("empty_agent");
+        expect(output.output).toContain("[task CALL FAILED - IMMEDIATE RETRY REQUIRED]");
+      });
+    });
+  });
+
+  describe("#given a non-task tool", () => {
+    describe("#when the tool is Bash with error markers in output", () => {
+      it("#then does not inject guidance", async () => {
+        const handler = createDelegateRetryHandler();
+        const input = { tool: "Bash", sessionID: "s1", callID: "c1", args: {} };
+        const original = "[ERROR] Invalid arguments: run_in_background is required";
+        const output = { title: "Bash", output: original, metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(original);
+      });
+    });
+  });
+});
+
+describe("detectDelegateTaskError", () => {
+  describe("#given output with [ERROR] and a known pattern", () => {
+    describe("#when output matches load_skills pattern", () => {
+      it("#then returns missing_load_skills error", () => {
+        const result = detectDelegateTaskError(
+          "[ERROR] Invalid arguments: load_skills parameter is missing",
+        );
+        expect(result).not.toBeNull();
+        expect(result?.errorType).toBe("missing_load_skills");
+        expect(result?.originalOutput).toContain("load_skills");
+      });
+    });
+
+    describe("#when output matches Skills not found pattern", () => {
+      it("#then returns unknown_skills error", () => {
+        const result = detectDelegateTaskError(
+          "[ERROR] Skills not found: badskill. Available skills: git-master",
+        );
+        expect(result).not.toBeNull();
+        expect(result?.errorType).toBe("unknown_skills");
+      });
+    });
+  });
+
+  describe("#given output with [ERROR] but no known pattern", () => {
+    describe("#when the error text does not match any pattern", () => {
+      it("#then returns null", () => {
+        const result = detectDelegateTaskError("[ERROR] Some completely unknown error occurred");
+        expect(result).toBeNull();
+      });
+    });
+  });
+
+  describe("#given output without any error markers", () => {
+    describe("#when output is a success message", () => {
+      it("#then returns null", () => {
+        const result = detectDelegateTaskError("All tasks completed.");
+        expect(result).toBeNull();
+      });
+    });
+  });
+});
+
+describe("buildRetryGuidance", () => {
+  describe("#given a detected error with Available list in output", () => {
+    describe("#when the original output contains Available categories", () => {
+      it("#then includes the available options in guidance", () => {
+        const guidance = buildRetryGuidance({
+          errorType: "unknown_category",
+          originalOutput:
+            "[ERROR] Unknown category: foo. Available categories: general, quick, visual-engineering",
+        });
+
+        expect(guidance).toContain("Available Options");
+        expect(guidance).toContain("general, quick, visual-engineering");
+      });
+    });
+  });
+
+  describe("#given a detected error without Available list", () => {
+    describe("#when the original output has no Available section", () => {
+      it("#then returns guidance without Available Options", () => {
+        const guidance = buildRetryGuidance({
+          errorType: "missing_run_in_background",
+          originalOutput: "[ERROR] run_in_background is required",
+        });
+
+        expect(guidance).toContain("missing_run_in_background");
+        expect(guidance).toContain("IMMEDIATE RETRY REQUIRED");
+        expect(guidance).not.toContain("Available Options");
+      });
+    });
+  });
+
+  describe("#given an unrecognized error type", () => {
+    describe("#when errorType is not in DELEGATE_TASK_ERROR_PATTERNS", () => {
+      it("#then returns generic fallback guidance", () => {
+        const guidance = buildRetryGuidance({
+          errorType: "totally_made_up_error",
+          originalOutput: "[ERROR] something",
+        });
+
+        expect(guidance).toContain("[task ERROR]");
+        expect(guidance).toContain("Fix the error");
+      });
+    });
+  });
+});

package/src/hooks/delegate-retry/handler.ts

@@ -0,0 +1,137 @@
+import type { PluginHookContributions } from "../../types/hook";
+import { log } from "../../shared/logger";
+
+type PostToolUseHook = NonNullable<PluginHookContributions["tool.execute.after"]>;
+
+export interface DelegateTaskErrorPattern {
+  pattern: string;
+  errorType: string;
+  fixHint: string;
+}
+
+export const DELEGATE_TASK_ERROR_PATTERNS: DelegateTaskErrorPattern[] = [
+  {
+    pattern: "run_in_background",
+    errorType: "missing_run_in_background",
+    fixHint:
+      "Add run_in_background=false (for delegation) or run_in_background=true (for parallel exploration)",
+  },
+  {
+    pattern: "load_skills",
+    errorType: "missing_load_skills",
+    fixHint:
+      "Add load_skills=[] parameter (empty array if no skills needed). Note: Calling Skill tool does NOT populate this.",
+  },
+  {
+    pattern: "category OR subagent_type",
+    errorType: "mutual_exclusion",
+    fixHint:
+      "Provide ONLY one of: category (e.g., 'general', 'quick') OR subagent_type (e.g., 'oracle', 'explore')",
+  },
+  {
+    pattern: "Must provide either category or subagent_type",
+    errorType: "missing_category_or_agent",
+    fixHint: "Add either category='general' OR subagent_type='explore'",
+  },
+  {
+    pattern: "Unknown category",
+    errorType: "unknown_category",
+    fixHint: "Use a valid category from the Available list in the error message",
+  },
+  {
+    pattern: "Agent name cannot be empty",
+    errorType: "empty_agent",
+    fixHint: "Provide a non-empty subagent_type value",
+  },
+  {
+    pattern: "Unknown agent",
+    errorType: "unknown_agent",
+    fixHint: "Use a valid agent from the Available agents list in the error message",
+  },
+  {
+    pattern: "Cannot call primary agent",
+    errorType: "primary_agent",
+    fixHint:
+      "Primary agents cannot be called via task. Use a subagent like 'explore', 'oracle', or 'librarian'",
+  },
+  {
+    pattern: "Skills not found",
+    errorType: "unknown_skills",
+    fixHint: "Use valid skill names from the Available list in the error message",
+  },
+];
+
+export interface DetectedError {
+  errorType: string;
+  originalOutput: string;
+}
+
+export function detectDelegateTaskError(output: string): DetectedError | null {
+  if (!output.includes("[ERROR]") && !output.includes("Invalid arguments")) return null;
+
+  for (const errorPattern of DELEGATE_TASK_ERROR_PATTERNS) {
+    if (output.includes(errorPattern.pattern)) {
+      return {
+        errorType: errorPattern.errorType,
+        originalOutput: output,
+      };
+    }
+  }
+
+  return null;
+}
+
+function extractAvailableList(output: string): string | null {
+  const availableMatch = output.match(/Available[^:]*:\s*(.+)$/m);
+  return availableMatch ? (availableMatch[1]?.trim() ?? null) : null;
+}
+
+export function buildRetryGuidance(errorInfo: DetectedError): string {
+  const pattern = DELEGATE_TASK_ERROR_PATTERNS.find((p) => p.errorType === errorInfo.errorType);
+
+  if (!pattern) {
+    return `[task ERROR] Fix the error and retry with correct parameters.`;
+  }
+
+  let guidance = `\n[task CALL FAILED - IMMEDIATE RETRY REQUIRED]\n\n**Error Type**: ${errorInfo.errorType}\n**Fix**: ${pattern.fixHint}\n`;
+
+  const availableList = extractAvailableList(errorInfo.originalOutput);
+  if (availableList) {
+    guidance += `\n**Available Options**: ${availableList}\n`;
+  }
+
+  guidance += `\n**Action**: Retry task NOW with corrected parameters.\n`;
+
+  return guidance;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function createDelegateRetryHandler(): PostToolUseHook {
+  return async (input: unknown, output: unknown) => {
+    if (!isRecord(input) || !isRecord(output)) {
+      return;
+    }
+
+    const tool = input.tool;
+    if (typeof tool !== "string" || tool.toLowerCase() !== "task") {
+      return;
+    }
+
+    const toolOutput = output.output;
+    if (typeof toolOutput !== "string") {
+      return;
+    }
+
+    const errorInfo = detectDelegateTaskError(toolOutput);
+    if (!errorInfo) {
+      return;
+    }
+
+    const guidance = buildRetryGuidance(errorInfo);
+    output.output = `${toolOutput}\n${guidance}`;
+    log("[delegate-retry] injected retry guidance", { errorType: errorInfo.errorType });
+  };
+}

package/src/hooks/delegate-retry/index.ts

@@ -0,0 +1,8 @@
+export { delegateRetryPlugin } from "./plugin";
+export {
+  createDelegateRetryHandler,
+  detectDelegateTaskError,
+  buildRetryGuidance,
+  DELEGATE_TASK_ERROR_PATTERNS,
+} from "./handler";
+export type { DelegateTaskErrorPattern, DetectedError } from "./handler";

package/src/hooks/delegate-retry/plugin.ts

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

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);
+      });
+    });
+  });
+});