@securecoms/agent-bridge 0.35.0 → 0.36.0

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

@@ -0,0 +1,79 @@
+/**
+ * MCP client Phase 1, Task 18 (spec §8 items 1, 2, 5, 6): the owner's `mcp_catalog_request` and the bridge's
+ * `mcp_catalog` reply, as pure functions. The bridge, never the runtime and never the model, builds and sends the reply.
+ *
+ *   request  {v: 1, type: "mcp_catalog_request", server_id, request_id}          exact keys; request_id = 32 lowercase hex
+ *   reply    {v: 1, type: "mcp_catalog", server_id, request_id, vendor, issuer, listed_at, tools, truncated}
+ *
+ * The runtime answers the loopback `mcp_catalog_list` (connect-agent-runtime data-plane.ts, mcp/catalog-list.ts) with
+ * `{ok: true, server_id, vendor, listed_at, tools: [{name, projection?, grantable, reason}], truncated}` or
+ * `{ok: false, server_id, state}`. validateCatalogListReply keeps only those fields, re-checked: anything else the runtime
+ * sends (an issuer, a token, a path) never reaches the message. The issuer is the bridge's own catalog row (display only;
+ * the web signs from its own row, spec §8 item 6).
+ *
+ * Size (spec §8 item 5, plan P-4): the UTF-8 JSON of the whole body is at most MCP_CATALOG_MAX_BYTES. A tool that does
+ * not fit becomes `{name, grantable: false, reason: "too_large"}` and the body says `truncated: true`. The measured wire
+ * expansion of the bridge send path is pinned by bridge-agent.mcp-catalog.test.ts (P-4).
+ */
+/** 384 KiB (spec §8 item 5). P-4 measured the real send path: see bridge-agent.mcp-catalog.test.ts. */
+export declare const MCP_CATALOG_MAX_BYTES: number;
+/** The runtime's listing cap (spec §9: 64 tools per server). A reply with more is malformed. */
+export declare const MCP_CATALOG_MAX_TOOLS = 64;
+/** The bridge's wait for the runtime's loopback answer. The runtime's own worst case is under 40 s; the web waits 60 s. */
+export declare const MCP_CATALOG_LIST_TIMEOUT_MS = 50000;
+/** A loopback catalog lister (ws-server.ts): resolves the runtime's result frame, or null (timeout, closed, too many pending). */
+export type McpCatalogLister = (serverId: string, timeoutMs: number) => Promise<unknown>;
+/** The runtime's content-free admission reasons (connect-agent-runtime mcp/admission.ts AdmissionReason). */
+export declare const MCP_CATALOG_REASONS: ReadonlySet<string>;
+type Bag = Record<string, unknown>;
+export interface McpCatalogRequest {
+    readonly serverId: string;
+    readonly requestId: string;
+}
+/** The parsed body of an `mcp_catalog_request`, or null for anything that is not exactly that shape. */
+export declare function parseMcpCatalogRequest(body: unknown): McpCatalogRequest | null;
+export type McpCatalogTool = {
+    name: string;
+    projection: Bag;
+    grantable: true;
+    reason: null;
+} | {
+    name: string;
+    grantable: false;
+    reason: string;
+};
+export interface McpCatalogListed {
+    readonly listedAt: string;
+    readonly truncated: boolean;
+    readonly tools: readonly McpCatalogTool[];
+}
+/**
+ * The runtime's `mcp_catalog_list_result` for `serverId` (whose policy vendor is `vendor`), re-checked; null when it is a
+ * failure (`ok: false`) or anything malformed. Never throws.
+ */
+export declare function validateCatalogListReply(frame: unknown, serverId: string, vendor: string): McpCatalogListed | null;
+export interface McpCatalogBody {
+    v: 1;
+    type: "mcp_catalog";
+    server_id: string;
+    request_id: string;
+    vendor: string;
+    issuer: string;
+    listed_at: string;
+    tools: McpCatalogTool[];
+    truncated: boolean;
+}
+export declare const mcpCatalogBodyBytes: (b: McpCatalogBody) => number;
+/**
+ * The `mcp_catalog` body, cut to MCP_CATALOG_MAX_BYTES: every tool starts as its too_large stub; then, in order, a tool's
+ * full entry replaces its stub when the body still fits. Replacing one array element changes the size by exactly the
+ * difference of the two entries' JSON, so the running total is exact. Order and names are kept; nothing is dropped.
+ */
+export declare function buildMcpCatalogBody(i: {
+    serverId: string;
+    requestId: string;
+    vendor: string;
+    issuer: string;
+    reply: McpCatalogListed;
+}): McpCatalogBody;
+export {};

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

