@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.a6376d75

package/dist/resources/extensions/bg-shell/process-manager.js

@@ -6,7 +6,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { writeFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { getShellConfig, sanitizeCommand } from "@gsd/pi-coding-agent";
+import { getShellConfig, sanitizeCommand, killProcessTree } from "@gsd/pi-coding-agent";
 import { rewriteCommandWithRtk } from "../shared/rtk.js";
 import { MAX_BUFFER_LINES, MAX_EVENTS, DEAD_PROCESS_TTL, } from "./types.js";
 import { restoreWindowsVTInput, formatUptime } from "./utilities.js";
@@ -221,6 +221,38 @@ export function startProcess(opts) {
     return bg;
 }
 // ── Process Kill ───────────────────────────────────────────────────────────
+/**
+ * Gracefully terminate a process and its tree using the shared killProcessTree
+ * ladder (SIGTERM → grace window → SIGKILL), the same path bash/async_bash/exec
+ * use. This is the "I want it dead, cleanly" intent — use it for the `kill`
+ * action, `restart`, and session cleanup. For sending a SPECIFIC signal the
+ * agent chose on purpose (SIGINT, SIGHUP, …) use killProcess(), which delivers
+ * that exact signal once and does not escalate.
+ *
+ * `graceMs` overrides the SIGTERM→SIGKILL window (default: killProcessTree's 5s);
+ * session cleanup passes a shorter grace so it stays snappy between units.
+ *
+ * Returns false only when the process is unknown/already dead; the actual
+ * SIGKILL escalation fires asynchronously after the grace window, so callers
+ * should not assume the process is dead the instant this returns.
+ */
+export function terminateProcess(id, graceMs) {
+    const bg = processes.get(id);
+    if (!bg)
+        return false;
+    if (!bg.alive)
+        return true;
+    if (!bg.proc.pid) {
+        // No pid to target a tree; fall back to a direct graceful signal.
+        try {
+            bg.proc.kill("SIGTERM");
+        }
+        catch { /* already gone */ }
+        return true;
+    }
+    killProcessTree(bg.proc.pid, graceMs !== undefined ? { graceMs } : undefined);
+    return true;
+}
 export function killProcess(id, sig = "SIGTERM") {
     const bg = processes.get(id);
     if (!bg)
@@ -272,13 +304,14 @@ export async function restartProcess(id) {
         return null;
     const config = old.startConfig;
     const restartCount = old.restartCount + 1;
-    // Kill old process
+    // Kill old process via the graceful ladder, then wait for it to actually die.
+    // killProcessTree escalates SIGTERM → grace → SIGKILL asynchronously, so poll
+    // for death rather than assuming a fixed sleep is enough.
     if (old.alive) {
-        killProcess(id, "SIGTERM");
-        await new Promise(r => setTimeout(r, 300));
-        if (old.alive) {
-            killProcess(id, "SIGKILL");
-            await new Promise(r => setTimeout(r, 200));
+        terminateProcess(id);
+        const deadline = Date.now() + 6_000; // grace (5s) + slack
+        while (old.alive && Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, 100));
         }
     }
     processes.delete(id);
@@ -328,24 +361,16 @@ export function pruneDeadProcesses() {
     }
 }
 export function cleanupAll() {
+    // Deliberately a bare, synchronous SIGKILL — not the graceful ladder. This runs
+    // from process 'exit'/signal handlers where timers no longer fire, so a deferred
+    // SIGKILL would never be delivered and children would be orphaned when we vanish.
+    // Immediate force-kill is the correct teardown semantics here.
     for (const [id, bg] of processes) {
         if (bg.alive)
             killProcess(id, "SIGKILL");
     }
     processes.clear();
 }
-/**
- * Kill all alive, non-persistent bg processes.
- * Called between auto-mode units to prevent orphaned servers from
- * keeping ports bound across task boundaries (#1209).
- */
-export function killSessionProcesses() {
-    for (const [id, bg] of processes) {
-        if (bg.alive && !bg.persistAcrossSessions) {
-            killProcess(id, "SIGTERM");
-        }
-    }
-}
 async function waitForProcessExit(bg, timeoutMs) {
     if (!bg.alive)
         return true;
@@ -359,20 +384,24 @@ async function waitForProcessExit(bg, timeoutMs) {
     });
     return !bg.alive;
 }
