goatcode-sh 0.0.1 → 0.1.3

package/src/hooks/context-window-limit/handler.ts

@@ -0,0 +1,128 @@
+import type { PluginHookContributions } from "../../types/hook";
+import { log } from "../../shared/logger";
+
+export const CONTEXT_WINDOW_LIMIT_PATTERNS = [
+  /context window/i,
+  /token limit/i,
+  /maximum context length/i,
+  /prompt is too long/i,
+  /too many tokens/i,
+] as const;
+
+const CONTEXT_WINDOW_LIMIT_MARKER = "[CONTEXT WINDOW LIMIT RECOVERY]";
+
+export const CONTEXT_WINDOW_LIMIT_RECOVERY_MESSAGE = `${CONTEXT_WINDOW_LIMIT_MARKER}\nContext usage is near the limit. Compact older turns, summarize large tool outputs, and continue with a reduced context footprint.`;
+
+type EventHook = NonNullable<PluginHookContributions["event"]>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function toUsageRatio(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return null;
+  }
+
+  if (value > 1) {
+    return value / 100;
+  }
+
+  return value;
+}
+
+function extractErrorText(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;
+  }
+
+  return "";
+}
+
+function appendRecoveryActions(properties: Record<string, unknown>): void {
+  const existing = properties.recoveryActions;
+  if (Array.isArray(existing)) {
+    const actions = new Set(existing.filter((value): value is string => typeof value === "string"));
+    actions.add("compact");
+    actions.add("summarize");
+    properties.recoveryActions = [...actions];
+    return;
+  }
+
+  properties.recoveryActions = ["compact", "summarize"];
+}
+
+function appendRecoveryContext(properties: Record<string, unknown>): void {
+  const existing = properties.recoveryContext;
+  if (typeof existing === "string" && existing.includes(CONTEXT_WINDOW_LIMIT_MARKER)) {
+    return;
+  }
+
+  if (typeof existing === "string" && existing.length > 0) {
+    properties.recoveryContext = `${existing}\n${CONTEXT_WINDOW_LIMIT_RECOVERY_MESSAGE}`;
+    return;
+  }
+
+  properties.recoveryContext = CONTEXT_WINDOW_LIMIT_RECOVERY_MESSAGE;
+}
+
+function isNearLimitSessionIdle(
+  event: Record<string, unknown>,
+  properties: Record<string, unknown>,
+): boolean {
+  if (event.type !== "session.idle") {
+    return false;
+  }
+
+  const ratio =
+    toUsageRatio(properties.contextWindowUsage) ??
+    toUsageRatio(properties.contextWindowUsagePct) ??
+    toUsageRatio(properties.contextUsage);
+
+  return ratio !== null && ratio >= 0.9;
+}
+
+function isTokenLimitError(
+  event: Record<string, unknown>,
+  properties: Record<string, unknown>,
+): boolean {
+  if (event.type !== "session.error") {
+    return false;
+  }
+
+  const errorText = extractErrorText(properties);
+  return CONTEXT_WINDOW_LIMIT_PATTERNS.some((pattern) => pattern.test(errorText));
+}
+
+export function createContextWindowLimitHandler(): EventHook {
+  return async (input: unknown) => {
+    if (!isRecord(input)) {
+      return;
+    }
+
+    const event = input.event;
+    if (!isRecord(event)) {
+      return;
+    }
+
+    const properties = event.properties;
+    if (!isRecord(properties)) {
+      return;
+    }
+
+    const shouldRecover =
+      isNearLimitSessionIdle(event, properties) || isTokenLimitError(event, properties);
+    if (!shouldRecover) {
+      return;
+    }
+
+    appendRecoveryActions(properties);
+    appendRecoveryContext(properties);
+    log("[context-window-limit] injected compaction and summarization recovery");
+  };
+}

package/src/hooks/context-window-limit/index.ts

@@ -0,0 +1,6 @@
+export { contextWindowLimitPlugin } from "./plugin";
+export {
+  createContextWindowLimitHandler,
+  CONTEXT_WINDOW_LIMIT_PATTERNS,
+  CONTEXT_WINDOW_LIMIT_RECOVERY_MESSAGE,
+} from "./handler";

