@securecoms/agent-bridge 0.35.0 → 0.37.0

package/dist/bridge-agent.d.ts

@@ -44,10 +44,12 @@ import { VOICE_CALL_START_MARKER } from "./voice/prompt-compiler.js";
 import { type CallBufferTurn } from "./voice/call-buffer.js";
 import { type VaultListNode, type VaultReadExpectations } from "./vault.js";
 import type { AgentActionNodeType, AgentActionNodeStatus, AgentActionNodeDetail } from "@agentvault/connect-core";
-import { removeManagedLlmSource, writeManagedFiles, writeManifestPolicy } from "./service/runtime-config-dir.js";
+import { removeManagedLlmSource, writeManagedFiles, writeManifestPolicy, writeMcpPolicy } from "./service/runtime-config-dir.js";
 import { type ReplyCredit } from "./reply-credit.js";
 import { bindRuntimeConfig, type FeatureSet } from "./grants/binding.js";
 import type { RuntimeReplyReceipt } from "./reply-receipts.js";
+import { type McpCatalog } from "./grants/mcp-catalog.js";
+import { type McpCatalogLister } from "./mcp-catalog-message.js";
 import type { SearchProvider } from "./grants/search-providers.js";
 export type AgentAudience = "owner_dm" | "team_room" | "partner_room" | "other_human_dm" | "agent_to_agent" | "unknown";
 export type BridgeToolGrant = 
@@ -169,6 +171,13 @@ export interface BridgeAuthorization {
      * for a harness socket and the HTTP/SSE paths (review m-3).
      */
     readonly memory_write?: true;
+    /**
+     * MCP client Task 16 (OQ-2 ruling, audit M-4): true ONLY on an owner-DM turn whose verified owner check read the DM's
+     * leaves as exactly the pinned owner and the agent (relayLeaf === false), and only while at least one `mcp:` grant is
+     * in tool_grants (renarrowManifestGrants and withMcpCapability drop it with the last one). The runtime offers an
+     * `mcp:` tool only with it. NOT a tool grant.
+     */
+    readonly relay_free?: true;
 }
 /**
  * Spec §8.2: what ws-server tells applyMemoryNote about the socket a
@@ -357,9 +366,10 @@ export declare const ROOM_VOICE_GUIDANCE_WITH_RESPONDER = "You are in a group vo
  * `voiceDefaultResponder` (never a body-supplied claim).
  */
 export declare function selectVoiceGuidance(isDm: boolean | undefined, voiceDefaultResponder: boolean | undefined): string;
