@agentguard-run/burn 0.1.0 → 0.2.0

package/dist/src/proxy/server.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Local reverse proxy for model runtimes.
+ *
+ * Put it in front of Ollama, vLLM, LM Studio or anything OpenAI-compatible
+ * on the same machine, point the agent at it, and every request becomes a
+ * model-call decision under the same policy as every other host.
+ *
+ * What it does, in order:
+ *   1. Resolve the session: x-agentguard-session header (high confidence)
+ *      or remote port (low confidence; can never earn a session-scope STOP).
+ *   2. Ask the gateway to admit the call. A STOP answers 429 with the alarm
+ *      box before anything is forwarded. A STOP therefore blocks the *next*
+ *      request; it never cuts a stream that is already flowing.
+ *   3. Forward the request; stream every upstream chunk to the client BEFORE
+ *      the observer parses it, honouring backpressure.
+ *   4. On end, commit the observed usage under the call ID, which replaces
+ *      any estimate that raw middleware reserved for the same call.
+ *
+ * Loopback only, both sides, by default. Node built-ins only. No body is
+ * ever stored.
+ */
+import { type Server } from 'node:http';
+import { type HostId } from '../events';
+import type { Gateway } from '../gateway';
+import { type ProxyProfile } from './usage-observer';
+export type ProxyHost = Extract<HostId, 'ollama' | 'vllm' | 'lm-studio' | 'openai-compatible'>;
+export interface ProxyOptions {
+    upstream: URL;
+    gateway: Gateway;
+    host: ProxyHost;
+    listenHost?: string;
+    listenPort?: number;
+    /** Session for requests that carry no header. Default: per-client-port, low confidence. */
+    defaultSession?: string;
+    /** Allow a non-loopback upstream (a GPU box on the LAN). Off by default. */
+    allowRemoteUpstream?: boolean;
+    log?: (line: string) => void;
+}
+export interface RunningProxy {
+    server: Server;
+    address: URL;
+    close(): Promise<void>;
+}
+export declare function profileFor(host: ProxyHost): ProxyProfile;
+export declare function startProxy(opts: ProxyOptions): Promise<RunningProxy>;

