goatcode-sh 0.0.1 → 0.1.2

package/src/hooks/model-management.test.ts

@@ -0,0 +1,121 @@
+declare const require: (name: string) => any;
+
+const { describe, expect, it, mock } = require("bun:test");
+import { createModelFallbackHandler, modelFallbackPlugin } from "./model-fallback";
+import { createRuntimeFallbackHandler, runtimeFallbackPlugin } from "./runtime-fallback";
+import {
+  createPreemptiveCompactionHandler,
+  preemptiveCompactionPlugin,
+} from "./preemptive-compaction";
+
+describe("model management hooks", () => {
+  describe("#given model-fallback receives rate-limit errors", () => {
+    describe("#when session.error is emitted with status 429", () => {
+      it("#then switches to the next model in fallback chain", async () => {
+        const sessionModels = new Map<string, string>([["ses-model", "openai/gpt-5"]]);
+        const onFallbackApplied = mock(() => undefined);
+
+        const handler = createModelFallbackHandler({
+          getCurrentModel: (sessionID) => sessionModels.get(sessionID),
+          setCurrentModel: (sessionID, model) => {
+            sessionModels.set(sessionID, model);
+          },
+          onFallbackApplied,
+        });
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-model",
+              model: "openai/gpt-5",
+              error: { statusCode: 429, message: "Too many requests" },
+              fallbackChain: ["openai/gpt-5", "openai/gpt-4.1-mini", "anthropic/claude-3.7-sonnet"],
+            },
+          },
+        });
+
+        expect(sessionModels.get("ses-model")).toBe("openai/gpt-4.1-mini");
+        expect(onFallbackApplied).toHaveBeenCalledTimes(1);
+      });
+    });
+  });
+
+  describe("#given runtime-fallback receives model/runtime errors", () => {
+    describe("#when session.error reports model not found", () => {
+      it("#then switches to a compatible fallback model", async () => {
+        const sessionModels = new Map<string, string>([["ses-runtime", "openai/gpt-5"]]);
+
+        const handler = createRuntimeFallbackHandler({
+          getCurrentModel: (sessionID) => sessionModels.get(sessionID),
+          setCurrentModel: (sessionID, model) => {
+            sessionModels.set(sessionID, model);
+          },
+        });
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-runtime",
+              model: "openai/gpt-5",
+              error: { message: "Model not found for this provider" },
+              fallbackChain: [
+                "anthropic/claude-3.7-sonnet",
+                "openai/gpt-4.1-mini",
+                "google/gemini-2.5-pro",
+              ],
+            },
+          },
+        });
+
+        expect(sessionModels.get("ses-runtime")).toBe("openai/gpt-4.1-mini");
+      });
+    });
+  });
+
+  describe("#given preemptive-compaction monitors token usage", () => {
+    describe("#when usage crosses and recrosses the 80% threshold", () => {
+      it("#then triggers compaction once per high-usage window", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          sessionID: "ses-compact",
+          usage: { inputTokens: 170_000, cacheReadTokens: 0 },
+          contextLimit: 200_000,
+        });
+
+        await handler({
+          sessionID: "ses-compact",
+          usage: { inputTokens: 175_000, cacheReadTokens: 0 },
+          contextLimit: 200_000,
+        });
+
+        await handler({
+          sessionID: "ses-compact",
+          usage: { inputTokens: 100_000, cacheReadTokens: 0 },
+          contextLimit: 200_000,
+        });
+
+        await handler({
+          sessionID: "ses-compact",
+          usage: { inputTokens: 180_000, cacheReadTokens: 0 },
+          contextLimit: 200_000,
+        });
+
+        expect(compactSession).toHaveBeenCalledTimes(2);
+      });
+    });
+  });
+
+  describe("#given hook micro-plugins are created", () => {
+    describe("#when each plugin registers hooks", () => {
+      it("#then wires event/message handlers through definePlugin", () => {
+        expect(typeof modelFallbackPlugin.hooks?.event).toBe("function");
+        expect(typeof runtimeFallbackPlugin.hooks?.event).toBe("function");
+        expect(typeof preemptiveCompactionPlugin.hooks?.["chat.message"]).toBe("function");
+      });
+    });
+  });
+});

