@gethelio/proxy 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -36,6 +36,12 @@ declare const policiesSchema: z.ZodObject<{
                 regex: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>>;
             environment: z.ZodOptional<z.ZodString>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                eq: z.ZodOptional<z.ZodString>;
+                neq: z.ZodOptional<z.ZodString>;
+                contains: z.ZodOptional<z.ZodString>;
+                regex: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>]>>>;
         }, z.core.$strict>;
         action: z.ZodEnum<{
             allow: "allow";
@@ -63,6 +69,7 @@ declare const policiesSchema: z.ZodObject<{
                 tool: "tool";
                 agent: "agent";
                 session: "session";
+                sender_id: "sender_id";
             }>>;
             max_spend: z.ZodOptional<z.ZodObject<{
                 field: z.ZodString;
@@ -73,6 +80,7 @@ declare const policiesSchema: z.ZodObject<{
                     tool: "tool";
                     agent: "agent";
                     session: "session";
+                    sender_id: "sender_id";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>>;
@@ -81,6 +89,38 @@ declare const policiesSchema: z.ZodObject<{
             suggestion: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>>>;
+    install: z.ZodOptional<z.ZodObject<{
+        default: z.ZodDefault<z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+        }>>;
+        rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            match: z.ZodObject<{
+                name: z.ZodOptional<z.ZodString>;
+                source: z.ZodOptional<z.ZodString>;
+                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    eq: z.ZodOptional<z.ZodString>;
+                    neq: z.ZodOptional<z.ZodString>;
+                    contains: z.ZodOptional<z.ZodString>;
+                    regex: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>]>>>;
+            }, z.core.$strict>;
+            action: z.ZodEnum<{
+                allow: "allow";
+                deny_install: "deny_install";
+            }>;
+            feedback: z.ZodOptional<z.ZodObject<{
+                message: z.ZodString;
+                suggestion: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    on_tool_drift: z.ZodOptional<z.ZodEnum<{
+        require_approval: "require_approval";
+        log: "log";
+        block: "block";
+    }>>;
     hot_reload: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 declare const approvalChannelSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -159,6 +199,12 @@ declare const helioConfigSchema: z.ZodObject<{
                     regex: z.ZodOptional<z.ZodString>;
                 }, z.core.$strict>>>;
                 environment: z.ZodOptional<z.ZodString>;
+                metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    eq: z.ZodOptional<z.ZodString>;
+                    neq: z.ZodOptional<z.ZodString>;
+                    contains: z.ZodOptional<z.ZodString>;
+                    regex: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>]>>>;
             }, z.core.$strict>;
             action: z.ZodEnum<{
                 allow: "allow";
@@ -186,6 +232,7 @@ declare const helioConfigSchema: z.ZodObject<{
                     tool: "tool";
                     agent: "agent";
                     session: "session";
+                    sender_id: "sender_id";
                 }>>;
                 max_spend: z.ZodOptional<z.ZodObject<{
                     field: z.ZodString;
@@ -196,6 +243,7 @@ declare const helioConfigSchema: z.ZodObject<{
                         tool: "tool";
                         agent: "agent";
                         session: "session";
+                        sender_id: "sender_id";
                     }>>;
                 }, z.core.$strict>>;
             }, z.core.$strict>>;
@@ -204,6 +252,38 @@ declare const helioConfigSchema: z.ZodObject<{
                 suggestion: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
         }, z.core.$strict>>>;
+        install: z.ZodOptional<z.ZodObject<{
+            default: z.ZodDefault<z.ZodEnum<{
+                allow: "allow";
+                deny: "deny";
+            }>>;
+            rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                name: z.ZodOptional<z.ZodString>;
+                match: z.ZodObject<{
+                    name: z.ZodOptional<z.ZodString>;
+                    source: z.ZodOptional<z.ZodString>;
+                    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        eq: z.ZodOptional<z.ZodString>;
+                        neq: z.ZodOptional<z.ZodString>;
+                        contains: z.ZodOptional<z.ZodString>;
+                        regex: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strict>]>>>;
+                }, z.core.$strict>;
+                action: z.ZodEnum<{
+                    allow: "allow";
+                    deny_install: "deny_install";
+                }>;
+                feedback: z.ZodOptional<z.ZodObject<{
+                    message: z.ZodString;
+                    suggestion: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        on_tool_drift: z.ZodOptional<z.ZodEnum<{
+            require_approval: "require_approval";
+            log: "log";
+            block: "block";
+        }>>;
         hot_reload: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     approval: z.ZodPrefault<z.ZodObject<{
@@ -240,6 +320,7 @@ declare const helioConfigSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         port: z.ZodDefault<z.ZodNumber>;
         host: z.ZodDefault<z.ZodString>;
+        evaluation_ttl: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Fully validated and defaulted Helio configuration. */
@@ -303,6 +384,22 @@ interface InputCondition {
     /** Pre-compiled RegExp when operator is 'regex'. */
     readonly regex?: RegExp;
 }
+/**
+ * A single flattened metadata condition (issue #13 — `match.metadata.*`).
+ *
+ * Mirrors InputCondition but matches a flat top-level key of the adapter-supplied
+ * context object (no JSONPath traversal), and is restricted to the string-friendly
+ * operator subset — metadata values (channel_id, sender_id, …) are strings, so the
+ * numeric comparators are deliberately excluded.
+ */
+interface MetadataCondition {
+    /** The metadata key to read (e.g. "channel_id", "sender_id", or virtual "agent_id"). */
+    readonly key: string;
+    readonly operator: 'eq' | 'neq' | 'contains' | 'regex';
+    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;
@@ -310,6 +407,8 @@ interface CompiledMatch {
     /** Flattened list of input conditions (one entry per path+operator pair). */
     readonly input?: readonly InputCondition[];
     readonly environment?: string;
+    /** Flattened list of metadata conditions (one entry per key+operator pair). */
+    readonly metadata?: readonly MetadataCondition[];
 }
 /** Compiled approval configuration with durations as milliseconds. */
 interface CompiledApproval {
@@ -324,13 +423,13 @@ interface CompiledSpendLimit {
     readonly limit: number;
     readonly currency: string;
     readonly windowMs: number;
-    readonly key?: 'tool' | 'agent' | 'session';
+    readonly key?: 'tool' | 'agent' | 'session' | 'sender_id';
 }
 /** Compiled rate/spend limit configuration. */
 interface CompiledLimits {
     readonly maxCalls?: number;
     readonly windowMs?: number;
-    readonly key?: 'tool' | 'agent' | 'session';
+    readonly key?: 'tool' | 'agent' | 'session' | 'sender_id';
     readonly maxSpend?: CompiledSpendLimit;
 }
 /** Policy action types. */
@@ -361,12 +460,44 @@ interface CompiledPolicyRule {
         readonly suggestion?: string;
     };
 }
+/** Compiled match block for an install-time rule (issue #13). */
+interface CompiledInstallMatch {
+    /** Glob matcher on the package name. */
+    readonly name?: ToolMatcher;
+    /** Exact ecosystem/source match (npm | pip | …). */
+    readonly source?: string;
+    /** Flattened metadata conditions (sender/channel-gated installs). */
+    readonly metadata?: readonly MetadataCondition[];
+}
+/** A compiled install-time rule. */
+interface CompiledInstallRule {
+    readonly index: number;
+    readonly name?: string;
+    readonly match: CompiledInstallMatch;
+    readonly action: 'deny_install' | 'allow';
+    readonly feedback?: {
+        readonly message: string;
+        readonly suggestion?: string;
+    };
+}
+/** Compiled install-time policy (issue #13). */
+interface CompiledInstallPolicy {
+    readonly defaultAction: 'allow' | 'deny';
+    readonly rules: readonly CompiledInstallRule[];
+}
 /** Top-level compiled policy — what the engine consumes. */
 interface CompiledPolicy {
     readonly defaultAction: 'allow' | 'deny';
     readonly flagDestructive?: 'log' | 'require_approval';
     readonly dryRun?: boolean;
+    /**
+     * Response to tool definition drift (issue #25). Undefined means "block"
+     * at the use site — conservative by default.
+     */
+    readonly onToolDrift?: 'block' | 'require_approval' | 'log';
     readonly rules: readonly CompiledPolicyRule[];
+    /** Install-time policy (issue #13 — deny_install). Undefined ⇒ observational. */
+    readonly install?: CompiledInstallPolicy;
 }
 /** A non-fatal warning produced during policy compilation. */
 interface PolicyParseWarning {
@@ -406,6 +537,13 @@ interface MatchContext {
     readonly toolArguments?: Readonly<Record<string, unknown>>;
     /** The configured environment label (e.g. "production", "staging"). */
     readonly environment?: string;
+    /**
+     * Adapter-supplied context for `match.metadata.*` (issue #13). Present only on
+     * the sideband (host-enforced) path; always absent on the MCP path, so metadata
+     * rules are inert there by construction. The virtual `agent_id` key (from the
+     * request column) is merged in by the decision pipeline, not stored here twice.
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 
 /** A JSON-RPC 2.0 request object. */
@@ -722,6 +860,27 @@ interface AuditRecord {
     readonly flagged_destructive: boolean;
     /** Whether this record was produced in dry-run mode. */
     readonly dry_run: boolean;
+    /**
+     * Record category discriminator (issues #12/#16). `'tool_call'` is the
+     * default for governed tool calls; `'drift_event'` for tool-definition drift
+     * records; `'install_scan'` for sideband install evaluations; and
+     * `'evaluation_expired'` for sideband evaluations whose `/audit` never
+     * arrived (the bypass/tamper signal — block_reason stays null so they do not
+     * count as enforcement blocks).
+     */
+    readonly record_kind: 'tool_call' | 'drift_event' | 'install_scan' | 'evaluation_expired';
+    /**
+     * Enforcement origin: `'mcp'` for the proxy path, or an adapter-supplied
+     * origin string (e.g. `'openclaw'`) for sideband-governed calls. Surfaces
+     * the enforcement-grade ladder (structural vs host-enforced) per record.
+     */
+    readonly origin: string;
+    /**
+     * Adapter-supplied context object (reserved keys: `channel_id`, `sender_id`,
+     * `sender_name`, `conversation_id`). Null for MCP-origin records. Backs
+     * `match.metadata.*` (#13) and the dashboard metadata columns (#16).
+     */
+    readonly metadata: Record<string, unknown> | null;
     /** ISO 8601 timestamp of when the record was persisted. */
     readonly created_at: string;
 }
@@ -747,6 +906,14 @@ interface AuditQueryFilters {
     readonly flagged_destructive?: boolean;
     /** Include only dry-run records (true) or non-dry-run records (false). */
     readonly dry_run?: boolean;
+    /** Filter by record kind (tool_call / drift_event / install_scan / evaluation_expired). */
+    readonly record_kind?: string;
+    /** Filter by enforcement origin (e.g. 'mcp', 'openclaw'). */
+    readonly origin?: string;
+    /** Filter by metadata.channel_id (adapter-supplied; JSON-extracted, substring match). */
+    readonly channel_id?: string;
+    /** Filter by metadata.sender_id (adapter-supplied; JSON-extracted, substring match). */
+    readonly sender_id?: string;
     /** 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. */
@@ -917,7 +1084,7 @@ declare class AuditWriter {
      * is scheduled. This keeps request-path latency bounded even under bursty
      * write load.
      */
-    push(record: Omit<AuditRecord, 'id' | 'created_at'>): void;
+    push(record: Omit<AuditRecord, 'id' | 'created_at'>, id?: string): void;
     /**
      * Push a record and schedule a high-priority async flush.
      *
@@ -926,7 +1093,7 @@ declare class AuditWriter {
      * A fatal-process crash still invokes the crash-drain hook, which calls
      * `flush()` synchronously before exit.
      */
-    pushImmediate(record: Omit<AuditRecord, 'id' | 'created_at'>): void;
+    pushImmediate(record: Omit<AuditRecord, 'id' | 'created_at'>, id?: string): void;
     /**
      * Schedule a flush on the next tick, coalescing multiple calls into one.
      */
@@ -1110,7 +1277,14 @@ declare class EvidenceStore {
 }
 
 /** Possible states of an approval ticket. */
-type ApprovalStatus = 'pending' | 'approved' | 'denied' | 'timeout' | 'break_glass' | 'client_disconnected' | 'shutdown_cancelled';
+type ApprovalStatus = 'pending' | 'approved' | 'denied' | 'timeout' | 'break_glass' | 'client_disconnected' | 'shutdown_cancelled'
+/**
+ * The approver's native UI cancelled the request (e.g. an OpenClaw
+ * `/approve` dialog dismissed without a decision). Distinct from
+ * `client_disconnected`, which the router reserves for the requesting agent
+ * aborting the held MCP request. Sideband (native) approvals only. (#12.)
+ */
+ | 'cancelled';
 /** A failed attempt to deliver an approval notification. */
 interface ApprovalNotificationFailure {
     readonly channel: string;
@@ -1233,7 +1407,7 @@ declare class ApprovalQueue {
      * @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?: {
+    resolve(id: string, status: 'approved' | 'denied' | 'timeout' | 'break_glass' | 'client_disconnected' | 'shutdown_cancelled' | 'cancelled', resolvedBy?: string, options?: {
         denial_reason?: string;
         break_glass_reason?: string;
     }): boolean;
@@ -1276,6 +1450,19 @@ interface ApprovalSubmitParams {
     readonly matched_rule: CompiledPolicyRule | undefined;
     readonly session_id: string | null;
 }
+/** Resolution statuses a native (sideband) ticket can be moved to. */
+type NativeResolution = 'approved' | 'denied' | 'timeout' | 'cancelled';
+/** Parameters for creating a native (adapter-owned) approval ticket. */
+interface NativeTicketParams {
+    readonly tool_name: string;
+    readonly tool_input: Record<string, unknown>;
+    readonly matched_rule: CompiledPolicyRule | undefined;
+    readonly session_id: string | null;
+    /** Adapter origin (e.g. "openclaw"); stored as channel_name `native:<origin>`. */
+    readonly origin: string;
+    /** Ticket timeout in ms (rule timeout, else the router default). */
+    readonly timeout_ms?: number;
+}
 declare class ApprovalRouter {
     private readonly defaultTimeoutMs;
     readonly defaultOnTimeout: 'allow' | 'deny';
@@ -1296,6 +1483,36 @@ declare class ApprovalRouter {
      * is held open.
      */
     submit(params: ApprovalSubmitParams, abortSignal?: AbortSignal): Promise<ApprovalOutcome>;
+    /**
+     * Create a native (adapter-owned) approval ticket without holding a Promise.
+     *
+     * Used by the sideband governance path (issue #12, D10): when `/evaluate`
+     * yields `require_approval`, the adapter runs the approval in its own UI
+     * (e.g. OpenClaw's Telegram dialog), so Helio must NOT block, start
+     * timeout/escalation timers, or notify a channel — doing so would
+     * double-notify. We still create the queue ticket and fire `onSubmit` so the
+     * dashboard's `approval_requested` SSE event flows and the ticket is visible.
+     *
+     * The ticket's `channel_name` is `native:<origin>`, which marks it as
+     * adapter-owned: the dashboard approve/deny endpoints refuse it (it can only
+     * be resolved through the adapter), and {@link resolveNativeTicket} is the
+     * resolution path.
+     */
+    createNativeTicket(params: NativeTicketParams): ApprovalTicket;
+    /**
+     * Resolve a native ticket created by {@link createNativeTicket}.
+     *
+     * Resolves the queue ticket and fires `onResolve` (→ `approval_resolved`
+     * SSE), with no held Promise to settle. Refuses tickets that have a pending
+     * router Promise (those are MCP-path tickets; resolving them here would leave
+     * the held request hanging) and tickets that are not `native:`-prefixed.
+     *
+     * @returns `true` if resolved, `false` if not found, already resolved, not a
+     *          native ticket, or router-managed.
+     */
+    resolveNativeTicket(ticketId: string, status: NativeResolution, resolvedBy?: string, options?: {
+        denial_reason?: string;
+    }): boolean;
     /**
      * Approve a pending ticket. Resolves the held Promise so the governed
      * forwarder can forward the request upstream.
@@ -1320,6 +1537,8 @@ declare class ApprovalRouter {
      *          already resolved.
      */
     breakGlass(ticketId: string, resolvedBy: string, reason: string): boolean;
+    /** Look up a ticket by id (delegates to the queue). */
+    getTicket(ticketId: string): ApprovalTicket | undefined;
     /** Clean up all pending timers and resolve all pending promises. */
     close(): void;
     private finalizePending;
@@ -1390,6 +1609,21 @@ declare class RateLimiter {
      * - At/over limit: does NOT record (blocked calls don't consume a slot)
      */
     check(params: RateLimitCheckParams): RateLimitResult;
+    /**
+     * Unconditionally record a call against the rate limit.
+     *
+     * Unlike check(), this always appends the timestamp — even when the bucket
+     * is already at/over the limit — because the call it represents has already
+     * executed. The sideband splits decision from execution: /evaluate peeks
+     * (non-destructive), and /audit calls record() once the external call ran,
+     * so refusing to record at the limit (as check() does) would let real calls
+     * escape accounting and under-count subsequent peeks. (issue #12, D3.)
+     *
+     * Warnings fire only while the post-append count stays within the limit —
+     * exact parity with check(), which never warns on its over-limit path — so a
+     * burst of over-limit audits cannot flood the dashboard's limit_warning feed.
+     */
+    record(params: RateLimitCheckParams): RateLimitResult;
     /**
      * Check the rate limit without recording the call (non-destructive).
      *
@@ -1499,6 +1733,20 @@ declare class SpendLimiter {
      * - Would exceed: does NOT record (rejected spends don't consume budget)
      */
     check(params: SpendLimitCheckParams): SpendLimitResult;
+    /**
+     * Unconditionally record a spend against the limit.
+     *
+     * Unlike check(), this always appends the amount — even when it pushes the
+     * window past the limit — because the spend it represents has already been
+     * incurred. The sideband peeks at /evaluate and commits here at /audit once
+     * the external call ran (issue #12, D3).
+     *
+     * Throws on a negative or non-finite amount: such amounts are rejected at
+     * /evaluate, so one reaching record() is a logic bug we surface loudly rather
+     * than silently corrupt the sliding-window sum. Warnings fire only while the
+     * post-append spend stays within the limit (parity with check()).
+     */
+    record(params: SpendLimitCheckParams): SpendLimitResult;
     /**
      * Check the spend limit without recording the spend (non-destructive).
      *
@@ -1587,6 +1835,7 @@ declare class GovernedForwarder implements McpForwarder {
     private readonly spendLimiter;
     private readonly annotationCache;
     private agentKeyWarned;
+    private senderKeyWarned;
     constructor(inner: McpForwarder, policy: CompiledPolicy, options?: GovernedForwarderOptions);
     /**
      * Swap the compiled policy atomically and reconcile limit bucket state
@@ -1617,6 +1866,15 @@ declare class GovernedForwarder implements McpForwarder {
      */
     primeAnnotationCache(): Promise<AnnotationCachePrimeResult>;
     forward(request: McpRequest): Promise<ForwardResult>;
+    /**
+     * Apply a tools/list response to the definition cache and surface any
+     * drift: console warning + immediate audit record per event. Single entry
+     * point for both runtime tools/list responses and startup priming, so the
+     * cache is updated exactly once per response.
+     */
+    private applyToolDefinitionUpdate;
+    /** Write an immediate audit record for a drift event (not a tool call). */
+    private writeDriftAuditRecord;
     private handleToolsCall;
     private handleApproval;
     private handleRateLimit;
@@ -1631,6 +1889,7 @@ declare class GovernedForwarder implements McpForwarder {
     /** Determine if the request was actually forwarded to the upstream MCP server. */
     private wasForwardedUpstream;
     private writeAuditRecord;
+    private makeDriftBlockResult;
     private makeDenyResult;
     private makePolicyMisconfiguredResult;
     private makeUnsupportedResult;
@@ -1640,15 +1899,169 @@ declare class GovernedForwarder implements McpForwarder {
     private makeClientDisconnectedBlockResult;
 }
 
+/** The outcome vocabulary adapters branch on — never internal rule actions. */
+type WireDecision = 'allow' | 'deny' | 'require_approval' | 'rate_limited' | 'spend_limited' | 'dry_run';
+/** Tool definition carried by /evaluate (optional; enables the drift guard). */
+interface WireToolDefinition {
+    readonly name: string;
+    readonly description?: string;
+    readonly input_schema?: unknown;
+    readonly output_schema?: unknown;
+    readonly title?: string;
+    readonly annotations?: Record<string, unknown>;
+}
+interface EvaluateInput {
+    readonly origin: string;
+    readonly adapter_version?: string;
+    readonly agent_id: string | null;
+    readonly session_id: string | null;
+    readonly tool: WireToolDefinition;
+    readonly arguments: Record<string, unknown> | undefined;
+    readonly metadata: Record<string, unknown> | null;
+}
+interface InstallScanInput {
+    readonly origin: string;
+    readonly agent_id: string | null;
+    readonly session_id: string | null;
+    readonly package: {
+        readonly name: string;
+        readonly version?: string;
+        readonly source?: string;
+        readonly spec?: string;
+        readonly url?: string;
+    };
+    readonly metadata: Record<string, unknown> | null;
+}
+interface AuditInput {
+    readonly evaluation_id: string;
+    readonly status: 'success' | 'error' | 'not_executed';
+    readonly error?: string;
+    readonly duration_ms?: number;
+    readonly result?: unknown;
+    readonly actual_amount?: number;
+}
+interface ResolveApprovalInput {
+    readonly resolution: 'approved' | 'denied' | 'timeout' | 'cancelled';
+    readonly resolved_by?: string;
+    readonly reason?: string;
+    readonly scope?: 'once' | 'always';
+}
+/** A service result: HTTP status + JSON body, adapted verbatim by the route. */
+interface ServiceResult {
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+}
+interface GovernanceServiceOptions {
+    readonly policy: CompiledPolicy;
+    readonly environment?: string;
+    readonly evidenceStore?: EvidenceStore;
+    readonly approvalRouter?: ApprovalRouter;
+    readonly rateLimiter?: RateLimiter;
+    readonly spendLimiter?: SpendLimiter;
+    readonly auditWriter?: AuditWriter;
+    /** Default approval timeout (ms) when a rule sets none. */
+    readonly approvalTimeoutMs?: number;
+    /** Pending-evaluation TTL (ms). Default 10 minutes. */
+    readonly ttlMs?: number;
+    /** Clock for testable time. Defaults to Date.now. */
+    readonly now?: () => number;
+    /** Sweep interval (ms). 0 disables the periodic GC backstop. Default 30s. */
+    readonly sweepIntervalMs?: number;
+    /** Max pending evaluations (count). Default 10,000. Overridable for tests. */
+    readonly maxPending?: number;
+    /** Max pending-evaluation footprint (serialized bytes). Default 64 MiB. */
+    readonly maxPendingBytes?: number;
+    /** Max distinct sender_id limit keys (issue #13). Default 50,000. Overridable for tests. */
+    readonly maxSenderKeys?: number;
+}
+declare class GovernanceService {
+    private policy;
+    private readonly environment;
+    private readonly evidenceStore;
+    private readonly approvalRouter;
+    private readonly rateLimiter;
+    private readonly spendLimiter;
+    private readonly auditWriter;
+    private readonly approvalTimeoutMs;
+    private readonly ttlMs;
+    private readonly now;
+    private readonly maxPending;
+    private readonly maxPendingBytes;
+    private readonly maxSenderKeys;
+    /** Distinct sender_id limit keys with live state (reservation registry, issue #13). */
+    private readonly senderKeys;
+    private readonly pending;
+    private readonly tombstones;
+    private readonly caches;
+    /** Native approval ticket id → its pending evaluation id, for on-access
+     * deadline enforcement on the resolve path. */
+    private readonly ticketToEvaluation;
+    private pendingBytes;
+    private sweepTimer;
+    private closed;
+    constructor(options: GovernanceServiceOptions);
+    /** Swap the compiled policy on hot-reload (mirrors GovernedForwarder). */
+    updatePolicy(policy: CompiledPolicy): void;
+    evaluate(req: EvaluateInput): ServiceResult;
+    audit(req: AuditInput, payloadHash: string): ServiceResult;
+    installScan(req: InstallScanInput): ServiceResult;
+    /** First-match-wins evaluation of the compiled install policy (issue #13). */
+    private evaluateInstall;
+    resolveApproval(ticketId: string, req: ResolveApprovalInput): ServiceResult;
+    sweep(): void;
+    /**
+     * Reserve a cardinality slot for a sender-keyed limit (issue #13).
+     *
+     * Only `sender:*` keys are gated — tool/session families are bounded by upstream
+     * cardinality, and the MCP path never reaches here, so structural traffic cannot
+     * be starved. A key already backed by live state (registry or a live limiter
+     * bucket) costs no new slot. At capacity we lazily prune dead keys before failing
+     * closed, so an emptied bucket frees its slot without waiting for the sweep.
+     */
+    private reserveSenderKey;
+    /** Drop registry keys with no pending evaluation AND no live limiter bucket. */
+    private pruneSenderKeys;
+    /**
+     * Whether either limiter still holds a live bucket for `key`. Uses the public
+     * `getKeyState()` — never the limiters' private maps — and its lazy eviction of
+     * an emptied bucket IS the prune-on-touch mechanism.
+     */
+    private hasLiveBucket;
+    close(): void;
+    /** Apply crossed deadlines to one pending entry. Returns its post-state. */
+    private enforceDeadlines;
+    private cacheFor;
+    private discardPending;
+    private getTicketStatus;
+    private planRate;
+    private planSpend;
+    /** Commit a limit plan at /audit time and return the evidence_chain block. */
+    private commitLimit;
+    private writeAudit;
+    private assertApprovalRouter;
+}
+
 /** 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.
+     * Bearer token for the evidence/context/session routes (the SDK scope).
+     * When omitted or empty, those routes run open — useful for local
+     * development when the operator has disabled the per-boot token via env.
      */
     readonly token?: string;
+    /**
+     * Bearer token for the governance routes (the adapter scope, issue #12/F6).
+     * Distinct from `token` so an SDK client cannot drive policy decisions and
+     * an adapter cannot write evidence it was not granted. When omitted, the
+     * governance routes run open (and only mount if `governance` is provided).
+     */
+    readonly adapterToken?: string;
+    /**
+     * The governance service backing `/evaluate`, `/audit`, `/install-scan`, and
+     * `/approval/:id/resolve`. When omitted, those routes return 503
+     * `governance_unavailable` (evidence-only deployments, and existing tests).
+     */
+    readonly governance?: GovernanceService;
 }
 /**
  * Create a Hono app for the SDK sideband API.
@@ -1673,6 +2086,20 @@ interface SidebandAppOptions {
  */
 declare function createSidebandApp(store: EvidenceStore, options?: SidebandAppOptions): Hono;
 
+/**
+ * Error thrown when the GovernanceService is wired in a way that could fail
+ * open — for example, an approval-capable policy with no ApprovalRouter to
+ * route `require_approval` decisions through (issue #12). Surfaced at
+ * construction and on hot-reload so a misconfiguration crashes loudly rather
+ * than silently degrading an approval into an unenforced allow.
+ *
+ * Direct embedders of GovernanceService can catch this distinctly; the bundled
+ * CLI always provides a router, so it never fires in the shipped path.
+ */
+declare class GovernanceConfigError extends Error {
+    constructor(message: string);
+}
+
 /** @internal Exported for testing only. */
 declare class QueueChannel implements ApprovalChannel {
     readonly type = "dashboard";
@@ -1809,6 +2236,8 @@ interface ActionEvent {
     readonly dry_run: boolean;
     readonly matched_rule: string | null;
     readonly matched_rule_index: number | null;
+    readonly record_kind: AuditRecord['record_kind'];
+    readonly origin: string;
 }
 /** Payload for an approval_requested event. */
 interface ApprovalRequestedEvent {
@@ -1903,4 +2332,4 @@ interface DashboardAppOptions {
  */
 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, StreamableHttpForwarder, type StreamableHttpForwarderOptions, UpstreamForwarder, type UpstreamForwarderOptions, VERSION, WebhookChannel, type WebhookChannelOptions, compilePolicies, createApp, createApprovalApp, createChannels, createDashboardApp, createSidebandApp, createSlackActionApp, evaluatePolicy, loadConfig, matchRule, startServer, startSidebandServer };
+export { type ApprovalAppOptions, type ApprovalChannel, type ApprovalOutcome, ApprovalQueue, type ApprovalQueueOptions, ApprovalRouter, type ApprovalRouterOptions, type ApprovalStatus, type ApprovalTicket, type AuditAggregateStats, type AuditInput, 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 EvaluateInput, type EvidenceEntry, EvidenceStore, type EvidenceStoreOptions, GovernanceConfigError, GovernanceService, type GovernanceServiceOptions, GovernedForwarder, type GovernedForwarderOptions, type HelioConfig, type InstallScanInput, type MatchContext, type PolicyDecision, PolicyParseError, QueueChannel, type RateLimitCheckParams, type RateLimitKeyState, type RateLimitResult, RateLimiter, type RateLimiterOptions, type ResolveApprovalInput, type ServerHandle, type SessionState, type SlackActionAppOptions, SlackChannel, type SlackChannelOptions, type SpendLimitCheckParams, type SpendLimitKeyState, type SpendLimitResult, SpendLimiter, type SpendLimiterOptions, SseUpstreamForwarder, type SseUpstreamForwarderOptions, StdioForwarder, type StdioForwarderOptions, StreamableHttpForwarder, type StreamableHttpForwarderOptions, UpstreamForwarder, type UpstreamForwarderOptions, VERSION, WebhookChannel, type WebhookChannelOptions, type WireDecision, compilePolicies, createApp, createApprovalApp, createChannels, createDashboardApp, createSidebandApp, createSlackActionApp, evaluatePolicy, loadConfig, matchRule, startServer, startSidebandServer };