goatcode-sh 0.0.1 → 0.1.3

package/src/hooks/model-fallback/handler.ts

@@ -0,0 +1,178 @@
+import { buildFallbackChain } from "../../shared/fallback-chain";
+import { resolveModel } from "../../shared/model-resolution-pipeline";
+import { log } from "../../shared/logger";
+
+type ModelSwitchReason = "rate-limit" | "service-unavailable";
+
+type ModelFallbackErrorEvent = {
+  event: {
+    type: string;
+    properties?: unknown;
+  };
+};
+
+type ModelFallbackState = {
+  sessionModels: Map<string, string>;
+};
+
+type ModelFallbackDependencies = {
+  defaultFallbackChain?: string[];
+  getCurrentModel?: (sessionID: string) => string | undefined;
+  getAvailableModels?: (sessionID: string) => Set<string>;
+  setCurrentModel?: (sessionID: string, model: string) => void | Promise<void>;
+  onFallbackApplied?: (input: {
+    sessionID: string;
+    previousModel: string;
+    nextModel: string;
+    reason: ModelSwitchReason;
+  }) => void | Promise<void>;
+};
+
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  return value as Record<string, unknown>;
+}
+
+function toStatusCode(error: unknown): number | undefined {
+  const record = toRecord(error);
+  if (!record) return undefined;
+
+  const direct = record["statusCode"];
+  if (typeof direct === "number") return direct;
+
+  const status = record["status"];
+  if (typeof status === "number") return status;
+
+  const nested = toRecord(record["error"]);
+  if (nested) {
+    const nestedCode = nested["statusCode"];
+    if (typeof nestedCode === "number") return nestedCode;
+  }
+
+  return undefined;
+}
+
+function getErrorMessage(error: unknown): string {
+  if (typeof error === "string") return error.toLowerCase();
+  const record = toRecord(error);
+  const message = record?.["message"];
+  if (typeof message === "string") return message.toLowerCase();
+  return "";
+}
+
+function classifyModelFallbackReason(error: unknown): ModelSwitchReason | undefined {
+  const statusCode = toStatusCode(error);
+  const message = getErrorMessage(error);
+
+  if (
+    statusCode === 429 ||
+    message.includes("rate limit") ||
+    message.includes("too many requests")
+  ) {
+    return "rate-limit";
+  }
+
+  if (
+    statusCode === 503 ||
+    message.includes("service unavailable") ||
+    message.includes("temporarily unavailable")
+  ) {
+    return "service-unavailable";
+  }
+
+  return undefined;
+}
+
+function getSessionID(properties: Record<string, unknown>): string | undefined {
+  const sessionID = properties["sessionID"];
+  if (typeof sessionID === "string" && sessionID.length > 0) return sessionID;
+
+  const info = toRecord(properties["info"]);
+  const infoID = info?.["id"];
+  if (typeof infoID === "string" && infoID.length > 0) return infoID;
+
+  return undefined;
+}
+
+function getNextFallbackModel(input: {
+  currentModel: string;
+  configuredFallbacks: string | string[] | undefined;
+  defaultChain: string[];
+  availableModels: Set<string>;
+}): string | undefined {
+  const fullChain = buildFallbackChain(input.configuredFallbacks, input.defaultChain);
+  const currentIndex = fullChain.findIndex(
+    (model) => model.toLowerCase() === input.currentModel.toLowerCase(),
+  );
+  const remaining = currentIndex >= 0 ? fullChain.slice(currentIndex + 1) : fullChain;
+
+  return resolveModel({
+    fallbackChain: remaining,
+    availableModels: input.availableModels,
+  })?.model;
+}
+
+export function createModelFallbackHandler(deps: ModelFallbackDependencies = {}) {
+  const state: ModelFallbackState = { sessionModels: new Map() };
+  const defaultSwitch = async (sessionID: string, model: string) => {
+    state.sessionModels.set(sessionID, model);
+  };
+
+  return async ({ event }: ModelFallbackErrorEvent): Promise<void> => {
+    if (event.type !== "session.error") return;
+
+    const properties = toRecord(event.properties);
+    if (!properties) return;
+
+    const reason = classifyModelFallbackReason(properties["error"]);
+    if (!reason) return;
+
+    const sessionID = getSessionID(properties);
+    if (!sessionID) return;
+
+    const configuredFallbacks = properties["fallbackChain"];
+    const fallbackInput =
+      typeof configuredFallbacks === "string" || Array.isArray(configuredFallbacks)
+        ? configuredFallbacks
+        : undefined;
+
+    const eventModel = properties["model"];
+    const currentModel =
+      (typeof eventModel === "string" && eventModel.length > 0 ? eventModel : undefined) ??
+      deps.getCurrentModel?.(sessionID) ??
+      state.sessionModels.get(sessionID);
+    if (!currentModel) return;
+
+    const availableModels = deps.getAvailableModels?.(sessionID) ?? new Set<string>();
+    const nextModel = getNextFallbackModel({
+      currentModel,
+      configuredFallbacks: fallbackInput,
+      defaultChain: deps.defaultFallbackChain ?? [],
+      availableModels,
+    });
+
+    if (!nextModel || nextModel.toLowerCase() === currentModel.toLowerCase()) {
+      log("[model-fallback] no eligible fallback model", { sessionID, currentModel, reason });
+      return;
+    }
+
+    const applyModel = deps.setCurrentModel ?? defaultSwitch;
+    await Promise.resolve(applyModel(sessionID, nextModel));
+
+    await Promise.resolve(
+      deps.onFallbackApplied?.({
+        sessionID,
+        previousModel: currentModel,
+        nextModel,
+        reason,
+      }),
+    );
+
+    log("[model-fallback] switched model", {
+      sessionID,
+      from: currentModel,
+      to: nextModel,
+      reason,
+    });
+  };
+}