package/src/hooks/phase-reminder/handler.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "bun:test";
+import type { HookHandler } from "../../types/hook";
+import { createPhaseReminderHandler, PHASE_REMINDER } from "./handler";
+
+const createHandler = (): HookHandler => createPhaseReminderHandler() as HookHandler;
+
+describe("createPhaseReminderHandler", () => {
+  describe("#given a user message from the orchestrator agent", () => {
+    describe("#when the handler processes messages", () => {
+      it("#then it prepends the phase reminder to the text", async () => {
+        const handler = createHandler();
+        const output = {
+          messages: [
+            {
+              info: { role: "user" },
+              parts: [{ type: "text", text: "Do the task" }],
+            },
+          ],
+        };
+
+        await handler({}, output);
+
+        expect(output.messages[0].parts[0].text).toContain(PHASE_REMINDER);
+        expect(output.messages[0].parts[0].text).toContain("Do the task");
+      });
+    });
+  });
+
+  describe("#given a user message with an explicit orchestrator agent", () => {
+    describe("#when the handler processes messages", () => {
+      it("#then it prepends the phase reminder", async () => {
+        const handler = createHandler();
+        const output = {
+          messages: [
+            {
+              info: { role: "user", agent: "orchestrator" },
+              parts: [{ type: "text", text: "Plan the work" }],
+            },
+          ],
+        };
+
+        await handler({}, output);
+
+        expect(output.messages[0].parts[0].text).toContain(PHASE_REMINDER);
+        expect(output.messages[0].parts[0].text).toContain("Plan the work");
+      });
+    });
+  });
+
+  describe("#given a user message from a non-orchestrator agent", () => {
+    describe("#when the handler processes messages", () => {
+      it("#then it does not modify the text", async () => {
+        const handler = createHandler();
+        const output = {
+          messages: [
+            {
+              info: { role: "user", agent: "worker" },
+              parts: [{ type: "text", text: "Do the task" }],
+            },
+          ],
+        };
+
+        await handler({}, output);
+
+        expect(output.messages[0].parts[0].text).toBe("Do the task");
+      });
+    });
+  });
+
+  describe("#given a message that already contains the reminder", () => {
+    describe("#when the handler processes messages", () => {
+      it("#then it does not double-prepend the reminder", async () => {
+        const handler = createHandler();
+        const existingText = `${PHASE_REMINDER}\n\n---\n\nDo the task`;
+        const output = {
+          messages: [
+            {
+              info: { role: "user" },
+              parts: [{ type: "text", text: existingText }],
+            },
+          ],
+        };
+
+        await handler({}, output);
+
+        const occurrences =
+          output.messages[0].parts[0].text.split("<reminder>Recall Workflow Rules:").length - 1;
+        expect(occurrences).toBe(1);
+      });
+    });
+  });
+
+  describe("#given an empty messages array", () => {
+    describe("#when the handler processes messages", () => {
+      it("#then it is a no-op", async () => {
+        const handler = createHandler();
+        const output = { messages: [] as unknown[] };
+
+        await handler({}, output);
+
+        expect(output.messages).toEqual([]);
+      });
+    });
+  });
+});

package/src/hooks/phase-reminder/handler.ts

@@ -0,0 +1,54 @@
+import type { PluginHookContributions } from "../../types/hook";
+
+type MessagesTransformHook = NonNullable<
+  PluginHookContributions["experimental.chat.messages.transform"]
+>;
+
+export const PHASE_REMINDER = `<reminder>Recall Workflow Rules:
+Understand → choose best path (delegate by rules and parallelize independent work) → execute → verify.
+If mentioning a specialist, launch it in the same turn.</reminder>`;
+
+const REMINDER_PREFIX = "<reminder>Recall Workflow Rules:";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isOrchestratorAgent(agent: unknown): boolean {
+  if (typeof agent !== "string") return true;
+  return agent.toLowerCase() === "orchestrator";
+}
+
+function prependReminder(text: string): string {
+  if (text.includes(REMINDER_PREFIX)) {
+    return text;
+  }
+  return `${PHASE_REMINDER}\n\n---\n\n${text}`;
+}
+
+export function createPhaseReminderHandler(): MessagesTransformHook {
+  return async (_input: unknown, output: unknown) => {
+    if (!isRecord(output)) return;
+
+    const messages = output.messages;
+    if (!Array.isArray(messages) || messages.length === 0) return;
+
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+      const message = messages[index];
+      if (!isRecord(message)) continue;
+
+      const info = message.info;
+      if (!isRecord(info) || info.role !== "user") continue;
+      if (!isOrchestratorAgent(info.agent)) return;
+
+      const parts = message.parts;
+      if (!Array.isArray(parts)) return;
+
+      const textPart = parts.find((part) => part?.type === "text" && typeof part.text === "string");
+      if (!textPart || typeof textPart.text !== "string") return;
+
+      textPart.text = prependReminder(textPart.text);
+      return;
+    }
+  };
+}

