@wrongstack/plugins 0.277.2 → 0.280.0

package/dist/llm-cache.d.ts

@@ -0,0 +1,56 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * llm-cache plugin — caches identical provider requests and skips the
+ * provider call entirely on a hit.
+ *
+ * This is the deepest intervention a plugin can make: it registers an
+ * `AgentExtension.wrapProviderRunner`, which the agent loop composes
+ * around EVERY provider call (`agent-loop.ts` → `extensions
+ * .wrapProviderRunner(baseRunner)`). The plugin fingerprints the
+ * outgoing `Request` (model + system + messages + tools + sampling
+ * params) and, on a match, returns the cached `Response` without ever
+ * touching the network — killing redundant calls from retries, loops,
+ * and re-runs.
+ *
+ * Safety posture: caching changes call semantics (a repeated request
+ * returns the same answer instead of a fresh sample), so the plugin is
+ * **opt-in** — it loads inert and does nothing until
+ * `config.extensions['llm-cache'].enabled = true`. By default it only
+ * caches deterministic requests (`temperature` 0 or unset) so a
+ * sampled generation is never silently frozen.
+ *
+ * Config (`config.extensions['llm-cache']`):
+ *
+ * ```jsonc
+ * {
+ *   "enabled": false,           // master switch (default OFF)
+ *   "maxEntries": 256,          // LRU capacity
+ *   "ttlMs": 0,                 // 0 = no expiry; else evict after N ms
+ *   "onlyDeterministic": true,  // only cache temperature 0/unset requests
+ *   "zeroUsageOnHit": false     // report 0 tokens on a hit (true) or keep
+ *                               // the cached usage for context accounting (false)
+ * }
+ * ```
+ *
+ * Tools:
+ *  - `llm_cache_status` — hit/miss/skip counters, size, config
+ *  - `llm_cache_clear`  — drop all cached entries
+ *
+ * @public
+ */
+
+/**
+ * Whether a request is safe to cache under `onlyDeterministic`. Sampled
+ * requests (temperature > 0) return different content each call, so
+ * caching them would silently freeze the first sample.
+ */
+declare function isDeterministic(request: Record<string, unknown>): boolean;
+/**
+ * Stable fingerprint of the request fields that affect the response.
+ * Excludes anything cosmetic (user id, etc.). Same inputs → same key.
+ */
+declare function fingerprintRequest(request: Record<string, unknown>): string;
+declare const plugin: Plugin;
+
+export { plugin as default, fingerprintRequest, isDeterministic };

package/dist/llm-cache.js

