goatcode-sh 0.0.1 → 0.1.2

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

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

@@ -0,0 +1,135 @@
+import type { PluginHookContributions } from "../../types/hook";
+import { log } from "../../shared/logger";
+import { matchDiagnostic } from "./patterns";
+
+const ERROR_DIAGNOSTIC_MARKER = "[ERROR DIAGNOSTIC]";
+
+type PostToolUseHook = NonNullable<PluginHookContributions["tool.execute.after"]>;
+type EventHook = NonNullable<PluginHookContributions["event"]>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function appendDiagnosticBlock(text: string, diagnosticText: string): string {
+  if (text.includes(ERROR_DIAGNOSTIC_MARKER)) {
+    return text;
+  }
+
+  return `${text}\n${diagnosticText}`;
+}
+
+function buildDiagnosticText(category: string, severity: string, suggestion: string): string {
+  return `${ERROR_DIAGNOSTIC_MARKER}\nCategory: ${category}\nSeverity: ${severity}\nSuggestion: ${suggestion}`;
+}
+
+function extractErrorTextFromProperties(properties: Record<string, unknown>): string {
+  const rawError = properties.error;
+  if (typeof rawError === "string") {
+    return rawError;
+  }
+
+  if (isRecord(rawError) && typeof rawError.message === "string") {
+    return rawError.message;
+  }
+
+  const message = properties.message;
+  if (typeof message === "string") {
+    return message;
+  }
+
+  return "";
+}
+
+function appendRecoveryContext(properties: Record<string, unknown>, diagnosticText: string): void {
+  const existing = properties.recoveryContext;
+  if (typeof existing === "string" && existing.includes(ERROR_DIAGNOSTIC_MARKER)) {
+    return;
+  }
+
+  if (typeof existing === "string" && existing.length > 0) {
+    properties.recoveryContext = `${existing}\n${diagnosticText}`;
+    return;
+  }
+
+  properties.recoveryContext = diagnosticText;
+}
+
+export function createToolErrorHandler(): PostToolUseHook {
+  return async (_input: unknown, output: unknown) => {
+    try {
+      if (!isRecord(output)) {
+        return;
+      }
+
+      const toolOutput = output.output;
+      if (typeof toolOutput !== "string" || toolOutput.includes(ERROR_DIAGNOSTIC_MARKER)) {
+        return;
+      }
+
+      const diagnostic = matchDiagnostic(toolOutput);
+      if (!diagnostic) {
+        return;
+      }
+
+      const diagnosticText = buildDiagnosticText(
+        diagnostic.category,
+        diagnostic.severity,
+        diagnostic.suggestion,
+      );
+
+      output.output = appendDiagnosticBlock(toolOutput, diagnosticText);
+      log("[error-diagnostics] injected tool error diagnostic", {
+        category: diagnostic.category,
+        severity: diagnostic.severity,
+      });
+    } catch (error) {
+      log("[error-diagnostics] tool.execute.after handling failed", { error: String(error) });
+    }
+  };
+}
+
+export function createEventErrorHandler(): EventHook {
+  return async (input: unknown) => {
+    try {
+      if (!isRecord(input)) {
+        return;
+      }
+
+      const event = input.event;
+      if (!isRecord(event) || event.type !== "session.error") {
+        return;
+      }
+
+      const properties = event.properties;
+      if (!isRecord(properties)) {
+        return;
+      }
+
+      const errorText = extractErrorTextFromProperties(properties);
+      if (errorText.includes(ERROR_DIAGNOSTIC_MARKER)) {
+        return;
+      }
+
+      const diagnostic = matchDiagnostic(errorText);
+      if (!diagnostic) {
+        return;
+      }
+
+      const diagnosticText = buildDiagnosticText(
+        diagnostic.category,
+        diagnostic.severity,
+        diagnostic.suggestion,
+      );
+
+      appendRecoveryContext(properties, diagnosticText);
+      log("[error-diagnostics] injected event recovery diagnostic", {
+        eventType: event.type,
+        category: diagnostic.category,
+        severity: diagnostic.severity,
+      });
+    } catch (error) {
+      log("[error-diagnostics] event handling failed", { error: String(error) });
+    }
+  };
+}

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