package/src/hooks/phase-reminder/index.ts

@@ -0,0 +1,2 @@
+export { createPhaseReminderHandler, PHASE_REMINDER } from "./handler";
+export { phaseReminderPlugin } from "./plugin";

package/src/hooks/phase-reminder/plugin.ts

@@ -0,0 +1,18 @@
+import { definePlugin } from "../../plugin-api";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createPhaseReminderHandler } from "./handler";
+
+const phaseReminderMessagesTransformHook = safeCreateHook(
+  "phase-reminder",
+  createPhaseReminderHandler,
+);
+
+export const phaseReminderPlugin = definePlugin({
+  name: "phase-reminder",
+  version: "0.1.0",
+  hooks: phaseReminderMessagesTransformHook
+    ? {
+        "experimental.chat.messages.transform": phaseReminderMessagesTransformHook,
+      }
+    : {},
+});

package/src/hooks/post-read-nudge/handler.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "bun:test";
+
+import { createPostReadNudgeHandler, POST_READ_NUDGE } from "./handler";
+
+describe("createPostReadNudgeHandler", () => {
+  describe("#given a Read tool call", () => {
+    describe("#when tool.execute.after runs on Read", () => {
+      it("#then appends the workflow nudge to the output", async () => {
+        const handler = createPostReadNudgeHandler();
+        const input = { tool: "Read", sessionID: "s1", callID: "c1", args: {} };
+        const output = { title: "read", output: "file content here", metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output.endsWith(POST_READ_NUDGE)).toBe(true);
+        expect(output.output).toContain("file content here");
+        expect(output.output).toContain("Workflow Reminder");
+      });
+    });
+
+    describe("#when the Read tool name is lowercase", () => {
+      it("#then still appends the nudge due to case-insensitive matching", async () => {
+        const handler = createPostReadNudgeHandler();
+        const input = { tool: "read", sessionID: "s1", callID: "c1", args: {} };
+        const output = { title: "read", output: "some content", metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output.endsWith(POST_READ_NUDGE)).toBe(true);
+      });
+    });
+
+    describe("#when the Read tool name is READ in uppercase", () => {
+      it("#then still appends the nudge", async () => {
+        const handler = createPostReadNudgeHandler();
+        const input = { tool: "READ", sessionID: "s1", callID: "c1", args: {} };
+        const output = { title: "read", output: "uppercase read content", metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output.endsWith(POST_READ_NUDGE)).toBe(true);
+      });
+    });
+  });
+
+  describe("#given a non-Read tool call", () => {
+    describe("#when the tool is Bash", () => {
+      it("#then leaves the output unchanged", async () => {
+        const handler = createPostReadNudgeHandler();
+        const input = { tool: "Bash", sessionID: "s1", callID: "c1", args: {} };
+        const original = "command output";
+        const output = { title: "bash", output: original, metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(original);
+      });
+    });
+
+    describe("#when the tool is Edit", () => {
+      it("#then leaves the output unchanged", async () => {
+        const handler = createPostReadNudgeHandler();
+        const input = { tool: "Edit", sessionID: "s1", callID: "c1", args: {} };
+        const original = "edit successful";
+        const output = { title: "edit", output: original, metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(original);
+      });
+    });
+  });
+
+  describe("#given a Read tool output that already contains the nudge", () => {
+    describe("#when the output already has the nudge text", () => {
+      it("#then does not double-append the nudge", async () => {
+        const handler = createPostReadNudgeHandler();
+        const input = { tool: "Read", sessionID: "s1", callID: "c1", args: {} };
+        const output = {
+          title: "read",
+          output: `file content${POST_READ_NUDGE}`,
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        const nudgeCount = output.output.split("Workflow Reminder").length - 1;
+        expect(nudgeCount).toBe(1);
+      });
+    });
+  });
+
+  describe("#given a Read tool with non-string output", () => {
+    describe("#when output.output is undefined", () => {
+      it("#then does not modify the output", async () => {
+        const handler = createPostReadNudgeHandler();
+        const input = { tool: "Read", sessionID: "s1", callID: "c1", args: {} };
+        const output = { title: "read", output: undefined as unknown as string, metadata: {} };
+
+        await handler(input, output);
+
+        expect(output.output).toBeUndefined();
+      });
+    });
+  });
+});

package/src/hooks/post-read-nudge/handler.ts

@@ -0,0 +1,28 @@
+import type { PluginHookContributions } from "../../types/hook";
+
+type PostToolUseHook = NonNullable<PluginHookContributions["tool.execute.after"]>;
+
+export const POST_READ_NUDGE =
+  "\n\n---\nWorkflow Reminder: delegate based on rules; if mentioning a specialist, launch it in this same turn.";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isReadTool(tool: string): boolean {
+  return tool.toLowerCase() === "read";
+}
+
+export function createPostReadNudgeHandler(): PostToolUseHook {
+  return async (input: unknown, output: unknown) => {
+    if (!isRecord(input) || !isRecord(output)) return;
+
+    const tool = input.tool;
+    const text = output.output;
+    if (typeof tool !== "string" || typeof text !== "string") return;
+    if (!isReadTool(tool)) return;
+    if (text.includes(POST_READ_NUDGE.trim())) return;
+
+    output.output = `${text}${POST_READ_NUDGE}`;
+  };
+}

package/src/hooks/post-read-nudge/index.ts

@@ -0,0 +1,2 @@
+export { createPostReadNudgeHandler, POST_READ_NUDGE } from "./handler";
+export { postReadNudgePlugin } from "./plugin";

package/src/hooks/post-read-nudge/plugin.ts

@@ -0,0 +1,18 @@
+import { definePlugin } from "../../plugin-api";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createPostReadNudgeHandler } from "./handler";
+
+const postReadNudgeToolExecuteAfterHook = safeCreateHook(
+  "post-read-nudge",
+  createPostReadNudgeHandler,
+);
+
+export const postReadNudgePlugin = definePlugin({
+  name: "post-read-nudge",
+  version: "0.1.0",
+  hooks: postReadNudgeToolExecuteAfterHook
+    ? {
+        "tool.execute.after": postReadNudgeToolExecuteAfterHook,
+      }
+    : {},
+});

package/src/hooks/preemptive-compaction/handler.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it, mock } from "bun:test";
+import { createPreemptiveCompactionHandler } from "./handler";
+
+describe("createPreemptiveCompactionHandler", () => {
+  describe("#given a handler with default 80% threshold", () => {
+    describe("#when token usage exceeds the threshold", () => {
+      it("#then triggers compaction for the session", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          sessionID: "ses-high",
+          usage: { totalTokens: 170_000 },
+          contextLimit: 200_000,
+        });
+
+        expect(compactSession).toHaveBeenCalledTimes(1);
+        expect(compactSession).toHaveBeenCalledWith("ses-high", {
+          usageRatio: 0.85,
+          usedTokens: 170_000,
+          contextLimit: 200_000,
+        });
+      });
+    });
+
+    describe("#when token usage is below the threshold", () => {
+      it("#then does not trigger compaction", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          sessionID: "ses-low",
+          usage: { totalTokens: 100_000 },
+          contextLimit: 200_000,
+        });
+
+        expect(compactSession).not.toHaveBeenCalled();
+      });
+    });
+
+    describe("#when no context limit is provided", () => {
+      it("#then does not trigger compaction", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          sessionID: "ses-nolimit",
+          usage: { totalTokens: 170_000 },
+        });
+
+        expect(compactSession).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("#given a handler tracking per-session compaction state", () => {
+    describe("#when usage stays above threshold across multiple calls", () => {
+      it("#then only compacts once until usage drops below threshold", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          sessionID: "ses-dedup",
+          usage: { totalTokens: 170_000 },
+          contextLimit: 200_000,
+        });
+
+        await handler({
+          sessionID: "ses-dedup",
+          usage: { totalTokens: 180_000 },
+          contextLimit: 200_000,
+        });
+
+        expect(compactSession).toHaveBeenCalledTimes(1);
+
+        await handler({
+          sessionID: "ses-dedup",
+          usage: { totalTokens: 100_000 },
+          contextLimit: 200_000,
+        });
+
+        await handler({
+          sessionID: "ses-dedup",
+          usage: { totalTokens: 175_000 },
+          contextLimit: 200_000,
+        });
+
+        expect(compactSession).toHaveBeenCalledTimes(2);
+      });
+    });
+  });
+
+  describe("#given a handler with no sessionID", () => {
+    describe("#when input lacks a sessionID", () => {
+      it("#then does nothing", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          usage: { totalTokens: 190_000 },
+          contextLimit: 200_000,
+        });
+
+        expect(compactSession).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("#given a handler with tokenUsage input format", () => {
+    describe("#when tokenUsage.total exceeds the threshold", () => {
+      it("#then triggers compaction using the alternate input shape", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          sessionID: "ses-alt",
+          tokenUsage: { total: 165_000 },
+          context: { limitTokens: 200_000 },
+        });
+
+        expect(compactSession).toHaveBeenCalledTimes(1);
+        expect(compactSession).toHaveBeenCalledWith("ses-alt", {
+          usageRatio: 0.825,
+          usedTokens: 165_000,
+          contextLimit: 200_000,
+        });
+      });
+    });
+  });
+});

