cdp-toolkit 2.0.0 → 2.2.0

package/src/bidi/session-lease.ts

@@ -35,8 +35,34 @@
  * ATOMICITY. Claims are exclusive creates (writeFile flag "wx"), exactly like
  * ../leases.ts claimLease, so "is the slot free, and if so take it" is atomic
  * against a racing process for free, with no registry lock.
+ *
+ * THE MUX: WHY A LIVE HOLDER IS NO LONGER A DEAD END. Everything above still
+ * holds — one process owns Firefox's single BiDi session — but the holder now
+ * also hosts a loopback BiDi multiplexer (./mux.ts) over that one real session
+ * and ADVERTISES its ws endpoint in this record (`muxEndpoint`). Two consequences
+ * for this module, and nothing else changes:
+ *
+ *  - THE HOLDER advertises via advertiseMux() once its mux is listening. That is
+ *    a rewrite of its OWN record, guarded by the same (pid, createdAt) ownership
+ *    test release uses, and written atomically (tmp + rename) so a concurrent
+ *    reader never sees a half-written record. Advertising is best-effort: a
+ *    refusal (`advertised:false`) means the record is no longer ours and the
+ *    holder simply runs alone.
+ *  - A JOINER DOES NOT WAIT. When acquire finds a LIVE holder that carries a
+ *    muxEndpoint, there is nothing to wait FOR: the slot will not free up (the
+ *    holder is healthy) and it does not need to, because the mux serves that one
+ *    session to as many processes as ask. So acquire returns { joinMux }
+ *    immediately, with NO handle and nothing written to disk — the joiner holds
+ *    no slot and must never release one. The record is re-read on every poll
+ *    iteration, so a holder that took the slot a moment ago and advertises a beat
+ *    later is joined as soon as it does, inside the existing wait window.
+ *
+ * A live holder with NO muxEndpoint (a foreign client, an older cdp-toolkit, or
+ * one running with CDP_FIREFOX_MUX=off) is still plain BUSY and still throws
+ * SessionSlotBusyError at the deadline — exactly today's behavior. CDP_FIREFOX_MUX=off
+ * makes acquire ignore muxEndpoint entirely, which is the opt-out.
  */
-import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { isPidAlive, leaseDir } from "../leases.ts";
 
@@ -55,6 +81,12 @@ export interface SessionSlotRecord {
   createdAt: number;
   /** Optional Marionette control port bound to this Firefox, when known. */
   marionettePort?: number;
+  /**
+   * Loopback ws endpoint of the BiDi multiplexer this holder hosts over the one
+   * real session (see ./mux.ts and the header). Absent means "this holder serves
+   * nobody but itself", which is what every pre-mux client's record looks like.
+   */
+  muxEndpoint?: string;
 }
 
 /**
@@ -68,7 +100,11 @@ export interface SessionSlotHandle {
 }
 
 export interface AcquireResult {
-  handle: SessionSlotHandle;
+  /**
+   * Present iff WE took the slot. Absent on the joinMux path: a joiner owns no
+   * slot, wrote no record, and must never release one.
+   */
+  handle?: SessionSlotHandle;
   /**
    * Set only when we STOLE a dead holder's slot. Its presence tells the caller
    * that Firefox may still believe an orphaned BiDi session is active, so the
@@ -77,6 +113,12 @@ export interface AcquireResult {
    * sessions". Absent on a clean first acquire.
    */
   staleHolder?: SessionSlotRecord;
