@polderlabs/bizar 6.2.4 → 6.3.0

package/plugins/bizar/src/logger.ts

@@ -1,144 +0,0 @@
-/**
- * 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 cline 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 cline client.
- *
- * @param client    The cline 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-engineering.ts

@@ -1,241 +0,0 @@
-/**
- * loop-engineering.ts
- *
- * v6.0.0 — Structured loop patterns for continuous agent execution.
- *
- * Inspired by:
- *   - https://github.com/cobusgreyling/loop-engineering
- *   - https://github.com/rudy2steiner/awesome-agent-loops
- *
- * Patterns supported (v1):
- *
- *   1. **ralph** — repeat until output contains `[STOP]` marker, or until
- *      `maxIterations` is reached, or until a manual stop signal.
- *   2. **repl**  — interactive, awaits user input between iterations
- *      (not yet implemented in v1).
- *   3. **cron**  — interval-based; reruns every N seconds.
- *   4. **plan-execute** — decompose once, iterate over subtasks.
- *
- * Loops are stored on disk as JSON files at:
- *   ~/.bizar/loops/<loopId>.json
- *
- * Each loop has:
- *   - id, pattern, task, status (running | stopped | done)
- *   - iterations[] — log of { index, startedAt, durationMs, output, stopReason }
- *   - context — pattern-specific config (interval, maxIterations, etc.)
- */
-
-import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-
-export type LoopPattern = "ralph" | "repl" | "cron" | "plan-execute";
-export type LoopStatus = "running" | "stopped" | "done";
-
-export interface LoopIteration {
-  index: number;
-  startedAt: string;
-  durationMs: number;
-  output: string;
-  stopReason?: string;
-}
-
-export interface LoopContext {
-  maxIterations: number;
-  stopMarker?: string;
-  intervalSeconds?: number;
-  subtasks?: string[];
-}
-
-export interface Loop {
-  id: string;
-  pattern: LoopPattern;
-  task: string;
-  status: LoopStatus;
-  createdAt: string;
-  updatedAt: string;
-  context: LoopContext;
-  iterations: LoopIteration[];
-}
-
-const LOOPS_DIR = join(homedir(), ".bizar", "loops");
-
-function ensureLoopsDir(): void {
-  if (!existsSync(LOOPS_DIR)) {
-    mkdirSync(LOOPS_DIR, { recursive: true });
-  }
-}
-
-function generateLoopId(): string {
-  return `loop_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
-}
-
-export interface StartLoopInput {
-  pattern: LoopPattern;
-  task: string;
-  context?: Partial<LoopContext>;
-}
-
-export interface StartLoopOutput {
-  ok: true;
-  loop: Loop;
-}
-
-export function startLoop(input: StartLoopInput): StartLoopOutput {
-  ensureLoopsDir();
-  const id = generateLoopId();
-  const now = new Date().toISOString();
-  const loop: Loop = {
-    id,
-    pattern: input.pattern,
-    task: input.task,
-    status: "running",
-    createdAt: now,
-    updatedAt: now,
-    context: {
-      maxIterations: input.context?.maxIterations ?? 10,
-      stopMarker: input.context?.stopMarker,
-      intervalSeconds: input.context?.intervalSeconds,
-      subtasks: input.context?.subtasks,
-    },
-    iterations: [],
-  };
-  writeFileSync(join(LOOPS_DIR, `${id}.json`), JSON.stringify(loop, null, 2));
-  return { ok: true, loop };
-}
-
-export function loadLoop(id: string): Loop | null {
-  const path = join(LOOPS_DIR, `${id}.json`);
-  if (!existsSync(path)) return null;
-  return JSON.parse(readFileSync(path, "utf8")) as Loop;
-}
-
-export function saveLoop(loop: Loop): void {
-  loop.updatedAt = new Date().toISOString();
-  writeFileSync(join(LOOPS_DIR, `${loop.id}.json`), JSON.stringify(loop, null, 2));
-}
-
-/**
- * Append an iteration result to a loop and update its status if a stop
- * condition was met.
- */
-export function appendIteration(
-  id: string,
-  result: Omit<LoopIteration, "startedAt"> & { startedAt?: string },
-): Loop | null {
-  const loop = loadLoop(id);
-  if (!loop) return null;
-  const iter: LoopIteration = {
-    index: loop.iterations.length,
-    startedAt: result.startedAt ?? new Date().toISOString(),
-    durationMs: result.durationMs,
-    output: result.output,
-    stopReason: result.stopReason,
-  };
-  loop.iterations.push(iter);
-  if (loop.context.maxIterations > 0 && loop.iterations.length >= loop.context.maxIterations) {
-    loop.status = "done";
-  } else if (
-    loop.pattern === "ralph" &&
-    loop.context.stopMarker &&
-    result.output.includes(loop.context.stopMarker)
-  ) {
-    loop.status = "done";
-    iter.stopReason = `stop marker "${loop.context.stopMarker}" found`;
-  }
-  saveLoop(loop);
-  return loop;
-}
-
-/**
- * Mark a loop as stopped (manual stop signal).
- *
- * If `reason` is given AND the loop has at least one iteration, attach
- * the reason to the most recent iteration. Otherwise, append a synthetic
- * "stopped" iteration so the reason is preserved in the audit log.
- */
-export function stopLoop(id: string, reason?: string): Loop | null {
-  const loop = loadLoop(id);
-  if (!loop) return null;
-  loop.status = "stopped";
-  if (reason) {
-    if (loop.iterations.length > 0) {
-      const last = loop.iterations[loop.iterations.length - 1];
-      if (last) last.stopReason = reason;
-    } else {
-      // Append a synthetic iteration so the reason isn't lost.
-      loop.iterations.push({
-        index: 0,
-        startedAt: new Date().toISOString(),
-        durationMs: 0,
-        output: "(loop stopped before any iterations ran)",
-        stopReason: reason,
-      });
-    }
-  }
-  saveLoop(loop);
-  return loop;
-}
-
-/**
- * Delete a loop from disk.
- */
-export function deleteLoop(id: string): boolean {
-  const path = join(LOOPS_DIR, `${id}.json`);
-  if (!existsSync(path)) return false;
-  unlinkSync(path);
-  return true;
-}
-
-/**
- * List all loops on disk, optionally filtered by status / pattern.
- */
-export function listLoops(filter?: { status?: LoopStatus; pattern?: LoopPattern }): Loop[] {
-  ensureLoopsDir();
-  const files = readdirSync(LOOPS_DIR).filter((f) => f.endsWith(".json"));
-  const out: Loop[] = [];
-  for (const f of files) {
-    try {
-      const l = JSON.parse(readFileSync(join(LOOPS_DIR, f), "utf8")) as Loop;
-      if (filter?.status && l.status !== filter.status) continue;
-      if (filter?.pattern && l.pattern !== filter.pattern) continue;
-      out.push(l);
-    } catch {
-      // skip malformed
-    }
-  }
-  return out.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
-}
-
-/**
- * Pattern execution: given a loop, return the prompt for the next
- * iteration and the stop marker to look for (if any).
- */
-export function buildNextIteration(loop: Loop): { prompt: string; stopMarker: string | null } {
-  switch (loop.pattern) {
-    case "ralph": {
-      const stopMarker = loop.context.stopMarker ?? "[STOP]";
-      const iterIndex = loop.iterations.length + 1;
-      const prompt = [
-        `Loop iteration ${iterIndex} of ${loop.context.maxIterations}.`,
-        `Task: ${loop.task}`,
-        ``,
-        `Output the literal marker "${stopMarker}" on its own line when done.`,
-      ].join("\n");
-      return { prompt, stopMarker };
-    }
-    case "cron":
-      return { prompt: loop.task, stopMarker: null };
-    case "plan-execute": {
-      const subs = loop.context.subtasks ?? [];
-      const nextIdx = loop.iterations.length;
-      const subtask = subs[nextIdx] ?? "(no more subtasks)";
-      return {
-        prompt: `Subtask ${nextIdx + 1} of ${subs.length}: ${subtask}`,
-        stopMarker: null,
-      };
-    }
-    case "repl":
-      return { prompt: loop.task, stopMarker: null };
-  }
-}

package/plugins/bizar/src/loop.ts

@@ -1,176 +0,0 @@
-/**
- * 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;
-}

package/plugins/bizar/src/mistake-recovery.ts

@@ -1,98 +0,0 @@
-/**
- * mistake-recovery.ts
- *
- * v6.0.1 — Built-in `onConsecutiveMistakeLimitReached` callback for the
- * Cline runtime.
- *
- * Why this exists:
- *
- *   The Cline runtime aborts a session after `execution.maxConsecutiveMistakes`
- *   identical-failure turns. The bundled CLI defaults this to 3 (via the
- *   `--retries` flag); the SDK default is 6. When the model emits malformed
- *   tool calls — e.g. `editor({ new_text: undefined })`, `ask_question({ options: null })`,
- *   `run_commands({ ... })` rejected by Zod — the counter increments on every
- *   iteration and the session is dead after a couple of bad turns.
- *
- *   Rather than raising the threshold (which masks the model misbehaviour),
- *   we install a `onConsecutiveMistakeLimitReached` callback that:
- *
- *     • For recoverable mistakes (invalid_tool_call, tool_execution_failed),
- *       injects a recovery notice into the conversation and resets the
- *       counter. Cline's `MistakeTracker.record()` returns
- *       `{ action: "continue", guidance: "..." }` and appends the guidance
- *       as a user message, then continues the run.
- *
- *     • For infra errors (api_error), stops immediately. Retrying a
- *       network/provider failure is wasted work.
- *
- *   This keeps the threshold tight (model discipline matters) while
- *   preventing a single bad turn from killing a long-running task.
- */
-
-import type {
-  ConsecutiveMistakeLimitContext,
-  ConsecutiveMistakeLimitDecision,
-} from "@cline/shared";
-
-const RECOVERABLE_REASONS = new Set<ConsecutiveMistakeLimitContext["reason"]>([
-  "invalid_tool_call",
-  "tool_execution_failed",
-]);
-
-export interface MistakeRecoveryOptions {
-  /**
-   * Called after the recovery notice is appended but before the run
-   * continues. Receives the full context for observability.
-   */
-  onRecovery?: (ctx: ConsecutiveMistakeLimitContext, guidance: string) => void;
-  /**
-   * Override the recovery guidance text. Defaults to `BUILTIN_RECOVERY_GUIDANCE`.
-   */
-  guidance?: string;
-}
-
-/**
- * The default guidance appended to the conversation when consecutive
- * recoverable mistakes trip the limit. Kept terse on purpose — longer
- * text dilutes model attention.
- */
-export const BUILTIN_RECOVERY_GUIDANCE = [
-  "You reached the consecutive-mistake limit. Before retrying:",
-  "",
-  "1. Re-read the failing tool's input schema. Every required field MUST be",
-  "   populated with a non-null value of the right type.",
-  "2. For `editor`: `new_text` must be a non-empty string. If you intended",
-  "   to delete content, set `new_text` to \"\" (empty string) and use",
-  "   `applyPatch` or `delete_file` instead.",
-  "3. For `ask_question`: `options` must be an array of ≥2 non-empty",
-  "   strings. Do not pass null, undefined, or arrays of length < 2.",
-  "4. For `run_commands`: `commands` must be a non-empty array of strings.",
-  "5. If you have made two mistakes on the SAME tool, switch tools or stop",
-  "   and explain in plain text what went wrong instead of retrying.",
-  "",
-  "Acknowledge this notice and continue.",
-].join("\n");
-
-/**
- * Default stop reason when an unrecoverable mistake hits the limit.
- */
-export const BUILTIN_STOP_REASON = "consecutive api_errors — stopping without retry";
-
-/**
- * Build an `onConsecutiveMistakeLimitReached` callback.
- *
- * Pass the result directly to `cline.start({ config: { onConsecutiveMistakeLimitReached } })`.
- */
-export function buildMistakeRecovery(
-  opts: MistakeRecoveryOptions = {},
-): (ctx: ConsecutiveMistakeLimitContext) => Promise<ConsecutiveMistakeLimitDecision> | ConsecutiveMistakeLimitDecision {
-  const guidance = opts.guidance ?? BUILTIN_RECOVERY_GUIDANCE;
-  const onRecovery = opts.onRecovery;
-  return (ctx) => {
-    if (RECOVERABLE_REASONS.has(ctx.reason)) {
-      onRecovery?.(ctx, guidance);
-      return { action: "continue", guidance };
-    }
-    return { action: "stop", reason: BUILTIN_STOP_REASON };
-  };
-}