@provos/ironcurtain 0.1.0

package/dist/session/step-loop-detector.d.ts

@@ -0,0 +1,63 @@
+/**
+ * StepLoopDetector -- Agent-level loop detection.
+ *
+ * Analyzes each execute_code step (code + result) using a 2x2 progress
+ * matrix to detect stuck or stagnating agents. The unit of analysis is
+ * the step, not individual MCP calls.
+ *
+ * Progress matrix:
+ *   - Full progress:    new approach + new outcome → reset concern
+ *   - World changed:    repeated approach + new outcome → reset concern
+ *   - Stuck:            new approach + repeated outcome → increment stuck
+ *   - Full stagnation:  repeated approach + repeated outcome → increment stagnation
+ */
+export type ProgressCategory = 'full_progress' | 'world_changed' | 'stuck' | 'full_stagnation';
+export type BlockVerdict = {
+    action: 'block';
+    message: string;
+    category: ProgressCategory;
+};
+export type StepVerdict = {
+    action: 'allow';
+} | {
+    action: 'warn';
+    message: string;
+    category: ProgressCategory;
+} | BlockVerdict;
+export interface StepLoopDetectorConfig {
+    stagnation: {
+        warn: number;
+        block: number;
+    };
+    stuck: {
+        warn: number;
+        block: number;
+    };
+}
+export declare class StepLoopDetector {
+    private readonly config;
+    private approachHashes;
+    private outcomeHashes;
+    private stagnationStreak;
+    private stuckStreak;
+    private blocked;
+    private blockVerdict;
+    constructor(config?: Partial<StepLoopDetectorConfig>);
+    /**
+     * Check if execution is blocked before running code.
+     * Returns the block verdict if blocked, null otherwise.
+     */
+    isBlocked(): BlockVerdict | null;
+    /**
+     * Analyze a completed step and return a verdict.
+     *
+     * @param code - The TypeScript code that was executed
+     * @param result - The execution result (will be hashed)
+     */
+    analyzeStep(code: string, result: unknown): StepVerdict;
+    /** Reset all state. */
+    reset(): void;
+    private classify;
+    private updateStreaks;
+    private checkThresholds;
+}

package/dist/session/step-loop-detector.js

