@agentguard-run/burn 0.1.1 → 0.2.1

package/dist/src/conformance.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * Conformance: the same failure, through every door, stops at the same step.
+ *
+ * Two fixtures, fitted on real sessions:
+ *
+ *   the storm   42 candidate spawns. First WARN must be spawn 24, first STOP
+ *               must be spawn 41. Every spawn-capable adapter replays it.
+ *   the grind   model calls of 250M tokens each. First WARN must be the call
+ *               after 3.5B, first STOP the call after 5B. Every usage-capable
+ *               adapter replays it.
+ *   composite   raw middleware supplies the spawns, the proxy supplies the
+ *               usage, one session ID. Candidate spawn 41 must see BOTH
+ *               planes in its findings. That is the claim on the box.
+ *
+ * Runs in a throwaway home in enforce mode. Nothing here touches ~/.agentguard.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runConformance = runConformance;
+const node_http_1 = require("node:http");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const codex_1 = require("./adapters/codex");
+const cursor_1 = require("./adapters/cursor");
+const raw_api_1 = require("./adapters/raw-api");
+const defaults_1 = require("./defaults");
+const events_1 = require("./events");
+const gateway_1 = require("./gateway");
+const server_1 = require("./proxy/server");
+const receipt_1 = require("./receipt");
+const STORM = 42;
+const WARN_AT = defaults_1.DEFAULT_THRESHOLDS.fanout.warn; // 24
+const STOP_AT = defaults_1.DEFAULT_THRESHOLDS.fanout.stop + 1; // 41
+const CALL_TOKENS = 250_000_000;
+const GRIND_WARN_CALL = Math.floor(defaults_1.DEFAULT_THRESHOLDS.sustained.warnTokens / CALL_TOKENS) + 1; // 15
+const GRIND_STOP_CALL = Math.floor(defaults_1.DEFAULT_THRESHOLDS.sustained.stopTokens / CALL_TOKENS) + 1; // 21
+function freshHome() {
+    const home = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'agb-conf-'));
+    const policy = { mode: 'enforce', thresholds: defaults_1.DEFAULT_THRESHOLDS };
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(home, 'burn-policy.json'), JSON.stringify(policy));
+    return home;
+}
+function boundaries(steps) {
+    const w = steps.findIndex((v) => v === 'WARN');
+    const a = steps.findIndex((v) => v === 'WARN' || v === 'WARN:other');
+    const s = steps.findIndex((v) => v === 'STOP');
+    return { firstWarn: w < 0 ? null : w + 1, firstStop: s < 0 ? null : s + 1, firstAnyWarn: a < 0 ? null : a + 1 };
+}
+// Hook adapters only expose the first finding's summary. Fan-out is evaluated
+// first in the core, so when it fires it is the one in the message.
+const FANOUT_WARN = /agent spawns this session/;
+function stepFromMessage(denied, message, warnPattern) {
+    if (denied)
+        return 'STOP';
+    if (!message || !message.includes('WARN'))
+        return 'OK';
+    return warnPattern.test(message) ? 'WARN' : 'WARN:other';
+}
+// ---- storms --------------------------------------------------------------
+function stormRaw(home) {
+    const burn = (0, raw_api_1.createRawApiGuard)({ sessionId: 'storm-raw', home });
+    const steps = [];
+    for (let i = 1; i <= STORM; i++) {
+        const lease = burn.beforeSpawn({ parentDepth: 0 });
+        const d = lease.decision;
+        const fanout = d.report.findings.find((f) => f.detector === 'fanout');
+        steps.push(d.blocked ? 'STOP' : fanout?.verdict === 'WARN' ? 'WARN' : d.verdict === 'WARN' ? 'WARN:other' : 'OK');
+        if (!d.blocked)
+            lease.started();
+    }
+    return boundaries(steps);
+}
+function stormCursor(home) {
+    const gateway = new gateway_1.Gateway(home);
+    const steps = [];
+    for (let i = 1; i <= STORM; i++) {
+        const out = (0, cursor_1.handleCursorHook)({ hook_event_name: 'subagentStart', conversation_id: 'storm-cursor', subagent_id: `sub-${i}`, parent_conversation_id: 'storm-cursor' }, gateway);
+        steps.push(stepFromMessage(out.permission === 'deny', out.agent_message, FANOUT_WARN));
+    }
+    return boundaries(steps);
+}
+function stormCodex(home) {
+    const gateway = new gateway_1.Gateway(home);
+    const steps = [];
+    for (let i = 1; i <= STORM; i++) {
+        const out = (0, codex_1.handleCodexHook)({ hook_event_name: 'PreToolUse', session_id: 'storm-codex', tool_name: 'Agent', tool_use_id: `call-${i}` }, gateway);
+        steps.push(stepFromMessage(out.hookSpecificOutput?.permissionDecision === 'deny', out.systemMessage, FANOUT_WARN));
+    }
+    return boundaries(steps);
+}
+function depthRaw(home) {
+    const burn = (0, raw_api_1.createRawApiGuard)({ sessionId: 'depth-raw', home });
+    const ok1 = !burn.beforeSpawn({ parentDepth: 0 }).blocked;
+    const ok2 = !burn.beforeSpawn({ parentDepth: 1 }).blocked;
+    const denied3 = burn.beforeSpawn({ parentDepth: 2 }).blocked;
+    return ok1 && ok2 && denied3;
+}
+// ---- grinds --------------------------------------------------------------
+function grindRaw(home) {
+    const burn = (0, raw_api_1.createRawApiGuard)({ sessionId: 'grind-raw', home });
+    const steps = [];
+    for (let i = 1; i <= GRIND_STOP_CALL + 1; i++) {
+        const call = burn.beforeCall({ estimatedTokens: 1_000 });
+        const d = call.decision;
+        const sustained = d.report.findings.find((f) => f.detector === 'sustained_burn');
+        steps.push(d.blocked ? 'STOP' : sustained?.verdict === 'WARN' ? 'WARN' : d.verdict === 'WARN' ? 'WARN:other' : 'OK');
+        if (d.blocked)
+            break;
+        call.complete({ tokens: CALL_TOKENS });
+    }
+    return boundaries(steps);
+}
+/** A stand-in Ollama: streams a few NDJSON chunks then the final counts. */
+function fakeOllama(tokensPerCall) {
+    const bodies = [];
+    const server = (0, node_http_1.createServer)((req, res) => {
+        req.resume();
+        req.on('end', () => {
+            res.writeHead(200, { 'content-type': 'application/x-ndjson' });
+            const parts = [
+                JSON.stringify({ model: 'test', message: { role: 'assistant', content: 'hel' }, done: false }),
+                JSON.stringify({ model: 'test', message: { role: 'assistant', content: 'lo' }, done: false }),
+                JSON.stringify({ model: 'test', done: true, prompt_eval_count: tokensPerCall - 7, eval_count: 7 }),
+            ];
+            const body = parts.join('\n') + '\n';
+            bodies.push(body);
+            let i = 0;
+            const tick = () => {
+                if (i < parts.length) {
+                    res.write(parts[i++] + '\n');
+                    setTimeout(tick, 2);
+                }
+                else
+                    res.end();
+            };
+            tick();
+        });
+    });
+    return new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', () => {
+            const a = server.address();
+            resolve({ server, url: new URL(`http://127.0.0.1:${a.port}`), bodies });
+        });
+    });
+}
+function post(url, path, headers) {
+    return new Promise((resolve, reject) => {
+        const req = (0, node_http_1.request)({ hostname: url.hostname, port: url.port, path, method: 'POST', headers: { 'content-type': 'application/json', ...headers } }, (res) => {
+            let body = '';
+            res.on('data', (d) => (body += d.toString()));
+            res.on('end', () => resolve({ status: res.statusCode ?? 0, body, headers: res.headers }));
+        });
+        req.on('error', reject);
+        req.end(JSON.stringify({ model: 'test', messages: [{ role: 'user', content: 'x' }] }));
+    });
+}
+async function grindProxy(home, sessionId = 'grind-proxy') {
+    const upstream = await fakeOllama(CALL_TOKENS);
+    const gateway = new gateway_1.Gateway(home);
+    const proxy = await (0, server_1.startProxy)({ upstream: upstream.url, gateway, host: 'ollama' });
+    const steps = [];
+    let byteIdentical = true;
+    let stopBody = '';
+    try {
+        for (let i = 1; i <= GRIND_STOP_CALL + 1; i++) {
+            const r = await post(proxy.address, '/api/chat', { [events_1.SESSION_HEADER]: sessionId, [events_1.CALL_HEADER]: `${sessionId}-${i}` });
+            if (r.status === 429) {
+                steps.push('STOP');
+                stopBody = r.body;
+                break;
+            }
+            // The proxy only exposes the verdict header on the wire, so the grind
+            // through the proxy is checked on verdict; the raw grind above proves
+            // the detector. No spawns happen here, so no advisory WARN can fire.
+            const v = r.headers['x-agentguard-verdict'];
+            steps.push(v === 'WARN' ? 'WARN' : 'OK');
+            if (r.body !== upstream.bodies[upstream.bodies.length - 1])
+                byteIdentical = false;
+        }
+    }
+    finally {
+        await proxy.close();
+        upstream.server.close();
+    }
+    return { ...boundaries(steps), byteIdentical, stopBody };
+}
+// ---- composite -----------------------------------------------------------
+async function composite(home) {
+    // Proxy supplies usage: 14 calls = 3.5B, so the session is in WARN territory.
+    const upstream = await fakeOllama(CALL_TOKENS);
+    const gateway = new gateway_1.Gateway(home);
+    const proxy = await (0, server_1.startProxy)({ upstream: upstream.url, gateway, host: 'ollama' });
+    try {
+        for (let i = 1; i <= GRIND_WARN_CALL - 1; i++)
+            await post(proxy.address, '/api/chat', { [events_1.SESSION_HEADER]: 'composite', [events_1.CALL_HEADER]: `c-${i}` });
+    }
+    finally {
+        await proxy.close();
+        upstream.server.close();
+    }
+    // Middleware supplies the tree on the same session ID.
+    const burn = (0, raw_api_1.createRawApiGuard)({ sessionId: 'composite', home });
+    let last = burn.beforeSpawn({ parentDepth: 0 });
+    for (let i = 1; i <= STOP_AT; i++) {
+        last = burn.beforeSpawn({ parentDepth: 0 });
+        if (!last.blocked)
+            last.started();
+    }
+    const detectors = new Set(last.decision.report.findings.map((f) => f.detector));
+    const view = gateway.peek('composite');
+    const hosts = view?.hosts.join('+') ?? '';
+    const ok = last.blocked && detectors.has('fanout') && detectors.has('sustained_burn') && view?.capabilities.usage === 'authoritative' && view?.capabilities.spawns === 'authoritative';
+    return {
+        ok,
+        detail: `spawn 41 ${last.blocked ? 'denied' : 'ALLOWED'}; findings ${[...detectors].join(',')}; hosts ${hosts}; coverage spawns:${view?.capabilities.spawns} usage:${view?.capabilities.usage}; tokens ${((view?.state.totalTokens ?? 0) / 1e9).toFixed(2)}B`,
+    };
+}
+// ---- runner --------------------------------------------------------------
+async function runConformance() {
+    const home = freshHome();
+    const checks = [];
+    const expectStorm = (name, b) => checks.push({
+        name,
+        ok: b.firstWarn === WARN_AT && b.firstStop === STOP_AT,
+        detail: `fan-out WARN at ${b.firstWarn} (want ${WARN_AT}), STOP at ${b.firstStop} (want ${STOP_AT})${b.firstAnyWarn !== null && b.firstAnyWarn < WARN_AT ? `; advisory spawn-rate WARN at ${b.firstAnyWarn}` : ''}`,
+    });
+    const expectGrind = (name, b) => checks.push({ name, ok: b.firstWarn === GRIND_WARN_CALL && b.firstStop === GRIND_STOP_CALL, detail: `first WARN call ${b.firstWarn} (want ${GRIND_WARN_CALL}), first STOP call ${b.firstStop} (want ${GRIND_STOP_CALL})` });
+    try {
+        expectStorm('storm · raw middleware', stormRaw(home));
+        expectStorm('storm · cursor subagentStart', stormCursor(home));
+        expectStorm('storm · codex PreToolUse', stormCodex(home));
+        checks.push({ name: 'depth · raw middleware', ok: depthRaw(home), detail: 'depth 1 and 2 admitted, depth 3 denied' });
+        expectGrind('grind · raw middleware', grindRaw(home));
+        const p = await grindProxy(home);
+        expectGrind('grind · ollama proxy', p);
+        checks.push({ name: 'proxy · streamed bytes identical to upstream', ok: p.byteIdentical, detail: p.byteIdentical ? 'every streamed body matched upstream byte for byte' : 'MISMATCH' });
+        checks.push({ name: 'proxy · STOP answers 429 with the alarm box', ok: p.stopBody.includes('agentguard_burn_stop') && p.stopBody.includes('AGENTGUARD STOP'), detail: p.stopBody ? 'error.type=agentguard_burn_stop, box present' : 'no STOP body captured' });
+        const c = await composite(home);
+        checks.push({ name: 'composite · middleware tree + proxy usage, one session', ok: c.ok, detail: c.detail });
+        // Receipts: every spawn decision above was signed; verify the chain tail.
+        const receipts = require('node:fs')
+            .readFileSync((0, node_path_1.join)(home, 'receipts.ndjson'), 'utf8')
+            .split('\n')
+            .filter(Boolean)
+            .map((l) => JSON.parse(l));
+        const allValid = receipts.every((r) => (0, receipt_1.verifyReceipt)(r));
+        const contentFree = !receipts.some((r) => JSON.stringify(r.payload).match(/transcript|prompt|\/Users\/|content/i));
+        checks.push({ name: `receipts · ${receipts.length} signed, all verify, content-free`, ok: allValid && contentFree && receipts.length > 0, detail: `${receipts.length} receipts, verify=${allValid}, content-free=${contentFree}` });
+    }
+    finally {
+        (0, node_fs_1.rmSync)(home, { recursive: true, force: true });
+    }
+    const ok = checks.every((c) => c.ok);
+    const text = [
+        'AGENTGUARD conformance · same failure, every door, same step',
+        ...checks.map((c) => `  ${c.ok ? 'PASS' : 'FAIL'}  ${c.name.padEnd(52)} ${c.detail}`),
+        ok ? 'all adapters agree' : 'DISAGREEMENT: an adapter drifted from the core',
+    ].join('\n');
+    return { ok, text, checks };
+}