@@ -0,0 +1,251 @@
+import { createHash } from 'crypto';
+
+// src/llm-cache/index.ts
+var state = {
+  cache: /* @__PURE__ */ new Map(),
+  hits: 0,
+  misses: 0,
+  skips: 0,
+  evictions: 0,
+  savedInputTokens: 0,
+  savedOutputTokens: 0,
+  extensionUnregister: null
+};
+var DEFAULTS = {
+  enabled: false,
+  maxEntries: 256,
+  ttlMs: 0,
+  onlyDeterministic: true,
+  zeroUsageOnHit: false
+};
+function readConfig(raw) {
+  if (!raw || typeof raw !== "object") return { ...DEFAULTS };
+  const r = raw;
+  return {
+    enabled: r["enabled"] === true,
+    maxEntries: typeof r["maxEntries"] === "number" && r["maxEntries"] >= 1 ? Math.floor(r["maxEntries"]) : DEFAULTS.maxEntries,
+    ttlMs: typeof r["ttlMs"] === "number" && r["ttlMs"] >= 0 ? r["ttlMs"] : DEFAULTS.ttlMs,
+    onlyDeterministic: r["onlyDeterministic"] !== false,
+    zeroUsageOnHit: r["zeroUsageOnHit"] === true
+  };
+}
+function isDeterministic(request) {
+  const t = request["temperature"];
+  return t === void 0 || t === 0;
+}
+function fingerprintRequest(request) {
+  const subset = {
+    model: request["model"] ?? null,
+    system: request["system"] ?? null,
+    messages: request["messages"] ?? null,
+    tools: Array.isArray(request["tools"]) ? request["tools"].map((t) => t?.name ?? t) : null,
+    temperature: request["temperature"] ?? null,
+    topP: request["topP"] ?? null,
+    topK: request["topK"] ?? null,
+    maxTokens: request["maxTokens"] ?? null,
+    stopSequences: request["stopSequences"] ?? null,
+    responseFormat: request["responseFormat"] ?? null,
+    reasoning: request["reasoning"] ?? null
+  };
+  return createHash("sha256").update(JSON.stringify(subset)).digest("hex");
+}
+function lruGet(key, ttlMs) {
+  const entry = state.cache.get(key);
+  if (!entry) return void 0;
+  if (ttlMs > 0 && Date.now() - entry.storedAt > ttlMs) {
+    state.cache.delete(key);
+    return void 0;
+  }
+  state.cache.delete(key);
+  state.cache.set(key, entry);
+  return entry;
+}
+function lruSet(key, response, maxEntries) {
+  state.cache.set(key, { response, storedAt: Date.now(), hits: 0 });
+  while (state.cache.size > maxEntries) {
+    const oldest = state.cache.keys().next().value;
+    if (oldest === void 0) break;
+    state.cache.delete(oldest);
+    state.evictions += 1;
+  }
+}
+var plugin = {
+  name: "llm-cache",
+  version: "0.1.0",
+  description: "Caches identical provider requests and short-circuits the provider call on a hit (wrapProviderRunner). Opt-in; deterministic-only by default.",
+  apiVersion: "^0.1.10",
+  capabilities: { tools: true },
+  defaultConfig: { ...DEFAULTS },
+  configSchema: {
+    type: "object",
+    properties: {
+      enabled: {
+        type: "boolean",
+        default: false,
+        description: "Master switch. OFF by default because caching changes provider call semantics."
+      },
+      maxEntries: {
+        type: "number",
+        minimum: 1,
+        default: 256,
+        description: "LRU capacity; oldest entries are evicted past this."
+      },
+      ttlMs: {
+        type: "number",
+        minimum: 0,
+        default: 0,
+        description: "Entry lifetime in ms. 0 = no expiry."
+      },
+      onlyDeterministic: {
+        type: "boolean",
+        default: true,
+        description: "Only cache requests with temperature 0 or unset (never freeze a sampled generation)."
+      },
+      zeroUsageOnHit: {
+        type: "boolean",
+        default: false,
+        description: "Report 0 tokens on a cache hit (true) so cost tracking reflects the saving, or keep the cached usage for context accounting (false)."
+      }
+    }
+  },
+  setup(api) {
+    state.cache.clear();
+    state.hits = 0;
+    state.misses = 0;
+    state.skips = 0;
+    state.evictions = 0;
+    state.savedInputTokens = 0;
+    state.savedOutputTokens = 0;
+    if (state.extensionUnregister) {
+      try {
+        state.extensionUnregister();
+      } catch {
+      }
+      state.extensionUnregister = null;
+    }
+    const cfg = readConfig(api.config.extensions?.["llm-cache"]);
+    if (cfg.enabled) {
+      state.extensionUnregister = api.extensions.register({
+        name: "llm-cache",
+        owner: "llm-cache",
+        async wrapProviderRunner(_ctx, request, inner) {
+          const req = request ?? {};
+          if (cfg.onlyDeterministic && !isDeterministic(req)) {
+            state.skips += 1;
+            api.metrics.counter("skips");
+            return inner(_ctx, request);
+          }
+          const key = fingerprintRequest(req);
+          const cached = lruGet(key, cfg.ttlMs);
+          if (cached) {
+            cached.hits += 1;
+            state.hits += 1;
+            state.savedInputTokens += cached.response.usage?.input ?? 0;
+            state.savedOutputTokens += cached.response.usage?.output ?? 0;
+            api.metrics.counter("hits");
+            if (cfg.zeroUsageOnHit) {
+              return {
+                ...cached.response,
+                usage: { ...cached.response.usage, input: 0, output: 0 }
+              };
+            }
+            return cached.response;
+          }
+          state.misses += 1;
+          api.metrics.counter("misses");
+          const response = await inner(_ctx, request);
+          if (response && typeof response === "object" && response.stopReason === "end_turn") {
+            lruSet(key, response, cfg.maxEntries);
+          }
+          return response;
+        }
+      });
+    }
+    api.tools.register({
+      name: "llm_cache_status",
+      description: "Reports llm-cache state: enabled, size, hit/miss/skip counters, and tokens saved by cache hits.",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      category: "Diagnostics",
+      mutating: false,
+      async execute() {
+        const total = state.hits + state.misses;
+        return {
+          ok: true,
+          enabled: cfg.enabled,
+          onlyDeterministic: cfg.onlyDeterministic,
+          maxEntries: cfg.maxEntries,
+          ttlMs: cfg.ttlMs,
+          size: state.cache.size,
+          counters: {
+            hits: state.hits,
+            misses: state.misses,
+            skips: state.skips,
+            evictions: state.evictions,
+            hitRate: total > 0 ? Number((state.hits / total).toFixed(3)) : 0
+          },
+          saved: { inputTokens: state.savedInputTokens, outputTokens: state.savedOutputTokens }
+        };
+      }
+    });
+    api.tools.register({
+      name: "llm_cache_clear",
+      description: "Drops all cached provider responses (does not disable the cache).",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      category: "Diagnostics",
+      mutating: true,
+      async execute() {
+        const cleared = state.cache.size;
+        state.cache.clear();
+        return { ok: true, cleared };
+      }
+    });
+    api.log.info("llm-cache plugin loaded", {
+      version: "0.1.0",
+      enabled: cfg.enabled,
+      onlyDeterministic: cfg.onlyDeterministic,
+      maxEntries: cfg.maxEntries
+    });
+  },
+  teardown(api) {
+    if (state.extensionUnregister) {
+      try {
+        state.extensionUnregister();
+      } catch {
+      }
+      state.extensionUnregister = null;
+    }
+    const final = {
+      hits: state.hits,
+      misses: state.misses,
+      skips: state.skips,
+      savedInputTokens: state.savedInputTokens,
+      savedOutputTokens: state.savedOutputTokens
+    };
+    state.cache.clear();
+    state.hits = 0;
+    state.misses = 0;
+    state.skips = 0;
+    state.evictions = 0;
+    state.savedInputTokens = 0;
+    state.savedOutputTokens = 0;
+    api.log.info("llm-cache: teardown complete", { final });
+  },
+  async health() {
+    const total = state.hits + state.misses;
+    return {
+      ok: true,
+      message: `llm-cache: ${state.cache.size} entr(ies), ${state.hits} hit(s) / ${state.misses} miss(es) (${total > 0 ? Math.round(state.hits / total * 100) : 0}% hit rate), ~${state.savedInputTokens + state.savedOutputTokens} tokens saved`,
+      counters: {
+        hits: state.hits,
+        misses: state.misses,
+        skips: state.skips,
+        evictions: state.evictions
+      }
+    };
+  }
+};
+var llm_cache_default = plugin;
+
+export { llm_cache_default as default, fingerprintRequest, isDeterministic };

