goatcode-sh 0.0.1 → 0.1.2

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

@@ -0,0 +1,142 @@
+import { describe, expect, it, mock } from "bun:test";
+import { createRuntimeFallbackHandler } from "./handler";
+
+describe("createRuntimeFallbackHandler", () => {
+  describe("#given a handler with a fallback chain", () => {
+    describe("#when error message contains 'model not found'", () => {
+      it("#then switches to a compatible same-provider fallback", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createRuntimeFallbackHandler({
+          setCurrentModel,
+        });
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-notfound",
+              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(setCurrentModel).toHaveBeenCalledTimes(1);
+        expect(setCurrentModel).toHaveBeenCalledWith("ses-notfound", "openai/gpt-4.1-mini");
+      });
+    });
+
+    describe("#when error message contains 'context length'", () => {
+      it("#then triggers fallback for context-exceeded reason", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+        const onFallbackApplied = mock(() => {});
+
+        const handler = createRuntimeFallbackHandler({
+          setCurrentModel,
+          onFallbackApplied,
+        });
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-ctx",
+              model: "anthropic/claude-3-5-sonnet",
+              error: { message: "Maximum context length exceeded" },
+              fallbackChain: [
+                "anthropic/claude-3-5-sonnet",
+                "anthropic/claude-3-5-haiku",
+                "openai/gpt-4o",
+              ],
+            },
+          },
+        });
+
+        expect(setCurrentModel).toHaveBeenCalledTimes(1);
+        expect(setCurrentModel).toHaveBeenCalledWith("ses-ctx", "anthropic/claude-3-5-haiku");
+        expect(onFallbackApplied).toHaveBeenCalledTimes(1);
+      });
+    });
+
+    describe("#when error message is a generic error", () => {
+      it("#then does not trigger any fallback", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createRuntimeFallbackHandler({
+          setCurrentModel,
+        });
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-generic",
+              model: "openai/gpt-4o",
+              error: { message: "Something went wrong" },
+              fallbackChain: ["openai/gpt-4o", "anthropic/claude-3-5-sonnet"],
+            },
+          },
+        });
+
+        expect(setCurrentModel).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("#given a handler receives non-error events", () => {
+    describe("#when event type is not session.error", () => {
+      it("#then does nothing", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createRuntimeFallbackHandler({
+          setCurrentModel,
+        });
+
+        await handler({
+          event: {
+            type: "session.created",
+            properties: {
+              sessionID: "ses-created",
+              model: "openai/gpt-4o",
+            },
+          },
+        });
+
+        expect(setCurrentModel).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("#given a handler with 'too many tokens' error", () => {
+    describe("#when error message contains 'too many tokens'", () => {
+      it("#then classifies as context-exceeded and triggers fallback", async () => {
+        const setCurrentModel = mock((_sid: string, _model: string) => {});
+
+        const handler = createRuntimeFallbackHandler({
+          setCurrentModel,
+        });
+
+        await handler({
+          event: {
+            type: "session.error",
+            properties: {
+              sessionID: "ses-tokens",
+              model: "openai/gpt-4o",
+              error: { message: "Too many tokens in the request" },
+              fallbackChain: ["openai/gpt-4o", "openai/gpt-4o-mini"],
+            },
+          },
+        });
+
+        expect(setCurrentModel).toHaveBeenCalledTimes(1);
+        expect(setCurrentModel).toHaveBeenCalledWith("ses-tokens", "openai/gpt-4o-mini");
+      });
+    });
+  });
+});

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

@@ -0,0 +1,171 @@
+import { buildFallbackChain } from "../../shared/fallback-chain";
+import { resolveModel } from "../../shared/model-resolution-pipeline";
+import { log } from "../../shared/logger";
+
+type RuntimeFallbackReason = "model-not-found" | "context-exceeded";
+
+type RuntimeFallbackEvent = {
+  event: {
+    type: string;
+    properties?: unknown;
+  };
+};
+
+type RuntimeFallbackDependencies = {
+  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: RuntimeFallbackReason;
+  }) => 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 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 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();
+
+  const nested = toRecord(record?.["error"]);
+  const nestedMessage = nested?.["message"];
+  if (typeof nestedMessage === "string") return nestedMessage.toLowerCase();
+
+  return "";
+}
+
+function classifyRuntimeFallbackReason(error: unknown): RuntimeFallbackReason | undefined {
+  const message = getErrorMessage(error);
+  if (message.includes("model not found") || message.includes("unknown model")) {
+    return "model-not-found";
+  }
+  if (
+    message.includes("context length") ||
+    message.includes("context window") ||
+    message.includes("maximum context") ||
+    message.includes("too many tokens")
+  ) {
+    return "context-exceeded";
+  }
+  return undefined;
+}
+
+function getProvider(model: string): string | undefined {
+  const idx = model.indexOf("/");
+  if (idx <= 0) return undefined;
+  return model.slice(0, idx).toLowerCase();
+}
+
+function getNextRuntimeFallbackModel(input: {
+  currentModel: string;
+  configuredFallbacks: string | string[] | undefined;
+  defaultChain: string[];
+  availableModels: Set<string>;
+}): string | undefined {
+  const currentProvider = getProvider(input.currentModel);
+  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;
+
+  const compatibleRemaining =
+    currentProvider === undefined
+      ? remaining
+      : remaining.filter((model) => getProvider(model) === currentProvider);
+
+  const compatibleResolved = resolveModel({
+    fallbackChain: compatibleRemaining,
+    availableModels: input.availableModels,
+  })?.model;
+  if (compatibleResolved) return compatibleResolved;
+
+  return resolveModel({
+    fallbackChain: remaining,
+    availableModels: input.availableModels,
+  })?.model;
+}
+
+export function createRuntimeFallbackHandler(deps: RuntimeFallbackDependencies = {}) {
+  const sessionModels = new Map<string, string>();
+  const defaultSwitch = async (sessionID: string, model: string) => {
+    sessionModels.set(sessionID, model);
+  };
+
+  return async ({ event }: RuntimeFallbackEvent): Promise<void> => {
+    if (event.type !== "session.error") return;
+
+    const properties = toRecord(event.properties);
+    if (!properties) return;
+
+    const reason = classifyRuntimeFallbackReason(properties["error"]);
+    if (!reason) return;
+
+    const sessionID = getSessionID(properties);
+    if (!sessionID) return;
+
+    const eventModel = properties["model"];
+    const currentModel =
+      (typeof eventModel === "string" && eventModel.length > 0 ? eventModel : undefined) ??
+      deps.getCurrentModel?.(sessionID) ??
+      sessionModels.get(sessionID);
+    if (!currentModel) return;
+
+    const configuredFallbacks = properties["fallbackChain"];
+    const fallbackInput =
+      typeof configuredFallbacks === "string" || Array.isArray(configuredFallbacks)
+        ? configuredFallbacks
+        : undefined;
+
+    const availableModels = deps.getAvailableModels?.(sessionID) ?? new Set<string>();
+    const nextModel = getNextRuntimeFallbackModel({
+      currentModel,
+      configuredFallbacks: fallbackInput,
+      defaultChain: deps.defaultFallbackChain ?? [],
+      availableModels,
+    });
+
+    if (!nextModel || nextModel.toLowerCase() === currentModel.toLowerCase()) {
+      log("[runtime-fallback] no compatible 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("[runtime-fallback] switched model", {
+      sessionID,
+      from: currentModel,
+      to: nextModel,
+      reason,
+    });
+  };
+}

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

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

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

@@ -0,0 +1,13 @@
+import { definePlugin } from "../../plugin-api";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createRuntimeFallbackHandler } from "./handler";
+
+const runtimeFallbackEventHook = safeCreateHook("runtime-fallback", () =>
+  createRuntimeFallbackHandler(),
+);
+
+export const runtimeFallbackPlugin = definePlugin({
+  name: "runtime-fallback",
+  version: "0.1.0",
+  hooks: runtimeFallbackEventHook ? { event: runtimeFallbackEventHook } : undefined,
+});

