@gethelio/proxy 0.12.0 → 0.13.0

package/dist/index.d.ts

@@ -51,6 +51,7 @@ declare const policiesSchema: z.ZodObject<{
                 contains: z.ZodOptional<z.ZodString>;
                 regex: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>]>>>;
+            upstreams: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>;
         action: z.ZodEnum<{
             deny: "deny";
@@ -171,6 +172,7 @@ declare const budgetSchema: z.ZodObject<{
                 contains: z.ZodOptional<z.ZodString>;
                 regex: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>>;
+            upstreams: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>;
         field: z.ZodString;
     }, z.core.$strict>>>;
@@ -190,11 +192,237 @@ declare const approvalChannelSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"dashboard">;
     name: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>], "type">;
-/** Zod schema for the complete `helio.yaml` configuration file. */
-declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodObject<{
+declare const singularConfigSchema: z.ZodObject<{
+    listen: z.ZodPrefault<z.ZodObject<{
+        port: z.ZodDefault<z.ZodNumber>;
+        host: z.ZodDefault<z.ZodString>;
+        allowed_origins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    environment: z.ZodOptional<z.ZodString>;
+    session: z.ZodPrefault<z.ZodObject<{
+        identity: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            source: z.ZodLiteral<"header">;
+            name: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string, string>>;
+        }, z.core.$strict>, z.ZodObject<{
+            source: z.ZodLiteral<"meta">;
+        }, z.core.$strict>, z.ZodObject<{
+            source: z.ZodLiteral<"legacy_header">;
+        }, z.core.$strict>], "source">>>;
+        on_unresolved: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+            anonymous: "anonymous";
+        }>>;
+    }, z.core.$strict>>;
+    policies: z.ZodPrefault<z.ZodObject<{
+        default: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+            allow: "allow";
+        }>>;
+        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>;
+                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>]>>>;
+                upstreams: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>;
+            action: z.ZodEnum<{
+                deny: "deny";
+                allow: "allow";
+                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";
+                    sender_id: "sender_id";
+                }>>;
+                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";
+                        sender_id: "sender_id";
+                    }>>;
+                }, 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>>>;
+        install: z.ZodOptional<z.ZodObject<{
+            default: z.ZodDefault<z.ZodEnum<{
+                deny: "deny";
+                allow: "allow";
+            }>>;
+            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";
+        }>>;
+        tool_revalidation: z.ZodOptional<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            interval: z.ZodDefault<z.ZodString>;
+            max_advertised_ttl: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        hot_reload: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    budgets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        limit: z.ZodNumber;
+        currency: z.ZodString;
+        window: z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"session">]>;
+        key: z.ZodDefault<z.ZodEnum<{
+            session: "session";
+            sender_id: "sender_id";
+            global: "global";
+        }>>;
+        on_exceed: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+            require_approval: "require_approval";
+        }>>;
+        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>>;
+        idle_ttl: z.ZodOptional<z.ZodString>;
+        contributors: z.ZodArray<z.ZodPipe<z.ZodUnknown, z.ZodObject<{
+            match: z.ZodObject<{
+                tool: z.ZodString;
+                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>>>;
+                upstreams: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>;
+            field: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>>;
+    approval: z.ZodPrefault<z.ZodObject<{
+        timeout: z.ZodDefault<z.ZodString>;
+        default_on_timeout: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+            allow: "allow";
+        }>>;
+        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.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"webhook">;
+            name: z.ZodOptional<z.ZodString>;
+            url: z.ZodString;
+            secret: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"dashboard">;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>], "type">>>;
+    }, z.core.$strict>>;
+    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.$strict>>;
+    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.$strict>>;
+    sdk: z.ZodPrefault<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.$strict>>;
     version: z.ZodLiteral<"1">;
     upstream: z.ZodObject<{
-        url: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
         transport: z.ZodDefault<z.ZodEnum<{
             "streamable-http": "streamable-http";
             sse: "sse";
@@ -212,6 +440,8 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
         forward_headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
         headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strict>;
+}, z.core.$strict>;
+declare const namedConfigSchema: z.ZodObject<{
     listen: z.ZodPrefault<z.ZodObject<{
         port: z.ZodDefault<z.ZodNumber>;
         host: z.ZodDefault<z.ZodString>;
@@ -269,6 +499,7 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
                     contains: z.ZodOptional<z.ZodString>;
                     regex: z.ZodOptional<z.ZodString>;
                 }, z.core.$strict>]>>>;
+                upstreams: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>;
             action: z.ZodEnum<{
                 deny: "deny";
@@ -389,6 +620,7 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
                     contains: z.ZodOptional<z.ZodString>;
                     regex: z.ZodOptional<z.ZodString>;
                 }, z.core.$strict>>>;
+                upstreams: z.ZodOptional<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>;
             field: z.ZodString;
         }, z.core.$strict>>>;