@@ -0,0 +1,136 @@
+/**
+ * StepLoopDetector -- Agent-level loop detection.
+ *
+ * Analyzes each execute_code step (code + result) using a 2x2 progress
+ * matrix to detect stuck or stagnating agents. The unit of analysis is
+ * the step, not individual MCP calls.
+ *
+ * Progress matrix:
+ *   - Full progress:    new approach + new outcome → reset concern
+ *   - World changed:    repeated approach + new outcome → reset concern
+ *   - Stuck:            new approach + repeated outcome → increment stuck
+ *   - Full stagnation:  repeated approach + repeated outcome → increment stagnation
+ */
+import { computeHash } from '../hash.js';
+const DEFAULT_CONFIG = {
+    stagnation: { warn: 3, block: 5 },
+    stuck: { warn: 5, block: 8 },
+};
+export class StepLoopDetector {
+    config;
+    approachHashes = new Set();
+    outcomeHashes = new Set();
+    stagnationStreak = 0;
+    stuckStreak = 0;
+    blocked = false;
+    blockVerdict = null;
+    constructor(config) {
+        this.config = {
+            stagnation: { ...DEFAULT_CONFIG.stagnation, ...config?.stagnation },
+            stuck: { ...DEFAULT_CONFIG.stuck, ...config?.stuck },
+        };
+    }
+    /**
+     * Check if execution is blocked before running code.
+     * Returns the block verdict if blocked, null otherwise.
+     */
+    isBlocked() {
+        return this.blocked ? this.blockVerdict : null;
+    }
+    /**
+     * Analyze a completed step and return a verdict.
+     *
+     * @param code - The TypeScript code that was executed
+     * @param result - The execution result (will be hashed)
+     */
+    analyzeStep(code, result) {
+        const approachHash = computeHash(code);
+        const outcomeHash = computeHash(result);
+        const isNewApproach = !this.approachHashes.has(approachHash);
+        const isNewOutcome = !this.outcomeHashes.has(outcomeHash);
+        this.approachHashes.add(approachHash);
+        this.outcomeHashes.add(outcomeHash);
+        const category = this.classify(isNewApproach, isNewOutcome);
+        this.updateStreaks(category);
+        return this.checkThresholds();
+    }
+    /** Reset all state. */
+    reset() {
+        this.approachHashes.clear();
+        this.outcomeHashes.clear();
+        this.stagnationStreak = 0;
+        this.stuckStreak = 0;
+        this.blocked = false;
+        this.blockVerdict = null;
+    }
+    classify(isNewApproach, isNewOutcome) {
+        if (isNewApproach && isNewOutcome)
+            return 'full_progress';
+        if (!isNewApproach && isNewOutcome)
+            return 'world_changed';
+        if (isNewApproach && !isNewOutcome)
+            return 'stuck';
+        return 'full_stagnation';
+    }
+    updateStreaks(category) {
+        switch (category) {
+            case 'full_progress':
+            case 'world_changed':
+                this.stagnationStreak = 0;
+                this.stuckStreak = 0;
+                break;
+            case 'stuck':
+                this.stuckStreak++;
+                this.stagnationStreak = 0;
+                break;
+            case 'full_stagnation':
+                this.stagnationStreak++;
+                this.stuckStreak = 0;
+                break;
+        }
+    }
+    checkThresholds() {
+        // Check block thresholds first
+        if (this.stagnationStreak >= this.config.stagnation.block) {
+            const verdict = {
+                action: 'block',
+                message: 'LOOP DETECTED: You have been repeating the same code with the same result. ' +
+                    'Execution is now blocked. Summarize what you have accomplished and stop.',
+                category: 'full_stagnation',
+            };
+            this.blocked = true;
+            this.blockVerdict = verdict;
+            return verdict;
+        }
+        if (this.stuckStreak >= this.config.stuck.block) {
+            const verdict = {
+                action: 'block',
+                message: 'LOOP DETECTED: You keep trying different approaches but getting the same result. ' +
+                    'Execution is now blocked. Summarize what you have accomplished and stop.',
+                category: 'stuck',
+            };
+            this.blocked = true;
+            this.blockVerdict = verdict;
+            return verdict;
+        }
+        // Check warn thresholds
+        if (this.stagnationStreak >= this.config.stagnation.warn) {
+            return {
+                action: 'warn',
+                message: 'WARNING: You are repeating the same code with the same result. ' +
+                    `Try a fundamentally different approach. (${this.stagnationStreak}/${this.config.stagnation.block} before block)`,
+                category: 'full_stagnation',
+            };
+        }
+        if (this.stuckStreak >= this.config.stuck.warn) {
+            return {
+                action: 'warn',
+                message: 'WARNING: Different approaches are producing the same result. ' +
+                    `Re-examine your assumptions. (${this.stuckStreak}/${this.config.stuck.block} before block)`,
+                category: 'stuck',
+            };
+        }
+        return { action: 'allow' };
+    }
+}
+//# sourceMappingURL=step-loop-detector.js.map

package/dist/session/step-loop-detector.js.map

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

package/dist/session/transport.d.ts

@@ -0,0 +1,24 @@
+import type { Session } from './types.js';
+/**
+ * A transport delivers messages between an external source and a session.
+ * It is responsible for:
+ * - Reading input from its source (stdin, HTTP, WebSocket, etc.)
+ * - Calling session.sendMessage() with each input
+ * - Delivering the response back to the source
+ * - Handling slash commands (including escalation approval)
+ * - Signaling when the conversation should end
+ *
+ * The transport does NOT own the session -- the caller creates the session
+ * and passes it to the transport. This allows the same session to be
+ * used with different transports (e.g., migrate from CLI to web mid-session).
+ */
+export interface Transport {
+    /**
+     * Starts the transport's message loop. Returns when the transport
+     * is done (user typed /quit, connection closed, etc.).
+     *
+     * The transport must handle errors from session.sendMessage()
+     * gracefully (display to user, continue accepting input).
+     */
+    run(session: Session): Promise<void>;
+}