package/src/hooks/context-window-limit/plugin.ts

@@ -0,0 +1,15 @@
+import { definePlugin } from "../../plugin-api/define-plugin";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createContextWindowLimitHandler } from "./handler";
+
+const eventHook = safeCreateHook("context-window-limit", createContextWindowLimitHandler);
+
+export const contextWindowLimitPlugin = definePlugin({
+  name: "context-window-limit",
+  version: "0.1.0",
+  hooks: eventHook
+    ? {
+        event: eventHook,
+      }
+    : {},
+});

package/src/hooks/continuation.test.ts

@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import {
+  clearSessionStore,
+  getSessionState,
+  setSessionState,
+} from "../features/session-state/session-store";
+import { createCompactionTodoPreserverHandler } from "./compaction-todo-preserver/handler";
+import { createStopGuardHandler } from "./stop-guard/handler";
+import { createTodoEnforcerHandler } from "./todo-enforcer/handler";
+
+type MutableTodoState = {
+  todos?: Array<{
+    content: string;
+    status: "pending" | "in_progress" | "completed" | "cancelled";
+  }>;
+};
+
+type GenericHook = (input: unknown, output?: unknown) => Promise<void>;
+
+function seedTodos(sessionID: string, todos: NonNullable<MutableTodoState["todos"]>): void {
+  setSessionState(sessionID, { status: "active" });
+  const state = getSessionState(sessionID) as unknown as MutableTodoState | undefined;
+  if (!state) {
+    return;
+  }
+  state.todos = todos;
+}
+
+describe("continuation hooks", () => {
+  beforeEach(() => {
+    clearSessionStore();
+  });
+
+  describe("#given todo-enforcer", () => {
+    describe("#when session.idle occurs with pending todos", () => {
+      it("#then injects a continuation message for the next todo", async () => {
+        const sessionID = "session-idle-with-todos";
+        seedTodos(sessionID, [
+          { content: "Implement hook wiring", status: "pending" },
+          { content: "Run typecheck", status: "completed" },
+        ]);
+        const handler = createTodoEnforcerHandler() as unknown as GenericHook;
+        const input = {
+          event: {
+            type: "session.idle",
+            properties: { sessionID },
+          },
+        };
+
+        await handler(input);
+
+        const properties = input.event.properties as Record<string, unknown>;
+        expect(typeof properties.continuationMessage).toBe("string");
+        expect(String(properties.continuationMessage)).toContain("Implement hook wiring");
+      });
+    });
+  });
+
+  describe("#given compaction-todo-preserver", () => {
+    describe("#when compaction runs with todo state", () => {
+      it("#then prepends todo snapshot to compacted context", async () => {
+        const sessionID = "session-compaction";
+        seedTodos(sessionID, [
+          { content: "First pending task", status: "pending" },
+          { content: "Current in-progress task", status: "in_progress" },
+        ]);
+        const handler = createCompactionTodoPreserverHandler() as unknown as GenericHook;
+        const input = {
+          event: {
+            type: "session.compacted",
+            properties: { sessionID },
+          },
+        };
+        const output = { context: ["existing compacted context"] };
+
+        await handler(input, output);
+
+        expect(output.context[0]).toContain("compaction-todo-preserver");
+        expect(output.context[0]).toContain("First pending task");
+        expect(output.context[1]).toBe("existing compacted context");
+      });
+    });
+  });
+
+  describe("#given stop-guard", () => {
+    describe("#when a stop-like message arrives while todos are pending", () => {
+      it("#then injects a continue-working reminder", async () => {
+        const sessionID = "session-stop-guard";
+        seedTodos(sessionID, [{ content: "Finish final verification", status: "pending" }]);
+        const handler = createStopGuardHandler() as unknown as GenericHook;
+        const input = {
+          sessionID,
+          message: "I'm done.",
+        } as Record<string, unknown>;
+
+        await handler(input);
+
+        expect(typeof input.stopGuardMessage).toBe("string");
+        expect(String(input.stopGuardMessage)).toContain("Finish final verification");
+      });
+    });
+  });
+});

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