goatcode-sh 0.0.1 → 0.1.3

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

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

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "bun:test";
+
+import { createContextWindowLimitHandler } from "./context-window-limit";
+import { createEditErrorHandler } from "./edit-error";
+import { createJsonErrorHandler } from "./json-error";
+import { createSessionRecoveryHandler } from "./session-recovery";
+
+describe("error recovery hooks", () => {
+  describe("#given edit-error hook", () => {
+    describe("#when Edit tool returns oldString not found", () => {
+      it("#then recovery guidance is appended", async () => {
+        const handler = createEditErrorHandler();
+        const input = { tool: "Edit" };
+        const output = { output: "Edit failed: oldString not found in target file" };
+
+        await handler(input, output);
+
+        expect(output.output).toContain("[EDIT ERROR RECOVERY]");
+      });
+    });
+  });
+
+  describe("#given json-error hook", () => {
+    describe("#when JSON parse failure text is returned", () => {
+      it("#then JSON recovery guidance is appended", async () => {
+        const handler = createJsonErrorHandler();
+        const input = { tool: "task" };
+        const output = { output: "JSON parse error: unexpected end of JSON input" };
+
+        await handler(input, output);
+
+        expect(output.output).toContain("[JSON ERROR RECOVERY]");
+      });
+    });
+  });
+
+  describe("#given session-recovery hook", () => {
+    describe("#when session.error reports disconnect", () => {
+      it("#then recovery context is injected into event properties", async () => {
+        const handler = createSessionRecoveryHandler();
+        const payload = {
+          event: {
+            type: "session.error",
+            properties: {
+              error: "session disconnect: socket hang up",
+            },
+          },
+        };
+
+        await handler(payload);
+
+        const recoveryContext = (payload.event.properties as { recoveryContext?: string })
+          .recoveryContext;
+        expect(recoveryContext).toContain("[SESSION RECOVERY]");
+      });
+    });
+  });
+
+  describe("#given context-window-limit hook", () => {
+    describe("#when session.idle reports high context usage", () => {
+      it("#then compact and summarize actions are injected", async () => {
+        const handler = createContextWindowLimitHandler();
+        const payload = {
+          event: {
+            type: "session.idle",
+            properties: {
+              contextWindowUsage: 0.95,
+            },
+          },
+        };
+
+        await handler(payload);
+
+        const properties = payload.event.properties as {
+          recoveryActions?: string[];
+          recoveryContext?: string;
+        };
+
+        expect(properties.recoveryActions).toContain("compact");
+        expect(properties.recoveryActions).toContain("summarize");
+        expect(properties.recoveryContext).toContain("[CONTEXT WINDOW LIMIT RECOVERY]");
+      });
+    });
+  });
+});

package/src/hooks/foreground-fallback/handler.test.ts