@@ -0,0 +1,35 @@
+/**
+ * MCP client Phase 1, Task 18 (spec §8 item 2, OQ-15 ruling): the rate limits on `mcp_catalog_request`.
+ *
+ *   per server: at most 1 listing in flight (a request meanwhile is ignored), 3 per rolling 60 s, 20 per rolling hour;
+ *   per agent:  at most 40 per rolling hour.
+ *
+ * A request counts when it is ADMITTED (the bridge then asks the runtime, which spends vendor quota), whatever the runtime
+ * answers. Over-limit and in-flight requests are ignored, never queued, and do not count. One `catalog_rate_limited`
+ * observation per window per scope (`onRateLimited`, content-free scope names). In bridge memory only: the counters
+ * reset on restart (the limit protects vendor quota and the owner's other devices; it is not a security boundary).
+ */
+export type McpCatalogRateVerdict = "ok" | "in_flight" | "rate_limited";
+export type McpCatalogRateScope = "server_minute" | "server_hour" | "agent_hour";
+export declare const MCP_CATALOG_PER_SERVER_MINUTE = 3;
+export declare const MCP_CATALOG_PER_SERVER_HOUR = 20;
+export declare const MCP_CATALOG_PER_AGENT_HOUR = 40;
+export interface McpCatalogRateDeps {
+    now?: () => number;
+    /** Called once per window per scope when a request is refused for the rate. */
+    onRateLimited?: (scope: McpCatalogRateScope) => void;
+}
+export declare class McpCatalogRateLimiter {
+    private readonly now;
+    private readonly onRateLimited;
+    private readonly inFlight;
+    private readonly perServer;
+    private agent;
+    /** Per scope key: no further log until this time (the end of the window that was full when it last logged). */
+    private readonly quietUntil;
+    constructor(deps?: McpCatalogRateDeps);
+    /** "ok" admits (and counts) the request and marks the server in flight; the caller MUST call release(serverId). */
+    admit(serverId: string): McpCatalogRateVerdict;
+    release(serverId: string): void;
+    private limited;
+}

package/dist/reply-intent.d.ts

@@ -45,7 +45,7 @@ export declare function decodeReplyBody(bytes: Uint8Array): ReplyBody;
  * byte-identical to the four-argument form, so every existing row and every uncredited reply verifies unchanged; a
  * flipped or nulled reply_credit column, or a credited row read by an older bridge, fails verification.
  */
