@polderlabs/bizar 6.2.4 → 6.3.0

package/plugins/bizar/src/fingerprint.ts

@@ -1,120 +0,0 @@
-/**
- * fingerprint.ts
- *
- * Stable hash of (tool, args) for loop detection.
- * Uses canonical key ordering and path normalization per §5.3.
- */
-
-import { createHash } from "node:crypto";
-import path from "node:path";
-
-/**
- * Recursively sort object keys into canonical (alphabetical) order
- * and return a stable string representation.
- */
-function canonicalStringify(value: unknown): string {
-  if (value === null) return "null";
-  if (value === undefined) return "undefined";
-  if (typeof value === "boolean") return String(value);
-  if (typeof value === "number") return String(value);
-  if (typeof value === "string") return JSON.stringify(value);
-
-  if (Array.isArray(value)) {
-    return `[${value.map(canonicalStringify).join(",")}]`;
-  }
-
-  if (typeof value === "object") {
-    const sorted = Object.keys(value as Record<string, unknown>)
-      .sort()
-      .reduce<Record<string, unknown>>((acc, key) => {
-        acc[key] = (value as Record<string, unknown>)[key];
-        return acc;
-      }, {});
-
-    const pairs = Object.entries(sorted)
-      .map(([k, v]) => `${JSON.stringify(k)}:${canonicalStringify(v)}`)
-      .join(",");
-    return `{${pairs}}`;
-  }
-
-  // functions, symbols, etc. — stringify as a tag
-  return Object.prototype.toString.call(value);
-}
-
-/**
- * Normalize a value for fingerprinting:
- * - Strip noise fields (timestamps, IDs, nonces, cwd)
- * - Resolve paths: in-worktree → relative, out-of-worktree → per-path hash
- */
-/**
- * Normalize a string value that may be a path.
- * Returns worktree-relative for in-worktree paths, per-path hash for outside paths.
- */
-function normalizePath(v: string, worktree: string): string {
-  if (!path.isAbsolute(v)) return v;
-  const rel = path.relative(worktree, v);
-  if (!rel.startsWith("..") && !path.isAbsolute(rel)) {
-    return rel;
-  }
-  // outside worktree — per-path stable hash
-  const h = createHash("sha256").update(v).digest("hex");
-  return `path:${h.slice(0, 16)}`;
-}
-
-function normalize(value: unknown, worktree: string): unknown {
-  if (value === null || value === undefined) return value;
-  if (typeof value === "boolean") return value;
-  if (typeof value === "number") return value;
-  if (typeof value === "string") {
-    // Path normalization for strings that are absolute paths
-    return normalizePath(value, worktree);
-  }
-
-  if (Array.isArray(value)) {
-    return value.map((item) => normalize(item, worktree));
-  }
-
-  if (typeof value === "object") {
-    const obj = value as Record<string, unknown>;
-    const result: Record<string, unknown> = {};
-
-    // Per §5.3: strip fields whose name contains time/stamp/created/updated/timestamp
-    const SKIP_TIME_FIELDS =
-      /(^|_)time($|_)|stamp|created|updated|timestamp/i;
-
-    // Per §5.3: strip ID/nonce fields by exact name
-    const SKIP_FIELDS = /^(id|uuid|nonce|requestId|traceId)$/i;
-
-    for (const [k, v] of Object.entries(obj)) {
-      // strip cwd field entirely per §5.3
-      if (k === "cwd") continue;
-      // strip ID/nonce fields per §5.3
-      if (SKIP_FIELDS.test(k)) continue;
-      // strip timestamp fields per §5.3
-      if (SKIP_TIME_FIELDS.test(k) && (typeof v === "number" || typeof v === "string")) continue;
-
-      // normalize (includes path normalization for strings via normalizePath)
-      result[k] = normalize(v, worktree);
-    }
-
-    return result;
-  }
-
-  return value;
-}
-
-/**
- * Compute a stable fingerprint for a (tool, args) pair.
- *
- * Canonical key order is guaranteed by sorting keys before stringify.
- * Paths are normalized per §5.3: in-worktree → relative, out-of-worktree → per-path hash.
- *
- * @param tool  Tool name (e.g. "read", "bash")
- * @param args  Raw tool arguments
- * @param worktree  Absolute path to the worktree root (used for path normalization)
- */
-export function fingerprint(tool: string, args: unknown, worktree: string): string {
-  const normalized = normalize(args, worktree);
-  const stable = canonicalStringify({ tool, args: normalized });
-  return createHash("sha256").update(stable, "utf8").digest("hex");
-}

