@agentguard-run/burn 0.1.0

package/dist/src/state/session.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Session state: fold events into the numbers detectors need.
+ *
+ * Active time is the key idea. These sessions are resumed over days. A
+ * wall-clock rolling window dilutes real activity with hours of idleness, so a
+ * "16 spawns in 5 minutes" rule never fires on a session that spawned 143
+ * agents over an evening with coffee breaks. Active time caps every gap
+ * between events, so a burst looks like a burst regardless of when the session
+ * started.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newSessionState = newSessionState;
+exports.applyEvent = applyEvent;
+exports.windowSum = windowSum;
+exports.medianCompletedMinute = medianCompletedMinute;
+exports.cacheReadRatio = cacheReadRatio;
+const defaults_1 = require("../defaults");
+function newSessionState(sessionId, firstEventAt) {
+    return {
+        sessionId,
+        startedAt: firstEventAt,
+        lastEventAt: firstEventAt,
+        totalTokens: 0,
+        totalCacheRead: 0,
+        spawnCount: 0,
+        maxDepth: 0,
+        activeMinutes: 0,
+        tokensByActiveMinute: new Map(),
+        spawnsByActiveMinute: new Map(),
+        surfaceReaders: new Map(),
+        burnDebt: 0,
+        lastDebtEventAt: firstEventAt,
+    };
+}
+/** Apply one event. Returns the active minutes that elapsed for debt accounting. */
+function applyEvent(state, event) {
+    const gap = Math.max(0, event.at - state.lastEventAt);
+    const activeGapMs = Math.min(gap, defaults_1.ACTIVE_GAP_CAP_MS);
+    const activeGapMinutes = activeGapMs / 60_000;
+    state.activeMinutes += activeGapMinutes;
+    state.lastEventAt = Math.max(state.lastEventAt, event.at);
+    const bucket = Math.floor(state.activeMinutes);
+    state.totalTokens += event.tokens;
+    state.totalCacheRead += event.cacheRead;
+    if (event.tokens > 0) {
+        state.tokensByActiveMinute.set(bucket, (state.tokensByActiveMinute.get(bucket) ?? 0) + event.tokens);
+    }
+    for (const spawn of event.spawns) {
+        state.spawnCount += 1;
+        state.spawnsByActiveMinute.set(bucket, (state.spawnsByActiveMinute.get(bucket) ?? 0) + 1);
+        // The child will live one level below the issuer.
+        state.maxDepth = Math.max(state.maxDepth, spawn.issuerDepth + 1);
+    }
+    for (const surface of event.surfaces) {
+        const readers = state.surfaceReaders.get(surface) ?? new Set();
+        // Attribute to the current spawn era: a cheap proxy for "distinct agent"
+        // that is honest about its imprecision. Duplicate work is WARN-only for
+        // exactly this reason.
+        readers.add(state.spawnCount);
+        state.surfaceReaders.set(surface, readers);
+    }
+    return activeGapMinutes;
+}
+/** Sum of a rolling window over the last N active minutes. */
+function windowSum(byMinute, activeMinutes, windowMinutes) {
+    const from = Math.max(0, Math.floor(activeMinutes) - windowMinutes);
+    let total = 0;
+    for (const [bucket, value] of byMinute) {
+        if (bucket >= from)
+            total += value;
+    }
+    return total;
+}
+/** Median of completed, nonzero active minutes. The current partial minute is excluded. */
+function medianCompletedMinute(state) {
+    const current = Math.floor(state.activeMinutes);
+    const values = [];
+    for (const [bucket, value] of state.tokensByActiveMinute) {
+        if (bucket < current && value > 0)
+            values.push(value);
+    }
+    if (values.length < 3)
+        return 0;
+    values.sort((a, b) => a - b);
+    const mid = Math.floor(values.length / 2);
+    return values.length % 2 ? values[mid] : (values[mid - 1] + values[mid]) / 2;
+}
+function cacheReadRatio(state) {
+    return state.totalTokens > 0 ? state.totalCacheRead / state.totalTokens : 0;
+}