-export declare function replyBodyMac(key: Uint8Array, replyId: string, channelId: string, body: Uint8Array, credit?: ReplyCredit): string;
+export declare function replyBodyMac(key: Uint8Array, replyId: string, channelId: string, body: Uint8Array, credit?: ReplyCredit, mcpTurn?: boolean): string;
 /** The ordinal of an unkeyed reply part (`p:<n>`), or null for a keyed part. */
 export declare function partOrdinal(part: string): number | null;
 /**

package/dist/service/runtime-config-dir.d.ts

@@ -13,6 +13,19 @@ export interface FsDeps {
     unlink: (p: string) => void;
 }
 export declare function runtimeConfigDir(home: string, identityId: string): string;
+/**
+ * The files the header says the backend never sends: the LLM key files
+ * (legacy `llm.key` / `llm.key.host` and the per-provider
+ * `llm.key.<slug>` / `llm.key.<slug>.host`, see connect-agent-runtime
+ * llm-source.ts) and the runtime's `local-config.json`. A backend that could
+ * write one of these could replace a customer's key, or plant its own key and
+ * host binding so decrypted prompts go to the attacker's provider account.
+ * The comparison ignores case (macOS volumes are case-insensitive by default)
+ * and trailing dots and spaces (Windows drops them), so neither "LLM.KEY" nor
+ * "llm.key." lands on the real file.
+ */
+/** Exported for the same-build invariant test (ws-server.test.ts): MCP_POLICY_WRITER_FEATURE requires mcp-policy.json here. */
+export declare function isLocalOnlyName(name: string): boolean;
 /** Owner grants (spec §7.8): the runtime honours a manifest-marked grant only for a tool listed here. */
 export declare const MANIFEST_POLICY_FILE = "manifest-policy.json";
 export interface ManifestPolicyDoc {
@@ -28,6 +41,48 @@ export interface ManifestPolicyDoc {
 export declare function removeManagedLlmSource(home: string, identityId: string, deps?: FsDeps): void;
 /** The bridge's own writer for manifest-policy.json (writeManagedFiles refuses the name). Atomic, 0600. Throws. */
 export declare function writeManifestPolicy(home: string, identityId: string, policy: ManifestPolicyDoc, deps?: FsDeps): void;
+/**
+ * MCP Phase 1 Task 15 (spec §12.1, §6.5): the bridge-written MCP policy. The runtime reader
+ * (`connect-agent-runtime/src/mcp/policy-file.ts`) accepts exactly these keys; `mcp-policy-reader.parity.test.ts`
+ * feeds every document the bridge can compute through it.
+ */
+export declare const MCP_POLICY_FILE = "mcp-policy.json";
+export declare const MCP_POLICY_TOP_STATES: readonly ["ok", "not_entitled", "kill_switch", "suspended", "no_config", "switch_off", "no_manifest", "malformed", "no_capability", "section_absent"];
+export type McpPolicyTopState = (typeof MCP_POLICY_TOP_STATES)[number];
+export type McpPolicyAuth = {
+    readonly mode: "oauth";
+    readonly issuer: string;
+    readonly client: "securecoms_cimd" | "customer";
+    readonly client_id: string;
+} | {
+    readonly mode: "key";
+};
+export type McpPolicyServer = {
+    readonly state: "refused";
+} | {
+    readonly state: "ok";
+    readonly vendor: string;
+    readonly url: string;
+    readonly auth: McpPolicyAuth;
+    readonly tools: Readonly<Record<string, {
+        readonly sha256: string;
+        readonly class: "read";
+    }>>;
+};
+export interface McpPolicyDoc {
+    readonly v: 1;
+    readonly state: McpPolicyTopState;
+    /** Round 2 H-B: in EVERY document, = signedMcpPresent || mcp_seen. */
+    readonly r3_hold: boolean;
+    readonly servers: Readonly<Record<string, McpPolicyServer>>;
+    /**
+     * C-NEW-1 (2026-10-30): in EVERY document. The `ok` document copies the signed `mcp.removed` (server ids, or `"*"`);
+     * every other document writes `[]`. The runtime deletes on `ok` only what this names; absence never deletes.
+     */
+    readonly remove: readonly string[] | "*";
+}
+/** The bridge's own writer for mcp-policy.json (writeManagedFiles refuses the name). Atomic, 0600, dirs 0700. Throws. */
+export declare function writeMcpPolicy(home: string, identityId: string, doc: McpPolicyDoc, deps?: FsDeps): void;
 export declare function writeManagedFiles(home: string, identityId: string, files: Record<string, string>, deps?: FsDeps): void;
 /** Every path skills.json names, checked on disk. Contents are never read. */
 export declare function checkConfiguredPaths(skillsJson: Record<string, unknown>, statFn?: (p: string) => {

package/dist/tool-status-sender.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Tool status, Phase 0 (spec §3.5; plan Task 9; round 1 H-3; round 2 M-2, M-8; architect ruling M-2): the post of the
+ * owner-DM last-turn record. The only code that moves the record off the host besides the apply-time report.
+ *
+ * Rules (ruling M-2: 15-minute UTC buckets, A1 §8):
+ * - two slots: `open` holds the latest noted record while its bucket (`at` + 15 min) has not closed; `closed` holds
+ *   the latest noted record whose bucket has closed. An attempt only ever posts `closed`, never `open`;
+ * - attempts happen only from the one timer, set for the first bucket boundary strictly after now (advanced by whole
+ *   buckets while before a 429's notBefore) plus a jitter in [0, 60 s) drawn fresh per timer from `random`;
+ * - compared with sameTuple against the LAST SUCCESSFULLY POSTED record (`at` is not in the tuple): unchanged posts
+ *   nothing, so a change and a revert inside one bucket post nothing;
+ * - the last-posted record advances only on a 2xx (round 1 H-3);
+ * - 429 sets notBefore to the attempt time plus its Retry-After (seconds, at least 60 s; missing or invalid means 60 s);
+ * - any other 4xx is terminal for that record: no retry until note() brings a different tuple (round 2 M-2);
+ * - 5xx, a timeout and a network error leave `closed` pending for the next boundary.
+ * carry() is what the apply-time report sends: the closed record, so a report inside a bucket never reveals that
+ * bucket's change early. Never throws to the caller. Advisory: the record authorizes nothing.
+ */
+import { type OwnerDmTurnRecord } from "./grants/tool-status.js";
+/** Ruling M-2: an attempt lands in [boundary, boundary + 60 s). */
+export declare const TOOL_STATUS_JITTER_MS = 60000;
+/** What one post attempt observed: an HTTP status (with the raw Retry-After header), a deadline, or a network error. */
+export type ToolStatusPostResult = {
+    readonly status: number;
+    readonly retryAfter?: string | null;
+} | "timeout" | "network";
+export type ToolStatusFailure = "http_error" | "timeout" | "network";
+export interface ToolStatusSenderOptions {
+    post: (rec: OwnerDmTurnRecord) => Promise<ToolStatusPostResult>;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    /** The jitter source, in [0, 1). Default Math.random. Depends on nothing in the record. */
+    random?: () => number;
+    /** Called once per failed attempt with its class only (never the URL, the body or a status text). */
+    onFailure?: (kind: ToolStatusFailure) => void;
+}
+/** The default timer: setTimeout, unref'd so a pending post never holds the process open. */
+export declare function defaultToolStatusSetTimer(fn: () => void, ms: number): unknown;
+export declare function defaultToolStatusClearTimer(h: unknown): void;
+export declare class ToolStatusSender {
+    private readonly postFn;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private readonly random;
+    private readonly onFailure;
+    /** The latest noted record while its bucket is still open. */
+    private open;
+    /** The latest noted record whose bucket has closed: the only record an attempt or carry() may send. */
+    private closed;
+    private lastPosted;
+    private terminalFor;
+    private notBefore;
+    private timer;
+    private inFlight;
+    private shut;
+    constructor(o: ToolStatusSenderOptions);
+    note(rec: OwnerDmTurnRecord): void;
+    /** Ruling M-2: what the apply-time report carries. The closed record only; an open bucket is never revealed early. */
+    carry(): OwnerDmTurnRecord | null;
+    /** R2-M1: the record belongs to an owner who is no longer the manifest's; forget it and what was posted. */
+    drop(): void;
+    close(): void;
+    private cancelTimer;
+    private promote;
+    private pending;
+    private schedule;
+    private fire;
+    private attempt;
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const BRIDGE_VERSION = "0.35.0";
+export declare const BRIDGE_VERSION = "0.36.0";

package/dist/ws-server.d.ts

@@ -51,7 +51,7 @@ export declare const MEMORY_UNIFIED_FEATURE = "memory_unified";
  * fake against this list at run time (7b gate fix: a member added here without
  * a fake made three tests throw "is not a function").
  */
-export declare const WS_AGENT_MEMBERS: readonly ["ackRuntimeMessages", "action", "admitRuntimeDelivery", "applyMemoryNote", "clearHarnessReport", "clearManifestConsumer", "clearPerToolConsumer", "clearSearchProvidersSocket", "clearUtilityToolsSocket", "harnessGrantsWithheld", "signedSearchProvider", "isRuntimeMessageRetired", "noteConsumerCapability", "noteManifestConsumer", "noteRoomCapReached", "noteSearchProvidersSocket", "noteUtilityToolsSocket", "noteNotesConsumer", "notePerToolConsumer", "noteRecallConsumer", "noteUnifiedConsumer", "noteSessionClose", "noteSessionEvicted", "noteSessionOpen", "notesAppliedGeneration", "notesForDelivery", "recallForDelivery", "unifiedFeatureOn", "unifiedForDelivery", "recordHarnessReport", "recordRuntimeReply", "reportStatusGated", "requeueFailedRuntimeDeliveries", "requeueFront", "runtimeReplyReceipt", "send", "sendA2A", "subscribe", "takeDeliverable", "wakeListeners"];
+export declare const WS_AGENT_MEMBERS: readonly ["ackRuntimeMessages", "action", "admitRuntimeDelivery", "applyMemoryNote", "clearHarnessReport", "clearManifestConsumer", "clearPerToolConsumer", "clearSearchProvidersSocket", "clearUtilityToolsSocket", "clearMcpClientSocket", "harnessGrantsWithheld", "signedSearchProvider", "r3Hold", "isRuntimeMessageRetired", "noteConsumerCapability", "noteManifestConsumer", "noteRoomCapReached", "noteSearchProvidersSocket", "noteUtilityToolsSocket", "noteMcpClientSocket", "noteMcpCatalogLister", "noteNotesConsumer", "notePerToolConsumer", "noteRecallConsumer", "noteUnifiedConsumer", "noteSessionClose", "noteSessionEvicted", "noteSessionOpen", "notesAppliedGeneration", "notesForDelivery", "recallForDelivery", "unifiedFeatureOn", "unifiedForDelivery", "recordHarnessReport", "recordRuntimeReply", "reportStatusGated", "requeueFailedRuntimeDeliveries", "requeueFront", "runtimeReplyReceipt", "send", "sendA2A", "subscribe", "takeDeliverable", "wakeListeners"];
 export type WsAgent = Pick<BridgeAgent, (typeof WS_AGENT_MEMBERS)[number]>;
 export declare function attachAgentWebSocket(server: HttpServer, agent: WsAgent, opts: AgentWebSocketOptions): {
     close(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@securecoms/agent-bridge",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -34,6 +34,7 @@
     "prepublishOnly": "bash scripts/pack-smoke.sh",
     "build": "tsc && node esbuild.config.mjs",
     "test": "vitest run",
+    "test:skew": "vitest run --config vitest.skew.config.ts",
     "test:watch": "vitest"
   },
   "dependencies": {