@polderlabs/bizar 3.23.1 → 4.2.0

package/plugins/bizar/src/key-rotation.ts

@@ -0,0 +1,218 @@
+/**
+ * plugins/bizar/src/key-rotation.ts
+ *
+ * Wraps a provider's fetch to automatically rotate through a list of API
+ * keys when the upstream returns a retryable status (429 / 402 / 5xx).
+ *
+ * Why this exists
+ * ───────────────
+ * MiniMax (like most LLM providers) applies per-key rate limits and
+ * quotas. When a key hits its limit, the request fails with 429 or 402
+ * and the agent session dies — there is no way to swap keys mid-session
+ * because the provider reads its key from auth.json once at init.
+ *
+ * opencode has no built-in multi-key rotation. This wrapper fills the gap:
+ *
+ *   • Read N keys from env vars (MINIMAX_API_KEY, MINIMAX_API_KEY_2,
+ *     ..., or MINIMAX_API_KEYS=key1,key2,...)
+ *   • On the first attempt, use key #0
+ *   • On 429/402/5xx response, retry with the next key (capped at N)
+ *   • On 401 (unauthorized) and other 4xx, do NOT rotate — those are
+ *     client errors that no key will fix
+ *
+ * Behaviour
+ * ─────────
+ * • Only POST requests targeting `/chat/completions` on a known provider
+ *   URL are intercepted. Other requests pass through untouched.
+ * • The `Authorization` header on the outgoing request is replaced with
+ *   the currently-selected key on every attempt. All other headers
+ *   (Content-Type, Accept, etc.) are preserved from the SDK.
+ * • Responses are NEVER consumed by this wrapper. The caller receives
+ *   the final response (success or last failure) intact, including its
+ *   unconsumed body stream — safe for SSE.
+ * • On a successful response, the "current key" index advances by one so
+ *   the next incoming request starts on a different key, spreading load.
+ * • On all-keys-exhausted, the last error response is returned so the
+ *   opencode SDK surfaces it normally — no special handling required
+ *   downstream.
+ *
+ * Concurrency
+ * ───────────
+ * Multiple requests can be in flight. The current-key index is shared
+ * state but JS is single-threaded, so a simple counter is safe. Each
+ * request reads the counter once at entry and writes it on success.
+ */
+
+import type { FetchLike } from "./reasoning-clean.js";
+
+export interface KeyRotationOptions {
+  /** Provider id whose requests should be wrapped (e.g. "minimax"). */
+  providerId: string;
+  /**
+   * List of API keys to rotate through. Must have at least 2 entries
+   * for rotation to kick in. A single-entry list (or empty) makes the
+   * wrapper a pass-through no-op.
+   */
+  apiKeys: string[];
+  /** Optional debug logger. */
+  debug?: (msg: string) => void;
+}
+
+/**
+ * HTTP status codes that indicate "this key is exhausted, try the next".
+ * 401 (unauthorized) is intentionally excluded — a bad key won't get
+ * better by retrying, and surfacing the auth error to the user is more
+ * useful than silently rotating past it.
+ */
+const RETRYABLE_STATUSES = new Set([
+  429, // Too Many Requests / rate limit
+  402, // Payment Required (quota exhausted)
+  500, 502, 503, 504, // Server errors that may be account-specific
+]);
+
+/** Decide whether `url` targets the provider we should rotate for.
+ *  Matches by substring on the provider id, mirroring the matcher in
+ *  `reasoning-clean.ts` so the two wrappers stay consistent. */
+function isProviderUrl(url: string, providerId: string): boolean {
+  const lower = url.toLowerCase();
+  const lp = providerId.toLowerCase();
+  return (
+    lower.includes(`/${lp}/`) ||
+    lower.includes(`/${lp}?`) ||
+    lower.includes(`${lp}.`) ||
+    lower.includes(`-${lp}.`) ||
+    lower.includes(`.${lp}/`)
+  );
+}
+
+/** Return a fresh `RequestInit` whose `Authorization` header is `Bearer <key>`.
+ *  Other headers from `init` are preserved. */
+function injectKey(init: RequestInit | undefined, key: string): RequestInit {
+  const headers = new Headers(init?.headers ?? {});
+  headers.set("Authorization", `Bearer ${key}`);
+  return { ...init, headers };
+}
+
+/**
+ * Wrap a fetch implementation so that requests to the target provider
+ * rotate through `apiKeys` on retryable status codes. Returns a function
+ * with the same signature as the original fetch.
+ */
+export function wrapFetchForKeyRotation(
+  originalFetch: FetchLike,
+  options: KeyRotationOptions,
+): FetchLike {
+  const { providerId, apiKeys, debug } = options;
+
+  if (apiKeys.length < 2) {
+    debug?.(
+      `key-rotation: apiKeys has ${apiKeys.length} entries; rotation disabled (need >= 2)`,
+    );
+    return originalFetch;
+  }
+
+  let currentIndex = 0;
+  let successCount = 0;
+  let rotationCount = 0;
+
+  return async (input, init) => {
+    const url =
+      typeof input === "string"
+        ? input
+        : input instanceof URL
+          ? input.toString()
+          : (input as Request).url;
+
+    // Only intercept POST chat-completions on the target provider.
+    // Everything else passes through untouched so the reasoning-clean
+    // wrapper (and any other wrapper) still sees the request.
+    if (!/\/chat\/completions(?:\?|$)/.test(url)) return originalFetch(input, init);
+    if (!isProviderUrl(url, providerId)) return originalFetch(input, init);
+    if ((init?.method ?? "POST").toUpperCase() !== "POST") return originalFetch(input, init);
+
+    const startIndex = currentIndex;
+    let lastResponse: Response | null = null;
+
+    for (let attempt = 0; attempt < apiKeys.length; attempt++) {
+      const keyIndex = (startIndex + attempt) % apiKeys.length;
+      const key = apiKeys[keyIndex]!;
+      const modifiedInit = injectKey(init, key);
+
+      let response: Response;
+      try {
+        response = await originalFetch(input, modifiedInit);
+      } catch (err) {
+        debug?.(
+          `key-rotation: fetch threw for key #${keyIndex}: ${(err as Error).message}`,
+        );
+        // Network errors also trigger retry with the next key.
+        if (attempt < apiKeys.length - 1) continue;
+        throw err;
+      }
+
+      lastResponse = response;
+
+      if (!RETRYABLE_STATUSES.has(response.status)) {
+        if (response.ok) {
+          successCount++;
+          // Advance the starting index so the next request begins on
+          // a different key — spreads load and avoids one hot key.
+          currentIndex = (keyIndex + 1) % apiKeys.length;
+        }
+        return response;
+      }
+
+      // Retryable status. Discard the response body and try the next key.
+      rotationCount++;
+      debug?.(
+        `key-rotation: key #${keyIndex} returned ${response.status}; ` +
+          `rotating to key #${(keyIndex + 1) % apiKeys.length}`,
+      );
+      // Best-effort body drain so the underlying connection can be reused.
+      try {
+        await response.body?.cancel();
+      } catch {
+        /* ignore */
+      }
+    }
+
+    debug?.(
+      `key-rotation: all ${apiKeys.length} keys exhausted; ` +
+        `returning last ${lastResponse?.status} response`,
+    );
+    return lastResponse!;
+  };
+}
+
+/**
+ * Resolve a list of MiniMax API keys from environment variables.
+ *
+ * Resolution order (first non-empty wins):
+ *   1. `MINIMAX_API_KEYS` — single env var holding a comma-separated list
+ *   2. `MINIMAX_API_KEY` + `MINIMAX_API_KEY_2`, `_3`, ..., `_16`
+ *   3. Empty array (rotation disabled)
+ *
+ * Whitespace around entries is trimmed; empty strings are filtered out.
+ * At most 16 keys are returned as a defensive cap so a misconfigured
+ * env var (e.g. an accidental comma-spam) cannot drive runaway rotation.
+ */
+export function discoverMiniMaxKeys(
+  env: Record<string, string | undefined> = process.env,
+): string[] {
+  const explicit = env.MINIMAX_API_KEYS;
+  if (explicit) {
+    return explicit
+      .split(",")
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0)
+      .slice(0, 16);
+  }
+  const keys: string[] = [];
+  const primary = env.MINIMAX_API_KEY;
+  if (primary && primary.trim().length > 0) keys.push(primary.trim());
+  for (let i = 2; i <= 16; i++) {
+    const k = env[`MINIMAX_API_KEY_${i}`];
+    if (k && k.trim().length > 0) keys.push(k.trim());
+  }
+  return keys;
+}

