npm - @gethelio/proxy - Versions diffs - 0.11.0 → 0.12.0 - Mend

@gethelio/proxy 0.11.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md +75 -45
package/dist/cli.js +2351 -959
package/dist/dashboard-assets/assets/index-BBYXsIig.css +1 -0
package/dist/dashboard-assets/assets/index-uJng9NyO.js +128 -0
package/dist/dashboard-assets/index.html +2 -2
package/dist/index.d.ts +257 -20
package/dist/index.js +2205 -874
package/package.json +7 -7
package/dist/dashboard-assets/assets/index-CPoQ6xns.css +0 -1
package/dist/dashboard-assets/assets/index-D19fYKEH.js +0 -128

package/dist/dashboard-assets/index.html CHANGED Viewed

@@ -6,8 +6,8 @@
     <meta name="referrer" content="no-referrer" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <title>Helio Dashboard</title>
-    <script type="module" crossorigin src="/assets/index-D19fYKEH.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CPoQ6xns.css">
+    <script type="module" crossorigin src="/assets/index-uJng9NyO.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BBYXsIig.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/index.d.ts CHANGED Viewed

@@ -6,10 +6,18 @@ import { KnownBlock } from '@slack/web-api';
 declare const VERSION: string;
+declare const sessionIdentitySourceSchema: 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">;
 declare const policiesSchema: z.ZodObject<{
     default: z.ZodDefault<z.ZodEnum<{
-        allow: "allow";
         deny: "deny";
+        allow: "allow";
     }>>;
     flag_destructive: z.ZodOptional<z.ZodEnum<{
         require_approval: "require_approval";
@@ -45,8 +53,8 @@ declare const policiesSchema: z.ZodObject<{
             }, z.core.$strict>]>>>;
         }, z.core.$strict>;
         action: z.ZodEnum<{
-            allow: "allow";
             deny: "deny";
+            allow: "allow";
             require_approval: "require_approval";
             rate_limit: "rate_limit";
             spend_limit: "spend_limit";
@@ -92,8 +100,8 @@ declare const policiesSchema: z.ZodObject<{
     }, z.core.$strict>>>;
     install: z.ZodOptional<z.ZodObject<{
         default: z.ZodDefault<z.ZodEnum<{
-            allow: "allow";
             deny: "deny";
+            allow: "allow";
         }>>;
         rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
             name: z.ZodOptional<z.ZodString>;
@@ -122,6 +130,11 @@ declare const policiesSchema: z.ZodObject<{
         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>;
 declare const budgetSchema: z.ZodObject<{
@@ -187,6 +200,11 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
             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>;
@@ -197,12 +215,27 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
     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<{
-            allow: "allow";
             deny: "deny";
+            allow: "allow";
         }>>;
         flag_destructive: z.ZodOptional<z.ZodEnum<{
             require_approval: "require_approval";
@@ -238,8 +271,8 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
                 }, z.core.$strict>]>>>;
             }, z.core.$strict>;
             action: z.ZodEnum<{
-                allow: "allow";
                 deny: "deny";
+                allow: "allow";
                 require_approval: "require_approval";
                 rate_limit: "rate_limit";
                 spend_limit: "spend_limit";
@@ -285,8 +318,8 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
         }, z.core.$strict>>>;
         install: z.ZodOptional<z.ZodObject<{
             default: z.ZodDefault<z.ZodEnum<{
-                allow: "allow";
                 deny: "deny";
+                allow: "allow";
             }>>;
             rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
                 name: z.ZodOptional<z.ZodString>;
@@ -315,6 +348,11 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
             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<{
@@ -358,8 +396,8 @@ declare const helioConfigSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.Z
     approval: z.ZodPrefault<z.ZodObject<{
         timeout: z.ZodDefault<z.ZodString>;
         default_on_timeout: z.ZodDefault<z.ZodEnum<{
-            allow: "allow";
             deny: "deny";
+            allow: "allow";
         }>>;
         channels: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
             type: z.ZodLiteral<"slack">;
@@ -406,6 +444,8 @@ type HelioConfig = z.infer<typeof helioConfigSchema>;
 type ApprovalChannel$1 = z.infer<typeof approvalChannelSchema>;
 /** The policies section of the config. */
 type PoliciesConfig = z.infer<typeof policiesSchema>;
+/** A single identity source from `session.identity`. */
+type SessionIdentitySource = z.infer<typeof sessionIdentitySourceSchema>;
 /** A single named budget from the `budgets` array (issue #14). */
 type BudgetConfig = z.infer<typeof budgetSchema>;
 /** The `budgets` section of the config. */
@@ -513,6 +553,12 @@ interface CompiledLimits {
     readonly key?: 'tool' | 'agent' | 'session' | 'sender_id';
     readonly maxSpend?: CompiledSpendLimit;
 }
+/** Compiled tool revalidation settings with durations as milliseconds. */
+interface CompiledToolRevalidation {
+    readonly enabled: boolean;
+    readonly intervalMs: number;
+    readonly maxAdvertisedTtlMs: number;
+}
 /** Policy action types. */
 type PolicyAction = 'allow' | 'deny' | 'require_approval' | 'rate_limit' | 'spend_limit' | 'dry_run';
 /** A fully compiled policy rule ready for engine evaluation. */
@@ -576,6 +622,8 @@ interface CompiledPolicy {
      * at the use site — conservative by default.
      */
     readonly onToolDrift?: 'block' | 'require_approval' | 'log';
+    /** Always set by compilePolicies; absent only in hand-built fixtures (treated as disabled). */
+    readonly toolRevalidation?: CompiledToolRevalidation;
     readonly rules: readonly CompiledPolicyRule[];
     /** Install-time policy (issue #13 — deny_install). Undefined ⇒ observational. */
     readonly install?: CompiledInstallPolicy;
@@ -679,15 +727,63 @@ interface JsonRpcRequest {
     method: string;
     params?: unknown;
 }
+/** Resolved governance session identity (issue #218). */
+interface ResolvedSession {
+    readonly id: string;
+    /** Strategy that produced it — recorded in the audit trail. */
+    readonly source: 'header' | 'meta' | 'legacy_header' | 'transport';
+}
 /** A parsed MCP request enriched with session context. */
 interface McpRequest extends JsonRpcRequest {
-    /** MCP session ID extracted from the `Mcp-Session-Id` header. */
-    sessionId?: string;
+    /** Proxy-resolved governance session identity (undefined when no strategy matched). */
+    session?: ResolvedSession;
+    /** Verbatim Mcp-Session-Id from the wire. Transport relay ONLY — never governance. */
+    transportSessionId?: string;
+    /**
+     * The client's verbatim MCP-Protocol-Version wire claim (issue #219) —
+     * captured raw, with no normalization, for the audit trail. It is the
+     * CLIENT'S claim, not the upstream era. Since issue #226 the
+     * streamable-http route validates header/body agreement before
+     * forwarding, so on a FORWARDED request a claim of `2026-07-28` has
+     * passed the agreement door; tier-2 claims (legacy, unknown, malformed)
+     * and notification claims remain unvalidated as captured. Streamable
+     * HTTP only: the header postdates the deprecated SSE transport, and
+     * stdio has no headers, so both leave it unset.
+     */
+    protocolVersion?: 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;
 }
+/**
+ * An inbound request rejected by the header/body agreement door (issue
+ * #226), as protocol facts: what the body said, what the headers claimed,
+ * and why they disagree. Deliberately camelCase and transport-free (no Hono
+ * types, no audit field names) — the audit-record mapping lives solely in
+ * `buildHeaderMismatchAuditRecord` on the audit side.
+ */
+interface HeaderMismatchRejection {
+    /** Human-readable mismatch reason; echoed values are display-capped. */
+    readonly reason: string;
+    /** The body's JSON-RPC method. */
+    readonly method: string;
+    /** The body's params, verbatim as parsed. */
+    readonly params?: unknown;
+    /**
+     * The body's name-bearing string field (`params.name` / `params.uri`),
+     * when the method defines one and the body carries a string value.
+     */
+    readonly bodyName?: string;
+    /** The client's verbatim MCP-Protocol-Version wire claim, if any. */
+    readonly protocolVersion?: string;
+    /** The inbound marker headers that were present, verbatim as received. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Proxy-resolved governance session identity, when a strategy matched. */
+    readonly session?: ResolvedSession;
+    /** Time from route-handler entry to rejection, in milliseconds. */
+    readonly durationMs: number;
+}
 /** The response returned by an MCP forwarder. */
 interface McpResponse {
     status: number;
@@ -724,6 +820,13 @@ interface ServerHandle {
 interface CreateAppOptions {
     /** Slack interactive action handler (mounted at /slack/actions). */
     slackActionApp?: Hono;
+    /**
+     * Recorder for inbound header/body agreement rejections (issue #226) on
+     * the streamable-http route. Enforcement does not depend on it — with no
+     * recorder the request is still rejected and no record is written (the
+     * library-embedding posture `missing_tool_name` also takes).
+     */
+    onHeaderMismatch?: (rejection: HeaderMismatchRejection) => void;
 }
 /**
  * Create a Hono app configured with the MCP proxy routes.
@@ -748,6 +851,12 @@ declare function startServer(app: Hono, config: HelioConfig): ServerHandle;
  */
 declare function startSidebandServer(app: Hono, port: number, host?: string): ServerHandle;
+/**
+ * `upstream.protocol_version`: `auto` probes and caches; a dated pin is a
+ * constant — never probed, never cached, never cleared.
+ */
+type UpstreamProtocolVersionPin = 'auto' | '2025-06-18' | '2026-07-28';
 interface StreamableHttpForwarderOptions {
     /** The upstream MCP server URL (e.g. "http://localhost:8080/mcp"). */
     url: string;
@@ -755,6 +864,8 @@ interface StreamableHttpForwarderOptions {
     headers?: Record<string, string>;
     /** Maximum time to wait for an upstream request before aborting. */
     requestTimeoutMs?: number;
+    /** `upstream.protocol_version`: `auto` (default) probes; a dated pin skips it. */
+    protocolVersion?: UpstreamProtocolVersionPin;
 }
 /**
  * Spec-compliant upstream MCP Streamable HTTP client.
@@ -775,11 +886,35 @@ declare class StreamableHttpForwarder implements McpForwarder {
     /** Lifecycle parity with sse/stdio. */
     close(): Promise<void>;
     forward(request: McpRequest): Promise<ForwardResult>;
+    /**
+     * The dual-era bridge (relay leg, modern era): a modern-only server
+     * answers the retired `initialize` handshake with 404/-32601, so Helio
+     * synthesizes the legacy InitializeResult locally from the upstream's own
+     * probe-time DiscoverResult. No `mcp-session-id` response header — the
+     * legacy spec permits sessionless servers, and the downstream stays
+     * sessionless. The synthesized protocolVersion is always the current
+     * legacy revision, even for a client that offered an older one.
+     */
+    private synthesizeInitializeResult;
+    /**
+     * The modern upstream removed `notifications/initialized`; answer the
+     * same minimal success envelope the SSE-notification path returns.
+     */
+    private swallowInitializedNotification;
+    /**
+     * The relay-side era falsification door (issue #219): a legacy-leg relay whose answer only a
+     * modern server gives clears the cached legacy era (the manager no-ops on
+     * pins, uncached eras, and cached modern). The response still flows to the
+     * client unchanged — no in-place retry.
+     */
+    private inspectLegacyRelayOutcome;
     /**
      * Helio-internal execution path (startup prime / internal maintenance) that
      * may borrow the proxy-managed internal session.
      */
     forwardInternal(request: McpRequest): Promise<ForwardResult>;
+    /** Drop the managed internal session AND the cached era; next internal call re-probes. */
+    resetInternalSession(): void;
     private send;
 }
@@ -939,8 +1074,14 @@ interface AuditRecord {
     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. */
+    /** Resolved governance session id, or the adapter-supplied id on sideband records. */
     readonly session_id: string | null;
+    /**
+     * Which identity strategy produced session_id (issue #218): `header`,
+     * `meta`, `legacy_header`, or `transport` on the MCP door, `sideband` for
+     * adapter-supplied ids. Null when no session resolved.
+     */
+    readonly session_source: 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. */
@@ -1007,6 +1148,14 @@ interface AuditRecord {
      * `match.metadata.*` (#13) and the dashboard metadata columns (#16).
      */
     readonly metadata: Record<string, unknown> | null;
+    /**
+     * The client's verbatim MCP-Protocol-Version wire claim on the inbound
+     * request (issue #219) — the CLIENT'S claim, not the upstream era, and not
+     * a validated fact. Recorded uncapped: truncation would manufacture a
+     * false claim in an audit record. Null when the request carried no header
+     * and on records with no MCP wire (drift events, sideband records).
+     */
+    readonly protocol_version: string | null;
     /** ISO 8601 timestamp of when the record was persisted. */
     readonly created_at: string;
 }
@@ -2032,11 +2181,28 @@ declare class SpendLimiter {
     close(): void;
 }
+declare const GATED_SESSION: unique symbol;
+/** A session bucket value that provably passed the identity gate. */
+type GatedSession = string & {
+    readonly [GATED_SESSION]: true;
+};
+declare const GATED_CHARGES: unique symbol;
+/** Budget charges that provably passed the session engagement check. */
+type GatedCharges = readonly BudgetCharge[] & {
+    readonly [GATED_CHARGES]: true;
+};
 /** Everything the engine needs about one tool call to resolve its charges. */
 interface BudgetChargeContext {
     readonly toolName: string;
     readonly toolArguments: Record<string, unknown> | undefined;
-    readonly sessionId: string | null;
+    /**
+     * Gate-minted session bucket value (issue #218), or null when identity is
+     * unresolved — `bucketKey` builds `session:unknown` from null, which is
+     * legal ONLY because `gateBudgetCharges` denies unresolved session-keyed
+     * engagement before `peekAll`/`recordAll` can run.
+     */
+    readonly sessionId: GatedSession | null;
     /** Adapter-supplied sender id (sideband only); null on the MCP path. */
     readonly senderId: string | null;
 }
@@ -2220,8 +2386,12 @@ declare class BudgetEngine {
         charges: BudgetCharge[];
         failures: BudgetChargeFailure[];
     };
-    /** Check every charge without mutating. All-or-nothing: one deny flips `allowed`. */
-    peekAll(charges: readonly BudgetCharge[]): {
+    /**
+     * Check every charge without mutating. All-or-nothing: one deny flips
+     * `allowed`. Accepts only gate-branded charges (issue #218) — a caller
+     * cannot peek budget state without having run the session engagement check.
+     */
+    peekAll(charges: GatedCharges): {
         allowed: boolean;
         entries: BudgetPeekEntry[];
     };
@@ -2232,7 +2402,7 @@ declare class BudgetEngine {
      * Recording is unconditional past the sink (an approved overage
      * legitimately pushes a bucket past its limit).
      */
-    recordAll(charges: readonly BudgetCharge[], meta: BudgetCommitMeta): BudgetPeekEntry[];
+    recordAll(charges: GatedCharges, meta: BudgetCommitMeta): BudgetPeekEntry[];
     /**
      * Fire one `onBreach` event per breached entry. Called by the doors at the
      * moment a peek outcome actually denies the call or raises the composite
@@ -2329,6 +2499,18 @@ declare class BudgetEngine {
     private snapshot;
 }
+/** Compiled session config, wired into the route factories at startup. */
+interface CompiledSessionIdentity {
+    /** The configured identity chain, in order; first match wins. */
+    readonly sources: readonly SessionIdentitySource[];
+    readonly onUnresolved: 'deny' | 'anonymous';
+    /**
+     * Human-readable strategy list (e.g. `header "x-helio-session-id",
+     * legacy_header`) — deny messages name the strategies that were tried.
+     */
+    readonly strategySummary: string;
+}
 /** Options for constructing a GovernedForwarder. */
 interface GovernedForwarderOptions {
     /** The current environment label (e.g. "production", "staging"). */
@@ -2345,6 +2527,12 @@ interface GovernedForwarderOptions {
     spendLimiter?: SpendLimiter;
     /** Budget engine for named cross-tool budgets (issue #14). */
     budgetEngine?: BudgetEngine;
+    /**
+     * Compiled session identity config (issue #218): the `on_unresolved` mode
+     * and the strategy summary deny messages name. Defaults to the schema
+     * default chain (deny mode) for direct/library construction.
+     */
+    session?: CompiledSessionIdentity;
 }
 /** Result of attempting to prime the tool annotation cache. */
 interface AnnotationCachePrimeResult {
@@ -2367,6 +2555,7 @@ declare class GovernedForwarder implements McpForwarder {
     private readonly inner;
     private policy;
     private readonly environment;
+    private readonly session;
     private readonly auditWriter;
     private readonly evidenceStore;
     private readonly approvalRouter;
@@ -2406,6 +2595,20 @@ declare class GovernedForwarder implements McpForwarder {
      */
     primeAnnotationCache(): Promise<AnnotationCachePrimeResult>;
     forward(request: McpRequest): Promise<ForwardResult>;
+    /**
+     * Clamp an over-long `result.ttlMs` on a `tools/list` response to
+     * `policies.tool_revalidation.max_advertised_ttl` (issue #221, D7).
+     *
+     * Downward-only: a `ttlMs` at or below the cap is left untouched, and a
+     * response with no `ttlMs` never gains one — Helio does not manufacture a
+     * cache hint the upstream never advertised. Non-numeric values are left
+     * alone rather than coerced. `cacheScope` passes through untouched: Helio
+     * baselines and vouches for tool *definitions* only, and its own
+     * `tools/list` view is not caller-varying, so it has no basis to alter a
+     * scope hint the upstream set. No-op when tool revalidation is disabled
+     * (including hand-built `CompiledPolicy` fixtures that omit the field).
+     */
+    private clampCacheHints;
     /**
      * Apply a tools/list response to the definition cache and surface any
      * drift: console warning + immediate audit record per event. Single entry
@@ -2469,14 +2672,20 @@ declare class GovernedForwarder implements McpForwarder {
      * or consuming any resources. Returns an MCP-compliant synthetic response.
      */
     private handleDryRun;
-    /** Construct a limit bucket key based on the configured key type. */
+    /**
+     * Construct a non-session limit bucket key. 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'`.
+     */
     private buildLimitKey;
     /**
-     * Construct a spend bucket key via the shared {@link spendBucketKey}
-     * composer — see its doc for why spend buckets are rule-discriminated.
-     * Rate buckets keep the undiscriminated keys.
+     * Gate a session-keyed limit at its key-build site (issue #218). Returns
+     * the bucket key, or null when identity is unresolved under deny mode —
+     * the caller denies (enforce) or reports the marker (dry-run).
      */
-    private buildSpendLimitKey;
+    private gateSessionLimitKey;
+    private makeSessionUnresolvedResult;
     private writeAuditRecord;
     private makeDriftBlockResult;
     private makeDenyResult;
@@ -2611,6 +2820,13 @@ interface GovernanceServiceOptions {
     readonly spendLimiter?: SpendLimiter;
     /** Budget engine for named cross-tool budgets (issue #14). */
     readonly budgetEngine?: BudgetEngine;
+    /**
+     * Compiled session identity config (issue #218): the sideband door gets
+     * the SAME on_unresolved policy as the MCP door — an adapter omitting
+     * session_id while a session-keyed control is engaged is denied under
+     * `deny`, pools under `anonymous`. Defaults to the schema default chain.
+     */
+    readonly session?: CompiledSessionIdentity;
     readonly auditWriter?: AuditWriter;
     /** Default approval timeout (ms) when a rule sets none. */
     readonly approvalTimeoutMs?: number;
@@ -2630,6 +2846,7 @@ interface GovernanceServiceOptions {
 declare class GovernanceService {
     private policy;
     private readonly environment;
+    private readonly session;
     private readonly evidenceStore;
     private readonly approvalRouter;
     private readonly rateLimiter;
@@ -2789,6 +3006,22 @@ declare class GovernanceConfigError extends Error {
     constructor(message: string);
 }
+/**
+ * Map a header/body agreement rejection (issue #226) onto the audit record
+ * shape, mirroring the `missing_tool_name` precedent: `policy_decision:
+ * 'rejected'`, no rule evaluated, nothing forwarded, written by the caller
+ * via `pushImmediate`. The snake_case mapping lives here alone — the
+ * rejection payload itself stays camelCase protocol facts (`mcp/types.ts`).
+ *
+ * `record_kind` stays `'tool_call'` for the whole class, non-tool methods
+ * included: it is the MCP-door request bucket, and `block_reason` is the
+ * query key. `tool_name` carries the body's name-bearing field (the body
+ * truth an investigator filters for) when the method has one, else the
+ * 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'>;
 /** @internal Exported for testing only. */
 declare class QueueChannel implements ApprovalChannel {
     readonly type = "dashboard";
@@ -2915,6 +3148,10 @@ interface ActionEvent {
     readonly block_reason: string | null;
     readonly approval_status: string | null;
     readonly session_id: string | null;
+    /** Identity strategy that produced session_id (issue #218), or null. */
+    readonly session_source: string | null;
+    /** The client's verbatim MCP-Protocol-Version wire claim (issue #219), or null. */
+    readonly protocol_version: string | null;
     readonly agent_id: string | null;
     readonly environment: string | null;
     readonly timestamp: string;
@@ -3061,4 +3298,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 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, 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 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 };