@@ -437,9 +669,38 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
         host: z.ZodDefault<z.ZodString>;
         evaluation_ttl: z.ZodDefault<z.ZodString>;
     }, z.core.$strict>>;
-}, z.core.$strict>>;
-/** Fully validated and defaulted Helio configuration. */
-type HelioConfig = z.infer<typeof helioConfigSchema>;
+    version: z.ZodLiteral<"1">;
+    upstreams: z.ZodArray<z.ZodObject<{
+        url: z.ZodOptional<z.ZodString>;
+        transport: z.ZodDefault<z.ZodEnum<{
+            "streamable-http": "streamable-http";
+            sse: "sse";
+            stdio: "stdio";
+        }>>;
+        protocol_version: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            "2025-06-18": "2025-06-18";
+            "2026-07-28": "2026-07-28";
+        }>>;
+        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>>;
+        headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** A fully validated and defaulted singular-mode (`upstream:`) configuration. */
+type SingularHelioConfig = z.output<typeof singularConfigSchema>;
+/** A fully validated and defaulted named-mode (`upstreams:`) configuration. */
+type NamedHelioConfig = z.output<typeof namedConfigSchema>;
+/** Fully validated and defaulted Helio configuration — one of the two mode arms. */
+type HelioConfig = SingularHelioConfig | NamedHelioConfig;
+/** Narrow a parsed config to the singular-mode (`upstream:`) arm. */
+declare function isSingularConfig(config: HelioConfig): config is SingularHelioConfig;
+/** Narrow a parsed config to the named-mode (`upstreams:`) arm. */
+declare function isNamedConfig(config: HelioConfig): config is NamedHelioConfig;
 /** An approval channel configuration (slack, webhook, or dashboard). */
 type ApprovalChannel$1 = z.infer<typeof approvalChannelSchema>;
 /** The policies section of the config. */
@@ -530,6 +791,8 @@ interface CompiledMatch {
     readonly environment?: string;
     /** Flattened list of metadata conditions (one entry per key+operator pair). */
     readonly metadata?: readonly MetadataCondition[];
+    /** Configured upstream names the rule is scoped to, OR within the list (issue #293). */
+    readonly upstreams?: readonly string[];
 }
 /** Compiled approval configuration with durations as milliseconds. */
 interface CompiledApproval {
@@ -673,6 +936,12 @@ interface MatchContext {
      * request column) is merged in by the decision pipeline, not stored here twice.
      */
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /**
+     * The governed door's configured upstream name (issue #295). A string only on
+     * the MCP path when a name is configured; undefined on the sideband and in
+     * singular mode, so upstream-scoped rules are inert there by construction.
+     */
+    readonly upstream?: string;
 }
 
 /** One compiled contributor: which calls feed the budget, and from which field. */
@@ -682,6 +951,13 @@ interface CompiledBudgetContributor {
         /** Flattened conditions (one per path+operator); absent when unconditioned. */
         readonly input?: readonly InputCondition[];
     };