package/plugins/bizar/src/handoff.ts

@@ -1,79 +0,0 @@
-/**
- * Handoff — static message templates for the loop-guard handoff mechanism.
- *
- * Spec requirements satisfied here:
- *   - §5.4 — the three canonical messages emitted at thresholds 5, 8, and 12.
- *   - §7.2 — prompt-injection invariant. The ONLY value interpolated into any
- *     of these strings is the tool name (`<tool>`), which comes from the
- *     cline tool registry and is a short, well-known identifier (e.g.
- *     `read`, `bash`, `edit`). It is never user content, never LLM output,
- *     never an agent-controlled string. No other interpolation is permitted
- *     in this file. A PR that adds any other interpolation is rejected.
- *   - §11.1, §11.2 — the literal substrings emitted here are the contract
- *     that Odin's loop-guard recogniser and every subagent's canonical
- *     `## Loop Guard Handling` section match against. Pinning the exact text
- *     is the whole point of this module.
- *
- * The threshold numbers ("5", "8", "12") are PART OF THE STATIC TEMPLATE.
- * They are NOT interpolated from the configured threshold or the actual
- * repetition count. This is deliberate: the agent prompts in §11.2 have
- * these literal numbers in their recognition patterns, and any change here
- * would silently break the loop-guard handoff in every subagent. If a user
- * configures non-default thresholds, the messages still emit the canonical
- * text — the action simply fires at different counts than the message
- * implies. This is a known limitation; see README "Limitations" §13.
- */
-
-const WARN_TEMPLATE =
-  "[loop guard: 5 identical calls to %TOOL%]. Consider using the task tool to report back to your parent with what you've learned and what you need.";
-
-const ESCALATE_TEMPLATE =
-  "[loop guard: 8 identical calls to %TOOL%]. Consider using the task tool to report back to your parent with what you've learned and what you need.";
-
-const BLOCK_TEMPLATE =
-  "Loop protection: 12 identical calls to %TOOL%. Use task to escalate.";
-
-/**
- * Replace the `%TOOL%` placeholder in a static template with the given tool
- * name. The placeholder is intentionally not a typical `${...}` expression
- * so it cannot collide with anything inside a tool name. `%TOOL%` is the
- * ONLY substitution performed.
- */
-function interpolate(template: string, tool: string): string {
-  return template.split("%TOOL%").join(tool);
-}
-
-/**
- * Threshold-5 message: system-prompt injection via
- * `experimental.chat.system.transform`. Subagent sees this as a
- * system reminder on its next turn.
- */
-export function warnMessage(tool: string): string {
-  return interpolate(WARN_TEMPLATE, tool);
-}
-
-/**
- * Threshold-8 message: stronger system-prompt injection via
- * `experimental.chat.system.transform`. Same mechanism as `warnMessage`,
- * different template.
- */
-export function escalateMessage(tool: string): string {
-  return interpolate(ESCALATE_TEMPLATE, tool);
-}
-
-/**
- * Threshold-12 message: thrown from `tool.execute.before`. Surfaces in the
- * TUI as a tool error. The plugin's hard-block runs BEFORE cline's
- * `doom_loop` recovery (spec §3.3), so the plugin wins.
- */
-export function blockMessage(tool: string): string {
-  return interpolate(BLOCK_TEMPLATE, tool);
-}
-
-// Exported for test verification. Tests should assert the templates have not
-// drifted from the spec's canonical text.
-export const CANONICAL_TEMPLATES = {
-  warn: WARN_TEMPLATE,
-  escalate: ESCALATE_TEMPLATE,
-  block: BLOCK_TEMPLATE,
-} as const;

package/plugins/bizar/src/hooks/memory-flush-on-compact.ts

