agentbox-flight-recorder 0.2.1

package/src/parse.js

@@ -0,0 +1,265 @@
+'use strict';
+/**
+ * agentbox — parse.js
+ * Zero-magic heuristics that classify agent output lines and build a
+ * session summary. Bring-your-own-parser later; these rules ship on by
+ * default and intentionally err on the side of "plain".
+ */
+
+// ANSI escape sequences (colors etc.) — stripped before classification
+const ANSI_RE = /\x1b(?:\[[?0-9;:><]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\)|[P^_].*?\x1b\\)/g;
+
+function stripAnsi(s) {
+  return String(s || '').replace(ANSI_RE, '');
+}
+
+// A shell-ish command at line start (with or without $ / > prompt)
+const CMD_RE = /^\s*(?:\$\s*|>\s*)?((?:sudo\s+)?(?:npm|npx|pnpm|yarn|bun|pip3?|python3?|node|deno|git|cargo|go|make|cmake|docker|kubectl|helm|brew|apt(?:-get)?|curl|wget|ssh|scp|rsync|terraform|aws|gcloud|gh|pytest|rails|ls|cp|mv|rm|mkdir|touch|chmod|chown|cat|sed|awk|grep)\b.+)$/i;
+
+// Explicit tool-call convention: [TOOL] name("args")  — agents can adopt it
+const TOOL_RE = /^\[(?:TOOL|tool|Tool)\]\s*(.+)$/;
+
+// File writes/edits/deletes mentioned in prose or tool output
+const FILEOP_RE = /\b(wrote|created|edited|deleted|removed|modified|renamed|overwrote)\b\s+(?:the\s+)?(?:file\s+)?([\w./~\\-]+\.[A-Za-z0-9]{1,10})/i;
+const FILE_GROUP_RE = /\b(wrote|created|edited|deleted|removed|modified|renamed|overwrote)\b\s+\d+\s+files?\b/i;
+const FILE_GROUP_ITEM_RE = /[└├]\s*([\w./~\\-]+\.[A-Za-z0-9]{1,10})\s*\(/;
+
+// File ops embedded in tool calls, e.g. write(src/deploy.sh — 42 lines)
+const TOOL_FILE_RE = /\b(write|edit|create|delete|remove|overwrite|patch|update)\s*\(\s*[\"']?([\w./~\\-]+\.[A-Za-z0-9]{1,10})\b/i;
+const VERB_MAP = { write: 'wrote', edit: 'edited', patch: 'edited', update: 'edited', create: 'created', delete: 'deleted', remove: 'removed', overwrite: 'overwrote' };
+
+// Structured tool names (from the hook/MCP adapters) → file op, for receipts
+const TOOLNAME_OP_MAP = {
+  Write: 'wrote', Edit: 'edited', MultiEdit: 'edited', NotebookEdit: 'edited',
+  Delete: 'removed', Remove: 'removed', Move: 'renamed', Rename: 'renamed',
+};
+function opForToolName(name) {
+  return TOOLNAME_OP_MAP[name] || 'touched';
+}
+
+/**
+ * Short, human preview of a tool input: known primary fields read better
+ * than raw JSON. Bash({command:'ls'}) → 'ls'; Write({file_path}) → the path.
+ */
+function inputPreview(input, cap = 120) {
+  if (input == null) return '';
+  if (typeof input === 'string') return input.slice(0, cap);
+  if (typeof input === 'object') {
+    const primary = input.command || input.file_path || input.notebook_path || input.path
+      || input.url || input.query || input.pattern || input.text;
+    if (primary != null) return String(primary).slice(0, cap);
+  }
+  try { return JSON.stringify(input).slice(0, cap); } catch { return String(input).slice(0, cap); }
+}
+
+/** One-line label for a structured tool call: Bash(git status --short) */
+function toolCallLabel(name, input) {
+  const preview = inputPreview(input, 120);
+  return `${name || 'tool'}${preview ? `(${preview})` : ''}`.slice(0, 200);
+}
+
+// URLs hit (network activity)
+const URL_RE = /https?:\/\/[^\s"'<>)\]]+/;
+
+/** Classify one line of output. Priority: tool > cmd > file > net > plain. */
+function classifyLine(line) {
+  const clean = stripAnsi(line);
+  if (!clean || !clean.trim()) return { kind: 'plain' };
+  const tool = clean.match(TOOL_RE);
+  if (tool) {
+    return { kind: 'tool', detail: tool[1].trim().slice(0, 200) };
+  }
+  const cmd = clean.match(CMD_RE);
+  if (cmd) {
+    return { kind: 'cmd', detail: cmd[1].trim().slice(0, 200) };
+  }
+  const file = clean.match(FILEOP_RE);
+  if (file) {
+    return { kind: 'file', detail: { op: file[1].toLowerCase(), path: file[2] } };
+  }
+  const url = clean.match(URL_RE);
+  if (url) {
+    return { kind: 'net', detail: url[0].slice(0, 200) };
+  }
+  return { kind: 'plain' };
+}
+
+/**
+ * Build a human summary from a verified event list.
+ * Event types produced by wrap():
+ *   meta  {cmd, argv, cwd, user, host, platform, node, agentbox, name, adapter?}
+ *   out   {stream: 'stdout'|'stderr', kind, text?|detail?}
+ *   in    {text}
+ *   exit  {code, durationMs}
+ *   signal{signal}
+ * Event types produced by the adapters (claude hooks / mcp wire tap):
+ *   tool_call    {phase:'start'|'end', name, input?, status?, durationMs?, source, id?}
+ *   prompt       {text, source}
+ *   notification {message}
+ *   turn_end     {}
+ *   mcp_msg      {dir:'C2S'|'S2C', method, id, preview}
+ *   note         {message}
+ */
+function summarize(events) {
+  const meta = events.find((e) => e.type === 'meta');
+  const exit = [...events].reverse().find((e) => e.type === 'exit');
+  const startT = events.length ? events[0].t : 0;
+  const endT = events.length ? events[events.length - 1].t : 0;
+
+  const stats = {
+    name: (meta && meta.data && meta.data.name) || 'session',
+    command: meta ? meta.data.cmd : '?',
+    cwd: meta ? meta.data.cwd : '?',
+    user: meta ? meta.data.user : '?',
+    adapter: (meta && meta.data && meta.data.adapter) || 'wrap',
+    started: startT ? new Date(startT) : null,
+    durationMs: exit && exit.data && exit.data.durationMs != null ? exit.data.durationMs : Math.max(0, endT - startT),
+    exitCode: exit && exit.data ? exit.data.code : null,
+    events: events.length,
+    byType: {},
+    byKind: {},
+    outputBytes: 0,
+    stderrLines: 0,
+    commands: [],
+    tools: [],
+    files: [],        // { op, path }
+    urls: [],
+    stdinEvents: 0,
+    humansConsulted: 0,
+    signals: [],
+    prompts: [],      // structured prompts (hook adapter)
+    turns: 0,         // agent turn boundaries (Stop hooks)
+    notifications: 0,
+    mcpMessages: 0,
+    toolCallStarts: 0,
+    toolCallEnds: 0,
+    toolErrors: 0,
+  };
+  const endOnlyNames = [];
+  let groupedFileOp = null;
+  let groupedFileUntil = 0;
+
+  for (const ev of events) {
+    stats.byType[ev.type] = (stats.byType[ev.type] || 0) + 1;
+    if (ev.type === 'out') {
+      const d = ev.data || {};
+      const kind = d.kind || 'plain';
+      const clean = stripAnsi(d.text || '');
+      stats.byKind[kind] = (stats.byKind[kind] || 0) + 1;
+      if (d.stream === 'stderr') stats.stderrLines += 1;
+      stats.outputBytes += Buffer.byteLength(String(d.text != null ? d.text : (d.detail || '')), 'utf8');
+      if (kind === 'cmd') {
+        const m = clean.match(CMD_RE);
+        stats.commands.push(m ? m[1].trim() : clean);
+      }
+      if (kind === 'tool') {
+        const m = clean.match(TOOL_RE);
+        const toolDetail = m ? m[1].trim() : (d.detail || clean);
+        stats.tools.push(toolDetail);
+        // file ops hidden inside tool calls: write(src/deploy.sh — …)
+        const tf = toolDetail.match(TOOL_FILE_RE);
+        if (tf) stats.files.push({ op: VERB_MAP[tf[1].toLowerCase()] || tf[1].toLowerCase(), path: tf[2] });
+      }
+      if (kind === 'file') {
+        const detail = d.detail && d.detail.path ? d.detail : classifyLine(d.text || '').detail;
+        if (detail && detail.path) stats.files.push({ op: detail.op, path: detail.path });
+      }
+      const group = clean.match(FILE_GROUP_RE);
+      if (group) {
+        groupedFileOp = group[1].toLowerCase();
+        groupedFileUntil = ev.t + 10000;
+      } else if (ev.t > groupedFileUntil) {
+        groupedFileOp = null;
+      }
+      const groupItem = groupedFileOp && clean.match(FILE_GROUP_ITEM_RE);
+      if (groupItem) stats.files.push({ op: groupedFileOp, path: groupItem[1] });
+      // URLs observed anywhere in output (stripped of ANSI)
+      const scan = stripAnsi([typeof d.detail === 'string' ? d.detail : '', typeof d.text === 'string' ? d.text : ''].join(' '));
+      const u = scan.match(URL_RE);
+      if (u) stats.urls.push(u[0]);
+    } else if (ev.type === 'in') {
+      stats.stdinEvents += 1;
+    } else if (ev.type === 'signal') {
+      stats.signals.push(ev.data && ev.data.signal);
+    } else if (ev.type === 'tool_call') {
+      // structured tool calls from the claude-code hook / mcp adapters
+      const d = ev.data || {};
+      if (d.phase === 'end') {
+        stats.toolCallEnds += 1;
+        if (d.status === 'error') stats.toolErrors += 1;
+        endOnlyNames.push(String(d.name || 'tool'));
+      } else {
+        stats.toolCallStarts += 1;
+        stats.tools.push(toolCallLabel(d.name, d.input));
+        if (d.input && typeof d.input === 'object') {
+          const p = d.input.file_path || d.input.notebook_path || d.input.path;
+          if (p) stats.files.push({ op: opForToolName(String(d.name || '')), path: String(p) });
+          if (d.input.command) stats.commands.push(String(d.input.command).slice(0, 200));
+          if (d.input.url) stats.urls.push(String(d.input.url).slice(0, 200));
+        }
+      }
+    } else if (ev.type === 'prompt') {
+      stats.stdinEvents += 1;
+      if (ev.data && ev.data.text) stats.prompts.push(String(ev.data.text).slice(0, 200));
+    } else if (ev.type === 'turn_end') {
+      stats.turns += 1;
+    } else if (ev.type === 'notification') {
+      stats.notifications += 1;
+    } else if (ev.type === 'mcp_msg') {
+      stats.mcpMessages += 1;
+    }
+  }
+
+  // session joined mid-flight (hooks added after start): no PreToolUse starts,
+  // only PostToolUse ends — still name the tools from the ends
+  if (stats.toolCallStarts === 0 && endOnlyNames.length) {
+    stats.tools.push(...endOnlyNames.map((n) => `${n} ()`));
+  }
+
+  stats.humansConsulted = stats.stdinEvents > 0 || stats.prompts.length > 0 ? 1 : 0;
+
+  // de-dup helpers
+  const uniq = (arr) => [...new Set(arr)];
+  stats.commands = uniq(stats.commands);
+  stats.urls = uniq(stats.urls);
+
+  // collapse file ops per path
+  const fileMap = new Map();
+  for (const f of stats.files) {
+    const cur = fileMap.get(f.path) || new Set();
+    cur.add(f.op);
+    fileMap.set(f.path, cur);
+  }
+  stats.files = [...fileMap.entries()].map(([p, ops]) => ({ path: p, ops: [...ops] }));
+
+  return stats;
+}
+
+function fmtDuration(ms) {
+  if (ms == null) return '?';
+  const s = Math.round(ms / 100) / 10;
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  const rem = Math.round(s % 60);
+  return `${m}m ${rem}s`;
+}
+
+function fmtBytes(b) {
+  if (b < 1024) return `${b} B`;
+  if (b < 1024 * 1024) return `${(b / 1024).toFixed(1)} kB`;
+  return `${(b / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/** A deadpan one-liner verdict, receipt style. */
+function verdict(stats) {
+  const deleted = stats.files.filter((f) => f.ops.some((o) => o === 'deleted' || o === 'removed'));
+  if (stats.signals.includes('SIGINT')) return 'flight interrupted mid-air. black box recovered.';
+  if (stats.toolErrors > 0) return `${stats.toolErrors} tool call${stats.toolErrors > 1 ? 's' : ''} went sideways. tape tells you which.`;
+  if (stats.exitCode !== 0 && stats.exitCode != null) return 'agentbox received. wreckage mapped below.';
+  if (deleted.length > 0) return `${deleted.length} file${deleted.length > 1 ? 's' : ''} deleted. hope ${deleted.length > 1 ? 'they were' : 'it was'} not load-bearing.`;
+  if (stats.humansConsulted === 0 && stats.events > 20) return 'smooth flight. zero supervision. as requested.';
+  if (stats.exitCode === 0) return 'uneventful flight. the best kind.';
+  return 'black box recovered. details below.';
+}
+
+module.exports = { classifyLine, summarize, fmtDuration, fmtBytes, verdict, stripAnsi, toolCallLabel, inputPreview, opForToolName, CMD_RE, TOOL_RE, FILEOP_RE, FILE_GROUP_RE, FILE_GROUP_ITEM_RE, TOOL_FILE_RE, URL_RE };

package/src/receipt.js

@@ -0,0 +1,176 @@
+'use strict';
+/**
+ * agentbox — receipt.js
+ * The one-page flight receipt: what happened, in numbers a human can scan
+ * in 5 seconds. Formats: text (POS-receipt aesthetic), markdown (PRs),
+ * json (machines).
+ */
+const { verifyChain } = require('./chain');
+const { summarize, fmtDuration, fmtBytes, verdict } = require('./parse');
+
+const CYAN = '\x1b[36m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const RESET = '\x1b[0m';
+const ORANGE = '\x1b[38;5;208m';
+
+const W = 52; // inner width
+
+function safeText(s) {
+  return String(s == null ? '' : s)
+    .replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, '')
+    .replace(/\x1b\[[?0-9;:><]*[ -/]*[@-~]/g, '')
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, '');
+}
+
+function mdEsc(s) {
+  return safeText(s).replace(/\\/g, '\\\\').replace(/([`*_[\]<>|])/g, '\\$1').replace(/\r?\n/g, ' ');
+}
+
+function visibleLen(s) {
+  return String(s || '').replace(/\x1b(?:\[[0-9;]*[A-HJKSTfmnsu]|\][^\x07]*(?:\x07|\x1b\\)|[P^_].*?\x1b\\)/g, '').length;
+}
+
+function pad(s, w) {
+  s = String(s);
+  const len = visibleLen(s);
+  if (len > w) return pad(s.slice(0, Math.max(0, w - 1)), w) + '…';
+  return s + ' '.repeat(Math.max(0, w - len));
+}
+function row(label, value) {
+  return `│ ${pad(safeText(label), 24)}${pad(safeText(value), W - 27)}│`;
+}
+/** multi-row value: wraps long values across continuation rows */
+function rowsFor(label, value) {
+  const out = [];
+  const chunks = String(value == null ? '' : value).match(/.{1,24}(\s|$)|\S+/g) || [''];
+  out.push(row(label, chunks[0] || ''));
+  for (let i = 1; i < chunks.length; i++) out.push(row(i === chunks.length - 1 ? '' : '  ↳', chunks[i]));
+  return out;
+}
+function sep() {
+  return `├${'─'.repeat(W - 2)}┤`;
+}
+
+function textReceipt(stats, chainOk) {
+  const lines = [];
+  const title = '⬢  A G E N T B O X   R E C E I P T';
+  lines.push('');
+  lines.push(`${CYAN}${BOLD}${title.padStart(Math.floor((W + title.length) / 2))}${RESET}`);
+  lines.push(`┌${'─'.repeat(W - 2)}┐`);
+  lines.push(...rowsFor('session', stats.name));
+  lines.push(...rowsFor('command', stats.command));
+  if (stats.adapter && stats.adapter !== 'wrap') {
+    lines.push(row('recorded via', stats.adapter === 'claude-code' ? 'claude code hooks' : stats.adapter === 'mcp' ? 'mcp wire tap' : stats.adapter));
+  }
+  lines.push(row('started', stats.started ? stats.started.toISOString().replace('T', ' ').slice(0, 19) : '?'));
+  lines.push(row('duration', fmtDuration(stats.durationMs)));
+  lines.push(row('exit code', stats.exitCode === 0 ? '0  (clean landing)' : stats.exitCode == null ? '?' : `${stats.exitCode}  (see tape)`));
+  lines.push(sep());
+
+  const toolN = stats.tools.length;
+  const cmdN = stats.commands.length;
+  lines.push(row('tool calls', String(toolN)));
+  if (stats.toolErrors) lines.push(row('tool errors', `${RED}${String(stats.toolErrors)}${RESET}`));
+  if (stats.turns) lines.push(row('agent turns', String(stats.turns)));
+  for (const t of stats.tools.slice(0, 4)) lines.push(row(`  · ${t.slice(0, 20)}`, ''));
+  if (toolN > 4) lines.push(row(`  … +${toolN - 4} more`, ''));
+  lines.push(row('shell commands', String(cmdN)));
+  for (const c of stats.commands.slice(0, 3)) lines.push(row(`  · ${c.slice(0, 20)}`, ''));
+  if (cmdN > 3) lines.push(row(`  … +${cmdN - 3} more`, ''));
+
+  const touched = stats.files.length;
+  const writes = stats.files.filter((f) => f.ops.some((o) => /wrote|created|overwrote/i.test(o))).length;
+  const edits = stats.files.filter((f) => f.ops.some((o) => /edited|modified|renamed/i.test(o))).length;
+  const dels = stats.files.filter((f) => f.ops.some((o) => /deleted|removed/i.test(o))).length;
+  lines.push(row('files touched', `${touched}${writes ? ` · ${writes} written` : ''}${edits ? ` · ${edits} edited` : ''}${dels ? ` · ${RED}${dels} deleted${RESET}` : ''}`));
+  for (const f of stats.files.slice(0, 4)) lines.push(row(`  · ${f.path.slice(0, 20)}`, f.ops.join(', ').slice(0, 20)));
+  if (touched > 4) lines.push(row(`  … +${touched - 4} more`, ''));
+
+  lines.push(row('urls hit', String(stats.urls.length)));
+  lines.push(row('output volume', `${fmtBytes(stats.outputBytes)} across ${stats.byType.out || 0} lines`));
+  lines.push(row('stderr lines', String(stats.stderrLines)));
+  lines.push(row('humans consulted', stats.humansConsulted ? '1  (kept in the loop)' : '0  (unsupervised flight)'));
+  lines.push(sep());
+  lines.push(row('events recorded', String(stats.events)));
+  lines.push(row('tamper chain', chainOk ? `${GREEN}sha256 · intact${RESET}` : `${RED}BROKEN${RESET}`));
+  lines.push(`└${'─'.repeat(W - 2)}┘`);
+  lines.push(`${ORANGE}${verdict(stats)}${RESET}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function markdownReceipt(stats, chainOk) {
+  const L = [];
+  L.push(`## ⬢ AGENTBOX flight receipt — \`${mdEsc(stats.name)}\``);
+  L.push('');
+  L.push(`> ${mdEsc(verdict(stats))}`);
+  L.push('');
+  L.push('| | |');
+  L.push('|---|---|');
+  L.push(`| **command** | \`${mdEsc(stats.command)}\` |`);
+  L.push(`| **started** | ${stats.started ? stats.started.toISOString() : '?'} |`);
+  L.push(`| **duration** | ${fmtDuration(stats.durationMs)} |`);
+  L.push(`| **exit code** | ${stats.exitCode == null ? '?' : stats.exitCode} |`);
+  L.push(`| **tool calls** | ${stats.tools.length} |`);
+  L.push(`| **shell commands** | ${stats.commands.length} |`);
+  L.push(`| **files touched** | ${stats.files.length}${stats.files.some((f) => f.ops.some((o) => /deleted|removed/i.test(o))) ? ' ⚠️ incl. deletions' : ''} |`);
+  L.push(`| **urls hit** | ${stats.urls.length} |`);
+  L.push(`| **humans consulted** | ${stats.humansConsulted} |`);
+  L.push(`| **events** | ${stats.events} (${fmtBytes(stats.outputBytes)} of output) |`);
+  L.push(`| **tamper chain** | ${chainOk ? '✅ sha256 intact' : '❌ BROKEN'} |`);
+  if (stats.humansConsulted) {
+    L.push('');
+    L.push('<details><summary>Prompts (the human did say things)</summary>');
+    L.push('');
+    for (const p of stats.prompts.slice(0, 10)) L.push(`- “${mdEsc(p).slice(0, 120)}”`);
+    L.push('');
+    L.push('</details>');
+  }
+  if (stats.files.length) {
+    L.push('');
+    L.push('<details><summary>Files touched</summary>');
+    L.push('');
+    for (const f of stats.files.slice(0, 20)) L.push(`- \`${mdEsc(f.path)}\` — ${mdEsc(f.ops.join(', '))}`);
+    L.push('');
+    L.push('</details>');
+  }
+  if (stats.tools.length) {
+    L.push('');
+    L.push('<details><summary>Tool calls</summary>');
+    L.push('');
+    for (const t of stats.tools.slice(0, 20)) L.push(`- \`${mdEsc(t)}\``);
+    L.push('');
+    L.push('</details>');
+  }
+  return L.join('\n');
+}
+
+function jsonReceipt(stats, chainOk, file) {
+  return JSON.stringify({ file, chainOk, ...stats, started: stats.started ? stats.started.toISOString() : null }, null, 2);
+}
+
+/**
+ * Print/render a receipt for a session file.
+ * opts: { format: 'text'|'markdown'|'json', force }
+ * Returns { ok, stats, chainOk }.
+ */
+function receipt(file, opts = {}) {
+  const res = verifyChain(file);
+  const chainOk = res.ok && res.complete;
+  if ((!res.ok || !res.complete) && !opts.force) {
+    process.stderr.write(`\x1b[31m⬢ agentbox: chain verification FAILED — ${res.reason || 'session is incomplete (missing exit event)'}\x1b[0m\n`);
+    process.exitCode = 1;
+    return { ok: false, chainOk, stats: null };
+  }
+  const stats = summarize(res.events);
+  const format = opts.format || 'text';
+  if (format === 'json') process.stdout.write(jsonReceipt(stats, chainOk, file) + '\n');
+  else if (format === 'markdown' || format === 'md') process.stdout.write(markdownReceipt(stats, chainOk) + '\n');
+  else process.stdout.write(textReceipt(stats, chainOk) + '\n');
+  return { ok: true, chainOk, stats };
+}
+
+module.exports = { receipt, textReceipt, markdownReceipt };

package/src/redact.js

@@ -0,0 +1,231 @@
+'use strict';
+/**
+ * agentbox — redact.js
+ * Default-on secret scrubbing for the flight tape.
+ *
+ * Every string that is about to be written to a session file passes through
+ * here. The hash chain commits to the *redacted* form, so the tape never
+ * contains the original secret and is still tamper-evident.
+ *
+ * Disable:     AGENTBOX_REDACT=0
+ * Extra rules: AGENTBOX_REDACT_EXTRA=pattern1|pattern2   (JS regex sources)
+ * Project cfg: .agentbox/config.json → { "redact": true, "redactPatterns": ["…"] }
+ *
+ * Design rules:
+ *   1. Deterministic — same input always yields the same redacted output
+ *      (required for a stable hash chain).
+ *   2. Conservative — prefer false positives over leaking a real secret.
+ *   3. Shape-preserving — objects stay objects; only string leaves change.
+ *   4. Never throw — a broken redactor must not abort a recording flight.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const PLACEHOLDER = '[REDACTED]';
+const SECRET_KEY_RE = /^(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret|auth(?:orization)?|auth[_-]?token|session[_-]?key)$/i;
+
+/**
+ * Built-in patterns. Order matters only for readability; each match is
+ * replaced independently. Keep sources free of the /g flag — we add it.
+ */
+const BUILTIN = [
+  // OpenAI / compatible
+  { name: 'openai',     re: /\bsk-[A-Za-z0-9]{20,}\b/g },
+  // Anthropic
+  { name: 'anthropic',  re: /\bsk-ant-[A-Za-z0-9\-_]{20,}\b/g },
+  // GitHub tokens
+  { name: 'github',     re: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/g },
+  // AWS access key id
+  { name: 'aws-key',    re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+  // AWS secret access key (40 base64-ish chars next to aws/secret context is hard;
+  // catch the common "SecretAccessKey=…" / "aws_secret_access_key=…" form instead)
+  { name: 'aws-secret', re: /(?:aws_?secret_?access_?key|secretAccessKey)\s*[=:]\s*["']?[A-Za-z0-9/+=]{35,}["']?/gi },
+  // Slack
+  { name: 'slack',      re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+  // Stripe
+  { name: 'stripe',     re: /\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g },
+  // Google API key
+  { name: 'google',     re: /\bAIza[0-9A-Za-z\-_]{20,}\b/g },
+  // Twilio
+  { name: 'twilio',     re: /\bSK[0-9a-fA-F]{32}\b/g },
+  // Bearer / Authorization header values
+  { name: 'bearer',     re: /(?:Bearer|Authorization)\s*[:=]?\s*["']?[A-Za-z0-9\-._~+/]+=*["']?/gi },
+  // JWT (three base64url segments)
+  { name: 'jwt',        re: /\beyJ[A-Za-z0-9\-_]{10,}\.[A-Za-z0-9\-_]{10,}\.[A-Za-z0-9\-_]{10,}\b/g },
+  // PEM private keys (single-line or the header alone is enough signal)
+  { name: 'pem',        re: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g },
+  { name: 'pem-hdr',    re: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g },
+  // Generic KEY=value / "key": "value" for secret-ish names
+  // (password, secret, token, apikey, api_key, access_key, private_key, client_secret, …)
+  {
+    name: 'kv-secret',
+    re: /(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret|auth[_-]?token|session[_-]?key)\s*[=:]\s*["']?[^\s"'\\]{6,}["']?/gi,
+  },
+  // JSON-style "password": "…"
+  {
+    name: 'json-secret',
+    re: /"(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret|auth[_-]?token)"\s*:\s*"[^"]{4,}"/gi,
+  },
+  // Connection strings with embedded credentials
+  {
+    name: 'connstr',
+    re: /\b(?:postgres|postgresql|mysql|mongodb|redis|amqp|https?):\/\/[^:\s]+:[^@\s]+@[^\s]+/gi,
+  },
+];
+
+let _cache = null; // { enabled, patterns: [{name, re}] }
+
+function loadConfig(cwd) {
+  const root = cwd || process.cwd();
+  try {
+    const cfgPath = path.join(root, '.agentbox', 'config.json');
+    if (fs.existsSync(cfgPath)) {
+      return JSON.parse(fs.readFileSync(cfgPath, 'utf8')) || {};
+    }
+  } catch { /* ignore malformed config */ }
+  return {};
+}
+
+/**
+ * Resolve enabled flag + pattern list. Result is cached for the process
+ * lifetime (config is expected to be stable during a session).
+ */
+function resolve(cwd) {
+  if (_cache) return _cache;
+
+  const env = process.env.AGENTBOX_REDACT;
+  const cfg = loadConfig(cwd);
+  // explicit false / "0" / "off" / "false" disables; everything else is on
+  let enabled = true;
+  if (env != null && /^(0|false|off|no)$/i.test(String(env).trim())) enabled = false;
+  if (cfg.redact === false) enabled = false;
+  if (cfg.redact === true) enabled = true;
+  // AGENTBOX_REDACT=1 forces on even if config said off
+  if (env != null && /^(1|true|on|yes)$/i.test(String(env).trim())) enabled = true;
+
+  const patterns = BUILTIN.map((p) => ({ name: p.name, re: cloneRe(p.re) }));
+
+  // project-level extra patterns
+  const extra = [];
+  if (Array.isArray(cfg.redactPatterns)) extra.push(...cfg.redactPatterns);
+  if (process.env.AGENTBOX_REDACT_EXTRA) {
+    extra.push(...String(process.env.AGENTBOX_REDACT_EXTRA).split('|').map((s) => s.trim()).filter(Boolean));
+  }
+  for (const src of extra) {
+    try {
+      patterns.push({ name: 'custom', re: new RegExp(src, 'gi') });
+    } catch { /* skip invalid user regex */ }
+  }
+
+  _cache = { enabled, patterns };
+  return _cache;
+}
+
+/** Force-reload config (tests only). */
+function resetCache() {
+  _cache = null;
+}
+
+function cloneRe(re) {
+  return new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g');
+}
+
+/**
+ * Redact a single string. Returns { text, count } where count is the number
+ * of pattern hits (not characters).
+ */
+function redactString(s, opts = {}) {
+  if (s == null) return { text: s, count: 0 };
+  const str = String(s);
+  if (!str) return { text: str, count: 0 };
+
+  const { enabled, patterns } = resolve(opts.cwd);
+  if (!enabled) return { text: str, count: 0 };
+
+  let text = str;
+  let count = 0;
+  for (const p of patterns) {
+    // reset lastIndex — we may reuse the same RegExp instance
+    p.re.lastIndex = 0;
+    if (!p.re.test(text)) continue;
+    p.re.lastIndex = 0;
+    text = text.replace(p.re, () => {
+      count += 1;
+      return PLACEHOLDER;
+    });
+  }
+  return { text, count };
+}
+
+/**
+ * Deep-redact any JSON-serializable value.
+ * - strings → redacted strings
+ * - arrays / plain objects → walked
+ * - numbers, bools, null → unchanged
+ * Never mutates the input.
+ */
+function redactDeep(value, opts = {}) {
+  const state = { count: 0 };
+  const out = walk(value, state, opts, 0);
+  return { value: out, count: state.count };
+}
+
+function walk(v, state, opts, depth, key) {
+  if (depth > 30) return v; // defensive against cycles / absurd nesting
+  if (v == null) return v;
+  const t = typeof v;
+  if (t === 'string') {
+    if (key && SECRET_KEY_RE.test(key)) { state.count += 1; return PLACEHOLDER; }
+    const r = redactString(v, opts);
+    state.count += r.count;
+    return r.text;
+  }
+  if (t === 'number' || t === 'boolean') return v;
+  if (Array.isArray(v)) {
+    return v.map((item) => walk(item, state, opts, depth + 1));
+  }
+  if (t === 'object') {
+    // plain object only — skip Buffer, Date, etc.
+    if (Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null) {
+      return v;
+    }
+    const out = {};
+    for (const k of Object.keys(v)) {
+      // also redact secret-looking *keys*' values more aggressively is already
+      // handled by the kv/json patterns on stringified forms; walk the value.
+      if (SECRET_KEY_RE.test(k) && v[k] != null) {
+        out[k] = PLACEHOLDER;
+        state.count += 1;
+      } else out[k] = walk(v[k], state, opts, depth + 1, k);
+    }
+    return out;
+  }
+  return v;
+}
+
+/**
+ * Convenience used by the chain writer: redact event data in place-of
+ * and return the scrubbed copy plus a hit count.
+ */
+function redactEventData(data, opts = {}) {
+  if (data == null) return { data, count: 0 };
+  if (typeof data !== 'object') {
+    const r = redactString(data, opts);
+    return { data: r.text, count: r.count };
+  }
+  const r = redactDeep(data, opts);
+  return { data: r.value, count: r.count };
+}
+
+module.exports = {
+  PLACEHOLDER,
+  BUILTIN,
+  redactString,
+  redactDeep,
+  redactEventData,
+  resolve,
+  resetCache,
+  loadConfig,
+  SECRET_KEY_RE,
+};