package/plugins/bizar/src/logger.ts

@@ -0,0 +1,144 @@
+/**
+ * Logger — thin wrapper over `client.app.log`.
+ *
+ * Spec requirements satisfied here:
+ *   - §6.5 — honors `BIZAR_LOG_LEVEL` env var (`debug` | `info` | `warn` | `error`,
+ *     default `info`, invalid values fall back to `info` with a warning).
+ *   - §7.6 — never accepts or emits raw tool args / session content. Every call
+ *     to `client.app.log` is `{ level, message }` (or the SDK's wrapped
+ *     `{ body: { service, level, message } }` shape) where `message` is a
+ *     static string the caller constructed. There is no second argument,
+ *     no metadata object, no structured logging payload.
+ *
+ * The logger swallows all errors from the underlying `client.app.log` call.
+ * A failed log MUST NOT crash the plugin or block the tool hook.
+ *
+ * The interface is intentionally compatible with the `Logger` shape that
+ * Thor's `StateStore` and `LogWriter` accept: a single `log(opts)` method
+ * returning `void` (synchronous). We also expose level-specific convenience
+ * methods (`debug` / `info` / `warn` / `error`) that all delegate to `log`.
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+/**
+ * Minimal client surface the logger depends on. The real opencode client's
+ * `app.log` is a generated SDK method with a complex Options<T> type; we
+ * accept any object with a compatible `app.log` method and treat the body
+ * as an opaque `unknown` at the boundary. The logger internally shapes the
+ * call to the SDK's expected `{ body: { service, level, message } }` form.
+ */
+export interface LoggerClient {
+  app: {
+    log: (input: unknown) => unknown;
+  };
+}
+
+/**
+ * The Logger interface matches the one defined in `state.ts` and `report.ts`
+ * (Thor's modules). A single `log(opts)` method, synchronous, returns `void`.
+ * The convenience methods are additive.
+ */
+export interface Logger {
+  log(opts: { level: LogLevel; message: string }): void;
+  debug(message: string): void;
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+}
+
+interface ParsedLogLevel {
+  level: LogLevel;
+  wasInvalid: boolean;
+  original: string | undefined;
+}
+
+function parseLogLevel(raw: string | undefined): ParsedLogLevel {
+  if (raw === undefined || raw === "") {
+    return { level: "info", wasInvalid: false, original: raw };
+  }
+  const lower = raw.toLowerCase();
+  if (lower === "debug" || lower === "info" || lower === "warn" || lower === "error") {
+    return { level: lower, wasInvalid: false, original: raw };
+  }
+  return { level: "info", wasInvalid: true, original: raw };
+}
+
+function readEnvLevel(): string | undefined {
+  try {
+    return typeof process !== "undefined" && process.env
+      ? process.env.BIZAR_LOG_LEVEL
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Service name stamped onto every log entry. Lets users filter app logs
+ * by service (e.g. `bizar`) in their diagnostic tooling.
+ */
+const SERVICE_NAME = "bizar";
+
+/**
+ * Construct a Logger bound to the opencode client.
+ *
+ * @param client    The opencode client (we use only `client.app.log`).
+ * @param envLevel  Optional override for `BIZAR_LOG_LEVEL`. If omitted, the
+ *                  env var is read once. Env vars are read at plugin init;
+ *                  mid-session changes are ignored (spec §6.5).
+ */
+export function createLogger(client: LoggerClient, envLevel?: string): Logger {
+  const raw = envLevel ?? readEnvLevel();
+  const parsed = parseLogLevel(raw);
+  const threshold = parsed.level;
+
+  if (parsed.wasInvalid) {
+    // Best-effort: warn about the invalid value, then proceed with "info".
+    // We call `client.app.log` directly because the logger is not yet wired
+    // to the threshold.
+    try {
+      client.app.log({
+        body: { service: SERVICE_NAME, level: "warn", message: `bizar: invalid BIZAR_LOG_LEVEL "${parsed.original ?? ""}", falling back to "info"` },
+      });
+    } catch {
+      // ignore — never let a warning crash init
+    }
+  }
+
+  function emit(msgLevel: LogLevel, message: string): void {
+    if (LEVEL_ORDER[msgLevel] < LEVEL_ORDER[threshold]) return;
+    try {
+      client.app.log({
+        body: { service: SERVICE_NAME, level: msgLevel, message },
+      });
+    } catch {
+      // Swallow — a failed log MUST NOT crash the plugin.
+    }
+  }
+
+  return {
+    log(opts) {
+      emit(opts.level, opts.message);
+    },
+    debug(message) {
+      emit("debug", message);
+    },
+    info(message) {
+      emit("info", message);
+    },
+    warn(message) {
+      emit("warn", message);
+    },
+    error(message) {
+      emit("error", message);
+    },
+  };
+}

package/plugins/bizar/src/loop.ts

@@ -0,0 +1,176 @@
+/**
+ * Loop — the threshold decision tree.
+ *
+ * Spec requirements satisfied here:
+ *   - §5.1 — algorithm. Count how many of the last `loopWindowSize` tool
+ *     calls share the given fingerprint. Re-scan the window each call.
+ *   - §5.4 — threshold table. The action returned by `decide()` corresponds
+ *     to the highest threshold that the count meets or exceeds.
+ *   - §5.5 — window vs counter semantics. The count is a re-scan of the
+ *     window, not a running counter. The intermediate non-matching calls
+ *     in the window do NOT "reset" anything; they just sit in the window
+ *     and shift older matching entries out as the window rolls forward.
+ *   - §7.2 — the `reason` field returned by `decide()` for warn/escalate/
+ *     block actions is a static message from `handoff.ts` with only the
+ *     tool name interpolated. No tool args, no LLM output, no agent-
+ *     controlled content is ever included.
+ *
+ * The `now` parameter is part of the public signature for API consistency
+ * with the spec (§5.1 timing context) but is not consumed by the decision
+ * logic — callers use it to timestamp the current tool call when adding it
+ * to the state.
+ */
+
+import type { SessionState } from "./state.js";
+import type { NormalizedOptions } from "./options.js";
+import {
+  warnMessage,
+  escalateMessage,
+  blockMessage,
+} from "./handoff.js";
+
+/**
+ * The decision returned by `decide()`. The `allow` variant carries no
+ * payload; the three action variants carry the canonical handoff message
+ * (via `reason`), the fingerprint that triggered the decision, and the
+ * repetition count in the window.
+ */
+export type Decision =
+  | { action: "allow" }
+  | {
+      action: "warn" | "escalate" | "block";
+      reason: string;
+      fingerprint: string;
+      count: number;
+    };
+
+/**
+ * Implicit "log a warning" threshold from spec §5.4 row 1. This is always
+ * two below `loopThresholdWarn` so the gap between log-only and inject-warn
+ * stays constant when the user reconfigures. We `max(1, …)` so a user who
+ * sets `loopThresholdWarn = 1` does not push the log-only threshold below 1.
+ */
+function logOnlyThreshold(options: NormalizedOptions): number {
+  return Math.max(1, options.loopThresholdWarn - 2);
+}
+
+/**
+ * Look at the last `loopWindowSize` tool calls and return those that share
+ * the given fingerprint. The window is a slice of the most recent entries;
+ * older entries are ignored (spec §5.1 step 3).
+ */
+function windowMatches(
+  state: SessionState,
+  fingerprint: string,
+  windowSize: number,
+): { calls: SessionState["toolCalls"]; count: number } {
+  if (state.toolCalls.length === 0 || windowSize <= 0) {
+    return { calls: [], count: 0 };
+  }
+  const start = Math.max(0, state.toolCalls.length - windowSize);
+  const window = state.toolCalls.slice(start);
+  const matches = window.filter((c) => c.fingerprint === fingerprint);
+  return { calls: matches, count: matches.length };
+}
+
+/**
+ * Recover the tool name from any call in `matches` that shares the
+ * fingerprint. The fingerprint is computed from `(tool, normalized args)`,
+ * so every call with this fingerprint has the same tool name. If the
+ * matches list is empty (should not happen when this is called — the
+ * caller only invokes us when `count >= 1`), fall back to `"unknown"`.
+ */
+function toolNameOf(matches: SessionState["toolCalls"]): string {
+  const first = matches[0];
+  return first ? first.tool : "unknown";
+}
+
+/**
+ * Build a Decision payload for a non-allow action. Pulls the canonical
+ * handoff message for the given action and the tool name recovered from
+ * the matching window entries.
+ */
+function payload(
+  action: "warn" | "escalate" | "block",
+  fingerprint: string,
+  count: number,
+  matches: SessionState["toolCalls"],
+): Decision {
+  const tool = toolNameOf(matches);
+  const reason =
+    action === "block"
+      ? blockMessage(tool)
+      : action === "escalate"
+        ? escalateMessage(tool)
+        : warnMessage(tool);
+  return { action, reason, fingerprint, count };
+}
+
+/**
+ * Decide what action to take for the current tool call.
+ *
+ * The function is pure: it does not mutate `state` and does not perform any
+ * I/O. The caller (the `tool.execute.before` hook in `index.ts`) is
+ * responsible for adding the current call to the state before invoking
+ * `decide()`, and for acting on the returned decision (log / inject / throw).
+ *
+ * @param state       The current session state. Must already include the
+ *                    current tool call in `state.toolCalls` (the caller
+ *                    appends it before calling `decide()`).
+ * @param fingerprint The fingerprint of the current tool call.
+ * @param now         Current epoch milliseconds. Part of the public signature
+ *                    for API consistency; not consumed by the decision logic.
+ * @param options     Normalized plugin options.
+ */
+export function decide(
+  state: SessionState,
+  fingerprint: string,
+  now: number,
+  options: NormalizedOptions,
+): Decision {
+  // Step 1: scan the window.
+  const { calls: matches, count } = windowMatches(
+    state,
+    fingerprint,
+    options.loopWindowSize,
+  );
+
+  // Step 2: apply thresholds from highest to lowest.
+  if (count >= options.loopThresholdBlock) {
+    return payload("block", fingerprint, count, matches);
+  }
+  if (count >= options.loopThresholdEscalate) {
+    return payload("escalate", fingerprint, count, matches);
+  }
+  if (count >= options.loopThresholdWarn) {
+    return payload("warn", fingerprint, count, matches);
+  }
+
+  // Step 3: log-only band (spec §5.4 row 1). Sits between `allow` and the
+  // inject-warn threshold. The caller distinguishes this case from
+  // inject-warn by inspecting `count` against `options.loopThresholdWarn`.
+  const logOnly = logOnlyThreshold(options);
+  if (count >= logOnly) {
+    return payload("warn", fingerprint, count, matches);
+  }
+
+  // `now` is accepted for API consistency; reference it so strict no-unused
+  // linters do not flag the parameter.
+  void now;
+
+  return { action: "allow" };
+}
+
+/**
+ * Convenience helper for the caller: given a `warn` decision, was this the
+ * log-only band (no injection) or the inject-warn band? The caller uses
+ * this to decide whether to write a `client.app.log` line or to set a
+ * pending system-transform injection.
+ */
+export function isLogOnlyWarn(
+  decision: Decision,
+  options: NormalizedOptions,
+): boolean {
+  if (decision.action !== "warn") return false;
+  return decision.count < options.loopThresholdWarn;
+}