+  /**
+   * Set instead of `handle` when a LIVE holder advertises a BiDi multiplexer.
+   * The caller dials `endpoint` exactly as it would dial Firefox; `holder` is the
+   * record it came from, for error reporting. Nothing was written to disk.
+   */
+  joinMux?: { endpoint: string; holder: SessionSlotRecord };
 }
 
 export interface AcquireOptions {
@@ -105,6 +147,16 @@ export function sessionSlotFile(endpoint: string): string {
   return join(leaseDir(), `ff-session-${safeEndpoint(endpoint)}.json`);
 }
 
+/**
+ * Where the detached mux DAEMON (./mux-daemon.ts) appends its one-line diagnostics for this
+ * endpoint. It is spawned with stdio:"ignore" (no console at all), so this file is the ONLY
+ * record of why a daemon refused to start; the driver names it in the error it raises when a
+ * daemon it spawned never advertised. Sibling of the slot file, same safeEndpoint key.
+ */
+export function muxDaemonLogFile(endpoint: string): string {
+  return join(leaseDir(), `ff-mux-${safeEndpoint(endpoint)}.log`);
+}
+
 /** Read per call (like leaseDir/leaseTtlMs), so a test can redirect it. A value
  *  that is not a finite number > 0 falls back to the default. */
 export function sessionWaitMs(): number {
@@ -236,7 +288,16 @@ export async function acquireSessionSlot(endpoint: string, opts: AcquireOptions)
       }
     }
 
-    // 4. LIVE holder: legitimate contention. Poll until the deadline, then fail.
+    // 4. LIVE holder. If it advertises a mux, JOIN it instead of waiting: the slot
+    // is never going to free up, and it does not have to — the holder's mux serves
+    // the one real session to every joiner. Return immediately, writing nothing.
+    // (The re-read at step 2 happens every iteration, so a holder that advertises a
+    // beat after taking the slot is picked up on the next poll.) CDP_FIREFOX_MUX=off
+    // opts out and restores the pre-mux busy-wait exactly.
+    if (typeof holder.muxEndpoint === "string" && holder.muxEndpoint.length > 0 && process.env.CDP_FIREFOX_MUX !== "off") {
+      return { joinMux: { endpoint: holder.muxEndpoint, holder } };
+    }
+    // No mux: legitimate contention. Poll until the deadline, then fail.
     lastLiveHolder = holder;
     const remaining = deadline - Date.now();
     if (remaining <= 0) throw new SessionSlotBusyError(endpoint, holder);
@@ -244,6 +305,37 @@ export async function acquireSessionSlot(endpoint: string, opts: AcquireOptions)
   }
 }
 
+/**
+ * Publish this holder's BiDi multiplexer endpoint into its OWN slot record, so a
+ * contending process joins the mux instead of waiting out the slot.
+ *
+ * Ownership-guarded by the same (pid, createdAt) test releaseSessionSlot uses: if
+ * the record on disk is missing or belongs to someone else (we were stolen from
+ * as a dead-looking holder, or we already released), we refuse with
+ * { advertised: false } and leave the file byte-for-byte untouched rather than
+ * stamping our mux onto a stranger's claim.
+ *
+ * Atomic: the merged record is written to `<file>.tmp-<pid>` and renamed over the
+ * original, so a concurrent acquire's read sees either the old record or the new
+ * one, never a truncated one. Every other field is preserved.
+ */
+export async function advertiseMux(handle: SessionSlotHandle, muxEndpoint: string): Promise<{ advertised: boolean }> {
+  const current = await readSessionSlot(handle.endpoint);
+  if (!current) return { advertised: false };
+  if (current.pid !== process.pid || current.createdAt !== handle.createdAt) return { advertised: false };
+  const file = sessionSlotFile(handle.endpoint);
+  const tmp = `${file}.tmp-${process.pid}`;
+  const next: SessionSlotRecord = { ...current, muxEndpoint };
+  try {
+    await writeFile(tmp, JSON.stringify(next), "utf8");
+    await rename(tmp, file);
+  } catch {
+    await unlink(tmp).catch(() => undefined);
+    return { advertised: false };
+  }
+  return { advertised: true };
+}
+
 /**
  * Release the slot, but ONLY if the record on disk is still the one we wrote.
  *

package/src/manifest.ts

@@ -230,6 +230,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "args": {
           "type": "array",
+          "items": {},
           "description": "Positional JSON arguments."
         },
         "savePath": {

package/src/mcp.ts

@@ -10,6 +10,9 @@
  *
  * Launch: `bunx -y cdp-toolkit`  (or `bun run src/mcp.ts` from a checkout)
  * Config:  CDP_BASE (default http://127.0.0.1:9222), CDP_TIMEOUT_MS, CDP_ARTIFACT_DIR,
+ *          CDP_TOOL_PROFILE (`full` — the default — advertises every group; `core` advertises
+ *          just the 12 everyday tools; or a comma-separated group list, e.g. `core,network`.
+ *          Startup-only filter on what tools/list shows; unlisted tools stay callable by name),
  *          CDP_FIREFOX_ENDPOINT (attach to a user-launched Firefox instead of spawning one;
  *          see backend.ts's ATTACH mode).
  *
@@ -17,7 +20,7 @@
  */
 import { Server } from "@modelcontextprotocol/server";
 import type { Tool } from "@modelcontextprotocol/server";