+/**
+ * Terminate the alive, non-persistent processes owned by a session, gracefully.
+ * Routes through the shared killProcessTree ladder (SIGTERM → grace → SIGKILL)
+ * via terminateProcess, with a short grace (default 300ms) so cleanup between
+ * units stays snappy; killProcessTree handles the SIGKILL escalation itself, so
+ * there is no separate force-kill pass here.
+ */
 export async function cleanupSessionProcesses(sessionFile, options) {
     const graceMs = Math.max(0, options?.graceMs ?? 300);
     const matches = Array.from(processes.values()).filter((bg) => bg.alive && !bg.persistAcrossSessions && bg.ownerSessionFile === sessionFile);
     if (matches.length === 0)
         return [];
     for (const bg of matches) {
-        killProcess(bg.id, "SIGTERM");
+        terminateProcess(bg.id, graceMs);
     }
     if (graceMs > 0) {
-        await Promise.all(matches.map((bg) => waitForProcessExit(bg, graceMs)));
-    }
-    for (const bg of matches) {
-        if (bg.alive)
-            killProcess(bg.id, "SIGKILL");
+        // Wait past the grace so the SIGKILL escalation has fired and exits are observed.
+        await Promise.all(matches.map((bg) => waitForProcessExit(bg, graceMs + 200)));
     }
     return matches.map((bg) => bg.id);
 }

package/dist/resources/extensions/bg-shell/readiness-detector.js

