@agentguard-run/burn 0.2.2 → 0.2.5

package/dist/src/gateway.js

@@ -41,6 +41,7 @@ const pre_tool_use_1 = require("./hook/pre-tool-use");
 const override_1 = require("./override");
 const receipt_1 = require("./receipt");
 const reservations_1 = require("./state/reservations");
+const account_1 = require("./state/account");
 const session_1 = require("./state/session");
 const MAX_SEEN_EVENTS = 4000;
 const FILE_PREFIX = 'gw-';
@@ -49,6 +50,8 @@ function safeName(sessionId) {
 }
 class Gateway {
     home;
+    /** Shared local storage for optional content-free usage observations. */
+    get dataDirectory() { return this.home; }
     store;
     signer;
     now;
@@ -214,7 +217,7 @@ class Gateway {
                 }
                 const live = new Map(meta.liveSpawns);
                 const proposedDepth = event.proposedDepth ?? (event.issuerId !== undefined && live.has(event.issuerId) ? live.get(event.issuerId) + 1 : 1);
-                const report = (0, evaluate_1.evaluate)(state, policy.thresholds, proposedDepth);
+                const report = (0, evaluate_1.evaluate)(state, policy.thresholds, proposedDepth, { sessions: (0, account_1.readAccountSessions)(this.home, state, event.at), now: event.at });
                 const reservation = tx.reserve({
                     sessionId: event.sessionId,
                     toolUseId: event.spawnId,
@@ -264,13 +267,13 @@ class Gateway {
                     this.applyUsage(event.callId, event.estimatedTokens, 0, event.at, state, calls);
                 }
                 meta.calls = [...calls];
-                const session = (0, evaluate_1.evaluate)(state, policy.thresholds, null);
+                const session = (0, evaluate_1.evaluate)(state, policy.thresholds, null, { sessions: (0, account_1.readAccountSessions)(this.home, state, event.at), now: event.at });
                 const local = (0, local_compute_1.evaluateLocalCompute)(compute, policy.thresholds);
                 const report = merge(session, local.findings);
                 const wouldBlock = report.verdict === 'STOP';
                 // A low-confidence session (proxy without a session header) can be
                 // stopped only on machine-scope grounds. Its session count is a guess.
-                const machineStop = local.verdict === 'STOP';
+                const machineStop = local.verdict === 'STOP' || session.findings.some((f) => f.detector === 'account' && f.verdict === 'STOP');
                 const due = wouldBlock && policy.mode === 'enforce' && (event.attribution === 'high' || machineStop);
                 const override = due ? (0, override_1.consumeOverride)(this.home, event.at) : null;
                 const blocked = due && !override;

package/dist/src/hook/pre-tool-use.d.ts

@@ -49,6 +49,8 @@ export interface PersistedSession {
     };
     /** Signature of the last finding set the user was told about. */
     notified?: string;
+    /** Additive chain head; old session files begin at genesis. */
+    lastReceipt?: string | null;
 }
 /** Inflate a persisted Claude Code session. Shared with status. */
 export declare function inflateHookSession(raw: PersistedSession): SessionState;

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

@@ -22,6 +22,10 @@ exports.loadPolicy = loadPolicy;
 exports.refreshSession = refreshSession;
 exports.handlePreToolUse = handlePreToolUse;
 exports.settingsSnippet = settingsSnippet;
+const node_crypto_1 = require("node:crypto");
+const events_1 = require("../events");
+const receipt_1 = require("../receipt");
+const account_1 = require("../state/account");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const evaluate_1 = require("../detectors/evaluate");
@@ -31,6 +35,7 @@ const session_1 = require("../state/session");
 const defaults_1 = require("../defaults");
 const override_1 = require("../override");
 const render_1 = require("../replay/render");
+const live_1 = require("../insights/live");
 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`);
@@ -48,13 +53,13 @@ function loadSession(home, sessionId, firstEventAt) {
     try {
         const raw = JSON.parse((0, node_fs_1.readFileSync)(sessionFile(home, sessionId), 'utf8'));
         const cursor = { ...raw.cursor, depthByUuid: new Map(raw.cursor.depthByUuid) };
-        return { cursor, state: inflateHookSession(raw), notified: raw.notified ?? '' };
+        return { cursor, state: inflateHookSession(raw), notified: raw.notified ?? '', lastReceipt: raw.lastReceipt ?? null };
     }
     catch {
-        return { cursor: (0, claude_transcript_1.newCursor)(), state: (0, session_1.newSessionState)(sessionId, firstEventAt), notified: '' };
+        return { cursor: (0, claude_transcript_1.newCursor)(), state: (0, session_1.newSessionState)(sessionId, firstEventAt), notified: '', lastReceipt: null };
     }
 }
-function saveSession(home, cursor, state, notified) {
+function saveSession(home, cursor, state, notified, lastReceipt) {
     (0, node_fs_1.mkdirSync)((0, node_path_1.join)(home, 'sessions'), { recursive: true, mode: 0o700 });
     const persisted = {
         cursor: { offset: cursor.offset, size: cursor.size, malformedLines: cursor.malformedLines, depthByUuid: [...cursor.depthByUuid] },
@@ -65,6 +70,7 @@ function saveSession(home, cursor, state, notified) {
             surfaceReaders: [...state.surfaceReaders].map(([k, v]) => [k, [...v]]),
         },
         notified,
+        lastReceipt,
     };
     const file = sessionFile(home, state.sessionId);
     (0, node_fs_1.writeFileSync)(`${file}.tmp`, JSON.stringify(persisted), { mode: 0o600 });
@@ -99,14 +105,14 @@ function recordDecision(home, entry) {
 }
 /** Refresh session state from the transcript. Cheap: only new bytes are read. */
 function refreshSession(home, sessionId, transcriptPath) {
-    const { cursor, state, notified } = loadSession(home, sessionId, Date.now());
+    const { cursor, state, notified, lastReceipt } = loadSession(home, sessionId, Date.now());
     const before = state.spawnCount;
     const events = (0, claude_transcript_1.readIncremental)(transcriptPath, cursor);
     for (const event of events)
         (0, session_1.applyEvent)(state, event);
     if (events.length > 0 && state.startedAt > events[0].at)
         state.startedAt = events[0].at;
-    saveSession(home, cursor, state, notified);
+    saveSession(home, cursor, state, notified, lastReceipt);
     return { cursor, state, newSpawns: state.spawnCount - before, notified };
 }
 function rememberNotified(home, sessionId, signature) {
@@ -122,77 +128,101 @@ function rememberNotified(home, sessionId, signature) {
     }
 }
 function handlePreToolUse(input, home, now = Date.now()) {
+    const observation = (0, live_1.observeTool)(home, input, 'claude', loadPolicy(home), now);
+    const output = handleSpawnPreToolUse(input, home, now);
+    if (!observation.messages.length)
+        return output;
+    return { ...output, suppressOutput: false, systemMessage: [output.systemMessage, ...observation.messages].filter(Boolean).join('\n') };
+}
+function handleSpawnPreToolUse(input, home, now) {
     const toolName = input.tool_name ?? '';
     if (!SPAWN_TOOLS.has(toolName) || !input.session_id || !input.transcript_path) {
         return { continue: true, suppressOutput: true };
     }
     const policy = loadPolicy(home);
     const store = new reservations_1.ReservationStore(home);
-    let report;
-    let reservation;
-    let notified = '';
     try {
-        const refreshed = refreshSession(home, input.session_id, input.transcript_path);
-        const { state, newSpawns } = refreshed;
-        notified = refreshed.notified;
-        if (newSpawns > 0)
-            store.reconcile(input.session_id, state.spawnCount, state.spawnCount - newSpawns);
-        // Depth of the proposed child: the issuing agent's depth plus one. A hook
-        // fired inside a subagent carries agent_id; treat that as depth 1 issuer.
-        const proposedDepth = input.agent_id ? 2 : 1;
-        report = (0, evaluate_1.evaluate)(state, policy.thresholds, proposedDepth);
-        reservation = store.reserve({
-            sessionId: input.session_id,
-            toolUseId: input.tool_use_id ?? `${input.session_id}:${now}`,
-            observedSpawns: state.spawnCount,
-            ceiling: policy.thresholds.fanout.stop,
-            now,
+        const signer = receipt_1.ReceiptSigner.loadOrCreate(home);
+        return store.withLock((tx) => {
+            const refreshed = refreshSession(home, input.session_id, input.transcript_path);
+            const { state, newSpawns } = refreshed;
+            const notified = refreshed.notified;
+            if (newSpawns > 0)
+                tx.reconcile(input.session_id, state.spawnCount, state.spawnCount - newSpawns);
+            // Depth of the proposed child: the issuing agent's depth plus one. A hook
+            // fired inside a subagent carries agent_id; treat that as depth 1 issuer.
+            const proposedDepth = input.agent_id ? 2 : 1;
+            const report = (0, evaluate_1.evaluate)(state, policy.thresholds, proposedDepth, { sessions: (0, account_1.readAccountSessions)(home, state, now), now });
+            const reservation = tx.reserve({
+                sessionId: input.session_id,
+                toolUseId: input.tool_use_id ?? `${input.session_id}:${now}`,
+                observedSpawns: state.spawnCount,
+                ceiling: policy.thresholds.fanout.stop,
+                now,
+            });
+            const shouldDeny = report.verdict === 'STOP' || !reservation.allowed;
+            const reason = shouldDeny ? buildDenyReason(report, reservation) : '';
+            // The audited override: only consulted when a block is about to happen.
+            const override = shouldDeny && policy.mode === 'enforce' ? (0, override_1.consumeOverride)(home, now) : null;
+            const blocked = policy.mode === 'enforce' && shouldDeny && !override;
+            const verdict = shouldDeny ? 'STOP' : report.verdict;
+            const raw = JSON.parse((0, node_fs_1.readFileSync)(sessionFile(home, input.session_id), 'utf8'));
+            const receipt = signer.sign({
+                schema: 'agentguard.burn.decision.v1', decisionId: (0, node_crypto_1.randomUUID)(), at: now,
+                host: 'claude-code', action: 'spawn', sessionDigest: (0, receipt_1.sha256)(input.session_id),
+                policy: { mode: policy.mode, digest: (0, receipt_1.sha256)((0, receipt_1.canonical)(policy)) },
+                measured: { sessionTokens: state.totalTokens, sessionSpawns: reservation.effectiveSpawns,
+                    proposedDepth, inFlight: 0, occupiedMs: 0 },
+                coverage: events_1.CAPABILITIES['claude-code'], verdict, blocked,
+                reasons: [...report.findings.map((f) => `${f.detector}:${f.verdict}`), ...(!reservation.allowed ? ['fanout:STOP'] : [])],
+                previous: raw.lastReceipt ?? null,
+            });
+            store.assertHeld();
+            (0, node_fs_1.appendFileSync)((0, node_path_1.join)(home, 'receipts.ndjson'), `${JSON.stringify(receipt)}\n`, { mode: 0o600 });
+            saveSession(home, refreshed.cursor, state, notified, (0, receipt_1.receiptDigest)(receipt));
+            recordDecision(home, {
+                host: 'claude-code', action: 'spawn',
+                at: now,
+                sessionId: input.session_id,
+                toolUseId: input.tool_use_id ?? null,
+                verdict,
+                wouldDeny: shouldDeny,
+                enforced: policy.mode === 'enforce' && shouldDeny && !override,
+                overridden: override ? { once: override.once, reason: override.reason } : undefined,
+                mode: policy.mode,
+                findings: report.findings.map((f) => ({ detector: f.detector, verdict: f.verdict, observed: f.observed, threshold: f.threshold })),
+                effectiveSpawns: reservation.effectiveSpawns,
+                totals: report.totals,
+            });
+            if (shouldDeny && policy.mode === 'enforce') {
+                if (!override)
+                    return deny(reason);
+                return {
+                    continue: true,
+                    systemMessage: `AgentGuard STOP overridden${override.once ? ' once' : ''} ("${override.reason}"): ${report.findings[0]?.summary ?? ''}`,
+                };
+            }
+            if (report.verdict !== 'OK') {
+                const signature = findingSignature(report);
+                if (signature === notified)
+                    return { continue: true, suppressOutput: true };
+                rememberNotified(home, input.session_id, signature);
+                return {
+                    continue: true,
+                    systemMessage: `AgentGuard ${report.verdict}${policy.mode === 'shadow' && shouldDeny ? ' (shadow: would have blocked)' : ''}: ${report.findings[0]?.summary ?? ''}`,
+                };
+            }
+            if (notified)
+                rememberNotified(home, input.session_id, '');
+            return { continue: true, suppressOutput: true };
         });
     }
     catch (error) {
         // Could not coordinate. Deny the spawn; never let a burst through blind.
         const reason = `AgentGuard failed closed: ${error instanceof Error ? error.message : 'unknown error'}`;
-        recordDecision(home, { at: now, sessionId: input.session_id, verdict: 'STOP', enforced: policy.mode === 'enforce', reason, failClosed: true });
+        recordDecision(home, { host: 'claude-code', action: 'spawn', at: now, sessionId: input.session_id, verdict: 'STOP', enforced: policy.mode === 'enforce', reason, failClosed: true });
         return policy.mode === 'enforce' ? deny(reason) : { continue: true, suppressOutput: true };
     }
-    const shouldDeny = report.verdict === 'STOP' || !reservation.allowed;
-    const reason = shouldDeny ? buildDenyReason(report, reservation) : '';
-    // The audited override: only consulted when a block is about to happen.
-    const override = shouldDeny && policy.mode === 'enforce' ? (0, override_1.consumeOverride)(home, now) : null;
-    recordDecision(home, {
-        at: now,
-        sessionId: input.session_id,
-        toolUseId: input.tool_use_id ?? null,
-        verdict: report.verdict,
-        wouldDeny: shouldDeny,
-        enforced: policy.mode === 'enforce' && shouldDeny && !override,
-        overridden: override ? { once: override.once, reason: override.reason } : undefined,
-        mode: policy.mode,
-        findings: report.findings.map((f) => ({ detector: f.detector, verdict: f.verdict, observed: f.observed, threshold: f.threshold })),
-        effectiveSpawns: reservation.effectiveSpawns,
-        totals: report.totals,
-    });
-    if (shouldDeny && policy.mode === 'enforce') {
-        if (!override)
-            return deny(reason);
-        return {
-            continue: true,
-            systemMessage: `AgentGuard STOP overridden${override.once ? ' once' : ''} ("${override.reason}"): ${report.findings[0]?.summary ?? ''}`,
-        };
-    }
-    if (report.verdict !== 'OK') {
-        const signature = findingSignature(report);
-        if (signature === notified)
-            return { continue: true, suppressOutput: true };
-        rememberNotified(home, input.session_id, signature);
-        return {
-            continue: true,
-            systemMessage: `AgentGuard ${report.verdict}${policy.mode === 'shadow' && shouldDeny ? ' (shadow: would have blocked)' : ''}: ${report.findings[0]?.summary ?? ''}`,
-        };
-    }
-    if (notified)
-        rememberNotified(home, input.session_id, '');
-    return { continue: true, suppressOutput: true };
 }
 function buildDenyReason(report, _reservation) {
     // Claude Code shows this reason to the user. A box reads as an alarm; a
@@ -209,7 +239,7 @@ function deny(reason) {
 function settingsSnippet(command) {
     return {
         hooks: {
-            PreToolUse: [{ matcher: '^(Agent|Task)$', hooks: [{ type: 'command', command, timeout: 5 }] }],
+            PreToolUse: [{ matcher: '.*', hooks: [{ type: 'command', command, timeout: 15 }] }],
         },
     };
 }

package/dist/src/insights/attribution.d.ts

@@ -0,0 +1,4 @@
+import { type AttributionSummary, type InsightTurn, type RewriteEvidence } from './types';
+export declare function classifyRewrite(turn: InsightTurn): RewriteEvidence | null;
+/** Partition measured usage; byte lengths only divide a measured increment among its recorded events. */
+export declare function attributeTurns(turns: InsightTurn[]): AttributionSummary;

package/dist/src/insights/attribution.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyRewrite = classifyRewrite;
+exports.attributeTurns = attributeTurns;
+const types_1 = require("./types");
+const transcript_1 = require("./transcript");
+function classifyRewrite(turn) {
+    if (!(turn.cacheWriteTokens > 150_000 && turn.cacheWriteTokens > turn.contextTokens / 2))
+        return null;
+    const idleMs = turn.signals.idleMs;
+    const ttl = turn.cacheTtlSeconds;
+    const evidence = { turnId: turn.id, cacheWriteTokens: turn.cacheWriteTokens, contextTokens: turn.contextTokens,
+        ...(idleMs !== undefined ? { idleMs } : {}), idleOver60Minutes: idleMs !== undefined && idleMs > 3_600_000,
+        ...(ttl ? { ttlSeconds: ttl } : {}), ttlUnknown: !ttl };
+    if (ttl && idleMs !== undefined && idleMs > ttl * 1000)
+        return { ...evidence, cause: 'idle_ttl_expired', explanation: 'Idle gap exceeds the TTL reported for this cache-write class; timing is consistent with expiration.' };
+    if (turn.signals.afterCompaction)
+        return { ...evidence, cause: 'compaction', explanation: 'A compaction boundary immediately precedes this usage turn.' };
+    if (turn.signals.firstSpawnedTurn)
+        return { ...evidence, cause: 'first_spawned_turn', explanation: 'This is the first recorded usage turn in an explicitly identified subagent session.' };
+    if (!ttl)
+        return { ...evidence, cause: 'unknown_ttl', explanation: 'Cache TTL is absent or mixed; expiration cannot be distinguished from a prefix change.' };
+    return { ...evidence, cause: 'prefix_change', explanation: turn.signals.prefixChanged
+            ? 'The host reports a changed prefix identifier without an expired-TTL or compaction signal.'
+            : 'No expiration, compaction, or first-subagent-turn signal explains the rewrite; prefix change is a residual hypothesis, not an observed cause.' };
+}
+const tokenCategories = ['input', 'cacheCreation', 'cacheRead', 'output'];
+const emptyBuckets = () => types_1.INSIGHT_BUCKETS.map(bucket => ({ bucket, tokens: 0,
+    categories: { input: 0, cacheCreation: 0, cacheRead: 0, output: 0 } }));
+/** Largest remainders split an already measured token total without inventing tokens from bytes. */
+function integerShares(total, weights) {
+    const weight = weights.reduce((sum, value) => sum + value, 0);
+    if (!weight || !total)
+        return weights.map(() => 0);
+    const exact = weights.map(value => total * (value / weight));
+    const shares = exact.map(Math.floor);
+    const order = exact.map((value, index) => ({ index, remainder: value - shares[index] }))
+        .sort((a, b) => b.remainder - a.remainder || a.index - b.index);
+    for (let left = total - shares.reduce((sum, value) => sum + value, 0), i = 0; left > 0; left--, i++)
+        shares[order[i % order.length].index]++;
+    return shares;
+}
+/** Partition measured usage; byte lengths only divide a measured increment among its recorded events. */
+function attributeTurns(turns) {
+    const buckets = emptyBuckets();
+    const byBucket = new Map(buckets.map(bucket => [bucket.bucket, bucket]));
+    const result = { buckets, totalTokens: 0, rewrites: [],
+        rewriteCounts: { idle_ttl_expired: 0, compaction: 0, first_spawned_turn: 0, prefix_change: 0, unknown_ttl: 0 },
+        idleOver60MinuteRewrites: 0, uncertainties: [], turnAttributions: [], sharedTurns: 0,
+        prefixRebaselines: 0, previousOutputTokensReserved: 0 };
+    const uncertainties = new Set();
+    const sessions = new Map();
+    const ordered = (0, transcript_1.deduplicateTurns)(turns).sort((a, b) => (a.at ?? 0) - (b.at ?? 0));
+    for (const turn of ordered) {
+        const remaining = { input: turn.inputTokens, cacheCreation: turn.cacheWriteTokens, cacheRead: turn.cacheReadTokens, output: turn.outputTokens };
+        const turnBuckets = emptyBuckets();
+        const turnByBucket = new Map(turnBuckets.map(bucket => [bucket.bucket, bucket]));
+        const totalTokens = Object.values(remaining).reduce((sum, value) => sum + value, 0);
+        result.totalTokens += totalTokens;
+        const allocate = (bucket, category, tokens) => {
+            const amount = Math.min(remaining[category], Math.max(0, tokens));
+            if (amount < tokens)
+                uncertainties.add('attribution_evidence_exceeds_category_total');
+            for (const target of [byBucket.get(bucket), turnByBucket.get(bucket)]) {
+                target.tokens += amount;
+                target.categories[category] += amount;
+            }
+            remaining[category] -= amount;
+        };
+        const previous = sessions.get(turn.sessionId);
+        let prefix = previous?.prefix ?? turn.contextTokens;
+        allocate('output', 'output', remaining.output);
+        const rewrite = classifyRewrite(turn);
+        if (rewrite) {
+            result.rewrites.push(rewrite);
+            result.rewriteCounts[rewrite.cause]++;
+            if (rewrite.idleOver60Minutes)
+                result.idleOver60MinuteRewrites++;
+            allocate('full_prefix_rewrites', 'cacheCreation', remaining.cacheCreation);
+            if (rewrite.ttlUnknown)
+                uncertainties.add('rewrite_ttl_unknown');
+            if (rewrite.cause === 'prefix_change') {
+                prefix = turn.contextTokens;
+                if (previous)
+                    result.prefixRebaselines++;
+                if (!turn.signals.prefixChanged)
+                    uncertainties.add('prefix_change_is_residual_hypothesis');
+            }
+        }
+        for (const item of turn.explicitAttribution) {
+            if (item.bucket !== 'output' && item.bucket !== 'full_prefix_rewrites' && item.bucket !== 'unattributed' && Number.isSafeInteger(item.tokens) && item.tokens > 0)
+                allocate(item.bucket, item.category, item.tokens);
+        }
+        if (turn.subagent) {
+            for (const category of ['input', 'cacheCreation', 'cacheRead'])
+                allocate('subagent_fanout', category, remaining[category]);
+        }
+        else if (!turn.explicitAttribution.length) {
+            if (!previous || rewrite?.cause === 'prefix_change') {
+                // Rewrites retain their measured write tokens; the rest establishes the new fixed prefix.
+                for (const category of ['input', 'cacheCreation', 'cacheRead'])
+                    allocate('instruction_stack', category, remaining[category]);
+            }
+            else {
+                const history = Math.max(0, turn.cacheReadTokens - prefix);
+                allocate('instruction_stack', 'cacheRead', Math.min(remaining.cacheRead, prefix));
+                allocate('history_resent', 'cacheRead', Math.min(remaining.cacheRead, history));
+                if (!rewrite) {
+                    // Prior assistant output reappears in input usage but is not newly arrived content.
+                    // Keep that measured input in the residual rather than count it as generated output twice.
+                    let reserved = Math.min(previous.previousOutput, remaining.input + remaining.cacheCreation);
+                    result.previousOutputTokensReserved += reserved;
+                    for (const category of ['input', 'cacheCreation']) {
+                        const amount = Math.min(reserved, remaining[category]);
+                        allocate('unattributed', category, amount);
+                        reserved -= amount;
+                    }
+                    const interval = turn.interval;
+                    const eventBuckets = ['tool_output', 'reread_files', 'conversation'];
+                    let weights = interval ? [interval.toolOutputBytes, interval.reReadBytes, interval.conversationBytes] : [0, 0, 0];
+                    if (interval && !weights.some(value => value > 0)) {
+                        // A sole event class owns the whole measured increment even for an
+                        // empty result; mixed empty payloads have no byte-based split.
+                        const present = [interval.toolResults > (interval.reReadResults ?? 0), (interval.reReadResults ?? 0) > 0, interval.userMessages > 0];
+                        if (present.filter(Boolean).length === 1)
+                            weights = present.map(value => value ? 1 : 0);
+                    }
+                    if (weights.some(value => value > 0)) {
+                        const shares = integerShares(remaining.input + remaining.cacheCreation, weights);
+                        const inputs = integerShares(remaining.input, shares);
+                        if (interval.shared && shares.some(value => value > 0))
+                            result.sharedTurns++;
+                        eventBuckets.forEach((bucket, i) => {
+                            allocate(bucket, 'input', inputs[i]);
+                            allocate(bucket, 'cacheCreation', shares[i] - inputs[i]);
+                        });
+                    }
+                }
+            }
+        }
+        for (const category of tokenCategories)
+            allocate('unattributed', category, remaining[category]);
+        turn.uncertainties.forEach(value => uncertainties.add(value));
+        sessions.set(turn.sessionId, { prefix, previousOutput: turn.outputTokens });
+        result.turnAttributions.push({ turnId: turn.id, sessionId: turn.sessionId, buckets: turnBuckets, totalTokens });
+    }
+    if (byBucket.get('unattributed').tokens)
+        uncertainties.add('unattributed_usage_includes_prior_output_and_missing_event_evidence');
+    result.uncertainties = [...uncertainties].sort();
+    return result;
+}

package/dist/src/insights/live.d.ts

@@ -0,0 +1,53 @@
+import type { Policy } from '../types';
+import type { InsightHost, InsightParserState, InsightTurn } from './types';
+import { type PricingTable } from './pricing';
+import { type Pace, type UsageWindow, type LimitForecast } from './pace';
+export interface InsightSettings {
+    rewriteWarnDollarsPerHour?: number;
+    heavyTurnTokens?: number;
+    pricingFile?: string;
+}
+export interface LiveSnapshot {
+    schema: 1;
+    host: InsightHost;
+    sessionId: string;
+    updatedAt: number;
+    toolEvents: number;
+    cursor: {
+        offset: number;
+        inode: number;
+        pathDigest: string;
+    };
+    parser?: InsightParserState;
+    pace: Pace;
+    windows: UsageWindow[];
+    forecast: LimitForecast;
+    lastTurnTokens: number;
+    rewriteDollarsToday: {
+        min: number;
+        max: number;
+    } | null;
+    unpricedRewritesToday: number;
+    heavyAbove: boolean;
+    rewriteAbove: boolean;
+}
+export interface LiveInput {
+    session_id?: string;
+    transcript_path?: string;
+    tool_name?: string;
+    rate_limits?: unknown;
+}
+export declare function pacePath(home: string, sessionId: string): string;
+export declare function readPricing(home: string, policy?: Policy): PricingTable;
+export declare function dollars(value: {
+    min: number;
+    max: number;
+} | null): string;
+export declare function hostWindows(value: unknown, source: UsageWindow['source'], at: number): UsageWindow[];
+export declare function heavyTurnMessage(turn: InsightTurn, rates: PricingTable): string;
+/** Local advisory observer. No tool input or output content enters this API. */
+export declare function observeTool(home: string, input: LiveInput, host: InsightHost, policy: Policy, now?: number): {
+    snapshot?: LiveSnapshot;
+    messages: string[];
+};
+export declare function renderStatusLine(snapshot: LiveSnapshot): string;