@@ -0,0 +1,229 @@
+import { describe, expect, it, mock } from "bun:test";
+import { createForegroundFallbackHandler } from "./handler";
+
+type GenericHook = (input: unknown) => Promise<void>;
+
+describe("createForegroundFallbackHandler", () => {
+  describe("#given a handler with a fallback chain", () => {
+    describe("#when a rate-limit error (429) occurs on session.error", () => {
+      it("#then switches to the next model and sets retry properties", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+        const onFallbackApplied = mock(() => {});
+        const onRetryRequested = mock(() => {});
+
+        const handler = createForegroundFallbackHandler({
+          setCurrentModel,
+          onFallbackApplied,
+          onRetryRequested,
+        }) as unknown as GenericHook;
+
+        const properties: Record<string, unknown> = {
+          sessionID: "ses-fg-429",
+          model: "anthropic/claude-3-5-sonnet",
+          error: { statusCode: 429, message: "Rate limit exceeded" },
+          fallbackChain: ["anthropic/claude-3-5-sonnet", "openai/gpt-4o", "google/gemini-2.5-pro"],
+        };
+        await handler({
+          event: {
+            type: "session.error",
+            properties,
+          },
+        });
+
+        expect(setCurrentModel).toHaveBeenCalledTimes(1);
+        expect(setCurrentModel).toHaveBeenCalledWith("ses-fg-429", "openai/gpt-4o");
+        expect(properties.retryRequested).toBe(true);
+        expect(properties.retryWithModel).toBe("openai/gpt-4o");
+        expect(onFallbackApplied).toHaveBeenCalledTimes(1);
+        expect(onRetryRequested).toHaveBeenCalledTimes(1);
+      });
+    });
+
+    describe("#when a 'too many requests' message triggers on session.error", () => {
+      it("#then detects rate-limit via message pattern matching", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createForegroundFallbackHandler({
+          setCurrentModel,
+        }) as unknown as GenericHook;
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-fg-msg",
+              model: "openai/gpt-4o",
+              error: { message: "Too many requests, please slow down" },
+              fallbackChain: ["openai/gpt-4o", "anthropic/claude-3-5-sonnet"],
+            },
+          },
+        });
+
+        expect(setCurrentModel).toHaveBeenCalledTimes(1);
+        expect(setCurrentModel).toHaveBeenCalledWith("ses-fg-msg", "anthropic/claude-3-5-sonnet");
+      });
+    });
+
+    describe("#when error message contains 'quota exceeded'", () => {
+      it("#then also recognizes as rate-limit error", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createForegroundFallbackHandler({
+          setCurrentModel,
+        }) as unknown as GenericHook;
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-fg-quota",
+              model: "openai/gpt-4o",
+              error: { message: "Quota exceeded for this billing period" },
+              fallbackChain: ["openai/gpt-4o", "google/gemini-2.5-pro"],
+            },
+          },
+        });
+
+        expect(setCurrentModel).toHaveBeenCalledTimes(1);
+        expect(setCurrentModel).toHaveBeenCalledWith("ses-fg-quota", "google/gemini-2.5-pro");
+      });
+    });
+  });
+
+  describe("#given a non-rate-limit error", () => {
+    describe("#when a 400 Bad Request occurs", () => {
+      it("#then does not trigger fallback", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createForegroundFallbackHandler({
+          setCurrentModel,
+        }) as unknown as GenericHook;
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-fg-400",
+              model: "openai/gpt-4o",
+              error: { statusCode: 400, message: "Bad request" },
+              fallbackChain: ["openai/gpt-4o", "anthropic/claude-3-5-sonnet"],
+            },
+          },
+        });
+
+        expect(setCurrentModel).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("#given a non-error event type", () => {
+    describe("#when event type is session.idle", () => {
+      it("#then does nothing", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createForegroundFallbackHandler({
+          setCurrentModel,
+        }) as unknown as GenericHook;
+
+        await handler({
+          event: {
+            type: "session.idle",
+            properties: {
+              sessionID: "ses-fg-idle",
+              model: "openai/gpt-4o",
+            },
+          },
+        });
+
+        expect(setCurrentModel).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("#given a rate-limit on message.updated event", () => {
+    describe("#when info.error contains a rate-limit error", () => {
+      it("#then triggers fallback via message.updated path", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createForegroundFallbackHandler({
+          setCurrentModel,
+        }) as unknown as GenericHook;
+
+        await handler({
+          event: {
+            type: "message.updated",
+            properties: {
+              sessionID: "ses-fg-msgupdated",
+              model: "anthropic/claude-3-5-sonnet",
+              info: {
+                error: { statusCode: 429, message: "Rate limit" },
+              },
+              fallbackChain: ["anthropic/claude-3-5-sonnet", "openai/gpt-4o"],
+            },
+          },
+        });
+
+        expect(setCurrentModel).toHaveBeenCalledTimes(1);
+        expect(setCurrentModel).toHaveBeenCalledWith("ses-fg-msgupdated", "openai/gpt-4o");
+      });
+    });
+  });
+
+  describe("#given no session ID in the event", () => {
+    describe("#when properties lack sessionID and info.id", () => {
+      it("#then does nothing", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createForegroundFallbackHandler({
+          setCurrentModel,
+        }) as unknown as GenericHook;
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              model: "openai/gpt-4o",
+              error: { statusCode: 429, message: "Rate limit" },
+              fallbackChain: ["openai/gpt-4o", "anthropic/claude-3-5-sonnet"],
+            },
+          },
+        });
+
+        expect(setCurrentModel).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("#given deduplication window", () => {
+    describe("#when the same rate-limit fires twice within 5 seconds", () => {
+      it("#then only triggers fallback once", async () => {
+        let currentTime = 1000000;
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createForegroundFallbackHandler({
+          setCurrentModel,
+          now: () => currentTime,
+        }) as unknown as GenericHook;
+
+        const makeEvent = () => ({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-fg-dedup",
+              model: "anthropic/claude-3-5-sonnet",
+              error: { statusCode: 429, message: "Rate limit" },
+              fallbackChain: ["anthropic/claude-3-5-sonnet", "openai/gpt-4o"],
+            },
+          },
+        });
+
+        await handler(makeEvent());
+        expect(setCurrentModel).toHaveBeenCalledTimes(1);
+
+        currentTime += 2000;
+        await handler(makeEvent());
+        expect(setCurrentModel).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
+});