@gethelio/proxy 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1874 @@
+import { z } from 'zod';
+import { Hono } from 'hono';
+import { ServerType } from '@hono/node-server';
+import { KnownBlock } from '@slack/web-api';
+
+declare const VERSION: string;
+
+declare const policiesSchema: z.ZodObject<{
+    default: z.ZodDefault<z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>>;
+    flag_destructive: z.ZodOptional<z.ZodEnum<{
+        require_approval: "require_approval";
+        log: "log";
+    }>>;
+    dry_run: z.ZodDefault<z.ZodBoolean>;
+    rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        match: z.ZodObject<{
+            tool: z.ZodOptional<z.ZodString>;
+            annotations: z.ZodOptional<z.ZodObject<{
+                readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+                destructiveHint: z.ZodOptional<z.ZodBoolean>;
+                idempotentHint: z.ZodOptional<z.ZodBoolean>;
+                openWorldHint: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>;
+            input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                eq: z.ZodOptional<z.ZodUnknown>;
+                neq: z.ZodOptional<z.ZodUnknown>;
+                gt: z.ZodOptional<z.ZodNumber>;
+                gte: z.ZodOptional<z.ZodNumber>;
+                lt: z.ZodOptional<z.ZodNumber>;
+                lte: z.ZodOptional<z.ZodNumber>;
+                contains: z.ZodOptional<z.ZodString>;
+                regex: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>>;
+            environment: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        action: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+            require_approval: "require_approval";
+            rate_limit: "rate_limit";
+            spend_limit: "spend_limit";
+            dry_run: "dry_run";
+        }>;
+        approval: z.ZodOptional<z.ZodObject<{
+            channel: z.ZodString;
+            timeout: z.ZodOptional<z.ZodString>;
+            delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            escalation_after: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        evidence: z.ZodOptional<z.ZodObject<{
+            requires: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        requires_success: z.ZodOptional<z.ZodBoolean>;
+        limits: z.ZodOptional<z.ZodObject<{
+            max_calls: z.ZodOptional<z.ZodNumber>;
+            window: z.ZodOptional<z.ZodString>;
+            key: z.ZodOptional<z.ZodEnum<{
+                tool: "tool";
+                agent: "agent";
+                session: "session";
+            }>>;
+            max_spend: z.ZodOptional<z.ZodObject<{
+                field: z.ZodString;
+                limit: z.ZodNumber;
+                currency: z.ZodString;
+                window: z.ZodString;
+                key: z.ZodOptional<z.ZodEnum<{
+                    tool: "tool";
+                    agent: "agent";
+                    session: "session";
+                }>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        feedback: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            suggestion: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    hot_reload: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+declare const approvalChannelSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"slack">;
+    name: z.ZodOptional<z.ZodString>;
+    bot_token: z.ZodString;
+    signing_secret: z.ZodString;
+    channel: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"webhook">;
+    name: z.ZodOptional<z.ZodString>;
+    url: z.ZodString;
+    secret: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"dashboard">;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+/** Zod schema for the complete `helio.yaml` configuration file. */
+declare const helioConfigSchema: z.ZodObject<{
+    version: z.ZodLiteral<"1">;
+    upstream: z.ZodObject<{
+        url: z.ZodString;
+        transport: z.ZodDefault<z.ZodEnum<{
+            "streamable-http": "streamable-http";
+            sse: "sse";
+            stdio: "stdio";
+        }>>;
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        connect_timeout: z.ZodDefault<z.ZodString>;
+        request_timeout: z.ZodDefault<z.ZodString>;
+        forward_headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    listen: z.ZodPrefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+        host: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    dashboard: z.ZodPrefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        port: z.ZodDefault<z.ZodNumber>;
+        host: z.ZodDefault<z.ZodString>;
+        api_secret: z.ZodOptional<z.ZodString>;
+        allow_open_mode: z.ZodDefault<z.ZodBoolean>;
+        sse_heartbeat_interval: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    environment: z.ZodOptional<z.ZodString>;
+    policies: z.ZodPrefault<z.ZodObject<{
+        default: z.ZodDefault<z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+        }>>;
+        flag_destructive: z.ZodOptional<z.ZodEnum<{
+            require_approval: "require_approval";
+            log: "log";
+        }>>;
+        dry_run: z.ZodDefault<z.ZodBoolean>;
+        rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            match: z.ZodObject<{
+                tool: z.ZodOptional<z.ZodString>;
+                annotations: z.ZodOptional<z.ZodObject<{
+                    readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+                    destructiveHint: z.ZodOptional<z.ZodBoolean>;
+                    idempotentHint: z.ZodOptional<z.ZodBoolean>;
+                    openWorldHint: z.ZodOptional<z.ZodBoolean>;
+                }, z.core.$strict>>;
+                input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    eq: z.ZodOptional<z.ZodUnknown>;
+                    neq: z.ZodOptional<z.ZodUnknown>;
+                    gt: z.ZodOptional<z.ZodNumber>;
+                    gte: z.ZodOptional<z.ZodNumber>;
+                    lt: z.ZodOptional<z.ZodNumber>;
+                    lte: z.ZodOptional<z.ZodNumber>;
+                    contains: z.ZodOptional<z.ZodString>;
+                    regex: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>>;
+                environment: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            action: z.ZodEnum<{
+                allow: "allow";
+                deny: "deny";
+                require_approval: "require_approval";
+                rate_limit: "rate_limit";
+                spend_limit: "spend_limit";
+                dry_run: "dry_run";
+            }>;
+            approval: z.ZodOptional<z.ZodObject<{
+                channel: z.ZodString;
+                timeout: z.ZodOptional<z.ZodString>;
+                delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                escalation_after: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            evidence: z.ZodOptional<z.ZodObject<{
+                requires: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+            requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            requires_success: z.ZodOptional<z.ZodBoolean>;
+            limits: z.ZodOptional<z.ZodObject<{
+                max_calls: z.ZodOptional<z.ZodNumber>;
+                window: z.ZodOptional<z.ZodString>;
+                key: z.ZodOptional<z.ZodEnum<{
+                    tool: "tool";
+                    agent: "agent";
+                    session: "session";
+                }>>;
+                max_spend: z.ZodOptional<z.ZodObject<{
+                    field: z.ZodString;
+                    limit: z.ZodNumber;
+                    currency: z.ZodString;
+                    window: z.ZodString;
+                    key: z.ZodOptional<z.ZodEnum<{
+                        tool: "tool";
+                        agent: "agent";
+                        session: "session";
+                    }>>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            feedback: z.ZodOptional<z.ZodObject<{
+                message: z.ZodString;
+                suggestion: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>;
+        hot_reload: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    approval: z.ZodPrefault<z.ZodObject<{
+        timeout: z.ZodDefault<z.ZodString>;
+        default_on_timeout: z.ZodDefault<z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+        }>>;
+        channels: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"slack">;
+            name: z.ZodOptional<z.ZodString>;
+            bot_token: z.ZodString;
+            signing_secret: z.ZodString;
+            channel: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"webhook">;
+            name: z.ZodOptional<z.ZodString>;
+            url: z.ZodString;
+            secret: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"dashboard">;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "type">>>;
+    }, z.core.$strip>>;
+    audit: z.ZodPrefault<z.ZodObject<{
+        storage: z.ZodDefault<z.ZodEnum<{
+            sqlite: "sqlite";
+        }>>;
+        path: z.ZodDefault<z.ZodString>;
+        retention: z.ZodDefault<z.ZodString>;
+        include_responses: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    sdk: z.ZodPrefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        port: z.ZodDefault<z.ZodNumber>;
+        host: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Fully validated and defaulted Helio configuration. */
+type HelioConfig = z.infer<typeof helioConfigSchema>;
+/** An approval channel configuration (slack, webhook, or dashboard). */
+type ApprovalChannel$1 = z.infer<typeof approvalChannelSchema>;
+/** The policies section of the config. */
+type PoliciesConfig = z.infer<typeof policiesSchema>;
+
+/** Structured error for configuration loading failures. */
+declare class ConfigError extends Error {
+    readonly details?: ReadonlyArray<{
+        path: string;
+        message: string;
+    }> | undefined;
+    constructor(message: string, details?: ReadonlyArray<{
+        path: string;
+        message: string;
+    }> | undefined);
+}
+/**
+ * Load and validate a `helio.yaml` configuration file.
+ *
+ * Pipeline: read file → parse YAML → interpolate env vars → validate with Zod.
+ *
+ * @param filePath - Path to the YAML configuration file.
+ * @param env - Optional environment variables for `${VAR}` interpolation.
+ * @returns The fully validated and defaulted configuration object.
+ * @throws {ConfigError} On file read error, YAML parse error, missing env var, or validation failure.
+ */
+declare function loadConfig(filePath: string, env?: Record<string, string | undefined>): Promise<HelioConfig>;
+
+/** Pre-compiled glob matcher for tool names. */
+interface ToolMatcher {
+    /** Original glob pattern string (e.g. "send_*") for audit/logging. */
+    readonly pattern: string;
+    /** Compiled test function — returns true if the tool name matches. */
+    readonly test: (toolName: string) => boolean;
+}
+/** Compiled annotation match conditions. */
+interface AnnotationMatch {
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+}
+/**
+ * A single flattened input condition.
+ *
+ * Config format `{ '$.amount': { gt: 10, lt: 100 } }` is flattened into
+ * two separate InputCondition entries — one per operator — to simplify
+ * the engine's evaluation loop.
+ */
+interface InputCondition {
+    /** JSONPath string (e.g. "$.amount"). */
+    readonly path: string;
+    /** Comparison operator. */
+    readonly operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'regex';
+    /** The comparison value. */
+    readonly value: unknown;
+    /** Pre-compiled RegExp when operator is 'regex'. */
+    readonly regex?: RegExp;
+}
+/** Compiled match block for a policy rule. */
+interface CompiledMatch {
+    readonly tool?: ToolMatcher;
+    readonly annotations?: AnnotationMatch;
+    /** Flattened list of input conditions (one entry per path+operator pair). */
+    readonly input?: readonly InputCondition[];
+    readonly environment?: string;
+}
+/** Compiled approval configuration with durations as milliseconds. */
+interface CompiledApproval {
+    readonly channel: string;
+    readonly timeoutMs?: number;
+    readonly delegates?: readonly string[];
+    readonly escalationAfterMs?: number;
+}
+/** Compiled spend limit with window as milliseconds. */
+interface CompiledSpendLimit {
+    readonly field: string;
+    readonly limit: number;
+    readonly currency: string;
+    readonly windowMs: number;
+    readonly key?: 'tool' | 'agent' | 'session';
+}
+/** Compiled rate/spend limit configuration. */
+interface CompiledLimits {
+    readonly maxCalls?: number;
+    readonly windowMs?: number;
+    readonly key?: 'tool' | 'agent' | 'session';
+    readonly maxSpend?: CompiledSpendLimit;
+}
+/** Policy action types. */
+type PolicyAction = 'allow' | 'deny' | 'require_approval' | 'rate_limit' | 'spend_limit' | 'dry_run';
+/** A fully compiled policy rule ready for engine evaluation. */
+interface CompiledPolicyRule {
+    /** Original position in the rules array (for audit/debugging). */
+    readonly index: number;
+    readonly name?: string;
+    readonly match: CompiledMatch;
+    readonly action: PolicyAction;
+    readonly approval?: CompiledApproval;
+    readonly evidence?: {
+        readonly requires: readonly string[];
+    };
+    readonly requires?: readonly string[];
+    /**
+     * When `requires` is set, controls whether dependency calls must have
+     * succeeded upstream. Undefined defaults to `true` at the check site — a
+     * failed call does NOT satisfy the dependency by default. Set to `false`
+     * in config (`requires_success: false`) to opt out of the outcome check
+     * and treat any attempted call as satisfying the dependency.
+     */
+    readonly requiresSuccess?: boolean;
+    readonly limits?: CompiledLimits;
+    readonly feedback?: {
+        readonly message: string;
+        readonly suggestion?: string;
+    };
+}
+/** Top-level compiled policy — what the engine consumes. */
+interface CompiledPolicy {
+    readonly defaultAction: 'allow' | 'deny';
+    readonly flagDestructive?: 'log' | 'require_approval';
+    readonly dryRun?: boolean;
+    readonly rules: readonly CompiledPolicyRule[];
+}
+/** A non-fatal warning produced during policy compilation. */
+interface PolicyParseWarning {
+    readonly ruleIndex: number;
+    readonly ruleName?: string;
+    readonly message: string;
+}
+/** Result of compiling a PoliciesConfig into engine-ready form. */
+interface CompilePoliciesResult {
+    readonly policy: CompiledPolicy;
+    readonly warnings: readonly PolicyParseWarning[];
+}
+/**
+ * Tool annotation hints as reported by the MCP server's tools/list response.
+ *
+ * Mirrors the MCP spec's annotation boolean fields. Defined locally to avoid
+ * a runtime dependency on `@modelcontextprotocol/sdk`.
+ */
+interface ToolAnnotationHints {
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+}
+/**
+ * Context passed to matchers when evaluating a policy rule against a request.
+ *
+ * Built by the engine from the MCP request and cached tool metadata.
+ * All fields are optional — not every MCP method involves a tool call.
+ */
+interface MatchContext {
+    /** The tool name from the tools/call request params. */
+    readonly toolName?: string;
+    /** Annotations from the MCP tool's metadata (tools/list cache). */
+    readonly annotations?: ToolAnnotationHints;
+    /** The `arguments` object from the tools/call request params. */
+    readonly toolArguments?: Readonly<Record<string, unknown>>;
+    /** The configured environment label (e.g. "production", "staging"). */
+    readonly environment?: string;
+}
+
+/** A JSON-RPC 2.0 request object. */
+interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: string | number | null;
+    method: string;
+    params?: unknown;
+}
+/** A parsed MCP request enriched with session context. */
+interface McpRequest extends JsonRpcRequest {
+    /** MCP session ID extracted from the `Mcp-Session-Id` header. */
+    sessionId?: string;
+    /** Per-request headers to forward to upstream (e.g. Authorization, X-* headers). */
+    headers?: Record<string, string>;
+    /** Abort signal tied to the downstream client request lifecycle. */
+    signal?: AbortSignal;
+}
+/** The response returned by an MCP forwarder. */
+interface McpResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+}
+/** The result of forwarding an MCP request, including timing metadata. */
+interface ForwardResult {
+    response: McpResponse;
+    /** Time in milliseconds the upstream request took. */
+    durationMs: number;
+}
+/** Interface for forwarding MCP requests to an upstream server. */
+interface McpForwarder {
+    forward(request: McpRequest): Promise<ForwardResult>;
+}
+
+/** Handle returned by `startServer` for lifecycle management. */
+interface ServerHandle {
+    server: ServerType;
+    close: () => Promise<void>;
+}
+/**
+ * Optional sub-apps to mount on the main proxy server.
+ *
+ * The main MCP port is the agent-facing edge and must stay minimal. Operator
+ * read APIs (approval REST, rate/spend limit status) deliberately live on
+ * the dashboard sideband instead, so that an agent speaking `/mcp` cannot
+ * enumerate budget state to time attacks or self-approve its own pending
+ * tickets on the same origin. Only Slack interactive action callbacks
+ * belong here — they are public inbound webhooks from Slack's servers, not
+ * operator read endpoints.
+ */
+interface CreateAppOptions {
+    /** Slack interactive action handler (mounted at /slack/actions). */
+    slackActionApp?: Hono;
+}
+/**
+ * Create a Hono app configured with the MCP proxy routes.
+ *
+ * @param _config - The validated Helio configuration.
+ * @param forwarder - The MCP forwarder to delegate requests to.
+ * @param options - Optional sub-apps to mount.
+ */
+declare function createApp(config: HelioConfig, forwarder: McpForwarder, options?: CreateAppOptions): Hono;
+/**
+ * Start the HTTP server on the configured host and port.
+ *
+ * @param app - The Hono app to serve.
+ * @param config - The validated Helio configuration (uses `listen.port` and `listen.host`).
+ * @returns A handle with the underlying server and a `close()` method for graceful shutdown.
+ */
+declare function startServer(app: Hono, config: HelioConfig): ServerHandle;
+/**
+ * Start the sideband HTTP server for the SDK API.
+ *
+ * Binds to 127.0.0.1 by default (local-only) on the configured SDK port.
+ */
+declare function startSidebandServer(app: Hono, port: number, host?: string): ServerHandle;
+
+/** Options for constructing an UpstreamForwarder. */
+interface UpstreamForwarderOptions {
+    /** The upstream MCP server URL (e.g. "http://localhost:8080/mcp"). */
+    url: string;
+    /** Static headers to include on every upstream request (e.g. API keys). */
+    headers?: Record<string, string>;
+    /** Maximum time to wait for an upstream request before aborting. */
+    requestTimeoutMs?: number;
+}
+/**
+ * Forward MCP requests to an upstream server via HTTP.
+ *
+ * Sends JSON-RPC POST requests to the configured URL, passes through
+ * session IDs and per-request headers, and captures request timing.
+ */
+declare class UpstreamForwarder implements McpForwarder {
+    private readonly url;
+    private readonly staticHeaders;
+    private readonly requestTimeoutMs;
+    constructor(options: UpstreamForwarderOptions);
+    forward(request: McpRequest): Promise<ForwardResult>;
+}
+
+/** Options for constructing an SseUpstreamForwarder. */
+interface SseUpstreamForwarderOptions {
+    /** The upstream SSE server URL (e.g. "http://localhost:8080/sse"). */
+    url: string;
+    /** Static headers to include on every request. */
+    headers?: Record<string, string>;
+    /** Timeout in milliseconds for individual requests. */
+    requestTimeoutMs?: number;
+    /** Timeout in milliseconds while establishing the SSE connection. */
+    connectTimeoutMs?: number;
+}
+/**
+ * Forward MCP requests to an upstream server that speaks SSE transport.
+ *
+ * Connects via GET to establish an SSE stream, learns the POST endpoint
+ * from the `endpoint` event, and correlates responses via JSON-RPC `id`.
+ */
+declare class SseUpstreamForwarder implements McpForwarder {
+    private readonly url;
+    private readonly staticHeaders;
+    private readonly pending;
+    private readonly requestTimeoutMs;
+    private readonly connectTimeoutMs;
+    private postUrl;
+    private abortController;
+    private connected;
+    constructor(options: SseUpstreamForwarderOptions);
+    /** Connect to the upstream SSE server and learn the POST endpoint. */
+    connect(): Promise<void>;
+    forward(request: McpRequest): Promise<ForwardResult>;
+    /** Close the SSE connection and reject all pending requests. */
+    close(): Promise<void>;
+    /** Resolve a potentially relative endpoint URL against the upstream base URL. */
+    private resolveEndpointUrl;
+    /** Consume the SSE ReadableStream, parsing events. */
+    private consumeStream;
+    /** Handle a `message` event from the SSE stream. */
+    private onMessage;
+}
+
+/** Options for constructing a StdioForwarder. */
+interface StdioForwarderOptions {
+    /** The command to spawn (e.g. "node", "python"). */
+    command: string;
+    /** Arguments to pass to the command. */
+    args?: string[];
+    /** Maximum number of auto-restart attempts on crash. */
+    maxRetries?: number;
+    /** Delay in milliseconds between restart attempts. */
+    retryDelayMs?: number;
+    /** Timeout in milliseconds for individual requests. */
+    requestTimeoutMs?: number;
+}
+/**
+ * Forward MCP requests to an upstream server via stdio.
+ *
+ * Spawns a child process and communicates using newline-delimited
+ * JSON-RPC on stdin/stdout.
+ */
+declare class StdioForwarder implements McpForwarder {
+    private readonly command;
+    private readonly args;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly pending;
+    private child;
+    private buffer;
+    private retryCount;
+    private dead;
+    private closing;
+    constructor(options: StdioForwarderOptions);
+    /** Spawn the child process and set up event handlers. */
+    start(): Promise<void>;
+    forward(request: McpRequest): Promise<ForwardResult>;
+    /** Gracefully close the child process. */
+    close(): Promise<void>;
+    /** Handle incoming data from child stdout, buffering partial lines. */
+    private onData;
+    /** Process a complete line from stdout. */
+    private onLine;
+    /** Handle unexpected child process exit (crash). */
+    private onUnexpectedExit;
+}
+
+/**
+ * Compile a validated PoliciesConfig into engine-ready form.
+ *
+ * Transforms raw config types into compiled types with pre-built glob
+ * matchers, pre-compiled regexes, and pre-parsed durations. Returns
+ * warnings for semantic issues (e.g. missing approval config).
+ *
+ * @throws {PolicyParseError} On invalid glob patterns or regex strings.
+ */
+declare function compilePolicies(config: PoliciesConfig): CompilePoliciesResult;
+
+/**
+ * Error thrown when policy compilation fails due to an invalid rule.
+ *
+ * Includes the rule index and optional name for clear error reporting.
+ */
+declare class PolicyParseError extends Error {
+    readonly ruleIndex: number;
+    readonly ruleName?: string;
+    constructor(message: string, ruleIndex: number, ruleName?: string);
+}
+
+/**
+ * Evaluate whether a compiled policy rule matches the given context.
+ *
+ * All present conditions in the rule's match block are AND'd together.
+ * A condition that is absent/undefined in the CompiledMatch is treated
+ * as "don't care" — it always passes. Short-circuits on the first false.
+ */
+declare function matchRule(rule: CompiledPolicyRule, ctx: MatchContext): boolean;
+
+/** The result of evaluating a tools/call request against the compiled policy. */
+interface PolicyDecision {
+    /** The action dictated by the matched rule (or the default policy). */
+    readonly action: PolicyAction;
+    /** The rule that matched, if any. Undefined when the default policy was applied. */
+    readonly matchedRule?: CompiledPolicyRule;
+    /** Human-readable explanation of the decision. */
+    readonly reason: string;
+}
+/**
+ * Evaluate a tools/call request against the compiled policy.
+ *
+ * Iterates the policy rules in definition order and returns the decision from
+ * the first matching rule (first-match-wins). If no rule matches, the policy's
+ * default action is applied.
+ *
+ * This function is pure and synchronous — no I/O, no side effects. It is the
+ * hot path and must complete in well under 1ms for any reasonable rule count.
+ */
+declare function evaluatePolicy(policy: CompiledPolicy, ctx: MatchContext): PolicyDecision;
+
+/** A single audit log entry recording a tool call and its governance outcome. */
+interface AuditRecord {
+    /** Unique record identifier (UUID v4). */
+    readonly id: string;
+    /** ISO 8601 timestamp of when the tool call was received by the proxy. */
+    readonly timestamp: string;
+    /** MCP session ID from the Mcp-Session-Id header, if present. */
+    readonly session_id: string | null;
+    /** Agent identifier from config or request header, if present. */
+    readonly agent_id: string | null;
+    /** Runtime environment label configured on proxy startup, if set. */
+    readonly environment: string | null;
+    /** The name of the tool that was called. */
+    readonly tool_name: string;
+    /** The arguments passed to the tool call. */
+    readonly tool_input: Record<string, unknown>;
+    /** The policy engine's decision: allow, deny, require_approval, etc. */
+    readonly policy_decision: string;
+    /** Structured block reason (when blocked), e.g. evidence_expired. */
+    readonly block_reason: string | null;
+    /** Name of the policy rule that matched, if any. */
+    readonly matched_rule: string | null;
+    /** Index of the matched rule in config order, if any. */
+    readonly matched_rule_index: number | null;
+    /** Evidence context from the evidence grounding system. */
+    readonly evidence_chain: Record<string, unknown> | null;
+    /** Approval workflow status: pending, approved, denied, timeout. */
+    readonly approval_status: string | null;
+    /** Identity of the approver, if approval was granted. */
+    readonly approved_by: string | null;
+    /**
+     * Upstream MCP server response. When `audit.include_responses` is true,
+     * this is the full JSON-RPC response body. When false, a {@link ResponseSummary}
+     * with only success/error status and content types. Null for denied calls
+     * (no upstream request was made).
+     */
+    readonly upstream_response: unknown;
+    /** Error message from upstream, if the call failed. */
+    readonly upstream_error: string | null;
+    /** HTTP status code returned by upstream, if a response was received. */
+    readonly upstream_http_status: number | null;
+    /** Time in milliseconds the upstream request took. */
+    readonly upstream_latency_ms: number | null;
+    /** End-to-end time from request receipt to final response. */
+    readonly total_duration_ms: number;
+    /** Time spent waiting in the approval queue, if applicable. */
+    readonly approval_wait_ms: number;
+    /** Proxy compute time excluding approval waits and upstream processing. */
+    readonly proxy_compute_ms: number;
+    /** Whether the tool was flagged as potentially destructive (destructiveHint). */
+    readonly flagged_destructive: boolean;
+    /** Whether this record was produced in dry-run mode. */
+    readonly dry_run: boolean;
+    /** ISO 8601 timestamp of when the record was persisted. */
+    readonly created_at: string;
+}
+/** Fields available for filtering audit record queries. */
+interface AuditQueryFilters {
+    /** Filter by tool name (exact match). */
+    readonly tool_name?: string;
+    /** Filter by policy decision (exact match). */
+    readonly policy_decision?: string;
+    /** Filter by block reason (exact match). */
+    readonly block_reason?: string;
+    /** Filter by whether a call was blocked (block_reason non-null). */
+    readonly blocked?: boolean;
+    /** Filter by session ID (exact match). */
+    readonly session_id?: string;
+    /** Filter by agent ID (exact match). */
+    readonly agent_id?: string;
+    /** Include only records created at or after this ISO 8601 timestamp. */
+    readonly from?: string;
+    /** Include only records created at or before this ISO 8601 timestamp. */
+    readonly to?: string;
+    /** Include only records flagged as destructive (true) or not (false). */
+    readonly flagged_destructive?: boolean;
+    /** Include only dry-run records (true) or non-dry-run records (false). */
+    readonly dry_run?: boolean;
+    /** Include only records where upstream HTTP status is >= this value. */
+    readonly upstream_status_min?: number;
+    /** Include only records where upstream HTTP status is <= this value. */
+    readonly upstream_status_max?: number;
+}
+/** Pagination options for list queries. */
+interface AuditPaginationOptions {
+    /** Maximum number of records to return (default: 50, max: 1000). */
+    readonly limit?: number;
+    /** Number of records to skip (default: 0). */
+    readonly offset?: number;
+    /** Sort order by created_at (default: 'desc'). */
+    readonly order?: 'asc' | 'desc';
+}
+/** Paginated result set from a list query. */
+interface AuditListResult {
+    readonly records: readonly AuditRecord[];
+    readonly total: number;
+    readonly limit: number;
+    readonly offset: number;
+}
+/** Time-bucket aggregation for dashboard charts. */
+interface AuditTimeBucket {
+    /** ISO 8601 timestamp for the start of the bucket. */
+    readonly bucket: string;
+    /** Number of records in this bucket. */
+    readonly count: number;
+}
+/** Aggregated statistics for the dashboard. */
+interface AuditAggregateStats {
+    /** Total number of records in the time range. */
+    readonly total: number;
+    /** Total records that resolved without a block (`block_reason IS NULL`). */
+    readonly allowed_total: number;
+    /** Total records that resolved with a block (`block_reason IS NOT NULL`). */
+    readonly blocked_total: number;
+    /** Total records produced in dry-run mode (`dry_run = 1`). */
+    readonly dry_run_total: number;
+    /** Total records produced in applied mode (`dry_run = 0`). */
+    readonly applied_total: number;
+    /** Counts grouped by policy decision. */
+    readonly by_decision: ReadonlyArray<{
+        readonly decision: string;
+        readonly count: number;
+    }>;
+    /** Counts grouped by block reason for blocked records only. */
+    readonly by_block_reason: ReadonlyArray<{
+        readonly reason: string;
+        readonly count: number;
+    }>;
+    /** Top tools by call count (max 10). */
+    readonly top_tools: ReadonlyArray<{
+        readonly tool_name: string;
+        readonly count: number;
+    }>;
+    /** Approval rate (approved / total require_approval decisions), or null if none. */
+    readonly approval_rate: number | null;
+    /** Records per hour over the time range. */
+    readonly per_hour: readonly AuditTimeBucket[];
+}
+/** Options for constructing an AuditStore. */
+interface AuditStoreOptions {
+    /** Path to the SQLite database file (use ':memory:' for in-memory). */
+    readonly path: string;
+    /** Retention duration string (e.g. "90d"). Records older than this are purged. */
+    readonly retention: string;
+    /** Whether to store upstream response bodies. */
+    readonly includeResponses: boolean;
+    /** Interval in milliseconds for retention cleanup (default: 86_400_000 = 24h). Set to 0 to disable. */
+    readonly cleanupIntervalMs?: number;
+}
+
+/**
+ * SQLite-backed audit record store.
+ *
+ * All read/write operations are synchronous (better-sqlite3 design).
+ * The AuditWriter wraps this with a batching/buffering layer.
+ */
+declare class AuditStore {
+    private readonly db;
+    private readonly insertStmt;
+    private readonly retentionMs;
+    private readonly includeResponses;
+    private cleanupTimer;
+    constructor(options: AuditStoreOptions);
+    /**
+     * Validate that the on-disk audit schema contains all required canonical columns.
+     *
+     * This keeps the clean-break migration policy while surfacing an actionable
+     * error for stale local databases instead of a low-level SQLite failure.
+     */
+    private assertRequiredSchema;
+    /**
+     * Insert a single audit record. Returns the generated record ID.
+     *
+     * @param record - The record to insert (id and created_at are auto-generated).
+     * @param createdAt - Optional override for the created_at timestamp (for testing).
+     * @param id - Optional pre-generated ID (used by AuditWriter to share ID with SSE event bus).
+     */
+    insert(record: Omit<AuditRecord, 'id' | 'created_at'>, createdAt?: string, id?: string): string;
+    /**
+     * Insert multiple audit records in a single SQLite transaction.
+     *
+     * Significantly faster than calling `insert()` in a loop because SQLite
+     * only syncs the WAL once per transaction. Records that fail to insert
+     * are skipped (the error callback is invoked) without aborting the batch.
+     *
+     * @param records - The records to insert.
+     * @param onError - Optional callback for per-record insert failures.
+     * @param onPersist - Optional callback for per-record successful inserts.
+     * @param ids - Optional pre-generated IDs (one per record). When provided,
+     *   each ID is passed to `insert()` so the same UUID can be shared with
+     *   the SSE event bus before the record is persisted.
+     * @returns The number of records successfully inserted.
+     */
+    insertBatch(records: ReadonlyArray<Omit<AuditRecord, 'id' | 'created_at'>>, onError?: (record: Omit<AuditRecord, 'id' | 'created_at'>, err: unknown) => void, ids?: ReadonlyArray<string>, onPersist?: (record: Omit<AuditRecord, 'id' | 'created_at'>, id: string) => void): number;
+    /** Get a single record by ID, or undefined if not found. */
+    get(id: string): AuditRecord | undefined;
+    /** Query records with filters and pagination. */
+    list(filters?: AuditQueryFilters, pagination?: AuditPaginationOptions): AuditListResult;
+    /** Count records matching the given filters. */
+    count(filters?: AuditQueryFilters): number;
+    /** Get aggregate statistics for a time range. */
+    aggregate(from?: string, to?: string): AuditAggregateStats;
+    /** Delete records older than the retention period. Returns the count of deleted records. */
+    purgeExpired(): number;
+    /** Close the database and stop the cleanup timer. */
+    close(): void;
+}
+
+/** Options for constructing an AuditWriter. */
+interface AuditWriterOptions {
+    /** The underlying synchronous store to flush records into. */
+    readonly store: AuditStore;
+    /** Max records before a flush is triggered (default: 50). */
+    readonly bufferSize?: number;
+    /** Max milliseconds between flushes (default: 100). */
+    readonly flushIntervalMs?: number;
+    /** Optional callback invoked when a record enters the in-memory buffer. */
+    readonly onPush?: (record: Omit<AuditRecord, 'id' | 'created_at'>, id: string) => void;
+    /** Optional callback invoked after a record is successfully persisted. */
+    readonly onPersist?: (record: Omit<AuditRecord, 'id' | 'created_at'>, id: string) => void;
+}
+/**
+ * Async buffered audit record writer.
+ *
+ * Records are pushed into an in-memory buffer and flushed to the AuditStore
+ * in batches — either when the buffer reaches `bufferSize` or every
+ * `flushIntervalMs`, whichever comes first.
+ */
+declare class AuditWriter {
+    private readonly store;
+    private readonly bufferSize;
+    private readonly onPush;
+    private readonly onPersist;
+    private buffer;
+    private timer;
+    private flushSoonTimer;
+    private closed;
+    constructor(options: AuditWriterOptions);
+    /**
+     * Push an audit record into the buffer. Returns immediately.
+     *
+     * A UUID is pre-generated so it can be shared with the SSE event bus
+     * (via the onPush callback) and later reused at insert time.
+     *
+     * If the buffer reaches the configured threshold, a near-term async flush
+     * is scheduled. This keeps request-path latency bounded even under bursty
+     * write load.
+     */
+    push(record: Omit<AuditRecord, 'id' | 'created_at'>): void;
+    /**
+     * Push a record and schedule a high-priority async flush.
+     *
+     * Security-critical records (deny, break-glass, rate/spend blocks) use this
+     * path so they are persisted on the next tick without blocking the request.
+     * A fatal-process crash still invokes the crash-drain hook, which calls
+     * `flush()` synchronously before exit.
+     */
+    pushImmediate(record: Omit<AuditRecord, 'id' | 'created_at'>): void;
+    /**
+     * Schedule a flush on the next tick, coalescing multiple calls into one.
+     */
+    private scheduleFlushSoon;
+    /** Flush all buffered records to the store in a single transaction. */
+    flush(): void;
+    /** Flush remaining records, stop the timer, and close the underlying store. */
+    close(): void;
+}
+
+/**
+ * A single evidence entry recorded by the SDK.
+ *
+ * DTO: snake_case because it's emitted directly over `/api/evidence/:session_id`
+ * and the SDK sideband's `/session/:id/state`. `JSON.stringify(entry)` produces
+ * the wire shape without a mapping layer.
+ */
+interface EvidenceEntry {
+    readonly evidence_key: string;
+    readonly data: unknown;
+    readonly tool_name: string;
+    readonly timestamp: string;
+    readonly expires_at: number;
+}
+/**
+ * A record that a tool was invoked in a session.
+ *
+ * DTO: snake_case because it appears inside `SessionState.completed_tools`.
+ */
+interface CompletedTool {
+    readonly tool_name: string;
+    readonly timestamp: string;
+    readonly succeeded: boolean;
+}
+/**
+ * Combined read-only state for a single session.
+ *
+ * DTO: snake_case because this is the response body of
+ * `/api/evidence/:session_id` and `/session/:session_id/state`.
+ */
+interface SessionState {
+    readonly session_id: string;
+    readonly evidence: Record<string, EvidenceEntry>;
+    readonly context: Record<string, unknown>;
+    readonly completed_tools: readonly CompletedTool[];
+}
+/**
+ * Diagnostics preview of the current evidence-key allowlist.
+ *
+ * Internal helper type used when sideband writes are rejected because an
+ * evidence key is not configured in policy.
+ */
+interface EvidenceKeyAllowlistPreview {
+    readonly allowedKeys: readonly string[];
+    readonly allowedKeyCount: number;
+    readonly truncated: boolean;
+}
+/** Result of attempting to store evidence via putEvidence(). */
+type PutEvidenceResult = {
+    readonly stored: true;
+} | {
+    readonly stored: false;
+    readonly reason: 'closed';
+} | {
+    readonly stored: false;
+    readonly reason: 'key_not_in_policy_allowlist';
+    readonly rejectedKey: string;
+    readonly allowlist: EvidenceKeyAllowlistPreview;
+};
+/** Result of attempting to write context via putContext(). */
+type PutContextResult = {
+    readonly stored: true;
+} | {
+    readonly stored: false;
+    readonly reason: 'closed';
+};
+/** Options for constructing an EvidenceStore. */
+interface EvidenceStoreOptions {
+    /** Default TTL in seconds when not specified per-entry (default: 300). */
+    readonly defaultTtlSeconds?: number;
+    /** Cleanup sweep interval in milliseconds (default: 60_000). Set to 0 to disable. */
+    readonly cleanupIntervalMs?: number;
+    /**
+     * Inactivity TTL for sessions that have no live evidence entries but still
+     * contain context and/or completed tool history (default: 1 hour).
+     */
+    readonly sessionInactivityMs?: number;
+    /**
+     * Optional allowlist of evidence keys accepted by putEvidence().
+     *
+     * When omitted, all keys are accepted. When provided, unknown keys are
+     * rejected to prevent high-cardinality session growth from dynamic keys.
+     */
+    readonly allowedEvidenceKeys?: readonly string[];
+    /** Injectable clock for testing (default: Date.now). */
+    readonly now?: () => number;
+}
+
+/** Input for putEvidence (omits computed fields). */
+interface PutEvidenceInput {
+    readonly evidence_key: string;
+    readonly data: unknown;
+    readonly tool_name: string;
+    readonly ttl_seconds?: number;
+}
+declare class EvidenceStore {
+    private static readonly EVIDENCE_ALLOWLIST_PREVIEW_LIMIT;
+    private static readonly MAX_UNIQUE_REJECTION_WARNINGS;
+    private static readonly REJECTION_WARNING_SUMMARY_INTERVAL;
+    private readonly sessions;
+    private readonly defaultTtlSeconds;
+    private readonly sessionInactivityMs;
+    private readonly now;
+    private readonly warnedRejectedEvidenceKeys;
+    private allowedEvidenceKeys;
+    private suppressedRejectionWarningCount;
+    private timer;
+    private closed;
+    constructor(options?: EvidenceStoreOptions);
+    /** Insert or update an evidence entry for a session. */
+    putEvidence(sessionId: string, input: PutEvidenceInput): PutEvidenceResult;
+    /** Set an arbitrary context value for a session. */
+    putContext(sessionId: string, key: string, value: unknown): PutContextResult;
+    /** Get a single evidence entry, or undefined if missing/expired. */
+    getEvidence(sessionId: string, evidenceKey: string): EvidenceEntry | undefined;
+    /** Check whether valid (non-expired) evidence exists. */
+    hasEvidence(sessionId: string, evidenceKey: string): boolean;
+    /**
+     * Check whether evidence with this key has ever been seen in the session.
+     *
+     * Distinct from hasEvidence(): a key may be "seen" but currently expired.
+     */
+    hasSeenEvidence(sessionId: string, evidenceKey: string): boolean;
+    /** Get a single context value, or undefined if missing. */
+    getContext(sessionId: string, key: string): unknown;
+    /**
+     * Record that a tool was invoked in a session (for dependency chains).
+     *
+     * Dependency-chain success is *sticky*: once a tool has successfully
+     * completed in a session, a later failed retry of the same tool must not
+     * revoke the dependency. Otherwise an agent could legitimately satisfy a
+     * dependency, get mid-session credentials, then lose access by accidentally
+     * re-calling the same tool with a bad argument. The stored entry therefore
+     * keeps `succeeded: true` once set; the timestamp refreshes on every call
+     * so operators still see the most recent invocation time.
+     */
+    recordToolCall(sessionId: string, toolName: string, succeeded: boolean): void;
+    /** Check whether a tool was called in a session (regardless of outcome). */
+    hasCompletedTool(sessionId: string, toolName: string): boolean;
+    /** Check whether a tool was called AND succeeded in a session. */
+    hasSuccessfulTool(sessionId: string, toolName: string): boolean;
+    /**
+     * Get a raw evidence entry WITHOUT lazy eviction.
+     * Used by the grounding layer to distinguish "never stored" from "stored but expired".
+     */
+    peekEvidence(sessionId: string, evidenceKey: string): EvidenceEntry | undefined;
+    /** Get the full combined state for a session (evidence + context + completed tools). */
+    getSessionState(sessionId: string): SessionState;
+    /** Sweep all sessions, removing expired evidence and empty sessions. */
+    cleanup(): void;
+    /** Stop the cleanup timer and clear all state. Idempotent. */
+    close(): void;
+    /** Number of tracked sessions (for testing/debugging). */
+    get sessionCount(): number;
+    /** Number of evidence entries for a session (including expired, pre-eviction). */
+    evidenceCount(sessionId: string): number;
+    /** Number of evidence keys ever seen in a session. */
+    seenEvidenceCount(sessionId: string): number;
+    /**
+     * Replace the evidence key allowlist.
+     *
+     * Unknown keys submitted through putEvidence() are ignored once an allowlist
+     * is configured.
+     */
+    setAllowedEvidenceKeys(keys: readonly string[]): void;
+    private ensureSession;
+    private touchSession;
+    private isEvidenceKeyAllowed;
+    private buildAllowlistPreview;
+    private warnRejectedEvidenceKey;
+}
+
+/** Possible states of an approval ticket. */
+type ApprovalStatus = 'pending' | 'approved' | 'denied' | 'timeout' | 'break_glass' | 'client_disconnected' | 'shutdown_cancelled';
+/** A failed attempt to deliver an approval notification. */
+interface ApprovalNotificationFailure {
+    readonly channel: string;
+    readonly phase: 'initial' | 'escalation';
+    readonly error: string;
+    readonly failed_at: string;
+}
+/**
+ * An approval ticket representing a held tools/call request waiting for a
+ * human decision.
+ *
+ * DTO: field names are snake_case because this type is emitted directly
+ * over REST `/api/approvals` and webhook payloads. `JSON.stringify(ticket)`
+ * produces the wire shape without a mapping layer. Strictly internal types
+ * in this file (e.g. `ApprovalOutcome`) remain idiomatic camelCase.
+ */
+interface ApprovalTicket {
+    readonly id: string;
+    readonly tool_name: string;
+    readonly tool_input: Record<string, unknown>;
+    readonly matched_rule: string | null;
+    readonly rule_index: number | null;
+    readonly channel_name: string;
+    readonly session_id: string | null;
+    readonly requested_at: string;
+    readonly timeout_at: string;
+    readonly timeout_ms: number;
+    status: ApprovalStatus;
+    resolved_at?: string;
+    resolved_by?: string;
+    denial_reason?: string;
+    break_glass_reason?: string;
+    escalated_at?: string;
+    escalated_to?: string[];
+    notification_failures?: ApprovalNotificationFailure[];
+}
+/** What the approval router returns to the governed forwarder. */
+type ApprovalOutcome = {
+    readonly status: 'approved';
+    readonly resolvedBy: string;
+    readonly ticketId: string;
+} | {
+    readonly status: 'denied';
+    readonly resolvedBy: string;
+    readonly reason?: string;
+    readonly ticketId: string;
+} | {
+    readonly status: 'timeout';
+    readonly ticketId: string;
+    readonly timeoutMs: number;
+} | {
+    readonly status: 'client_disconnected';
+    readonly ticketId: string;
+} | {
+    readonly status: 'shutdown_cancelled';
+    readonly ticketId: string;
+} | {
+    readonly status: 'break_glass';
+    readonly resolvedBy: string;
+    readonly reason: string;
+    readonly ticketId: string;
+};
+/**
+ * Channel interface for approval notifications.
+ *
+ * Channels are responsible for notifying approvers when a new ticket
+ * is created. The actual resolution happens via the REST API or the
+ * channel's own callback mechanism.
+ */
+interface ApprovalChannel {
+    /** Channel type identifier (e.g. 'dashboard', 'webhook', 'slack'). */
+    readonly type: string;
+    /** Send a notification about a new approval request. Fire-and-forget. */
+    notify(ticket: ApprovalTicket): Promise<void>;
+}
+
+/** Options for constructing an ApprovalQueue. */
+interface ApprovalQueueOptions {
+    /** Clock function for testable time. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Interval (ms) between cleanup sweeps. 0 disables cleanup. Default: 60000. */
+    readonly cleanupIntervalMs?: number;
+    /** How long (ms) to keep resolved tickets before cleanup. Default: 3600000 (1 hour). */
+    readonly resolvedRetentionMs?: number;
+}
+/** Filter options for listing tickets. */
+interface ApprovalListFilter {
+    readonly status?: ApprovalStatus;
+}
+declare class ApprovalQueue {
+    private readonly tickets;
+    private readonly now;
+    private readonly resolvedRetentionMs;
+    private timer;
+    private closed;
+    constructor(options?: ApprovalQueueOptions);
+    /**
+     * Create and store a new approval ticket.
+     *
+     * @returns the created ticket (with generated ID and timestamps).
+     */
+    add(params: {
+        tool_name: string;
+        tool_input: Record<string, unknown>;
+        matched_rule: string | null;
+        rule_index: number | null;
+        channel_name: string;
+        session_id: string | null;
+        timeout_ms: number;
+    }): ApprovalTicket;
+    /** Get a ticket by ID. Returns undefined if not found. */
+    get(id: string): ApprovalTicket | undefined;
+    /** List tickets, optionally filtered by status. */
+    list(filter?: ApprovalListFilter): ApprovalTicket[];
+    /** Shortcut: list only pending tickets. */
+    listPending(): ApprovalTicket[];
+    /**
+     * Resolve a pending ticket.
+     *
+     * @returns `true` if the ticket was resolved, `false` if not found or
+     *          already resolved (no double-resolution).
+     */
+    resolve(id: string, status: 'approved' | 'denied' | 'timeout' | 'break_glass' | 'client_disconnected' | 'shutdown_cancelled', resolvedBy?: string, options?: {
+        denial_reason?: string;
+        break_glass_reason?: string;
+    }): boolean;
+    /** Remove resolved tickets older than the retention period. */
+    cleanup(): void;
+    /** Clear the cleanup timer and mark the queue as closed. */
+    close(): void;
+}
+
+/** Options for constructing an ApprovalRouter. */
+interface ApprovalRouterOptions {
+    /** Default timeout (ms) when no rule-level timeout is specified. */
+    readonly defaultTimeoutMs: number;
+    /** What to do when a timeout fires: 'allow' forwards upstream, 'deny' blocks. */
+    readonly defaultOnTimeout: 'allow' | 'deny';
+    /** Map of channel-type → channel implementation. */
+    readonly channels: Map<string, ApprovalChannel>;
+    /** The approval queue for ticket storage. */
+    readonly queue: ApprovalQueue;
+    /** Clock function for testable time. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Optional callback when a new approval ticket is submitted. */
+    readonly onSubmit?: (ticket: ApprovalTicket) => void;
+    /** Optional callback when a ticket is resolved (approved, denied, break_glass, timeout, client_disconnected, shutdown_cancelled). */
+    readonly onResolve?: (ticket: ApprovalTicket) => void;
+    /** Optional callback when channel notification delivery fails. */
+    readonly onNotifyFailure?: (event: ApprovalNotifyFailureEvent) => void;
+}
+/** Payload emitted when approval-channel notification delivery fails. */
+interface ApprovalNotifyFailureEvent {
+    readonly ticket_id: string;
+    readonly channel: string;
+    readonly phase: 'initial' | 'escalation';
+    readonly error: string;
+}
+/** Parameters for submitting an approval request. */
+interface ApprovalSubmitParams {
+    readonly tool_name: string;
+    readonly tool_input: Record<string, unknown>;
+    readonly matched_rule: CompiledPolicyRule | undefined;
+    readonly session_id: string | null;
+}
+declare class ApprovalRouter {
+    private readonly defaultTimeoutMs;
+    readonly defaultOnTimeout: 'allow' | 'deny';
+    private readonly channels;
+    private readonly queue;
+    private readonly now;
+    private readonly onSubmit;
+    private readonly onResolve;
+    private readonly onNotifyFailure;
+    private readonly pending;
+    private closed;
+    constructor(options: ApprovalRouterOptions);
+    /**
+     * Submit a tool call for approval. Returns a Promise that resolves
+     * when the approval is granted, denied, or times out.
+     *
+     * The governed forwarder `await`s this Promise while the HTTP request
+     * is held open.
+     */
+    submit(params: ApprovalSubmitParams, abortSignal?: AbortSignal): Promise<ApprovalOutcome>;
+    /**
+     * Approve a pending ticket. Resolves the held Promise so the governed
+     * forwarder can forward the request upstream.
+     *
+     * @returns `true` if the ticket was approved, `false` if not found or
+     *          already resolved.
+     */
+    approve(ticketId: string, approvedBy: string): boolean;
+    /**
+     * Deny a pending ticket. Resolves the held Promise so the governed
+     * forwarder can return structured denial feedback.
+     *
+     * @returns `true` if the ticket was denied, `false` if not found or
+     *          already resolved.
+     */
+    deny(ticketId: string, deniedBy: string, reason?: string): boolean;
+    /**
+     * Break-glass override: force-approve a pending ticket, bypassing the
+     * normal approval flow. The event is prominently flagged in the audit trail.
+     *
+     * @returns `true` if the ticket was resolved, `false` if not found or
+     *          already resolved.
+     */
+    breakGlass(ticketId: string, resolvedBy: string, reason: string): boolean;
+    /** Clean up all pending timers and resolve all pending promises. */
+    close(): void;
+    private finalizePending;
+    private reportNotifyFailure;
+}
+
+/** Options for constructing a RateLimiter. */
+interface RateLimiterOptions {
+    /** Clock function for testable time. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Interval (ms) between cleanup sweeps. 0 disables cleanup. Default: 60000. */
+    readonly cleanupIntervalMs?: number;
+    /** Optional callback when utilization exceeds the warning threshold. */
+    readonly onWarning?: (state: RateLimitKeyState) => void;
+    /** Utilization ratio (0-1) that triggers the warning callback. Default: 0.8. */
+    readonly warningThreshold?: number;
+}
+/** Parameters for a rate limit check. */
+interface RateLimitCheckParams {
+    /** The bucket key, constructed by the caller (e.g. "tool:send_email"). */
+    readonly key: string;
+    /** Maximum calls allowed within the window. */
+    readonly maxCalls: number;
+    /** Sliding window duration in milliseconds. */
+    readonly windowMs: number;
+}
+/** Result of a rate limit check. */
+interface RateLimitResult {
+    /** Whether the call was allowed (under the limit). */
+    readonly allowed: boolean;
+    /** Number of calls in the current window (after this check). */
+    readonly current: number;
+    /** The configured max calls. */
+    readonly limit: number;
+    /** The configured window in milliseconds. */
+    readonly windowMs: number;
+    /** Timestamp (ms) when the oldest entry in the window expires. 0 if no entries. */
+    readonly resetAtMs: number;
+}
+/**
+ * Read-only snapshot of a rate limit key's current state (for dashboard).
+ *
+ * DTO: field names are snake_case because this type is emitted directly over
+ * `/api/limits`. `JSON.stringify(state)` produces the wire shape without a
+ * mapping layer. Strictly internal types in this file (e.g. `RateLimitResult`,
+ * `RateLimitCheckParams`) remain idiomatic camelCase.
+ */
+interface RateLimitKeyState {
+    readonly key: string;
+    readonly current: number;
+    readonly limit: number;
+    readonly window_ms: number;
+    readonly reset_at_ms: number;
+}
+declare class RateLimiter {
+    private readonly buckets;
+    private readonly now;
+    private readonly onWarning;
+    private readonly warningThreshold;
+    private timer;
+    private closed;
+    constructor(options?: RateLimiterOptions);
+    /**
+     * Check and optionally record a call against the rate limit.
+     *
+     * Evicts expired timestamps, then checks the count:
+     * - Under limit: records the timestamp and returns `allowed: true`
+     * - At/over limit: does NOT record (blocked calls don't consume a slot)
+     */
+    check(params: RateLimitCheckParams): RateLimitResult;
+    /**
+     * Check the rate limit without recording the call (non-destructive).
+     *
+     * Used by dry-run mode to determine what would happen without consuming
+     * a slot in the bucket.
+     */
+    peek(params: RateLimitCheckParams): RateLimitResult;
+    /** Get the current state of a single key. Returns undefined if not tracked. */
+    getKeyState(key: string): RateLimitKeyState | undefined;
+    /** List all tracked keys with their current state. */
+    listKeyStates(): RateLimitKeyState[];
+    /** Sweep all buckets: remove expired timestamps, delete empty buckets. */
+    cleanup(): void;
+    /** Clear all rate limit state. Called on policy hot-reload. */
+    reset(): void;
+    /**
+     * Reconcile bucket state against a new policy's limit configuration.
+     *
+     * Walks every existing bucket and checks whether its last-seen
+     * `{ maxCalls, windowMs }` tuple still appears anywhere in `validConfigs`.
+     * Buckets whose config is still present are left untouched — counters and
+     * elapsed-window progress are preserved across hot-reloads. Buckets whose
+     * config is gone (rule changed or removed) are evicted so the next check
+     * lazy-creates a fresh bucket under the new config.
+     *
+     * This is the compare-and-evict semantic that replaces the old `reset()`
+     * call on every hot-reload, which wiped all state even when the matching
+     * rule was unchanged.
+     */
+    reconcile(validConfigs: Iterable<{
+        maxCalls: number;
+        windowMs: number;
+    }>): void;
+    /** Stop the cleanup timer and mark as closed. */
+    close(): void;
+}
+
+/** Options for constructing a SpendLimiter. */
+interface SpendLimiterOptions {
+    /** Clock function for testable time. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Interval (ms) between cleanup sweeps. 0 disables cleanup. Default: 60000. */
+    readonly cleanupIntervalMs?: number;
+    /** Optional callback when utilization exceeds the warning threshold. */
+    readonly onWarning?: (state: SpendLimitKeyState) => void;
+    /** Utilization ratio (0-1) that triggers the warning callback. Default: 0.8. */
+    readonly warningThreshold?: number;
+}
+/** Parameters for a spend limit check. */
+interface SpendLimitCheckParams {
+    /** The bucket key, constructed by the caller (e.g. "tool:create_payment"). */
+    readonly key: string;
+    /** The monetary amount of this call. */
+    readonly amount: number;
+    /** Maximum cumulative spend allowed within the window. */
+    readonly limit: number;
+    /** Sliding window duration in milliseconds. */
+    readonly windowMs: number;
+}
+/** Result of a spend limit check. */
+interface SpendLimitResult {
+    /** Whether the spend was allowed (under the limit). */
+    readonly allowed: boolean;
+    /** Cumulative spend in the current window (after this check). */
+    readonly currentSpend: number;
+    /** The configured spend limit. */
+    readonly limit: number;
+    /** The configured window in milliseconds. */
+    readonly windowMs: number;
+    /** Timestamp (ms) when the oldest entry in the window expires. 0 if no entries. */
+    readonly resetAtMs: number;
+    /**
+     * Set when the call was rejected for a reason other than "would exceed limit".
+     * `'invalid_amount'` indicates the amount was negative, NaN, or non-finite.
+     */
+    readonly reason?: 'invalid_amount';
+}
+/**
+ * Read-only snapshot of a spend limit key's current state (for dashboard).
+ *
+ * DTO: field names are snake_case because this type is emitted directly over
+ * `/api/limits`. `JSON.stringify(state)` produces the wire shape without a
+ * mapping layer. Strictly internal types in this file (e.g. `SpendLimitResult`,
+ * `SpendLimitCheckParams`) remain idiomatic camelCase.
+ */
+interface SpendLimitKeyState {
+    readonly key: string;
+    readonly current_spend: number;
+    readonly limit: number;
+    readonly currency: string;
+    readonly window_ms: number;
+    readonly reset_at_ms: number;
+}
+declare class SpendLimiter {
+    private readonly buckets;
+    private readonly now;
+    private readonly onWarning;
+    private readonly warningThreshold;
+    private timer;
+    private closed;
+    constructor(options?: SpendLimiterOptions);
+    /**
+     * Check and optionally record a spend against the limit.
+     *
+     * Evicts expired entries, sums remaining amounts, then checks:
+     * - Under limit (currentSpend + amount <= limit): records and returns `allowed: true`
+     * - Would exceed: does NOT record (rejected spends don't consume budget)
+     */
+    check(params: SpendLimitCheckParams): SpendLimitResult;
+    /**
+     * Check the spend limit without recording the spend (non-destructive).
+     *
+     * Used by dry-run mode to determine what would happen without consuming
+     * budget in the bucket.
+     */
+    peek(params: SpendLimitCheckParams): SpendLimitResult;
+    /**
+     * Set the display currency for a key. Called by the governed forwarder
+     * after check() so dashboard reads include the currency label.
+     */
+    setCurrency(key: string, currency: string): void;
+    /** Get the current state of a single key. Returns undefined if not tracked. */
+    getKeyState(key: string): SpendLimitKeyState | undefined;
+    /** List all tracked keys with their current state. */
+    listKeyStates(): SpendLimitKeyState[];
+    /** Sweep all buckets: remove expired entries, delete empty buckets. */
+    cleanup(): void;
+    /** Clear all spend limit state. Called on policy hot-reload. */
+    reset(): void;
+    /**
+     * Reconcile bucket state against a new policy's spend configuration.
+     *
+     * Walks every existing bucket and checks whether its last-seen
+     * `{ limit, currency, windowMs }` tuple still appears in `validConfigs`.
+     * Buckets whose config is unchanged are left untouched — cumulative spend
+     * and elapsed-window progress are preserved across hot-reloads. Buckets
+     * whose config is gone (rule changed or removed) are evicted so the next
+     * check lazy-creates a fresh bucket under the new config.
+     *
+     * Currency is part of the tuple because a USD→EUR switch is a meaningful
+     * policy change — the same numeric limit buys a different amount of real
+     * spend, so the bucket must reset. This replaces the old `reset()` call
+     * on every hot-reload, which wiped all state even when the matching rule
+     * was unchanged.
+     */
+    reconcile(validConfigs: Iterable<{
+        limit: number;
+        currency: string;
+        windowMs: number;
+    }>): void;
+    /** Stop the cleanup timer and mark as closed. */
+    close(): void;
+}
+
+/** Options for constructing a GovernedForwarder. */
+interface GovernedForwarderOptions {
+    /** The current environment label (e.g. "production", "staging"). */
+    environment?: string;
+    /** Async audit writer for recording tool call decisions. */
+    auditWriter?: AuditWriter;
+    /** In-memory evidence store for evidence grounding. */
+    evidenceStore?: EvidenceStore;
+    /** Approval router for handling require_approval decisions. */
+    approvalRouter?: ApprovalRouter;
+    /** Rate limiter for handling rate_limit decisions. */
+    rateLimiter?: RateLimiter;
+    /** Spend limiter for handling spend_limit decisions. */
+    spendLimiter?: SpendLimiter;
+}
+/** Result of attempting to prime the tool annotation cache. */
+interface AnnotationCachePrimeResult {
+    /** True when cache update succeeded from a valid tools/list response shape. */
+    readonly success: boolean;
+    /** Number of tools currently cached after the attempt. */
+    readonly toolsCached: number;
+    /** Failure reason when success is false. */
+    readonly reason?: string;
+}
+/**
+ * A McpForwarder decorator that evaluates policy rules before forwarding
+ * tools/call requests to the upstream MCP server.
+ *
+ * - tools/call: evaluate policy → allow, deny, or reject (unimplemented action)
+ * - tools/list: forward, then cache tool annotations for future evaluations
+ * - All other methods: pass through directly
+ */
+declare class GovernedForwarder implements McpForwarder {
+    private readonly inner;
+    private policy;
+    private readonly environment;
+    private readonly auditWriter;
+    private readonly evidenceStore;
+    private readonly approvalRouter;
+    private readonly rateLimiter;
+    private readonly spendLimiter;
+    private readonly annotationCache;
+    private agentKeyWarned;
+    constructor(inner: McpForwarder, policy: CompiledPolicy, options?: GovernedForwarderOptions);
+    /**
+     * Swap the compiled policy atomically and reconcile limit bucket state
+     * against the new configuration.
+     *
+     * Rate and spend limit buckets are preserved when their underlying rule
+     * config is unchanged — this is what makes a benign hot-reload (e.g. a
+     * `vim :w` with no real edits, or a whitespace-only config change) safe:
+     * operators do not get a surprise zero of their live rate/spend state
+     * mid-window. Buckets whose config changed or whose rule was removed are
+     * evicted by the limiters' `reconcile()` methods, so the next check
+     * lazy-creates a fresh bucket under the new config.
+     *
+     * See `packages/proxy/src/policy/rate-limiter.ts` and `spend-limiter.ts`
+     * for the per-bucket compare-and-evict semantics.
+     */
+    updatePolicy(policy: CompiledPolicy): void;
+    /**
+     * Prime the annotation cache by fetching tools/list directly from upstream.
+     *
+     * This path is intended for startup warm-up and intentionally bypasses policy
+     * and audit handling. Runtime tools/list requests still flow through forward().
+     */
+    primeAnnotationCache(): Promise<AnnotationCachePrimeResult>;
+    forward(request: McpRequest): Promise<ForwardResult>;
+    private handleToolsCall;
+    private handleApproval;
+    private handleRateLimit;
+    private handleSpendLimit;
+    /**
+     * Handle dry-run mode: compute what would have happened without forwarding
+     * or consuming any resources. Returns an MCP-compliant synthetic response.
+     */
+    private handleDryRun;
+    /** Construct a limit bucket key based on the configured key type. */
+    private buildLimitKey;
+    /** Determine if the request was actually forwarded to the upstream MCP server. */
+    private wasForwardedUpstream;
+    private writeAuditRecord;
+    private makeDenyResult;
+    private makePolicyMisconfiguredResult;
+    private makeUnsupportedResult;
+    private makeDryRunResult;
+    private makeEvidenceBlockResult;
+    private makeSessionRequiredBlockResult;
+    private makeClientDisconnectedBlockResult;
+}
+
+/** Options for constructing the SDK sideband Hono app. */
+interface SidebandAppOptions {
+    /**
+     * Bearer token that every request must carry in its `Authorization`
+     * header (except `GET /healthz`). When omitted or empty, the sideband
+     * runs open — useful for local development when the operator has
+     * explicitly disabled the per-boot token via env.
+     */
+    readonly token?: string;
+}
+/**
+ * Create a Hono app for the SDK sideband API.
+ *
+ * The sideband API allows the Python/TypeScript SDK to report evidence
+ * and context to the proxy's in-memory evidence store. It runs on a
+ * separate port (default 3200) bound to 127.0.0.1 only.
+ *
+ * Two orthogonal defenses apply to every request:
+ *
+ * 1. **CORS guard.** Any request carrying an `Origin` header is rejected
+ *    with 403 (including `Origin: null`), and any `OPTIONS` preflight is
+ *    rejected with 403.
+ *    The SDK itself never sets an `Origin` header; only browsers do. This
+ *    defends against a malicious local HTML file POSTing to
+ *    127.0.0.1:3200 through the user's browser.
+ * 2. **Bearer auth.** When `options.token` is set, every request except
+ *    `GET /healthz` must carry `Authorization: Bearer <token>`. The proxy
+ *    generates a fresh token per boot and prints it to stderr so the SDK
+ *    can pick it up via the `HELIO_SDK_TOKEN` env var. Health is left
+ *    unauthenticated so container probes keep working.
+ */
+declare function createSidebandApp(store: EvidenceStore, options?: SidebandAppOptions): Hono;
+
+/** @internal Exported for testing only. */
+declare class QueueChannel implements ApprovalChannel {
+    readonly type = "dashboard";
+    notify(): Promise<void>;
+}
+/**
+ * Build a map of channel key → ApprovalChannel from the approval config.
+ *
+ * Each channel is keyed by its `name` field if present, otherwise by its
+ * `type`. This allows multiple channels of the same type (e.g. two webhook
+ * channels with different names) to coexist.
+ *
+ * Policy rules reference channels by this key via `approval.channel`.
+ */
+declare function createChannels(channels: ReadonlyArray<ApprovalChannel$1>): Map<string, ApprovalChannel>;
+
+/** Configuration for a webhook approval channel. */
+interface WebhookChannelOptions {
+    /** The URL to POST approval notifications to. */
+    readonly url: string;
+    /** Optional HMAC-SHA256 secret for signing outbound payloads. */
+    readonly secret?: string;
+}
+/**
+ * Webhook approval channel.
+ *
+ * Sends an HTTP POST to a configured URL when a new approval ticket is
+ * created. The payload includes an `event` field for future extensibility
+ * and the full ticket data. When a `secret` is configured, the payload is
+ * signed with HMAC-SHA256 and the signature is sent in the
+ * `x-helio-signature` header.
+ *
+ * Errors are logged but never thrown — the ticket remains resolvable via
+ * the REST API regardless of whether the webhook notification succeeds.
+ */
+declare class WebhookChannel implements ApprovalChannel {
+    readonly type = "webhook";
+    private readonly url;
+    private readonly secret;
+    constructor(options: WebhookChannelOptions);
+    notify(ticket: ApprovalTicket): Promise<void>;
+}
+
+/** Configuration for a Slack approval channel. */
+interface SlackChannelOptions {
+    /** Slack bot token (xoxb-...). */
+    readonly botToken: string;
+    /** Slack app signing secret for verifying action callbacks. */
+    readonly signingSecret: string;
+    /** Slack channel ID or name to post messages to. */
+    readonly channel: string;
+}
+/**
+ * Slack approval channel.
+ *
+ * Posts a Block Kit interactive message to the configured Slack channel
+ * when a new approval ticket is created. The message includes Approve
+ * and Deny buttons. Button clicks are handled by the separate Slack
+ * action handler ({@link createSlackActionApp} in `slack-actions.ts`).
+ *
+ * Errors are logged but never thrown — the ticket remains resolvable via
+ * the REST API regardless of whether the Slack notification succeeds.
+ */
+declare class SlackChannel implements ApprovalChannel {
+    readonly type = "slack";
+    /** Exposed for the Slack action handler to verify request signatures. */
+    readonly signingSecret: string;
+    private readonly client;
+    private readonly channel;
+    constructor(options: SlackChannelOptions);
+    notify(ticket: ApprovalTicket): Promise<void>;
+    /**
+     * Update an existing Slack message — used by the action handler to
+     * replace the approval buttons with a resolution status.
+     */
+    updateMessage(channel: string, ts: string, text: string, blocks: KnownBlock[]): Promise<void>;
+}
+
+/** Options for the Slack action handler. */
+interface SlackActionAppOptions {
+    /** The approval router for resolving tickets. */
+    readonly router: ApprovalRouter;
+    /** The channel map — used to find SlackChannel instances for signature
+     *  verification and message updates. */
+    readonly channels: Map<string, ApprovalChannel>;
+}
+/**
+ * Create a Hono app for handling Slack interactive action callbacks.
+ *
+ * Mounted on the main proxy server at `/slack/actions`. Verifies Slack
+ * request signatures, resolves approval tickets, and updates the original
+ * Slack message to show the decision.
+ */
+declare function createSlackActionApp(options: SlackActionAppOptions): Hono;
+
+/** Options for the approval REST API. */
+interface ApprovalAppOptions {
+    /** Bearer token for authenticating POST requests. When set, POST endpoints
+     *  require an `Authorization: Bearer <token>` header. GET endpoints remain
+     *  unprotected for dashboard / monitoring read access. */
+    readonly apiSecret?: string;
+}
+/**
+ * Create a Hono app for the approval REST API.
+ *
+ * Mounted exclusively on the dashboard sideband under `/api/approvals`.
+ * The dashboard sideband's own bearer middleware covers every `/api/*`
+ * path, so callers pass `apiSecret: undefined` here to avoid double
+ * authentication. Provides endpoints for listing, inspecting,
+ * approving, and denying approval tickets.
+ *
+ * Used by:
+ * - Webhook callbacks
+ * - Dashboard UI
+ * - Programmatic/CLI access (through the dashboard sideband port)
+ */
+declare function createApprovalApp(router: ApprovalRouter, queue: ApprovalQueue, options?: ApprovalAppOptions): Hono;
+
+/** Payload for an action event (new tool call processed). */
+interface ActionEvent {
+    readonly id: string;
+    readonly tool_name: string;
+    readonly policy_decision: string;
+    readonly block_reason: string | null;
+    readonly approval_status: string | null;
+    readonly session_id: string | null;
+    readonly agent_id: string | null;
+    readonly environment: string | null;
+    readonly timestamp: string;
+    readonly total_duration_ms: number;
+    readonly approval_wait_ms: number;
+    readonly proxy_compute_ms: number;
+    readonly flagged_destructive: boolean;
+    readonly dry_run: boolean;
+    readonly matched_rule: string | null;
+    readonly matched_rule_index: number | null;
+}
+/** Payload for an approval_requested event. */
+interface ApprovalRequestedEvent {
+    readonly ticket_id: string;
+    readonly tool_name: string;
+    readonly channel: string;
+    readonly requested_at: string;
+}
+/** Payload for an approval_resolved event. */
+interface ApprovalResolvedEvent {
+    readonly ticket_id: string;
+    readonly status: string;
+    readonly resolved_by?: string;
+    readonly resolved_at: string;
+}
+/** Payload for a limit_warning event (approaching threshold). */
+interface LimitWarningEvent {
+    readonly key: string;
+    readonly type: 'rate' | 'spend';
+    readonly current: number;
+    readonly limit: number;
+    readonly utilization: number;
+}
+/** Payload for approval notification delivery failures. */
+interface ApprovalNotificationFailedEvent {
+    readonly ticket_id: string;
+    readonly channel: string;
+    readonly phase: 'initial' | 'escalation';
+    readonly error: string;
+}
+/** Map of event type names to their payload types. */
+interface DashboardEvents {
+    action: ActionEvent;
+    approval_requested: ApprovalRequestedEvent;
+    approval_resolved: ApprovalResolvedEvent;
+    limit_warning: LimitWarningEvent;
+    approval_notification_failed: ApprovalNotificationFailedEvent;
+}
+/** Union of all dashboard event type names. */
+type DashboardEventType = keyof DashboardEvents;
+/**
+ * Typed event bus for dashboard real-time updates.
+ *
+ * Wraps Node's `EventEmitter` with type-safe emit/on/off methods and an
+ * `onAny()` helper that subscribes to all event types at once (used by the
+ * SSE endpoint).
+ */
+declare class DashboardEventBus {
+    private readonly emitter;
+    constructor();
+    /** Emit a typed event to all listeners. */
+    emit<K extends DashboardEventType>(event: K, data: DashboardEvents[K]): void;
+    /** Subscribe to a specific event type. */
+    on<K extends DashboardEventType>(event: K, listener: (data: DashboardEvents[K]) => void): void;
+    /** Unsubscribe from a specific event type. */
+    off<K extends DashboardEventType>(event: K, listener: (data: DashboardEvents[K]) => void): void;
+    /**
+     * Subscribe to ALL event types. The listener receives the event type name
+     * and the payload for each event.
+     *
+     * @returns An unsubscribe function that removes all listeners at once.
+     */
+    onAny(listener: (event: DashboardEventType, data: DashboardEvents[DashboardEventType]) => void): () => void;
+    /** Remove all listeners and release resources. */
+    close(): void;
+}
+
+/** Dependencies for the dashboard API. */
+interface DashboardAppDeps {
+    readonly auditStore: AuditStore;
+    readonly approvalRouter: ApprovalRouter;
+    readonly approvalQueue: ApprovalQueue;
+    readonly rateLimiter: RateLimiter;
+    readonly spendLimiter: SpendLimiter;
+    readonly evidenceStore: EvidenceStore;
+    readonly eventBus: DashboardEventBus;
+}
+/** Options for the dashboard API. */
+interface DashboardAppOptions {
+    /** Bearer token for authenticating POST (mutating) endpoints. */
+    readonly apiSecret?: string;
+    /** Absolute path to the dashboard's built static assets directory. */
+    readonly staticDir?: string;
+    /** SSE heartbeat interval in milliseconds. Defaults to 30 000 (30s). */
+    readonly sseHeartbeatMs?: number;
+}
+/**
+ * Create a Hono app for the dashboard REST + SSE API.
+ *
+ * This wrapper preserves the original API for call sites that do not need
+ * an explicit lifecycle close hook.
+ */
+declare function createDashboardApp(deps: DashboardAppDeps, options?: DashboardAppOptions): Hono;
+
+export { type ApprovalAppOptions, type ApprovalChannel, type ApprovalOutcome, ApprovalQueue, type ApprovalQueueOptions, ApprovalRouter, type ApprovalRouterOptions, type ApprovalStatus, type ApprovalTicket, type AuditAggregateStats, type AuditListResult, type AuditPaginationOptions, type AuditQueryFilters, type AuditRecord, AuditStore, type AuditStoreOptions, type AuditTimeBucket, AuditWriter, type AuditWriterOptions, type CompilePoliciesResult, type CompiledPolicy, type CompiledPolicyRule, ConfigError, type CreateAppOptions, type DashboardAppDeps, type DashboardAppOptions, DashboardEventBus, type DashboardEventType, type DashboardEvents, type EvidenceEntry, EvidenceStore, type EvidenceStoreOptions, GovernedForwarder, type GovernedForwarderOptions, type HelioConfig, type MatchContext, type PolicyDecision, PolicyParseError, QueueChannel, type RateLimitCheckParams, type RateLimitKeyState, type RateLimitResult, RateLimiter, type RateLimiterOptions, type ServerHandle, type SessionState, type SlackActionAppOptions, SlackChannel, type SlackChannelOptions, type SpendLimitCheckParams, type SpendLimitKeyState, type SpendLimitResult, SpendLimiter, type SpendLimiterOptions, SseUpstreamForwarder, type SseUpstreamForwarderOptions, StdioForwarder, type StdioForwarderOptions, UpstreamForwarder, type UpstreamForwarderOptions, VERSION, WebhookChannel, type WebhookChannelOptions, compilePolicies, createApp, createApprovalApp, createChannels, createDashboardApp, createSidebandApp, createSlackActionApp, evaluatePolicy, loadConfig, matchRule, startServer, startSidebandServer };