package/dist/src/defaults.d.ts

@@ -21,6 +21,17 @@ import type { Policy, Thresholds } from './types';
  * absent from these thresholds.
  */
 export declare const DEFAULT_THRESHOLDS: Thresholds;
+export declare const DEFAULT_LOCAL_COMPUTE: {
+    windowMs: number;
+    warnConcurrent: number;
+    stopConcurrent: number | null;
+    warnOccupiedMs: number | null;
+    stopOccupiedMs: number | null;
+};
+/** How long a model-call reservation may stay open before it is presumed dead. */
+export declare const CALL_RESERVATION_TTL_MS: number;
+/** Tokens assumed for a call whose caller gave no estimate. Replaced by the real count on completion. */
+export declare const DEFAULT_CALL_ESTIMATE_TOKENS = 0;
 /** First-run policy. Shadow: evaluate and record, never block. */
 export declare const DEFAULT_POLICY: Policy;
 /** Idle gaps longer than this do not count as active time. */

package/dist/src/defaults.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SHADOW_MIN_DAYS = exports.SHADOW_MIN_DECISIONS = exports.ACTIVE_GAP_CAP_MS = exports.DEFAULT_POLICY = exports.DEFAULT_THRESHOLDS = void 0;
+exports.SHADOW_MIN_DAYS = exports.SHADOW_MIN_DECISIONS = exports.ACTIVE_GAP_CAP_MS = exports.DEFAULT_POLICY = exports.DEFAULT_CALL_ESTIMATE_TOKENS = exports.CALL_RESERVATION_TTL_MS = exports.DEFAULT_LOCAL_COMPUTE = exports.DEFAULT_THRESHOLDS = void 0;
 /**
  * Shipped thresholds.
  *
@@ -40,7 +40,22 @@ exports.DEFAULT_THRESHOLDS = {
         windowActiveMinutes: 300,
         warnConcurrentSessions: 4,
     },
+    // Local model runtimes. Elapsed request time is not GPU utilisation (it
+    // includes queueing and transport), so it is called occupied time and it
+    // only warns unless the operator sets a ceiling for their own hardware.
+    localCompute: {
+        windowMs: 15 * 60 * 1000,
+        warnConcurrent: 4,
+        stopConcurrent: null,
+        warnOccupiedMs: null,
+        stopOccupiedMs: null,
+    },
 };
+exports.DEFAULT_LOCAL_COMPUTE = exports.DEFAULT_THRESHOLDS.localCompute;
+/** How long a model-call reservation may stay open before it is presumed dead. */
+exports.CALL_RESERVATION_TTL_MS = 30 * 60 * 1000;
+/** Tokens assumed for a call whose caller gave no estimate. Replaced by the real count on completion. */
+exports.DEFAULT_CALL_ESTIMATE_TOKENS = 0;
 /** First-run policy. Shadow: evaluate and record, never block. */
 exports.DEFAULT_POLICY = {
     mode: 'shadow',

package/dist/src/detectors/local-compute.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The local-compute plane.
+ *
+ * On a hosted API the loss is dollars, and the two session detectors in
+ * evaluate.ts cover it. On a local runtime the loss is different: the GPU is
+ * already paid for, so what a runaway costs you is the machine itself, wedged
+ * behind eight concurrent requests for an hour. Concurrency and occupied
+ * request time are the honest signals we can see from a proxy.
+ *
+ * This ships WARN-only. We cannot see the hardware, so a universal STOP would
+ * be a guess, and a guessed STOP is what gets a safety tool uninstalled.
+ * Operators who know their server set the ceilings in burn-policy.json.
+ */
+import type { ComputeSnapshot } from '../state/reservations';
+import type { Finding, Thresholds, Verdict } from '../types';
+export declare function evaluateLocalCompute(snapshot: ComputeSnapshot, thresholds: Thresholds): {
+    verdict: Verdict;
+    findings: Finding[];
+};

package/dist/src/detectors/local-compute.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * The local-compute plane.
+ *
+ * On a hosted API the loss is dollars, and the two session detectors in
+ * evaluate.ts cover it. On a local runtime the loss is different: the GPU is
+ * already paid for, so what a runaway costs you is the machine itself, wedged
+ * behind eight concurrent requests for an hour. Concurrency and occupied
+ * request time are the honest signals we can see from a proxy.
+ *
+ * This ships WARN-only. We cannot see the hardware, so a universal STOP would
+ * be a guess, and a guessed STOP is what gets a safety tool uninstalled.
+ * Operators who know their server set the ceilings in burn-policy.json.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateLocalCompute = evaluateLocalCompute;
+const defaults_1 = require("../defaults");
+function evaluateLocalCompute(snapshot, thresholds) {
+    const t = thresholds.localCompute ?? defaults_1.DEFAULT_LOCAL_COMPUTE;
+    const findings = [];
+    let verdict = 'OK';
+    const minutes = Math.round(snapshot.windowMs / 60_000);
+    // The candidate call is already reserved, so inFlight includes it.
+    if (t.stopConcurrent !== null && snapshot.inFlight > t.stopConcurrent) {
+        findings.push({
+            detector: 'local_compute',
+            verdict: 'STOP',
+            summary: `${snapshot.inFlight} model calls in flight on this machine; ceiling is ${t.stopConcurrent}.`,
+            observed: snapshot.inFlight,
+            threshold: t.stopConcurrent,
+        });
+        verdict = 'STOP';
+    }
+    else if (snapshot.inFlight >= t.warnConcurrent) {
+        findings.push({
+            detector: 'local_compute',
+            verdict: 'WARN',
+            summary: `${snapshot.inFlight} model calls in flight on this machine.`,
+            observed: snapshot.inFlight,
+            threshold: t.warnConcurrent,
+        });
+        verdict = 'WARN';
+    }
+    const occupiedSec = Math.round(snapshot.occupiedMs / 1000);
+    if (t.stopOccupiedMs !== null && snapshot.occupiedMs >= t.stopOccupiedMs) {
+        findings.push({
+            detector: 'local_compute',
+            verdict: 'STOP',
+            summary: `${occupiedSec}s of occupied request time in the last ${minutes} min; ceiling is ${Math.round(t.stopOccupiedMs / 1000)}s.`,
+            observed: snapshot.occupiedMs,
+            threshold: t.stopOccupiedMs,
+        });
+        verdict = 'STOP';
+    }
+    else if (t.warnOccupiedMs !== null && snapshot.occupiedMs >= t.warnOccupiedMs && verdict === 'OK') {
+        findings.push({
+            detector: 'local_compute',
+            verdict: 'WARN',
+            summary: `${occupiedSec}s of occupied request time in the last ${minutes} min.`,
+            observed: snapshot.occupiedMs,
+            threshold: t.warnOccupiedMs,
+        });
+        verdict = 'WARN';
+    }
+    return { verdict, findings };
+}

package/dist/src/events.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The host-neutral event vocabulary.
+ *
+ * Every adapter, whatever it can see, speaks this. A Cursor subagentStart
+ * hook, a Codex PreToolUse hook, an Ollama response through the proxy, and an
+ * orchestrator's beforeSpawn call all normalise into these shapes, and the
+ * detectors never learn which host produced them. That is the whole
+ * cross-tool claim in one file: one policy can only be enforced identically
+ * if the inputs are identical in kind.
+ *
+ * What is deliberately absent: prompts, completions, source code, transcript
+ * paths, raw tool arguments. Surfaces are digests. Session IDs are opaque.
+ *
+ * Coverage is part of correctness, not marketing. An adapter that cannot see
+ * a signal says so, so an OK verdict never masquerades as full visibility.
+ */
+export type HostId = 'claude-code' | 'cursor' | 'codex' | 'ollama' | 'vllm' | 'lm-studio' | 'openai-compatible' | 'raw-api';
+/** How much an adapter can actually see of each policy plane. */
+export type Coverage = 'authoritative' | 'estimated' | 'missing';
+export interface HostCapabilities {
+    spawns: Coverage;
+    depth: Coverage;
+    usage: Coverage;
+}
+/**
+ * How sure the adapter is that this event belongs to the session it names.
+ * A proxy request carrying x-agentguard-session is high. A proxy request
+ * identified only by client port is low, and a low-confidence session can
+ * never be hard-STOPped on session-scope grounds: reconnects fragment it.
+ */
+export type Attribution = 'high' | 'low';
+interface Base {
+    schemaVersion: 1;
+    eventId: string;
+    host: HostId;
+    /** Opaque logical session. Shared across hosts when the integration propagates it. */
+    sessionId: string;
+    at: number;
+}
+export interface SessionOpened extends Base {
+    kind: 'session_opened';
+    capabilities: HostCapabilities;
+}
+/** A model call is about to be made. Reserves the estimate under callId. */
+export interface CallRequested extends Base {
+    kind: 'call_requested';
+    callId: string;
+    estimatedTokens: number;
+    attribution: Attribution;
+}
+/** Usage was observed. With a callId it *replaces* that call's reservation. */
+export interface ModelUsageObserved extends Base {
+    kind: 'model_usage';
+    /** input + output. Cache-read is carried for explanation only. */
+    tokens: number;
+    cacheRead: number;
+    usageCoverage: Coverage;
+    callId?: string;
+}
+export interface ToolSurfaceRead extends Base {
+    kind: 'surface_read';
+    /** sha256 of the normalised path or pattern, never the path itself. */
+    surfaceDigest: string;
+}
+export interface SpawnRequested extends Base {
+    kind: 'spawn_requested';
+    spawnId: string;
+    /** Depth the child would have, when the host knows it. Root issuer proposes 1. */
+    proposedDepth?: number;
+    /** The agent issuing the spawn, when the host names it. Used to derive depth. */
+    issuerId?: string;
+    attribution: Attribution;
+}
+export interface SpawnStarted extends Base {
+    kind: 'spawn_started';
+    spawnId: string;
+    depth: number;
+}
+export interface SpawnFinished extends Base {
+    kind: 'spawn_finished';
+    spawnId: string;
+}
+export interface SessionClosed extends Base {
+    kind: 'session_closed';
+}
+export type AgentEvent = SessionOpened | CallRequested | ModelUsageObserved | ToolSurfaceRead | SpawnRequested | SpawnStarted | SpawnFinished | SessionClosed;
+/** Session IDs are propagated between hosts through these, and only these. */
+export declare const SESSION_HEADER = "x-agentguard-session";
+export declare const CALL_HEADER = "x-agentguard-call";
+export declare const SESSION_ENV = "AGENTGUARD_SESSION_ID";
+export declare function isValidSessionId(value: string): boolean;
+export declare function eventId(): string;
+export declare const CAPABILITIES: Record<HostId, HostCapabilities>;
+export {};

package/dist/src/events.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * The host-neutral event vocabulary.
+ *
+ * Every adapter, whatever it can see, speaks this. A Cursor subagentStart
+ * hook, a Codex PreToolUse hook, an Ollama response through the proxy, and an
+ * orchestrator's beforeSpawn call all normalise into these shapes, and the
+ * detectors never learn which host produced them. That is the whole
+ * cross-tool claim in one file: one policy can only be enforced identically
+ * if the inputs are identical in kind.
+ *
+ * What is deliberately absent: prompts, completions, source code, transcript
+ * paths, raw tool arguments. Surfaces are digests. Session IDs are opaque.
+ *
+ * Coverage is part of correctness, not marketing. An adapter that cannot see
+ * a signal says so, so an OK verdict never masquerades as full visibility.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPABILITIES = exports.SESSION_ENV = exports.CALL_HEADER = exports.SESSION_HEADER = void 0;
+exports.isValidSessionId = isValidSessionId;
+exports.eventId = eventId;
+/** Session IDs are propagated between hosts through these, and only these. */
+exports.SESSION_HEADER = 'x-agentguard-session';
+exports.CALL_HEADER = 'x-agentguard-call';
+exports.SESSION_ENV = 'AGENTGUARD_SESSION_ID';
+const SESSION_ID_RE = /^[A-Za-z0-9._:@/-]{1,256}$/;
+function isValidSessionId(value) {
+    return SESSION_ID_RE.test(value);
+}
+function eventId() {
+    // Node built-ins only. Time-ordered enough for dedupe, unique enough for logs.
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+exports.CAPABILITIES = {
+    'claude-code': { spawns: 'authoritative', depth: 'authoritative', usage: 'authoritative' },
+    // Cursor names the subagent and its parent; hosted-model usage is never exposed.
+    cursor: { spawns: 'authoritative', depth: 'estimated', usage: 'missing' },
+    // Codex gates spawn_agent through PreToolUse; the transcript is a locator, not a contract.
+    codex: { spawns: 'authoritative', depth: 'estimated', usage: 'estimated' },
+    // A proxy sees every token and no tree.
+    ollama: { spawns: 'missing', depth: 'missing', usage: 'authoritative' },
+    vllm: { spawns: 'missing', depth: 'missing', usage: 'authoritative' },
+    'lm-studio': { spawns: 'missing', depth: 'missing', usage: 'authoritative' },
+    'openai-compatible': { spawns: 'missing', depth: 'missing', usage: 'estimated' },
+    // The orchestrator knows everything, because it is the one doing it.
+    'raw-api': { spawns: 'authoritative', depth: 'authoritative', usage: 'authoritative' },
+};