@polderlabs/bizar 10.1.0 → 10.2.0

package/cli/commands/headroom.mjs

@@ -0,0 +1,204 @@
+/**
+ * cli/commands/headroom.mjs
+ *
+ * Headroom context compression CLI.
+ * v3.17.0+ — status, stats, install, wrap, unwrap, start, stop, doctor.
+ */
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
+
+const HOME = homedir();
+const BIZAR_HOME = join(HOME, '.config', 'bizar');
+
+// ── Dashboard connection ────────────────────────────────────────────────────────
+
+function readDashboardConn() {
+  const portFile = join(BIZAR_HOME, 'dashboard.port');
+  const authFile = join(BIZAR_HOME, 'dashboard-secret');
+  let port = 4321;
+  let secret = '';
+  try {
+    if (existsSync(portFile)) {
+      const parsed = parseInt(readFileSync(portFile, 'utf8').trim(), 10);
+      if (Number.isFinite(parsed) && parsed > 0) port = parsed;
+    }
+  } catch { /* ignore */ }
+  try {
+    if (existsSync(authFile)) secret = readFileSync(authFile, 'utf8').trim();
+  } catch { /* ignore */ }
+  return { port, secret };
+}
+
+// ── Help ───────────────────────────────────────────────────────────────────────
+
+export function showHeadroomHelp() {
+  console.log(`
+  bizar headroom — Manage Headroom context compression
+
+  Usage:
+    bizar headroom status              Show live status (installed, proxy, wrapped)
+    bizar headroom stats              Show compression stats for the last 24h
+    bizar headroom install            Install headroom via pip or npm
+    bizar headroom wrap               Wrap cline to route through the proxy
+    bizar headroom unwrap             Unwrap cline
+    bizar headroom start              Start the proxy server
+    bizar headroom stop              Stop the proxy server
+    bizar headroom doctor            Run headroom doctor health check
+
+  Examples:
+    bizar headroom status
+    bizar headroom stats
+    bizar headroom install
+    bizar headroom wrap
+  `);
+}
+
+// ── API helpers ────────────────────────────────────────────────────────────────
+
+async function apiGet(path) {
+  const { port, secret } = readDashboardConn();
+  const baseUrl = `http://127.0.0.1:${port}`;
+  const url = `${baseUrl}${path}`;
+  const headers = { accept: 'application/json' };
+  if (secret) headers.authorization = `Basic ${Buffer.from(`cline:${secret}`).toString('base64')}`;
+  const res = await fetch(url, { method: 'GET', headers });
+  const text = await res.text();
+  let data = null;
+  try { data = text ? JSON.parse(text) : null; } catch { /* ignore */ }
+  if (!res.ok) throw new Error(`${path}: ${data?.message || data?.error || res.statusText}`);
+  return data;
+}
+
+async function apiPost(path, body = {}) {
+  const { port, secret } = readDashboardConn();
+  const baseUrl = `http://127.0.0.1:${port}`;
+  const url = `${baseUrl}${path}`;
+  const headers = { 'content-type': 'application/json', accept: 'application/json' };
+  if (secret) headers.authorization = `Basic ${Buffer.from(`cline:${secret}`).toString('base64')}`;
+  const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body) });
+  const text = await res.text();
+  let data = null;
+  try { data = text ? JSON.parse(text) : null; } catch { /* ignore */ }
+  if (!res.ok) throw new Error(`${path}: ${data?.message || data?.error || res.statusText}`);
+  return data;
+}
+
+// ── Command runner ────────────────────────────────────────────────────────────
+
+async function runHeadroomCommand(headroomArgs) {
+  const sub = headroomArgs[0];
+  const flags = headroomArgs.slice(1).filter((a) => a.startsWith('-'));
+  const positional = headroomArgs.slice(1).filter((a) => !a.startsWith('-'));
+
+  if (!sub || sub === '--help' || sub === '-h' || flags.includes('--help') || flags.includes('-h')) {
+    showHeadroomHelp();
+    return;
+  }
+
+  if (sub === 'status') {
+    const s = await apiGet('/api/headroom/status');
+    console.log('');
+    console.log(chalk.bold('  Headroom status'));
+    console.log('');
+    console.log(`    ${chalk.dim('installed:')}   ${s.installed ? chalk.green('yes') : chalk.red('no')} ${s.version || ''}`);
+    console.log(`    ${chalk.dim('proxy:')}       ${s.proxyRunning ? chalk.green('running') : chalk.yellow('stopped')} ${s.proxyPort ? `@ ${s.proxyPort}` : ''} ${s.proxyPid ? `(PID ${s.proxyPid})` : ''}`);
+    console.log(`    ${chalk.dim('wrapped:')}     ${s.wrapped ? chalk.green('yes') : chalk.yellow('no')}`);
+    console.log(`    ${chalk.dim('healthy:')}     ${s.healthy === 'ok' ? chalk.green('ok') : s.healthy === 'warn' ? chalk.yellow('warn') : chalk.red('fail')}`);
+    if (s.messages && s.messages.length > 0) {
+      console.log('');
+      for (const m of s.messages) {
+        console.log(`    ${m}`);
+      }
+    }
+    console.log('');
+    return;
+  }
+
+  if (sub === 'stats') {
+    const hours = parseInt(positional[0], 10) || 24;
+    const st = await apiGet(`/api/headroom/stats?hours=${hours}`);
+    console.log('');
+    console.log(chalk.bold(`  Headroom stats (${hours}h)`));
+    console.log('');
+    if (st.error) {
+      console.log(chalk.yellow(`    ${st.error}`));
+    } else {
+      console.log(`    ${chalk.dim('tokens saved:')}    ${(st.tokensSaved || 0).toLocaleString()}`);
+      console.log(`    ${chalk.dim('compression:')}    ${st.compressionRatio ? `${Math.round(st.compressionRatio * 100)}%` : '—'}`);
+      console.log(`    ${chalk.dim('cache hits:')}     ${st.cacheHits ?? '—'}`);
+      console.log(`    ${chalk.dim('transforms:')}     ${st.transforms ?? '—'}`);
+    }
+    console.log('');
+    return;
+  }
+
+  if (sub === 'install') {
+    const r = await apiPost('/api/headroom/install', { force: true });
+    if (r.installed) {
+      console.log(chalk.green(`  ✓ Headroom installed via ${r.method}${r.version ? ` (${r.version})` : ''}`));
+    } else {
+      console.log(chalk.red('  ✗ Install failed. Try: pip install "headroom-ai[all]"'));
+    }
+    return;
+  }
+
+  if (sub === 'wrap') {
+    const port = parseInt(positional[0], 10) || 8787;
+    const r = await apiPost('/api/headroom/wrap', { port });
+    if (r.ok) {
+      console.log(chalk.green(`  ✓ cline wrapped with Headroom on port ${port}`));
+    } else {
+      console.log(chalk.red(`  ✗ Wrap failed: ${r.log || 'unknown error'}`));
+    }
+    return;
+  }
+
+  if (sub === 'unwrap') {
+    const r = await apiPost('/api/headroom/unwrap');
+    if (r.ok) {
+      console.log(chalk.green('  ✓ cline unwrapped from Headroom'));
+    } else {
+      console.log(chalk.red('  ✗ Unwrap failed'));
+    }
+    return;
+  }
+
+  if (sub === 'start') {
+    const port = parseInt(positional[0], 10) || 8787;
+    const r = await apiPost('/api/headroom/proxy/start', { port, host: '127.0.0.1' });
+    if (r.ok) {
+      console.log(chalk.green(`  ✓ Proxy started on 127.0.0.1:${port} (PID ${r.pid})`));
+    } else {
+      console.log(chalk.red('  ✗ Proxy start failed'));
+    }
+    return;
+  }
+
+  if (sub === 'stop') {
+    const r = await apiPost('/api/headroom/proxy/stop');
+    if (r.ok) {
+      console.log(chalk.green('  ✓ Proxy stopped'));
+    } else {
+      console.log(chalk.red('  ✗ Proxy stop failed'));
+    }
+    return;
+  }
+
+  if (sub === 'doctor') {
+    // Run `headroom doctor` locally
+    const child = spawn('headroom', ['doctor'], { stdio: 'inherit' });
+    await new Promise((resolve) => child.on('close', resolve));
+    return;
+  }
+
+  console.error(chalk.red(`  ✗ Unknown headroom subcommand: ${sub}`));
+  showHeadroomHelp();
+  process.exit(1);
+}
+
+export async function run(name, args, isHelpRequest) {
+  await runHeadroomCommand(args);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar",
-  "version": "10.1.0",
+  "version": "10.2.0",
   "description": "Norse-pantheon multi-agent system for Claude Code — 14 agents across 4 cost tiers with cost-aware routing, plans, and a configurable agent harness. Ships as a single npm package with the dashboard server, Claude Code MCP server, and typed SDK.",
   "type": "module",
   "bin": {

package/packages/sdk/dist/agent/cron.d.ts

@@ -0,0 +1,44 @@
+/**
+ * src/agent/cron.ts
+ *
+ * Pillar A — Cron scheduled tasks.
+ *
+ * Exports:
+ *   addCronTask({ cron, prompt, recurring })
+ *   listCronTasks()
+ *   removeCronTask(id)
+ *
+ * Persists to `.bizar/cron.json`.
+ */
+export interface CronTask {
+    id: string;
+    cron: string;
+    prompt: string;
+    recurring: boolean;
+    createdAt: string;
+}
+/**
+ * Add a cron task.
+ *
+ * @param opts.cron       — cron expression (e.g. "0 * * * *")
+ * @param opts.prompt     — prompt to execute on trigger
+ * @param opts.recurring  — if false, task is removed after first run
+ * @param opts.repoRoot   — optional repo root override
+ * @returns the created CronTask
+ */
+export declare function addCronTask(opts: {
+    cron: string;
+    prompt: string;
+    recurring?: boolean;
+    repoRoot?: string;
+}): CronTask;
+/**
+ * List all cron tasks.
+ */
+export declare function listCronTasks(repoRoot?: string): CronTask[];
+/**
+ * Remove a cron task by id.
+ * @returns true if the task existed and was removed
+ */
+export declare function removeCronTask(id: string, repoRoot?: string): boolean;
+//# sourceMappingURL=cron.d.ts.map

package/packages/sdk/dist/agent/cron.js

@@ -0,0 +1,79 @@
+/**
+ * src/agent/cron.ts
+ *
+ * Pillar A — Cron scheduled tasks.
+ *
+ * Exports:
+ *   addCronTask({ cron, prompt, recurring })
+ *   listCronTasks()
+ *   removeCronTask(id)
+ *
+ * Persists to `.bizar/cron.json`.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+function cronStorePath(repoRoot) {
+    return join(repoRoot ?? process.cwd(), ".bizar", "cron.json");
+}
+function loadStore(repoRoot) {
+    const fp = cronStorePath(repoRoot);
+    if (!existsSync(fp))
+        return { tasks: [] };
+    try {
+        return JSON.parse(readFileSync(fp, "utf-8"));
+    }
+    catch {
+        return { tasks: [] };
+    }
+}
+function saveStore(store, repoRoot) {
+    const fp = cronStorePath(repoRoot);
+    const dir = join(fp, "..");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(fp, JSON.stringify(store, null, 2), "utf-8");
+}
+/**
+ * Add a cron task.
+ *
+ * @param opts.cron       — cron expression (e.g. "0 * * * *")
+ * @param opts.prompt     — prompt to execute on trigger
+ * @param opts.recurring  — if false, task is removed after first run
+ * @param opts.repoRoot   — optional repo root override
+ * @returns the created CronTask
+ */
+export function addCronTask(opts) {
+    const { cron, prompt, recurring = false, repoRoot } = opts;
+    const store = loadStore(repoRoot);
+    const task = {
+        id: randomUUID(),
+        cron,
+        prompt,
+        recurring,
+        createdAt: new Date().toISOString(),
+    };
+    store.tasks.push(task);
+    saveStore(store, repoRoot);
+    return task;
+}
+/**
+ * List all cron tasks.
+ */
+export function listCronTasks(repoRoot) {
+    return loadStore(repoRoot).tasks;
+}
+/**
+ * Remove a cron task by id.
+ * @returns true if the task existed and was removed
+ */
+export function removeCronTask(id, repoRoot) {
+    const store = loadStore(repoRoot);
+    const before = store.tasks.length;
+    store.tasks = store.tasks.filter((t) => t.id !== id);
+    if (store.tasks.length === before)
+        return false;
+    saveStore(store, repoRoot);
+    return true;
+}
+//# sourceMappingURL=cron.js.map

package/packages/sdk/dist/agent/heartbeat.d.ts

@@ -0,0 +1,43 @@
+/**
+ * src/agent/heartbeat.ts
+ *
+ * Pillar A — Heartbeat + session resume.
+ *
+ * Exports `startHeartbeat(intervalMs)` which returns a session ID and a
+ * JSONL writer that appends heartbeat records to
+ * `.harness/traces/heartbeat.jsonl`. Each record carries:
+ *   session_id, started_at, last_heartbeat_at, status
+ *
+ * Status transitions: running → idle → done | failed
+ */
+export type SessionStatus = "running" | "idle" | "failed" | "done";
+export interface HeartbeatRecord {
+    session_id: string;
+    started_at: string;
+    last_heartbeat_at: string;
+    status: SessionStatus;
+}
+/** Returns the path to the heartbeat log, resolved from repo root. */
+export declare function heartbeatPath(repoRoot: string): string;
+/**
+ * Start a heartbeat ticker.
+ *
+ * @param intervalMs  — milliseconds between heartbeat writes (default 30_000)
+ * @param repoRoot    — repository root (default process.cwd())
+ * @returns {{ sessionId: string, stop: () => void }}
+ */
+export declare function startHeartbeat(intervalMs?: number, repoRoot?: string): {
+    sessionId: string;
+    stop: () => void;
+};
+/**
+ * Mark a session as failed in the heartbeat log.
+ * Reads the original started_at from the JSONL file if available.
+ */
+export declare function failHeartbeat(sessionId: string, repoRoot?: string): void;
+/**
+ * Mark a session as done.
+ * Reads the original started_at from the JSONL file if available.
+ */
+export declare function stopHeartbeat(sessionId: string, repoRoot?: string): void;
+//# sourceMappingURL=heartbeat.d.ts.map

package/packages/sdk/dist/agent/heartbeat.js

@@ -0,0 +1,116 @@
+/**
+ * src/agent/heartbeat.ts
+ *
+ * Pillar A — Heartbeat + session resume.
+ *
+ * Exports `startHeartbeat(intervalMs)` which returns a session ID and a
+ * JSONL writer that appends heartbeat records to
+ * `.harness/traces/heartbeat.jsonl`. Each record carries:
+ *   session_id, started_at, last_heartbeat_at, status
+ *
+ * Status transitions: running → idle → done | failed
+ */
+import { existsSync, mkdirSync, appendFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+/** Returns the path to the heartbeat log, resolved from repo root. */
+export function heartbeatPath(repoRoot) {
+    return join(repoRoot, ".harness", "traces", "heartbeat.jsonl");
+}
+/**
+ * Start a heartbeat ticker.
+ *
+ * @param intervalMs  — milliseconds between heartbeat writes (default 30_000)
+ * @param repoRoot    — repository root (default process.cwd())
+ * @returns {{ sessionId: string, stop: () => void }}
+ */
+export function startHeartbeat(intervalMs = 30_000, repoRoot) {
+    const root = repoRoot ?? process.cwd();
+    const dir = join(root, ".harness", "traces");
+    const fp = heartbeatPath(root);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const sessionId = randomUUID();
+    const startedAt = new Date().toISOString();
+    function writeRecord(status) {
+        const record = {
+            session_id: sessionId,
+            started_at: startedAt,
+            last_heartbeat_at: new Date().toISOString(),
+            status,
+        };
+        appendFileSync(fp, JSON.stringify(record) + "\n", "utf-8");
+    }
+    writeRecord("running");
+    const interval = setInterval(() => {
+        writeRecord("running");
+    }, intervalMs);
+    return {
+        sessionId,
+        stop: () => {
+            clearInterval(interval);
+            writeRecord("done");
+        },
+    };
+}
+/**
+ * Mark a session as failed in the heartbeat log.
+ * Reads the original started_at from the JSONL file if available.
+ */
+export function failHeartbeat(sessionId, repoRoot) {
+    const root = repoRoot ?? process.cwd();
+    const fp = heartbeatPath(root);
+    if (!existsSync(fp))
+        return;
+    const startedAt = _readStartedAt(fp, sessionId);
+    const record = {
+        session_id: sessionId,
+        started_at: startedAt,
+        last_heartbeat_at: new Date().toISOString(),
+        status: "failed",
+    };
+    appendFileSync(fp, JSON.stringify(record) + "\n", "utf-8");
+}
+/**
+ * Mark a session as done.
+ * Reads the original started_at from the JSONL file if available.
+ */
+export function stopHeartbeat(sessionId, repoRoot) {
+    const root = repoRoot ?? process.cwd();
+    const fp = heartbeatPath(root);
+    if (!existsSync(fp))
+        return;
+    const startedAt = _readStartedAt(fp, sessionId);
+    const record = {
+        session_id: sessionId,
+        started_at: startedAt,
+        last_heartbeat_at: new Date().toISOString(),
+        status: "done",
+    };
+    appendFileSync(fp, JSON.stringify(record) + "\n", "utf-8");
+}
+/** Find the original started_at for a session from the JSONL file. */
+function _readStartedAt(fp, sessionId) {
+    try {
+        const raw = readFileSync(fp, "utf-8");
+        for (const line of raw.split("\n").reverse()) {
+            if (!line)
+                continue;
+            try {
+                const rec = JSON.parse(line);
+                if (rec.session_id === sessionId && rec.started_at) {
+                    return rec.started_at;
+                }
+            }
+            catch {
+                // skip malformed lines
+            }
+        }
+    }
+    catch {
+        // ignore read errors
+    }
+    return new Date().toISOString();
+}
+//# sourceMappingURL=heartbeat.js.map

package/packages/sdk/dist/index.d.ts

@@ -21,5 +21,8 @@ export { SwarmTopologyRegistry, swarmTopologyRegistry, initSwarm, getSwarm, list
 export type { SwarmRecord, SwarmTopology, InitSwarmInput, InitSwarmResult, } from "./swarm-topology.js";
 export { ByzantineConsensus, type ByzantineConsensusOpts, QueenCoordinator, type QueenCoordinatorOpts, createConsensus, getSharedConsensus, resetSharedConsensus, type ConsensusHandle, type CreateConsensusOpts, PHASE_ORDER, DEFAULT_QUORUM, DEFAULT_PEER_COUNT, DEFAULT_MAX_FAULTS, } from "./consensus/index.js";
 export type { CommitResult, ConsensusOpts, ConsensusStatus, Decision, Phase, ProposeResult, Proposal, ProposalSnapshot, ProposalStatus, Vote, VoteResult, ViewChangeResult, } from "./consensus/types.js";
+export { recordInstinct, listInstincts, promoteInstinct, dropInstinct, recordDecision, listDecisions, verifyChain, datamark, } from "./learning/index.js";
+export { startHeartbeat, stopHeartbeat, failHeartbeat, heartbeatPath, type HeartbeatRecord, type SessionStatus, } from "./agent/heartbeat.js";
+export { addCronTask, listCronTasks, removeCronTask, type CronTask, } from "./agent/cron.js";
 export { SDK_VERSION } from "./version.js";
 //# sourceMappingURL=index.d.ts.map

package/packages/sdk/dist/index.js

@@ -21,5 +21,10 @@ export { BizarAgentRegistry, bizarAgentRegistry, } from "./agent-registry.js";
 export { SwarmTopologyRegistry, swarmTopologyRegistry, initSwarm, getSwarm, listSwarms, recordAgentInSwarm, decommissionSwarm, SWARM_TOPOLOGIES, DEFAULT_TOPOLOGY, DEFAULT_MAX_AGENTS, DEFAULT_SWARM_ID, } from "./swarm-topology.js";
 // F-039 — Byzantine fault-tolerant consensus (thin PBFT port).
 export { ByzantineConsensus, QueenCoordinator, createConsensus, getSharedConsensus, resetSharedConsensus, PHASE_ORDER, DEFAULT_QUORUM, DEFAULT_PEER_COUNT, DEFAULT_MAX_FAULTS, } from "./consensus/index.js";
+// F-034 — Self-learning (Pillar D): instincts + decisions logs.
+export { recordInstinct, listInstincts, promoteInstinct, dropInstinct, recordDecision, listDecisions, verifyChain, datamark, } from "./learning/index.js";
+// Pillar A — heartbeat + cron (autonomous long-running agents)
+export { startHeartbeat, stopHeartbeat, failHeartbeat, heartbeatPath, } from "./agent/heartbeat.js";
+export { addCronTask, listCronTasks, removeCronTask, } from "./agent/cron.js";
 export { SDK_VERSION } from "./version.js";
 //# sourceMappingURL=index.js.map

package/packages/sdk/dist/learning/decisions.d.ts

@@ -0,0 +1,46 @@
+/**
+ * learning/decisions.ts — Decisions log (append-only, tamper-evident).
+ *
+ * v10.1.1 — Pillar D: Decisions log backed by `.bizar/learning/decisions.jsonl`.
+ *
+ * Each entry:
+ *   {id, ts, event: 'decide'|'supersede'|'redact',
+ *    subject, rationale, refs?, prev_hash, hash}
+ *
+ * tamper-evident chain: sha256(prev_hash + entry_body) → current hash.
+ * Datamark on render: escape unicode surrogates via JSON.stringify replacer
+ * (same pattern as gstack's wrapUntrustedContent).
+ */
+interface DecisionInput {
+    event: "decide" | "supersede" | "redact";
+    subject: string;
+    rationale: string;
+    refs?: string[];
+    project?: string;
+}
+/** Record a new decision. Returns the created entry. */
+export declare function recordDecision({ event, subject, rationale, refs, project, }: DecisionInput): Record<string, unknown>;
+/** List all decisions. */
+export declare function listDecisions(opts?: {
+    project?: string;
+}): Record<string, unknown>[];
+/**
+ * Verify the tamper-evident chain.
+ * Returns { ok: true } if every entry's hash matches the computed hash
+ * and prev_hash chains correctly. Returns { ok: false, at: number } on
+ * the first break.
+ */
+export declare function verifyChain(opts?: {
+    project?: string;
+}): {
+    ok: boolean;
+    at?: number;
+};
+/**
+ * Datamark renderer — escape unicode surrogates so JSON.stringify never
+ * emits invalid strings when rendering decisions in the UI.
+ * Pattern borrowed from gstack's wrapUntrustedContent.
+ */
+export declare function datamark(value: unknown): unknown;
+export {};
+//# sourceMappingURL=decisions.d.ts.map