package/src/hooks/preemptive-compaction/handler.ts

@@ -0,0 +1,84 @@
+import { log } from "../../shared/logger";
+
+type PreemptiveCompactionInput = {
+  sessionID?: string;
+  usage?: { inputTokens?: number; cacheReadTokens?: number; totalTokens?: number };
+  context?: { limitTokens?: number };
+  tokenUsage?: { input?: number; cacheRead?: number; total?: number };
+  contextLimit?: number;
+};
+
+type PreemptiveCompactionDeps = {
+  threshold?: number;
+  getTokenUsage?: (
+    input: PreemptiveCompactionInput,
+  ) => { usedTokens: number; contextLimit: number } | undefined;
+  compactSession?: (
+    sessionID: string,
+    info: { usageRatio: number; usedTokens: number; contextLimit: number },
+  ) => void | Promise<void>;
+};
+
+function resolveTokenUsage(
+  input: PreemptiveCompactionInput,
+): { usedTokens: number; contextLimit: number } | undefined {
+  const usageFromUsage = input.usage;
+  const usageFromTokenUsage = input.tokenUsage;
+
+  const usedTokens =
+    usageFromUsage?.totalTokens ??
+    usageFromTokenUsage?.total ??
+    (usageFromUsage
+      ? (usageFromUsage.inputTokens ?? 0) + (usageFromUsage.cacheReadTokens ?? 0)
+      : (usageFromTokenUsage?.input ?? 0) + (usageFromTokenUsage?.cacheRead ?? 0));
+
+  const contextLimit = input.context?.limitTokens ?? input.contextLimit;
+
+  if (!contextLimit || contextLimit <= 0) return undefined;
+  return { usedTokens, contextLimit };
+}
+
+export function createPreemptiveCompactionHandler(deps: PreemptiveCompactionDeps = {}) {
+  const threshold = deps.threshold ?? 0.8;
+  const compactedWhileAboveThreshold = new Set<string>();
+
+  return async (input: PreemptiveCompactionInput): Promise<void> => {
+    const sessionID = input.sessionID;
+    if (!sessionID) return;
+
+    const resolved = deps.getTokenUsage?.(input) ?? resolveTokenUsage(input);
+    if (!resolved) return;
+
+    const usageRatio = resolved.usedTokens / resolved.contextLimit;
+    if (usageRatio < threshold) {
+      compactedWhileAboveThreshold.delete(sessionID);
+      return;
+    }
+
+    if (compactedWhileAboveThreshold.has(sessionID)) return;
+
+    compactedWhileAboveThreshold.add(sessionID);
+
+    try {
+      await Promise.resolve(
+        deps.compactSession?.(sessionID, {
+          usageRatio,
+          usedTokens: resolved.usedTokens,
+          contextLimit: resolved.contextLimit,
+        }),
+      );
+      log("[preemptive-compaction] triggered compaction", {
+        sessionID,
+        usageRatio,
+        usedTokens: resolved.usedTokens,
+        contextLimit: resolved.contextLimit,
+      });
+    } catch (error) {
+      compactedWhileAboveThreshold.delete(sessionID);
+      log("[preemptive-compaction] compaction trigger failed", {
+        sessionID,
+        error: String(error),
+      });
+    }
+  };
+}

package/src/hooks/preemptive-compaction/index.ts

@@ -0,0 +1,2 @@
+export { createPreemptiveCompactionHandler } from "./handler";
+export { preemptiveCompactionPlugin } from "./plugin";