network-ai 4.15.2 → 5.0.0

package/dist/lib/agent-vcr.js

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * VCR — Record and replay LLM/agent interactions for testing
+ *
+ * Provides a VCR (Video Cassette Recorder) pattern for capturing
+ * agent execution calls and replaying them deterministically in tests.
+ *
+ * Modes:
+ *   - `record` — Intercepts calls, forwards to real handler, saves cassette
+ *   - `replay` — Matches calls to recorded cassettes, returns saved results
+ *   - `passthrough` — Disabled, all calls go to real handler
+ *
+ * Features:
+ *   - Cassettes stored as JSON files
+ *   - Request matching by agent ID + action + params hash
+ *   - Configurable matching strictness
+ *   - Call ordering enforcement (optional)
+ *   - Missing cassette detection with helpful errors
+ *
+ * Usage:
+ *   const vcr = new AgentVCR({ mode: 'record', cassettePath: './fixtures' });
+ *   const result = await vcr.execute('agent-1', payload, realHandler);
+ *   await vcr.save('my-test'); // Saves cassette to ./fixtures/my-test.json
+ *
+ *   // Later in tests:
+ *   const vcr2 = new AgentVCR({ mode: 'replay', cassettePath: './fixtures' });
+ *   await vcr2.load('my-test');
+ *   const result2 = await vcr2.execute('agent-1', payload); // Returns recorded result
+ *
+ * @module AgentVCR
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentVCR = void 0;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+// ============================================================================
+// VCR
+// ============================================================================
+/**
+ * Agent VCR — Record and replay agent execution calls.
+ *
+ * In `record` mode, calls are forwarded to the real handler and saved.
+ * In `replay` mode, calls are matched to saved cassettes.
+ */
+class AgentVCR {
+    cassette = null;
+    replayIndex = 0;
+    config;
+    constructor(config) {
+        this.config = {
+            mode: config.mode,
+            cassettePath: config.cassettePath,
+            matchMode: config.matchMode ?? 'exact',
+            ordered: config.ordered ?? false,
+            throwOnMissing: config.throwOnMissing ?? true,
+        };
+    }
+    /** Get current mode */
+    get mode() {
+        return this.config.mode;
+    }
+    /** Set mode at runtime */
+    setMode(mode) {
+        this.config.mode = mode;
+    }
+    /**
+     * Execute an agent call through the VCR.
+     *
+     * @param agentId - The agent to call
+     * @param payload - The request payload
+     * @param handler - Real handler (required in record/passthrough mode)
+     */
+    async execute(agentId, payload, handler) {
+        switch (this.config.mode) {
+            case 'passthrough':
+                if (!handler)
+                    throw new Error('VCR passthrough mode requires a handler');
+                return handler(agentId, payload);
+            case 'record':
+                return this.recordExecution(agentId, payload, handler);
+            case 'replay':
+                return this.replayExecution(agentId, payload);
+            default:
+                throw new Error(`Unknown VCR mode: ${this.config.mode}`);
+        }
+    }
+    /**
+     * Load a cassette from disk.
+     */
+    async load(name) {
+        const filePath = (0, path_1.join)(this.config.cassettePath, `${name}.json`);
+        const raw = await (0, promises_1.readFile)(filePath, 'utf-8');
+        this.cassette = JSON.parse(raw);
+        this.replayIndex = 0;
+        return this.cassette;
+    }
+    /**
+     * Save the current recording as a named cassette.
+     */
+    async save(name) {
+        if (!this.cassette) {
+            this.cassette = { name, createdAt: Date.now(), interactions: [] };
+        }
+        this.cassette.name = name;
+        try {
+            await (0, promises_1.stat)(this.config.cassettePath);
+        }
+        catch {
+            await (0, promises_1.mkdir)(this.config.cassettePath, { recursive: true });
+        }
+        const filePath = (0, path_1.join)(this.config.cassettePath, `${name}.json`);
+        await (0, promises_1.writeFile)(filePath, JSON.stringify(this.cassette, null, 2), 'utf-8');
+    }
+    /** Get the current cassette */
+    getCassette() {
+        return this.cassette;
+    }
+    /** Reset the VCR (clear cassette and replay index) */
+    reset() {
+        this.cassette = null;
+        this.replayIndex = 0;
+    }
+    /** Get number of recorded interactions */
+    get interactionCount() {
+        return this.cassette?.interactions.length ?? 0;
+    }
+    /**
+     * Try to match a request to a recorded interaction.
+     * Useful for debugging match failures.
+     */
+    findMatch(agentId, payload) {
+        const fingerprint = this.computeFingerprint(agentId, payload);
+        if (!this.cassette) {
+            return { matched: false, fingerprint, candidates: 0 };
+        }
+        const candidates = this.cassette.interactions.filter((i) => {
+            if (this.config.matchMode === 'fuzzy') {
+                return i.agentId === agentId;
+            }
+            return i.fingerprint === fingerprint;
+        });
+        return {
+            matched: candidates.length > 0,
+            fingerprint,
+            candidates: candidates.length,
+            bestMatch: candidates[0],
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Internal
+    // --------------------------------------------------------------------------
+    async recordExecution(agentId, payload, handler) {
+        if (!handler)
+            throw new Error('VCR record mode requires a handler');
+        if (!this.cassette) {
+            this.cassette = { name: 'recording', createdAt: Date.now(), interactions: [] };
+        }
+        const start = Date.now();
+        const response = await handler(agentId, payload);
+        const durationMs = Date.now() - start;
+        const action = payload['action'] ?? '';
+        const paramsHash = this.hashParams(payload);
+        const fingerprint = this.computeFingerprint(agentId, payload);
+        this.cassette.interactions.push({
+            fingerprint,
+            agentId,
+            action,
+            paramsHash,
+            request: payload,
+            response,
+            recordedAt: Date.now(),
+            durationMs,
+        });
+        return response;
+    }
+    replayExecution(agentId, payload) {
+        if (!this.cassette || this.cassette.interactions.length === 0) {
+            throw new Error('No cassette loaded for replay. Call load() first.');
+        }
+        // Ordered mode: use sequential index
+        if (this.config.ordered) {
+            if (this.replayIndex >= this.cassette.interactions.length) {
+                throw new Error(`VCR replay exhausted: ${this.replayIndex} calls made but only ${this.cassette.interactions.length} recorded`);
+            }
+            const interaction = this.cassette.interactions[this.replayIndex++];
+            return interaction.response;
+        }
+        // Unordered: match by fingerprint
+        const fingerprint = this.computeFingerprint(agentId, payload);
+        const match = this.cassette.interactions.find((i) => {
+            if (this.config.matchMode === 'fuzzy') {
+                return i.agentId === agentId;
+            }
+            return i.fingerprint === fingerprint;
+        });
+        if (match) {
+            return match.response;
+        }
+        if (this.config.throwOnMissing) {
+            throw new Error(`VCR replay: no matching interaction for agent='${agentId}' fingerprint='${fingerprint}'. ` +
+                `Cassette has ${this.cassette.interactions.length} interactions.`);
+        }
+        return { error: 'VCR: no matching interaction', agentId };
+    }
+    computeFingerprint(agentId, payload) {
+        const action = payload['action'] ?? '';
+        const paramsHash = this.hashParams(payload);
+        return `${agentId}:${action}:${paramsHash}`;
+    }
+    hashParams(payload) {
+        const sorted = JSON.stringify(payload, Object.keys(payload).sort());
+        return (0, crypto_1.createHash)('sha256').update(sorted).digest('hex').slice(0, 12);
+    }
+}
+exports.AgentVCR = AgentVCR;
+//# sourceMappingURL=agent-vcr.js.map

package/dist/lib/agent-vcr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-vcr.js","sourceRoot":"","sources":["../../lib/agent-vcr.ts"],"names":[],"mappings":"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"}

package/dist/lib/anomaly-detector.d.ts

@@ -0,0 +1,112 @@
+/**
+ * AnomalyDetector — Baseline agent behavior and flag statistical outliers.
+ *
+ * Maintains rolling statistics (mean, stddev) per agent for latency, token
+ * usage, and error rate.  New observations are checked against the baseline
+ * and flagged as anomalies when they exceed a configurable z-score threshold.
+ *
+ * Uses Welford's online algorithm for numerically stable incremental
+ * mean/variance — no batch recomputation needed.
+ *
+ * @module AnomalyDetector
+ */
+/** A detected anomaly */
+export interface Anomaly {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Agent that triggered the anomaly */
+    agentId: string;
+    /** Which metric is anomalous */
+    metric: AnomalyMetric;
+    /** Observed value */
+    observed: number;
+    /** Baseline mean for this agent + metric */
+    baselineMean: number;
+    /** Baseline standard deviation */
+    baselineStddev: number;
+    /** Z-score of the observation */
+    zScore: number;
+    /** Severity based on z-score magnitude */
+    severity: 'warning' | 'critical';
+}
+/** Metrics that are monitored for anomalies */
+export type AnomalyMetric = 'latency' | 'tokens' | 'errorRate';
+/** Summary of an agent's baseline */
+export interface BaselineSummary {
+    agentId: string;
+    latency: {
+        mean: number;
+        stddev: number;
+        samples: number;
+    };
+    tokens: {
+        mean: number;
+        stddev: number;
+        samples: number;
+    };
+    errorRate: {
+        mean: number;
+        stddev: number;
+        samples: number;
+    };
+}
+/**
+ * Monitors agent behavior and flags statistical anomalies.
+ *
+ * @example
+ * ```ts
+ * const detector = new AnomalyDetector();
+ *
+ * // Feed observations as they occur:
+ * detector.observe('agent-1', { latencyMs: 200, tokens: 500, success: true });
+ * detector.observe('agent-1', { latencyMs: 15000, tokens: 500, success: true });
+ * // ^ second call may flag latency anomaly if baseline is ~200ms
+ *
+ * const anomalies = detector.getAnomalies();
+ * const baseline = detector.getBaseline('agent-1');
+ * ```
+ */
+export declare class AnomalyDetector {
+    private baselines;
+    private anomalies;
+    private maxAnomalies;
+    private warningThreshold;
+    private criticalThreshold;
+    private minSamples;
+    private errorWindow;
+    constructor(options?: {
+        /** Z-score threshold for 'warning' level. Default 2.0 */
+        warningThreshold?: number;
+        /** Z-score threshold for 'critical' level. Default 3.0 */
+        criticalThreshold?: number;
+        /** Minimum samples before anomaly detection activates. Default 10 */
+        minSamples?: number;
+        /** Max anomalies to retain. Default 1000 */
+        maxAnomalies?: number;
+    });
+    /**
+     * Record an observation for an agent and check for anomalies.
+     * Returns any anomalies detected from this observation.
+     */
+    observe(agentId: string, obs: {
+        latencyMs: number;
+        tokens: number;
+        success: boolean;
+    }): Anomaly[];
+    /** Get all recorded anomalies, optionally filtered by agent */
+    getAnomalies(agentId?: string): Anomaly[];
+    /** Get recent anomalies (last N) */
+    getRecentAnomalies(count: number): Anomaly[];
+    /** Get the baseline summary for an agent */
+    getBaseline(agentId: string): BaselineSummary | null;
+    /** List all agents with baselines */
+    listAgents(): string[];
+    /** Total anomalies recorded */
+    get anomalyCount(): number;
+    /** Clear all baselines and anomalies */
+    clear(): void;
+    /** Clear data for a specific agent */
+    clearAgent(agentId: string): void;
+    private checkMetric;
+}
+//# sourceMappingURL=anomaly-detector.d.ts.map

package/dist/lib/anomaly-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anomaly-detector.d.ts","sourceRoot":"","sources":["../../lib/anomaly-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,yBAAyB;AACzB,MAAM,WAAW,OAAO;IACtB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,MAAM,EAAE,aAAa,CAAC;IACtB,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,QAAQ,EAAE,SAAS,GAAG,UAAU,CAAC;CAClC;AAED,+CAA+C;AAC/C,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAgB/D,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAiCD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,SAAS,CAAyC;IAC1D,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAA6D;gBAEpE,OAAO,CAAC,EAAE;QACpB,yDAAyD;QACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,0DAA0D;QAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,qEAAqE;QACrE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,4CAA4C;QAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB;IAOD;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE;QAC5B,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,OAAO,CAAC;KAClB,GAAG,OAAO,EAAE;IA+Cb,+DAA+D;IAC/D,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE;IAKzC,oCAAoC;IACpC,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,EAAE;IAI5C,4CAA4C;IAC5C,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAWpD,qCAAqC;IACrC,UAAU,IAAI,MAAM,EAAE;IAItB,+BAA+B;IAC/B,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,wCAAwC;IACxC,KAAK,IAAI,IAAI;IAMb,sCAAsC;IACtC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAMjC,OAAO,CAAC,WAAW;CA0BpB"}

package/dist/lib/anomaly-detector.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * AnomalyDetector — Baseline agent behavior and flag statistical outliers.
+ *
+ * Maintains rolling statistics (mean, stddev) per agent for latency, token
+ * usage, and error rate.  New observations are checked against the baseline
+ * and flagged as anomalies when they exceed a configurable z-score threshold.
+ *
+ * Uses Welford's online algorithm for numerically stable incremental
+ * mean/variance — no batch recomputation needed.
+ *
+ * @module AnomalyDetector
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnomalyDetector = void 0;
+// ============================================================================
+// WELFORD HELPERS
+// ============================================================================
+function welfordInit() {
+    return { count: 0, mean: 0, m2: 0 };
+}
+function welfordUpdate(state, value) {
+    state.count++;
+    const delta = value - state.mean;
+    state.mean += delta / state.count;
+    const delta2 = value - state.mean;
+    state.m2 += delta * delta2;
+}
+function welfordStddev(state) {
+    if (state.count < 2)
+        return 0;
+    return Math.sqrt(state.m2 / (state.count - 1));
+}
+function welfordZScore(state, value) {
+    const std = welfordStddev(state);
+    if (std === 0 || state.count < 5)
+        return 0; // Need minimum samples
+    return (value - state.mean) / std;
+}
+// ============================================================================
+// DETECTOR
+// ============================================================================
+/**
+ * Monitors agent behavior and flags statistical anomalies.
+ *
+ * @example
+ * ```ts
+ * const detector = new AnomalyDetector();
+ *
+ * // Feed observations as they occur:
+ * detector.observe('agent-1', { latencyMs: 200, tokens: 500, success: true });
+ * detector.observe('agent-1', { latencyMs: 15000, tokens: 500, success: true });
+ * // ^ second call may flag latency anomaly if baseline is ~200ms
+ *
+ * const anomalies = detector.getAnomalies();
+ * const baseline = detector.getBaseline('agent-1');
+ * ```
+ */
+class AnomalyDetector {
+    baselines = new Map();
+    anomalies = [];
+    maxAnomalies;
+    warningThreshold;
+    criticalThreshold;
+    minSamples;
+    errorWindow = new Map();
+    constructor(options) {
+        this.warningThreshold = options?.warningThreshold ?? 2.0;
+        this.criticalThreshold = options?.criticalThreshold ?? 3.0;
+        this.minSamples = options?.minSamples ?? 10;
+        this.maxAnomalies = options?.maxAnomalies ?? 1000;
+    }
+    /**
+     * Record an observation for an agent and check for anomalies.
+     * Returns any anomalies detected from this observation.
+     */
+    observe(agentId, obs) {
+        let baseline = this.baselines.get(agentId);
+        if (!baseline) {
+            baseline = {
+                latency: welfordInit(),
+                tokens: welfordInit(),
+                errorRate: welfordInit(),
+            };
+            this.baselines.set(agentId, baseline);
+        }
+        // Update error rate tracking
+        let errWin = this.errorWindow.get(agentId);
+        if (!errWin) {
+            errWin = { total: 0, errors: 0 };
+            this.errorWindow.set(agentId, errWin);
+        }
+        errWin.total++;
+        if (!obs.success)
+            errWin.errors++;
+        const currentErrorRate = errWin.total > 0 ? errWin.errors / errWin.total : 0;
+        const detected = [];
+        // Check before updating baseline (compare against historical)
+        detected.push(...this.checkMetric(agentId, 'latency', baseline.latency, obs.latencyMs));
+        detected.push(...this.checkMetric(agentId, 'tokens', baseline.tokens, obs.tokens));
+        detected.push(...this.checkMetric(agentId, 'errorRate', baseline.errorRate, currentErrorRate));
+        // Now update baselines
+        welfordUpdate(baseline.latency, obs.latencyMs);
+        welfordUpdate(baseline.tokens, obs.tokens);
+        welfordUpdate(baseline.errorRate, currentErrorRate);
+        // Store detected anomalies
+        for (const a of detected) {
+            this.anomalies.push(a);
+        }
+        if (this.anomalies.length > this.maxAnomalies) {
+            this.anomalies.splice(0, this.anomalies.length - this.maxAnomalies);
+        }
+        return detected;
+    }
+    /** Get all recorded anomalies, optionally filtered by agent */
+    getAnomalies(agentId) {
+        if (agentId)
+            return this.anomalies.filter(a => a.agentId === agentId);
+        return [...this.anomalies];
+    }
+    /** Get recent anomalies (last N) */
+    getRecentAnomalies(count) {
+        return this.anomalies.slice(-count);
+    }
+    /** Get the baseline summary for an agent */
+    getBaseline(agentId) {
+        const b = this.baselines.get(agentId);
+        if (!b)
+            return null;
+        return {
+            agentId,
+            latency: { mean: b.latency.mean, stddev: welfordStddev(b.latency), samples: b.latency.count },
+            tokens: { mean: b.tokens.mean, stddev: welfordStddev(b.tokens), samples: b.tokens.count },
+            errorRate: { mean: b.errorRate.mean, stddev: welfordStddev(b.errorRate), samples: b.errorRate.count },
+        };
+    }
+    /** List all agents with baselines */
+    listAgents() {
+        return [...this.baselines.keys()];
+    }
+    /** Total anomalies recorded */
+    get anomalyCount() {
+        return this.anomalies.length;
+    }
+    /** Clear all baselines and anomalies */
+    clear() {
+        this.baselines.clear();
+        this.anomalies.length = 0;
+        this.errorWindow.clear();
+    }
+    /** Clear data for a specific agent */
+    clearAgent(agentId) {
+        this.baselines.delete(agentId);
+        this.errorWindow.delete(agentId);
+        this.anomalies = this.anomalies.filter(a => a.agentId !== agentId);
+    }
+    checkMetric(agentId, metric, state, value) {
+        if (state.count < this.minSamples)
+            return [];
+        const z = welfordZScore(state, value);
+        const absZ = Math.abs(z);
+        if (absZ >= this.warningThreshold) {
+            return [{
+                    timestamp: new Date().toISOString(),
+                    agentId,
+                    metric,
+                    observed: value,
+                    baselineMean: state.mean,
+                    baselineStddev: welfordStddev(state),
+                    zScore: z,
+                    severity: absZ >= this.criticalThreshold ? 'critical' : 'warning',
+                }];
+        }
+        return [];
+    }
+}
+exports.AnomalyDetector = AnomalyDetector;
+//# sourceMappingURL=anomaly-detector.js.map

package/dist/lib/anomaly-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anomaly-detector.js","sourceRoot":"","sources":["../../lib/anomaly-detector.ts"],"names":[],"mappings":"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"}

package/dist/lib/approval-inbox.d.ts

@@ -0,0 +1,147 @@
+/**
+ * ApprovalInbox — Web-accessible human-in-the-loop approval system
+ *
+ * Provides an HTTP API and SSE streaming for managing approval requests
+ * from AI agents. Designed to work as an ApprovalCallback for ApprovalGate
+ * while also exposing a REST-like HTTP interface.
+ *
+ * Features:
+ *   - Queues approval requests with unique IDs and optional timeouts
+ *   - REST API: list, get, approve, deny, stats
+ *   - SSE stream for real-time notifications
+ *   - Auto-expiry for stale requests
+ *   - Standalone HTTP server or mountable handler
+ *
+ * @module ApprovalInbox
+ * @version 1.0.0
+ */
+import { EventEmitter } from 'events';
+import { IncomingMessage, ServerResponse, Server } from 'http';
+import type { ApprovalRequest, ApprovalDecision, ApprovalCallback } from './agent-runtime';
+/** Status of an approval entry */
+export type ApprovalStatus = 'pending' | 'approved' | 'denied' | 'expired';
+/** A queued approval entry */
+export interface ApprovalEntry {
+    /** Unique identifier for this approval */
+    id: string;
+    /** The original approval request */
+    request: ApprovalRequest;
+    /** Current status */
+    status: ApprovalStatus;
+    /** Decision if resolved */
+    decision?: ApprovalDecision;
+    /** When the request was created */
+    createdAt: number;
+    /** When the request was resolved */
+    resolvedAt?: number;
+    /** Timeout for this specific request (ms) */
+    timeoutMs: number;
+}
+/** Options for the ApprovalInbox */
+export interface ApprovalInboxOptions {
+    /** Default timeout for approval requests in ms (default: 300000 = 5 min) */
+    defaultTimeoutMs?: number;
+    /** Maximum number of pending approvals (default: 100) */
+    maxPending?: number;
+    /** Maximum history entries to keep (default: 1000) */
+    maxHistory?: number;
+    /** URL path prefix for HTTP handler (default: '/approvals') */
+    pathPrefix?: string;
+}
+/** SSE event types */
+export type InboxEventType = 'new' | 'approved' | 'denied' | 'expired';
+/** SSE event payload */
+export interface InboxEvent {
+    type: InboxEventType;
+    entry: ApprovalEntry;
+}
+/** Stats snapshot */
+export interface InboxStats {
+    pending: number;
+    approved: number;
+    denied: number;
+    expired: number;
+    total: number;
+}
+/**
+ * Web-accessible approval inbox for human-in-the-loop agent workflows.
+ *
+ * Use `inbox.callback()` to get an ApprovalCallback for ApprovalGate,
+ * and `inbox.httpHandler()` to mount the HTTP API on a server.
+ *
+ * @example
+ * ```ts
+ * const inbox = new ApprovalInbox();
+ * const gate = new ApprovalGate(inbox.callback());
+ * const server = inbox.createServer(3002);
+ * ```
+ */
+export declare class ApprovalInbox extends EventEmitter {
+    private readonly pending;
+    private readonly history;
+    private readonly sseClients;
+    private readonly defaultTimeoutMs;
+    private readonly maxPending;
+    private readonly maxHistory;
+    private readonly pathPrefix;
+    private approvedCount;
+    private deniedCount;
+    private expiredCount;
+    constructor(options?: ApprovalInboxOptions);
+    /**
+     * Returns an ApprovalCallback suitable for ApprovalGate.
+     * Each call enqueues a pending approval and waits for resolution.
+     */
+    callback(): ApprovalCallback;
+    /**
+     * Enqueue an approval request. Returns a promise that resolves when
+     * the request is approved, denied, or expires.
+     */
+    enqueue(request: ApprovalRequest, timeoutMs?: number): Promise<ApprovalDecision>;
+    /**
+     * Approve a pending request.
+     * @returns The resolved entry, or undefined if not found/already resolved.
+     */
+    approve(id: string, approvedBy: string, reason?: string): ApprovalEntry | undefined;
+    /**
+     * Deny a pending request.
+     * @returns The resolved entry, or undefined if not found/already resolved.
+     */
+    deny(id: string, deniedBy?: string, reason?: string): ApprovalEntry | undefined;
+    /** Get a single entry by ID (pending or historical) */
+    get(id: string): ApprovalEntry | undefined;
+    /** List entries by status (default: 'pending') */
+    list(status?: ApprovalStatus | 'all'): ApprovalEntry[];
+    /** Get aggregate stats */
+    stats(): InboxStats;
+    /** Number of pending approvals */
+    get pendingCount(): number;
+    /**
+     * Returns an HTTP request handler for the approval inbox API.
+     *
+     * Routes (relative to pathPrefix):
+     *   GET  /           — List approvals (?status=pending|approved|denied|expired|all)
+     *   GET  /stats      — Aggregate stats
+     *   GET  /sse        — SSE event stream
+     *   GET  /:id        — Get single entry
+     *   POST /:id/approve — Approve (body: { approvedBy, reason? })
+     *   POST /:id/deny    — Deny (body: { deniedBy?, reason? })
+     */
+    httpHandler(): (req: IncomingMessage, res: ServerResponse) => void;
+    /**
+     * Create a standalone HTTP server for the inbox.
+     * @returns The HTTP server instance (already listening).
+     */
+    startServer(port: number, hostname?: string): Server;
+    /** Broadcast an event to all connected SSE clients */
+    private broadcastSSE;
+    /** Register an SSE client */
+    private addSSEClient;
+    private resolve;
+    private expire;
+    private addToHistory;
+    private routeRequest;
+    private sendJson;
+    private readBody;
+}
+//# sourceMappingURL=approval-inbox.d.ts.map