@occasiolabs/occasio 0.8.3 → 0.8.4

package/src/cli/clear.js

@@ -0,0 +1,55 @@
+// `occasio clear` — reset session + today's log.
+// `occasio clear --history` — wipe ALL historical logs + blocked-secret records.
+//
+// Destructive but bounded to ~/.occasio/. session.json is unconditionally
+// removed; logs are removed file-by-file (no rmdir) so an exotic
+// permission error on one file does not abort the rest.
+
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+
+const LOG_DIR      = path.join(os.homedir(), '.occasio');
+const SESSION_FILE = path.join(LOG_DIR, 'session.json');
+
+const col = {
+  g: s => `\x1b[32m${s}\x1b[0m`,
+  d: s => `\x1b[2m${s}\x1b[0m`,
+};
+
+function todayStr() {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth()+1).padStart(2,'0')}-${String(d.getDate()).padStart(2,'0')}`;
+}
+function getLogFile() { return path.join(LOG_DIR, 'logs', `${todayStr()}.jsonl`); }
+
+function ensureDirs() {
+  for (const sub of ['', 'logs', 'reports', 'blocked', 'distilled']) {
+    const d = path.join(LOG_DIR, sub);
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+  }
+}
+
+function run(args) {
+  ensureDirs();
+  const clearAll = (args || []).includes('--history');
+  if (clearAll) {
+    const logsDir = path.join(LOG_DIR, 'logs');
+    const blockedDir = path.join(LOG_DIR, 'blocked');
+    let n = 0;
+    for (const dir of [logsDir, blockedDir]) {
+      try { for (const f of fs.readdirSync(dir)) { fs.unlinkSync(path.join(dir, f)); n++; } } catch {}
+    }
+    try { fs.unlinkSync(SESSION_FILE); } catch {}
+    console.log(col.g(`✓ Cleared all history (${n} log files) and session data`));
+  } else {
+    try { fs.unlinkSync(getLogFile()); } catch {}
+    try { fs.unlinkSync(SESSION_FILE); } catch {}
+    console.log(col.g("✓ Cleared today's log and session data"));
+    console.log(col.d('  Use --history to wipe all historical logs'));
+  }
+}
+
+module.exports = { run };

package/src/cli/help.js

@@ -0,0 +1,81 @@
+// `occasio help` — top-level usage. Pure text; no side effects other
+// than console.log. Each CLI command lives in its own file under
+// src/cli/ as part of the index.js decomposition (see CHANGELOG).
+
+'use strict';
+
+const VERSION = (() => {
+  try { return require('../../package.json').version; }
+  catch { return '0.0.0-unknown'; }
+})();
+
+const col = {
+  r: s => `\x1b[31m${s}\x1b[0m`, g: s => `\x1b[32m${s}\x1b[0m`,
+  y: s => `\x1b[33m${s}\x1b[0m`, c: s => `\x1b[36m${s}\x1b[0m`,
+  d: s => `\x1b[2m${s}\x1b[0m`,  b: s => `\x1b[1m${s}\x1b[0m`,
+};
+
+function run() {
+  console.log(`
+${col.b(`⚡ Occasio v${VERSION}`)}
+
+${col.b('Usage:')}
+  occasio claude [args...]   Start Claude with local proxy (intercept + log)
+  occasio demo               10-second proof: see Occasio block real secrets
+  occasio demo attest        End-to-end attestation pipeline against a synthetic audit chain
+  occasio demo anomalies     End-to-end EDR test: synthetic adversarial chain → all 4 detectors
+  occasio dashboard          Open live dashboard for the running session
+  occasio register           Register shell alias (type 'claude' directly)
+  occasio status             Show session stats and savings breakdown
+  occasio doctor             Check setup: Node, claude CLI, port, Python, profile
+  occasio clear              Reset today's log and session data
+  occasio clear --history    Wipe all historical logs
+  occasio ledger             Inspect token ledger (--last N, --summary, --scope session|today)
+  occasio replay             Replay run audit (--last N, --detail, --run <id>, --attribute)
+  occasio distill            Inspect distilled outputs (--last N, --entry <N> for raw)
+  occasio inspect            Cloud-boundary manifest (--last N, --entry N, --run <id>)
+  occasio boundary           Per-request three-column view: produced / re-entered / prevented
+  occasio baseline           Behavior baseline: [learn|show|compare|reset] (per project cwd)
+  occasio harness            Run a real Claude Code session against scratch fixtures and verify governance claims (needs ANTHROPIC_API_KEY)
+  occasio redteam            Autonomous adversarial test — tester LLM probes a subject Claude Code session under Occasio (needs ANTHROPIC_API_KEY + @anthropic-ai/sdk)
+  occasio policy [show]      Show active policy: flags, tool routing, overrides
+  occasio policy show --diff Only values that differ from defaults
+  occasio policy validate    Validate policy.yml and report errors/warnings
+  occasio policy init        Create a starter policy.yml (safe, non-destructive)
+                                Use --template strict|finance for a non-default starter
+  occasio policy doctor      Cross-reference session logs with policy; surface suggestions
+  occasio audit [verify]     Verify tamper-evident hash chain in pipeline-events.jsonl
+  occasio audit repair       Truncate a crash-partial trailing line (--file <path> [--dry-run])
+  occasio report             Governance export: file access log, blocked paths, secret events
+  occasio anomalies          Live anomaly detection over the audit chain (--window 15m, --json)
+  occasio computer-use       Apply a Computer-Use policy to a JSONL of tool_use blocks (--dry-run --example)
+  occasio attest --run-id <uuid>  AI-Agent Behavioral Attestation v1: hash-chain commitment + execution summary for one run
+                              Add --sign in GitHub Actions (with permissions: id-token: write) for Sigstore keyless signing
+  occasio attest verify <file>   Re-verify a signed attestation: Sigstore bundle + DSSE payload match + audit chain integrity
+  occasio selftest           Run governance self-checks on a scratch chain (does not touch your audit log)
+  occasio report --format csv  CSV export for auditors / SIEM import
+  occasio mcp-experiment     MCP vs. built-in tool adoption stats (experiment)
+
+${col.b('Presets:')}
+  --preset balanced  (default)  Intercept safe reads locally, log all requests
+  --preset strict               Block requests that contain detected secrets
+  --preset off                  Log only — no interception, no blocking
+
+${col.b('Flags:')}
+  --budget <N>                  Block requests once session cost exceeds $N (e.g. --budget 1.00)
+  --hardened                    Route Read/Glob/Grep through unified runtime (distill + secret scan)
+  --block-secrets               Alias for --preset strict
+  --log-only                    Alias for --preset off
+  --dashboard                   Open live dashboard at http://localhost:3001
+  --port <N>                    Proxy port (default: 8081)
+  --verbose                     Print live per-request chatter (off by default — quiet for Claude Code's TUI)
+
+${col.b('Multi-agent routing:')}
+  Default               → Claude Code adapter
+  Header x-occasio-agent: cline → Cline adapter (synthetic; live validation pending)
+
+${col.b('Logs:')} ~/.occasio/logs/YYYY-MM-DD.jsonl
+`);
+}
+
+module.exports = { run };

package/src/cli/register.js

@@ -0,0 +1,90 @@
+// `occasio register` — installs a `claude()` shell function so the user
+// can keep typing `claude` and silently get routed through the proxy.
+//
+// Idempotent: detects the canonical marker and exits; auto-upgrades the
+// legacy `--intercept` snippet to `claude` if found. Best-effort on
+// failure — prints a manual instruction rather than crashing.
+
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+
+const col = {
+  r: s => `\x1b[31m${s}\x1b[0m`, g: s => `\x1b[32m${s}\x1b[0m`,
+  y: s => `\x1b[33m${s}\x1b[0m`, d: s => `\x1b[2m${s}\x1b[0m`,
+};
+
+function registerWindows() {
+  const profileDir  = path.join(os.homedir(), 'Documents', 'PowerShell');
+  const profileFile = path.join(profileDir, 'Microsoft.PowerShell_profile.ps1');
+  const snippet = `\n# Occasio — intercept Claude Code traffic\nfunction claude { occasio claude @args }\n`;
+  const alreadyMarker = 'occasio claude @args';
+  const legacyMarker  = 'occasio --intercept @args';
+  try {
+    if (!fs.existsSync(profileDir)) fs.mkdirSync(profileDir, { recursive: true });
+    const existing = fs.existsSync(profileFile) ? fs.readFileSync(profileFile, 'utf8') : '';
+    if (existing.includes(alreadyMarker)) {
+      console.log(col.g('✓ Already registered (PowerShell)'));
+      console.log(col.d('  Type: claude'));
+    } else if (existing.includes(legacyMarker)) {
+      const updated = existing.replace(
+        /function claude \{ occasio --intercept @args \}/g,
+        'function claude { occasio claude @args }'
+      );
+      fs.writeFileSync(profileFile, updated);
+      console.log(col.g('✓ Updated to canonical form (occasio claude)'));
+      console.log('');
+      console.log(col.y(`  ⚠  Restart PowerShell — the 'claude' alias is not active yet.`));
+      console.log(col.d(`     Open a new terminal, or run:  . $PROFILE`));
+      console.log('');
+    } else {
+      fs.appendFileSync(profileFile, snippet);
+      console.log(col.g(`✓ Registered in ${profileFile}`));
+      console.log('');
+      console.log(col.y(`  ⚠  Restart PowerShell — the 'claude' alias is not active yet.`));
+      console.log(col.d(`     Open a new terminal, or run:  . $PROFILE`));
+      console.log('');
+    }
+  } catch (e) {
+    console.log(col.r(`✗ Could not write profile: ${e.message}`));
+    console.log(col.d(`  Add manually to your PowerShell profile:\n  function claude { occasio claude @args }`));
+  }
+}
+
+function registerPosix() {
+  const rcFile = (process.env.SHELL || '').includes('zsh')
+    ? path.join(os.homedir(), '.zshrc')
+    : path.join(os.homedir(), '.bashrc');
+  const snippet = `\n# Occasio — intercept Claude Code traffic\nclaude() { occasio claude "$@"; }\n`;
+  const alreadyMarker = 'occasio claude "$@"';
+  const legacyMarker  = 'occasio --intercept "$@"';
+  try {
+    const existing = fs.existsSync(rcFile) ? fs.readFileSync(rcFile, 'utf8') : '';
+    if (existing.includes(alreadyMarker)) {
+      console.log(col.g(`✓ Already registered (${rcFile})`));
+    } else if (existing.includes(legacyMarker)) {
+      const updated = existing.replace(
+        /claude\(\) \{ occasio --intercept "\$@"; \}/g,
+        'claude() { occasio claude "$@"; }'
+      );
+      fs.writeFileSync(rcFile, updated);
+      console.log(col.g(`✓ Updated to canonical form in ${rcFile}`));
+    } else {
+      fs.appendFileSync(rcFile, snippet);
+      console.log(col.g(`✓ Registered in ${rcFile}`));
+    }
+    console.log(col.d('  Run: source ' + rcFile + '  — then type: claude'));
+  } catch (e) {
+    console.log(col.r(`✗ Could not write ${rcFile}: ${e.message}`));
+    console.log(col.d(`  Add manually:\n  claude() { occasio claude "$@"; }`));
+  }
+}
+
+function run() {
+  if (process.platform === 'win32') registerWindows();
+  else registerPosix();
+}
+
+module.exports = { run };

package/src/cli/status.js

@@ -0,0 +1,94 @@
+// `occasio status` — session summary (cost, savings, coverage, budget).
+// Read-only against ~/.occasio/session.json + today's JSONL log.
+
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+
+const { calcCompoundingSavings } = require('../cost/prices');
+const { fmtBudget }              = require('../budget');
+
+const LOG_DIR      = path.join(os.homedir(), '.occasio');
+const SESSION_FILE = path.join(LOG_DIR, 'session.json');
+
+const col = {
+  r: s => `\x1b[31m${s}\x1b[0m`, g: s => `\x1b[32m${s}\x1b[0m`,
+  y: s => `\x1b[33m${s}\x1b[0m`, c: s => `\x1b[36m${s}\x1b[0m`,
+  d: s => `\x1b[2m${s}\x1b[0m`,  b: s => `\x1b[1m${s}\x1b[0m`,
+};
+
+function todayStr() {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth()+1).padStart(2,'0')}-${String(d.getDate()).padStart(2,'0')}`;
+}
+function getLogFile() { return path.join(LOG_DIR, 'logs', `${todayStr()}.jsonl`); }
+
+function run() {
+  let s = null; try { s = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf8')); } catch {}
+  console.log(col.b('\n⚡ Occasio\n'));
+  if (!s) { console.log(col.d('  No session data yet. Run: occasio claude\n')); return; }
+
+  const cacheSav  = s.cache_savings      || 0;
+  const laoSav    = s.lao_cost_saved     || 0;
+  const distSav   = s.distill_cost_saved || 0;
+  const payload   = laoSav + distSav;
+  const { savings: context } =
+    calcCompoundingSavings(s.run_id, s.log_file || getLogFile(), s.model || '');
+  const totalSav  = payload + context + cacheSav;
+  const broaderCf = (s.cost || 0) + totalSav;
+  const savedPct  = broaderCf > 0.00001 ? Math.round(totalSav / broaderCf * 100) : 0;
+
+  // Headline
+  if (totalSav > 0.00001) {
+    console.log(col.g(`  Saved:       $${totalSav.toFixed(4)}`) +
+      col.d(`  (${savedPct}% off — would have cost $${broaderCf.toFixed(4)})`));
+  } else {
+    console.log(col.d(`  Saved:       $0.0000  (no interceptable tool calls in this session yet)`));
+  }
+  console.log(col.y(`  Cost:        $${s.cost.toFixed(4)}`));
+
+  // Plain-English coverage. Defensive: legacy sessions (pre-multi-round-fix)
+  // may have tools_attempted undercounted relative to tools_local_count.
+  // We clamp the denominator to at least the numerator so the displayed
+  // ratio is always 0–100% and never reads "X of Y < X (>100%)".
+  const localCnt   = s.tools_local_count || 0;
+  const mcpCnt     = s.tools_mcp_count   || 0;
+  const attempted  = s.tools_attempted   || 0;
+  const totalLocal = localCnt + mcpCnt;
+  const denom      = Math.max(attempted, totalLocal);
+  if (denom > 0) {
+    const cpct = Math.round(totalLocal / denom * 100);
+    const cColor = cpct >= 80 ? col.g : cpct >= 50 ? col.y : col.r;
+    console.log(cColor(`  Ran locally: ${totalLocal} of ${denom} tool calls (${cpct}%)`));
+  }
+  if (s.blocked) console.log(col.r(`  Blocked:     ${s.blocked} secrets`));
+  if (s.secrets_redacted) console.log(col.c(`  Redacted:    ${s.secrets_redacted} secret${s.secrets_redacted !== 1 ? 's' : ''} in tool results`));
+  if (s.tools_transformed) console.log(col.c(`  Transforms:  ${s.tools_transformed} tool result${s.tools_transformed !== 1 ? 's' : ''} shaped`));
+  if (s.budget != null) {
+    const pct = Math.min(999, Math.round((s.cost || 0) / s.budget * 100));
+    const budgetStr = fmtBudget(s.cost || 0, s.budget);
+    const budgetColor = pct >= 100 ? col.r : pct >= 80 ? col.y : col.g;
+    console.log(budgetColor(`  Budget:      ${budgetStr}`));
+    if (s.budget_exceeded_count) console.log(col.r(`  BudgetBlk:   ${s.budget_exceeded_count} request(s) blocked`));
+  }
+
+  // Detail
+  console.log(col.d(`  ────`));
+  console.log(col.d(`  Requests:    ${s.requests} · ${(s.input_tokens/1000).toFixed(1)}k tokens in · ${(s.output_tokens/1000).toFixed(1)}k out`));
+  if (totalSav > 0.00001) {
+    const parts = [];
+    if (payload  > 0.00001) parts.push(`$${payload.toFixed(4)} payload`);
+    if (context  > 0.00001) parts.push(`$${context.toFixed(4)} context`);
+    if (cacheSav > 0.00001) parts.push(`$${cacheSav.toFixed(4)} cache`);
+    if (parts.length) console.log(col.d(`  Breakdown:   ${parts.join(' + ')}`));
+  }
+  const tail = [];
+  if (s.mode)  tail.push(`Mode: ${s.mode}`);
+  if (s.start) tail.push(`Since: ${new Date(s.start).toLocaleString()}`);
+  if (tail.length) console.log(col.d(`  ${tail.join('   ·   ')}`));
+  console.log('');
+}
+
+module.exports = { run };

package/src/cost/prices.js

@@ -0,0 +1,106 @@
+// Token-cost arithmetic for Anthropic-priced models. Extracted from
+// src/index.js so the proxy hot-path doesn't carry pricing data, and so
+// MODEL_PRICES updates land in a file small enough to review at a glance.
+//
+// Prices are USD per 1M tokens. Cache-write is the one-time cost to
+// populate a cache breakpoint; cache-read is the cheap subsequent hit.
+//
+// Substring matching is intentional — Anthropic's model_id strings often
+// carry a dated suffix (claude-haiku-4-5-20251001) we want to absorb
+// without a table update. The trade-off: a truly unknown model silently
+// falls back to `default`. We warn once per unknown model so the failure
+// is loud the first time and quiet thereafter.
+
+'use strict';
+
+const fs = require('fs');
+
+const MODEL_PRICES = {
+  'claude-opus-4-6':   { in: 15.00, out: 75.00, cache_write:  18.75, cache_read:  1.50 },
+  'claude-opus-4':     { in: 15.00, out: 75.00, cache_write:  18.75, cache_read:  1.50 },
+  'claude-sonnet-4-6': { in:  3.00, out: 15.00, cache_write:   3.75, cache_read:  0.30 },
+  'claude-sonnet-4':   { in:  3.00, out: 15.00, cache_write:   3.75, cache_read:  0.30 },
+  'claude-haiku-4-5':  { in:  0.25, out:  1.25, cache_write:   0.30, cache_read:  0.03 },
+  'claude-haiku-4':    { in:  0.25, out:  1.25, cache_write:   0.30, cache_read:  0.03 },
+  'default':           { in:  3.00, out: 15.00, cache_write:   3.75, cache_read:  0.30 },
+};
+
+// Track which unknown model names we've already complained about, so a
+// long session with a new model surfaces the warning exactly once instead
+// of on every request.
+const _warnedUnknown = new Set();
+
+function getPrice(model) {
+  if (!model) return MODEL_PRICES.default;
+  for (const [k, v] of Object.entries(MODEL_PRICES)) {
+    if (k !== 'default' && model.includes(k)) return v;
+  }
+  if (!_warnedUnknown.has(model)) {
+    _warnedUnknown.add(model);
+    // stderr so it doesn't pollute proxy stdout. Silenceable via env for
+    // CI runs that legitimately want to price unknown models as default.
+    if (!process.env.OCCASIO_QUIET_PRICING) {
+      process.stderr.write(
+        `[occasio] warning: unknown model "${model}" — falling back to default pricing ` +
+        `(in:$${MODEL_PRICES.default.in}/M, out:$${MODEL_PRICES.default.out}/M). ` +
+        `Add it to src/cost/prices.js to silence this.\n`
+      );
+    }
+  }
+  return MODEL_PRICES.default;
+}
+
+function calcCost(model, inp, out, cacheWrite = 0, cacheRead = 0) {
+  const p = getPrice(model);
+  return (inp / 1e6 * p.in) + (out / 1e6 * p.out)
+       + (cacheWrite / 1e6 * p.cache_write) + (cacheRead / 1e6 * p.cache_read);
+}
+
+// Savings from Anthropic prompt caching: cache reads are 10× cheaper than fresh input.
+function calcCacheSavings(model, cacheReadTokens) {
+  if (!cacheReadTokens) return 0;
+  const p = getPrice(model);
+  return (cacheReadTokens / 1e6) * (p.in - p.cache_read);
+}
+
+// Cross-request compounding savings: reads the run's JSONL entries in sequence order
+// and weights each distilled batch by the exact number of subsequent API calls that
+// carry the smaller result in their conversation history.
+// Formula: Σ (distill_tokens_saved[i] / 1M × price_in × (N - i - 1))
+// Returns { savings: float, carryInstances: int }
+// carryInstances = total sum of subsequent-call counts across all distilled batches
+// — the actual multiplier used — so the display is self-explanatory.
+// Assumption: tool results accumulate in Claude Code's message history for all
+// subsequent requests in the session (true for normal sessions; may not hold if
+// Claude Code resets context mid-session).
+function calcCompoundingSavings(runId, logFile, model) {
+  if (!runId) return { savings: 0, carryInstances: 0 };
+  let entries;
+  try {
+    const lines = fs.readFileSync(logFile, 'utf8').trim().split('\n').filter(Boolean);
+    entries = lines
+      .map(l => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(e => e && e.run_id === runId);
+  } catch { return { savings: 0, carryInstances: 0 }; }
+  const N = entries.length;
+  if (N < 2) return { savings: 0, carryInstances: 0 };
+  const p = getPrice(model);
+  let savings = 0, carryInstances = 0;
+  for (let i = 0; i < N; i++) {
+    const dt = entries[i].distill_tokens_saved || 0;
+    if (dt > 0) {
+      const subsequent = N - i - 1;
+      savings += (dt / 1e6) * p.in * subsequent;
+      carryInstances += subsequent;
+    }
+  }
+  return { savings, carryInstances };
+}
+
+module.exports = {
+  MODEL_PRICES,
+  getPrice,
+  calcCost,
+  calcCacheSavings,
+  calcCompoundingSavings,
+};