@opengsd/gsd-pi 1.2.0-dev.5457a158 → 1.2.0-dev.6ccd27b3

package/src/resources/extensions/browser-tools/index.ts

@@ -2,7 +2,7 @@
 import { importExtensionModule, type ExtensionAPI, type ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { closeManagedGsdBrowser, registerManagedGsdBrowserTools, warmUpManagedGsdBrowser } from "./engine/managed-gsd-browser.js";
-import { resolveBrowserEngineMode, type BrowserEngineMode } from "./engine/selection.js";
+import { commitBrowserEngineResolution, resolveAmbientBrowserEngineResolution, type BrowserEngineMode } from "./engine/selection.js";
 import { setArtifactRootForCwd } from "./state.js";
 import { detectWebApp } from "./web-app-detect.js";
 
@@ -167,13 +167,59 @@ function withBrowserArtifactCwdScope(pi: ExtensionAPI): ExtensionAPI {
   };
 }
 
-async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
-  const engine = resolveBrowserEngineMode();
+/** Daemon-connect budget when the probe-resolved managed engine is verified at session start. */
+const PROBE_WARMUP_TIMEOUT_MS = 10_000;
+
+async function registerBrowserTools(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  const projectRoot = ctx.cwd || process.cwd();
+  const resolution = resolveAmbientBrowserEngineResolution(projectRoot);
+  let engine = resolution.engine;
   if (engine === "off") return;
+
+  // A probe-resolved managed engine is only a prediction that gsd-browser
+  // works — prove it by connecting the daemon before committing the session's
+  // tool registrations to it. Connect failure falls back to legacy Playwright
+  // (the failure mode that made ADR-024 freeze the old default) and commits
+  // the outcome so ambient readers see the engine actually in use. When eager
+  // warm-up is disabled the daemon-connect proof cannot run, so the probe
+  // default treats the managed engine as unprovable and falls back to legacy
+  // rather than registering it unverified. An explicit
+  // GSD_BROWSER_ENGINE=gsd-browser override skips the gate and is honored
+  // verbatim, matching prior behavior.
+  if (engine === "gsd-browser" && resolution.source === "probe" && !registeredEngine) {
+    if (isWarmUpDisabled()) {
+      engine = commitLegacyFallback(projectRoot, "warm-up disabled; managed engine unverifiable; using legacy Playwright");
+    } else {
+      const warmUp = await warmUpManagedGsdBrowser(ctx, AbortSignal.timeout(PROBE_WARMUP_TIMEOUT_MS));
+      if (!warmUp.ok) {
+        engine = commitLegacyFallback(projectRoot, `gsd-browser daemon connect failed (${warmUp.error}); using legacy Playwright`);
+        if (ctx.hasUI) {
+          ctx.ui.notify(
+            `gsd-browser engine unavailable (${warmUp.error}); using Playwright browser tools for this session.`,
+            "warning",
+          );
+        }
+      } else if (warmUp.coverageWarning && ctx.hasUI) {
+        ctx.ui.notify(warmUp.coverageWarning, "warning");
+      }
+    }
+  }
+
+  // Browser tool registrations are process-global and cannot be swapped once
+  // live. When an earlier session in this process already registered an engine
+  // and this project resolved a different one (per-project probe resolution can
+  // diverge across projects in a multi-session process), adopt the registered
+  // engine rather than throwing — a throw surfaces as "browser-tools failed to
+  // load" and leaves this session with no browser tools at all. Commit the
+  // adoption so ambient readers (UAT guidance, warm-up) describe the engine
+  // actually in use.
   if (registeredEngine && registeredEngine !== engine) {
-    throw new Error(
-      `Browser tools already registered with GSD_BROWSER_ENGINE=${registeredEngine}. Restart GSD before switching to ${engine}.`,
-    );
+    engine = registeredEngine;
+    commitBrowserEngineResolution(projectRoot, {
+      engine,
+      source: "probe",
+      reason: `browser tools already registered with ${engine} earlier in this process; adopting it`,
+    });
   }
 
   let registration: Promise<void>;
@@ -202,29 +248,41 @@ async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
   }
 }
 