package/src/hooks/safe-hook-wrapper.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "bun:test";
+
+import type { PluginHookHandler } from "../types/plugin";
+import { wrapSafely } from "./safe-hook-wrapper";
+
+describe("wrapSafely", () => {
+  describe("#given a handler that throws", () => {
+    describe("#when wrapped and called", () => {
+      it("#then error is caught and no throw escapes", async () => {
+        const failing: PluginHookHandler = async () => {
+          throw new Error("boom");
+        };
+        const wrapped = wrapSafely("event", failing);
+
+        await expect(wrapped({}, {})).resolves.toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given a handler that succeeds", () => {
+    describe("#when wrapped and called", () => {
+      it("#then it executes normally", async () => {
+        const calls: string[] = [];
+        const success: PluginHookHandler = async () => {
+          calls.push("ran");
+        };
+        const wrapped = wrapSafely("event", success);
+
+        await wrapped({}, {});
+
+        expect(calls).toEqual(["ran"]);
+      });
+    });
+  });
+});

package/src/hooks/safe-hook-wrapper.ts

@@ -0,0 +1,12 @@
+import type { PluginHookHandler } from "../types/plugin";
+import { log } from "../shared/logger";
+
+export function wrapSafely(name: string, handler: PluginHookHandler): PluginHookHandler {
+  return async (input: unknown, output: unknown) => {
+    try {
+      await handler(input, output);
+    } catch (error) {
+      log(`[hook] Error in hook "${name}"`, { error });
+    }
+  };
+}

package/src/hooks/session-recovery/handler.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "bun:test";
+
+import { createSessionRecoveryHandler, SESSION_RECOVERY_MESSAGE } from "./handler";
+
+type UnknownHandler = (input: unknown) => Promise<void>;
+
+describe("createSessionRecoveryHandler", () => {
+  describe("#given a handler instance", () => {
+    const handler = createSessionRecoveryHandler() as unknown as UnknownHandler;
+
+    describe("#when event is session.error with a matching recovery pattern", () => {
+      it("#then sets recoveryContext on properties", async () => {
+        const properties: Record<string, unknown> = { error: "session crash detected" };
+        const input = {
+          event: { type: "session.error", properties },
+        };
+        await handler(input);
+        expect(properties.recoveryContext).toBe(SESSION_RECOVERY_MESSAGE);
+      });
+    });
+
+    describe("#when event is session.error with 'connection reset'", () => {
+      it("#then sets recoveryContext", async () => {
+        const properties: Record<string, unknown> = { error: "connection reset by peer" };
+        const input = {
+          event: { type: "session.error", properties },
+        };
+        await handler(input);
+        expect(properties.recoveryContext).toContain("[SESSION RECOVERY]");
+      });
+    });
+
+    describe("#when event is session.error but error does not match patterns", () => {
+      it("#then no recoveryContext is added", async () => {
+        const properties: Record<string, unknown> = { error: "unknown error happened" };
+        const input = {
+          event: { type: "session.error", properties },
+        };
+        await handler(input);
+        expect(properties.recoveryContext).toBeUndefined();
+      });
+    });
+
+    describe("#when event type is not session.error", () => {
+      it("#then no-op", async () => {
+        const properties: Record<string, unknown> = { error: "session crash detected" };
+        const input = {
+          event: { type: "session.idle", properties },
+        };
+        await handler(input);
+        expect(properties.recoveryContext).toBeUndefined();
+      });
+    });
+
+    describe("#when recoveryContext already contains the marker", () => {
+      it("#then does not double-append", async () => {
+        const properties: Record<string, unknown> = {
+          error: "session crash detected",
+          recoveryContext: SESSION_RECOVERY_MESSAGE,
+        };
+        const input = {
+          event: { type: "session.error", properties },
+        };
+        await handler(input);
+        expect(properties.recoveryContext).toBe(SESSION_RECOVERY_MESSAGE);
+      });
+    });
+
+    describe("#when input is not a record", () => {
+      it("#then no-op", async () => {
+        await handler(null);
+      });
+    });
+
+    describe("#when error is an object with message property", () => {
+      it("#then extracts message for pattern matching", async () => {
+        const properties: Record<string, unknown> = {
+          error: { message: "socket hang up" },
+        };
+        const input = {
+          event: { type: "session.error", properties },
+        };
+        await handler(input);
+        expect(properties.recoveryContext).toContain("[SESSION RECOVERY]");
+      });
+    });
+  });
+});

package/src/hooks/session-recovery/handler.ts

@@ -0,0 +1,87 @@
+import type { PluginHookContributions } from "../../types/hook";
+import { log } from "../../shared/logger";
+
+export const SESSION_RECOVERY_PATTERNS = [
+  /session.*crash/i,
+  /session.*disconnect/i,
+  /connection reset/i,
+  /socket hang up/i,
+  /network.*interrupted/i,
+] as const;
+
+const SESSION_RECOVERY_MARKER = "[SESSION RECOVERY]";
+
+export const SESSION_RECOVERY_MESSAGE = `${SESSION_RECOVERY_MARKER}\nSession interruption detected. Reuse the latest confirmed state, avoid replaying completed tool calls, and continue from the last successful step.`;
+
+type EventHook = NonNullable<PluginHookContributions["event"]>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function extractErrorText(input: Record<string, unknown>): string {
+  const event = input.event;
+  if (!isRecord(event)) {
+    return "";
+  }
+
+  const properties = event.properties;
+  if (!isRecord(properties)) {
+    return "";
+  }
+
+  const rawError = properties.error;
+  if (typeof rawError === "string") {
+    return rawError;
+  }
+
+  if (isRecord(rawError) && typeof rawError.message === "string") {
+    return rawError.message;
+  }
+
+  return "";
+}
+
+function appendRecoveryContext(properties: Record<string, unknown>, message: string): void {
+  const existing = properties.recoveryContext;
+  if (typeof existing === "string" && existing.includes(SESSION_RECOVERY_MARKER)) {
+    return;
+  }
+
+  if (typeof existing === "string" && existing.length > 0) {
+    properties.recoveryContext = `${existing}\n${message}`;
+    return;
+  }
+
+  properties.recoveryContext = message;
+}
+
+export function createSessionRecoveryHandler(): EventHook {
+  return async (input: unknown) => {
+    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 = extractErrorText(input);
+    const isRecoverableSessionError = SESSION_RECOVERY_PATTERNS.some((pattern) =>
+      pattern.test(errorText),
+    );
+
+    if (!isRecoverableSessionError) {
+      return;
+    }
+
+    appendRecoveryContext(properties, SESSION_RECOVERY_MESSAGE);
+    log("[session-recovery] injected session recovery context");
+  };
+}

package/src/hooks/session-recovery/index.ts

@@ -0,0 +1,6 @@
+export { sessionRecoveryPlugin } from "./plugin";
+export {
+  createSessionRecoveryHandler,
+  SESSION_RECOVERY_PATTERNS,
+  SESSION_RECOVERY_MESSAGE,
+} from "./handler";

package/src/hooks/session-recovery/plugin.ts

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

package/src/hooks/skill-discovery/plugin.ts

@@ -0,0 +1,45 @@
+import { definePlugin } from "../../plugin-api/define-plugin";
+import { getAvailableSkills } from "../../tools/skill/handler";
+
+function buildSkillsSystemBlock(): string | null {
+  const skills = getAvailableSkills();
+  if (skills.length === 0) return null;
+
+  const lines = skills.map((s) => `- **${s.name}**`);
+
+  return [
+    "## Available Skills",
+    "",
+    "Use the `skill` tool to load any of these skills by name:",
+    ...lines,
+  ].join("\n");
+}
+
+export const skillDiscoveryPlugin = definePlugin({
+  name: "skill-discovery",
+  version: "0.1.0",
+  hooks: {
+    "experimental.chat.system.transform": async (
+      _input: { sessionID?: string; model: unknown },
+      output: { system: string[] },
+    ) => {
+      const block = buildSkillsSystemBlock();
+      if (block) {
+        output.system.push(block);
+      }
+    },
+    "tool.definition": async (
+      input: { toolID: string },
+      output: { description: string; parameters: unknown },
+    ) => {
+      if (input.toolID !== "skill") return;
+
+      const skills = getAvailableSkills();
+      if (skills.length === 0) return;
+
+      const listing = skills.map((s) => `  - ${s.name}`).join("\n");
+
+      output.description += `\n\nAvailable skills:\n${listing}`;
+    },
+  },
+});