@agentguard-run/burn 0.1.1 → 0.2.0

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' },
+};

package/dist/src/gateway.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The gateway: one transaction boundary for every host.
+ *
+ * Adapters do not evaluate policy. They translate what they can see into
+ * AgentEvents and hand them here. The gateway folds events into per-session
+ * state, evaluates the same detectors the Claude hook uses, and returns a
+ * decision. Cursor, Codex, the Ollama proxy and raw middleware therefore
+ * cannot drift from each other, because there is nothing host-specific left
+ * to drift.
+ *
+ * Three properties are load-bearing:
+ *
+ *   1. A spawn is admitted inside the same machine-wide lock the Claude hook
+ *      uses, as one transaction: fold, evaluate, reserve, sign. Ten parallel
+ *      Cursor hooks racing a cap of 40 admit exactly 40, for exactly the
+ *      reason ten Claude hooks do.
+ *
+ *   2. Usage is committed by call ID and *replaces* what was reserved under
+ *      it. When middleware estimated 120K and the proxy later saw 87K for the
+ *      same call, the session moves by 87K, not 207K. Double counting is the
+ *      easiest way to make a cross-tool product lie, and it is ruled out here
+ *      rather than in every adapter.
+ *
+ *   3. A STOP blocks the next expansion. It never truncates a request that is
+ *      already streaming and never kills a running agent. Blocking is not
+ *      killing, and the product does not pretend otherwise.
+ *
+ * Persisted state is content-free: counts, digests, verdicts.
+ */
+import { type AgentEvent, type Attribution, type CallRequested, type Coverage, type HostCapabilities, type HostId, type SpawnRequested } from './events';
+import { type SignedReceipt } from './receipt';
+import { type ComputeSnapshot } from './state/reservations';
+import type { BurnReport, Mode, SessionState, Verdict } from './types';
+export interface Decision {
+    decisionId: string;
+    action: 'spawn' | 'model_call';
+    verdict: Verdict;
+    /** The policy would block this if enforcing. */
+    wouldBlock: boolean;
+    /** Enforcing, and blocking. */
+    blocked: boolean;
+    mode: Mode;
+    report: BurnReport;
+    capabilities: HostCapabilities;
+    effectiveSpawns: number;
+    /** Depth the child would have. Null for model calls. */
+    proposedDepth: number | null;
+    compute: ComputeSnapshot | null;
+    receipt: SignedReceipt | null;
+    /** Set when the decision was forced by an infrastructure failure. */
+    failedClosed?: string;
+}
+export interface UsageCoverage {
+    authoritative: number;
+    estimated: number;
+    missing: number;
+}
+export interface GatewaySessionView {
+    sessionId: string;
+    hosts: HostId[];
+    capabilities: HostCapabilities;
+    state: SessionState;
+    liveSpawns: number;
+    usage: UsageCoverage;
+    decisions: number;
+    wouldBlock: number;
+    closedAt: number | null;
+}
+export interface GatewayOptions {
+    /** Sign receipts. On by default; off keeps tests and hot paths key-free. */
+    sign?: boolean;
+    now?: () => number;
+}
+export declare class Gateway {
+    private readonly home;
+    private readonly store;
+    private readonly signer;
+    private readonly now;
+    private readonly sessionsDir;
+    constructor(home: string, opts?: GatewayOptions);
+    private file;
+    private load;
+    private save;
+    /**
+     * Fold observations. Never decides, never blocks. Idempotent per eventId,
+     * so a retried hook or a replayed transcript line is a no-op.
+     */
+    observe(events: AgentEvent[]): void;
+    private fold;
+    /**
+     * Replace-not-add by call ID. An estimate reserved by middleware is
+     * superseded by the proxy's authoritative count for the same call, up or
+     * down. Without a call ID the usage is simply added.
+     */
+    private applyUsage;
+    private commitUsage;
+    /**
+     * Admit or deny a spawn. One transaction under the machine lock: fold,
+     * evaluate the proposal, reserve, sign.
+     */
+    beforeSpawn(event: SpawnRequested): Decision;
+    /**
+     * Admit or deny a model call. Reserves the caller's estimate under callId;
+     * completion replaces it. The local-compute plane is evaluated here and
+     * only here, because only calls occupy the machine.
+     */
+    beforeCall(event: CallRequested): Decision;
+    /** Real usage for a reserved call. Replaces the estimate; releases the slot. */
+    completeCall(args: {
+        host: HostId;
+        sessionId: string;
+        callId: string;
+        tokens: number;
+        cacheRead?: number;
+        usageCoverage: Coverage;
+        at?: number;
+    }): void;
+    /** The call never produced usage. Releases the estimate and the slot. */
+    failCall(args: {
+        host: HostId;
+        sessionId: string;
+        callId: string;
+        at?: number;
+    }): void;
+    private finish;
+    private failClosed;
+    peek(sessionId: string): GatewaySessionView | null;
+    /** Every gateway session on this machine, newest activity first. */
+    sessions(): GatewaySessionView[];
+    compute(sessionId?: string): ComputeSnapshot;
+}
+/** A session fed by several hosts sees the best coverage any of them provides. */
+export declare function mergeCapabilities(hosts: HostId[]): HostCapabilities;
+export type { Attribution };