-import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { TOOLS, TOOL_NAMES, BASE } from "./index.ts";
 import { MANIFEST } from "./manifest.ts";
 import { resolveBackend, getOrCreateFirefoxSession, disposeFirefoxSession } from "./backend.ts";
@@ -25,10 +28,9 @@ import { disposeBrowserSession } from "./tools/browser-session.ts";
 import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, markLongLivedProcess, withLeaseScope } from "./leases.ts";
-import { TOOL_GROUP, TOOL_GROUPS, GROUP_TOOLS, PROFILES, type ProfileName } from "./toolGroups.ts";
+import { resolveProfile, TOOL_GROUP, TOOL_GROUPS, GROUP_TOOLS } from "./toolGroups.ts";
 import { TOOL_DOCS } from "./toolDocs.ts";
-
-const VERSION = "2.0.0";
+import { VERSION } from "./version.ts";
 
 // Backend + (Firefox only) attach endpoint are read once at startup (MCP has no per-call notion
 // of backend): --browser flag / CDP_BROWSER env, else "chrome" (zero behavior change for existing
@@ -52,70 +54,85 @@ function auditCoverage(): void {
   if (orphanSchema.length) console.error(`[cdp-toolkit] WARN: manifest schemas with no registered tool: ${orphanSchema.join(", ")}`);
 }
 
-// Server `instructions` (MCP initialize result): the cross-cutting conventions that
-// used to be re-stated inside every tool's schema — the target-selector grammar, the
-// lease-token model, the MV3 worker/wake arm, the origin vocabulary. Stating them ONCE
-// here (loaded a single time at init) is what let the per-tool descriptions and the
+// Server `instructions` (returned by server/discover on 2026-era connections, and by
+// initialize on 2025-era ones): the cross-cutting conventions that used to be re-stated
+// inside every tool's schema — the target-selector grammar, the lease-token model, the
+// MV3 worker/wake arm, the origin vocabulary — plus how to read the (fixed, cacheable)
+// tool listing. Stating them ONCE here is what let the per-tool descriptions and the
 // 42-way-duplicated `lease` param collapse to short pointers, cutting the tools/list
 // payload without losing a single behavior. Kept under Claude Code's 2KB instructions
 // cap and front-loaded (grammar + leases before origin) so nothing critical is clipped.
 const INSTRUCTIONS = [
   "cdp-toolkit drives a real browser over Chrome DevTools Protocol (or Firefox WebDriver-BiDi): open and drive pages, click/fill/type, screenshot and accessibility-snapshot, read console + network, set cookies, emulate devices, run Lighthouse and performance traces, record screencasts. Conventions shared across its tools:",
-  "TOOL AVAILABILITY: the server starts on the core profile (12 everyday tools); the rest are organized into groups you can discover and activate with `browser_tools` (or start with CDP_TOOL_PROFILE=full for everything at once). `describe_tool` returns full docs for any tool by name, including hidden ones. Hidden tools are still callable by name even while unlisted.",
+  "TOOL AVAILABILITY: tools/list is complete and fixed for this process's life — cache it. Its one-liners are not the full docs: call describe_tool {name} on an unfamiliar tool, or describe_tool {} for the grouped catalog. CDP_TOOL_PROFILE=core (or a group list) lists only those groups; unlisted tools stay callable by name.",
   "TARGET SELECTOR (the `target` param, unless a tool says otherwise): 'active' (default = first page) | 'index:N' (0-based) | 'url:<substr>' | 'title:<substr>' | 'label:<name>' (exact, from the origin ledger or a live lease) | a 32-hex '<targetId>'. Four Chrome-only tools (evaluate_script, list_network_requests, get_network_request, list_console_messages) also accept 'worker:<substr>' to reach a service/shared worker — e.g. an MV3 extension's background worker (worker:<extension-id> or worker:background.js); an idle-evicted worker is started first (see each tool's `wake`).",
   "LEASES (the `lease` param): claim_page, and new_page{claim:true}, mint an opaque token. Omit it for a tab THIS process already holds. It is required for a tab held by ANOTHER process, or one claimed explicitly. Under CDP_REQUIRE_LEASE the gate auto-acquires a lease for any tab this process drives — no token is surfaced, so pass `target`, not `lease` — while an explicit claim:true still demands its token on every later call. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all.",
   "ORIGIN: list_pages and list_leases tag each tab's `origin` as 'agent' (this toolkit created it) or 'unknown' — never 'human', because the toolkit cannot prove a person opened a tab. An 'agent' tab stays findable after its creator releases the lease or dies.",
 ].join("\n\n");
 
