@occasiolabs/occasio 0.8.1

package/src/preflight/cli.js

@@ -0,0 +1,164 @@
+'use strict';
+
+/**
+ * occasio preflight — CLI entry point (ARCH-26, read-only).
+ *
+ * Usage:
+ *   occasio preflight               Print opening-move pattern table
+ *   occasio preflight --show        Same (alias for future flag compatibility)
+ *   occasio preflight --days N      Use last N days of logs (default: 30)
+ *   occasio preflight --reset       Clear pattern store (available after ARCH-27)
+ */
+
+const os   = require('os');
+const path = require('path');
+const {
+  mine,
+  getGitRoot,
+  MIN_SESSIONS_FOR_PATTERN,
+} = require('./miner');
+
+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`,
+};
+
+// Minimum display confidence threshold — patterns below this are not shown
+const DISPLAY_THRESHOLD = 0.40;
+
+// Maximum table rows
+const MAX_ROWS = 10;
+
+function ordinal(n) {
+  const r = Math.round(n);
+  if (r === 1) return '1st';
+  if (r === 2) return '2nd';
+  if (r === 3) return '3rd';
+  return `${r}th+`;
+}
+
+function truncate(s, maxLen) {
+  if (s.length <= maxLen) return s;
+  return '…' + s.slice(-(maxLen - 1)); // right-side truncation preserves filename
+}
+
+function runPreflightCli(args, opts) {
+  const { cwd: cwdOverride, logsDir } = opts || {};
+
+  const daysIdx = (args || []).indexOf('--days');
+  const days    = daysIdx >= 0 ? (parseInt(args[daysIdx + 1], 10) || 30) : 30;
+  const reset   = (args || []).includes('--reset');
+
+  const cwd         = cwdOverride || process.cwd();
+  const gitRoot     = getGitRoot(cwd);
+  const projectRoot = gitRoot || cwd;
+  const displayRoot = projectRoot.replace(os.homedir(), '~');
+  const rootLabel   = gitRoot ? 'git root' : 'directory';
+
+  console.log(col.b('\n⚡ Occasio — Opening-move patterns\n'));
+
+  // --reset: placeholder until ARCH-27 adds persistent pattern store
+  if (reset) {
+    console.log(`  ${col.d(`${displayRoot}  (${rootLabel})`)}`);
+    console.log(col.d('\n  Pattern store reset will be available after ARCH-27 (pattern persistence).\n'));
+    return { ok: true };
+  }
+
+  const allProjects = mine({ days, logsDir, filterCwd: cwd });
+  const proj        = allProjects.find(p => p.projectRoot === projectRoot);
+
+  // ── Empty-state handling ─────────────────────────────────────────────────────
+
+  if (!proj || proj.totalSessions === 0) {
+    console.log(`  ${col.d(`${displayRoot}  (${rootLabel})`)}`);
+    console.log(col.d(`  0 sessions with cwd tracking  \xb7  last ${days} days\n`));
+    console.log(col.d(`  No session history found for this project.`));
+    if (!proj || proj.totalSessions === 0) {
+      console.log(col.d(`  Patterns emerge after ${MIN_SESSIONS_FOR_PATTERN}+ sessions.`));
+      console.log(col.d(`  (cwd tracking requires Occasio ≥v0.6.3)\n`));
+    }
+    return { ok: true, totalSessions: 0 };
+  }
+
+  if (proj.totalSessions < MIN_SESSIONS_FOR_PATTERN) {
+    console.log(`  ${col.d(`${displayRoot}  (${rootLabel})`)}`);
+    console.log(col.d(`  ${proj.totalSessions} session${proj.totalSessions !== 1 ? 's' : ''}  \xb7  last ${days} days\n`));
+    console.log(col.d(`  Not enough history — patterns emerge after ${MIN_SESSIONS_FOR_PATTERN}+ sessions.\n`));
+    return { ok: true, totalSessions: proj.totalSessions };
+  }
+
+  // ── Table ────────────────────────────────────────────────────────────────────
+
+  const candidates = proj.tools
+    .filter(t => t.confidence >= DISPLAY_THRESHOLD)
+    .slice(0, MAX_ROWS);
+
+  console.log(`  ${col.d(`${displayRoot}  (${rootLabel})`)}`);
+  console.log(col.d(`  ${proj.totalSessions} sessions  \xb7  last ${days} days  \xb7  first 5 tool calls per session\n`));
+
+  if (!candidates.length) {
+    console.log(col.d(`  No consistent patterns found. Sessions in this project vary too much.\n`));
+    return { ok: true, totalSessions: proj.totalSessions, candidates: 0 };
+  }
+
+  // Column widths
+  const W_NUM    = 2;
+  const W_TOOL   = 6;
+  const W_TARGET = 44;
+  const W_SEEN   = 9;
+  const W_CONF   = 11;
+  const W_POS    = 10;
+
+  const header = [
+    '#'.padEnd(W_NUM),
+    'Tool'.padEnd(W_TOOL),
+    'Target'.padEnd(W_TARGET),
+    'Seen'.padStart(W_SEEN),
+    'Confidence'.padStart(W_CONF),
+    'Position'.padStart(W_POS),
+  ].join('  ');
+
+  const divider = [
+    '─'.repeat(W_NUM),
+    '─'.repeat(W_TOOL),
+    '─'.repeat(W_TARGET),
+    '─'.repeat(W_SEEN),
+    '─'.repeat(W_CONF),
+    '─'.repeat(W_POS),
+  ].join('  ');
+
+  console.log(`  ${col.d(header)}`);
+  console.log(`  ${col.d(divider)}`);
+
+  for (let i = 0; i < candidates.length; i++) {
+    const c       = candidates[i];
+    const numStr  = String(i + 1).padEnd(W_NUM);
+    const toolStr = c.tool.padEnd(W_TOOL);
+    const target  = truncate(c.cmd, W_TARGET).padEnd(W_TARGET);
+    const seen    = `${c.count} / ${c.totalSessions}`.padStart(W_SEEN);
+    const confPct = `${Math.round(c.confidence * 100)}%`.padStart(W_CONF);
+    const posStr  = ordinal(c.medianPosition).padStart(W_POS);
+
+    const confColor = c.confidence >= 0.70 ? col.g
+                    : c.confidence >= 0.50 ? col.y
+                    : col.d;
+
+    console.log(
+      `  ${col.d(numStr)}  ${col.c(toolStr)}  ${col.d(target)}  ` +
+      `${col.d(seen)}  ${confColor(confPct)}  ${col.d(posStr)}`
+    );
+  }
+
+  console.log('');
+  console.log(col.d(`  Patterns learned locally from tool-usage history, not prompt content.`));
+  console.log(col.d(`  Preflight execution is off. Run occasio with --preflight to enable (coming soon).`));
+  console.log(col.d(`  To reset patterns for this project: occasio preflight --reset\n`));
+
+  return { ok: true, totalSessions: proj.totalSessions, candidates: candidates.length };
+}
+
+module.exports = { runPreflightCli };

package/src/preflight/miner.js

@@ -0,0 +1,329 @@
+'use strict';
+
+/**
+ * Preflight pattern miner (ARCH-26, read-only).
+ *
+ * Reads ~/.occasio/logs/*.jsonl, groups entries by run_id, and identifies
+ * which tool calls appear consistently at the start of sessions for a given
+ * project root. No execution, no caching, no side effects.
+ *
+ * Schema requirement: log entries must have a `cwd` field (added in v0.6.3).
+ * Entries without `cwd` are silently skipped; the mine() output will show
+ * how many cwd-tagged sessions were found.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const { execSync } = require('child_process');
+
+const LOG_DIR = path.join(os.homedir(), '.occasio');
+
+// Only mine these tool types. Shell commands are too variable to be useful
+// as preflight candidates; todo tools carry no path information.
+const MINEABLE_TOOLS = new Set([
+  'Read', 'Glob', 'Grep',           // Claude Code agent-protocol names
+  'read_file', 'find_files', 'grep', // Cline / canonical names
+]);
+
+// Number of tools to consider "early in session" (per ARCH-26 design)
+const EARLY_TOOL_LIMIT = 5;
+
+// Minimum sessions before a pattern is surfaced
+const MIN_SESSIONS_FOR_PATTERN = 3;
+
+// -------------------------------------------------------------------
+// Normalization helpers
+// -------------------------------------------------------------------
+
+function normalizeToolName(name) {
+  if (name === 'Read'     || name === 'read_file')  return 'read';
+  if (name === 'Glob'     || name === 'find_files') return 'glob';
+  if (name === 'Grep'     || name === 'grep')       return 'grep';
+  return (name || 'unknown').toLowerCase();
+}
+
+// Make a path relative to a root directory.
+// Returns the basename if the path is outside the root (e.g. cross-drive on Windows).
+function relativize(root, absPath) {
+  if (!root || !absPath) return absPath || '';
+  try {
+    const rel = path.relative(root, absPath);
+    // Starts with '..' means outside root — fall back to basename for readability
+    return rel.startsWith('..') ? path.basename(absPath) : rel;
+  } catch {
+    return absPath;
+  }
+}
+
+// Build a stable, comparable key for a tool call within a project.
+// Read: key on relative file path (the cmd field is the absolute path).
+// Glob / Grep: key on the pattern string (cmd is the pattern).
+// Shell / other: excluded by MINEABLE_TOOLS guard before this is called.
+function buildToolKey(toolRecord, projectRoot) {
+  const name = normalizeToolName(toolRecord.tool);
+  const cmd  = toolRecord.cmd || '';
+
+  if (name === 'read') {
+    const rel = relativize(projectRoot, cmd);
+    return `${name}:${rel}`;
+  }
+  // glob and grep: cmd is already the pattern string
+  return `${name}:${cmd}`;
+}
+
+// -------------------------------------------------------------------
+// Git root detection (cached, non-fatal)
+// -------------------------------------------------------------------
+
+const _gitRootCache = new Map();
+
+function getGitRoot(dir) {
+  if (!dir) return null;
+  if (_gitRootCache.has(dir)) return _gitRootCache.get(dir);
+  try {
+    if (!fs.existsSync(dir)) {
+      _gitRootCache.set(dir, null);
+      return null;
+    }
+    const raw = execSync('git rev-parse --show-toplevel', {
+      cwd: dir,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 2000,
+    }).toString().trim();
+    // Normalize separators so Windows forward-slash git output matches path.resolve()
+    const normalized = raw.split('/').join(path.sep);
+    _gitRootCache.set(dir, normalized);
+    return normalized;
+  } catch {
+    _gitRootCache.set(dir, null);
+    return null;
+  }
+}
+
+// -------------------------------------------------------------------
+// Log reading
+// -------------------------------------------------------------------
+
+function readRecentEntries(days, logsDir) {
+  const dir = logsDir || path.join(LOG_DIR, 'logs');
+  const entries = [];
+  try {
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - days);
+    const files = fs.readdirSync(dir)
+      .filter(f => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f))
+      .filter(f => {
+        try { return new Date(f.slice(0, 10)) >= cutoff; } catch { return false; }
+      })
+      .sort(); // chronological; oldest first
+    for (const f of files) {
+      const raw = fs.readFileSync(path.join(dir, f), 'utf8');
+      for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try { entries.push(JSON.parse(trimmed)); } catch {}
+      }
+    }
+  } catch {}
+  return entries;
+}
+
+// -------------------------------------------------------------------
+// Run grouping and early-tool extraction
+// -------------------------------------------------------------------
+
+// Group entries by run_id (entries without run_id are skipped).
+// Sort each group's entries by iso timestamp ascending.
+function groupByRun(entries) {
+  const map = new Map();
+  for (const e of entries) {
+    if (!e.run_id) continue;
+    if (!map.has(e.run_id)) map.set(e.run_id, []);
+    map.get(e.run_id).push(e);
+  }
+  for (const arr of map.values()) {
+    arr.sort((a, b) => {
+      const ai = a.iso || a.ts || '';
+      const bi = b.iso || b.ts || '';
+      return ai < bi ? -1 : ai > bi ? 1 : 0;
+    });
+  }
+  return map;
+}
+
+// Pick cwd from the first entry in a run that carries the field.
+// Returns null for runs logged before cwd was added to the schema.
+function runCwd(runEntries) {
+  for (const e of runEntries) {
+    if (typeof e.cwd === 'string' && e.cwd) return e.cwd;
+  }
+  return null;
+}
+
+// Extract the first EARLY_TOOL_LIMIT mineable tool calls across all entries
+// of a run, in chronological order of the entries they appear in.
+function earlyTools(runEntries, limit) {
+  const result = [];
+  for (const entry of runEntries) {
+    if (!Array.isArray(entry.tools)) continue;
+    for (const t of entry.tools) {
+      if (!MINEABLE_TOOLS.has(t.tool)) continue;
+      result.push(t);
+      if (result.length >= limit) return result;
+    }
+  }
+  return result;
+}
+
+// -------------------------------------------------------------------
+// Median helper
+// -------------------------------------------------------------------
+
+function median(arr) {
+  if (!arr.length) return 1;
+  const sorted = [...arr].sort((a, b) => a - b);
+  const mid    = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0
+    ? (sorted[mid - 1] + sorted[mid]) / 2
+    : sorted[mid];
+}
+
+// -------------------------------------------------------------------
+// Core miner
+// -------------------------------------------------------------------
+
+/**
+ * Mine opening-move patterns from logs.
+ *
+ * Options:
+ *   days      — how many days of logs to scan (default: 30)
+ *   logsDir   — override log directory (for tests)
+ *   filterCwd — if provided, only return patterns for this working directory
+ *
+ * Returns an array of project records, each shaped:
+ * {
+ *   projectRoot: string,       // git root or raw cwd
+ *   totalSessions: number,     // distinct run_ids with cwd for this project
+ *   legacySessions: number,    // run_ids seen but lacking cwd field (info only)
+ *   tools: Array<{
+ *     key: string,             // stable tool key
+ *     tool: string,            // 'read' | 'glob' | 'grep'
+ *     cmd: string,             // display-friendly target/pattern
+ *     count: number,           // sessions that included this tool early
+ *     totalSessions: number,   // same as parent.totalSessions
+ *     confidence: number,      // count / totalSessions  (0–1)
+ *     medianPosition: number,  // 1-indexed median ordinal position in early window
+ *   }>
+ * }
+ */
+function mine(opts) {
+  const { days = 30, logsDir, filterCwd } = opts || {};
+
+  const entries = readRecentEntries(days, logsDir);
+  const runsMap = groupByRun(entries);
+
+  // Determine what project root the caller wants (if filtering)
+  let filterRoot = null;
+  if (filterCwd) {
+    filterRoot = getGitRoot(filterCwd) || filterCwd;
+  }
+
+  // project_root → { projectRoot, sessions: Set, toolCounts: Map, legacySessions: number }
+  const projects = new Map();
+  let totalLegacy = 0;
+
+  for (const [, runEntries] of runsMap) {
+    const cwd = runCwd(runEntries);
+    if (!cwd) {
+      // Pre-schema run; count it if it falls under the filter project
+      // but we can't know which project it belongs to — just count globally.
+      totalLegacy++;
+      continue;
+    }
+
+    const gitRoot     = getGitRoot(cwd);
+    const projectRoot = gitRoot || cwd;
+
+    if (filterRoot && projectRoot !== filterRoot) continue;
+
+    if (!projects.has(projectRoot)) {
+      projects.set(projectRoot, {
+        projectRoot,
+        sessions:    new Set(),
+        toolCounts:  new Map(),   // toolKey → { count, positions[], tool, cmd }
+        legacySessions: 0,
+      });
+    }
+
+    const proj = projects.get(projectRoot);
+    proj.sessions.add(runEntries[0].run_id);
+
+    const tools = earlyTools(runEntries, EARLY_TOOL_LIMIT);
+    tools.forEach((t, idx) => {
+      const key = buildToolKey(t, projectRoot);
+      if (!proj.toolCounts.has(key)) {
+        proj.toolCounts.set(key, {
+          count:     0,
+          positions: [],
+          tool:      normalizeToolName(t.tool),
+          cmd:       t.cmd || '',
+        });
+      }
+      const rec = proj.toolCounts.get(key);
+      rec.count++;
+      rec.positions.push(idx + 1); // 1-indexed position in early window
+    });
+  }
+
+  const result = [];
+  for (const [, proj] of projects) {
+    const totalSessions = proj.sessions.size;
+    if (totalSessions === 0) continue;
+
+    const toolsList = [];
+    for (const [key, rec] of proj.toolCounts) {
+      const confidence    = rec.count / totalSessions;
+      const medianPosition = median(rec.positions);
+      toolsList.push({
+        key,
+        tool:         rec.tool,
+        cmd:          rec.cmd,
+        count:        rec.count,
+        totalSessions,
+        confidence,
+        medianPosition,
+      });
+    }
+
+    // Sort: confidence desc, then median position asc (earlier = better preflight candidate)
+    toolsList.sort((a, b) =>
+      b.confidence - a.confidence || a.medianPosition - b.medianPosition
+    );
+
+    result.push({
+      projectRoot:    proj.projectRoot,
+      totalSessions,
+      legacySessions: proj.legacySessions,
+      tools:          toolsList,
+    });
+  }
+
+  return result;
+}
+
+module.exports = {
+  mine,
+  // Exported for testing
+  readRecentEntries,
+  groupByRun,
+  earlyTools,
+  buildToolKey,
+  normalizeToolName,
+  relativize,
+  getGitRoot,
+  median,
+  runCwd,
+  EARLY_TOOL_LIMIT,
+  MIN_SESSIONS_FOR_PATTERN,
+};

package/src/proxy/agent-router.js

@@ -0,0 +1,93 @@
+'use strict';
+
+/**
+ * Agent router — picks an adapter for an incoming proxy request.
+ *
+ * Detection signal: the `x-occasio-agent` HTTP header.
+ *   - Header value matches a registered agent → that adapter.
+ *   - Header missing or unknown               → claude-code (default).
+ *
+ * The header is Occasio-internal: callers (Cline, etc.) set it; the
+ * proxy strips it before forwarding to Anthropic.
+ *
+ * This module deliberately knows about no specific adapter. Adapters are
+ * passed in as a map by the proxy bootstrap. That keeps this file
+ * agent-agnostic and testable in isolation.
+ */
+
+/**
+ * Content fingerprint — given an Anthropic SSE response buffer and the
+ * registry, find the agent whose tool-name map best matches the tool blocks
+ * in the response. Returns the agentId or null if no agent claims any name.
+ *
+ * Used as a fallback signal when the explicit header is absent (e.g., the
+ * user's tool doesn't expose a custom-headers UI). Content fingerprint is
+ * deterministic and cannot misroute Claude Code traffic — Claude Code's
+ * tool names (`Read`, `Bash`) only exist in the claude-code map.
+ */
+function detectAgentFromSse(sseBody, adapters, registry) {
+  if (!sseBody || !adapters || !registry) return null;
+  try {
+    const { parseSSE } = require('../interceptor');
+    const parsed = parseSSE(sseBody);
+    const blocks = parsed && parsed.blocks ? Object.values(parsed.blocks) : [];
+    const names = blocks.filter(b => b && b.type === 'tool_use').map(b => b.name);
+    if (!names.length) return null;
+
+    let best = null;
+    let bestScore = 0;
+    for (const agentId of Object.keys(adapters)) {
+      const score = names.reduce(
+        (n, name) => n + (registry.toCanonical(agentId, name) ? 1 : 0),
+        0,
+      );
+      if (score > bestScore) { best = agentId; bestScore = score; }
+    }
+    return bestScore > 0 ? best : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pick an adapter for an incoming proxy request.
+ *
+ * Resolution order:
+ *   1. Explicit header  `x-occasio-agent`  → that adapter
+ *   2. Content fingerprint (when sseBody + registry supplied)
+ *   3. defaultAgent
+ *
+ * @param {object} headers
+ * @param {object} adapters       { [agentId]: adapterModule, ... }
+ * @param {string} defaultAgent   agentId to pick when nothing else matches
+ * @param {object} [opts]         { sseBody, registry } for content fingerprint
+ * @returns {{ adapter, agentId, source: 'header' | 'fingerprint' | 'default' }}
+ */
+function selectAdapter(headers, adapters, defaultAgent, opts = {}) {
+  const raw = headers && headers['x-occasio-agent'];
+  if (typeof raw === 'string') {
+    const id = raw.trim().toLowerCase();
+    if (adapters && adapters[id]) {
+      return { adapter: adapters[id], agentId: id, source: 'header' };
+    }
+  }
+
+  // Content fingerprint — used when the header is missing or the tool's
+  // request configuration didn't forward it. Only fires when sseBody and
+  // registry are provided (proxy supplies them; unit tests can omit).
+  if (opts.sseBody && opts.registry) {
+    const detected = detectAgentFromSse(opts.sseBody, adapters, opts.registry);
+    if (detected && detected !== defaultAgent) {
+      return { adapter: adapters[detected], agentId: detected, source: 'fingerprint' };
+    }
+  }
+
+  if (!adapters || !adapters[defaultAgent]) {
+    throw new Error(`agent-router: defaultAgent "${defaultAgent}" not in adapters map`);
+  }
+  return { adapter: adapters[defaultAgent], agentId: defaultAgent, source: 'default' };
+}
+
+const HEADER_NAME = 'x-occasio-agent';
+
+module.exports = { selectAdapter, detectAgentFromSse, HEADER_NAME };