+    /**
+     * Configured upstream names the contributor is scoped to (issue #293);
+     * absent means every door contributes. A scoped contributor never
+     * participates when the charge context carries no upstream (sideband,
+     * singular mode).
+     */
+    readonly upstreams?: readonly string[];
     /** Dot-path into the tool arguments (e.g. "$.amount"), resolved per call. */
     readonly field: string;
 }
@@ -836,6 +1112,47 @@ interface CreateAppOptions {
  * @param options - Optional sub-apps to mount.
  */
 declare function createApp(config: HelioConfig, forwarder: McpForwarder, options?: CreateAppOptions): Hono;
+/**
+ * Optional sub-apps and callbacks for the multi-upstream composition.
+ * The main-port posture is `createApp`'s (see CreateAppOptions): only the
+ * Slack webhook callback belongs beside the MCP doors.
+ */
+interface CreateMultiAppOptions {
+    /** Slack interactive action handler (mounted at /slack/actions, global). */
+    slackActionApp?: Hono;
+    /**
+     * Recorder for inbound header/body agreement rejections (issue #226),
+     * called with the name of the door that rejected so the audit record can
+     * attribute it. Enforcement does not depend on it.
+     */
+    onHeaderMismatch?: (rejection: HeaderMismatchRejection, upstreamName: string) => void;
+    /**
+     * @internal Test seam for the per-door concurrent-session cap on the
+     * `/sse/<name>` mounts (issue #232's cap, per-route by construction), so
+     * tests need not mint 1024 real streams per door. The same value goes to
+     * every door's route; the session maps stay per-route-instance. Not wired
+     * to config — absent means the hardcoded 1024.
+     */
+    sse?: {
+        readonly maxConcurrentSessions?: number;
+    };
+}
+/**
+ * Create a Hono app serving every named upstream at its own pair of mounts,
+ * `/mcp/<name>` and `/sse/<name>`, each a fresh route stack wrapping that
+ * entry's forwarder. `/healthz` and `/slack/actions` stay global. There is
+ * NO bare-path default: bare `/mcp`, `/sse`, and unknown names get an
+ * explicit 404 catch-all whose JSON-RPC envelope states the path shape and
+ * never enumerates configured names.
+ *
+ * @param config - The validated named-mode Helio configuration.
+ * @param forwarders - One forwarder per configured entry, keyed by name.
+ *   Must cover the configured names exactly; missing or extra keys throw
+ *   (a missing key would silently mount a dead door, an extra one means the
+ *   record drifted from the config — fail at composition, not per request).
+ * @param options - Optional sub-apps and callbacks.
+ */
+declare function createMultiApp(config: HelioConfig, forwarders: Record<string, McpForwarder>, options?: CreateMultiAppOptions): Hono;
 /**
  * Start the HTTP server on the configured host and port.
  *
@@ -866,6 +1183,11 @@ interface StreamableHttpForwarderOptions {
     requestTimeoutMs?: number;
     /** `upstream.protocol_version`: `auto` (default) probes; a dated pin skips it. */
     protocolVersion?: UpstreamProtocolVersionPin;
+    /**
+     * The operator-chosen upstream entry name (issue #295), threaded to the
+     * session manager's era lifecycle lines. Unset in singular mode.
+     */
+    upstreamName?: string;
 }
 /**
  * Spec-compliant upstream MCP Streamable HTTP client.
@@ -984,6 +1306,11 @@ interface StdioForwarderOptions {
     retryDelayMs?: number;
     /** Timeout in milliseconds for individual requests. */
     requestTimeoutMs?: number;
+    /**
+     * The operator-chosen upstream entry name (multi-upstream mode). Unset in
+     * singular mode — the death line then keeps its bare `[helio]` tag.
+     */
+    upstreamName?: string;
 }
 /**
  * Forward MCP requests to an upstream server via stdio.
@@ -997,6 +1324,7 @@ declare class StdioForwarder implements McpForwarder {
     private readonly maxRetries;
     private readonly retryDelayMs;
     private readonly pending;
+    private readonly logTag;
     private child;
     private buffer;
     private retryCount;
@@ -1156,6 +1484,14 @@ interface AuditRecord {
      * and on records with no MCP wire (drift events, sideband records).
      */
     readonly protocol_version: string | null;