package/src/hooks/model-fallback/index.ts

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

package/src/hooks/model-fallback/plugin.ts

@@ -0,0 +1,11 @@
+import { definePlugin } from "../../plugin-api";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createModelFallbackHandler } from "./handler";
+
+const modelFallbackEventHook = safeCreateHook("model-fallback", () => createModelFallbackHandler());
+
+export const modelFallbackPlugin = definePlugin({
+  name: "model-fallback",
+  version: "0.1.0",
+  hooks: modelFallbackEventHook ? { event: modelFallbackEventHook } : undefined,
+});

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,159 @@
+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();
+      });
+    });
+  });
+
+  describe("#given multiple exploration tool calls exceeding threshold", () => {
+    describe("#when 3+ exploration calls are made (read, grep, glob mix)", () => {
+      it("#then escalates to a delegation nudge on subsequent reads", async () => {
+        const handler = createPostReadNudgeHandler();
+
+        // First two reads get normal nudge
+        const input1 = { tool: "read", sessionID: "s1", callID: "c1", args: {} };
+        const output1 = { title: "read", output: "content1", metadata: {} };
+        await handler(input1, output1);
+        expect(output1.output).toContain("Workflow Reminder");
+        expect(output1.output).not.toContain("DELEGATION NUDGE");
+
+        // Second read
+        const input2 = { tool: "read", sessionID: "s1", callID: "c2", args: {} };
+        const output2 = { title: "read", output: "content2", metadata: {} };
+        await handler(input2, output2);
+        expect(output2.output).toContain("Workflow Reminder");
+        expect(output2.output).not.toContain("DELEGATION NUDGE");
+
+        // Third read triggers escalation
+        const input3 = { tool: "read", sessionID: "s1", callID: "c3", args: {} };
+        const output3 = { title: "read", output: "content3", metadata: {} };
+        await handler(input3, output3);
+        expect(output3.output).toContain("DELEGATION NUDGE");
+        expect(output3.output).toContain("delegate to a specialist agent NOW");
+      });
+    });
+
+    describe("#when grep and glob calls contribute to the count", () => {
+      it("#then counts all exploration tools toward the threshold", async () => {
+        const handler = createPostReadNudgeHandler();
+
+        // Grep call — doesn't append nudge to grep output
+        const grepInput = { tool: "grep", sessionID: "s1", callID: "c1", args: {} };
+        const grepOutput = { title: "grep", output: "grep results", metadata: {} };
+        await handler(grepInput, grepOutput);
+        expect(grepOutput.output).toBe("grep results");
+
+        // Glob call — doesn't append nudge to glob output
+        const globInput = { tool: "glob", sessionID: "s1", callID: "c2", args: {} };
+        const globOutput = { title: "glob", output: "glob results", metadata: {} };
+        await handler(globInput, globOutput);
+        expect(globOutput.output).toBe("glob results");
+
+        // Third exploration call is a read — should trigger escalation
+        const readInput = { tool: "read", sessionID: "s1", callID: "c3", args: {} };
+        const readOutput = { title: "read", output: "file content", metadata: {} };
+        await handler(readInput, readOutput);
+        expect(readOutput.output).toContain("DELEGATION NUDGE");
+      });
+    });
+  });
+});