machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/local/browser-pairing-store.mjs

@@ -1,82 +1,119 @@
 import { randomBytes } from "node:crypto";
-import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { createExclusiveFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
-import { readBoundedRegularFileSync } from "./secure-file.mjs";
-import { assertStateMaintenanceAvailable, ensureOwnerOnlyDir, ownerOnlyFile } from "./state.mjs";
-import { EXPECTED_EXTENSION_VERSION } from "./browser-extension-protocol.mjs";
+import { inspectPathIfPresentSync, readBoundedRegularFileSync, retryTransientMultipleLinksSync } from "./secure-file.mjs";
+import { acquireMaintenanceLock, assertStateMaintenanceAvailable } from "./state.mjs";
+import { ensureOwnerOnlyDir, ownerOnlyFile } from "./secure-file.mjs";
+import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
 
 const DEFAULT_BROWSER_PORT = 39393;
 const PAIRING_FILE = "browser-bridge.json";
+const PAIRING_SCHEMA_VERSION = 2;
+const PAIRING_AUTH_VERSION = 2;
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{32,100}$/;
 
-export async function loadOrCreatePairing(stateRoot) {
-  if (!stateRoot) return { token: randomBytes(32).toString("base64url"), port: DEFAULT_BROWSER_PORT };
-  assertStateMaintenanceAvailable(stateRoot);
+export async function loadOrCreatePairing(stateRoot, options = {}) {
+  if (!stateRoot) return newPairing(DEFAULT_BROWSER_PORT);
   ensureOwnerOnlyDir(stateRoot);
   const file = join(stateRoot, PAIRING_FILE);
+  const inspect = options.inspectPathIfPresentSync || inspectPathIfPresentSync;
+  const existing = inspect(file, "browser pairing state");
+  if (existing) {
+    if (existing.isSymbolicLink() || !existing.isFile()) throw new Error("browser pairing state must be a regular file and not a symbolic link");
+    const current = readPublishedPairing(file);
+    if (!current.requiresMigration) { assertStateMaintenanceAvailable(stateRoot); return current.value; }
+    return migratePreviousPairing(stateRoot, file);
+  }
+  assertStateMaintenanceAvailable(stateRoot);
   for (let attempt = 0; attempt < 2; attempt += 1) {
-    if (existsSync(file)) {
-      ownerOnlyFile(file);
-      let parsed;
-      try { parsed = JSON.parse(readBoundedRegularFileSync(file, 64 * 1024).toString("utf8")); }
-      catch { throw new Error("browser pairing state is not valid bounded JSON"); }
-      if (!/^[A-Za-z0-9_-]{32,100}$/.test(parsed.token) || !Number.isInteger(parsed.port) || parsed.port < 1024 || parsed.port > 65535) {
-        throw new Error("browser pairing state is invalid");
-      }
-      return parsed;
-    }
-    const value = { token: randomBytes(32).toString("base64url"), port: DEFAULT_BROWSER_PORT };
+    const value = newPairing(DEFAULT_BROWSER_PORT);
     try {
-      createExclusiveFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+      createExclusiveFileSync(file, pairingJson(value), { mode: 0o600 });
       ownerOnlyFile(file);
       return value;
     } catch (error) {
       if (error?.code !== "EEXIST") throw error;
+      const created = readPublishedPairing(file);
+      if (!created.requiresMigration) return created.value;
     }
   }
-  throw new Error("browser pairing state could not be initialized");
+  return migratePreviousPairing(stateRoot, file);
 }
 
 export async function savePairing(stateRoot, value) {
   assertStateMaintenanceAvailable(stateRoot);
+  const normalized = normalizePairing(value);
   const file = join(stateRoot, PAIRING_FILE);
-  replaceFileAtomicallySync(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  replaceFileAtomicallySync(file, pairingJson(normalized), { mode: 0o600 });
   ownerOnlyFile(file);
 }
 
-export function pairingHtml(port, token) {
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="machine-bridge-browser-pair" content="1"><meta name="machine-bridge-browser-port" content="${port}"><meta name="machine-bridge-browser-token" content="${token}"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Machine Bridge browser pairing</title></head><body><h1>Machine Bridge browser pairing</h1><p>Expected extension build: <strong>${EXPECTED_EXTENSION_VERSION}</strong>. Reload the unpacked extension after every Machine Bridge upgrade.</p><p>The installed extension reads pairing material from this loopback-only page and stores it in browser-local extension storage. It is not sent to any website.</p><p id="status">Waiting for the Machine Bridge extension.</p></body></html>`;
+export function readBrowserPairing(stateRoot, options = {}) {
+  const current = readBrowserPairingEntry(stateRoot, options); if (!current) return null;
+  if (current.requiresMigration) throw new Error("browser pairing state requires migration before pairing"); return current.value;
+}
+export function readBrowserPairingPort(stateRoot, options = {}) { return readBrowserPairingEntry(stateRoot, options)?.value.port ?? null; }
+function readBrowserPairingEntry(stateRoot, options) {
+  const file = join(stateRoot, PAIRING_FILE); const inspect = options.inspectPathIfPresentSync || inspectPathIfPresentSync;
+  const existing = inspect(file, "browser pairing state");
+  if (!existing) return null; if (existing.isSymbolicLink() || !existing.isFile()) throw new Error("browser pairing state must be a regular file and not a symbolic link");
+  return readPublishedPairing(file);
 }
 
-export function isAllowedExtensionOrigin(origin) {
-  let parsed;
-  try { parsed = new URL(String(origin || "")); } catch { return false; }
-  return parsed.protocol === "chrome-extension:"
-    && /^[a-p]{32}$/.test(parsed.hostname)
-    && !parsed.username
-    && !parsed.password
-    && !parsed.port
-    && (parsed.pathname === "" || parsed.pathname === "/")
-    && !parsed.search
-    && !parsed.hash;
+async function migratePreviousPairing(stateRoot, file) {
+  const lock = await acquirePairingMigrationLock(stateRoot);
+  try {
+    const current = readPublishedPairing(file);
+    if (!current.requiresMigration) return current.value;
+    const value = { schemaVersion: PAIRING_SCHEMA_VERSION, pairingAuthVersion: PAIRING_AUTH_VERSION, extensionToken: token(), runtimeToken: current.value.runtimeToken || token(), port: current.value.port, migrationPending: true };
+    replaceFileAtomicallySync(file, pairingJson(value), { mode: 0o600 });
+    ownerOnlyFile(file);
+    return value;
+  } finally { lock.release(); }
 }
 
-export function isAllowedLoopbackHost(host, port) {
-  const normalized = String(host || "").toLowerCase();
-  return normalized === `127.0.0.1:${port}` || normalized === `localhost:${port}` || normalized === `[::1]:${port}`;
+async function acquirePairingMigrationLock(stateRoot) {
+  const deadline = createMonotonicDeadline(5_000);
+  do {
+    const lock = acquireMaintenanceLock(stateRoot, { operation: "browser-pairing-migration" });
+    if (lock.acquired) return lock;
+    await new Promise((resolvePromise) => { setTimeout(resolvePromise, Math.min(50, Math.max(1, deadline.remainingMs()))); });
+  } while (!deadline.expired());
+  throw new Error("browser pairing migration could not acquire the state maintenance lock");
 }
 
-export function securityHeaders(contentType) {
-  return {
-    "content-type": contentType,
-    "cache-control": "no-store",
-    "content-security-policy": "default-src 'none'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
-    "x-content-type-options": "nosniff",
-    "referrer-policy": "no-referrer",
-  };
+function readPublishedPairing(file) {
+  return retryTransientMultipleLinksSync(() => readPairing(file));
 }
 
-export function sendJson(response, value) {
-  response.writeHead(200, securityHeaders("application/json; charset=utf-8"));
-  response.end(`${JSON.stringify(value)}\n`);
+function readPairing(file) {
+  ownerOnlyFile(file);
+  let parsed;
+  try { parsed = JSON.parse(readBoundedRegularFileSync(file, 64 * 1024, "browser pairing state", { verifyPathIdentity: true, rejectMultipleLinks: true }).toString("utf8")); }
+  catch { throw new Error("browser pairing state is not valid bounded JSON"); }
+  if (parsed?.schemaVersion === PAIRING_SCHEMA_VERSION && parsed?.pairingAuthVersion === PAIRING_AUTH_VERSION) {
+    return { requiresMigration: false, value: normalizePairing(parsed) };
+  }
+  if (parsed?.schemaVersion === PAIRING_SCHEMA_VERSION && parsed?.pairingAuthVersion === undefined
+      && TOKEN_PATTERN.test(String(parsed?.extensionToken || ""))
+      && TOKEN_PATTERN.test(String(parsed?.runtimeToken || "")) && parsed.extensionToken !== parsed.runtimeToken && validPort(parsed?.port)) {
+    return { requiresMigration: true, value: { extensionToken: parsed.extensionToken, runtimeToken: parsed.runtimeToken, port: Number(parsed.port) } };
+  }
+  if (TOKEN_PATTERN.test(String(parsed?.token || "")) && validPort(parsed?.port)) {
+    return { requiresMigration: true, value: { extensionToken: parsed.token, runtimeToken: "", port: Number(parsed.port) } };
+  }
+  throw new Error("browser pairing state is invalid");
+}
+
+function normalizePairing(value) {
+  if (value?.schemaVersion !== PAIRING_SCHEMA_VERSION || value?.pairingAuthVersion !== PAIRING_AUTH_VERSION || !TOKEN_PATTERN.test(String(value.extensionToken || ""))
+      || !TOKEN_PATTERN.test(String(value.runtimeToken || "")) || value.extensionToken === value.runtimeToken || !validPort(value.port)
+      || typeof value.migrationPending !== "boolean") {
+    throw new Error("browser pairing state is invalid");
+  }
+  return { schemaVersion: PAIRING_SCHEMA_VERSION, pairingAuthVersion: PAIRING_AUTH_VERSION, extensionToken: String(value.extensionToken), runtimeToken: String(value.runtimeToken), port: Number(value.port), migrationPending: value.migrationPending };
 }
+function newPairing(port) { return { schemaVersion: PAIRING_SCHEMA_VERSION, pairingAuthVersion: PAIRING_AUTH_VERSION, extensionToken: token(), runtimeToken: token(), port, migrationPending: false }; }
+function token() { return randomBytes(32).toString("base64url"); }
+function validPort(value) { return Number.isInteger(Number(value)) && Number(value) >= 1024 && Number(value) <= 65535; }
+function pairingJson(value) { return `${JSON.stringify(value, null, 2)}\n`; }

package/src/local/browser-request-registry.mjs

@@ -1,67 +1,93 @@
 import { randomBytes } from "node:crypto";
 import { MAX_BROWSER_MESSAGE_BYTES } from "./browser-extension-protocol.mjs";
-
+import { browserRequestResponseError, browserRequestTransportError, invalidBrowserResponseSettlement } from "./browser-request-settlement.mjs";
 export class BrowserRequestRegistry {
   constructor({ maximum = 32 } = {}) {
     this.maximum = maximum;
     this.pending = new Map();
   }
-
   request({ transport, method, params, timeoutSeconds, callId = "" }) {
     if (this.pending.size >= this.maximum) throw new Error("too many concurrent browser requests");
+    if (typeof method !== "string" || !/^[a-z][a-z0-9_]{0,63}$/.test(method)) throw new Error("browser request method is invalid");
+    if (!Number.isSafeInteger(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > 185) throw new Error("browser request timeout is invalid");
     const id = `browser_${randomBytes(18).toString("base64url")}`;
     return new Promise((resolvePromise, rejectPromise) => {
       const timeoutMs = timeoutSeconds * 1000;
       const timeout = setTimeout(() => {
+        const pending = this.pending.get(id);
+        if (!pending) return;
         this.pending.delete(id);
-        sendCancelQuietly(transport, id);
-        rejectPromise(new Error(`browser request timed out after ${timeoutSeconds}s`));
+        const terminationRequested = sendCancelQuietly(transport, id);
+        rejectPromise(browserRequestTransportError({
+          pending,
+          code: "timeout",
+          fallback: `browser request timed out after ${timeoutSeconds}s`,
+          terminationRequested,
+        }));
       }, timeoutMs);
       timeout.unref?.();
-      this.pending.set(id, { resolve: resolvePromise, reject: rejectPromise, timeout, callId });
+      const pending = { resolve: resolvePromise, reject: rejectPromise, timeout, callId, method, dispatchAttempted: false };
+      this.pending.set(id, pending);
       try {
         const message = JSON.stringify({ type: "request", id, method, params, timeout_ms: timeoutMs });
         if (Buffer.byteLength(message) > MAX_BROWSER_MESSAGE_BYTES) throw new Error("browser request exceeds maximum message size");
+        pending.dispatchAttempted = true;
         transport.send(message);
       } catch (error) {
         clearTimeout(timeout);
         this.pending.delete(id);
-        rejectPromise(error);
+        rejectPromise(pending.dispatchAttempted
+          ? browserRequestTransportError({ pending, code: "unavailable", fallback: error })
+          : error);
       }
     });
   }
-
   settle(message) {
     if (message?.type !== "response" || typeof message.id !== "string") return false;
     const pending = this.pending.get(message.id);
     if (!pending) return false;
     clearTimeout(pending.timeout);
     this.pending.delete(message.id);
-    if (message.ok === false) pending.reject(new Error(String(message.error || "browser operation failed").slice(0, 2000)));
-    else pending.resolve(message.result);
+    if (message.ok === false) {
+      if (typeof message.error !== "string" || !message.error || message.error.includes("\0") || message.error.length > 2000) {
+        pending.reject(invalidBrowserResponseSettlement(pending));
+      } else {
+        pending.reject(browserRequestResponseError(message.error, pending));
+      }
+    } else if (message.ok === true && message.result && typeof message.result === "object" && !Array.isArray(message.result)) {
+      pending.resolve(message.result);
+    } else {
+      pending.reject(invalidBrowserResponseSettlement(pending));
+    }
     return true;
   }
 
-  cancelCall(callId, transport) {
+  cancelCall(callId, transport, reason = null) {
     if (!callId) return;
     for (const [id, pending] of this.pending) {
       if (pending.callId !== callId) continue;
       clearTimeout(pending.timeout);
       this.pending.delete(id);
-      sendCancelQuietly(transport, id);
-      pending.reject(new Error("browser request cancelled; a user-visible action may already have completed"));
+      const terminationRequested = sendCancelQuietly(transport, id);
+      const code = reason?.code === "timeout" ? "timeout" : "cancelled";
+      pending.reject(browserRequestTransportError({
+        pending,
+        code,
+        fallback: code === "timeout" ? "browser request timed out" : "browser request cancelled",
+        terminationRequested,
+      }));
     }
   }
 
   rejectAll(message) {
     for (const pending of this.pending.values()) {
       clearTimeout(pending.timeout);
-      pending.reject(new Error(message));
+      pending.reject(browserRequestTransportError({ pending, code: "unavailable", fallback: message }));
     }
     this.pending.clear();
   }
 }
 
 function sendCancelQuietly(transport, id) {
-  try { transport?.send(JSON.stringify({ type: "cancel", id })); } catch {}
+  try { transport?.send(JSON.stringify({ type: "cancel", id })); return true; } catch { return false; }
 }

package/src/local/browser-request-settlement.mjs

@@ -0,0 +1,78 @@
+// @ts-check
+import { browserMethodMayMutate, browserPostDispatchTransportFailure } from "./browser-extension-protocol.mjs";
+import { BridgeError } from "./errors.mjs";
+/** @typedef {{method: unknown, dispatchAttempted?: boolean}} BrowserPendingSettlement */
+/** @param {{pending?: BrowserPendingSettlement | null, code: string, fallback: unknown, terminationRequested?: boolean}} options */
+export function browserRequestTransportError({ pending, code, fallback, terminationRequested = false }) {
+  const mutation = pending?.dispatchAttempted === true && browserMethodMayMutate(pending.method);
+  const message = mutation
+    ? browserPostDispatchTransportFailure(pending.method, boundedMessage(fallback))
+    : boundedMessage(fallback);
+  return new BridgeError(code, message, {
+    expose: true,
+    retryable: mutation ? false : code !== "cancelled",
+    ...(mutation ? {
+      details: {
+        request_delivery: "sent",
+        side_effects_started: "unknown",
+        termination_requested: terminationRequested === true,
+        effect_settlement: terminationRequested === true ? "pending" : "unknown",
+      },
+    } : {}),
+  });
+}
+/** @param {string} message @param {BrowserPendingSettlement | null | undefined} pending */
+export function browserRequestResponseError(message, pending) {
+  const mutation = pending?.dispatchAttempted === true && browserMethodMayMutate(pending.method);
+  if (message === "browser broker is busy") return new BridgeError("limit_exceeded", message, { retryable: true });
+  if (["browser extension is not connected", "browser extension send failed"].includes(message)) return new BridgeError("unavailable", message, { retryable: true });
+  if (message.startsWith("browser mutation request may have been dispatched;")) {
+    return browserRequestTransportError({ pending, code: "unavailable", fallback: message });
+  }
+  if (message.startsWith("browser broker request timed out after dispatch")) {
+    return browserRequestTransportError({
+      pending,
+      code: "timeout",
+      fallback: message,
+      terminationRequested: mutation && message.includes("cancellation requested"),
+    });
+  }
+  if (message.startsWith("browser connection changed after request dispatch")) {
+    return browserRequestTransportError({ pending, code: "unavailable", fallback: message });
+  }
+  const partial = mutation && (
+    message.startsWith("browser mutation may have completed;")
+    || message.startsWith("trusted browser input may have been partially dispatched")
+    || message.startsWith("form submission failed after partial changes")
+    || message.startsWith("browser action may have been dispatched")
+    || message.startsWith("browser tab mutation may have been dispatched")
+    || message.startsWith("browser screenshot temporary tab activation may have been dispatched")
+    || message.startsWith("browser screenshot restoration may have been dispatched")
+  );
+  return partial
+    ? new BridgeError("execution_failed", message, {
+        expose: true,
+        retryable: false,
+        details: { side_effects_started: true, termination_requested: false, effect_settlement: "unknown" },
+      })
+    : new BridgeError("execution_failed", message, { expose: true, retryable: false });
+}
+/** @param {BrowserPendingSettlement | null | undefined} pending */
+export function invalidBrowserResponseSettlement(pending) {
+  if (pending?.dispatchAttempted === true && browserMethodMayMutate(pending.method)) {
+    return browserRequestTransportError({
+      pending,
+      code: "execution_failed",
+      fallback: "browser extension response was malformed",
+    });
+  }
+  return new BridgeError("execution_failed", "browser extension response was malformed", {
+    expose: true,
+    retryable: false,
+  });
+}
+/** @param {unknown} value */
+function boundedMessage(value) {
+  const message = value instanceof Error ? value.message : typeof value === "string" ? value : "browser transport failed";
+  return message ? message.slice(0, 2000) : "browser transport failed";
+}

package/src/local/browser-resource-input.mjs

@@ -0,0 +1,74 @@
+import { normalizeBrowserSelector, normalizeFormAction } from "./browser-command.mjs";
+
+const MAX_FIELD_VALUE_CHARS = 128 * 1024;
+const RESOURCE_NAME = /^[a-z][a-z0-9._-]{0,63}$/;
+
+export function prepareBrowserFormField(input, index) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error(`fields[${index}] must be an object`);
+  const allowed = new Set(["selector", "value", "value_resource", "action", "sensitive"]);
+  for (const key of Object.keys(input)) if (!allowed.has(key)) throw new Error(`unknown fields[${index}] property: ${key}`);
+  if (input.sensitive !== undefined && typeof input.sensitive !== "boolean") throw new Error(`fields[${index}].sensitive must be boolean`);
+  const action = input.action === undefined ? "fill" : normalizeFormAction(input.action);
+  const selector = normalizeBrowserSelector(input.selector, action);
+  const directValue = input.value === undefined ? null : boundedBrowserValue(input.value, `fields[${index}].value`);
+  const resourceName = input.value_resource === undefined ? "" : validateBrowserResource(input.value_resource);
+  if (directValue !== null && resourceName) throw new Error(`fields[${index}] value and value_resource are mutually exclusive`);
+  const hasValue = directValue !== null || Boolean(resourceName);
+  if (!hasValue && !["check", "uncheck", "click"].includes(action)) throw new Error(`fields[${index}] requires value or value_resource`);
+  if (hasValue && !["fill", "select"].includes(action)) throw new Error(`fields[${index}] value is not valid for action '${action}'`);
+  return { index, selector, action, sensitive: input.sensitive === true, value: directValue, resourceName };
+}
+
+export function normalizeUploadFilename(value, { derived = false } = {}) {
+  if (typeof value !== "string") {
+    if (derived) return "upload.bin";
+    throw new Error("filenames entries must be safe single-component filenames of at most 255 characters");
+  }
+  let name = value;
+  if (derived) name = name.replace(/[\u0000-\u001f\u007f/\\]+/g, "_").trim();
+  if (!name || name === "." || name === ".." || name.length > 255 || /[\u0000-\u001f\u007f/\\]/.test(name)) {
+    if (derived) return "upload.bin";
+    throw new Error("filenames entries must be safe single-component filenames of at most 255 characters");
+  }
+  return name;
+}
+
+export function normalizeMimeType(value) {
+  if (typeof value !== "string") throw new Error("mime_types entries must be valid media types");
+  const mime = value.trim().toLowerCase();
+  if (!/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/.test(mime) || mime.length > 200) {
+    throw new Error("mime_types entries must be valid media types");
+  }
+  return mime;
+}
+
+export function optionalStringArray(value, label, maxItems, maxLength) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > maxItems) throw new Error(`${label} must be an array with at most ${maxItems} entries`);
+  return value.map((item, index) => {
+    if (typeof item !== "string" || item.includes("\0") || !item.length || item.length > maxLength) {
+      throw new Error(`${label}[${index}] must be a non-empty string of at most ${maxLength} characters`);
+    }
+    return item;
+  });
+}
+
+export async function resolveBrowserActionValue(args, readResourceText) {
+  let value = args.value === undefined ? null : boundedBrowserValue(args.value, "value");
+  if (args.value_resource !== undefined) {
+    if (value !== null) throw new Error("value and value_resource are mutually exclusive");
+    value = boundedBrowserValue(await readResourceText(validateBrowserResource(args.value_resource)), "value_resource");
+  }
+  return { value, source: args.value_resource !== undefined ? "local-resource" : value === null ? "none" : "mcp-argument" };
+}
+
+export function boundedBrowserValue(value, label) {
+  if (typeof value !== "string") throw new Error(`${label} must be a string`);
+  if (value.includes("\0") || value.length > MAX_FIELD_VALUE_CHARS) throw new Error(`${label} exceeds the maximum length or contains a NUL byte`);
+  return value;
+}
+
+export function validateBrowserResource(value) {
+  if (typeof value !== "string" || !RESOURCE_NAME.test(value)) throw new Error("value_resource is invalid");
+  return value;
+}

package/src/local/browser-trusted-input-health.mjs

@@ -0,0 +1,63 @@
+import { BridgeError } from "./errors.mjs";
+
+const TRUSTED_PAGE_ACTIONS = new Set(["click", "double_click", "hover", "press", "type_text"]);
+const AMBIGUOUS_TRUSTED_INPUT = "trusted browser input may have been partially dispatched";
+export const TRUSTED_INPUT_QUARANTINE_REASON = "browser_trusted_input_quarantined";
+export const TRUSTED_INPUT_QUARANTINE_FALLBACK = "trusted_input_quarantined_after_ambiguous_failure";
+
+export class BrowserTrustedInputHealth {
+  constructor({ logger = null } = {}) {
+    this.logger = logger || { event() {} };
+    this.quarantinedGeneration = 0;
+  }
+
+  status(bridge = {}) {
+    const connected = bridge.extensionConnected === true;
+    const generation = extensionGeneration(bridge);
+    const supported = bridge.extensionInfo?.capabilities?.includes("trusted_input") === true;
+    const quarantined = connected && generation > 0 && this.quarantinedGeneration === generation;
+    return Object.freeze({ connected, generation, supported, quarantined, available: connected && supported && !quarantined });
+  }
+
+  pageInputMode({ inputMode, action, bridge }) {
+    const health = this.status(bridge);
+    if (!health.quarantined || inputMode === "dom" || !TRUSTED_PAGE_ACTIONS.has(action)) {
+      return Object.freeze({ inputMode, fallback: false });
+    }
+    if (inputMode === "trusted") throw quarantinedError();
+    return Object.freeze({ inputMode: "dom", fallback: true });
+  }
+
+  assertTrustedAvailable(bridge) {
+    if (this.status(bridge).quarantined) throw quarantinedError();
+  }
+
+  noteAmbiguousFailure(error, bridge = {}) {
+    const message = String(error?.message || error || "");
+    if (!message.startsWith(AMBIGUOUS_TRUSTED_INPUT)) return false;
+    const health = this.status(bridge);
+    if (!health.connected || health.generation < 1) return false;
+    if (this.quarantinedGeneration !== health.generation) {
+      this.quarantinedGeneration = health.generation;
+      this.logger.event?.("warn", "browser.trusted_input.quarantined", {
+        reason: "ambiguous_input_settlement",
+      }, "trusted browser input quarantined for the current extension connection");
+    }
+    return true;
+  }
+}
+
+function extensionGeneration(bridge) {
+  const value = bridge.extensionGeneration;
+  if (Number.isSafeInteger(value) && value > 0) return value;
+  return bridge.extensionConnected === true ? 1 : 0;
+}
+
+function quarantinedError() {
+  return new BridgeError("unavailable",
+    "trusted browser input is quarantined for the current extension connection after an ambiguous dispatch",
+    {
+      retryable: false,
+      details: { reason: TRUSTED_INPUT_QUARANTINE_REASON, side_effects_started: false },
+    });
+}

package/src/local/call-authority.mjs

@@ -0,0 +1,21 @@
+import { recordMatchesAuthorityRevocation } from "../shared/authority-revocation.mjs";
+
+export function bindCallPrincipal(record, principal) {
+  if (!record || !principal || typeof principal !== "object") return false;
+  if (principal.kind !== "account") {
+    record.owner_kind = "local";
+    return true;
+  }
+  record.owner_kind = "account";
+  record.owner_account_id = String(principal.accountId || "");
+  record.owner_account_version = Number(principal.accountVersion);
+  record.owner_client_id = String(principal.clientId || "");
+  record.owner_family_id = String(principal.familyId || "");
+  return true;
+}
+
+export function callIdsForAuthority(records, revocation) {
+  return [...records]
+    .filter((record) => recordMatchesAuthorityRevocation(record, revocation))
+    .map((record) => record.id);
+}

package/src/local/call-capacity.mjs

@@ -0,0 +1,45 @@
+import { toolCallAdmission, toolCallCapacityConfig, toolCallCapacityUsage } from "../shared/tool-call-capacity.mjs";
+import { BridgeError } from "./errors.mjs";
+
+/** @param {unknown} maximumValue @param {unknown} reservedValue @param {Iterable<string>} [reservedTools] */
+export function callCapacityConfig(maximumValue, reservedValue, reservedTools = []) {
+  const maximum = Number(maximumValue);
+  return toolCallCapacityConfig(
+    Number.isFinite(maximum) && maximum > 0 ? Math.floor(maximum) : 16,
+    reservedValue,
+    reservedTools,
+  );
+}
+
+/** @param {Map<string, any>} calls @param {ReturnType<typeof callCapacityConfig>} config @param {string} toolName */
+export function assertCallCapacity(calls, config, toolName) {
+  const decision = toolCallAdmission(callSnapshot(calls), config, toolName);
+  if (decision.allowed) return;
+  if (decision.reason === "total_capacity") {
+    throw new BridgeError("limit_exceeded", `too many concurrent tool calls (${config.maximum})`, { retryable: true });
+  }
+  throw new BridgeError(
+    "limit_exceeded",
+    `ordinary tool-call capacity reached (${config.ordinaryMaximum}); control-plane capacity is reserved for diagnosis and recovery`,
+    { retryable: true },
+  );
+}
+
+/** @param {Map<string, any>} calls @param {ReturnType<typeof callCapacityConfig>} config */
+export function callCapacitySnapshot(calls, config) {
+  const usage = toolCallCapacityUsage(callSnapshot(calls), config);
+  return {
+    maximum: usage.maximum,
+    ordinary_capacity: usage.ordinaryMaximum,
+    reserved_capacity: usage.reserved,
+    active_reserved: usage.activeReserved,
+    active_ordinary: usage.activeOrdinary,
+  };
+}
+
+/** @param {Map<string, any>} calls */
+function callSnapshot(calls) {
+  const byTool = Object.create(null);
+  for (const call of calls.values()) byTool[call.tool] = (byTool[call.tool] || 0) + 1;
+  return { active: calls.size, byTool };
+}

package/src/local/call-registry-drain.mjs

@@ -0,0 +1,54 @@
+import { BridgeError } from "./errors.mjs";
+import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
+
+const states = new WeakMap();
+
+/** @typedef {{ calls: ReadonlyMap<string, unknown>, cancel: (callId: unknown, reason?: unknown, code?: string) => boolean }} DrainableCallRegistry */
+
+export function assertCallRegistryOpen(registry) {
+  if (!stateFor(registry).draining) return;
+  throw new BridgeError("unavailable", "runtime is stopping and cannot accept new tool calls", { retryable: true });
+}
+
+/** @param {DrainableCallRegistry} registry @param {unknown} [reason] @param {number} [waitMs] */
+export async function cancelAllCallsAndWait(registry, reason = "runtime stopped", waitMs = 5_000) {
+  const state = stateFor(registry);
+  state.draining = true;
+  for (const id of [...registry.calls.keys()]) registry.cancel(id, reason);
+  const deadline = createMonotonicDeadline(waitMs);
+  while (registry.calls.size && !deadline.expired()) {
+    await waitForRegistryChange(state, Math.max(1, deadline.remainingMs()));
+  }
+  if (registry.calls.size) {
+    throw new BridgeError("unavailable", "tool call shutdown did not settle before the runtime teardown deadline", {
+      retryable: true,
+      details: { active_calls: registry.calls.size },
+    });
+  }
+}
+
+export function notifyCallRegistryChanged(registry) {
+  for (const waiter of [...stateFor(registry).waiters]) waiter();
+}
+
+function stateFor(registry) {
+  let state = states.get(registry);
+  if (!state) {
+    state = { draining: false, waiters: new Set() };
+    states.set(registry, state);
+  }
+  return state;
+}
+
+function waitForRegistryChange(state, waitMs) {
+  return new Promise((resolvePromise) => {
+    let timer;
+    const done = () => {
+      if (timer) clearTimeout(timer);
+      state.waiters.delete(done);
+      resolvePromise();
+    };
+    state.waiters.add(done);
+    timer = setTimeout(done, waitMs);
+  });
+}