-/** Owner grants plan 4 Task 11: TEST SEAM for the refetch's writers and binder (call order, throws). Production omits it. */
 export interface GrantWriters {
     writeManifestPolicy?: typeof writeManifestPolicy;
+    /** MCP Task 16. */
+    writeMcpPolicy?: typeof writeMcpPolicy;
     writeManagedFiles?: typeof writeManagedFiles;
     bindRuntimeConfig?: typeof bindRuntimeConfig;
     removeManagedLlmSource?: typeof removeManagedLlmSource;
@@ -372,6 +382,15 @@ export interface BridgeAgentDeps {
      * UNIFIED_MEMORY_PART1 decides (switch.arch.test.ts pins both).
      */
     unifiedMemoryPart1?: boolean;
+    /**
+     * MCP client Task 16: TEST SEAM ONLY. The catalog the manifest verifier and mcp-policy.json use. Production (bin.ts)
+     * never passes it, so the compiled MCP_CATALOG (Phase 1: {linear}, Task 22) decides what MCP is grantable.
+     */
+    mcpCatalog?: McpCatalog;
+    /** PR-B2 audit M-2: TEST SEAM ONLY. The H-D delivered-turn record's bound (default MCP_DELIVERED_TRACK_MAX). */
+    mcpDeliveredTrackMax?: number;
+    /** PR-B2 follow-up test seam: the backoff of the mcp-policy.json write retry (the last value repeats). */
+    mcpPolicyRetryDelaysMs?: readonly number[];
     /**
      * Unified memory: TEST SEAM. Production builds the real worker from dist/memory-worker.js (Task 27 pins that bin.ts
      * never passes it).
@@ -757,12 +776,9 @@ export declare class SendForbiddenError extends Error {
     readonly channelId: string;
     constructor(channelId: string);
 }
-/**
- * Audit M-B1 (controller ruling 2026-10-05): a reply to a room-granted turn
- * would be sealed at an epoch the room was not classified at, and the room is
- * not internal there. Dropped. A SendForbiddenError, so both transports treat
- * it as terminal (send_forbidden: the runtime acks, nothing redelivers).
- */
+export declare class McpReplyWithheldError extends SendForbiddenError {
+    constructor(channelId: string);
+}
 export declare class RoomClassChangedSendError extends SendForbiddenError {
     constructor(channelId: string);
 }
@@ -1206,6 +1222,57 @@ export declare class BridgeAgent {
     private readonly roomDefaultGrants;
     /** Owner grants (spec §7.4): the two manifest switches, read once at construction. */
     private readonly ownerDmManifestGrants;
+    /**
+     * MCP client Task 16 (OQ-16, coordinator ruling D-7): SECURECOMS_MCP_GRANTS, read ONCE at construction. "off" writes
+     * kill_switch (deleting); any value other than unset/"on"/"off" is suspended (non-deleting, one content-free warn).
+     */
+    private readonly mcpHostSwitch;
+    /** MCP Task 16 test seam (BridgeAgentDeps.mcpCatalog); undefined in production, so MCP_CATALOG decides. */
+    private readonly mcpCatalog;
+    /**
+     * MCP Task 16 (OQ-1; PR-B1 audit M-2): the two raw /files fields from the LAST fetch. Any failed or rejected fetch
+     * sets `fetched: false` (no_config, non-deleting): the last values are never kept to keep an `ok` document alive.
+     */
+    private mcpConfig;
+    /**
+     * MCP Task 16: the mcp-policy.json document this process last WROTE (the file the runtime reads), or null before the
+     * first write and after a failed one (fail closed: issuance reads only a document known to be on disk).
+     */
+    private mcpPolicyWritten;
+    private mcpPolicyWrittenJson;
+    /** Deletion-ack ruling §3: the manifest counter in force when `mcpPolicyWrittenJson` was written (never read live). */
+    private mcpPolicyWrittenCounter;
+    /** Ruling §3: newest counter whose written policy the runtime fully acted on. Memory only, monotonic, starts at 0. */
+    private mcpDeletionsThrough;
+    /** Ruling §3: the last `credentials_present` an accepted frame carried; null until one arrives. */
+    private mcpCredentialsPresentValue;
+    /** Ruling §3: per attached socket, whether its latest hello declared mcp_deletion_ack_v1 (harness noted false). */
+    private readonly mcpDeletionAckSockets;
+    /** Ruling §3 rate: the ack-derived report values in the last report posted (null until one is). */
+    private lastReportedMcpAck;
+    /** #1351 round 2 M-1: bumped on every byte-changing policy write (and on the inert document being put in force). */
+    private policyWriteSeq;
+    /** M-1: per ack-capable socket, the policyWriteSeq at the dispatch of each owner-DM turn, by message id (bounded). */
+    private readonly mcpTurnSeq;
+    /**
+     * #1351 round 2 H-1: the ack values the REPORT may carry. An ack lands seconds after an owner-DM turn and a report
+     * posted then would time the turn (record_report sets applied_at). So, as the tool-status sender: `open` holds a
+     * change while its 15-minute UTC bucket is open, `closed` what the report carries, and the only post is from one
+     * timer at the next bucket boundary plus jitter.
+     */
+    private mcpAckOpen;
+    private mcpAckClosed;
+    private mcpAckTimer;
+    /** PR-B2 follow-up: a failed write is retried on this backoff (the last value repeats) until one lands or close(). */
+    private readonly mcpPolicyRetryDelaysMs;
+    private mcpPolicyRetryTimer;
+    private mcpPolicyRetryAttempt;
+    /** MCP Task 18: the loopback catalog listers of the attached runtime sockets that declared mcp_client_v1 (ws-server.ts). */
+    private readonly mcpCatalogListers;
+    /** MCP Task 18 (OQ-15): per server 1 in flight, 3 / 60 s, 20 / hour; per agent 40 / hour. Memory only. */
+    private readonly mcpCatalogRate;
+    /** MCP Task 18: answers in progress (outside the ingest cycle). Observable by tests; close() does not wait on them. */
+    private readonly mcpCatalogWork;
     private readonly roomManifestGrants;
     /**
      * Audit M-B4: DM channels whose roster was epoch-fresh at THIS ingest
@@ -1214,6 +1281,32 @@ export declare class BridgeAgent {
     private readonly ownerDmCycleFresh;
     private toolGrantManifest;
     private toolGrantCounter;
+    /**
+     * Tool status Phase 0 (spec §3.1, §3.2; plan Task 8): the latest owner-DM last-turn record, in memory only (no store
+     * table: after a restart there is none until the next typed owner-DM turn). ADVISORY: nothing reads it to decide a
+     * grant. Content-free: enums, booleans, one 15-minute bucket `at` (ruling M-2), one counter, built-in names from the
+     * allowlist. This is the latest record, open bucket included; what leaves the host is the sender's closed record.
+     */
+    private ownerDmLastTurn;
+    /**
+     * Test seams (Task 8; ruling M-2): the cause function, the bridge clock the record and the sender read, and the
+     * sender's timer and jitter source.
+     */
+    private toolStatusCause;
+    private toolStatusNow;
+    private toolStatusSetTimer;
+    private toolStatusClearTimer;
+    private toolStatusRandom;
+    /**
+     * Phase 0 Task 9 (spec §3.5), ruling M-2: the post of the record to the narrow route, only just after a 15-minute
+     * UTC bucket boundary, and only a record whose bucket has closed.
+     */
+    private readonly toolStatusSender;
+    /**
+     * MCP Phase 1 Task 14 (OQ-3 ruling item 3): the sticky R-3 flag, mirrored from the sealed store. Starts false and is
+     * set true at start() by the store (or by a failed read, fail closed). Only applyToolGrantManifest changes it after.
+     */
+    private mcpSeen;
     private manifestState;
     /** Failed owner-turn checks since the last successful runtime-config report (§7.7). */
     private ownerVerifyFailures;
@@ -1579,6 +1672,26 @@ export declare class BridgeAgent {
      */
     refetchRuntimeConfig(): Promise<void>;
     private refetchRuntimeConfigOnce;
+    /** MCP Task 16 (OQ-1): the bridge's in-force entitlement reading; not fetched (or failed) is suspended. */
+    private mcpEntitlementInForce;
+    /** PR-B1 audit M-2: forget the last /files fields and rewrite mcp-policy.json (no_config: no grants, no deletion). */
+    private noteMcpConfigUnfetched;
+    /** MCP Task 16: the live inputs of mcp-policy.json (the pinned manifest in force only). */
+    private mcpPolicyInput;
+    /**
+     * MCP Task 16 (spec §12.1): recompute mcp-policy.json and write it when it changed. The written document is what MCP
+     * issuance and release-time re-narrowing read, so it is cleared BEFORE the write and set only after it lands: a failed
+     * write leaves no document in force here (no MCP grant), and the next trigger tries again. Never throws.
+     */
+    private recomputeMcpPolicy;
+    /** A document is in force: no pending retry, and the next failure starts the backoff from the first delay. */
+    private clearMcpPolicyRetry;
+    /**
+     * PR-B2 follow-up: one pending retry at a time. The retry recomputes from the state THEN (never re-writes a stale
+     * document); any other trigger that writes successfully meanwhile cancels it. Nothing is in force on the bridge side
+     * until a write lands (mcpPolicyWritten stays null).
+     */
+    private scheduleMcpPolicyRetry;
     /**
      * Plan 4 Task 11: the refetch under a manifest in force. Returns false when the binding failed (H-4),
      * after the memory was applied; the caller then writes nothing else. Throws only from a file write, with
@@ -2043,6 +2156,41 @@ export declare class BridgeAgent {
      * there so a retry can resend the exact bytes).
      */
     private publishBody;
+    /**
+     * MCP Task 16 (round 2 H-D): message ids whose DELIVERED authorization (after release-time re-narrowing) carried an
+     * `mcp:` grant, with their channel and whether the runtime acked them. Recorded at the buffer exit, the one place
+     * every consumer's copy leaves from (over-recording a turn a non-capable consumer then received without the grant only
+     * adds a check). Kept after the ack, so a late frame citing the turn is still checked. Bounded: the oldest ACKED entry
+     * goes first.
+     */
+    private readonly mcpDeliveredTurns;
+    private readonly mcpDeliveredTrackMax;
+    /**
+     * Record `m` when its authorization carries an `mcp:` grant. Returns false ONLY when `m` is a new turn, the record is
+     * at its bound and no entry is acked: the caller (the buffer exit) must then issue no mcp: grant (audit M-2, fail
+     * closed). `rebuild` (PR-B2 audit C-1 (b): a restored runtime-inbox row, or a replayed turn) records unconditionally:
+     * those grants were issued before, so the record may exceed its bound by at most the runtime inbox's size.
+     */
+    private noteMcpDelivered;
+    /**
+     * H-D: whether a frame to `channelId` must pass the relay-free check: it answers a recorded MCP turn (any channel:
+     * a frame of that turn sent elsewhere is checked against ITS channel), or it cites no turn while an MCP turn is
+     * unacked in the same channel.
+     */
+    private mcpReplyGuarded;
+    /**
+     * H-D, synchronous: read the channel's local leaves from the warm manager in one step and tie the read to the
+     * envelope's SEALED group and epoch, so the leaf set is exactly the membership that can open these bytes. Owner and
+     * agent only: pass. Anyone else: withhold. The tree moved past the seal on the first attempt: StaleEpochError, which
+     * sendWithSelfHeal answers with its one converge-and-re-seal (the existing semantics); still unprovable on the retry,
+     * or no warm manager, no pin, or any throw: withhold (fail closed). Read-only; never touches the group.
+     *
+     * Scope (PR-B2 audit item 5): this guards the `send` path (publishBody) only. `status` detail, the `action_*` run
+     * frames, `/v1/send-attachment` and summary frames are NOT checked; they are safe for MCP turns only because the
+     * runtime emits none of them (pinned by connect-agent-runtime/src/outbound-frames.arch.test.ts). A runtime that starts
+     * emitting any of them needs this guard extended to that frame first.
+     */
+    private assertMcpReplyRelayFree;
     /**
      * Audit M-B1 (controller ruling): a reply to a room-granted turn is sealed
      * only at the epoch the room was classified at. On a move, the room is
@@ -3057,6 +3205,13 @@ export declare class BridgeAgent {
      * never changes a grant in step 1. A save that throws keeps the old state.
      */
     private applyToolGrantManifest;
+    /**
+     * MCP Task 14: the R-3 hold Task 17 filters on and Task 15 writes as `r3_hold`. True while the manifest in force signs
+     * an owner_dm `mcp:` string, or while the sticky flag is set (an old client's re-sign cannot lift it, audit C-1).
+     */
+    r3Hold(): boolean;
+    /** Persist then mirror. Setting mirrors even on a failed write; clearing mirrors only after the write (fail closed). */
+    private setMcpSeen;
     private logManifest;
     /** Classify one inbound turn at the agent's CURRENT epoch for its channel. */
     private authorizeTurn;
@@ -3101,6 +3256,20 @@ export declare class BridgeAgent {
      *   once, outside server control, is an open design follow-up.
      */
     private authorizationFor;
+    /**
+     * Tool status Phase 0 (spec §3.2, §3.5; plan Task 8; round 1 H-2, M-4; round 2 H-4): build the candidate record and
+     * keep the previous one (and its `at`) when the change tuple is the same, so `at` means "last changed". Never throws
+     * into the authorization path. Never logs a channel id, sender id or tool name.
+     */
+    private noteOwnerDmTurn;
+    /** R2-M1: the served manifest names another owner than the pin; the held record belongs to the old owner. */
+    private dropOwnerDmLastTurn;
+    /**
+     * Phase 0 Task 9 (spec §3.5): POST the record, body = the record only, to the narrow agent-key route. The backend
+     * resolves the identity from the device credential; no identity, channel or sender id is in the URL or the body.
+     * Returns the status class only; never throws.
+     */
+    private postToolStatus;
     /**
      * One content-free INFO line per authorization decision (every call site of
      * authorizationFor stages exactly one runtime turn). It says WHY a turn got
@@ -3175,6 +3344,28 @@ export declare class BridgeAgent {
      * client's own wait already renders "Summary unavailable" — so there is
      * nothing to catch here besides the send itself.
      */
+    /**
+     * MCP client Task 18 (spec §8 item 2; audit M-3, H-3; OQ-2, OQ-15). Accept an `mcp_catalog_request` only when: its
+     * body is exactly the §8 shape; it is a direct frame (never a voice channel's) in a channel the server marks as a DM
+     * that IS the signed owner DM; verifyOwnerTurn says `verified` (the pinned owner's signature, the signed DM, the leaf
+     * check, not a replay) with `relayLeaf === false`; mcp-policy.json as written is `ok` with this server `ok`; a runtime
+     * socket that declared mcp_client_v1 is attached; and the rate limits admit it. The replay row is written HERE
+     * (M-3: the request never reaches stageRuntimeInbox, where it is otherwise written), for every verified request, before
+     * anything is answered; the ownerReplayPending entry is removed in `finally`. A failure to record answers nothing.
+     * Never throws. The answer runs outside the ingest cycle, so the row is acked now.
+     */
+    private acceptMcpCatalogRequest;
+    /** The signed server's vendor and the bridge catalog row's issuer, when mcp-policy.json as WRITTEN is `ok` with it `ok`. */
+    private mcpCatalogTarget;
+    /** Ask the runtime, re-check, build (384 KB cap) and send. Never throws. */
+    private answerMcpCatalogRequest;
+    /**
+     * The `mcp_catalog` reply: a system_event envelope with a body-level type (the sendSummary shape), on the shared
+     * self-heal seam and the one publish chokepoint. H-D applies to EVERY attempt (it carries vendor-supplied tool
+     * descriptions): after the seal, before the POST, the leaves at the SEALED group and epoch must be exactly the owner
+     * and the agent, or the frame is withheld. One message id across the retry.
+     */
+    private sendMcpCatalog;
     private handleSummarize;
     /**
      * A thin adapter over the daemon's one-shot completion seam. Voice-enabled
@@ -3307,6 +3498,23 @@ export declare class BridgeAgent {
      * audience that is still signed, else dropped. Only narrows; an unchanged message is returned by reference.
      */
     private renarrowManifestGrants;
+    /**
+     * MCP Task 16 (audit H-2; round 2 LOW), after the base re-narrowing: a buffered `mcp:` grant survives release only
+     * when, NOW, the turn is still a plain owner-DM turn in the signed DM channel, the host switch reads "on", the
+     * entitlement reading is in force, the name is not in skills.disabled, the mcp-policy.json document last written
+     * lists the server ok with the tool, and a FRESH synchronous read of the DM's local leaves holds exactly the pinned
+     * owner and the agent (MlsGroupKeyProvider.leafSnapshotCached: one `state` object, no await; null fails closed). Any
+     * other mcp: grant is dropped, never kept as a fallback. relay_free is dropped whenever no mcp: grant survives.
+     * Read-only: never touches the MLS group. Only narrows; returns `m` by reference when nothing changes.
+     */
+    private renarrowMcpGrants;
+    /**
+     * MCP Task 16 (OQ-2; audit H-2, round 2 H-D): a FRESH read of the channel's local leaf set holds exactly the pinned
+     * owner and this agent. Synchronous (one manager `state`, so the leaves belong to one epoch); a cold manager or any
+     * throw reads as NOT relay-free.
+     */
+    private ownerDmRelayFreeNow;
+    private renarrowManifestGrantsBase;
     private takeBufferedRaw;
     /**
      * Phase 3 F2: per-channel ordered delivery for the /v1/ws runtime consumer.
@@ -3555,6 +3763,74 @@ export declare class BridgeAgent {
     private lastReportedUtilityTools;
     noteSearchProvidersSocket(token: object, declared: boolean): void;
     clearSearchProvidersSocket(token: object): void;
+    /** MCP Task 16 (spec §15): the same AND-over-sockets state for mcp_client_v1, kept per socket. */
+    private readonly mcpClientSockets;
+    noteMcpClientSocket(token: object, declared: boolean): void;
+    clearMcpClientSocket(token: object): void;
+    /** Deletion-ack ruling §3: ws-server notes every runtime hello's mcp_deletion_ack_v1 declaration (harness: false). */
+    noteMcpDeletionAckSocket(token: object, declared: boolean): void;
+    /** #1351 round 2 observation: with no ack-capable socket left (detached, or re-hello'd without the feature), the last
+     *  credentials value is no longer known: forget it, so a later socket does not inherit a stale value. */
+    private forgetCredentialsIfNoAckSocket;
+    clearMcpDeletionAckSocket(token: object): void;
+    /** #1351 round 2 M-1: ws-server calls this when it sends an owner-DM turn to an ack-capable socket. Bounded. */
+    noteMcpTurnDispatch(token: object, messageId: string): void;
+    /** Ruling §3 / §5.3: the AND over attached sockets, false with none attached (as mcpClientCapable). */
+    private mcpDeletionAckCapable;
+    /**
+     * Deletion-ack ruling (2026-10-31) §3 acceptance. ws-server has validated the frame shape and the socket (declared
+     * mcp_deletion_ack_v1 and mcp_client_v1, no harness). `credentials_present` is taken as is. `applied_sha256` advances
+     * `mcpDeletionsThrough` only when it is the SHA-256 of the bytes THIS bridge last wrote (JSON + newline) and still
+     * holds in force, and that document's top state is one whose deletion set covers the signed removal; then to the
+     * counter recorded at that write, never the live one. Anything else is ignored silently. Never throws.
+     */
+    noteMcpDeletionAck(token: object, frame: {
+        credentials_present: boolean;
+        message_id?: string;
+        applied_sha256?: string;
+    }): void;
+    /** H-1: a change of the ack values goes into the open bucket; the report sees it only once the bucket has closed. */
+    private noteMcpAckChanged;
+    private promoteMcpAck;
+    /** H-1: one timer, at the first bucket boundary strictly after now plus a jitter in [0, 60 s), as the tool-status sender. */
+    private scheduleMcpAckReport;
+    /**
+     * Ruling §5.3: the three keys. The two ack values come from the CLOSED bucket only (H-1), so no report, whatever
+     * posts it, reveals an owner-DM turn before its 15-minute bucket has closed. `mcp_r3_hold` is not DM timing: live.
+     */
+    private reportedMcpAck;
+    private mcpAckSignature;
+    /**
+     * A SOCKET change (attach, detach, a hello) can change which keys the report carries; their values are the closed
+     * ones, so this is not owner-DM timing and may use the capability refetch. An ACK never comes here (H-1): it goes
+     * through noteMcpAckChanged and the bucket timer.
+     */
+    private maybeReportMcpAck;
+    /** MCP Task 18: ws-server registers (or, with null, removes) a socket's loopback catalog lister. */
+    noteMcpCatalogLister(token: object, lister: McpCatalogLister | null): void;
+    /**
+     * MCP Task 19 (spec §12.3): "ok" when every attached runtime socket declared mcp_client_v1 (the AND, which harness
+     * sockets hold false: a harness socket counts in the AND and never declares it); else "harness_consumer" when the
+     * latest hello was a harness; else "missing".
+     */
+    private reportedMcpCapability;
+    /**
+     * MCP Task 19 (spec §12.3): at most 8 `{server_id, vendor, state}` for the signed servers of the manifest in force,
+     * from mcp-policy.json as WRITTEN. Only the states the bridge itself knows: top `kill_switch` and `not_entitled` give
+     * that state per server; top `ok` gives `ok` for a server the bridge lists `ok` and `malformed` for one it refused.
+     * Every other top state (no capability, suspended, no config, switch off, section absent, malformed section) gives no
+     * row. The runtime-only states (needs_login, login_expired, definition_changed, server_version_unsupported,
+     * server_unreachable) have no runtime-to-bridge report path in Phase 1. `vendor` is reported only when it is a key of
+     * the bridge's compiled catalog; a signed vendor outside it gives no row. Never a tool name, URL or issuer.
+     */
+    private reportedMcpServers;
+    /**
+     * MCP Task 16: every attached runtime socket declared mcp_client_v1; no socket attached means absent (false).
+     * PR-B2 follow-up (documented): a HARNESS socket counts in this AND. ws-server notes every socket that said hello,
+     * and a harness hello is always noted `false` (harnessClaimed never resets), so one attached harness connector holds
+     * the capability false for files, the report and mcp-policy.json (top `no_capability`) while it is attached.
+     */
+    mcpClientCapable(): boolean;
     noteUtilityToolsSocket(token: object, declared: boolean): void;
     clearUtilityToolsSocket(token: object): void;
     /** U6: every attached runtime socket declared utility_tools_v1; no socket attached means absent (false). */
@@ -3576,6 +3852,8 @@ export declare class BridgeAgent {
      * switches and the new capability, then a debounced refetch (one per burst) only when needed.
      */
     private onCapabilityMaybeChanged;
+    /** Debounced, with a max wait: a burst that never pauses still refetches at most maxWait after its first change. */
+    private scheduleCapabilityRefetch;
     /**
      * A refetch re-renders skills.json (owner_dm_search_cap counts web_extract only with the capability, D39) and posts
      * the report. Needed under a manifest in force, or when the reported value is stale. Never before the boot fetch.

package/dist/consumer-grants.d.ts

@@ -28,6 +28,8 @@ export declare const MANIFEST_GRANTS_FEATURE = "manifest_grants_v1";
 export declare const SEARCH_PROVIDERS_FEATURE = "search_providers_v2";
 /** Weather/currency spec §8.1 (U6): the /v1/ws hello feature of a runtime that knows weather_forecast and currency_convert. Pinned to the runtime's by capability-parity.test.ts. */
 export declare const UTILITY_TOOLS_FEATURE = "utility_tools_v1";
+/** MCP client spec §15 (plan Task 16): the /v1/ws hello feature of a runtime that runs the read-only MCP client. Never a TOOL_FEATURE value. Pinned to the runtime's by capability-parity.test.ts. */
+export declare const MCP_CLIENT_FEATURE = "mcp_client_v1";
 export declare const CONSTANT_TOOL_NAMES: Readonly<Record<"owner_dm" | "team_room", readonly string[]>>;
 /**
  * Spec §7.9: a consumer that did not declare manifest_grants_v1 (runtime 0.12.2, a harness,
@@ -64,3 +66,29 @@ export declare function withSearchCapability(m: BridgeMessage, consumerHasFeatur
  * policy file and TOOL_FEATURE. Returns `m` by reference when nothing drops; never mutates `m`.
  */
 export declare function withUtilityCapability(m: BridgeMessage, consumerHasFeature: boolean): BridgeMessage;
+/** The exact prefix of an owner-signed MCP grant name (`mcp:<server_id>/<tool>`). */
+export declare const MCP_GRANT_PREFIX = "mcp:";
+/**
+ * Spec §15 per-delivery MCP filter, on every delivery path after withUtilityCapability, judged by the consumer's OWN
+ * hello. An `mcp:` grant survives only for a consumer that declared mcp_client_v1, on a turn whose audience is
+ * `owner_dm` and that carries no relay_speaker mark (any value: the mark disqualifies, T-10). Otherwise every `mcp:`
+ * grant is dropped, marked or unmarked (a harness, an older runtime and every HTTP path never receive one, T-14).
+ * Every other grant and field is unchanged. Only narrows; returns `m` by reference when nothing drops; never mutates.
+ */
+export declare function withMcpCapability(m: BridgeMessage, consumerHasFeature: boolean): BridgeMessage;
+/**
+ * R-3 "holds" keep set, the bridge copy (spec §10, audit M-1): an ALLOW-list, so a future built-in is withdrawn by
+ * default while the hold is on. Pinned equal to the runtime's (Task 12b) by consumer-grants.mcp.test.ts, and over
+ * MANIFEST_KNOWN_TOOLS.owner_dm it withdraws exactly fetch_url, web_extract, http_request and sql_query.
+ */
+export declare const R3_KEEP_TOOLS: ReadonlySet<string>;
+/**
+ * Spec §10 R-3 "holds" filter, on every delivery path to every consumer. `hold` is the agent's R-3 hold
+ * (BridgeAgent.r3Hold(): the in-force manifest's signedMcpPresent, computed on the raw verified owner_dm array, or the
+ * sticky mcp_seen flag). It is message-independent on purpose: it never reads this message's grants (which
+ * withMcpCapability, entitlement, kill switches or skills.disabled may already have emptied), so no narrowing step can
+ * lift it (audit C-2, OQ-13). While it holds, every owner-DM turn (audience owner_dm, or the owner-relayed voice turn
+ * marked relay_speaker "owner") keeps only R3_KEEP_TOOLS and `mcp:` grants. Other audiences are unchanged. Only
+ * narrows; returns `m` by reference when nothing drops; never mutates.
+ */
+export declare function withR3Holds(m: BridgeMessage, hold: boolean): BridgeMessage;

package/dist/grants/binding.d.ts

@@ -69,7 +69,8 @@ export declare function legacyAssignToken(d: {
  * unknown name in manifest-policy.json as an unreadable file and drops EVERY manifest grant, so a tool listed here is
  * written to the policy file (and delivered) only when every attached runtime socket declared its feature.
  */
-export type Feature = "search_providers_v2" | "utility_tools_v1";
+/** MCP Task 16: "mcp_client_v1" is a Feature (capabilityFeatures) but never a TOOL_FEATURE value (pinned by capability-parity.test.ts). */
+export type Feature = "search_providers_v2" | "utility_tools_v1" | "mcp_client_v1";
 export type FeatureSet = ReadonlySet<Feature>;
 /** No socket attached, or none declared anything: fail closed. */
 export declare const NO_FEATURES: FeatureSet;

package/dist/grants/effective.d.ts

@@ -39,9 +39,17 @@ export interface EffectiveInput {
     };
     readonly roomSearchCapped: boolean;
 }
+/** Phase 0 Task 6 (spec §3.2, round 2 M-12): why a signed tool was dropped owner-side, pushed at the line that drops it. */
+export type WithheldWhy = "disabled_by_owner" | "no_endpoint" | "no_database";
+export interface WithheldTool {
+    readonly tool: string;
+    readonly why: WithheldWhy;
+}
 export interface EffectiveGrant {
     readonly grants: readonly ReadGrant[];
     readonly source: GrantSource;
     readonly withheldBySearchCap: boolean;
+    /** Signed tools the manifest branch dropped, in ceiling order, frozen. [] on every other branch. The team-room search cap is not an owner-side reason (it keeps withheldBySearchCap). */
+    readonly withheld: readonly WithheldTool[];
 }
 export declare function effectiveToolGrants(i: EffectiveInput): EffectiveGrant;

package/dist/grants/manifest.d.ts

@@ -8,6 +8,8 @@
  */
 import { type SearchProvider } from "./search-providers.js";
 import { type OwnerGrantPin } from "./pin.js";
+import { type SignedMcp } from "./mcp-section.js";
+import { type McpCatalog } from "./mcp-catalog.js";
 export declare const TOOL_GRANTS_DOMAIN = "SECURECOMS-TOOL-GRANTS-V1:";
 export declare const MANIFEST_STATES: readonly ["ok", "unchanged", "no_pin", "no_manifest", "malformed", "unsupported_algo", "bad_signature", "wrong_agent", "wrong_owner", "rollback", "unknown_entry", "kept_last_good"];
 export type ManifestState = (typeof MANIFEST_STATES)[number];
@@ -33,6 +35,17 @@ export interface ToolGrantManifest {
     readonly databases: Readonly<Record<string, SignedDatabase>>;
     /** Plan 4 Task 7 (spec §8.1, §7.10): the signed values the config binding compares. Required. */
     readonly config: SignedConfig;
+    /**
+     * MCP Phase 1 Task 14 (spec §12.2, §13a). `mcp` is the parsed signed section, or null when the key is absent or the
+     * section is malformed (`mcpKey` tells them apart, OQ-3 ruling). A malformed section never makes the manifest malformed.
+     */
+    readonly mcp: SignedMcp | null;
+    readonly mcpKey: "absent" | "present";
+    /**
+     * R-3 raw predicate (audit C-2): some string in the signature-verified `grants.owner_dm` starts with `mcp:`, read after
+     * step 5 and BEFORE step 6, parseMcp, the ceiling and the catalog, so none of them can lift R-3.
+     */
+    readonly signedMcpPresent: boolean;
 }
 export interface SignedEndpoint {
     readonly baseUrl: string;
@@ -75,4 +88,5 @@ export declare function verifyToolGrantManifest(raw: unknown, ctx: {
     pin: OwnerGrantPin;
     agentIdentityId: string;
     storedCounter: number | null;
+    mcpCatalog?: McpCatalog;
 }): ManifestVerdict;

package/dist/grants/mcp-catalog.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The bridge's copy of the compiled MCP catalog (spec §11, §12.2 "the vendor and tool are in the bridge's catalog copy").
+ * Phase 1 holds exactly one row, Linear (Task 22; Eric 2026-10-30, "ship Linear only"), identical to the runtime's
+ * (`connect-agent-runtime/src/mcp/catalog.ts`) value for value. No vendor value is ever written from memory; each cites
+ * its source below. `mcp-catalog.parity.test.ts` and `mcp-lists.parity.test.ts` pin this copy to the runtime's byte for
+ * byte, so the two cannot drift. How a row is added, changed or withdrawn: docs/runbooks/mcp-catalog-update.md.
+ */
+/** The runtime's `CatalogRow`, field for field (OQ-6 ruling: the #1308 §11 fields exactly). */
+export interface McpCatalogRow {
+    displayName?: string;
+    host: string;
+    readOnlyUrl: string;
+    readTools: readonly string[];
+    scopes: readonly string[];
+    redirectPort?: 47823;
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    revocationEndpoint?: string;
+    docs: Readonly<Record<string, string>>;
+}
+export type McpCatalog = Readonly<Record<string, McpCatalogRow>>;
+export declare const MCP_CATALOG: McpCatalog;

package/dist/grants/mcp-issuance.d.ts

@@ -0,0 +1,34 @@
+/**
+ * MCP client Phase 1, Task 16 (spec §12.2 "issued"; OQ-1, OQ-2 rulings; audit H-3, M-4): which `mcp:` grants an
+ * owner-DM turn is issued. Pure; the bridge calls it right after effectiveToolGrants, on the owner-DM branch only.
+ *
+ *   issued = { mcp:s/t in manifest.grants.owner_dm (step 6 already applied the code ceiling and the catalog) }
+ *            only when ALL of:
+ *              effectiveToolGrants returned source "manifest" (so the turn was manifest-eligible: never a fallback);
+ *              the owner verdict is `verified` with relayLeaf === false (OQ-2: exactly owner and agent leaves);
+ *              the bridge's in-force entitlement reading is "entitled" (OQ-1);
+ *              SECURECOMS_MCP_GRANTS reads "on" (D-7: off and suspended issue nothing);
+ *              SECURECOMS_OWNER_DM_MANIFEST_GRANTS is on;
+ *              the mcp-policy.json document the bridge last WROTE is top `ok` and lists the server `ok` with the tool;
+ *            minus every name in skills.disabled.
+ *
+ * Fail closed throughout: an absent relayLeaf, an absent policy, a missing server or tool all issue nothing.
+ */
+import type { GrantSource, ReadGrant } from "./effective.js";
+import type { ToolGrantManifest } from "./manifest.js";
+import type { McpEntitlementReading, McpHostSwitch } from "./mcp-policy.js";
+import type { OwnerTurnVerdict } from "./owner-turn.js";
+import type { McpPolicyDoc } from "../service/runtime-config-dir.js";
+export interface McpIssuanceInput {
+    readonly source: GrantSource;
+    readonly verdict: OwnerTurnVerdict | undefined;
+    readonly entitlement: McpEntitlementReading;
+    readonly hostSwitch: McpHostSwitch;
+    readonly ownerDmManifestSwitchOn: boolean;
+    readonly disabled: ReadonlySet<string>;
+    readonly manifest: ToolGrantManifest | null;
+    readonly policy: McpPolicyDoc | null;
+}
+/** True when the written policy lists `serverId` as `ok` with `tool` among its tools. */
+export declare function mcpPolicyAllows(policy: McpPolicyDoc | null, serverId: string, tool: string): boolean;
+export declare function mcpIssuance(i: McpIssuanceInput): readonly ReadGrant[];

package/dist/grants/mcp-policy.d.ts

@@ -0,0 +1,82 @@
+/**
+ * MCP client Phase 1, Task 15 (spec §6.5, §12.1; OQ-1 and OQ-3 rulings; round 2 H-B): the `mcp-policy.json` document.
+ *
+ * Pure, except mcpGrantsHostSwitch's one start-time warn. The bridge writes the result with writeMcpPolicy BEFORE it
+ * issues any MCP grant (Task 16 wires it). The runtime deletes a token only on `ok` for a server named in `remove`
+ * (and not listed), `not_entitled` or `kill_switch` (deletion.ts; a host typo is therefore `suspended`, never
+ * `kill_switch`). The rules that matter most here:
+ *   - C-NEW-1 (2026-10-30): `remove` is copied ONLY from the signed `mcp.removed` of the manifest in force, and only into
+ *     the `ok` document; every other document writes `remove: []`. Absence from `servers` never deletes, so a stale
+ *     view re-signed by the owner cannot launder a deletion. No record of an earlier section is kept;
+ *   - a server the bridge refuses for its own reasons stays LISTED as `refused`;
+ *   - a verified manifest with NO `mcp` key is `section_absent`, never top `ok` with empty servers (OQ-3). An explicit
+ *     signed `"mcp": {"servers": {}}` is top `ok` with empty servers and deletes nothing; `{"servers": {}, "removed": "*"}`
+ *     is remove-all.
+ *
+ * `r3_hold` (= signedMcpPresent || mcp_seen) is in EVERY document, empty-servers ones included (round 2 H-B).
+ *
+ * Precedence, first match wins (the spec fixes no order; this one puts the host's own switch first, then what the bridge
+ * cannot know, then the backend's entitlement, then local switches, then the manifest, then the consumer):
+ *   kill_switch | host suspended (D-7), no_config, not_entitled | suspended, switch_off, no_manifest, section_absent,
+ *   malformed, no_capability, ok
+ */
+import type { ToolGrantManifest } from "./manifest.js";
+import { type McpCatalog } from "./mcp-catalog.js";
+import type { McpPolicyDoc } from "../service/runtime-config-dir.js";
+import { type ServiceLog } from "../service-log.js";
+/**
+ * Architect skew ruling (2026-10-30): this bridge declares, in EVERY hello reply (ws-server.ts), that it is the sole
+ * writer of mcp-policy.json: it refuses backend delivery of that name (runtime-config-dir.ts isLocalOnlyName). The
+ * runtime deletes tokens and offers MCP tools from the file only on a turn from a declaring socket (connect-agent-runtime
+ * data-plane.ts MCP_POLICY_WRITER_FEATURE). Unconditional: a statement about this build, not about the runtime or the
+ * switches (the host kill switch travels IN the file and must keep deleting). Never declare it from a build where the
+ * backend can write that name (ws-server.test.ts same-build row).
+ */
+export declare const MCP_POLICY_WRITER_FEATURE = "mcp_policy_writer_v1";
+/**
+ * Deletion-ack ruling (2026-10-31) §3: declared in the hello reply and by the runtime in its hello. Only a socket that
+ * declared it (and mcp_client_v1, no harness) may send `mcp_deletion_ack`.
+ */
+export declare const MCP_DELETION_ACK_FEATURE = "mcp_deletion_ack_v1";
+/** Ruling §3: the top states whose deletion set covers the manifest's signed `removed` (ok), or everything on disk. */
+export declare const MCP_ACK_STATES: ReadonlySet<string>;
+export type McpEntitlementReading = "entitled" | "not_entitled" | "suspended";
+/**
+ * OQ-1 ruling (ADR G). Only `true`/"entitled" is in force and only `false`/"not_entitled" is the deleting downgrade.
+ * Anything else (missing, unknown, disagreeing, non-boolean) is `suspended`: no grants, no deletion.
+ */
+export declare function mcpEntitlementReading(mcpEntitled: unknown, mcpCause: unknown): McpEntitlementReading;
+/**
+ * Host kill switch SECURECOMS_MCP_GRANTS (OQ-16; coordinator ruling D-7). Tri-state, so a typo can never delete:
+ *   unset or exactly "on" -> "on"; exactly "off" -> "off" (writes `kill_switch`, a deleting state);
+ *   any other value -> "suspended" (writes top `suspended`: no grants, no deletion).
+ */
+export type McpHostSwitch = "on" | "off" | "suspended";
+/**
+ * Read once at bridge start by the caller. A suspended value logs ONE content-free warn per call carrying the enum,
+ * never the raw value (it may be anything an operator typed).
+ */
+export declare function mcpGrantsHostSwitch(env: Readonly<Record<string, string | undefined>>, log?: ServiceLog): McpHostSwitch;
+export interface McpPolicyInput {
+    /** mcpGrantsHostSwitch(), read once at bridge start. "off" writes `kill_switch`; "suspended" writes `suspended`. */
+    readonly hostSwitch: McpHostSwitch;
+    /** The last /runtime-config/files result: not yet fetched (or failed), or the two raw fields from a successful fetch. */
+    readonly config: {
+        readonly fetched: false;
+    } | {
+        readonly fetched: true;
+        readonly mcp_entitled: unknown;
+        readonly mcp_cause: unknown;
+    };
+    /** SECURECOMS_OWNER_DM_MANIFEST_GRANTS on. */
+    readonly ownerDmManifestSwitchOn: boolean;
+    /** The verified manifest in force, or null. */
+    readonly manifest: ToolGrantManifest | null;
+    /** `mcp_client_v1` on every attached runtime socket of the identity (absent with none). */
+    readonly capability: boolean;
+    /** The sticky flag from the sealed store (Task 14). */
+    readonly mcpSeen: boolean;
+    /** Test seam; the compiled bridge catalog by default. */
+    readonly catalog?: McpCatalog;
+}
+export declare function mcpPolicyFor(i: McpPolicyInput): McpPolicyDoc;