package/dist/src/proxy/server.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Local reverse proxy for model runtimes.
+ *
+ * Put it in front of Ollama, vLLM, LM Studio or anything OpenAI-compatible
+ * on the same machine, point the agent at it, and every request becomes a
+ * model-call decision under the same policy as every other host.
+ *
+ * What it does, in order:
+ *   1. Resolve the session: x-agentguard-session header (high confidence)
+ *      or remote port (low confidence; can never earn a session-scope STOP).
+ *   2. Ask the gateway to admit the call. A STOP answers 429 with the alarm
+ *      box before anything is forwarded. A STOP therefore blocks the *next*
+ *      request; it never cuts a stream that is already flowing.
+ *   3. Forward the request; stream every upstream chunk to the client BEFORE
+ *      the observer parses it, honouring backpressure.
+ *   4. On end, commit the observed usage under the call ID, which replaces
+ *      any estimate that raw middleware reserved for the same call.
+ *
+ * Loopback only, both sides, by default. Node built-ins only. No body is
+ * ever stored.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.profileFor = profileFor;
+exports.startProxy = startProxy;
+const node_http_1 = require("node:http");
+const node_https_1 = require("node:https");
+const events_1 = require("../events");
+const render_1 = require("../replay/render");
+const usage_observer_1 = require("./usage-observer");
+const HOP_BY_HOP = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade']);
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+function profileFor(host) {
+    return host === 'ollama' ? 'ollama' : 'openai-compatible';
+}
+async function startProxy(opts) {
+    const listenHost = opts.listenHost ?? '127.0.0.1';
+    if (!LOOPBACK.has(listenHost))
+        throw new Error(`AgentGuard proxy listens on loopback only; refusing ${listenHost}`);
+    if (!opts.allowRemoteUpstream && !LOOPBACK.has(opts.upstream.hostname)) {
+        throw new Error(`Upstream ${opts.upstream.hostname} is not loopback. Pass --allow-remote-upstream if that is intended.`);
+    }
+    const log = opts.log ?? (() => undefined);
+    const server = (0, node_http_1.createServer)((req, res) => {
+        handle(req, res, opts, log).catch((error) => {
+            if (!res.headersSent)
+                res.writeHead(502, { 'content-type': 'application/json; charset=utf-8' });
+            if (!res.writableEnded)
+                res.end(JSON.stringify({ error: { type: 'agentguard_proxy_error', message: error instanceof Error ? error.message : String(error) } }));
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(opts.listenPort ?? 0, listenHost, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const addr = server.address();
+    if (!addr || typeof addr === 'string')
+        throw new Error('proxy did not bind a TCP port');
+    return {
+        server,
+        address: new URL(`http://${listenHost}:${addr.port}`),
+        close: () => new Promise((resolve, reject) => server.close((e) => (e ? reject(e) : resolve()))),
+    };
+}
+async function handle(req, res, opts, log) {
+    const startedAt = Date.now();
+    const explicit = first(req.headers[events_1.SESSION_HEADER]);
+    const sessionId = explicit && (0, events_1.isValidSessionId)(explicit) ? explicit : opts.defaultSession ?? `${opts.host}:port-${req.socket.remotePort ?? 0}`;
+    const attribution = explicit && (0, events_1.isValidSessionId)(explicit) ? 'high' : opts.defaultSession ? 'high' : 'low';
+    const callId = first(req.headers[events_1.CALL_HEADER]) ?? (0, events_1.eventId)();
+    const decision = opts.gateway.beforeCall({
+        schemaVersion: 1,
+        kind: 'call_requested',
+        eventId: `proxy:${callId}`,
+        host: opts.host,
+        sessionId,
+        at: startedAt,
+        callId,
+        estimatedTokens: 0,
+        attribution,
+    });
+    if (decision.blocked) {
+        req.resume();
+        const box = (0, render_1.renderStop)(decision.report, { colour: false, subject: 'call' });
+        log(`STOP ${sessionId} ${req.method} ${req.url}`);
+        res.writeHead(429, {
+            'content-type': 'application/json; charset=utf-8',
+            'retry-after': '60',
+            'cache-control': 'no-store',
+            'x-agentguard-verdict': 'STOP',
+        });
+        res.end(JSON.stringify({
+            error: {
+                type: 'agentguard_burn_stop',
+                message: box,
+                verdict: decision.verdict,
+                findings: decision.report.findings.map((f) => ({ detector: f.detector, verdict: f.verdict, summary: f.summary })),
+                prescriptions: decision.report.prescriptions,
+                receipt: decision.receipt,
+            },
+        }));
+        return;
+    }
+    const target = new URL(req.url ?? '/', opts.upstream);
+    const headers = forward(req.headers);
+    headers.host = opts.upstream.host;
+    // Keep the bytes inspectable without ever decompressing on the hot path.
+    headers['accept-encoding'] = 'identity';
+    if (decision.verdict !== 'OK')
+        headers['x-agentguard-verdict'] = decision.verdict;
+    const requester = target.protocol === 'https:' ? node_https_1.request : node_http_1.request;
+    const profile = profileFor(opts.host);
+    await new Promise((resolve, reject) => {
+        const upstream = requester({ protocol: target.protocol, hostname: target.hostname, port: target.port || undefined, method: req.method, path: `${target.pathname}${target.search}`, headers }, (up) => {
+            const outHeaders = forward(up.headers);
+            if (decision.verdict !== 'OK')
+                outHeaders['x-agentguard-verdict'] = decision.verdict;
+            res.writeHead(up.statusCode ?? 502, outHeaders);
+            const observer = new usage_observer_1.UsageObserver(profile, first(up.headers['content-type']));
+            up.on('data', (raw) => {
+                const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+                // Invariant: the client gets the bytes before we look at them.
+                const writable = res.write(chunk);
+                observer.observe(chunk);
+                if (!writable) {
+                    up.pause();
+                    res.once('drain', () => up.resume());
+                }
+            });
+            up.once('end', () => {
+                const seen = observer.finish();
+                res.end();
+                const finishedAt = Date.now();
+                if (seen.observed) {
+                    opts.gateway.completeCall({ host: opts.host, sessionId, callId, tokens: seen.tokens, cacheRead: seen.cacheRead, usageCoverage: seen.authoritative ? 'authoritative' : 'estimated', at: finishedAt });
+                }
+                else {
+                    // The server sent no usage. Coverage drops; the count does not lie.
+                    opts.gateway.failCall({ host: opts.host, sessionId, callId, at: finishedAt });
+                }
+                log(`${decision.verdict.padEnd(4)} ${sessionId} ${req.method} ${req.url} ${seen.observed ? `${seen.tokens} tok` : 'usage missing'} ${finishedAt - startedAt}ms`);
+                resolve();
+            });
+            up.once('error', (error) => {
+                res.destroy(error);
+                opts.gateway.failCall({ host: opts.host, sessionId, callId });
+                reject(error);
+            });
+        });
+        upstream.once('error', (error) => {
+            opts.gateway.failCall({ host: opts.host, sessionId, callId });
+            reject(error);
+        });
+        req.pipe(upstream);
+    });
+}
+function first(v) {
+    return Array.isArray(v) ? v[0] : v;
+}
+function forward(src) {
+    const out = {};
+    for (const [k, v] of Object.entries(src))
+        if (v !== undefined && !HOP_BY_HOP.has(k.toLowerCase()))
+            out[k] = v;
+    return out;
+}

package/dist/src/proxy/usage-observer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Watch response bytes go past and pick out the usage figures.
+ *
+ * This is a side channel, never a data path: the proxy writes every chunk to
+ * the client before this sees it, and this keeps only counts. Prompts and
+ * completions are parsed and dropped line by line. A non-streaming body is
+ * buffered up to a cap so a giant response cannot turn a guard into a
+ * memory leak.
+ *
+ * Ollama profile        final NDJSON object, prompt_eval_count + eval_count
+ * OpenAI-compatible     non-streaming `usage`, or the final SSE usage event
+ *                       when the server sends one (vLLM, LM Studio and
+ *                       llama.cpp do with stream_options.include_usage).
+ *
+ * Missing usage is reported as missing. It is never a guessed zero.
+ */
+export type ProxyProfile = 'ollama' | 'openai-compatible';
+export interface ObservedUsage {
+    tokens: number;
+    cacheRead: number;
+    observed: boolean;
+    authoritative: boolean;
+    model?: string;
+}
+export declare class UsageObserver {
+    private readonly profile;
+    private lineBuffer;
+    private body;
+    private bodyBytes;
+    private overflow;
+    private usage;
+    private authoritative;
+    private model;
+    private readonly streaming;
+    constructor(profile: ProxyProfile, contentType?: string);
+    observe(chunk: Buffer): void;
+    finish(): ObservedUsage;
+    private parseLine;
+    private parseJson;
+}

package/dist/src/proxy/usage-observer.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Watch response bytes go past and pick out the usage figures.
+ *
+ * This is a side channel, never a data path: the proxy writes every chunk to
+ * the client before this sees it, and this keeps only counts. Prompts and
+ * completions are parsed and dropped line by line. A non-streaming body is
+ * buffered up to a cap so a giant response cannot turn a guard into a
+ * memory leak.
+ *
+ * Ollama profile        final NDJSON object, prompt_eval_count + eval_count
+ * OpenAI-compatible     non-streaming `usage`, or the final SSE usage event
+ *                       when the server sends one (vLLM, LM Studio and
+ *                       llama.cpp do with stream_options.include_usage).
+ *
+ * Missing usage is reported as missing. It is never a guessed zero.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageObserver = void 0;
+const MAX_BUFFER = 32 * 1024 * 1024;
+class UsageObserver {
+    profile;
+    lineBuffer = '';
+    body = [];
+    bodyBytes = 0;
+    overflow = false;
+    usage = null;
+    authoritative = false;
+    model;
+    streaming;
+    constructor(profile, contentType = '') {
+        this.profile = profile;
+        const ct = contentType.toLowerCase();
+        this.streaming = ct.includes('text/event-stream') || ct.includes('ndjson') || (profile === 'ollama' && !ct.includes('application/json'));
+    }
+    observe(chunk) {
+        if (this.streaming) {
+            this.lineBuffer += chunk.toString('utf8');
+            for (;;) {
+                const nl = this.lineBuffer.indexOf('\n');
+                if (nl < 0)
+                    break;
+                const line = this.lineBuffer.slice(0, nl).replace(/\r$/, '');
+                this.lineBuffer = this.lineBuffer.slice(nl + 1);
+                this.parseLine(line);
+            }
+            return;
+        }
+        if (this.overflow)
+            return;
+        this.bodyBytes += chunk.length;
+        if (this.bodyBytes > MAX_BUFFER) {
+            this.overflow = true;
+            this.body = [];
+            return;
+        }
+        this.body.push(Buffer.from(chunk));
+    }
+    finish() {
+        if (this.streaming && this.lineBuffer.trim())
+            this.parseLine(this.lineBuffer.trim());
+        if (!this.streaming && !this.overflow)
+            this.parseJson(Buffer.concat(this.body).toString('utf8'));
+        this.body = [];
+        return {
+            tokens: this.usage?.tokens ?? 0,
+            cacheRead: this.usage?.cacheRead ?? 0,
+            observed: this.usage !== null,
+            authoritative: this.authoritative,
+            model: this.model,
+        };
+    }
+    parseLine(raw) {
+        const line = raw.trim();
+        if (!line || line.startsWith(':'))
+            return;
+        if (line.startsWith('data:')) {
+            const payload = line.slice(5).trim();
+            if (!payload || payload === '[DONE]')
+                return;
+            this.parseJson(payload);
+            return;
+        }
+        if (this.profile === 'ollama')
+            this.parseJson(line);
+    }
+    parseJson(text) {
+        let v;
+        try {
+            v = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        if (!isRecord(v))
+            return;
+        if (typeof v.model === 'string')
+            this.model = v.model;
+        if (this.profile === 'ollama') {
+            const prompt = count(v.prompt_eval_count);
+            const completion = count(v.eval_count);
+            if (prompt !== undefined || completion !== undefined) {
+                this.usage = { tokens: (prompt ?? 0) + (completion ?? 0), cacheRead: 0 };
+                this.authoritative = v.done === true;
+            }
+            return;
+        }
+        if (!isRecord(v.usage))
+            return;
+        const u = v.usage;
+        const prompt = count(u.prompt_tokens) ?? count(u.input_tokens);
+        const completion = count(u.completion_tokens) ?? count(u.output_tokens);
+        const total = count(u.total_tokens);
+        const details = isRecord(u.prompt_tokens_details) ? u.prompt_tokens_details : isRecord(u.input_tokens_details) ? u.input_tokens_details : undefined;
+        const cached = details ? count(details.cached_tokens) : undefined;
+        if (prompt !== undefined || completion !== undefined || total !== undefined) {
+            this.usage = { tokens: Math.max(total ?? 0, (prompt ?? 0) + (completion ?? 0)), cacheRead: cached ?? 0 };
+            this.authoritative = true;
+        }
+    }
+}
+exports.UsageObserver = UsageObserver;
+function isRecord(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function count(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.trunc(v) : undefined;
+}

package/dist/src/receipt.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Content-free signed receipts.
+ *
+ * Every decision that matters (a spawn admission, or any non-OK verdict on a
+ * model call) is signed with a local Ed25519 key and chained to the previous
+ * receipt for the same session. The payload is counts, digests and verdicts.
+ * It contains no prompt, no completion, no path, no tool input. That is what
+ * lets a receipt leave the machine when a session transcript never can.
+ *
+ * Node built-ins only. The key is generated on first use, 0600, under the
+ * AgentGuard home. This is developer-grade evidence, not enterprise key
+ * custody; rotation and external signers are a later product, not a hidden
+ * gap.
+ */
+import type { HostCapabilities, HostId } from './events';
+import type { Verdict } from './types';
+export interface ReceiptPayload {
+    schema: 'agentguard.burn.decision.v1';
+    decisionId: string;
+    at: number;
+    host: HostId;
+    /** sha256 of the session id: correlatable, not reversible. */
+    sessionDigest: string;
+    action: 'spawn' | 'model_call';
+    policy: {
+        mode: 'shadow' | 'enforce';
+        digest: string;
+    };
+    measured: {
+        sessionTokens: number;
+        sessionSpawns: number;
+        proposedDepth: number | null;
+        inFlight: number;
+        occupiedMs: number;
+    };
+    coverage: HostCapabilities;
+    verdict: Verdict;
+    blocked: boolean;
+    reasons: string[];
+    previous: string | null;
+}
+export interface SignedReceipt {
+    payload: ReceiptPayload;
+    keyId: string;
+    algorithm: 'Ed25519';
+    publicKey: string;
+    signature: string;
+}
+/** Stable key order so the bytes that were signed can be reproduced anywhere. */
+export declare function canonical(value: unknown): string;
+export declare function sha256(text: string): string;
+export declare class ReceiptSigner {
+    private readonly privatePem;
+    readonly publicKey: string;
+    readonly keyId: string;
+    constructor(privatePem: string);
+    static loadOrCreate(home: string): ReceiptSigner;
+    sign(payload: ReceiptPayload): SignedReceipt;
+}
+export declare function verifyReceipt(receipt: SignedReceipt): boolean;
+export declare function receiptDigest(receipt: SignedReceipt): string;

package/dist/src/receipt.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Content-free signed receipts.
+ *
+ * Every decision that matters (a spawn admission, or any non-OK verdict on a
+ * model call) is signed with a local Ed25519 key and chained to the previous
+ * receipt for the same session. The payload is counts, digests and verdicts.
+ * It contains no prompt, no completion, no path, no tool input. That is what
+ * lets a receipt leave the machine when a session transcript never can.
+ *
+ * Node built-ins only. The key is generated on first use, 0600, under the
+ * AgentGuard home. This is developer-grade evidence, not enterprise key
+ * custody; rotation and external signers are a later product, not a hidden
+ * gap.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReceiptSigner = void 0;
+exports.canonical = canonical;
+exports.sha256 = sha256;
+exports.verifyReceipt = verifyReceipt;
+exports.receiptDigest = receiptDigest;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Stable key order so the bytes that were signed can be reproduced anywhere. */
+function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    const entries = Object.keys(value)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`);
+    return `{${entries.join(',')}}`;
+}
+function sha256(text) {
+    return (0, node_crypto_1.createHash)('sha256').update(text).digest('hex');
+}
+class ReceiptSigner {
+    privatePem;
+    publicKey;
+    keyId;
+    constructor(privatePem) {
+        const priv = (0, node_crypto_1.createPrivateKey)(privatePem);
+        this.privatePem = priv.export({ type: 'pkcs8', format: 'pem' }).toString();
+        const spki = (0, node_crypto_1.createPublicKey)(priv).export({ type: 'spki', format: 'der' });
+        this.publicKey = spki.toString('base64');
+        this.keyId = sha256(this.publicKey).slice(0, 16);
+    }
+    static loadOrCreate(home) {
+        const file = (0, node_path_1.join)(home, 'receipt-signing-key.pem');
+        if ((0, node_fs_1.existsSync)(file))
+            return new ReceiptSigner((0, node_fs_1.readFileSync)(file, 'utf8'));
+        (0, node_fs_1.mkdirSync)(home, { recursive: true, mode: 0o700 });
+        // Sixty hook processes on a fresh home all arrive here at once. Exactly
+        // one key must win: write to a private temp name, then link it into
+        // place (link fails with EEXIST if a sibling got there first), and the
+        // losers read the winner's key. Nobody ever sees a half-written PEM.
+        const pair = (0, node_crypto_1.generateKeyPairSync)('ed25519');
+        const pem = pair.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+        const tmp = `${file}.${process.pid}.tmp`;
+        (0, node_fs_1.writeFileSync)(tmp, pem, { mode: 0o600 });
+        try {
+            (0, node_fs_1.linkSync)(tmp, file);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        finally {
+            (0, node_fs_1.rmSync)(tmp, { force: true });
+        }
+        return new ReceiptSigner((0, node_fs_1.readFileSync)(file, 'utf8'));
+    }
+    sign(payload) {
+        const bytes = Buffer.from(canonical(payload));
+        return {
+            payload,
+            keyId: this.keyId,
+            algorithm: 'Ed25519',
+            publicKey: this.publicKey,
+            signature: (0, node_crypto_1.sign)(null, bytes, this.privatePem).toString('base64'),
+        };
+    }
+}
+exports.ReceiptSigner = ReceiptSigner;
+function verifyReceipt(receipt) {
+    try {
+        const key = (0, node_crypto_1.createPublicKey)({ key: Buffer.from(receipt.publicKey, 'base64'), type: 'spki', format: 'der' });
+        return (0, node_crypto_1.verify)(null, Buffer.from(canonical(receipt.payload)), key, Buffer.from(receipt.signature, 'base64'));
+    }
+    catch {
+        return false;
+    }
+}
+function receiptDigest(receipt) {
+    return sha256(canonical(receipt));
+}

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

@@ -1,11 +1,18 @@
 /**
- * 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;
+    subject?: 'spawn' | 'call';
+}): string;
 export declare function renderSessionRow(s: SessionReplay): string;