+function commitLegacyFallback(projectRoot: string, reason: string): "legacy" {
+  commitBrowserEngineResolution(projectRoot, { engine: "legacy", source: "probe", reason });
+  return "legacy";
+}
+
 function isWarmUpDisabled(): boolean {
   const value = process.env.GSD_BROWSER_WARMUP?.trim().toLowerCase();
   return value === "0" || value === "false" || value === "off";
 }
 
 /**
- * Auto-initialize the managed gsd-browser engine only when explicitly selected
- * for a web app. Best-effort and non-blocking: warm-up runs in the background
- * and only surfaces a warning if it fails.
+ * Auto-initialize the managed gsd-browser engine when it was selected via the
+ * explicit GSD_BROWSER_ENGINE override, which registers without the
+ * daemon-connect gate. Best-effort and non-blocking: warm-up runs in the
+ * background and only surfaces a warning if it fails. Probe-resolved sessions
+ * already connected (or fell back) during registration, so they are excluded
+ * to avoid re-warming and double-notifying.
  */
 function maybeWarmUpManagedEngine(pi: ExtensionAPI, ctx: ExtensionContext): void {
   if (isWarmUpDisabled()) return;
-  if (resolveBrowserEngineMode() !== "gsd-browser") return;
 
   const projectRoot = ctx.cwd || process.cwd();
+  const resolution = resolveAmbientBrowserEngineResolution(projectRoot);
+  if (resolution.engine !== "gsd-browser" || resolution.source !== "env") return;
   if (!detectWebApp(projectRoot)) return;
 
   void warmUpManagedGsdBrowser(ctx).then((result) => {
-    if (!result.ok && ctx.hasUI) {
+    if (!ctx.hasUI) return;
+    if (!result.ok) {
       ctx.ui.notify(
         `gsd-browser auto-init failed: ${result.error}. Browser UAT tools will retry on first use; run /gsd doctor if this persists.`,
         "warning",
       );
+    } else if (result.coverageWarning) {
+      ctx.ui.notify(result.coverageWarning, "warning");
     }
   });
 }
@@ -240,7 +298,7 @@ async function closeActiveBrowserEngines(): Promise<void> {
 export default function (pi: ExtensionAPI) {
   pi.on("session_start", async (_event, ctx) => {
     if (ctx.hasUI) {
-      void registerBrowserTools(pi)
+      void registerBrowserTools(pi, ctx)
         .then(() => maybeWarmUpManagedEngine(pi, ctx))
         .catch((error) => {
           ctx.ui.notify(`browser-tools failed to load: ${error instanceof Error ? error.message : String(error)}`, "warning");
@@ -248,7 +306,7 @@ export default function (pi: ExtensionAPI) {
       return;
     }
 
-    await registerBrowserTools(pi);
+    await registerBrowserTools(pi, ctx);
     maybeWarmUpManagedEngine(pi, ctx);
   });
 

package/src/resources/extensions/browser-tools/tests/browser-engine-selection.test.mjs

@@ -1,35 +1,105 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
 const jiti = require("jiti")(__dirname, { interopDefault: true, debug: false });
 
-const { resolveBrowserEngineMode } = jiti("../engine/selection.ts");
+const {
+  commitBrowserEngineResolution,
+  resolveAmbientBrowserEngineResolution,
+  resolveBrowserEngineResolution,
+} = jiti("../engine/selection.ts");
 
-describe("resolveBrowserEngineMode", () => {
-  it("defaults to the Playwright engine", () => {
-    assert.equal(resolveBrowserEngineMode({}), "legacy");
-  });
+function makeProject({ webApp }) {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-engine-selection-"));
+  const pkg = webApp ? { dependencies: { react: "^18.0.0" } } : { name: "cli-tool" };
+  writeFileSync(join(dir, "package.json"), JSON.stringify(pkg));
+  return dir;
+}
+
+function makeFakeCli() {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-fake-cli-"));
+  const cliPath = join(dir, "gsd-browser");
+  writeFileSync(cliPath, "#!/bin/sh\n");
+  return cliPath;
+}
 
-  it("accepts the explicit engine modes", () => {
-    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "gsd-browser" }), "gsd-browser");
-    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "legacy" }), "legacy");
-    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "off" }), "off");
+describe("resolveBrowserEngineResolution", () => {
+  it("honors the explicit engine modes verbatim with env source", () => {
+    assert.deepEqual(
+      ["gsd-browser", "legacy", "off"].map(
+        (mode) => resolveBrowserEngineResolution({ GSD_BROWSER_ENGINE: mode }).engine,
+      ),
+      ["gsd-browser", "legacy", "off"],
+    );
+    assert.equal(resolveBrowserEngineResolution({ GSD_BROWSER_ENGINE: "gsd-browser" }).source, "env");
   });
 
   it("accepts compatibility aliases", () => {
-    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "playwright" }), "legacy");
-    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "false" }), "off");
+    assert.equal(resolveBrowserEngineResolution({ GSD_BROWSER_ENGINE: "playwright" }).engine, "legacy");
+    assert.equal(resolveBrowserEngineResolution({ GSD_BROWSER_ENGINE: "false" }).engine, "off");
   });
 
   it("rejects unknown engine modes", () => {
     assert.throws(
-      () => resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "surprise" }),
+      () => resolveBrowserEngineResolution({ GSD_BROWSER_ENGINE: "surprise" }),
       /Expected "gsd-browser", "legacy", or "off"/,
     );
   });