-// Progressive disclosure: start with a lean profile (default "core") and reveal
-// further tool groups on demand via the browser_tools meta-tool, which fires
-// notifications/tools/list_changed so the client re-fetches tools/list. This keeps
-// the baseline tools/list payload — and thus the context tokens the toolkit costs —
-// a fraction of the full 45-tool surface until a group is actually needed. Set
-// CDP_TOOL_PROFILE=full to advertise everything at startup (prior behavior).
-const START_PROFILE: ProfileName = process.env.CDP_TOOL_PROFILE === "full" ? "full" : "core";
-const activeGroups = new Set<string>(PROFILES[START_PROFILE]);
+// Progressive disclosure, 2.1 model: the tool listing is STATIC — computed once here and
+// returned byte-identical to every tools/list on every connection, so a client may cache
+// it (the 2026-07-28 revision requires the tool set not to change as a side effect of
+// other requests, which is exactly what the 2.0 browser_tools toggle did). Discovery is
+// the HOST's job per the MCP client best-practices: the client picks which of the listed
+// tools to put in front of the model. `describe_tool` is the inspect layer — one call
+// returns the full prose for any tool, listed or not — and CDP_TOOL_PROFILE is the only
+// filter, applied once at startup by whoever configures the server. A tool that the
+// profile hides is still callable by name; hiding only trims the listing's token cost.
+const PROFILE = startupProfile();
 