package/dist/src/types.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Shared types for the burn detector.
+ *
+ * The core is host-agnostic on purpose. A Claude Code transcript, a Cursor hook
+ * payload, or raw API middleware each normalise into the same event stream and
+ * the same SessionState, so the detectors and the verdict logic are written
+ * once. That is the durable position: a single vendor will never monitor its
+ * competitors, so the policy layer has to sit above all of them.
+ */
+export type Verdict = 'OK' | 'WARN' | 'STOP';
+export type Detector = 'fanout' | 'sustained_burn' | 'burn_debt' | 'spawn_rate' | 'account' | 'duplicate_work';
+/** One normalised observation from a host transcript. */
+export interface BurnEvent {
+    /** Unix milliseconds. */
+    at: number;
+    /** All token classes summed. Zero for non-usage lines. */
+    tokens: number;
+    /** cache_read_input_tokens. Reported for explanation only, never a detector input. */
+    cacheRead: number;
+    /** Spawn descriptors emitted by this event, if any. */
+    spawns: SpawnEvent[];
+    /** Files or patterns read by this event, if any. */
+    surfaces: string[];
+    /** True when the host marks this line as belonging to a subagent. */
+    sidechain: boolean;
+    /** Host-supplied ids, used to reconstruct ancestry when present. */
+    uuid?: string;
+    parentUuid?: string;
+}
+export interface SpawnEvent {
+    description: string;
+    model?: string;
+    /** Depth of the agent that issued the spawn. Root is 0. */
+    issuerDepth: number;
+}
+/**
+ * Live state for one session. Everything a detector needs is here, and nothing
+ * else: no prompt text, no response text, no file contents.
+ */
+export interface SessionState {
+    sessionId: string;
+    startedAt: number;
+    lastEventAt: number;
+    totalTokens: number;
+    totalCacheRead: number;
+    spawnCount: number;
+    maxDepth: number;
+    /** Active-time accounting. Gaps are capped so a resumed session does not
+     *  hide current activity behind hours of wall-clock idleness. */
+    activeMinutes: number;
+    /** Rolling windows keyed by active-minute bucket. */
+    tokensByActiveMinute: Map<number, number>;
+    spawnsByActiveMinute: Map<number, number>;
+    /** Surfaces read, with the set of spawn eras that read them. */
+    surfaceReaders: Map<string, Set<number>>;
+    /** Burn-debt accumulator, see detectors/sustained-burn.ts. */
+    burnDebt: number;
+    lastDebtEventAt: number;
+}
+export interface Finding {
+    detector: Detector;
+    verdict: Verdict;
+    /** Short, factual, no advice. Advice lives in prescriptions. */
+    summary: string;
+    observed: number;
+    threshold: number;
+}
+export interface BurnReport {
+    sessionId: string;
+    verdict: Verdict;
+    findings: Finding[];
+    prescriptions: string[];
+    /** Explanation only. Shown to the user, never used to decide. */
+    cacheReadRatio: number;
+    totals: {
+        tokens: number;
+        spawns: number;
+        maxDepth: number;
+        activeMinutes: number;
+    };
+}
+export interface Thresholds {
+    fanout: {
+        warn: number;
+        stop: number;
+        maxDepth: number;
+    };
+    sustained: {
+        warnTokens: number;
+        stopTokens: number;
+    };
+    burnDebt: {
+        /** Tokens per active minute the user is "allowed" before debt accrues. */
+        baselinePerActiveMinute: number;
+        tolerance: number;
+        warnDebt: number;
+        stopDebt: number;
+        /** Debt is not evaluated until calibration has produced a baseline. */
+        enabled: boolean;
+    };
+    spawnRate: {
+        windowActiveMinutes: number;
+        warn: number;
+        stop: number;
+        enforce: boolean;
+    };
+    duplicate: {
+        warnReaders: number;
+    };
+    account: {
+        /** No shipped default. The provider's real allowance is unknown to us. */
+        stopTokens: number | null;
+        warnTokens: number | null;
+        windowActiveMinutes: number;
+        warnConcurrentSessions: number;
+    };
+}
+export type Mode = 'shadow' | 'enforce';
+export interface Policy {
+    mode: Mode;
+    thresholds: Thresholds;
+    /** Calibration provenance, so a report can say where its numbers came from. */
+    calibration?: {
+        sessionsSampled: number;
+        generatedAt: number;
+        method: string;
+    };
+}

package/dist/src/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Shared types for the burn detector.
+ *
+ * The core is host-agnostic on purpose. A Claude Code transcript, a Cursor hook
+ * payload, or raw API middleware each normalise into the same event stream and
+ * the same SessionState, so the detectors and the verdict logic are written
+ * once. That is the durable position: a single vendor will never monitor its
+ * competitors, so the policy layer has to sit above all of them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@agentguard-run/burn",
+  "version": "0.1.0",
+  "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",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "bin": {
+    "agentguard-burn": "dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json && node --test \"dist/tests/**/*.test.js\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "replay": "node dist/cli.js replay"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "agentguard",
+    "claude-code",
+    "agents",
+    "token-budget",
+    "circuit-breaker",
+    "runaway",
+    "fan-out"
+  ]
+}