@@ -1,123 +0,0 @@
-/**
- * memory-flush-on-compact.ts — Pre-compaction memory flush hook (v6.0.0)
- *
- * Pattern: OpenClaw `flush-plan.ts:27-34` (close the durability gap
- * where compaction drops context before it's persisted to memory).
- *
- * The hook fires when `shouldCompact()` returns true. It writes any
- * pending context to the memory vault BEFORE the conversation is
- * summarized by the host.
- *
- * Trigger: `onEvent('session.usage.update', ...)` when usage ratio
- * crosses the compaction threshold. The hook is non-blocking —
- * it queues a write but doesn't await the host's summarizer.
- *
- * v6.0.0 — initial implementation. The flush writes a "pre-compact
- * snapshot" note to the vault with the recent message digest. After
- * the host's summarizer runs, the memory-write-on-end hook can
- * reference this snapshot for context continuity.
- *
- * See: research/agent-harness-survey/round-9-memory/bizar-memory-redesign.md
- *   § C.1 — Tier 1 Working Memory: pre-compaction flush
- */
-
-import { join } from "node:path";
-import { homedir } from "node:os";
-import { writeFileSync, mkdirSync } from "node:fs";
-
-import type { Logger } from "../logger.js";
-import { shouldCompact } from "../compaction.mjs";
-
-export interface MemoryFlushOnCompactDeps {
-  worktree: string;
-  logger: Logger;
-  enabled: boolean;
-  /** Override vault root for the snapshot. Default: ~/.bizar_memory. */
-  vaultRoot?: string;
-}
-
-export interface FlushOnCompactEvent {
-  sessionId: string;
-  usage: { total: number; input?: number; output?: number; cached?: number };
-  maxContext: number;
-  /** Last N messages, for the snapshot. */
-  recentMessages?: Array<{ role: string; content: string }>;
-}
-
-const SNAPSHOTS_DIR = "compaction-snapshots";
-
-function resolveVaultRoot(custom?: string): string {
-  if (custom) return custom;
-  const fromEnv = process.env.BIZAR_MEMORY_VAULT;
-  if (fromEnv) return fromEnv;
-  return join(homedir(), ".bizar_memory");
-}
-
-function timestampSlug(d = new Date()): string {
-  return d.toISOString().replace(/[:.]/g, "-");
-}
-
-export interface MemoryFlushOnCompactHook {
-  /** Check + flush if over threshold. Returns true if a snapshot was written. */
-  maybeFlush: (event: FlushOnCompactEvent) => Promise<boolean>;
-}
-
-export function createMemoryFlushOnCompact(
-  deps: MemoryFlushOnCompactDeps,
-): MemoryFlushOnCompactHook {
-  const logger = deps.logger;
-  const vaultRoot = resolveVaultRoot(deps.vaultRoot);
-  return {
-    maybeFlush: async (event) => {
-      if (!deps.enabled) return false;
-      if (!shouldCompact(event.usage, event.maxContext)) return false;
-      const ratio = event.maxContext > 0 ? event.usage.total / event.maxContext : 0;
-      const ts = timestampSlug();
-      const slug = `${ts}-${event.sessionId.slice(0, 8)}`;
-      const dir = join(vaultRoot, "projects", "BizarHarness", SNAPSHOTS_DIR);
-      const path = join(dir, `${slug}.md`);
-      try {
-        mkdirSync(dir, { recursive: true });
-        const lines: string[] = [];
-        lines.push("---");
-        lines.push("kind: pre-compact-snapshot");
-        lines.push(`session_id: ${event.sessionId}`);
-        lines.push(`timestamp: ${ts}`);
-        lines.push(`usage_total: ${event.usage.total}`);
-        lines.push(`max_context: ${event.maxContext}`);
-        lines.push(`usage_ratio: ${ratio.toFixed(3)}`);
-        lines.push("tags: [snapshot, compaction]");
-        lines.push("---");
-        lines.push("");
-        lines.push(`# Pre-compaction snapshot — ${ts}`);
-        lines.push("");
-        lines.push(`Session \`${event.sessionId}\` crossed the compaction threshold ` +
-          `(${ratio.toFixed(1)}% of ${event.maxContext} tokens). This note captures the ` +
-          `recent context so it can be retrieved after summarization.`);
-        lines.push("");
-        if (event.recentMessages && event.recentMessages.length > 0) {
-          lines.push("## Recent messages");
-          lines.push("");
-          for (const m of event.recentMessages) {
-            const content = m.content.length > 500
-              ? m.content.slice(0, 500) + "…"
-              : m.content;
-            lines.push(`### ${m.role}`);
-            lines.push("");
-            lines.push(content);
-            lines.push("");
-          }
-        }
-        writeFileSync(path, lines.join("\n"), "utf8");
-        logger.info(
-          `bizar: pre-compact snapshot written to ${path} (ratio=${ratio.toFixed(2)})`,
-        );
-        return true;
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        logger.warn(`bizar: pre-compact snapshot failed: ${msg}`);
-        return false;
-      }
-    },
-  };
-}