-/** Always-listed meta-tools that drive disclosure; never part of a group. */
-const META_TOOLS: ReadonlyArray<{ name: string; description: string; inputSchema: Tool["inputSchema"] }> = [
+/** Read CDP_TOOL_PROFILE once; an unknown group name is a configuration error, not a warning. */
+function startupProfile() {
+  try {
+    return resolveProfile(process.env.CDP_TOOL_PROFILE);
+  } catch (err) {
+    console.error(`[cdp-toolkit] ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * The one and only tools/list payload, in manifest order (a stable order is a spec
+ * SHOULD, and it keeps the response byte-identical across calls so caching is real):
+ * describe_tool first, then every manifest tool the selected backend can run whose
+ * group the profile advertises. Descriptions here are the compressed one-liners —
+ * full prose is served on demand by describe_tool.
+ *
+ * Frozen at runtime (the handler hands the SAME array to every caller); the cast back to
+ * a mutable Tool[] is only because ListToolsResult declares `tools` mutable.
+ */
+const LISTING: Tool[] = Object.freeze([
   {
-    name: "browser_tools",
+    name: "describe_tool",
     description:
-      "Manage which cdp-toolkit tool groups are exposed (progressive disclosure). Most tools are hidden until their group is activated; activating one reveals its tools via tools/list_changed. Use action:list_groups first to see what exists.",
+      "Full description and per-parameter docs for any cdp-toolkit tool by name, including tools not in tools/list (unlisted tools stay callable by name). Call it before using an unfamiliar tool: the live tools/list carries only terse one-liners. With no name it returns the grouped catalog of every tool the selected browser supports.",
     inputSchema: {
       type: "object",
       properties: {
-        action: {
+        name: {
           type: "string",
-          enum: ["list_groups", "activate", "deactivate", "set_profile"],
-          description: "list_groups: show every group, its tools, and active state; activate/deactivate: toggle one group; set_profile: switch wholesale.",
+          description: "Tool name, e.g. take_screenshot. Omit it to get the catalog: every group, its tool names, and whether the group is in tools/list.",
         },
-        group: { type: "string", enum: [...TOOL_GROUPS], description: "Group for activate/deactivate." },
-        profile: { type: "string", enum: ["core", "full"], description: "Profile for set_profile (core=lean, full=all groups)." },
       },
-      required: ["action"],
-      additionalProperties: false,
-    } as Tool["inputSchema"],
-  },
-  {
-    name: "describe_tool",
-    description: "Return the full description and per-parameter docs for any cdp-toolkit tool by name — including tools not currently listed. Call this before using an unfamiliar tool; the live tools/list carries only terse summaries.",
-    inputSchema: {
-      type: "object",
-      properties: { name: { type: "string", description: "Tool name, e.g. take_screenshot." } },
-      required: ["name"],
       additionalProperties: false,
     } as Tool["inputSchema"],
   },
-];
+  ...MANIFEST
+    .filter((s) => AVAILABLE_NAMES.has(s.name) && PROFILE.groups.has(TOOL_GROUP[s.name]!))
+    .map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema as Tool["inputSchema"] })),
+] satisfies Tool[]) as Tool[];
 
-/** Human-readable dump of every group, its tools, and whether it's currently active. */
-function renderGroups(): string {
-  const lines = [`profile start=${START_PROFILE}; active groups: ${[...activeGroups].join(", ") || "(none)"}`];
+/** describe_tool with no name: every group the backend supports, and whether it is listed. */
+function renderCatalog(): string {
+  const lines = [
+    `cdp-toolkit ${VERSION} · browser=${BROWSER} · ${AVAILABILITY.available.length} tools available, ${LISTING.length} in tools/list (CDP_TOOL_PROFILE=${PROFILE.label})`,
+  ];
   for (const g of TOOL_GROUPS) {
     const shown = GROUP_TOOLS[g].filter((n) => AVAILABLE_NAMES.has(n));
-    lines.push(`${activeGroups.has(g) ? "[on] " : "[off]"} ${g} (${shown.length}): ${shown.join(", ")}`);
+    if (!shown.length) continue;
+    lines.push(`${PROFILE.groups.has(g) ? "[listed]" : "[hidden]"} ${g} (${shown.length}): ${shown.join(", ")}`);
   }
+  lines.push("Unlisted tools are callable by name; describe_tool {name} documents any of them.");
   return lines.join("\n");
 }
 
@@ -129,114 +146,114 @@ function renderToolDoc(toolName: string): string {
   return `${toolName}${group ? ` [group: ${group}]` : ""}\n\n${doc.description}\n\nParameters:\n${body}`;
 }
 
-const server = new Server({ name: "cdp-toolkit", version: VERSION }, { capabilities: { tools: { listChanged: true } }, instructions: INSTRUCTIONS });
-
-server.setRequestHandler('tools/list', async () => ({
-  // Two-axis disclosure: (1) the always-present meta-tools; (2) manifest tools the
-  // selected backend can run AND whose group is currently active. Descriptions/schemas
-  // here are the compressed form — full prose is served on demand by describe_tool.
-  tools: [
-    ...META_TOOLS,
-    ...MANIFEST
-      .filter((s) => AVAILABLE_NAMES.has(s.name) && activeGroups.has(TOOL_GROUP[s.name] ?? ""))
-      .map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema as Tool["inputSchema"] })),
-  ],
-}));
+// The listing never changes, and it is identical for every caller (a stdio server has no
+// per-caller auth), so it is `public` with a 1h TTL rather than the SDK's conservative
+// { ttlMs: 0, cacheScope: 'private' } default. A restart under a different CDP_TOOL_PROFILE
+// or --browser is a different server configuration, not a mid-life change to this one.
+const LIST_CACHE_HINT = { ttlMs: 3_600_000, cacheScope: "public" } as const;
 
-server.setRequestHandler('tools/call', async (request) => {
-  const { name } = request.params;
-  const args = (request.params.arguments ?? {}) as unknown;
+/**
+ * Build one server instance. serveStdio calls this per connection — and possibly twice
+ * per process (a server/discover probe instance that is discarded if the client falls
+ * back to initialize) — so it must be PURE: no I/O, no shared mutable state.
+ *
+ * We stay on the low-level `Server` rather than `McpServer` deliberately, despite the
+ * deprecation note. McpServer.registerTool wants a Standard-Schema (zod) object for
+ * inputSchema, and CONTRACT.md rule 1 forbids any runtime dependency beyond the SDK;
+ * our manifest is plain JSON Schema (src/manifest.ts). McpServer also cannot express
+ * "hidden tools remain callable by name", which is the whole point of CDP_TOOL_PROFILE.
+ */
+function buildServer(): Server {
+  const server = new Server(
+    { name: "cdp-toolkit", version: VERSION },
+    {
+      // The list is fixed for the life of the process; nothing will ever notify.
+      capabilities: { tools: { listChanged: false } },
+      instructions: INSTRUCTIONS,
+      cacheHints: { "tools/list": LIST_CACHE_HINT, "server/discover": LIST_CACHE_HINT },
+    },
+  );
 
-  // Meta-tools are handled at the MCP layer (they mutate what tools/list advertises)
-  // and never enter the browser dispatch or a lease scope.
-  if (name === "describe_tool") {
-    const toolName = typeof (args as { name?: unknown }).name === "string" ? (args as { name: string }).name : "";
-    const known = Boolean(TOOL_DOCS[toolName]);
-    return { content: [{ type: "text" as const, text: renderToolDoc(toolName) }], isError: !known };
-  }
+  server.setRequestHandler('tools/list', async () => ({ tools: LISTING }));
 
-  if (name === "browser_tools") {
-    const a = args as { action?: unknown; group?: unknown; profile?: unknown };
-    const action = typeof a.action === "string" ? a.action : "";
-    const before = [...activeGroups].sort().join(",");
+  server.setRequestHandler('tools/call', async (request) => {
+    const { name } = request.params;
+    const args = (request.params.arguments ?? {}) as unknown;
 
-    if (action === "list_groups") {
-      return { content: [{ type: "text" as const, text: renderGroups() }] };
-    }
-    if (action === "activate" || action === "deactivate") {
-      const group = typeof a.group === "string" ? a.group : "";
-      if (!(TOOL_GROUPS as readonly string[]).includes(group)) {
-        return { content: [{ type: "text" as const, text: `unknown group: ${group}. Known: ${TOOL_GROUPS.join(", ")}` }], isError: true };
+    // describe_tool is handled at the MCP layer (it reads only static docs) and never
+    // enters the browser dispatch or a lease scope. With a name it documents one tool —
+    // listed or not; with no name it returns the grouped catalog.
+    if (name === "describe_tool") {
+      const requested = (args as { name?: unknown }).name;
+      if (typeof requested !== "string" || requested === "") {
+        return { content: [{ type: "text" as const, text: renderCatalog() }] };
       }
-      if (action === "activate") activeGroups.add(group);
-      else activeGroups.delete(group);
-    } else if (action === "set_profile") {
-      const profile = a.profile === "full" ? "full" : a.profile === "core" ? "core" : "";
-      if (!profile) return { content: [{ type: "text" as const, text: `unknown profile: ${String(a.profile)}. Known: core, full` }], isError: true };
-      activeGroups.clear();
-      for (const g of PROFILES[profile]) activeGroups.add(g);
-    } else {
-      return { content: [{ type: "text" as const, text: `unknown action: ${action}. Use list_groups | activate | deactivate | set_profile.` }], isError: true };
+      const known = Boolean(TOOL_DOCS[requested]);
+      return { content: [{ type: "text" as const, text: renderToolDoc(requested) }], isError: !known };
     }
 
-    if ([...activeGroups].sort().join(",") !== before) {
-      try {
-        await server.sendToolListChanged();
-      } catch (err) {
-        console.error(`[cdp-toolkit] WARN: sendToolListChanged failed: ${err instanceof Error ? err.message : String(err)}`);
-      }
+    if (!AVAILABLE_NAMES.has(name)) {
+      const gap = AVAILABILITY.unavailable.find((u) => u.name === name);
+      return {
+        content: [{ type: "text" as const, text: `unknown tool: ${name}${gap ? ` (not available under --browser ${BROWSER}, needs: ${gap.missing.join(", ")})` : ""}` }],
+        isError: true,
+      };
     }
-    return { content: [{ type: "text" as const, text: renderGroups() }] };
-  }
 
-  if (!AVAILABLE_NAMES.has(name)) {
-    const gap = AVAILABILITY.unavailable.find((u) => u.name === name);
-    return {
-      content: [{ type: "text" as const, text: `unknown tool: ${name}${gap ? ` (not available under --browser ${BROWSER}, needs: ${gap.missing.join(", ")})` : ""}` }],
-      isError: true,
-    };
-  }
+    // ONE lease scope per dispatch, wrapping BOTH backend branches. This is the
+    // reason no tool takes a lease parameter: the token rides the async context
+    // down to whichever resolution path the tool eventually reaches, so a tool
+    // added tomorrow is covered with no action from whoever writes it. Reading
+    // 'lease' off args here is the only place the MCP layer knows the key exists.
+    return withLeaseScope(leaseFromArgs(args), async () => {
+      if (BROWSER === "chrome") {
+        const fn = dispatch[name];
+        if (!fn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
+        try {
+          const result = await fn(args);
+          return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
+        }
+      }
 
-  // ONE lease scope per dispatch, wrapping BOTH backend branches. This is the
-  // reason no tool takes a lease parameter: the token rides the async context
-  // down to whichever resolution path the tool eventually reaches, so a tool
-  // added tomorrow is covered with no action from whoever writes it. Reading
-  // 'lease' off args here is the only place the MCP layer knows the key exists.
-  return withLeaseScope(leaseFromArgs(args), async () => {
-    if (BROWSER === "chrome") {
-      const fn = dispatch[name];
-      if (!fn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
+      // Firefox: one BiDi session memoized for the life of this server process (lifetime "session",
+      // ADR-001); launched lazily on the first Firefox tool call, torn down on shutdown below.
+      const neutralFn = neutralDispatch[name];
+      if (!neutralFn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
       try {
-        const result = await fn(args);
+        const session = await getOrCreateFirefoxSession({ endpoint: FIREFOX_ENDPOINT });
+        const result = await neutralFn(session.driver, args);
         return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
       }
-    }
-
-    // Firefox: one BiDi session memoized for the life of this server process (lifetime "session",
-    // ADR-001); launched lazily on the first Firefox tool call, torn down on shutdown below.
-    const neutralFn = neutralDispatch[name];
-    if (!neutralFn) return { content: [{ type: "text" as const, text: `unknown tool: ${name}` }], isError: true };
-    try {
-      const session = await getOrCreateFirefoxSession({ endpoint: FIREFOX_ENDPOINT });
-      const result = await neutralFn(session.driver, args);
-      return { content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }] };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      return { content: [{ type: "text" as const, text: `Error: ${message}` }], isError: true };
-    }
+    });
   });
-});
+
+  return server;
+}
 
 auditCoverage();
 // This process is the long-lived MCP server, which is what makes strict mode
 // (CDP_REQUIRE_LEASE) safe to honor here and unsafe in cli.ts. See requireLease.
 markLongLivedProcess();
-await server.connect(new StdioServerTransport());
+
+// serveStdio owns the era decision for the connection: a modern opening (server/discover
+// with the per-request _meta envelope) pins a 2026-07-28 instance, a 2025-era `initialize`
+// pins a legacy one. legacy:'serve' (the default) is deliberate — 2025-era clients keep the
+// initialize handshake they expect, so this upgrade is invisible to them.
+const handle = serveStdio(
+  ({ era }) => {
+    console.error(`[cdp-toolkit] connection pinned to the ${era} protocol era`);
+    return buildServer();
+  },
+  { onerror: (err) => console.error(`[cdp-toolkit] stdio: ${err.message}`) },
+);
 console.error(
-  `[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools, CDP_BASE=${BASE}`,
+  `[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools available, ${LISTING.length} listed (CDP_TOOL_PROFILE=${PROFILE.label}), CDP_BASE=${BASE}`,
 );
 
 // LAUNCH-mode Firefox owns a real OS process (see bidi/launch.ts): it must be reaped on every
@@ -255,6 +272,9 @@ async function shutdown(): Promise<void> {
   // Track P3). Unlike Firefox it owns no OS process, so process.exit would collect it anyway; it is
   // closed explicitly so shutdown does not depend on that, and is a no-op when neither tool ran.
   await disposeBrowserSession();
+  // Close the stdio connection (pinned instance + transport) last, so a tool call still
+  // in flight over it cannot outlive the browser resources it was driving.
+  await handle.close().catch(() => undefined);
   process.exit(0);
 }
 process.on("SIGINT", () => void shutdown());

package/src/toolGroups.ts

@@ -47,3 +47,35 @@ export const PROFILES = {
 } as const;
 
 export type ProfileName = keyof typeof PROFILES;
+
+/**
+ * Resolve CDP_TOOL_PROFILE into the set of groups whose tools tools/list advertises.
+ *
+ * The profile is a STARTUP filter, read once: the listing it selects is fixed for the
+ * life of the process (2.1 dropped the runtime `browser_tools` toggle, so the tool set
+ * can never change as a side effect of another request — a spec MUST). Accepted
+ * spellings: unset/empty or "full" (everything), "core" (the lean everyday set), or a
+ * comma-separated list of group names. `core` is always included, so a list can never
+ * strand the basics.
+ */
+export function resolveProfile(spec: string | undefined): { groups: ReadonlySet<ToolGroup>; label: string } {
+  const all = (): { groups: ReadonlySet<ToolGroup>; label: string } => ({ groups: new Set(TOOL_GROUPS), label: "full" });
+  const raw = (spec ?? "").trim();
+  if (raw === "" || raw.toLowerCase() === "full") return all();
+
+  const tokens = raw.split(",").map((t) => t.trim().toLowerCase()).filter((t) => t !== "");
+  if (tokens.includes("full")) return all();
+
+  const known = new Set<string>(TOOL_GROUPS);
+  const picked = new Set<ToolGroup>(["core"]);
+  for (const token of tokens) {
+    if (!known.has(token)) {
+      throw new Error(`CDP_TOOL_PROFILE: unknown tool group '${token}'. Known: full, core, ${TOOL_GROUPS.filter((g) => g !== "core").join(", ")}`);
+    }
+    picked.add(token as ToolGroup);
+  }
+  if (picked.size === TOOL_GROUPS.length) return all();
+  // Canonical label: TOOL_GROUPS order, not the order the caller typed, so the ready
+  // line and the catalog header read the same for every equivalent spelling.
+  return { groups: picked, label: TOOL_GROUPS.filter((g) => picked.has(g)).join(",") };
+}

package/src/version.ts

@@ -0,0 +1,9 @@
+/**
+ * Single source of truth for the package version string.
+ *
+ * mcp.ts reports it in the MCP `serverInfo` (and thus in the 2026-07-28
+ * `_meta['io.modelcontextprotocol/serverInfo']` envelope) and on its stderr
+ * ready line; keeping it in its own module means a release bump touches one
+ * line here plus package.json, not a const buried in the server.
+ */
+export const VERSION = "2.2.0";