package/dist/session/transport.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transport.js.map

package/dist/session/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/session/transport.ts"],"names":[],"mappings":""}

package/dist/session/truncate-result.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tool result truncation utility.
+ *
+ * Truncates oversized tool results before they reach the LLM to prevent
+ * "prompt is too long" errors. The audit log (written at the trusted
+ * process level) preserves full untruncated results for forensics.
+ *
+ * Strategy: serialize the value to JSON, measure that, and if it exceeds
+ * the budget, truncate the JSON string with a head/tail split.
+ */
+/** 100 KB ≈ 25K tokens, matching Claude Code's cap. */
+export declare const DEFAULT_RESULT_SIZE_LIMIT = 100000;
+/** Returns the configured result size limit (bytes). */
+export declare function getResultSizeLimit(): number;
+export interface TruncationResult {
+    value: unknown;
+    truncated: boolean;
+    originalSize: number;
+    finalSize: number;
+}
+/**
+ * Truncates a single string to fit within `maxBytes`, keeping ~80% from
+ * the head and ~20% from the tail with a marker in between.
+ */
+export declare function truncateString(s: string, maxBytes: number): string;
+/**
+ * Truncates a tool result value to fit within `budget` bytes.
+ *
+ * Serializes the value to JSON, and if it exceeds the budget, replaces
+ * it with a truncated string (head/tail with marker). When the value
+ * fits, it's returned as-is (zero-copy).
+ */
+export declare function truncateResult(value: unknown, budget?: number): TruncationResult;
+/** Formats bytes as a human-readable KB string. */
+export declare function formatKB(bytes: number): string;

package/dist/session/truncate-result.js

