@opengsd/gsd-pi 1.2.0-dev.b1abb545 → 1.2.0-dev.e8563f58

package/src/resources/extensions/browser-tools/engine/managed-gsd-browser.ts

@@ -3,6 +3,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { Type, type TSchema } from "@sinclair/typebox";
 
+import { BROWSER_CONTRACT_TOOL_NAMES, type BrowserContractToolName } from "../../shared/browser-contract.js";
 import { resolveGsdBrowserMcpLaunchConfig, type GsdBrowserMcpLaunchConfig } from "../../shared/gsd-browser-cli.js";
 import { buildMcpChildEnv } from "../../mcp-client/manager.js";
 
@@ -13,6 +14,8 @@ interface ManagedBrowserToolDetails {
   server: string;
   tool: string;
   mcpTool: string;
+  /** All MCP tools invoked, in order, when a translation made multiple calls. */
+  mcpTools?: string[];
   sessionName?: string;
   projectRoot?: string;
   truncated?: boolean;
@@ -37,9 +40,28 @@ interface McpContentItem {
   [key: string]: unknown;
 }
 
+interface ManagedTranslatedCall {
+  mcpTool: string;
+  args: Record<string, unknown>;
+  /** Best-effort call: a failure adds no evidence but does not fail the tool. */
+  optional?: boolean;
+}
+
+interface ManagedToolTranslation {
+  /** Every MCP tool build() can emit; all must be served for contract coverage. */
+  requires: readonly string[];
+  /** Expand the Pi contract args into one or more sequential gsd-browser MCP calls. */
+  build(args: Record<string, unknown>): ManagedTranslatedCall[];
+}
+
 interface ManagedBrowserToolSpec {
-  name: string;
+  /** gsd-browser MCP tool candidates, tried in order. Defaults to the contract name itself. */
   mcpTools?: string[];
+  /**
+   * Param-shape translation for contract tools gsd-browser does not serve
+   * under any name. Takes precedence over mcpTools/name-based dispatch.
+   */
+  translate?: ManagedToolTranslation;
   label: string;
   description: string;
   parameters: TSchema;
@@ -51,6 +73,7 @@ const connections = new Map<string, ManagedConnection>();
 const pendingConnections = new Map<string, Promise<ManagedConnection>>();
 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." }),
@@ -77,30 +100,16 @@ const BatchStep = Type.Object({
   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",
-] as const;
-
-const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
-  {
-    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: Record<BrowserContractToolName, ManagedBrowserToolSpec> = {
+  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({
@@ -108,8 +117,14 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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({
@@ -118,8 +133,14 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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({
@@ -130,8 +151,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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({
@@ -140,16 +160,14 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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({
@@ -160,8 +178,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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({
@@ -171,8 +188,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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: [
@@ -183,8 +199,39 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       checks: Type.Array(AssertionCheck),
     }, { additionalProperties: true }),
   },
-  {
-    name: "browser_verify",
+  browser_verify: {
+    translate: {
+      requires: ["browser_navigate", "browser_assert", "browser_screenshot"],
+      build: (args) => {
+        const calls: ManagedTranslatedCall[] = [
+          {
+            mcpTool: "browser_navigate",
+            args: { url: args.url, ...(args.timeout === undefined ? {} : { timeout: args.timeout }) },
+          },
+        ];
+        const verifyChecks = Array.isArray(args.checks) ? args.checks as Array<Record<string, unknown>> : [];
+        const assertChecks: Array<Record<string, unknown>> = [];
+        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({
@@ -199,8 +246,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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 },
@@ -210,8 +256,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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.",
@@ -222,8 +267,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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.",
@@ -234,8 +278,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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.",
@@ -243,8 +286,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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.",
@@ -253,8 +295,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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.",
@@ -262,14 +303,22 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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: [
@@ -282,8 +331,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       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({
@@ -291,7 +339,7 @@ const MANAGED_BROWSER_TOOLS: ManagedBrowserToolSpec[] = [
       scope: Type.Optional(Type.String({ description: "CSS selector to narrow the search area." })),
     }, { additionalProperties: true }),
   },
-];
+};
 
 function resolveProjectRoot(ctx?: ExtensionContext): string {
   return ctx?.cwd || process.cwd();
@@ -381,11 +429,27 @@ function isUnknownMcpToolError(error: unknown): boolean {
   return /unknown tool|tool .*not found|tool not found|not registered|does not exist/i.test(message);
 }
 
-function normalizeManagedArgs(piToolName: string, args: Record<string, unknown>): Record<string, unknown> {
+function normalizeBatchStep(step: unknown): unknown {
+  if (!step || typeof step !== "object") return step;
+  const { clearFirst, ...rest } = step as Record<string, unknown>;
+  return clearFirst === undefined ? step : { ...rest, clear_first: clearFirst };
+}
+
+export function normalizeManagedArgs(piToolName: string, args: Record<string, unknown>): Record<string, unknown> {
   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;
 }
 
@@ -463,43 +527,104 @@ function truncateHeadText(
   };
 }
 
+type McpToolCallResult = {
+  content?: unknown;
+  structuredContent?: unknown;
+  isError?: boolean;
+};
+
+function callGsdBrowserMcp(
+  connection: ManagedConnection,
+  mcpTool: string,
+  args: Record<string, unknown>,
+  signal?: AbortSignal,
+): Promise<McpToolCallResult> {
+  return connection.client.callTool(
+    { name: mcpTool, arguments: args },
+    undefined,
+    { signal, timeout: MCP_CALL_TIMEOUT_MS },
+  ) as Promise<McpToolCallResult>;
+}
+
+function buildManagedToolResult(
+  connection: ManagedConnection,
+  piToolName: string,
+  mcpToolsUsed: string[],
+  contentItems: McpContentItem[],
+  lastResult: McpToolCallResult,
+): ManagedBrowserToolResult {
+  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: ManagedConnection,
+  piToolName: string,
+  translation: ManagedToolTranslation,
+  args: Record<string, unknown>,
+  options: { signal?: AbortSignal },
+): Promise<ManagedBrowserToolResult> {
+  const calls = translation.build(args);
+  const contentItems: McpContentItem[] = [];
+  const toolsUsed: string[] = [];
+  let lastResult: McpToolCallResult = {};
+
+  for (const call of calls) {
+    let result: McpToolCallResult;
+    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 as McpContentItem[]);
+    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: string,
-  mcpTools: string[],
+  spec: ManagedBrowserToolSpec,
   args: Record<string, unknown>,
   options: { signal?: AbortSignal; ctx?: ExtensionContext },
 ): Promise<ManagedBrowserToolResult> {
   const connection = await getOrConnectManagedGsdBrowser(options.ctx, options.signal);
   const normalizedArgs = normalizeManagedArgs(piToolName, args);
-  let lastError: unknown;
 
-  for (const mcpTool of mcpTools) {
+  if (spec.translate) {
+    return callTranslatedGsdBrowserTool(connection, piToolName, spec.translate, normalizedArgs, options);
+  }
+
+  let lastError: unknown;
+  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 as McpContentItem[] : [];
-      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 as { structuredContent?: unknown }).structuredContent,
-          mcpIsError: Boolean((result as { isError?: boolean }).isError),
-        },
-        isError: Boolean((result as { isError?: boolean }).isError),
-      };
+      return buildManagedToolResult(connection, piToolName, [mcpTool], contentItems, result);
     } catch (error) {
       lastError = error;
       if (!isUnknownMcpToolError(error)) break;
@@ -520,6 +645,46 @@ function formatManagedBrowserError(toolName: string, error: unknown): string {
   ].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: Iterable<string>): BrowserContractToolName[] {
+  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: ManagedConnection,
+  signal?: AbortSignal,
+): Promise<string | undefined> {
+  let served: string[];
+  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
@@ -530,19 +695,21 @@ function formatManagedBrowserError(toolName: string, error: unknown): string {
 export async function warmUpManagedGsdBrowser(
   ctx?: ExtensionContext,
   signal?: AbortSignal,
-): Promise<{ ok: true } | { ok: false; error: string }> {
+): Promise<{ ok: true; coverageWarning?: string } | { ok: false; error: string }> {
   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: ExtensionAPI): void {
-  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 } : {}),
@@ -551,20 +718,20 @@ export function registerManagedGsdBrowserTools(pi: ExtensionAPI): void {
       async execute(_toolCallId, params, signal, _onUpdate, ctx) {
         try {
           return await callManagedGsdBrowserTool(
-            tool.name,
-            tool.mcpTools ?? [tool.name],
+            name,
+            tool,
             params as Record<string, unknown>,
             { 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,

package/src/resources/extensions/browser-tools/engine/selection.ts

@@ -1,11 +1,38 @@
+/**
+ * Browser Automation Engine resolution (ADR-037).
+ *
+ * The engine choice behind the canonical `browser_*` tools is a runtime
+ * decision with a recorded reason, not a static default:
+ *   - An explicit `GSD_BROWSER_ENGINE` override is honored verbatim.
+ *   - Otherwise, browser-facing projects prefer the managed gsd-browser engine
+ *     when the availability probe can prove a CLI exists, and fall back to
+ *     legacy Playwright with the failure reason recorded.
+ *   - Non-browser-facing projects keep legacy Playwright (browser tools are
+ *     incidental there; the managed daemon is not worth its startup risk).
+ *
+ * This module owns the committed resolution, not just the prediction: when
+ * registration verifies a probe-resolved managed engine (daemon connect) and
+ * falls back, the outcome is committed here so every ambient reader — UAT
+ * guidance, re-warm-up, later sessions in the same process — sees the engine
+ * the session actually registered.
+ */
+import path from "node:path";
+
+import { resolveGsdBrowserCliAvailability } from "../../shared/gsd-browser-cli.js";
+import { detectWebApp } from "../web-app-detect.js";
+
 export type BrowserEngineMode = "gsd-browser" | "legacy" | "off";
 
-const DEFAULT_BROWSER_ENGINE: BrowserEngineMode = "legacy";
+export interface BrowserEngineResolution {
+  engine: BrowserEngineMode;
+  /** "env" = explicit GSD_BROWSER_ENGINE override; "probe" = default path decided by availability. */
+  source: "env" | "probe";
+  reason: string;
+}
 
-export function resolveBrowserEngineMode(env: NodeJS.ProcessEnv = process.env): BrowserEngineMode {
-  const raw = env.GSD_BROWSER_ENGINE?.trim();
-  if (!raw) return DEFAULT_BROWSER_ENGINE;
+const committedResolutionByProjectRoot = new Map<string, BrowserEngineResolution>();
 
+function parseExplicitEngineMode(raw: string): BrowserEngineMode {
   const normalized = raw.toLowerCase();
   if (normalized === "gsd-browser" || normalized === "gsd_browser" || normalized === "gsdbrowser") {
     return "gsd-browser";
@@ -17,3 +44,62 @@ export function resolveBrowserEngineMode(env: NodeJS.ProcessEnv = process.env):
 
   throw new Error(`Invalid GSD_BROWSER_ENGINE="${raw}". Expected "gsd-browser", "legacy", or "off".`);
 }
+
+/** Pure resolution from explicit inputs. Never cached; probes on every call. */
+export function resolveBrowserEngineResolution(
+  env: NodeJS.ProcessEnv,
+  projectRoot?: string,
+): BrowserEngineResolution {
+  const raw = env.GSD_BROWSER_ENGINE?.trim();
+  if (raw) {
+    return { engine: parseExplicitEngineMode(raw), source: "env", reason: `GSD_BROWSER_ENGINE=${raw}` };
+  }
+
+  if (!projectRoot) {
+    return { engine: "legacy", source: "probe", reason: "no project root to probe; using legacy Playwright" };
+  }
+
+  if (!detectWebApp(projectRoot)) {
+    return {
+      engine: "legacy",
+      source: "probe",
+      reason: "project is not browser-facing; using legacy Playwright",
+    };
+  }
+
+  const availability = resolveGsdBrowserCliAvailability(env);
+  return availability.available
+    ? {
+        engine: "gsd-browser",
+        source: "probe",
+        reason: `web app detected and managed gsd-browser engine available (${availability.detail})`,
+      }
+    : {
+        engine: "legacy",
+        source: "probe",
+        reason: `web app detected but gsd-browser unavailable (${availability.detail}); falling back to legacy Playwright`,
+      };
+}
+
+/**
+ * Session-facing resolution: the committed record for this project root, or
+ * the ambient probe result, cached as the initial commitment (the probe
+ * touches the filesystem and at worst one short subprocess).
+ */
+export function resolveAmbientBrowserEngineResolution(projectRoot: string): BrowserEngineResolution {
+  const key = path.resolve(projectRoot);
+  const committed = committedResolutionByProjectRoot.get(key);
+  if (committed) return committed;
+
+  const resolution = resolveBrowserEngineResolution(process.env, projectRoot);
+  committedResolutionByProjectRoot.set(key, resolution);
+  return resolution;
+}
+
+/**
+ * Record a verified outcome for this project root — e.g. the probe predicted
+ * gsd-browser but the daemon-connect gate fell back to legacy Playwright.
+ */
+export function commitBrowserEngineResolution(projectRoot: string, resolution: BrowserEngineResolution): void {
+  committedResolutionByProjectRoot.set(path.resolve(projectRoot), resolution);
+}