@polderlabs/bizar 4.4.13 → 4.5.1

package/cli/bin.mjs

@@ -91,6 +91,7 @@ function showHelp() {
     service             Manage the background service daemon
     bg <subcommand>     Manage background agents (list/view/kill/logs)
     memory <subcommand> Manage project memory (Bizar Memory Service)
+    headroom <subcommand> Manage Headroom context compression
     dash <subcommand>   Manage the dashboard (start/stop/status/cleanup/tui)
     browser-harness-up  Start Chromium for browser-harness (start/stop/status/restart)
     dev-link [src]      Symlink the local plugin source into opencode's plugin dir
@@ -98,6 +99,7 @@ function showHelp() {
     doctor              Check the BizarHarness install for health issues
     heads-up <subcommand>  Manage pre-push / pre-release heads-ups (list/check/archive)
     minimax <subcommand>   Manage MiniMax Token Plan integration (key + onboarding)
+    usage                 Show compact usage analytics summary (24h rolling)
     mod <subcommand>       Manage mods (install/upgrade/list via the dashboard API)
 
   Examples:
@@ -196,6 +198,8 @@ function showUpdateHelp() {
 
   Usage:
     bizar update                       Update EVERYTHING (default; auto-kills + restarts)
+    bizar update --check               Only print current vs. latest; do not update
+    bizar update --channel=stable|beta Pick the npm dist-tag (default: stable)
     bizar update --no-restart          Don't auto-restart the dashboard after update
     bizar update --dry-run             Print what would happen, change nothing
     bizar update --force               Override .bizar/PRE_PUSH_NOTES.md blockers
@@ -223,12 +227,20 @@ function showUpdateHelp() {
       --no-restart).
     • Runs 'bizar doctor' after a successful update to catch config
       regressions before opencode tries to start.
+    • With --check: prints the version matrix and release-notes excerpt
+      between current and latest, exits non-zero if an update is available.
 
   Examples:
     bizar update                       Full auto-update (recommended)
+    bizar update --check               Show version matrix + notes, do nothing
+    bizar update --channel=beta        Upgrade to latest beta build
     bizar update --dry-run             Preview what would change
-    bizar update --pick                Pick specific components
     bizar update plugin --no-restart   Plugin-only, leave dashboard alone
+
+  Errors:
+    Network failures (registry offline / DNS) and npm permission issues
+    are surfaced with the raw npm output. The provisioner never silently
+    swallows them — look for the ✗ marker in the step output.
   `);
 }
 
@@ -731,6 +743,235 @@ async function runMinimaxCommand(minimaxArgs) {
   process.exit(1);
 }
 
+// ── Usage subcommand ───────────────────────────────────────────────────────
+
+function showUsageHelp() {
+  console.log(`
+  bizar usage — Show compact usage analytics summary
+
+  Usage:
+    bizar usage [24h|7d|30d]   Show summary for the given range (default: 24h)
+
+  Examples:
+    bizar usage
+    bizar usage 7d
+    bizar usage 30d
+  `);
+}
+
+async function runUsageCommand(args) {
+  const range = (args[0] && ['24h', '7d', '30d'].includes(args[0])) ? args[0] : '24h';
+  const { port, secret } = readDashboardConn();
+  const url = `http://127.0.0.1:${port}/api/usage?range=${range}`;
+  const headers = { accept: 'application/json' };
+  if (secret) headers.authorization = `Basic ${Buffer.from(`opencode:${secret}`).toString('base64')}`;
+  try {
+    const resp = await fetch(url, { method: 'GET', headers });
+    const text = await resp.text();
+    let data = null;
+    try { data = text ? JSON.parse(text) : null; } catch { /* ignore */ }
+    if (!resp.ok || !data) {
+      console.error(chalk.red(`  ✗ Failed to load usage data: ${data?.message ?? resp.statusText}`));
+      process.exit(1);
+    }
+    const t = data.totals;
+    console.log('');
+    console.log(chalk.bold(`  Usage summary — ${range} (from JSONL store)`));
+    console.log('');
+    console.log(`    ${chalk.dim('Requests:')}   ${t.requests.toLocaleString()}  (${t.errors} errors)`);
+    console.log(`    ${chalk.dim('Tokens:')}     ${t.totalTokens.toLocaleString()} total  (${t.promptTokens.toLocaleString()} prompt · ${t.completionTokens.toLocaleString()} completion)`);
+    console.log(`    ${chalk.dim('Cached:')}     ${t.cachedTokens.toLocaleString()} tokens`);
+    console.log(`    ${chalk.dim('Reasoning:')}  ${t.reasoningTokens.toLocaleString()} tokens`);
+    console.log(`    ${chalk.dim('Avg latency:')} ${t.avgLatencyMs}ms  (p95: ${t.p95LatencyMs}ms)`);
+    if (t.costEstimate > 0) {
+      console.log(`    ${chalk.dim('Est. cost:')}   $${t.costEstimate.toFixed(4)} USD`);
+    }
+    console.log('');
+    if (data.daily && data.daily.length > 0) {
+      console.log(chalk.dim(`  ${chalk.bold('Daily breakdown')}`));
+      for (const day of data.daily.slice(-7)) {
+        const barLen = Math.round((day.totalTokens / Math.max(...data.daily.map(d => d.totalTokens))) * 20);
+        const bar = '█'.repeat(barLen) + '░'.repeat(20 - barLen);
+        console.log(`    ${day.date}  ${bar}  ${day.totalTokens.toLocaleString()} tok  ${day.requests} req`);
+      }
+    }
+    if (data.perModel && data.perModel.length > 0) {
+      console.log('');
+      console.log(chalk.dim(`  ${chalk.bold('Per model')}`));
+      for (const m of data.perModel.slice(0, 8)) {
+        console.log(`    ${m.modelId.padEnd(24)} ${String(m.requests).padStart(6)} req  ${String(m.totalTokens).padStart(8)} tok`);
+      }
+    }
+    console.log('');
+  } catch (err) {
+    console.error(chalk.red(`  ✗ Network error: ${err && err.message ? err.message : String(err)}`));
+    console.error(chalk.dim('    Is the dashboard running? Run `bizar dash start` first.'));
+    process.exit(1);
+  }
+}
+
+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 opencode to route through the proxy
+    bizar headroom unwrap             Unwrap opencode
+    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
+  `);
+}
+
+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;
+  }
+
+  // Delegate to dashboard API
+  const { port, secret } = readDashboardConn();
+  const baseUrl = `http://127.0.0.1:${port}`;
+
+  async function apiGet(path) {
+    const url = `${baseUrl}${path}`;
+    const headers = { accept: 'application/json' };
+    if (secret) headers.authorization = `Basic ${Buffer.from(`opencode:${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 url = `${baseUrl}${path}`;
+    const headers = { 'content-type': 'application/json', accept: 'application/json' };
+    if (secret) headers.authorization = `Basic ${Buffer.from(`opencode:${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;
+  }
+
+  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(`  ✓ opencode 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('  ✓ opencode 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 { spawn } = await import('node:child_process');
+    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);
+}
+
 function showDashHelp() {
   console.log(`
   bizar dash — Manage the Bizar dashboard
@@ -942,6 +1183,8 @@ async function main() {
       const { runMemory } = await import('./memory.mjs');
       await runMemory(args[1], args.slice(2));
     }
+  } else if (args[0] === 'headroom') {
+    await runHeadroomCommand(args.slice(1));
   } else if (args[0] === 'export') {
     if (isHelpRequest) showExportHelp();
     else await runExport(parseFlag('--target'));
@@ -1083,6 +1326,9 @@ async function main() {
     // test, config, clear, reset-onboarding. All commands shell out
     // to the dashboard's /api/minimax/* routes.
     await runMinimaxCommand(args.slice(1));
+  } else if (args[0] === 'usage') {
+    // v4.6.0 — Compact usage analytics summary from the JSONL store.
+    await runUsageCommand(args.slice(1));
   } else if (args[0] === 'dash' || args[0] === 'dashboard') {
     // `bizar dashboard` is a deprecated alias for `bizar dash`
     if (args[0] === 'dashboard') {

package/cli/provision.mjs

@@ -1121,17 +1121,131 @@ export async function runProvision(opts = {}) {
  * `cli/update.mjs` (the bin.mjs-facing module) can stay a thin shim
  * without duplicating flag parsing. Accepts the legacy `subargs: string[]`
  * shape so any external callers keep working.
+ *
+ * Recognized flags (v4.4.14):
+ *   --check           Only print current vs. latest, don't update.
+ *   --channel <name>  npm dist-tag (stable | beta). Default: stable.
+ *   --no-restart      Don't auto-restart the dashboard after update.
+ *   --dry-run         Print what would happen, change nothing.
+ *   --force           Override .bizar/PRE_PUSH_NOTES.md blockers.
+ *   --yes / -y        Same as --force, but named for one-line scripts.
+ *   --with-mods <csv> Opt-in: install specific mods as part of the run.
+ *
+ * With --check, we print the version matrix and release notes between
+ * current and latest, then return without touching the system.
  */
 export async function runUpdate(subargs = []) {
+  const args = Array.isArray(subargs) ? subargs : [];
+  const checkOnly = args.includes('--check');
+
+  // --channel <name> — extract a single value. Accepts both
+  //   --channel=beta     (equals form)
+  //   --channel beta     (separate-arg form)
+  // Default: 'stable'.
+  let channel = 'stable';
+  const eqArg = args.find((a) => a.startsWith('--channel='));
+  if (eqArg) {
+    const value = eqArg.slice('--channel='.length);
+    if (value === 'stable' || value === 'beta') {
+      channel = value;
+    } else {
+      console.log(chalk.yellow(`  ⚠ Unknown channel "${value}". Using "stable".`));
+    }
+  } else {
+    const channelIdx = args.indexOf('--channel');
+    if (channelIdx >= 0) {
+      const value = args[channelIdx + 1];
+      if (!value || value.startsWith('--')) {
+        console.log(chalk.yellow('  ⚠ --channel needs a value (stable | beta). Using "stable".'));
+      } else if (value !== 'stable' && value !== 'beta') {
+        console.log(chalk.yellow(`  ⚠ Unknown channel "${value}". Using "stable".`));
+      } else {
+        channel = value;
+      }
+    }
+  }
+
+  if (checkOnly) {
+    return runCheck(channel);
+  }
+
+  // Pass channel through to the provisioner. The provisioner does the
+  // actual npm install; channel maps to the npm dist-tag suffix.
   return runProvision({
     mode: 'update',
-    dryRun: subargs.includes('--dry-run'),
-    force: subargs.includes('--force'),
-    yes: subargs.includes('--yes') || subargs.includes('-y'),
-    restart: !subargs.includes('--no-restart'),
+    dryRun: args.includes('--dry-run'),
+    force: args.includes('--force'),
+    yes: args.includes('--yes') || args.includes('-y'),
+    restart: !args.includes('--no-restart'),
+    channel,
   });
 }
 
+/**
+ * v4.4.14 — `bizar update --check`. Print the version matrix and (if
+ * a newer version exists) the release notes between current and latest.
+ * Does NOT touch the system. Exits non-zero when an update is available
+ * so callers can use it in CI / pre-flight scripts.
+ */
+export async function runCheck(channel = 'stable') {
+  console.log(chalk.bold.hex('#a855f7')('\n  ᚦ BIZAR UPDATE — CHECK ᚦ\n'));
+  console.log(chalk.dim(`  Channel: ${channel}\n`));
+
+  const state = detectState();
+  printVersionMatrix([
+    { label: 'opencode-ai', current: state.opencodeCli.version, latest: state.opencodeCli.latest },
+    { label: PKG_MAIN, current: state.pkgVersion, latest: state.pkgLatest },
+  ]);
+
+  const cur = state.pkgVersion;
+  const lat = state.pkgLatest;
+  if (cur && lat && cur !== lat) {
+    console.log(chalk.dim(`\n  Release notes (${cur} → ${lat}):`));
+    const notes = fetchReleaseNotes(PKG_MAIN, cur, lat).catch((err) => {
+      console.log(chalk.dim(`    (could not fetch: ${err.message || err})`));
+      return null;
+    });
+    const text = await notes;
+    if (text) {
+      // Trim to a sensible cap (first 30 lines) so the console stays
+      // readable; the full notes are one `npm view` call away.
+      const lines = text.split(/\r?\n/).slice(0, 30);
+      for (const line of lines) console.log(`    ${line}`);
+      if (lines.length === 30) console.log(chalk.dim('    ... (truncated; run `npm view @polderlabs/bizar` for full)'));
+    }
+    console.log(chalk.yellow(`\n  ⤵ Run \`bizar update\` to apply.\n`));
+    // Non-zero exit so scripts can detect the update-available case.
+    return { ok: true, updateAvailable: true, channel };
+  }
+
+  console.log(chalk.green('\n  ✓ Already on the latest version.\n'));
+  return { ok: true, updateAvailable: false, channel };
+}
+
+/**
+ * Fetch the release notes between two versions from the npm registry.
+ * Returns a plain-text summary (the registry's "description" field for
+ * the latest version), or null on any failure. Never throws — failures
+ * are surfaced to the caller as null so the check command stays useful
+ * offline.
+ */
+async function fetchReleaseNotes(pkg, _from, _to) {
+  // The npm registry does not expose a structured per-version release-
+  // notes field. The best we can do is `npm view <pkg> description`
+  // which is the package's README excerpt. We surface that as "notes".
+  try {
+    const { execFileSync } = await import('node:child_process');
+    const out = execFileSync('npm', ['view', pkg, 'description'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 10000,
+      encoding: 'utf8',
+    }).toString().trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * CLI-flag-parsing entrypoint for `bizar install`. Mirrors `runUpdate`
  * so `cli/install.mjs` can stay a thin shim too.

package/config/agents/_shared/SKILLS.md

@@ -0,0 +1,109 @@
+# Bizar Skills - Reference
+
+Skills are specialized instruction sets that agents load before working on specific domains. They live as `SKILL.md` files in well-known directories and are injected into agent context when relevant.
+
+## What Skills Are
+
+A skill is a Markdown file with YAML frontmatter. The frontmatter declares a `description` that the agent matcher uses to decide when to load the skill. The body contains domain-specific knowledge, patterns, gotchas, and code examples.
+
+Example `SKILL.md`:
+
+```yaml
+---
+name: my-skill
+description: Use when working with X. Covers Y and Z.
+---
+# My Skill
+
+## When to use
+...
+
+## Key concepts
+...
+
+## Code examples
+...
+
+## Common gotchas
+...
+```
+
+## Where Skills Live
+
+| Path | Source | Priority | Notes |
+|---|---|---|---|
+| `~/.opencode/skills/<name>/SKILL.md` | User / System | Highest | User-overridable builtins |
+| `~/.agents/skills/<name>/SKILL.md` | User-added | High | Installed via `skills add` |
+| `bizar-dash/skills/<name>/SKILL.md` | Shipped | Medium | Ships with BizarHarness package |
+| `.agents/skills/<name>/SKILL.md` | Project | Low | Project-local skills |
+| `.opencode/skills/<name>/SKILL.md` | Project | Lowest | Project-local skills |
+
+When the same skill name appears in multiple places, the highest-priority source wins.
+
+## Discovering Skills
+
+Use the `skills` CLI:
+
+```bash
+# List installed skills
+skills list --json
+
+# Search for a skill
+skills search "react"
+
+# Install from a repository
+skills add owner/repo -s "skill-name" -y
+```
+
+Known repositories:
+- `vercel-labs/skills` - find-skills, skill-creator, general tools
+- `vercel-labs/agent-skills` - React, Next.js, frontend performance
+- `shadcn/ui` - shadcn/ui components
+- `supabase/agent-skills` - Postgres, Auth, Edge Functions
+- `mattpocock/skills` - TypeScript, TDD
+- `anthropics/skills` - Claude patterns, agents
+- `leonxlnx/taste-skill` - design, UI/UX
+
+## Shipped Bizar Skills
+
+These skills ship with BizarHarness and are available immediately:
+
+| Skill | Description |
+|---|---|
+| `bizar` | Norse-pantheon multi-agent system, Odin routing, agent tiers |
+| `agent-baseline` | Always-on rules: Semble, Skills CLI, loop guard, copyright |
+| `self-improvement` | .bizar/AGENTS_SELF_IMPROVEMENT.md protocol |
+| `obsidian` | Bizar Memory Service (Obsidian + Git + LightRAG) |
+| `minimax` | MiniMax provider, multi-key rotation, usage tracking |
+| `providers` | Provider subsystem, backup keys, auto-add wizard |
+| `chat` | Chat + opencode session integration |
+| `usage` | Token usage monitoring, cost estimation, MiniMax usage dashboard |
+| `skills-cli` | skills CLI reference, skill repos, discovery protocol |
+| `lightrag` | LightRAG integration, opencode-free defaults, indexing |
+| `sdk` | @polderlabs/bizar-sdk on Cloudflare Workers |
+
+## Skill Loading
+
+Agents check skill relevance at dispatch time. You can also load a skill explicitly in conversation using the `skill` tool:
+
+```
+Load the `minimax` skill before we discuss multi-key rotation.
+```
+
+## Adding a Project Skill
+
+Create a skill directory in your project:
+
+```bash
+mkdir -p .agents/skills/my-project-skill
+cat > .agents/skills/my-project-skill/SKILL.md << 'EOF'
+---
+name: my-project-skill
+description: Use when working on my project's specific domain X.
+---
+# My Project Skill
+...
+EOF
+```
+
+Project skills are picked up automatically on next session start.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar",
-  "version": "4.4.13",
+  "version": "4.5.1",
   "description": "Norse-pantheon multi-agent system for opencode — 13 agents across 4 cost tiers with cost-aware routing, plans, and a configurable agent harness. v4 ships as a single npm package bundling the dashboard server, opencode plugin, and typed SDK.",
   "type": "module",
   "bin": {