package/dist/loop-breaker.d.ts

@@ -0,0 +1,43 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * loop-breaker plugin — detects runaway tool-call loops and breaks them.
+ *
+ * Agents occasionally get stuck re-issuing the same tool call with the
+ * same input (a failing bash command retried forever, re-reading the
+ * same file, re-writing identical content). Each repeat burns tokens
+ * and wall-clock without making progress. This plugin fingerprints
+ * every tool call (`toolName` + canonicalized input JSON) via a
+ * `PreToolUse '*'` hook and tracks consecutive repeats:
+ *
+ *  - at `warnAfter` repeats  → inject `additionalContext` telling the
+ *    model it is looping and should change approach
+ *  - at `blockAfter` repeats → block the call outright with a clear
+ *    reason (unless `mode: 'warn'`)
+ *
+ * Any *different* call resets the streak, so normal workflows (many
+ * distinct reads/edits) are never touched. A small LRU of recent
+ * fingerprints also catches A-B-A-B oscillation loops.
+ *
+ * Config (`config.extensions['loop-breaker']`):
+ *
+ * ```jsonc
+ * {
+ *   "enabled": true,
+ *   "mode": "block",        // "block" | "warn"
+ *   "warnAfter": 3,          // consecutive identical calls before warning
+ *   "blockAfter": 5,         // consecutive identical calls before blocking
+ *   "oscillationWindow": 8,  // recent-call window for A-B-A-B detection
+ *   "ignoreTools": []        // tool names exempt from loop detection
+ * }
+ * ```
+ *
+ * Toggle off entirely with `{ "name": "loop-breaker", "enabled": false }`
+ * in `config.plugins`, or `"enabled": false` in the options above.
+ *
+ * @public
+ */
+
+declare const plugin: Plugin;
+
+export { plugin as default };