@@ -72,6 +72,17 @@ export async function waitForReady(bg, timeout, signal) {
             return { ready: false, detail: "Cancelled" };
         }
         if (!bg.alive) {
+            // A clean exit-0 means the command ran to completion — it was a batch
+            // command (e.g. terraform apply, a migration, a build), not a long-lived
+            // server. That is success, not a readiness failure; say so plainly and
+            // point at the right tool so the agent stops using wait_for_ready here.
+            if (bg.exitCode === 0) {
+                return {
+                    ready: false,
+                    detail: "Process completed (exit 0) before signaling readiness — it ran to completion rather than staying alive. " +
+                        "wait_for_ready is for long-lived servers/watchers; for a run-to-completion command use async_bash (or bg_shell 'run').",
+                };
+            }
             const stderrLines = bg.output.filter(l => l.stream === "stderr").slice(-5).map(l => l.line);
             const stderrContext = stderrLines.length > 0 ? `\nstderr:\n${stderrLines.join("\n").slice(0, 500)}` : "";
             return {

package/dist/resources/extensions/bg-shell/utilities.js

@@ -37,6 +37,9 @@ export const formatUptime = formatDuration;
 export function formatTimeAgo(timestamp) {
     return formatDuration(Date.now() - timestamp) + " ago";
 }
+// NOTE: these worktree-layout regexes mirror findWorktreeSegment in
+// src/resources/extensions/gsd/worktree-root.ts (bg-shell does not import the
+// gsd extension). Keep them synchronized when a layout changes.
 function deriveProjectRootFromAutoWorktree(cachedCwd) {
     if (!cachedCwd)
         return undefined;

package/dist/resources/extensions/browser-tools/engine/managed-gsd-browser.js

@@ -1,12 +1,14 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { Type } from "@sinclair/typebox";
+import { BROWSER_CONTRACT_TOOL_NAMES } from "../../shared/browser-contract.js";
 import { resolveGsdBrowserMcpLaunchConfig } from "../../shared/gsd-browser-cli.js";
 import { buildMcpChildEnv } from "../../mcp-client/manager.js";
 const connections = new Map();
 const pendingConnections = new Map();
 const DEFAULT_MAX_LINES = 2_000;
 const DEFAULT_MAX_BYTES = 50 * 1024;
+const MCP_CALL_TIMEOUT_MS = 60_000;
 const AssertionCheck = Type.Object({
     kind: Type.String({ description: "Assertion kind, e.g. url_contains, text_visible, selector_visible, no_console_errors, no_failed_requests." }),
     selector: Type.Optional(Type.String()),
@@ -30,29 +32,15 @@ const BatchStep = Type.Object({
     ref: Type.Optional(Type.String()),
     checks: Type.Optional(Type.Array(AssertionCheck)),
 }, { additionalProperties: true });
-export const MANAGED_GSD_BROWSER_TOOL_NAMES = [
-    "browser_navigate",
-    "browser_click",
-    "browser_type",
-    "browser_fill_form",
-    "browser_click_ref",
-    "browser_fill_ref",
-    "browser_wait_for",
-    "browser_assert",
-    "browser_verify",
-    "browser_screenshot",
-    "browser_snapshot_refs",
-    "browser_find",
-    "browser_get_console_logs",
-    "browser_get_network_logs",
-    "browser_evaluate",
-    "browser_reload",
-    "browser_batch",
-    "browser_act",
-];
-const MANAGED_BROWSER_TOOLS = [
-    {
-        name: "browser_navigate",
+/**
+ * The managed adapter serves exactly the Browser Automation Contract
+ * vocabulary. The spec table below is keyed by contract name, so adding a
+ * contract capability fails typecheck here until the adapter declares how the
+ * gsd-browser server satisfies it.
+ */
+export const MANAGED_GSD_BROWSER_TOOL_NAMES = BROWSER_CONTRACT_TOOL_NAMES;
+export const MANAGED_BROWSER_TOOL_SPECS = {
+    browser_navigate: {
         label: "Browser Navigate",
         description: "Navigate the managed gsd-browser session to a URL and return page state. Use for local web app verification and UAT evidence.",
         parameters: Type.Object({
@@ -60,8 +48,14 @@ const MANAGED_BROWSER_TOOLS = [
             screenshot: Type.Optional(Type.Boolean({ description: "Capture screenshot evidence when supported." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_click",
+    browser_click: {
+        translate: {
+            requires: ["browser_batch"],
+            build: (args) => [{
+                    mcpTool: "browser_batch",
+                    args: { steps: [{ action: "click", ...args }] },
+                }],
+        },
         label: "Browser Click",
         description: "Click an element in the managed gsd-browser session by selector or coordinates.",
         parameters: Type.Object({
@@ -70,8 +64,14 @@ const MANAGED_BROWSER_TOOLS = [
             y: Type.Optional(Type.Number({ description: "Y coordinate to click." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_type",
+    browser_type: {
+        translate: {
+            requires: ["browser_batch"],
+            build: (args) => [{
+                    mcpTool: "browser_batch",
+                    args: { steps: [{ action: "type", ...args }] },
+                }],
+        },
         label: "Browser Type",
         description: "Type or fill text into an input in the managed gsd-browser session.",
         parameters: Type.Object({
@@ -82,8 +82,7 @@ const MANAGED_BROWSER_TOOLS = [
             slowly: Type.Optional(Type.Boolean({ description: "Type character by character." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_fill_form",
+    browser_fill_form: {
         label: "Browser Fill Form",
         description: "Fill a form in the managed gsd-browser session using field labels, names, placeholders, or aria labels.",
         parameters: Type.Object({
@@ -92,16 +91,14 @@ const MANAGED_BROWSER_TOOLS = [
             submit: Type.Optional(Type.Boolean({ description: "Submit the form after filling." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_click_ref",
+    browser_click_ref: {
         label: "Browser Click Ref",
         description: "Click a versioned ref from the latest gsd-browser snapshot.",
         parameters: Type.Object({
             ref: Type.String({ description: "Versioned ref, e.g. @v3:e2." }),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_fill_ref",
+    browser_fill_ref: {
         label: "Browser Fill Ref",
         description: "Fill text into an input-like versioned ref from the latest gsd-browser snapshot.",
         parameters: Type.Object({
@@ -112,8 +109,7 @@ const MANAGED_BROWSER_TOOLS = [
             slowly: Type.Optional(Type.Boolean({ description: "Type character by character." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_wait_for",
+    browser_wait_for: {
         label: "Browser Wait For",
         description: "Wait for a browser condition such as network idle, selector visibility, text visibility, or URL change.",
         parameters: Type.Object({
@@ -123,8 +119,7 @@ const MANAGED_BROWSER_TOOLS = [
             timeout: Type.Optional(Type.Number({ description: "Maximum milliseconds to wait." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_assert",
+    browser_assert: {
         label: "Browser Assert",
         description: "Run explicit browser assertions and return structured PASS/FAIL evidence.",
         promptGuidelines: [
@@ -135,8 +130,40 @@ const MANAGED_BROWSER_TOOLS = [
             checks: Type.Array(AssertionCheck),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_verify",
+    browser_verify: {
+        translate: {
+            requires: ["browser_navigate", "browser_assert", "browser_screenshot"],
+            build: (args) => {
+                const calls = [
+                    {
+                        mcpTool: "browser_navigate",
+                        args: { url: args.url, ...(args.timeout === undefined ? {} : { timeout: args.timeout }) },
+                    },
+                ];
+                const verifyChecks = Array.isArray(args.checks) ? args.checks : [];
+                const assertChecks = [];
+                for (const check of verifyChecks) {
+                    if (typeof check.expectedText === "string") {
+                        assertChecks.push({ kind: "text_visible", text: check.expectedText });
+                    }
+                    if (typeof check.selector === "string") {
+                        if (check.expectedVisible === false) {
+                            assertChecks.push({ kind: "selector_hidden", selector: check.selector });
+                        }
+                        else if (check.expectedVisible === true || check.expectedText === undefined) {
+                            assertChecks.push({ kind: "selector_visible", selector: check.selector });
+                        }
+                    }
+                }
+                if (assertChecks.length > 0) {
+                    calls.push({ mcpTool: "browser_assert", args: { checks: assertChecks } });
+                }
+                if (verifyChecks.some((check) => check.screenshot === true)) {
+                    calls.push({ mcpTool: "browser_screenshot", args: {}, optional: true });
+                }
+                return calls;
+            },
+        },
         label: "Browser Verify",
         description: "Run a structured browser verification flow and return evidence from the managed gsd-browser session.",
         parameters: Type.Object({
@@ -151,8 +178,7 @@ const MANAGED_BROWSER_TOOLS = [
             timeout: Type.Optional(Type.Number({ description: "Navigation timeout in milliseconds." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_screenshot",
+    browser_screenshot: {
         label: "Browser Screenshot",
         description: "Capture browser screenshot evidence from the managed gsd-browser session.",
         compatibility: { producesImages: true },
@@ -162,8 +188,7 @@ const MANAGED_BROWSER_TOOLS = [
             quality: Type.Optional(Type.Number({ description: "JPEG quality when supported." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_snapshot_refs",
+    browser_snapshot_refs: {
         mcpTools: ["browser_snapshot", "browser_snapshot_refs"],
         label: "Browser Snapshot Refs",
         description: "Capture a compact gsd-browser snapshot with versioned refs for reliable interaction.",
@@ -174,8 +199,7 @@ const MANAGED_BROWSER_TOOLS = [
             mode: Type.Optional(Type.String({ description: "Snapshot mode: interactive, form, dialog, navigation, errors, headings, visible_only." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_find",
+    browser_find: {
         mcpTools: ["browser_find_element", "browser_find"],
         label: "Browser Find",
         description: "Find elements by text, role, or selector in the managed gsd-browser session.",
@@ -186,8 +210,7 @@ const MANAGED_BROWSER_TOOLS = [
             limit: Type.Optional(Type.Number({ description: "Maximum results to return." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_get_console_logs",
+    browser_get_console_logs: {
         mcpTools: ["browser_console", "browser_get_console_logs"],
         label: "Browser Console Logs",
         description: "Return buffered console logs and JavaScript errors from the managed gsd-browser session.",
@@ -195,8 +218,7 @@ const MANAGED_BROWSER_TOOLS = [
             clear: Type.Optional(Type.Boolean({ description: "Clear the buffer after reading logs." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_get_network_logs",
+    browser_get_network_logs: {
         mcpTools: ["browser_network", "browser_get_network_logs"],
         label: "Browser Network Logs",
         description: "Return buffered network requests and responses from the managed gsd-browser session.",
@@ -205,8 +227,7 @@ const MANAGED_BROWSER_TOOLS = [
             filter: Type.Optional(Type.String({ description: "Filter, e.g. all, errors, fetch-xhr." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_evaluate",
+    browser_evaluate: {
         mcpTools: ["browser_eval", "browser_evaluate"],
         label: "Browser Evaluate",
         description: "Evaluate a JavaScript expression in the managed gsd-browser page context.",
@@ -214,14 +235,22 @@ const MANAGED_BROWSER_TOOLS = [
             expression: Type.String({ description: "JavaScript expression to evaluate." }),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_reload",
+    browser_reload: {
+        // gsd-browser's daemon has a reload command but does not expose it over
+        // MCP, so reload rides browser_evaluate. The network-idle settle is
+        // best-effort: pages with persistent connections never go idle.
+        translate: {
+            requires: ["browser_evaluate", "browser_wait_for"],
+            build: () => [
+                { mcpTool: "browser_evaluate", args: { expression: "location.reload()" } },
+                { mcpTool: "browser_wait_for", args: { condition: "network_idle", timeout: 3_000 }, optional: true },
+            ],
+        },
         label: "Browser Reload",
         description: "Reload the current page in the managed gsd-browser session.",
         parameters: Type.Object({}, { additionalProperties: true }),
     },
-    {
-        name: "browser_batch",
+    browser_batch: {
         label: "Browser Batch",
         description: "Execute multiple explicit browser steps through the managed gsd-browser session in one call.",
         promptGuidelines: [
@@ -234,8 +263,7 @@ const MANAGED_BROWSER_TOOLS = [
             finalSummaryOnly: Type.Optional(Type.Boolean({ description: "Return only the compact final summary." })),
         }, { additionalProperties: true }),
     },
-    {
-        name: "browser_act",
+    browser_act: {
         label: "Browser Act",
         description: "Execute a semantic browser action through gsd-browser, such as primary_cta, submit_form, or close_dialog.",
         parameters: Type.Object({
@@ -243,7 +271,7 @@ const MANAGED_BROWSER_TOOLS = [
             scope: Type.Optional(Type.String({ description: "CSS selector to narrow the search area." })),
         }, { additionalProperties: true }),
     },
-];
+};
 function resolveProjectRoot(ctx) {
     return ctx?.cwd || process.cwd();
 }
@@ -324,11 +352,27 @@ function isUnknownMcpToolError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return /unknown tool|tool .*not found|tool not found|not registered|does not exist/i.test(message);
 }
-function normalizeManagedArgs(piToolName, args) {
+function normalizeBatchStep(step) {
+    if (!step || typeof step !== "object")
+        return step;
+    const { clearFirst, ...rest } = step;
+    return clearFirst === undefined ? step : { ...rest, clear_first: clearFirst };
+}
+export function normalizeManagedArgs(piToolName, args) {
     if (piToolName === "browser_snapshot_refs") {
         const { interactiveOnly: _interactiveOnly, ...snapshotArgs } = args;
         return snapshotArgs;
     }
+    if (piToolName === "browser_batch") {
+        // gsd-browser's MCP batch tool reads snake_case option and step keys.
+        const { stopOnFailure, finalSummaryOnly, steps, ...rest } = args;
+        return {
+            ...rest,
+            ...(Array.isArray(steps) ? { steps: steps.map(normalizeBatchStep) } : {}),
+            ...(stopOnFailure === undefined ? {} : { stop_on_failure: stopOnFailure }),
+            ...(finalSummaryOnly === undefined ? {} : { summary_only: finalSummaryOnly }),
+        };
+    }
     return args;
 }
 function serializeMcpContent(contentItems) {
@@ -395,32 +439,70 @@ function truncateHeadText(text, options) {
         totalBytes,
     };
 }
-async function callManagedGsdBrowserTool(piToolName, mcpTools, args, options) {
+function callGsdBrowserMcp(connection, mcpTool, args, signal) {
+    return connection.client.callTool({ name: mcpTool, arguments: args }, undefined, { signal, timeout: MCP_CALL_TIMEOUT_MS });
+}
+function buildManagedToolResult(connection, piToolName, mcpToolsUsed, contentItems, lastResult) {
+    const serialized = serializeMcpContent(contentItems);
+    return {
+        content: serialized.content,
+        details: {
+            engine: "gsd-browser",
+            server: connection.launch.serverName,
+            tool: piToolName,
+            mcpTool: mcpToolsUsed[mcpToolsUsed.length - 1] ?? piToolName,
+            ...(mcpToolsUsed.length > 1 ? { mcpTools: mcpToolsUsed } : {}),
+            sessionName: connection.launch.sessionName,
+            projectRoot: connection.launch.projectRoot,
+            truncated: serialized.truncated,
+            outputLines: serialized.outputLines,
+            outputBytes: serialized.outputBytes,
+            structuredContent: lastResult.structuredContent,
+            mcpIsError: Boolean(lastResult.isError),
+        },
+        isError: Boolean(lastResult.isError),
+    };
+}
+async function callTranslatedGsdBrowserTool(connection, piToolName, translation, args, options) {
+    const calls = translation.build(args);
+    const contentItems = [];
+    const toolsUsed = [];
+    let lastResult = {};
+    for (const call of calls) {
+        let result;
+        try {
+            result = await callGsdBrowserMcp(connection, call.mcpTool, normalizeManagedArgs(call.mcpTool, call.args), options.signal);
+        }
+        catch (error) {
+            if (call.optional)
+                continue;
+            throw error;
+        }
+        if (call.optional && result.isError)
+            continue;
+        toolsUsed.push(call.mcpTool);
+        if (Array.isArray(result.content))
+            contentItems.push(...result.content);
+        lastResult = result;
+        // Later calls assume the earlier ones took effect (e.g. assert after a
+        // failed navigation would report misleading evidence), so stop here.
+        if (lastResult.isError)
+            break;
+    }
+    return buildManagedToolResult(connection, piToolName, toolsUsed, contentItems, lastResult);
+}
+async function callManagedGsdBrowserTool(piToolName, spec, args, options) {
     const connection = await getOrConnectManagedGsdBrowser(options.ctx, options.signal);
     const normalizedArgs = normalizeManagedArgs(piToolName, args);
+    if (spec.translate) {
+        return callTranslatedGsdBrowserTool(connection, piToolName, spec.translate, normalizedArgs, options);
+    }
     let lastError;
-    for (const mcpTool of mcpTools) {
+    for (const mcpTool of spec.mcpTools ?? [piToolName]) {
         try {
-            const result = await connection.client.callTool({ name: mcpTool, arguments: normalizedArgs }, undefined, { signal: options.signal, timeout: 60000 });
+            const result = await callGsdBrowserMcp(connection, mcpTool, normalizedArgs, options.signal);
             const contentItems = Array.isArray(result.content) ? result.content : [];
-            const serialized = serializeMcpContent(contentItems);
-            return {
-                content: serialized.content,
-                details: {
-                    engine: "gsd-browser",
-                    server: connection.launch.serverName,
-                    tool: piToolName,
-                    mcpTool,
-                    sessionName: connection.launch.sessionName,
-                    projectRoot: connection.launch.projectRoot,
-                    truncated: serialized.truncated,
-                    outputLines: serialized.outputLines,
-                    outputBytes: serialized.outputBytes,
-                    structuredContent: result.structuredContent,
-                    mcpIsError: Boolean(result.isError),
-                },
-                isError: Boolean(result.isError),
-            };
+            return buildManagedToolResult(connection, piToolName, [mcpTool], contentItems, result);
         }
         catch (error) {
             lastError = error;
@@ -440,6 +522,43 @@ function formatManagedBrowserError(toolName, error) {
         "Unset GSD_BROWSER_ENGINE or set GSD_BROWSER_ENGINE=playwright to use the default Playwright engine.",
     ].join("\n");
 }
+/**
+ * Contract tools the server's advertised tool list cannot satisfy through any
+ * of their declared MCP candidates or translations.
+ */
+export function findMissingContractCoverage(servedToolNames) {
+    const served = new Set(servedToolNames);
+    return BROWSER_CONTRACT_TOOL_NAMES.filter((name) => {
+        const spec = MANAGED_BROWSER_TOOL_SPECS[name];
+        if (spec.translate) {
+            return !spec.translate.requires.every((required) => served.has(required));
+        }
+        const candidates = spec.mcpTools ?? [name];
+        return !candidates.some((candidate) => served.has(candidate));
+    });
+}
+/**
+ * Compare the server's advertised tool list against the Browser Automation
+ * Contract so a server that stops serving a contract tool surfaces at warm-up
+ * instead of as a first-use error. Best-effort: a failed or empty listing
+ * returns no warning (call-time alias fallback still applies).
+ */
+async function verifyContractCoverage(connection, signal) {
+    let served;
+    try {
+        const result = await connection.client.listTools(undefined, { signal, timeout: 10000 });
+        served = (result.tools ?? []).map((tool) => tool.name);
+    }
+    catch {
+        return undefined;
+    }
+    if (served.length === 0)
+        return undefined;
+    const missing = findMissingContractCoverage(served);
+    if (missing.length === 0)
+        return undefined;
+    return `gsd-browser does not serve ${missing.length} Browser Automation Contract tool(s): ${missing.join(", ")}. These will error on first use; update gsd-browser or check GSD_BROWSER_* overrides.`;
+}
 /**
  * Eagerly establish the managed gsd-browser connection so browser tools are
  * ready before first use. Best-effort: returns the error instead of throwing so
@@ -449,17 +568,19 @@ function formatManagedBrowserError(toolName, error) {
  */
 export async function warmUpManagedGsdBrowser(ctx, signal) {
     try {
-        await getOrConnectManagedGsdBrowser(ctx, signal);
-        return { ok: true };
+        const connection = await getOrConnectManagedGsdBrowser(ctx, signal);
+        const coverageWarning = await verifyContractCoverage(connection, signal);
+        return coverageWarning ? { ok: true, coverageWarning } : { ok: true };
     }
     catch (error) {
         return { ok: false, error: error instanceof Error ? error.message : String(error) };
     }
 }
 export function registerManagedGsdBrowserTools(pi) {
-    for (const tool of MANAGED_BROWSER_TOOLS) {
+    for (const name of BROWSER_CONTRACT_TOOL_NAMES) {
+        const tool = MANAGED_BROWSER_TOOL_SPECS[name];
         pi.registerTool({
-            name: tool.name,
+            name,
             label: tool.label,
             description: tool.description,
             ...(tool.promptGuidelines ? { promptGuidelines: tool.promptGuidelines } : {}),
@@ -467,17 +588,17 @@ export function registerManagedGsdBrowserTools(pi) {
             parameters: tool.parameters,
             async execute(_toolCallId, params, signal, _onUpdate, ctx) {
                 try {
-                    return await callManagedGsdBrowserTool(tool.name, tool.mcpTools ?? [tool.name], params, { signal, ctx });
+                    return await callManagedGsdBrowserTool(name, tool, params, { signal, ctx });
                 }
                 catch (error) {
-                    const message = formatManagedBrowserError(tool.name, error);
+                    const message = formatManagedBrowserError(name, error);
                     return {
                         content: [{ type: "text", text: message }],
                         details: {
                             engine: "gsd-browser",
                             server: "gsd-browser",
-                            tool: tool.name,
-                            mcpTool: tool.mcpTools?.[0] ?? tool.name,
+                            tool: name,
+                            mcpTool: tool.translate?.requires[0] ?? tool.mcpTools?.[0] ?? name,
                             error: error instanceof Error ? error.message : String(error),
                         },
                         isError: true,