@polderlabs/bizar-plugin 0.5.4

package/src/plan-fs.ts

@@ -0,0 +1,323 @@
+/**
+ * plan-fs.ts
+ *
+ * v0.5.0 — Plan filesystem operations.
+ *
+ * Pure file-I/O helpers for the on-disk plan layout used by the v2
+ * canvas:
+ *
+ *     <worktree>/plans/<slug>/meta.json   — status + bookkeeping
+ *     <worktree>/plans/<slug>/plan.json   — v2 canvas
+ *
+ * This module is the **only** place in the plugin that knows the
+ * layout. Both `src/commands-impl.ts` (slash-command side effects)
+ * and `src/tools/plan-action.ts` (the `bizar_plan_action` tool) build
+ * on these primitives. The CLI in `cli/plan.mjs` duplicates the same
+ * layout (language boundary: mjs vs ts); keep both copies in sync.
+ *
+ * Concurrency:
+ *   - All writes go through a single async mutex so two concurrent
+ *     `createPlan()` calls cannot both create the same slug, and so a
+ *     `createPlan` racing with a `bizar_plan_action` write never
+ *     produces a partial state on disk.
+ *   - Writes are atomic: write to `<file>.tmp`, then `renameSync` to
+ *     the final path. A crash mid-write leaves a `.tmp` orphan — the
+ *     `rmSync` in the catch block is best-effort.
+ *
+ * Errors:
+ *   - All functions return a discriminated result object (`{ ok: true, ... }`
+ *     or `{ ok: false, error: ... }`) and NEVER throw. Callers can
+ *     surface the error string to the user.
+ *   - Slug validation: every public function validates the slug with
+ *     `SLUG_REGEX` and returns `{ ok: false, error: ... }` on failure.
+ *
+ * [KEEP-IN-SYNC-WITH cli/plan.mjs] — the CLI in `cli/plan.mjs` mirrors
+ * the layout. If you change the canvas or meta shape, update both.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+
+import type { Logger } from "./logger.js";
+
+// --- Constants ------------------------------------------------------------
+
+/** Same slug rule used everywhere in the project. */
+const SLUG_REGEX = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+/** Initial status of a freshly created plan. */
+const DEFAULT_STATUS = "draft" as const;
+
+// --- Types ----------------------------------------------------------------
+
+/** Public result type for all plan-fs operations. */
+export type PlanFsResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: string };
+
+/** A summary row used by `listPlans`. */
+export interface PlanListEntry {
+  slug: string;
+  status: string;
+  lastEdited: string;
+}
+
+/** The shape stored in `meta.json`. */
+export interface PlanMeta {
+  status: string;
+  lastEdited: string;
+  /** Anything else the viewer/agent has written into meta. */
+  [key: string]: unknown;
+}
+
+/** The shape stored in `plan.json` (v2 canvas). */
+export interface PlanCanvas {
+  schemaVersion: 2;
+  title: string;
+  elements: unknown[];
+  connections: unknown[];
+  comments: unknown[];
+  viewport: { x: number; y: number; zoom: number };
+  lastEdited: string;
+  [key: string]: unknown;
+}
+
+/** Returned by `createPlan` on success. */
+export interface CreatePlanSuccess {
+  meta: PlanMeta;
+  canvas: PlanCanvas;
+}
+
+// --- Module-level mutex ---------------------------------------------------
+
+/** Per-process mutex. Serializes every plan-fs mutation. */
+const locks: { chain: Promise<unknown> } = { chain: Promise.resolve() };
+
+async function withLock<T>(fn: () => Promise<T>): Promise<T> {
+  const prev = locks.chain ?? Promise.resolve();
+  const next = prev.then(fn, fn);
+  locks.chain = next.catch(() => {});
+  return next;
+}
+
+// --- Helpers --------------------------------------------------------------
+
+function planDir(worktree: string, slug: string): string {
+  return join(worktree, "plans", slug);
+}
+
+function metaPath(worktree: string, slug: string): string {
+  return join(planDir(worktree, slug), "meta.json");
+}
+
+function canvasPath(worktree: string, slug: string): string {
+  return join(planDir(worktree, slug), "plan.json");
+}
+
+function isValidSlug(slug: string): boolean {
+  return SLUG_REGEX.test(slug);
+}
+
+function readJson<T>(filePath: string): T | null {
+  if (!existsSync(filePath)) return null;
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw) as unknown;
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed as T;
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonAtomic(
+  filePath: string,
+  data: unknown,
+  logger: Logger,
+): { ok: true } | { ok: false; error: string } {
+  const tmp = `${filePath}.tmp`;
+  try {
+    mkdirSync(join(filePath, ".."), { recursive: true });
+    writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
+    renameSync(tmp, filePath);
+    return { ok: true };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logger.warn(`bizar: plan-fs: failed to write ${filePath}: ${msg}`);
+    try {
+      if (existsSync(tmp)) rmSync(tmp);
+    } catch {
+      // best-effort cleanup
+    }
+    return { ok: false, error: `Failed to write ${filePath}: ${msg}` };
+  }
+}
+
+function titleCaseFromSlug(slug: string): string {
+  return slug
+    .split(/[-_]/)
+    .map((w) => (w.length === 0 ? w : w[0]!.toUpperCase() + w.slice(1)))
+    .join(" ");
+}
+
+// --- Public API -----------------------------------------------------------
+
+/**
+ * Create a new plan at `<worktree>/plans/<slug>/`. The directory
+ * contains:
+ *
+ *   - `meta.json`  — `{ status: "draft", lastEdited: <iso>, title }`
+ *   - `plan.json`  — minimal v2 canvas (empty elements / connections / comments)
+ *
+ * If a plan with the same slug already exists, returns
+ * `{ ok: false, error: "Plan already exists: <slug>" }` — we never
+ * clobber. Callers should explicitly `/plan delete` first if they
+ * want a fresh canvas.
+ *
+ * The `template` option is currently informational only — the v0.5.0
+ * MVP always scaffolds a blank canvas. Future versions may seed the
+ * canvas with template-specific elements.
+ */
+export async function createPlan(
+  worktree: string,
+  slug: string,
+  opts: { template?: string | null; logger: Logger },
+): Promise<PlanFsResult<CreatePlanSuccess>> {
+  if (!isValidSlug(slug)) {
+    return {
+      ok: false,
+      error: `Invalid slug "${slug}". Must match ^[a-z0-9][a-z0-9-]{0,63}$.`,
+    };
+  }
+
+  return withLock(async () => {
+    const dir = planDir(worktree, slug);
+    if (existsSync(dir)) {
+      return {
+        ok: false,
+        error:
+          `Plan "${slug}" already exists at ${dir}. ` +
+          `Use /plan delete ${slug} first, or pick a new slug.`,
+      };
+    }
+
+    const now = new Date().toISOString();
+    const title = titleCaseFromSlug(slug);
+    const meta: PlanMeta = {
+      status: DEFAULT_STATUS,
+      lastEdited: now,
+      title,
+    };
+    const canvas: PlanCanvas = {
+      schemaVersion: 2,
+      title,
+      elements: [],
+      connections: [],
+      comments: [],
+      viewport: { x: 0, y: 0, zoom: 1 },
+      lastEdited: now,
+    };
+
+    // Ensure the directory exists before writing (writeJsonAtomic also
+    // mkdir's the parent, but doing it explicitly lets us return a
+    // clearer error).
+    try {
+      mkdirSync(dir, { recursive: true });
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      opts.logger.warn(`bizar: plan-fs: mkdir failed for ${dir}: ${msg}`);
+      return { ok: false, error: `Cannot create plan directory: ${dir} (${msg})` };
+    }
+
+    const metaRes = writeJsonAtomic(metaPath(worktree, slug), meta, opts.logger);
+    if (!metaRes.ok) return metaRes;
+    const canvasRes = writeJsonAtomic(canvasPath(worktree, slug), canvas, opts.logger);
+    if (!canvasRes.ok) {
+      // Roll back the partially-created directory so a retry has a
+      // clean slate. Best-effort.
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+      return canvasRes;
+    }
+
+    opts.logger.info(
+      `bizar: plan-fs: created plan "${slug}" at ${dir} (template=${opts.template ?? "blank"})`,
+    );
+    return { ok: true, value: { meta, canvas } };
+  });
+}
+
+/**
+ * List the plans in `<worktree>/plans/`. Returns an array sorted by
+ * slug. Each entry has `slug`, `status` (from `meta.json` if present,
+ * else `"unknown"`), and `lastEdited` (ISO timestamp or `""` if
+ * missing).
+ *
+ * Returns `[]` when the worktree has no `plans/` directory — that's
+ * the "no plans yet" case, not an error.
+ */
+export async function listPlans(
+  worktree: string,
+  _logger: Logger,
+): Promise<PlanListEntry[]> {
+  const dir = join(worktree, "plans");
+  if (!existsSync(dir)) return [];
+
+  // Use sync readdir here — the function is called rarely (from
+  // /plan list) and the directory is small. Keeping the function
+  // async lets us swap in an async implementation later.
+  const { readdirSync, statSync } = await import("node:fs");
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+
+  const out: PlanListEntry[] = [];
+  for (const name of entries) {
+    const full = join(dir, name);
+    try {
+      const stat = statSync(full);
+      if (!stat.isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    if (!isValidSlug(name)) continue; // skip non-slug dirs
+
+    const meta = readJson<PlanMeta>(metaPath(worktree, name));
+    out.push({
+      slug: name,
+      status: meta?.status ?? "unknown",
+      lastEdited:
+        typeof meta?.lastEdited === "string" ? meta.lastEdited : "",
+    });
+  }
+  out.sort((a, b) => a.slug.localeCompare(b.slug));
+  return out;
+}
+
+/**
+ * Read `meta.json` for a plan. Returns `null` if the plan or the
+ * meta file does not exist. The caller decides what "missing" means
+ * (the slash command treats it as a soft error).
+ */
+export async function getPlanMeta(
+  worktree: string,
+  slug: string,
+): Promise<PlanMeta | null> {
+  if (!isValidSlug(slug)) return null;
+  return readJson<PlanMeta>(metaPath(worktree, slug));
+}

package/src/report.ts

@@ -0,0 +1,178 @@
+/**
+ * report.ts
+ *
+ * Per-session log writer. Appends metadata-only lines (no args) to
+ * ~/.cache/bizar/logs/<sessionId>.log with 10 MB rotation.
+ * Per §7.1, §7.6, §8.3, §10.1.
+ */
+
+import { appendFileSync, renameSync, unlinkSync, existsSync, statSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+/** Minimal Logger interface — same shape as state.ts */
+export interface Logger {
+  log(opts: { level: "debug" | "info" | "warn" | "error"; message: string }): void;
+}
+
+function expandHome(p: string): string {
+  if (p.startsWith("~/") || p === "~") {
+    return path.join(os.homedir(), p.slice(1));
+  }
+  return p;
+}
+
+/**
+ * Log line format (per §7.1):
+ * 2026-06-17T14:30:01.123Z agent=thor tool=read fingerprint=ab12cd outcome=ok duration=45ms
+ */
+function formatLine(
+  sessionId: string,
+  agent: string | null,
+  tool: string,
+  fingerprint: string,
+  outcome: "ok" | "error",
+  durationMs: number
+): string {
+  const ts = new Date().toISOString();
+  const agentPart = agent ? ` agent=${agent}` : "";
+  return `${ts}${agentPart} tool=${tool} fingerprint=${fingerprint} outcome=${outcome} duration=${durationMs}ms\n`;
+}
+
+/**
+ * Recursive mkdirSync with EACCES handling per §8.2.
+ */
+function ensureDir(dir: string, logger: Logger): boolean {
+  try {
+    mkdirSync(dir, { recursive: true });
+    return true;
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "EACCES" || code === "EROFS") {
+      logger.log({
+        level: "error",
+        message: `bizar: cannot create log directory ${dir}: ${String(err)}`,
+      });
+      return false;
+    }
+    throw err;
+  }
+}
+
+/**
+ * Rotate log files when current file exceeds maxBytes:
+ * 1. Delete .3.log (if exists)
+ * 2. Rename .2.log → .3.log
+ * 3. Rename .1.log → .2.log
+ * 4. Rename <sessionId>.log → .1.log
+ *
+ * Each step in its own try/catch. Best-effort — never blocks the write.
+ * Per §8.3.
+ */
+function rotateLog(logPath: string, logger: Logger): void {
+  const dir = path.dirname(logPath);
+
+  // Step 1: delete .3.log
+  const p3 = path.join(dir, ".3.log");
+  if (existsSync(p3)) {
+    try { unlinkSync(p3); } catch { /* non-fatal */ }
+  }
+
+  // Step 2: rename .2.log → .3.log
+  const p2 = path.join(dir, ".2.log");
+  if (existsSync(p2)) {
+    try { renameSync(p2, p3); } catch {
+      logger.log({ level: "warn", message: `bizar: log rotation .2→.3 failed` });
+    }
+  }
+
+  // Step 3: rename .1.log → .2.log
+  const p1 = path.join(dir, ".1.log");
+  if (existsSync(p1)) {
+    try { renameSync(p1, p2); } catch {
+      logger.log({ level: "warn", message: `bizar: log rotation .1→.2 failed` });
+    }
+  }
+
+  // Step 4: rename current → .1.log
+  if (existsSync(logPath)) {
+    try { renameSync(logPath, p1); } catch {
+      logger.log({ level: "warn", message: `bizar: log rotation current→.1 failed` });
+    }
+  }
+}
+
+export class LogWriter {
+  private logDir: string;
+  private maxBytes: number;
+  private logger: Logger;
+  private initialized = false;
+
+  constructor(logDir: string, maxBytes: number, logger: Logger) {
+    this.logDir = expandHome(logDir);
+    this.maxBytes = Math.max(1024, Math.floor(maxBytes));
+    this.logger = logger;
+  }
+
+  /**
+   * Lazily ensure the log directory exists.
+   */
+  private ensureLogDir(): boolean {
+    if (this.initialized) return true;
+    this.initialized = true;
+    return ensureDir(this.logDir, this.logger);
+  }
+
+  /**
+   * Append a metadata-only log line for a tool call.
+   *
+   * Per §7.1 / §7.6: NO args are written. Only:
+   * - ISO timestamp
+   * - session ID
+   * - tool name
+   * - fingerprint hash
+   * - outcome (ok | error)
+   * - duration in milliseconds
+   */
+  async write(event: {
+    sessionId: string;
+    agent: string | null;
+    tool: string;
+    fingerprint: string;
+    outcome: "ok" | "error";
+    durationMs: number;
+  }): Promise<void> {
+    if (!this.ensureLogDir()) return;
+
+    const logPath = path.join(this.logDir, `${event.sessionId}.log`);
+    const line = formatLine(
+      event.sessionId,
+      event.agent,
+      event.tool,
+      event.fingerprint,
+      event.outcome,
+      event.durationMs
+    );
+
+    // Check rotation threshold
+    try {
+      if (existsSync(logPath)) {
+        const stat = statSync(logPath);
+        if (stat.size + Buffer.byteLength(line, "utf8") > this.maxBytes) {
+          rotateLog(logPath, this.logger);
+        }
+      }
+    } catch {
+      // best-effort rotation check
+    }
+
+    try {
+      appendFileSync(logPath, line, "utf8");
+    } catch (err: unknown) {
+      this.logger.log({
+        level: "warn",
+        message: `bizar: failed to write to log ${logPath}: ${String(err)}`,
+      });
+    }
+  }
+}

package/src/research-prompt.ts

@@ -0,0 +1,35 @@
+/**
+ * research-prompt.ts
+ *
+ * The intervention message injected into a background session that has been
+ * stuck in a thinking loop. The LLM sees this as a new user message and
+ * should respond by spawning Mimir or taking other concrete action.
+ *
+ * Security note: the message is static — it does not interpolate any
+ * user-supplied content, prompt, or agent output. The only variable is
+ * the duration. This matches the prompt-injection invariant from
+ * handoff.ts: the only dynamic content is a short number from our own
+ * state, never from agent or user sources.
+ *
+ * The duration is formatted as `Xm Ys` (or just `Ys` if under a minute)
+ * so the agent has concrete context for how long it has been looping.
+ * We do not include the instanceId, sessionId, prompt preview, or any
+ * other potentially-sensitive content — those would only widen the
+ * attack surface without helping the LLM make progress.
+ */
+export function researchInterventionPrompt(durationMs: number): string {
+  const safeMs = Math.max(0, Math.floor(durationMs));
+  const minutes = Math.floor(safeMs / 60_000);
+  const seconds = Math.floor((safeMs % 60_000) / 1000);
+  const durationStr = minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+  return `[SYSTEM REMINDER — Thinking Loop Detected]
+
+You have been thinking for over ${durationStr} without calling any tools or producing any text output. This is a sign you are stuck in a thinking loop.
+
+To make progress, take ONE of these actions NOW:
+1. Use the task tool to spawn a Mimir agent for focused research on the original topic.
+2. Use read/grep/glob to gather concrete information from the codebase.
+3. Use bash to execute commands that produce observable results.
+
+Do NOT continue thinking without taking action. Make a tool call in your next turn.`;
+}