@@ -0,0 +1,71 @@
+/**
+ * Tool result truncation utility.
+ *
+ * Truncates oversized tool results before they reach the LLM to prevent
+ * "prompt is too long" errors. The audit log (written at the trusted
+ * process level) preserves full untruncated results for forensics.
+ *
+ * Strategy: serialize the value to JSON, measure that, and if it exceeds
+ * the budget, truncate the JSON string with a head/tail split.
+ */
+/** 100 KB ≈ 25K tokens, matching Claude Code's cap. */
+export const DEFAULT_RESULT_SIZE_LIMIT = 100_000;
+/** Returns the configured result size limit (bytes). */
+export function getResultSizeLimit() {
+    const envVal = process.env['RESULT_SIZE_LIMIT'];
+    if (envVal) {
+        const parsed = parseInt(envVal, 10);
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return DEFAULT_RESULT_SIZE_LIMIT;
+}
+/**
+ * Truncates a single string to fit within `maxBytes`, keeping ~80% from
+ * the head and ~20% from the tail with a marker in between.
+ */
+export function truncateString(s, maxBytes) {
+    const buf = Buffer.from(s, 'utf-8');
+    if (buf.length <= maxBytes)
+        return s;
+    const truncatedBytes = buf.length - maxBytes;
+    const realMarker = `\n[... truncated ${truncatedBytes} bytes ...]\n`;
+    const markerBytes = Buffer.byteLength(realMarker, 'utf-8');
+    const available = maxBytes - markerBytes;
+    if (available <= 0)
+        return realMarker;
+    const headBytes = Math.floor(available * 0.8);
+    const tailBytes = available - headBytes;
+    const head = buf.subarray(0, headBytes).toString('utf-8');
+    const tail = tailBytes > 0
+        ? buf.subarray(buf.length - tailBytes).toString('utf-8')
+        : '';
+    return head + realMarker + tail;
+}
+/**
+ * Truncates a tool result value to fit within `budget` bytes.
+ *
+ * Serializes the value to JSON, and if it exceeds the budget, replaces
+ * it with a truncated string (head/tail with marker). When the value
+ * fits, it's returned as-is (zero-copy).
+ */
+export function truncateResult(value, budget) {
+    const limit = budget ?? getResultSizeLimit();
+    const json = JSON.stringify(value);
+    // JSON.stringify returns undefined for undefined input
+    if (json === undefined) {
+        return { value, truncated: false, originalSize: 0, finalSize: 0 };
+    }
+    const originalSize = Buffer.byteLength(json, 'utf-8');
+    if (originalSize <= limit) {
+        return { value, truncated: false, originalSize, finalSize: originalSize };
+    }
+    const truncated = truncateString(json, limit);
+    const finalSize = Buffer.byteLength(truncated, 'utf-8');
+    return { value: truncated, truncated: true, originalSize, finalSize };
+}
+/** Formats bytes as a human-readable KB string. */
+export function formatKB(bytes) {
+    return `${(bytes / 1024).toFixed(1)}KB`;
+}
+//# sourceMappingURL=truncate-result.js.map

package/dist/session/truncate-result.js.map

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

package/dist/session/types.d.ts

@@ -0,0 +1,220 @@
+import type { IronCurtainConfig } from '../config/types.js';
+import type { Sandbox } from '../sandbox/index.js';
+import type { ResolvedResourceBudgetConfig } from '../config/user-config.js';
+import type { CumulativeBudgetSnapshot } from './resource-budget-tracker.js';
+/**
+ * Unique identifier for a session. Branded to prevent accidental
+ * mixing with other string identifiers.
+ */
+export type SessionId = string & {
+    readonly __brand: 'SessionId';
+};
+/** Creates a new unique SessionId. */
+export declare function createSessionId(): SessionId;
+/**
+ * The possible states a session can be in. Linear progression:
+ * initializing -> ready -> (processing <-> ready) -> closed.
+ *
+ * - initializing: sandbox and resources being set up
+ * - ready: accepting messages
+ * - processing: a message is being processed (generateText in flight)
+ * - closed: resources released, no more messages accepted
+ */
+export type SessionStatus = 'initializing' | 'ready' | 'processing' | 'closed';
+/**
+ * A single turn in the conversation. Captures what the user said,
+ * what the agent responded, and metadata about the turn.
+ */
+export interface ConversationTurn {
+    /** 1-based turn number within this session. */
+    readonly turnNumber: number;
+    /** The user's input for this turn. */
+    readonly userMessage: string;
+    /** The agent's final text response for this turn. */
+    readonly assistantResponse: string;
+    /** Token usage for this turn (prompt + completion). */
+    readonly usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    /** ISO 8601 timestamp when this turn started. */
+    readonly timestamp: string;
+}
+/**
+ * A diagnostic event emitted during message processing.
+ * Transports decide how (or whether) to display these.
+ */
+export type DiagnosticEvent = {
+    readonly kind: 'tool_call';
+    readonly toolName: string;
+    readonly preview: string;
+} | {
+    readonly kind: 'agent_text';
+    readonly preview: string;
+} | {
+    readonly kind: 'step_finish';
+    readonly stepIndex: number;
+} | {
+    readonly kind: 'loop_detection';
+    readonly action: 'warn' | 'block';
+    readonly category: string;
+    readonly message: string;
+} | {
+    readonly kind: 'result_truncation';
+    readonly originalKB: number;
+    readonly finalKB: number;
+} | {
+    readonly kind: 'budget_warning';
+    readonly dimension: string;
+    readonly percentUsed: number;
+    readonly message: string;
+} | {
+    readonly kind: 'budget_exhausted';
+    readonly dimension: string;
+    readonly message: string;
+} | {
+    readonly kind: 'message_compaction';
+    readonly originalMessageCount: number;
+    readonly newMessageCount: number;
+    readonly summaryPreview: string;
+};
+/**
+ * Budget status: current consumption snapshot plus configured limits.
+ * Exposed to transports for the /budget command and end-of-session summary.
+ */
+export interface BudgetStatus {
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly totalTokens: number;
+    readonly stepCount: number;
+    readonly elapsedSeconds: number;
+    readonly estimatedCostUsd: number;
+    readonly limits: ResolvedResourceBudgetConfig;
+    readonly cumulative: CumulativeBudgetSnapshot;
+}
+/**
+ * Read-only snapshot of session state. Exposed to transports
+ * and external observers without giving them mutation access.
+ */
+export interface SessionInfo {
+    readonly id: SessionId;
+    readonly status: SessionStatus;
+    readonly turnCount: number;
+    readonly createdAt: string;
+}
+/**
+ * Factory function for creating sandbox instances.
+ * The default creates a real Sandbox wrapping UTCP Code Mode's V8 isolate.
+ * Tests provide a factory returning a mock.
+ */
+export type SandboxFactory = (config: IronCurtainConfig) => Promise<Sandbox>;
+/**
+ * Escalation request data surfaced to the transport.
+ * Decoupled from ToolCallRequest to avoid leaking internal types
+ * to transport implementations.
+ */
+export interface EscalationRequest {
+    /** Unique ID for this escalation, used to match approve/deny responses. */
+    readonly escalationId: string;
+    readonly toolName: string;
+    readonly serverName: string;
+    readonly arguments: Record<string, unknown>;
+    readonly reason: string;
+}
+/**
+ * Options for creating a session. Extends the base config with
+ * session-specific overrides.
+ */
+export interface SessionOptions {
+    /** Base configuration. If omitted, loaded from environment. */
+    config?: IronCurtainConfig;
+    /** If provided, reuses the sandbox from this previous session via symlink. */
+    resumeSessionId?: string;
+    /**
+     * Maximum number of messages to retain in history before pruning.
+     * Defined as an extension point but not enforced in the initial
+     * implementation. When the context window is exceeded,
+     * generateText() throws and the error propagates to the transport.
+     */
+    maxHistoryMessages?: number;
+    /**
+     * Factory for creating sandbox instances.
+     * Default: creates a real Sandbox (UTCP Code Mode V8 isolate).
+     * Tests provide a factory returning a mock.
+     */
+    sandboxFactory?: SandboxFactory;
+    /**
+     * Callback invoked when the proxy surfaces an escalation.
+     * The transport uses this to notify the user and collect approval.
+     * If not provided, escalations are auto-denied.
+     */
+    onEscalation?: (request: EscalationRequest) => void;
+    /**
+     * Callback invoked during message processing with diagnostic events.
+     * Transports use this to display progress (e.g., tool call previews).
+     * If not provided, diagnostics are silently dropped.
+     */
+    onDiagnostic?: (event: DiagnosticEvent) => void;
+}
+/**
+ * The core session contract. A session is a stateful conversation
+ * that owns its sandbox, policy engine, and message history.
+ *
+ * Invariants:
+ * - sendMessage() can only be called when status is 'ready'
+ * - sendMessage() is not reentrant (status transitions to 'processing')
+ * - After close(), no methods except getInfo() are valid
+ * - The session ID is unique and immutable for the session's lifetime
+ */
+export interface Session {
+    /** Returns a read-only snapshot of session state. */
+    getInfo(): SessionInfo;
+    /**
+     * Sends a user message and returns the agent's response.
+     *
+     * Appends the user message to conversation history, calls the LLM
+     * with the full history, appends the response messages, and returns
+     * the agent's text.
+     *
+     * @throws {SessionNotReadyError} if status is not 'ready'
+     * @throws {SessionClosedError} if session has been closed
+     */
+    sendMessage(userMessage: string): Promise<string>;
+    /**
+     * Returns the conversation history as turn summaries.
+     * Does not expose raw ModelMessage[] to avoid coupling
+     * callers to the AI SDK's internal message format.
+     */
+    getHistory(): readonly ConversationTurn[];
+    /**
+     * Returns accumulated diagnostic events from all turns.
+     * Transports can use this for a /logs command or similar.
+     */
+    getDiagnosticLog(): readonly DiagnosticEvent[];
+    /**
+     * Resolves a pending escalation. Called by the transport
+     * when the user approves or denies via a slash command.
+     *
+     * Writes the response to the escalation directory so the
+     * proxy process can pick it up and continue.
+     *
+     * @throws {Error} if no escalation with this ID is pending
+     */
+    resolveEscalation(escalationId: string, decision: 'approved' | 'denied'): Promise<void>;
+    /**
+     * Returns any currently pending escalation, or undefined.
+     */
+    getPendingEscalation(): EscalationRequest | undefined;
+    /**
+     * Returns current resource budget consumption and configured limits.
+     * Used by transports for /budget display and end-of-session summary.
+     */
+    getBudgetStatus(): BudgetStatus;
+    /**
+     * Releases all session resources: sandbox, MCP connections,
+     * audit log, escalation directory. Idempotent -- safe to call
+     * multiple times. After close(), status becomes 'closed'.
+     */
+    close(): Promise<void>;
+}

package/dist/session/types.js

@@ -0,0 +1,6 @@
+import { randomUUID } from 'node:crypto';
+/** Creates a new unique SessionId. */
+export function createSessionId() {
+    return randomUUID();
+}
+//# sourceMappingURL=types.js.map

package/dist/session/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/session/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAYzC,sCAAsC;AACtC,MAAM,UAAU,eAAe;IAC7B,OAAO,UAAU,EAAe,CAAC;AACnC,CAAC"}

package/dist/trusted-process/audit-log.d.ts

@@ -0,0 +1,7 @@
+import type { AuditEntry } from '../types/audit.js';
+export declare class AuditLog {
+    private stream;
+    constructor(path: string);
+    log(entry: AuditEntry): void;
+    close(): Promise<void>;
+}

package/dist/trusted-process/audit-log.js

@@ -0,0 +1,21 @@
+import { createWriteStream } from 'node:fs';
+export class AuditLog {
+    stream;
+    constructor(path) {
+        this.stream = createWriteStream(path, { flags: 'a' });
+    }
+    log(entry) {
+        this.stream.write(JSON.stringify(entry) + '\n');
+    }
+    async close() {
+        return new Promise((resolve, reject) => {
+            this.stream.end((err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+    }
+}
+//# sourceMappingURL=audit-log.js.map

package/dist/trusted-process/audit-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-log.js","sourceRoot":"","sources":["../../src/trusted-process/audit-log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAoB,MAAM,SAAS,CAAC;AAG9D,MAAM,OAAO,QAAQ;IACX,MAAM,CAAc;IAE5B,YAAY,IAAY;QACtB,IAAI,CAAC,MAAM,GAAG,iBAAiB,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACxD,CAAC;IAED,GAAG,CAAC,KAAiB;QACnB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,KAAK;QACT,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAA6B,EAAE,EAAE;gBAChD,IAAI,GAAG;oBAAE,MAAM,CAAC,GAAG,CAAC,CAAC;;oBAChB,OAAO,EAAE,CAAC;YACjB,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/trusted-process/call-circuit-breaker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CallCircuitBreaker -- Proxy-level rate limiter for MCP tool calls.
+ *
+ * Protects against runaway sandbox code that hammers the same tool
+ * with identical arguments. Uses a sliding-window approach: if the
+ * same (tool, argsHash) pair appears more than `threshold` times
+ * within `windowMs`, the call is denied.
+ *
+ * Runs AFTER policy evaluation so every call is always audited.
+ */
+export interface CircuitBreakerConfig {
+    windowMs: number;
+    threshold: number;
+}
+export type CircuitBreakerVerdict = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+export declare class CallCircuitBreaker {
+    private readonly config;
+    private windows;
+    constructor(config?: Partial<CircuitBreakerConfig>);
+    /**
+     * Check whether a tool call should be allowed.
+     *
+     * @returns `{ allowed: true }` or `{ allowed: false, reason: string }`
+     */
+    check(toolName: string, args: Record<string, unknown>): CircuitBreakerVerdict;
+    /** Reset all state. */
+    reset(): void;
+}