package/dist/loop-breaker.js

@@ -0,0 +1,241 @@
+// src/loop-breaker/index.ts
+var state = {
+  lastFingerprint: null,
+  streak: 0,
+  recent: [],
+  invocations: 0,
+  warnings: 0,
+  blocks: 0,
+  oscillationsDetected: 0,
+  hookUnregister: null
+};
+var DEFAULTS = {
+  enabled: true,
+  mode: "block",
+  warnAfter: 3,
+  blockAfter: 5,
+  oscillationWindow: 8,
+  ignoreTools: []
+};
+function readConfig(raw) {
+  if (!raw || typeof raw !== "object") return { ...DEFAULTS };
+  const r = raw;
+  const warnAfter = typeof r["warnAfter"] === "number" && r["warnAfter"] >= 2 ? r["warnAfter"] : DEFAULTS.warnAfter;
+  const blockAfter = typeof r["blockAfter"] === "number" && r["blockAfter"] > warnAfter ? r["blockAfter"] : Math.max(DEFAULTS.blockAfter, warnAfter + 1);
+  return {
+    enabled: r["enabled"] !== false,
+    mode: r["mode"] === "warn" ? "warn" : "block",
+    warnAfter,
+    blockAfter,
+    oscillationWindow: typeof r["oscillationWindow"] === "number" && r["oscillationWindow"] >= 4 ? r["oscillationWindow"] : DEFAULTS.oscillationWindow,
+    ignoreTools: Array.isArray(r["ignoreTools"]) ? r["ignoreTools"].filter((t) => typeof t === "string") : []
+  };
+}
+function canonicalize(value) {
+  try {
+    return JSON.stringify(sortKeys(value));
+  } catch {
+    return String(value);
+  }
+}
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = sortKeys(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+function fingerprint(toolName, toolInput) {
+  return `${toolName}\0${canonicalize(toolInput)}`;
+}
+function isOscillating(recent, windowSize) {
+  if (recent.length < windowSize) return false;
+  const window = recent.slice(-windowSize);
+  const unique = new Set(window);
+  if (unique.size !== 2) return false;
+  for (let i = 2; i < window.length; i++) {
+    if (window[i] !== window[i - 2]) return false;
+  }
+  return window[0] !== window[1];
+}
+var plugin = {
+  name: "loop-breaker",
+  version: "0.1.0",
+  description: "Detects runaway tool-call loops (identical repeats and A-B-A-B oscillation) \u2014 warns the model, then blocks",
+  apiVersion: "^0.1.10",
+  capabilities: { tools: true, hooks: true },
+  defaultConfig: { ...DEFAULTS },
+  configSchema: {
+    type: "object",
+    properties: {
+      enabled: { type: "boolean", default: true, description: "Master switch." },
+      mode: {
+        type: "string",
+        enum: ["block", "warn"],
+        default: "block",
+        description: "block = refuse the repeated call; warn = only inject context."
+      },
+      warnAfter: {
+        type: "number",
+        minimum: 2,
+        default: 3,
+        description: "Consecutive identical calls before a warning is injected."
+      },
+      blockAfter: {
+        type: "number",
+        minimum: 3,
+        default: 5,
+        description: "Consecutive identical calls before the call is blocked."
+      },
+      oscillationWindow: {
+        type: "number",
+        minimum: 4,
+        default: 8,
+        description: "Recent-call window length used for A-B-A-B oscillation detection."
+      },
+      ignoreTools: {
+        type: "array",
+        items: { type: "string" },
+        default: [],
+        description: "Tool names exempt from loop detection."
+      }
+    }
+  },
+  setup(api) {
+    state.lastFingerprint = null;
+    state.streak = 0;
+    state.recent = [];
+    state.invocations = 0;
+    state.warnings = 0;
+    state.blocks = 0;
+    state.oscillationsDetected = 0;
+    if (state.hookUnregister) {
+      try {
+        state.hookUnregister();
+      } catch {
+      }
+      state.hookUnregister = null;
+    }
+    const cfg = readConfig(api.config.extensions?.["loop-breaker"]);
+    const hook = (input) => {
+      if (!cfg.enabled) return;
+      const toolName = input.toolName ?? "unknown";
+      if (cfg.ignoreTools.includes(toolName)) return;
+      state.invocations += 1;
+      const fp = fingerprint(toolName, input.toolInput);
+      if (fp === state.lastFingerprint) {
+        state.streak += 1;
+      } else {
+        state.lastFingerprint = fp;
+        state.streak = 1;
+      }
+      state.recent.push(fp);
+      if (state.recent.length > Math.max(cfg.oscillationWindow, 16)) {
+        state.recent.splice(0, state.recent.length - Math.max(cfg.oscillationWindow, 16));
+      }
+      if (state.streak >= cfg.blockAfter && cfg.mode === "block") {
+        state.blocks += 1;
+        api.metrics.counter("blocks");
+        return {
+          decision: "block",
+          reason: `loop-breaker: "${toolName}" has been called ${state.streak} times in a row with identical input. This looks like a runaway loop. Change the input, try a different tool, or explain to the user why repetition is needed. (Disable this guard via config.extensions["loop-breaker"].enabled = false.)`
+        };
+      }
+      if (state.streak >= cfg.warnAfter) {
+        state.warnings += 1;
+        api.metrics.counter("warnings");
+        const remaining = cfg.mode === "block" ? cfg.blockAfter - state.streak : null;
+        return {
+          decision: "allow",
+          additionalContext: `loop-breaker: "${toolName}" repeated ${state.streak}x with identical input.` + (remaining !== null && remaining > 0 ? ` It will be BLOCKED after ${remaining} more identical call(s).` : "") + " If the previous result was not what you needed, change the approach instead of retrying."
+        };
+      }
+      if (isOscillating(state.recent, cfg.oscillationWindow)) {
+        state.oscillationsDetected += 1;
+        api.metrics.counter("oscillations");
+        state.recent = [];
+        return {
+          decision: "allow",
+          additionalContext: `loop-breaker: the last ${cfg.oscillationWindow} tool calls alternate between two identical calls (A-B-A-B pattern). You appear to be undoing and redoing the same work. Step back and pick a single approach.`
+        };
+      }
+      return;
+    };
+    state.hookUnregister = api.registerHook("PreToolUse", "*", hook);
+    api.tools.register({
+      name: "loop_breaker_status",
+      description: "Reports loop-breaker state: config, current repeat streak, and counters (warnings, blocks, oscillations).",
+      inputSchema: { type: "object", properties: {} },
+      permission: "auto",
+      category: "Diagnostics",
+      mutating: false,
+      async execute() {
+        return {
+          ok: true,
+          enabled: cfg.enabled,
+          mode: cfg.mode,
+          warnAfter: cfg.warnAfter,
+          blockAfter: cfg.blockAfter,
+          oscillationWindow: cfg.oscillationWindow,
+          ignoreTools: cfg.ignoreTools,
+          currentStreak: state.streak,
+          counters: {
+            invocations: state.invocations,
+            warnings: state.warnings,
+            blocks: state.blocks,
+            oscillationsDetected: state.oscillationsDetected
+          }
+        };
+      }
+    });
+    api.log.info("loop-breaker plugin loaded", {
+      version: "0.1.0",
+      enabled: cfg.enabled,
+      mode: cfg.mode,
+      warnAfter: cfg.warnAfter,
+      blockAfter: cfg.blockAfter
+    });
+  },
+  teardown(api) {
+    if (state.hookUnregister) {
+      try {
+        state.hookUnregister();
+      } catch {
+      }
+      state.hookUnregister = null;
+    }
+    const final = {
+      invocations: state.invocations,
+      warnings: state.warnings,
+      blocks: state.blocks,
+      oscillationsDetected: state.oscillationsDetected
+    };
+    state.lastFingerprint = null;
+    state.streak = 0;
+    state.recent = [];
+    state.invocations = 0;
+    state.warnings = 0;
+    state.blocks = 0;
+    state.oscillationsDetected = 0;
+    api.log.info("loop-breaker: teardown complete", { final });
+  },
+  async health() {
+    return {
+      ok: true,
+      message: `loop-breaker: ${state.invocations} call(s) observed, ${state.warnings} warning(s), ${state.blocks} block(s), ${state.oscillationsDetected} oscillation(s)`,
+      counters: {
+        invocations: state.invocations,
+        warnings: state.warnings,
+        blocks: state.blocks,
+        oscillationsDetected: state.oscillationsDetected
+      }
+    };
+  }
+};
+var loop_breaker_default = plugin;
+
+export { loop_breaker_default as default };

package/dist/model-router.d.ts

@@ -0,0 +1,69 @@
+import { Plugin } from '@wrongstack/core';
+
+/**
+ * model-router plugin — routes each provider call to a different model
+ * based on declarative rules, on the wire.
+ *
+ * Like `llm-cache`, this registers an `AgentExtension.wrapProviderRunner`
+ * (composed around EVERY provider call in the agent loop). Before the
+ * request goes out, the plugin evaluates an ordered rule list against
+ * the request's size and shape and rewrites `request.model` to the
+ * first matching rule's target — e.g. small/tool-free turns to a cheap
+ * fast model, large refactors to a capable one.
+ *
+ * IMPORTANT constraint: the active provider instance is fixed for the
+ * session. Rerouting only works among models the CURRENT provider
+ * serves (e.g. anthropic `haiku` ↔ `opus`). Routing to a model id the
+ * provider doesn't recognize will fail at the provider — keep targets
+ * within one provider's catalog.
+ *
+ * Safety posture: opt-in — loads inert until
+ * `config.extensions['model-router'].enabled = true`. A `dryRun` mode
+ * (default) only records what it WOULD route without changing the model,
+ * so you can observe the routing before trusting it.
+ *
+ * Config (`config.extensions['model-router']`):
+ *
+ * ```jsonc
+ * {
+ *   "enabled": false,
+ *   "dryRun": true,             // observe only; do not rewrite the model
+ *   "rules": [
+ *     { "maxChars": 2000, "hasTools": false, "model": "claude-haiku-4-5" },
+ *     { "minChars": 40000, "model": "claude-opus-4-8" }
+ *   ]
+ * }
+ * ```
+ *
+ * A rule matches when ALL of its present conditions hold. The first
+ * matching rule wins; if none match, the request passes through with its
+ * original model.
+ *
+ * Tools:
+ *  - `model_router_status` — rules, mode, and per-target routing counts
+ *
+ * @public
+ */
+
+interface RouteRule {
+    /** Match when the request's total char size is <= this. */
+    maxChars?: number | undefined;
+    /** Match when the request's total char size is >= this. */
+    minChars?: number | undefined;
+    /** Match when the request has (true) / lacks (false) tools. */
+    hasTools?: boolean | undefined;
+    /** The model id to route matching requests to (required). */
+    model: string;
+}
+/**
+ * Total character size of the request's actual prompt text (system +
+ * message content). Only counts `text` block values and bare-string
+ * content — not structural fields like `type`/`role` — so the size is a
+ * meaningful proxy for prompt weight.
+ */
+declare function requestCharSize(request: Record<string, unknown>): number;
+/** First rule whose present conditions all hold, or null. */
+declare function pickRule(rules: RouteRule[], size: number, hasTools: boolean): RouteRule | null;
+declare const plugin: Plugin;
+
+export { plugin as default, pickRule, requestCharSize };