@agentguard-run/burn 0.1.0 → 0.1.1

package/dist/src/hook/pre-tool-use.js

@@ -27,6 +27,7 @@ const claude_transcript_1 = require("../history/claude-transcript");
 const reservations_1 = require("../state/reservations");
 const session_1 = require("../state/session");
 const defaults_1 = require("../defaults");
+const render_1 = require("../replay/render");
 const SPAWN_TOOLS = new Set(['Agent', 'Task']);
 function sessionFile(home, sessionId) {
     return (0, node_path_1.join)(home, 'sessions', `${sessionId.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
@@ -145,10 +146,10 @@ function handlePreToolUse(input, home, now = Date.now()) {
     }
     return { continue: true, suppressOutput: true };
 }
-function buildDenyReason(report, reservation) {
-    const lead = report.findings.find((f) => f.verdict === 'STOP')?.summary ?? `Fan-out ceiling reached (${reservation.effectiveSpawns} effective spawns).`;
-    const rx = report.prescriptions.slice(0, 3).map((p, i) => `${i + 1}. ${p}`).join(' ');
-    return `AgentGuard STOP: blocked this agent spawn. ${lead} ${rx} Override once with: agentguard-burn resume --once --reason "..."`;
+function buildDenyReason(report, _reservation) {
+    // Claude Code shows this reason to the user. A box reads as an alarm; a
+    // sentence reads as a log line. Colour is off: the host decides rendering.
+    return (0, render_1.renderStop)(report, { colour: false });
 }
 function deny(reason) {
     return {

package/dist/src/replay/render.d.ts

@@ -1,11 +1,17 @@
 /**
- * Terminal rendering for replay. This output is the marketing artifact, so it
- * has to survive a screenshot: pure ASCII box drawing, ANSI colour that
- * degrades cleanly, nothing that depends on a font.
+ * Terminal rendering. This output is the distribution artifact, so it is
+ * designed to be screenshotted: one giant number, a curve you can see the
+ * runaway in, one line worth quoting. Pure ASCII/ANSI, degrades cleanly.
  */
+import type { BurnReport } from '../types';
 import type { ReplaySummary, SessionReplay } from './simulate';
+export declare function sparkline(curve: number[], stopAt: number | null, on: boolean): string;
+export declare function comparison(tokens: number): string;
 export declare function renderReplay(summary: ReplaySummary, opts?: {
     colour?: boolean;
     top?: number;
 }): string;
+export declare function renderStop(report: BurnReport, opts?: {
+    colour?: boolean;
+}): string;
 export declare function renderSessionRow(s: SessionReplay): string;

package/dist/src/replay/render.js

@@ -1,11 +1,14 @@
 "use strict";
 /**
- * Terminal rendering for replay. This output is the marketing artifact, so it
- * has to survive a screenshot: pure ASCII box drawing, ANSI colour that
- * degrades cleanly, nothing that depends on a font.
+ * Terminal rendering. This output is the distribution artifact, so it is
+ * designed to be screenshotted: one giant number, a curve you can see the
+ * runaway in, one line worth quoting. Pure ASCII/ANSI, degrades cleanly.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.sparkline = sparkline;
+exports.comparison = comparison;
 exports.renderReplay = renderReplay;
+exports.renderStop = renderStop;
 exports.renderSessionRow = renderSessionRow;
 const evaluate_1 = require("../detectors/evaluate");
 const C = {
@@ -16,74 +19,201 @@ const C = {
     yellow: '\x1b[33m',
     green: '\x1b[32m',
     cyan: '\x1b[36m',
+    magenta: '\x1b[35m',
+    bgRed: '\x1b[41m',
+    white: '\x1b[97m',
 };
-function colour(enabled, code, text) {
-    return enabled ? `${code}${text}${C.reset}` : text;
+const W = 72;
+function paint(on, code, text) {
+    return on ? `${code}${text}${C.reset}` : text;
 }
-const W = 70;
-function line(text = '') {
-    const clean = text.replace(/\x1b\[[0-9;]*m/g, '');
-    const pad = Math.max(0, W - 2 - clean.length);
+function strip(text) {
+    return text.replace(/\x1b\[[0-9;]*m/g, '');
+}
+function row(text = '') {
+    const pad = Math.max(0, W - 2 - strip(text).length);
     return `│ ${text}${' '.repeat(pad)} │`;
 }
 const TOP = `╭${'─'.repeat(W)}╮`;
 const MID = `├${'─'.repeat(W)}┤`;
 const BOT = `╰${'─'.repeat(W)}╯`;
-/** API-list equivalent. Labelled as a scenario, never as the user's bill. */
+// ---------------------------------------------------------------------------
+// Block digits. Five rows, three columns each, for 0-9 . % B K M and space.
+// ---------------------------------------------------------------------------
+const GLYPHS = {
+    '0': ['█▀▀█', '█  █', '█  █', '█  █', '▀▀▀▀'],
+    '1': ['  ▀█', '   █', '   █', '   █', '   ▀'],
+    '2': ['▀▀▀█', '   █', '█▀▀▀', '█   ', '▀▀▀▀'],
+    '3': ['▀▀▀█', '   █', ' ▀▀█', '   █', '▀▀▀▀'],
+    '4': ['█  █', '█  █', '▀▀▀█', '   █', '   ▀'],
+    '5': ['█▀▀▀', '█   ', '▀▀▀█', '   █', '▀▀▀▀'],
+    '6': ['█▀▀▀', '█   ', '█▀▀█', '█  █', '▀▀▀▀'],
+    '7': ['▀▀▀█', '   █', '   █', '   █', '   ▀'],
+    '8': ['█▀▀█', '█  █', '█▀▀█', '█  █', '▀▀▀▀'],
+    '9': ['█▀▀█', '█  █', '▀▀▀█', '   █', '▀▀▀▀'],
+    '.': ['    ', '    ', '    ', '    ', ' ▀  '],
+    '%': ['▀▀  █', '   █ ', '  █  ', ' █   ', '█  ▀▀'],
+    B: ['█▀▀▄', '█  █', '█▀▀▄', '█  █', '▀▀▀ '],
+    M: ['█▄ ▄█', '█ ▀ █', '█   █', '█   █', '▀   ▀'],
+    K: ['█  █', '█ █ ', '██  ', '█ █ ', '▀  ▀'],
+    ' ': ['  ', '  ', '  ', '  ', '  '],
+};
+function blockDigits(text) {
+    const rows = ['', '', '', '', ''];
+    for (const ch of text) {
+        const g = GLYPHS[ch] ?? GLYPHS[' '];
+        for (let r = 0; r < 5; r++)
+            rows[r] += g[r] + ' ';
+    }
+    return rows.map((r) => r.trimEnd());
+}
+// ---------------------------------------------------------------------------
+// Sparkline with the STOP point marked.
+// ---------------------------------------------------------------------------
+const BARS = '▁▂▃▄▅▆▇█';
+function sparkline(curve, stopAt, on) {
+    if (curve.length === 0)
+        return '';
+    let out = '';
+    for (let i = 0; i < curve.length; i++) {
+        const level = Math.min(BARS.length - 1, Math.max(0, Math.round(curve[i] * (BARS.length - 1))));
+        const bar = BARS[level];
+        if (stopAt !== null && i >= stopAt) {
+            // Everything after the stop is the tail enforcement would have cut.
+            out += paint(on, C.red, i === stopAt ? '┃' : bar);
+        }
+        else {
+            out += paint(on, C.green, bar);
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// The quotable comparison. Tokens to something a human can picture.
+// ---------------------------------------------------------------------------
+const COMPARISONS = [
+    { tokens: 7_000_000_000, label: 'all of English Wikipedia' },
+    { tokens: 1_200_000_000, label: 'the entire Harry Potter series, 1,000 times' },
+    { tokens: 200_000_000, label: 'the complete works of Shakespeare, 200 times' },
+    { tokens: 40_000_000, label: 'the King James Bible, 50 times' },
+    { tokens: 130_000, label: 'Slaughterhouse-Five' },
+];
+function comparison(tokens) {
+    for (const c of COMPARISONS) {
+        const times = tokens / c.tokens;
+        if (times >= 1) {
+            const n = times >= 10 ? Math.round(times) : Math.round(times * 10) / 10;
+            return `≈ ${c.label}${n > 1 ? `, ${n}×` : ''}`;
+        }
+    }
+    return '';
+}
+// ---------------------------------------------------------------------------
+// Replay
+// ---------------------------------------------------------------------------
 function scenarioUsd(tokens, cacheShare) {
     const cached = tokens * cacheShare;
     return (cached * 0.3 + (tokens - cached) * 5) / 1e6;
 }
 function renderReplay(summary, opts = {}) {
     const on = opts.colour ?? Boolean(process.stdout.isTTY);
-    const top = opts.top ?? 8;
+    const top = opts.top ?? 6;
     const out = [];
-    const cacheShare = summary.sessions.length
-        ? summary.sessions.reduce((s, r) => s + r.cacheReadRatio * r.totalTokens, 0) / Math.max(summary.totalTokens, 1)
+    const cacheShare = summary.totalTokens
+        ? summary.sessions.reduce((s, r) => s + r.cacheReadRatio * r.totalTokens, 0) / summary.totalTokens
         : 0;
+    const share = Math.round(summary.catchableShare * 100);
     out.push(TOP);
-    out.push(line(colour(on, C.bold, 'AGENTGUARD REPLAY')));
-    out.push(line(colour(on, C.dim, 'Your agent history, before enforcement was installed')));
+    out.push(row(paint(on, C.bold + C.magenta, 'AGENTGUARD') + '  ' + paint(on, C.dim, 'replay · your agent history, before enforcement')));
     out.push(MID);
-    out.push(line(`${summary.sessions.length} sessions   ${summary.totalSpawns} spawns   ${(0, evaluate_1.fmt)(summary.totalTokens)} tokens observed`));
-    out.push(line(colour(on, C.dim, `${Math.round(cacheShare * 100)}% cache-read. Shown as explanation; it decided nothing.`)));
+    // Hero: the one number. Rendered huge.
+    out.push(row(''));
+    for (const line of blockDigits(`${share}%`))
+        out.push(row('  ' + paint(on, C.bold + C.green, line)));
+    out.push(row(''));
+    out.push(row('  ' + paint(on, C.bold, 'of everything you burned came after a point it would have blocked')));
+    out.push(row(''));
+    // Three supporting numbers, card-style.
+    const cards = [
+        { n: (0, evaluate_1.fmt)(summary.totalTokens), l: 'observed', c: C.white },
+        { n: (0, evaluate_1.fmt)(summary.catchableTail), l: 'after STOP', c: C.red },
+        { n: `$${Math.round(scenarioUsd(summary.catchableTail, cacheShare)).toLocaleString()}`, l: 'API-list, scenario', c: C.yellow },
+    ];
+    const COL = 20;
+    out.push(row('  ' + cards.map((k) => paint(on, C.bold + k.c, k.n.padEnd(COL))).join('')));
+    out.push(row('  ' + cards.map((k) => paint(on, C.dim, k.l.padEnd(COL))).join('')));
+    const comp = comparison(summary.catchableTail);
+    if (comp)
+        out.push(row('  ' + paint(on, C.dim, comp)));
     out.push(MID);
-    out.push(line(colour(on, C.bold, 'WHAT ENFORCEMENT WOULD HAVE INTERCEPTED')));
-    out.push(line(''));
-    const share = Math.round(summary.catchableShare * 100);
-    out.push(line(`${colour(on, C.bold, (0, evaluate_1.fmt)(summary.catchableTail))} tokens observed after the first STOP boundary`));
-    out.push(line(`${share}% of everything you burned   ≈ $${Math.round(scenarioUsd(summary.catchableTail, cacheShare)).toLocaleString()} at API list, as a scenario`));
-    out.push(line(''));
-    out.push(line(colour(on, C.dim, 'Upper bound. It assumes you would not have overridden or restarted.')));
-    out.push(MID);
-    out.push(line(`${colour(on, C.red, `${summary.stops} STOP`)}   ${colour(on, C.yellow, `${summary.warns} WARN`)}   ${colour(on, C.green, `${summary.clean} clean`)}`));
+    out.push(row(`${paint(on, C.bold + C.red, `${summary.stops} STOP`)}   ${paint(on, C.bold + C.yellow, `${summary.warns} WARN`)}   ${paint(on, C.bold + C.green, `${summary.clean} clean`)}` +
+        paint(on, C.dim, `   across ${summary.sessions.length} sessions, ${summary.totalSpawns} spawns`)));
     out.push(MID);
     for (const s of summary.sessions.slice(0, top)) {
-        out.push(line(colour(on, C.bold, `session ${s.sessionId.slice(0, 8)}`) + `   ${(0, evaluate_1.fmt)(s.totalTokens)} tokens · ${s.spawns} spawns · depth ${s.maxDepth}`));
-        if (s.fanoutStop) {
-            out.push(line(`  ${colour(on, C.red, 'FAN-OUT STOP')} before spawn ${s.fanoutStop.atSpawn} at ${(0, evaluate_1.fmt)(s.fanoutStop.tokensAtStop)}`));
-        }
-        if (s.sustainedStop) {
-            out.push(line(`  ${colour(on, C.red, 'SUSTAINED STOP')} near ${(0, evaluate_1.fmt)(s.sustainedStop.tokensAtStop)}`));
-        }
-        if (!s.fanoutStop && !s.sustainedStop) {
-            if (s.firstWarn)
-                out.push(line(`  ${colour(on, C.yellow, 'WARN')} (${s.firstWarn.detector}) at ${(0, evaluate_1.fmt)(s.firstWarn.tokensAt)} · no stop`));
-            else
-                out.push(line(`  ${colour(on, C.green, 'clean')}`));
-        }
-        if (s.catchableTail > 0) {
-            out.push(line(`  observed tail after stop: ${colour(on, C.bold, (0, evaluate_1.fmt)(s.catchableTail))}`));
-        }
+        const tag = s.fanoutStop ? paint(on, C.red, 'FAN-OUT STOP') : s.sustainedStop ? paint(on, C.red, 'SUSTAINED STOP') : s.firstWarn ? paint(on, C.yellow, 'WARN') : paint(on, C.green, 'clean');
+        out.push(row(`${sparkline(s.curve, s.stopAtIndex, on)}  ${tag}`));
+        const detail = s.fanoutStop
+            ? `before spawn ${s.fanoutStop.atSpawn}, tail ${(0, evaluate_1.fmt)(s.catchableTail)}`
+            : s.sustainedStop
+                ? `near ${(0, evaluate_1.fmt)(s.sustainedStop.tokensAtStop)}, tail ${(0, evaluate_1.fmt)(s.catchableTail)}`
+                : `${(0, evaluate_1.fmt)(s.totalTokens)} · ${s.spawns} spawns`;
+        out.push(row(paint(on, C.dim, `${s.sessionId.slice(0, 8)}  ${(0, evaluate_1.fmt)(s.totalTokens).padStart(6)} · ${String(s.spawns).padStart(3)} spawns   ${detail}`)));
     }
     if (summary.sessions.length > top) {
-        out.push(line(colour(on, C.dim, `… ${summary.sessions.length - top} more sessions below the warning line`)));
+        out.push(row(paint(on, C.dim, `… ${summary.sessions.length - top} more, all clean`)));
     }
     out.push(MID);
-    out.push(line(colour(on, C.cyan, 'Next: agentguard-burn init   (shadow mode; blocks nothing yet)')));
+    out.push(row(paint(on, C.dim, 'Upper bound; assumes no override or restart. Nothing left this machine.')));
+    out.push(row(paint(on, C.cyan, 'next  agentguard-burn init') + paint(on, C.dim, '   shadow mode; blocks nothing until you say so')));
     out.push(BOT);
     return out.join('\n');
 }
+// ---------------------------------------------------------------------------
+// The mid-session STOP box. What Claude shows the user when a spawn is denied.
+// ---------------------------------------------------------------------------
+function renderStop(report, opts = {}) {
+    const on = opts.colour ?? false;
+    const lead = report.findings.find((f) => f.verdict === 'STOP')?.summary ?? 'Fan-out ceiling reached.';
+    const w = 64;
+    const bar = '━'.repeat(w);
+    const lines = [];
+    lines.push(paint(on, C.red, `┏${bar}┓`));
+    lines.push(paint(on, C.red, '┃ ') + paint(on, C.bold + C.bgRed + C.white, ' AGENTGUARD STOP ') + paint(on, C.bold, '  agent spawn blocked') + paint(on, C.red, ' '.repeat(w - 40) + '┃'));
+    lines.push(paint(on, C.red, `┣${bar}┫`));
+    lines.push(paint(on, C.red, '┃ ') + lead.padEnd(w - 1).slice(0, w - 1) + paint(on, C.red, '┃'));
+    lines.push(paint(on, C.red, '┃ ') + paint(on, C.dim, `${(0, evaluate_1.fmt)(report.totals.tokens)} tokens · ${report.totals.spawns} spawns · depth ${report.totals.maxDepth}`.padEnd(w - 1)) + paint(on, C.red, '┃'));
+    lines.push(paint(on, C.red, `┣${bar}┫`));
+    lines.push(paint(on, C.red, '┃ ') + paint(on, C.bold, 'DO NOW'.padEnd(w - 1)) + paint(on, C.red, '┃'));
+    report.prescriptions.slice(0, 3).forEach((p, i) => {
+        const wrapped = wrap(`${i + 1}. ${p}`, w - 2, '   ');
+        for (const line of wrapped) {
+            lines.push(paint(on, C.red, '┃ ') + line.padEnd(w - 1) + paint(on, C.red, '┃'));
+        }
+    });
+    lines.push(paint(on, C.red, `┣${bar}┫`));
+    lines.push(paint(on, C.red, '┃ ') + paint(on, C.dim, 'override once:  agentguard-burn resume --once --reason "..."'.padEnd(w - 1)) + paint(on, C.red, '┃'));
+    lines.push(paint(on, C.red, `┗${bar}┛`));
+    return lines.join('\n');
+}
+/** Word-aware wrap. Continuation lines are indented. */
+function wrap(text, width, indent) {
+    const words = text.split(' ');
+    const lines = [];
+    let current = '';
+    for (const word of words) {
+        const prefix = lines.length ? indent : '';
+        if ((current + ' ' + word).trim().length + prefix.length > width && current) {
+            lines.push((lines.length ? indent : '') + current);
+            current = word;
+        }
+        else {
+            current = current ? `${current} ${word}` : word;
+        }
+    }
+    if (current)
+        lines.push((lines.length ? indent : '') + current);
+    return lines;
+}
 function renderSessionRow(s) {
     return `${s.sessionId.slice(0, 8)}  ${(0, evaluate_1.fmt)(s.totalTokens).padStart(8)}  ${String(s.spawns).padStart(4)} spawns  ${s.finalVerdict}`;
 }

package/dist/src/replay/simulate.d.ts

@@ -37,6 +37,10 @@ export interface SessionReplay {
         tokensAt: number;
         spawnsAt: number;
     } | null;
+    /** Cumulative tokens sampled over active time, for a sparkline. 0..1 normalised. */
+    curve: number[];
+    /** Index into curve where the earliest STOP fired, or null. */
+    stopAtIndex: number | null;
 }
 export declare function discoverTranscripts(root?: string): string[];
 export declare function replaySession(path: string, thresholds: Thresholds): SessionReplay | null;

package/dist/src/replay/simulate.js

@@ -60,6 +60,9 @@ function replayEvents(sessionId, path, events, thresholds) {
     let sustainedStop = null;
     let firstWarn = null;
     let tokensAtEarliestStop = null;
+    // Cumulative tokens after every event, for the sparkline.
+    const timeline = [];
+    let stopEventIndex = null;
     for (const event of events) {
         // A hook boundary exists only where a spawn was attempted. Evaluate the
         // *proposal* before applying the event, then apply it.
@@ -80,6 +83,7 @@ function replayEvents(sessionId, path, events, thresholds) {
             }
             if ((fanoutStop || sustainedStop) && tokensAtEarliestStop === null) {
                 tokensAtEarliestStop = state.totalTokens;
+                stopEventIndex = timeline.length;
             }
         }
         // The sustained plane also has a boundary at every tool call, not just
@@ -92,12 +96,16 @@ function replayEvents(sessionId, path, events, thresholds) {
             const hit = report.findings.find((f) => f.verdict === 'STOP' && (f.detector === 'sustained_burn' || f.detector === 'burn_debt'));
             if (hit) {
                 sustainedStop = { atSpawn: state.spawnCount, tokensAtStop: state.totalTokens };
-                if (tokensAtEarliestStop === null)
+                if (tokensAtEarliestStop === null) {
                     tokensAtEarliestStop = state.totalTokens;
+                    stopEventIndex = timeline.length;
+                }
             }
         }
         (0, session_1.applyEvent)(state, event);
+        timeline.push(state.totalTokens);
     }
+    const { curve, stopAtIndex } = downsample(timeline, stopEventIndex, 32);
     const final = (0, evaluate_1.evaluate)(state, thresholds, null);
     return {
         sessionId,
@@ -112,8 +120,23 @@ function replayEvents(sessionId, path, events, thresholds) {
         sustainedStop,
         catchableTail: tokensAtEarliestStop === null ? 0 : Math.max(0, state.totalTokens - tokensAtEarliestStop),
         firstWarn,
+        curve,
+        stopAtIndex,
     };
 }
+/** Compress a cumulative timeline into N normalised buckets, carrying the stop index across. */
+function downsample(timeline, stopIndex, buckets) {
+    if (timeline.length === 0)
+        return { curve: [], stopAtIndex: null };
+    const max = timeline[timeline.length - 1] || 1;
+    const curve = [];
+    for (let b = 0; b < buckets; b++) {
+        const i = Math.min(timeline.length - 1, Math.floor(((b + 1) / buckets) * timeline.length) - 1);
+        curve.push(Math.max(0, timeline[Math.max(0, i)]) / max);
+    }
+    const stopAtIndex = stopIndex === null ? null : Math.min(buckets - 1, Math.floor((stopIndex / timeline.length) * buckets));
+    return { curve, stopAtIndex };
+}
 function replayAll(paths, thresholds, minTokens = 0) {
     const sessions = [];
     for (const path of paths) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentguard-run/burn",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local runaway-agent circuit breaker for AI coding agents. Detects fan-out storms and sustained token burn, blocks the next spawn, and proves what happened. Nothing leaves the machine.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -39,4 +39,4 @@
     "runaway",
     "fan-out"
   ]
-}
+}