+    /**
+     * Name of the upstream MCP server this record is attributed to (issue
+     * #292). Null in singular mode (no named upstreams configured), on
+     * sideband records (no MCP door), and on rows that predate the column.
+     * Required-nullable like session_source/protocol_version: a producer that
+     * could silently omit it would exempt that door from attribution.
+     */
+    readonly upstream: string | null;
     /** ISO 8601 timestamp of when the record was persisted. */
     readonly created_at: string;
 }
@@ -1171,6 +1507,18 @@ interface AuditQueryFilters {
     readonly blocked?: boolean;
     /** Filter by session ID (exact match). */
     readonly session_id?: string;
+    /**
+     * Filter by session identity source (exact match — the five-value
+     * `header` / `meta` / `legacy_header` / `transport` / `sideband`
+     * vocabulary, issue #250). SQL equality: rows whose session_source is
+     * NULL never match any filter value.
+     */
+    readonly session_source?: string;
+    /**
+     * Filter by upstream name (exact match). SQL equality: rows whose
+     * upstream is NULL never match any filter value.
+     */
+    readonly upstream?: string;
     /** Filter by agent ID (exact match). */
     readonly agent_id?: string;
     /** Include only records created at or after this ISO 8601 timestamp. */
@@ -1239,9 +1587,15 @@ interface AuditAggregateStats {
         readonly reason: string;
         readonly count: number;
     }>;
-    /** Top tools by call count (max 10). */
+    /**
+     * Top tools by call count (max 10 rows). Each row is a (tool, upstream)
+     * pair (issue #297): same-named tools on different upstreams stay
+     * distinct. Upstream is null in singular mode, so all-null groups reduce
+     * to exactly the pre-#297 per-tool rows.
+     */
     readonly top_tools: ReadonlyArray<{
         readonly tool_name: string;
+        readonly upstream: string | null;
         readonly count: number;
     }>;
     /** Approval rate (approved / total require_approval decisions), or null if none. */
@@ -1364,8 +1718,15 @@ declare class AuditStore {
     private query;
     /** Count records matching the given filters. */
     count(filters?: AuditQueryFilters): number;
-    /** Get aggregate statistics for a time range. */
-    aggregate(from?: string, to?: string): AuditAggregateStats;
+    /**
+     * Get aggregate statistics for a time range. The optional upstream filter
+     * scopes EVERY sub-aggregate (totals, by_decision, by_block_reason,
+     * top_tools, approval_rate, per_hour) — "analytics for this door", not one
+     * filtered chart. Exact match: null-upstream rows never match any value.
+     */
+    aggregate(from?: string, to?: string, filters?: {
+        upstream?: string;
+    }): AuditAggregateStats;
     /** Delete records older than the retention period. Returns the count of deleted records. */
     purgeExpired(): number;
     private purgeBefore;
@@ -1653,6 +2014,18 @@ interface ApprovalTicket {
     readonly rule_index: number | null;
     readonly channel_name: string;
     readonly session_id: string | null;
+    /**
+     * Which identity strategy produced session_id (issue #251): the MCP
+     * resolver's vocabulary on proxy tickets, `sideband` on adapter tickets.
+     * OPTIONAL-ABSENT, not nullable: the ticket is the wire object, and an
+     * unattributed ticket omits the key rather than emitting null.
+     */
+    readonly session_source?: string;
+    /**
+     * Upstream attribution (issue #292). Absent in singular mode and on
+     * native (sideband) tickets — same wire-additive optional spelling.
+     */
+    readonly upstream?: string;
     readonly requested_at: string;
     readonly timeout_at: string;
     readonly timeout_ms: number;
@@ -1748,6 +2121,10 @@ declare class ApprovalQueue {
         timeout_ms: number;
         /** Breached budget context on break-glass / merged tickets (issue #14). */
         breached_budgets?: readonly BudgetBreachContext[];
+        /** Identity-strategy attribution for session_id (issue #251). */
+        session_source?: string | null;
+        /** Upstream attribution (issue #292); absent in singular mode. */
+        upstream?: string | null;
     }): ApprovalTicket;
     /** Get a ticket by ID. Returns undefined if not found. */
     get(id: string): ApprovalTicket | undefined;
@@ -1803,6 +2180,13 @@ interface ApprovalSubmitParams {
     readonly tool_input: Record<string, unknown>;
     readonly matched_rule: CompiledPolicyRule | undefined;
     readonly session_id: string | null;
+    /**
+     * Identity-strategy attribution for session_id (issue #251).
+     * Required-nullable so no submit site can silently forget it.
+     */
+    readonly session_source: string | null;
+    /** Upstream attribution (issue #292); null in singular mode. */
+    readonly upstream: string | null;
     /** Breached budget context; marks the ticket as break-glass (issue #14). */
     readonly breached_budgets?: readonly BudgetBreachContext[];
     /**
@@ -2010,12 +2394,21 @@ declare class RateLimiter {
      * 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`.
+     * `{ maxCalls, windowMs }` tuple still appears 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.
      *
+     * Keys built by `ruleBucketKey` (bucket-key.ts) carry the owning rule's
+     * index, and for those the tuple must match at THAT index
+     * (`config.ruleIndex`): a reorder that shifts a rate rule's index evicts
+     * its old-index bucket instead of leaving an orphan no rule reads again —
+     * or worse, letting whatever rule now sits at that index adopt another
+     * rule's accrued calls. Un-suffixed keys keep the tuple-anywhere match,
+     * but only against index-less configs — a caller that passes only indexed
+     * configs (as the proxy does) evicts every un-suffixed bucket, fail-closed.
+     *
      * 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.
@@ -2023,6 +2416,7 @@ declare class RateLimiter {
     reconcile(validConfigs: Iterable<{
         maxCalls: number;
         windowMs: number;
+        ruleIndex?: number;
     }>): void;
     /** Stop the cleanup timer and mark as closed. */
     /**
@@ -2151,12 +2545,14 @@ declare class SpendLimiter {
      * whose config is gone (rule changed or removed) are evicted so the next
      * check lazy-creates a fresh bucket under the new config.
      *
-     * Keys built by {@link spendBucketKey} carry the owning rule's index, and
-     * for those the tuple must match at THAT index (`config.ruleIndex`): a
+     * Keys built by `ruleBucketKey` (bucket-key.ts) carry the owning rule's
+     * index, and for those the tuple must match at THAT index (`config.ruleIndex`): a
      * reorder that shifts a spend rule's index evicts its old-index bucket
      * instead of leaving an orphan no rule reads again — or worse, letting
      * whatever rule now sits at that index adopt another rule's accrued spend.
-     * Un-suffixed keys keep the tuple-anywhere match.
+     * Un-suffixed keys keep the tuple-anywhere match, but only against
+     * index-less configs — a caller that passes only indexed configs (as the
+     * proxy does) evicts every un-suffixed bucket, fail-closed.
      *
      * 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
@@ -2205,6 +2601,13 @@ interface BudgetChargeContext {
     readonly sessionId: GatedSession | null;
     /** Adapter-supplied sender id (sideband only); null on the MCP path. */
     readonly senderId: string | null;
+    /**
+     * The governed door's configured upstream name (issue #295); null on the
+     * sideband and in singular mode. Required so every door states its
+     * upstream: a silently-missing value would exempt that door's calls from
+     * upstream-scoped contributors once those exist.
+     */
+    readonly upstream: string | null;
 }
 /** One budget's share of a call: which bucket, how much. */
 interface BudgetCharge {
@@ -2218,6 +2621,12 @@ interface BudgetCharge {
      * NOT repopulate the new pot with old-config spend — recordAll skips it.
      */
     readonly generation: number;
+    /**
+     * The charge context's upstream name, stamped only when the door set one
+     * (issue #295). Optional is the honest type: `remintDeferredCharges`
+     * rebuilds charges without it, so deferred commits snapshot null.
+     */
+    readonly upstream?: string;
 }
 /** A budget whose contributor matched but whose amount was unusable. */
 interface BudgetChargeFailure {
@@ -2242,6 +2651,11 @@ interface BudgetPeekEntry {
     readonly remaining: number;
     /** Epoch ms when the oldest entry ages out (duration); null for session pots. */
     readonly resetAtMs: number | null;
+    /**
+     * The charge's upstream label, or null: sideband calls, singular mode, and
+     * reminted deferred commits all snapshot null (issue #295).
+     */
+    readonly upstream: string | null;
     /**
      * Set on recordAll snapshots for charges frozen before a tuple-changing
      * reload: the executed spend was ledgered under its evaluate-time
@@ -2306,6 +2720,12 @@ interface BudgetCommitEvent {
     readonly limit: number;
     readonly currency: string;
     readonly utilization: number;
+    /**
+     * Upstream attribution from the charge context (issue #292), or null.
+     * Reminted frozen-plan charges drop the label by design, so deferred
+     * sideband commits always emit null here.
+     */
+    readonly upstream: string | null;
 }
 /**
  * Payload for the per-budget breach callback (dashboard event bus). Fired
@@ -2322,6 +2742,8 @@ interface BudgetBreachEvent {
     readonly spent: number;
     readonly limit: number;
     readonly currency: string;
+    /** Upstream attribution from the peek entry's context (issue #292), or null. */
+    readonly upstream: string | null;
 }
 /** Wire-ready bucket state for `GET /api/budgets` (snake_case DTO). */
 interface BudgetBucketState {
@@ -2373,14 +2795,18 @@ declare class BudgetEngine {
     /**
      * Resolve which budgets a call feeds and how much it charges each.
      *
-     * A contributor participates when its tool glob matches the tool name AND
-     * every `match.input` condition holds (absent conditions means the glob
-     * alone decides); the FIRST participating contributor (config order, over
-     * that combined predicate) supplies the amount field. A call that matches
-     * the glob but not the conditions simply does not feed the budget — no
-     * charge, no failure. Once a contributor is selected, a missing,
-     * non-numeric, negative, or non-finite amount fails closed as a `failures`
-     * entry — the caller must deny the call.
+     * A contributor participates when its upstream scope admits the call's
+     * door (absent scope admits every door; a scoped contributor never
+     * participates when `ctx.upstream` is null — sideband, singular mode) AND
+     * its tool glob matches the tool name AND every `match.input` condition
+     * holds (absent conditions means the glob alone decides); the FIRST
+     * participating contributor (config order, over that combined predicate)
+     * supplies the amount field. A call that matches the glob but not the
+     * conditions or the scope simply does not feed the budget — no charge, no
+     * failure — and a later contributor may still participate. Once a
+     * contributor is selected, a missing, non-numeric, negative, or non-finite
+     * amount fails closed as a `failures` entry — the caller must deny the
+     * call.
      */
     resolveCharges(ctx: BudgetChargeContext): {
         charges: BudgetCharge[];
@@ -2533,6 +2959,13 @@ interface GovernedForwarderOptions {
      * default chain (deny mode) for direct/library construction.
      */
     session?: CompiledSessionIdentity;
+    /**
+     * The operator-chosen upstream entry name (issue #295, multi-upstream
+     * substrate). Unset in singular mode — every governance surface then
+     * behaves exactly as today. The multi-upstream composition loop (issue
+     * #294) passes each entry's name.
+     */
+    upstreamName?: string;
 }
 /** Result of attempting to prime the tool annotation cache. */
 interface AnnotationCachePrimeResult {
@@ -2562,6 +2995,7 @@ declare class GovernedForwarder implements McpForwarder {
     private readonly rateLimiter;
     private readonly spendLimiter;
     private readonly budgetEngine;
+    private readonly upstreamName;
     private readonly annotationCache;
     private agentKeyWarned;
     private senderKeyWarned;
@@ -2673,7 +3107,9 @@ declare class GovernedForwarder implements McpForwarder {
      */
     private handleDryRun;
     /**
-     * Construct a non-session limit bucket key. Session keys are deliberately
+     * Construct a non-session limit bucket key. Tool-scope keys route through
+     * the shared `toolLimitKey` leaf, which prefixes them with the configured
+     * upstream name when one is set (issue #295). Session keys are deliberately
      * NOT built here: they come only from the gate module's `sessionLimitKey`,
      * whose `GatedSession` parameter makes skipping the identity gate a
      * compile error (issue #218) — call sites branch on `key === 'session'`.
@@ -2730,6 +3166,13 @@ interface BudgetEventRecord {
     readonly timestamp: string;
     readonly timestamp_ms: number;
     readonly created_at: string;
+    /**
+     * Upstream attribution read from the referenced audit record via LEFT
+     * JOIN (issue #292) — never a stored ledger column. Null on singular-mode
+     * records, dangling or null `audit_record_id`, and rows predating the
+     * audit column; a null renders as empty/absent, never a made-up label.
+     */
+    readonly upstream: string | null;
 }
 /** One page of a budget's event history plus the unpaginated total. */
 interface BudgetEventsPage {
@@ -3020,7 +3463,7 @@ declare class GovernanceConfigError extends Error {
  * reserved `'<header_mismatch>'` sentinel — either way `top_tools` already
  * excludes rejected records, so these rows never pollute tool rankings.
  */
-declare function buildHeaderMismatchAuditRecord(rejection: HeaderMismatchRejection, environment?: string): Omit<AuditRecord, 'id' | 'created_at'>;
+declare function buildHeaderMismatchAuditRecord(rejection: HeaderMismatchRejection, environment?: string, upstream?: string): Omit<AuditRecord, 'id' | 'created_at'>;
 
 /** @internal Exported for testing only. */
 declare class QueueChannel implements ApprovalChannel {
@@ -3164,6 +3607,8 @@ interface ActionEvent {
     readonly matched_rule_index: number | null;
     readonly record_kind: AuditRecord['record_kind'];
     readonly origin: string;
+    /** Upstream attribution from the audit record (issue #292), or null. */
+    readonly upstream: string | null;
 }
 /** Payload for an approval_requested event. */
 interface ApprovalRequestedEvent {
@@ -3171,6 +3616,8 @@ interface ApprovalRequestedEvent {
     readonly tool_name: string;
     readonly channel: string;
     readonly requested_at: string;
+    /** Upstream attribution from the ticket (issue #292), or null. */
+    readonly upstream: string | null;
 }
 /** Payload for an approval_resolved event. */
 interface ApprovalResolvedEvent {
@@ -3186,6 +3633,11 @@ interface LimitWarningEvent {
     readonly current: number;
     readonly limit: number;
     readonly utilization: number;
+    /**
+     * Upstream name parsed from a partitioned bucket key (issue #292), or
+     * null — session keys, singular tool keys, and sideband keys have no door.
+     */
+    readonly upstream: string | null;
 }
 /** Payload for approval notification delivery failures. */
 interface ApprovalNotificationFailedEvent {
@@ -3289,6 +3741,20 @@ interface DashboardAppOptions {
     readonly staticDir?: string;
     /** SSE heartbeat interval in milliseconds. Defaults to 30 000 (30s). */
     readonly sseHeartbeatMs?: number;
+    /**
+     * @internal Test seam for the concurrent-connection cap (issue #285), so
+     * tests need not mint 256 real streams. Not wired to config — the cap is
+     * a hardcoded invariant (see MAX_SSE_CONNECTIONS).
+     */
+    readonly maxSseConnections?: number;
+    /**
+     * @internal Test seam for the stale-connection sweep cadence (issue
+     * #327), so sweeper tests need not wait out the production floor. `0`
+     * DISABLES the sweeper entirely (the repo-wide sweep-interval
+     * convention). Not wired to config — the 10 s floor stays the
+     * production default.
+     */
+    readonly sweepIntervalMs?: number;
 }
 /**
  * Create a Hono app for the dashboard REST + SSE API.
@@ -3298,4 +3764,4 @@ interface DashboardAppOptions {
  */
 declare function createDashboardApp(deps: DashboardAppDeps, options?: DashboardAppOptions): Hono;
 
-export { type AdapterLivenessEntry, 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 BudgetBreachContext, type BudgetBreachEvent, type BudgetBucketState, type BudgetCommitEvent, BudgetEngine, type BudgetEventRecord, type BudgetEventsPage, type BudgetLedgerRow, type BudgetLedgerSink, BudgetParseError, type BudgetState, type CompilePoliciesResult, type CompiledBudget, type CompiledBudgetContributor, type CompiledBudgetWindow, type CompiledPolicy, type CompiledPolicyRule, ConfigError, type CreateAppOptions, type DashboardAppDeps, type DashboardAppOptions, DashboardEventBus, type DashboardEventType, type DashboardEvents, EXPORT_MAX_RECORDS, type EvaluateInput, type EvidenceEntry, EvidenceStore, type EvidenceStoreOptions, GovernanceConfigError, GovernanceService, type GovernanceServiceOptions, GovernedForwarder, type GovernedForwarderOptions, type HeaderMismatchRejection, type HelioConfig, type InstallScanInput, LIST_MAX_PAGE_SIZE, 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, buildHeaderMismatchAuditRecord, compileBudgets, compilePolicies, createApp, createApprovalApp, createChannels, createDashboardApp, createSidebandApp, createSlackActionApp, evaluatePolicy, loadConfig, matchRule, startServer, startSidebandServer };
+export { type AdapterLivenessEntry, 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 BudgetBreachContext, type BudgetBreachEvent, type BudgetBucketState, type BudgetCommitEvent, BudgetEngine, type BudgetEventRecord, type BudgetEventsPage, type BudgetLedgerRow, type BudgetLedgerSink, BudgetParseError, type BudgetState, type CompilePoliciesResult, type CompiledBudget, type CompiledBudgetContributor, type CompiledBudgetWindow, type CompiledPolicy, type CompiledPolicyRule, ConfigError, type CreateAppOptions, type CreateMultiAppOptions, type DashboardAppDeps, type DashboardAppOptions, DashboardEventBus, type DashboardEventType, type DashboardEvents, EXPORT_MAX_RECORDS, type EvaluateInput, type EvidenceEntry, EvidenceStore, type EvidenceStoreOptions, GovernanceConfigError, GovernanceService, type GovernanceServiceOptions, GovernedForwarder, type GovernedForwarderOptions, type HeaderMismatchRejection, type HelioConfig, type InstallScanInput, LIST_MAX_PAGE_SIZE, type MatchContext, type NamedHelioConfig, type PolicyDecision, PolicyParseError, QueueChannel, type RateLimitCheckParams, type RateLimitKeyState, type RateLimitResult, RateLimiter, type RateLimiterOptions, type ResolveApprovalInput, type ServerHandle, type SessionState, type SingularHelioConfig, 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, buildHeaderMismatchAuditRecord, compileBudgets, compilePolicies, createApp, createApprovalApp, createChannels, createDashboardApp, createMultiApp, createSidebandApp, createSlackActionApp, evaluatePolicy, isNamedConfig, isSingularConfig, loadConfig, matchRule, startServer, startSidebandServer };