+
+  it("defaults to legacy Playwright when no project root is known", () => {
+    const resolution = resolveBrowserEngineResolution({});
+    assert.equal(resolution.engine, "legacy");
+    assert.equal(resolution.source, "probe");
+  });
+
+  it("keeps legacy Playwright for non-browser-facing projects", () => {
+    const cliPath = makeFakeCli();
+    const resolution = resolveBrowserEngineResolution(
+      { GSD_BROWSER_CLI_PATH: cliPath },
+      makeProject({ webApp: false }),
+    );
+    assert.equal(resolution.engine, "legacy");
+    assert.match(resolution.reason, /not browser-facing/);
+  });
+
+  it("prefers the managed gsd-browser engine for web apps when the CLI is provable", () => {
+    const cliPath = makeFakeCli();
+    const resolution = resolveBrowserEngineResolution(
+      { GSD_BROWSER_CLI_PATH: cliPath },
+      makeProject({ webApp: true }),
+    );
+    assert.equal(resolution.engine, "gsd-browser");
+    assert.equal(resolution.source, "probe");
+    assert.match(resolution.reason, /web app detected/);
+  });
+
+  it("falls back to legacy Playwright with a recorded reason when the CLI is unavailable", () => {
+    const resolution = resolveBrowserEngineResolution(
+      { GSD_BROWSER_CLI_PATH: "/nonexistent/gsd-browser" },
+      makeProject({ webApp: true }),
+    );
+    assert.equal(resolution.engine, "legacy");
+    assert.equal(resolution.source, "probe");
+    assert.match(resolution.reason, /falling back to legacy Playwright/);
+  });
+});
+
+describe("committed resolution", () => {
+  it("ambient readers see a committed verification outcome instead of the prediction", () => {
+    const projectRoot = makeProject({ webApp: true });
+    const fallback = {
+      engine: "legacy",
+      source: "probe",
+      reason: "gsd-browser daemon connect failed (test); using legacy Playwright",
+    };
+    commitBrowserEngineResolution(projectRoot, fallback);
+    assert.deepEqual(resolveAmbientBrowserEngineResolution(projectRoot), fallback);
+  });
 });

package/src/resources/extensions/browser-tools/tests/gsd-browser-launch-config.test.mjs

