@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.65546769

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

@@ -37,10 +37,13 @@ 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;
-    const match = cachedCwd.match(/^(.*?)[\\/]\.gsd[\\/]worktrees[\\/][^\\/]+(?:[\\/].*)?$/);
+    const match = cachedCwd.match(/^(.*?)[\\/]\.gsd(?:-worktrees|[\\/]worktrees)[\\/][^\\/]+(?:[\\/].*)?$/);
     return match?.[1];
 }
 export function getBgShellLiveCwd(cachedCwd, pathExists = existsSync, getCwd = () => process.cwd(), chdir = (path) => process.chdir(path)) {
@@ -67,7 +70,7 @@ export function getBgShellLiveCwd(cachedCwd, pathExists = existsSync, getCwd = (
 }
 export function resolveBgShellPersistenceCwd(cachedCwd, liveCwd = undefined, pathExists = existsSync) {
     const resolvedLiveCwd = liveCwd ?? getBgShellLiveCwd(cachedCwd, pathExists);
-    const cachedIsAutoWorktree = /(?:^|[\\/])\.gsd[\\/]worktrees[\\/]/.test(cachedCwd);
+    const cachedIsAutoWorktree = /(?:^|[\\/])\.gsd(?:-worktrees|[\\/]worktrees)[\\/]/.test(cachedCwd);
     if (!cachedIsAutoWorktree)
         return cachedCwd;
     if (cachedCwd === resolvedLiveCwd && pathExists(cachedCwd))

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,

package/dist/resources/extensions/browser-tools/engine/selection.js

@@ -1,8 +1,26 @@
-const DEFAULT_BROWSER_ENGINE = "legacy";
-export function resolveBrowserEngineMode(env = process.env) {
-    const raw = env.GSD_BROWSER_ENGINE?.trim();
-    if (!raw)
-        return DEFAULT_BROWSER_ENGINE;
+/**
+ * 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";
+const committedResolutionByProjectRoot = new Map();
+function parseExplicitEngineMode(raw) {
     const normalized = raw.toLowerCase();
     if (normalized === "gsd-browser" || normalized === "gsd_browser" || normalized === "gsdbrowser") {
         return "gsd-browser";
@@ -14,3 +32,53 @@ export function resolveBrowserEngineMode(env = 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, projectRoot) {
+    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) {
+    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, resolution) {
+    committedResolutionByProjectRoot.set(path.resolve(projectRoot), resolution);
+}