@@ -0,0 +1,93 @@
+import type { DiagnosticPattern, DiagnosticResult } from "./types";
+
+export const DIAGNOSTIC_PATTERNS: DiagnosticPattern[] = [
+  {
+    category: "rate-limit",
+    patterns: [/rate limit/i, /too many requests/i, /429/i, /quota exceeded/i],
+    severity: "warning",
+    suggestion:
+      "Rate limited. Wait 30-60 seconds then retry. If persistent, check API quota or switch to a different model.",
+  },
+  {
+    category: "auth",
+    patterns: [/unauthorized/i, /invalid.*api.*key/i, /authentication failed/i, /403 forbidden/i],
+    severity: "error",
+    suggestion: "Authentication failed. Verify API key is set correctly and has not expired.",
+  },
+  {
+    category: "timeout",
+    patterns: [/timeout/i, /timed out/i, /deadline exceeded/i, /ETIMEDOUT/i],
+    severity: "warning",
+    suggestion:
+      "Request timed out. Try a shorter prompt, reduce context size, or check network connectivity.",
+  },
+  {
+    category: "permission",
+    patterns: [/permission denied/i, /EACCES/i, /operation not permitted/i],
+    severity: "error",
+    suggestion:
+      "Permission denied. Check file/directory permissions or run with appropriate privileges.",
+  },
+  {
+    category: "file-system",
+    patterns: [/ENOENT/i, /no such file/i, /file not found/i, /EEXIST/i, /directory not empty/i],
+    severity: "error",
+    suggestion:
+      "File system error. Verify the path exists and is accessible. Check for typos in file paths.",
+  },
+  {
+    category: "network",
+    patterns: [
+      /ECONNREFUSED/i,
+      /ENOTFOUND/i,
+      /network.*error/i,
+      /fetch failed/i,
+      /socket hang up/i,
+    ],
+    severity: "error",
+    suggestion:
+      "Network error. Check internet connectivity and that the target service is running.",
+  },
+  {
+    category: "memory",
+    patterns: [/out of memory/i, /heap.*limit/i, /allocation failed/i, /JavaScript heap/i],
+    severity: "error",
+    suggestion:
+      "Memory limit reached. Reduce context window size, compact the session, or restart with fewer files loaded.",
+  },
+  {
+    category: "syntax",
+    patterns: [/SyntaxError/i, /unexpected token/i, /parsing error/i],
+    severity: "error",
+    suggestion:
+      "Syntax error detected. Check for malformed code, missing brackets, or invalid characters.",
+  },
+  {
+    category: "type-error",
+    patterns: [/TypeError/i, /is not a function/i, /cannot read propert/i, /undefined is not/i],
+    severity: "error",
+    suggestion:
+      "Type error. Check that the variable exists and is the expected type before accessing properties.",
+  },
+];
+
+export function matchDiagnostic(text: string): DiagnosticResult | null {
+  for (const diagnosticPattern of DIAGNOSTIC_PATTERNS) {
+    for (const pattern of diagnosticPattern.patterns) {
+      const match = text.match(pattern);
+      if (!match) {
+        continue;
+      }
+
+      return {
+        category: diagnosticPattern.category,
+        severity: diagnosticPattern.severity,
+        matched: match[0],
+        suggestion: diagnosticPattern.suggestion,
+        timestamp: new Date().toISOString(),
+      };
+    }
+  }
+
+  return null;
+}

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

@@ -0,0 +1,11 @@
+import { definePlugin } from "../../plugin-api";
+import { createEventErrorHandler, createToolErrorHandler } from "./handler";
+
+export const errorDiagnosticsPlugin = definePlugin({
+  name: "error-diagnostics",
+  version: "0.1.0",
+  hooks: {
+    "tool.execute.after": createToolErrorHandler(),
+    event: createEventErrorHandler(),
+  },
+});

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

@@ -0,0 +1,26 @@
+export type ErrorCategory =
+  | "rate-limit"
+  | "auth"
+  | "timeout"
+  | "permission"
+  | "file-system"
+  | "network"
+  | "memory"
+  | "syntax"
+  | "type-error"
+  | "unknown";
+
+export type DiagnosticPattern = {
+  category: ErrorCategory;
+  patterns: RegExp[];
+  severity: "error" | "warning" | "info";
+  suggestion: string;
+};
+
+export type DiagnosticResult = {
+  category: ErrorCategory;
+  severity: string;
+  matched: string;
+  suggestion: string;
+  timestamp: string;
+};