@@ -1,7 +1,10 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 
-const { resolveGsdBrowserMcpLaunchConfig } = await import("../../shared/gsd-browser-cli.ts");
+const {
+  resolveGsdBrowserDaemonStartInvocation,
+  resolveGsdBrowserMcpLaunchConfig,
+} = await import("../../shared/gsd-browser-cli.ts");
 
 describe("resolveGsdBrowserMcpLaunchConfig identity flags", () => {
   it("emits a non-empty --identity-key alongside --identity-scope", () => {
@@ -34,4 +37,40 @@ describe("resolveGsdBrowserMcpLaunchConfig identity flags", () => {
     });
     assert.equal(args[args.indexOf("--identity-key") + 1], "custom-key");
   });
+
+  it("splits GSD_BROWSER_MCP_COMMAND command lines before spawning", () => {
+    const commandLine = '"C:\\Program Files\\nodejs\\node.exe" "C:\\Users\\Test User\\AppData\\Roaming\\npm\\node_modules\\@opengsd\\gsd-browser\\bin\\gsd-browser"';
+    const { command, args } = resolveGsdBrowserMcpLaunchConfig("C:\\Users\\Test User\\project", {
+      GSD_BROWSER_MCP_COMMAND: commandLine,
+    });
+
+    assert.equal(command, "C:\\Program Files\\nodejs\\node.exe");
+    assert.equal(args[0], "C:\\Users\\Test User\\AppData\\Roaming\\npm\\node_modules\\@opengsd\\gsd-browser\\bin\\gsd-browser");
+    assert.equal(args[1], "mcp");
+  });
+
+  it("uses a path-safe identity-project identifier", () => {
+    const { args } = resolveGsdBrowserMcpLaunchConfig("/tmp/example/project", {});
+    const projectId = args[args.indexOf("--identity-project") + 1];
+    assert.equal(typeof projectId, "string");
+    assert.doesNotMatch(projectId, /[\\/]/);
+  });
+});
+
+describe("resolveGsdBrowserDaemonStartInvocation", () => {
+  it("mirrors MCP session and identity flags with daemon start", () => {
+    const launch = resolveGsdBrowserMcpLaunchConfig("/tmp/example-project", {});
+    const daemon = resolveGsdBrowserDaemonStartInvocation("/tmp/example-project", {});
+
+    assert.equal(daemon.command, launch.command);
+    assert.equal(daemon.cwd, launch.cwd);
+    assert.deepEqual(
+      daemon.args.slice(daemon.args.indexOf("--session")),
+      launch.args.slice(launch.args.indexOf("--session")),
+    );
+    assert.deepEqual(
+      daemon.args.slice(0, daemon.args.indexOf("--session")),
+      [...launch.args.slice(0, launch.args.indexOf("mcp")), "daemon", "start"],
+    );
+  });
 });

package/src/resources/extensions/browser-tools/tests/managed-gsd-browser-tools.test.mjs

@@ -2,10 +2,33 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 
 const {
+  MANAGED_BROWSER_TOOL_SPECS,
   MANAGED_GSD_BROWSER_TOOL_NAMES,
+  findMissingContractCoverage,
+  normalizeManagedArgs,
   registerManagedGsdBrowserTools,
 } = await import("../engine/managed-gsd-browser.ts");
 