package/plugins/bizar/src/hooks/memory-inject.ts

@@ -1,247 +0,0 @@
-/**
- * plugins/bizar/src/hooks/memory-inject.ts
- *
- * Session-start memory injection hook.
- *
- * Fires on `session.created` event, searches the memory vault for
- * relevant context based on the user's initial message, and queues a
- * Memory Context injection into the system prompt via
- * `experimental.chat.system.transform`.
- *
- * Key design decisions:
- *   - Fires ONCE per session (idempotent via `ctx._memoryInjectedSessions`)
- *   - Uses the first user message text as the search query
- *   - Reads top 3 results and injects a "## Memory Context" section
- *   - Skips if no results found (no empty section)
- *   - Configurable via `settings.memory.injectOnSessionStart` (default true)
- *   - Non-blocking: memory search is fire-and-forget
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-
-import type { Logger } from "../logger.js";
-
-/** How many memory results to inject at most */
-const MAX_INJECT_RESULTS = 3;
-
-/**
- * Resolve the dashboard server port. Returns null if not available.
- */
-export async function resolveDashboardPort(): Promise<number | null> {
-  const portFile = join(homedir(), ".config", "bizar", "dashboard.port");
-  if (existsSync(portFile)) {
-    try {
-      const raw = readFileSync(portFile, "utf8").trim();
-      const n = parseInt(raw, 10);
-      if (Number.isFinite(n) && n > 0 && n <= 65535) return n;
-    } catch {
-      // fall through
-    }
-  }
-  const envPort = process.env.BIZAR_DASHBOARD_PORT;
-  if (envPort) {
-    const n = parseInt(envPort, 10);
-    if (Number.isFinite(n) && n > 0 && n <= 65535) return n;
-  }
-  return null;
-}
-
-/**
- * Search memory vault via the dashboard API.
- * Returns up to `limit` results.
- */
-async function searchMemory(
-  port: number,
-  query: string,
-  limit = 5,
-): Promise<Array<{ path: string | null; snippet: string; score: number }>> {
-  try {
-    // Try semantic first, then fall back to FTS
-    const baseUrl = `http://127.0.0.1:${port}`;
-
-    // Semantic search via LightRAG
-    const semRes = await fetch(`${baseUrl}/api/memory/semantic-search`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ query, limit, sources: ["lightrag", "obsidian"] }),
-    });
-
-    if (semRes.ok) {
-      const data = (await semRes.json()) as {
-        results?: Array<{
-          relPath?: string | null;
-          snippet?: string;
-          score?: number;
-        }>;
-      };
-      if (data.results && data.results.length > 0) {
-        return (data.results).map((r) => ({
-          path: r.relPath ?? null,
-          snippet: typeof r.snippet === "string" ? r.snippet.slice(0, 500) : String(r.snippet ?? ""),
-          score: typeof r.score === "number" ? r.score : 1,
-        }));
-      }
-    }
-
-    // Fall back to FTS
-    const ftsRes = await fetch(
-      `${baseUrl}/api/memory/search?q=${encodeURIComponent(query)}&limit=${limit}`,
-      { method: "GET" },
-    );
-    if (ftsRes.ok) {
-      const data = (await ftsRes.json()) as {
-        results?: Array<{ relPath?: string; snippet?: string; score?: number }>;
-      };
-      if (data.results) {
-        return data.results.map((r) => ({
-          path: r.relPath ?? null,
-          snippet: typeof r.snippet === "string" ? r.snippet.slice(0, 500) : String(r.snippet ?? ""),
-          score: typeof r.score === "number" ? r.score : 0,
-        }));
-      }
-    }
-  } catch {
-    // non-fatal: memory injection should not break session start
-  }
-  return [];
-}
-
-/**
- * Extract a search query from the first user message.
- * Uses a simple heuristic: first 50 chars + key nouns.
- */
-function buildSearchQuery(messageText: string): string {
-  // Strip /commands, whitespace, quotes
-  const cleaned = messageText.replace(/^[\/\s"\']+/, "").trim();
-  // Take first meaningful chunk (up to 80 chars)
-  const core = cleaned.slice(0, 80).split(/[.\n!?]/)[0] ?? cleaned;
-  return core || cleaned.slice(0, 50);
-}
-
-/**
- * Format a memory result as a markdown section for injection.
- */
-function formatMemoryContext(
-  results: Array<{ path: string | null; snippet: string; score: number }>,
-): string {
-  const lines = ["## Memory Context\n"];
-  lines.push(
-    `_Automatically injected from the Bizar Memory vault. ${results.length} relevant note(s) found._\n`,
-  );
-  for (const r of results.slice(0, MAX_INJECT_RESULTS)) {
-    if (r.path) {
-      lines.push(`### ${r.path}`);
-    } else {
-      lines.push("### (semantic match)");
-    }
-    lines.push(`_${r.score > 0 ? `score: ${r.score.toFixed(2)}` : "full-text match"}_\n`);
-    lines.push(r.snippet);
-    lines.push("\n---\n");
-  }
-  return lines.join("\n");
-}
-
-export interface MemoryInjectDeps {
-  /** Set of sessionIds that have already been injected (cleared on session.deleted). */
-  injectedSessions: Set<string>;
-  worktree: string;
-  logger: Logger;
-  /** If false, skip injection entirely (configurable via settings). */
-  enabled: boolean;
-}
-
-/**
- * Build the session-start memory injection logic.
- * Call this from the `event` hook for `session.created` events.
- *
- * Usage in index.ts `event` hook:
- *   const memoryInjectDeps = { injectedSessions, worktree, logger, enabled: true };
- *   const { memoryInject } = createMemoryInject(memoryInjectDeps);
- *   // in event handler:
- *   if (type === "session.created") {
- *     memoryInject(sessionID, userMessageText).catch(() => {});
- *   }
- *
- * The `injectedSessions` Set is also checked/cleared in `session.deleted`.
- */
-export function createMemoryInject(deps: MemoryInjectDeps) {
-  const { injectedSessions, logger } = deps;
-
-  /**
-   * Fire memory search and queue the result for injection.
-   * Safe to await or fire-and-forget — errors are swallowed.
-   */
-  async function memoryInject(
-    sessionID: string,
-    userMessageText: string,
-    signal?: AbortSignal,
-  ): Promise<void> {
-    if (!deps.enabled) return;
-    if (injectedSessions.has(sessionID)) return;
-
-    // Mark injected BEFORE the async work so we don't double-fire
-    // even if the request races.
-    injectedSessions.add(sessionID);
-
-    try {
-      const port = await resolveDashboardPort();
-      if (!port) return;
-
-      const query = buildSearchQuery(userMessageText);
-      if (!query) return;
-
-      const results = await searchMemory(port, query, 5);
-      if (results.length === 0) return;
-
-      const context = formatMemoryContext(results);
-
-      // We can't directly push to output.system here (we're in the `event` hook).
-      // Instead, we use the `pendingInjections` map in the RuntimeContext
-      // (same mechanism used for loop guard injections).
-      // The `experimental.chat.system.transform` hook already checks this map.
-      // We store it under a special marker so the transform hook can distinguish it.
-      // But wait — pendingInjections only holds ONE message at a time.
-      // We need a separate mechanism... Actually, looking at the transform hook:
-      //   const pending = ctx.pendingInjections.get(sessionID);
-      //   if (pending) { output.system.push(pending); ctx.pendingInjections.delete(sessionID); }
-      // This only allows ONE injection at a time.
-      //
-      // Alternative: use a separate Map for memory injections.
-      // The transform hook checks ctx._memoryInjections.get(sessionID) separately.
-      //
-      // Since we control both the injection (here) and the hook (in index.ts),
-      // we can add a second map. Let's use ctx._memoryPendingInjections.
-
-      // Signal that we have memory to inject by setting a flag.
-      // The actual injection happens in experimental.chat.system.transform.
-      // We use a module-level store that the transform hook reads.
-      _pendingMemoryContext.set(sessionID, context);
-    } catch (err) {
-      // Non-fatal: don't let a failed memory injection break session start.
-      logger.debug(
-        `bizar: memory-inject failed for session ${sessionID}: ${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
-  }
-
-  return { memoryInject };
-}
-
-/**
- * Module-level store for pending memory context injections.
- * The `experimental.chat.system.transform` hook reads this and injects
- * the queued context into the system prompt.
- */
-export const _pendingMemoryContext = new Map<string, string>();
-
-/**
- * Retrieve and clear any pending memory context for a session.
- * Called from `experimental.chat.system.transform`.
- */
-export function popMemoryContext(sessionID: string): string | null {
-  const ctx = _pendingMemoryContext.get(sessionID);
-  _pendingMemoryContext.delete(sessionID);
-  return ctx ?? null;
-}