+// The tools @opengsd/gsd-browser actually serves over MCP (subset relevant to
+// the contract). Notably absent: browser_click, browser_type, browser_verify,
+// browser_reload — those are satisfied through translations.
+const GSD_BROWSER_SERVED_TOOLS = [
+  "browser_navigate",
+  "browser_snapshot",
+  "browser_click_ref",
+  "browser_fill_ref",
+  "browser_fill_form",
+  "browser_wait_for",
+  "browser_assert",
+  "browser_screenshot",
+  "browser_find_element",
+  "browser_console",
+  "browser_network",
+  "browser_evaluate",
+  "browser_batch",
+  "browser_act",
+];
+
 describe("registerManagedGsdBrowserTools", () => {
   it("registers the curated Pi browser contract", () => {
     const tools = [];
@@ -31,3 +54,116 @@ describe("registerManagedGsdBrowserTools", () => {
     assert.equal(screenshot?.compatibility?.producesImages, true);
   });
 });
+
+describe("findMissingContractCoverage", () => {
+  it("reports nothing for the tool list gsd-browser actually serves", () => {
+    assert.deepEqual(findMissingContractCoverage(GSD_BROWSER_SERVED_TOOLS), []);
+  });
+
+  it("reports contract tools none of whose MCP candidates are served", () => {
+    const served = GSD_BROWSER_SERVED_TOOLS.filter((name) => name !== "browser_assert");
+    // browser_verify also depends on browser_assert through its translation.
+    assert.deepEqual(findMissingContractCoverage(served), ["browser_assert", "browser_verify"]);
+  });
+
+  it("reports translated tools when a required MCP tool is missing", () => {
+    const served = GSD_BROWSER_SERVED_TOOLS.filter((name) => name !== "browser_batch");
+    assert.deepEqual(findMissingContractCoverage(served), ["browser_click", "browser_type", "browser_batch"]);
+  });
+});
+
+describe("contract tool translations", () => {
+  it("translates browser_click into a single-step batch call", () => {
+    const calls = MANAGED_BROWSER_TOOL_SPECS.browser_click.translate.build({ selector: "#save" });
+    assert.deepEqual(calls, [{
+      mcpTool: "browser_batch",
+      args: { steps: [{ action: "click", selector: "#save" }] },
+    }]);
+  });
+
+  it("translates browser_type into a single-step batch call", () => {
+    const calls = MANAGED_BROWSER_TOOL_SPECS.browser_type.translate.build({
+      selector: "#name",
+      text: "hello",
+      clearFirst: true,
+      submit: true,
+    });
+    assert.deepEqual(calls, [{
+      mcpTool: "browser_batch",
+      args: { steps: [{ action: "type", selector: "#name", text: "hello", clearFirst: true, submit: true }] },
+    }]);
+  });
+
+  it("normalizes batch options and step keys to the daemon's snake_case", () => {
+    const normalized = normalizeManagedArgs("browser_batch", {
+      steps: [{ action: "type", selector: "#name", text: "hi", clearFirst: true }],
+      stopOnFailure: false,
+      finalSummaryOnly: true,
+    });
+    assert.deepEqual(normalized, {
+      steps: [{ action: "type", selector: "#name", text: "hi", clear_first: true }],
+      stop_on_failure: false,
+      summary_only: true,
+    });
+  });
+
+  it("translates browser_verify into navigate, assert, and screenshot calls", () => {
+    const calls = MANAGED_BROWSER_TOOL_SPECS.browser_verify.translate.build({
+      url: "http://localhost:3000",
+      timeout: 5000,
+      checks: [
+        { description: "heading shows", selector: "h1", expectedText: "Welcome" },
+        { description: "spinner gone", selector: ".spinner", expectedVisible: false },
+        { description: "evidence", selector: "main", expectedVisible: true, screenshot: true },
+      ],
+    });
+    assert.deepEqual(calls, [
+      { mcpTool: "browser_navigate", args: { url: "http://localhost:3000", timeout: 5000 } },
+      {
+        mcpTool: "browser_assert",
+        args: {
+          checks: [
+            { kind: "text_visible", text: "Welcome" },
+            { kind: "selector_hidden", selector: ".spinner" },
+            { kind: "selector_visible", selector: "main" },
+          ],
+        },
+      },
+      { mcpTool: "browser_screenshot", args: {}, optional: true },
+    ]);
+  });
+
+  it("declares every tool a translation can emit in its coverage requirements", () => {
+    for (const [name, spec] of Object.entries(MANAGED_BROWSER_TOOL_SPECS)) {
+      if (!spec.translate) continue;
+      const maximalArgs = {
+        url: "http://localhost:3000",
+        timeout: 5000,
+        selector: "#el",
+        text: "hi",
+        clearFirst: true,
+        checks: [{ description: "d", selector: "#el", expectedText: "hi", expectedVisible: true, screenshot: true }],
+      };
+      const emitted = spec.translate.build(maximalArgs).map((call) => call.mcpTool);
+      for (const mcpTool of emitted) {
+        assert.ok(
+          spec.translate.requires.includes(mcpTool),
+          `${name} translation emits ${mcpTool} but does not require it for coverage`,
+        );
+      }
+    }
+  });
+
+  it("translates browser_verify without checks into navigation only", () => {
+    const calls = MANAGED_BROWSER_TOOL_SPECS.browser_verify.translate.build({ url: "http://localhost:3000", checks: [] });
+    assert.deepEqual(calls, [{ mcpTool: "browser_navigate", args: { url: "http://localhost:3000" } }]);
+  });
+
+  it("translates browser_reload into evaluate plus best-effort network-idle wait", () => {
+    const calls = MANAGED_BROWSER_TOOL_SPECS.browser_reload.translate.build({});
+    assert.deepEqual(calls, [
+      { mcpTool: "browser_evaluate", args: { expression: "location.reload()" } },
+      { mcpTool: "browser_wait_for", args: { condition: "network_idle", timeout: 3_000 }, optional: true },
+    ]);
+  });
+});