@opengsd/gsd-pi 1.1.1-dev.616a1a1 → 1.1.1-dev.9bb7453

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

@@ -1,11 +1,16 @@
-/** browser-tools — pi extension: full browser interaction via Playwright. */
+/** browser-tools — Pi Browser Automation Contract adapter. */
 import { importExtensionModule, type ExtensionAPI } from "@gsd/pi-coding-agent";
 
-let registrationPromise: Promise<void> | null = null;
+import { closeManagedGsdBrowser, registerManagedGsdBrowserTools } from "./engine/managed-gsd-browser.js";
+import { resolveBrowserEngineMode, type BrowserEngineMode } from "./engine/selection.js";
 
-async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
-  if (!registrationPromise) {
-    registrationPromise = (async () => {
+let legacyRegistrationPromise: Promise<void> | null = null;
+let managedRegistrationPromise: Promise<void> | null = null;
+let registeredEngine: Exclude<BrowserEngineMode, "off"> | null = null;
+
+async function registerLegacyBrowserTools(pi: ExtensionAPI): Promise<void> {
+  if (!legacyRegistrationPromise) {
+    legacyRegistrationPromise = (async () => {
       const [
         lifecycle,
         capture,
@@ -136,12 +141,55 @@ async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
       injectionDetection.registerInjectionDetectionTools(pi, deps);
       verify.registerVerifyTools(pi, deps);
     })().catch((error) => {
-      registrationPromise = null;
+      legacyRegistrationPromise = null;
       throw error;
     });
   }
 
-  return registrationPromise;
+  return legacyRegistrationPromise;
+}
+
+async function registerBrowserTools(pi: ExtensionAPI): Promise<void> {
+  const engine = resolveBrowserEngineMode();
+  if (engine === "off") return;
+  if (registeredEngine && registeredEngine !== engine) {
+    throw new Error(
+      `Browser tools already registered with GSD_BROWSER_ENGINE=${registeredEngine}. Restart GSD before switching to ${engine}.`,
+    );
+  }
+
+  let registration: Promise<void>;
+  if (engine === "legacy") {
+    registration = registerLegacyBrowserTools(pi);
+  } else if (!managedRegistrationPromise) {
+    managedRegistrationPromise = Promise.resolve()
+      .then(() => {
+        registerManagedGsdBrowserTools(pi);
+      })
+      .catch((error) => {
+        managedRegistrationPromise = null;
+        throw error;
+      });
+    registration = managedRegistrationPromise;
+  } else {
+    registration = managedRegistrationPromise;
+  }
+
+  registeredEngine = engine;
+  try {
+    await registration;
+  } catch (error) {
+    if (registeredEngine === engine) registeredEngine = null;
+    throw error;
+  }
+}
+
+async function closeActiveBrowserEngines(): Promise<void> {
+  await closeManagedGsdBrowser();
+  if (legacyRegistrationPromise) {
+    const { closeBrowser } = await importExtensionModule<typeof import("./lifecycle.js")>(import.meta.url, "./lifecycle.js");
+    await closeBrowser();
+  }
 }
 
 export default function (pi: ExtensionAPI) {
@@ -157,7 +205,10 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("session_shutdown", async () => {
-    const { closeBrowser } = await importExtensionModule<typeof import("./lifecycle.js")>(import.meta.url, "./lifecycle.js");
-    await closeBrowser();
+    await closeActiveBrowserEngines();
+  });
+
+  pi.on("session_switch", async () => {
+    await closeActiveBrowserEngines();
   });
 }

package/src/resources/extensions/browser-tools/package.json

@@ -4,16 +4,20 @@
   "version": "1.0.0",
   "type": "module",
   "scripts": {
-    "test": "node --test tests/*.test.mjs"
+    "test": "node --import ../gsd/tests/resolve-ts.mjs --experimental-strip-types --test tests/*.test.mjs"
   },
   "pi": {
     "extensions": ["./index.ts"]
   },
   "peerDependencies": {
+    "@opengsd/gsd-browser": ">=0.1.27",
     "playwright": ">=1.40.0",
     "sharp": ">=0.33.0"
   },
   "peerDependenciesMeta": {
+    "@opengsd/gsd-browser": {
+      "optional": true
+    },
     "playwright": {
       "optional": true
     },

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

@@ -0,0 +1,35 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createRequire } from "node:module";
+import { dirname } 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");
+
+describe("resolveBrowserEngineMode", () => {
+  it("defaults to gsd-browser", () => {
+    assert.equal(resolveBrowserEngineMode({}), "gsd-browser");
+  });
+
+  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");
+  });
+
+  it("accepts compatibility aliases", () => {
+    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "playwright" }), "legacy");
+    assert.equal(resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "false" }), "off");
+  });
+
+  it("rejects unknown engine modes", () => {
+    assert.throws(
+      () => resolveBrowserEngineMode({ GSD_BROWSER_ENGINE: "surprise" }),
+      /Expected "gsd-browser", "legacy", or "off"/,
+    );
+  });
+});

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

@@ -0,0 +1,33 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+const {
+  MANAGED_GSD_BROWSER_TOOL_NAMES,
+  registerManagedGsdBrowserTools,
+} = await import("../engine/managed-gsd-browser.ts");
+
+describe("registerManagedGsdBrowserTools", () => {
+  it("registers the curated Pi browser contract", () => {
+    const tools = [];
+    registerManagedGsdBrowserTools({
+      registerTool(tool) {
+        tools.push(tool);
+      },
+    });
+
+    assert.deepEqual(tools.map((tool) => tool.name), [...MANAGED_GSD_BROWSER_TOOL_NAMES]);
+    assert.equal(new Set(tools.map((tool) => tool.name)).size, tools.length);
+  });
+
+  it("keeps screenshots marked as image-producing evidence", () => {
+    const tools = [];
+    registerManagedGsdBrowserTools({
+      registerTool(tool) {
+        tools.push(tool);
+      },
+    });
+
+    const screenshot = tools.find((tool) => tool.name === "browser_screenshot");
+    assert.equal(screenshot?.compatibility?.producesImages, true);
+  });
+});

package/src/resources/extensions/claude-code-cli/stream-adapter.ts

@@ -27,10 +27,21 @@ import { homedir } from "node:os";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { PartialMessageBuilder, ZERO_USAGE, mapUsage } from "./partial-builder.js";
-import { buildWorkflowMcpServers, resolveWorkflowMcpProjectRoot } from "../gsd/workflow-mcp.js";
-import { buildProjectGsdMcpServers } from "../gsd/mcp-project-config.js";
+import {
+	buildWorkflowMcpServers,
+	getRequiredWorkflowToolsForAutoUnit,
+	resolveWorkflowMcpProjectRoot,
+} from "../gsd/workflow-mcp.js";
+import { buildProjectGsdMcpServers, ensureProjectWorkflowMcpConfig } from "../gsd/mcp-project-config.js";
 import { loadProjectGSDPreferences } from "../gsd/preferences.js";
-import { discoverBrowserMcpServerName, discoverMcpServerNames, discoverWorkflowMcpServerName, computeMcpDisallowedTools } from "../gsd/mcp-filter.js";
+import {
+	discoverBrowserMcpServerName,
+	discoverMcpServers,
+	discoverMcpServerNames,
+	discoverWorkflowMcpServerName,
+	computeMcpDisallowedTools,
+} from "../gsd/mcp-filter.js";
+import { RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES, RUN_UAT_FORBIDDEN_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES, resolveToolPresentationPlan } from "../gsd/tool-presentation-plan.js";
 import { showInterviewRound, type Question, type RoundResult } from "../shared/tui.js";
 import type {
 	BetaRawMessageStreamEvent,
@@ -324,6 +335,33 @@ function extractMessageText(msg: { role: string; content: unknown }): string {
 	return "";
 }
 
+const GSD_PHASE_PATTERNS: Array<[string, RegExp]> = [
+	["run-uat", /\b(?:UNIT:\s*Run UAT|run-uat)\b/i],
+	["complete-milestone", /\b(?:UNIT:\s*Complete Milestone|complete-milestone)\b/i],
+	["validate-milestone", /\b(?:UNIT:\s*Validate Milestone|validate-milestone)\b/i],
+	["reassess-roadmap", /\b(?:UNIT:\s*Reassess Roadmap|reassess-roadmap)\b/i],
+	["complete-slice", /\b(?:UNIT:\s*Complete Slice|complete-slice)\b/i],
+	["replan-slice", /\b(?:UNIT:\s*Replan Slice|replan-slice)\b/i],
+	["plan-slice", /\b(?:UNIT:\s*Plan Slice|plan-slice|gsd_plan_slice)\b/i],
+	["plan-milestone", /\b(?:UNIT:\s*Plan Milestone|plan-milestone|gsd_plan_milestone)\b/i],
+	["execute-task", /\b(?:UNIT:\s*Execute Task|execute-task|execute-task-simple|reactive-execute)\b/i],
+	["gate-evaluate", /\b(?:UNIT:\s*Gate Evaluate|gate-evaluate|gsd_save_gate_result)\b/i],
+	["research-milestone", /\b(?:UNIT:\s*Research Milestone|research-milestone)\b/i],
+	["research-slice", /\b(?:UNIT:\s*Research Slice|research-slice)\b/i],
+	["discuss-milestone", /\b(?:Discuss milestone|discuss-milestone)\b/i],
+];
+
+export function inferGsdPhaseFromContext(context: Context): string | undefined {
+	const text = [
+		context.systemPrompt ?? "",
+		...context.messages.map((message) => extractMessageText(message)),
+	].join("\n");
+	for (const [phase, pattern] of GSD_PHASE_PATTERNS) {
+		if (pattern.test(text)) return phase;
+	}
+	return undefined;
+}
+
 /**
  * Build a full conversational prompt from GSD's context messages.
  *
@@ -1462,19 +1500,113 @@ function mapThinkingLevelToAnthropicEffort(level: ThinkingLevel | undefined, mod
 	}
 }
 
-function workflowMcpServerNameFromAllowedTools(allowedTools: unknown): string | undefined {
+function parseAllowedMcpToolName(toolName: string): { server: string; tool: string } | undefined {
+	const match = /^mcp__(.+)__(\*|[^*]+)$/.exec(toolName);
+	return match?.[1] && match[2] ? { server: match[1], tool: match[2] } : undefined;
+}
+
+function browserMcpServerNameFromAllowedTools(allowedTools: unknown): string | undefined {
 	if (!Array.isArray(allowedTools)) return undefined;
 	for (const toolName of allowedTools) {
 		if (typeof toolName !== "string") continue;
-		const match = /^mcp__(.+)__\*$/.exec(toolName);
-		if (match?.[1] && match[1] !== "gsd-browser") return match[1];
+		const parsed = parseAllowedMcpToolName(toolName);
+		if (!parsed) continue;
+		if (parsed.server === "gsd-browser" || parsed.tool.startsWith("browser_")) {
+			return parsed.server;
+		}
 	}
 	return undefined;
 }
 
-function browserMcpServerNameFromAllowedTools(allowedTools: unknown): string | undefined {
+function workflowMcpServerNameFromAllowedTools(allowedTools: unknown): string | undefined {
 	if (!Array.isArray(allowedTools)) return undefined;
-	return allowedTools.includes("mcp__gsd-browser__*") ? "gsd-browser" : undefined;
+	const browserServerName = browserMcpServerNameFromAllowedTools(allowedTools);
+	for (const toolName of allowedTools) {
+		if (typeof toolName !== "string") continue;
+		const parsed = parseAllowedMcpToolName(toolName);
+		if (!parsed || parsed.server === browserServerName || parsed.tool.startsWith("browser_")) continue;
+		return parsed.server;
+	}
+	return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+	return isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+
+function cloneSdkMcpServerConfig(config: unknown): Record<string, unknown> | undefined {
+	if (!isRecord(config)) return undefined;
+	const cloned: Record<string, unknown> = {};
+	for (const key of ["type", "command", "cwd", "url"] as const) {
+		if (typeof config[key] === "string") cloned[key] = config[key];
+	}
+	if (Array.isArray(config.args)) {
+		cloned.args = config.args.filter((arg): arg is string => typeof arg === "string");
+	}
+	if (isStringRecord(config.env)) cloned.env = { ...config.env };
+	if (isStringRecord(config.headers)) cloned.headers = { ...config.headers };
+	if (isRecord(config.oauth)) cloned.oauth = { ...config.oauth };
+	return Object.keys(cloned).length > 0 ? cloned : undefined;
+}
+
+function resolveProjectMcpServerConfig(
+	projectRoot: string,
+	serverName: string | undefined,
+	fallbackServers?: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+	if (!serverName) return undefined;
+	const projectServer = discoverMcpServers(projectRoot).find((server) => server.name === serverName);
+	return cloneSdkMcpServerConfig(projectServer?.config) ?? cloneSdkMcpServerConfig(fallbackServers?.[serverName]);
+}
+
+function resolveProjectMcpServerConfigs(
+	projectRoot: string,
+	serverNames: readonly (string | undefined)[],
+	fallbackServers?: Record<string, unknown>,
+): Record<string, Record<string, unknown>> | undefined {
+	const resolved: Record<string, Record<string, unknown>> = {};
+	for (const serverName of serverNames) {
+		const serverConfig = resolveProjectMcpServerConfig(projectRoot, serverName, fallbackServers);
+		if (serverName && serverConfig) resolved[serverName] = serverConfig;
+	}
+	return Object.keys(resolved).length > 0 ? resolved : undefined;
+}
+
+function resolveExactWorkflowMcpToolsForPhase(
+	gsdPhase: string | undefined,
+	workflowServerName: string | undefined,
+	workflowExplicitlyBlocked: boolean,
+): string[] {
+	if (!gsdPhase || !workflowServerName || workflowExplicitlyBlocked) return [];
+	const requiredTools = gsdPhase === "run-uat"
+		? [...RUN_UAT_WORKFLOW_TOOL_NAMES]
+		: getRequiredWorkflowToolsForAutoUnit(gsdPhase);
+	const supportTools = gsdPhase === "run-uat" ? [] : ["gsd_milestone_status"];
+	const requestedToolNames = [...new Set([...requiredTools, ...supportTools])];
+	if (requestedToolNames.length === 0) return [];
+	return resolveToolPresentationPlan({
+		phase: gsdPhase,
+		surface: "claude-code-sdk",
+		workflowMcpServerName: workflowServerName,
+		requestedToolNames,
+	}).presentedToolNames;
+}
+
+export function autoInitClaudeCodeWorkflowMcp(cwd: string): void {
+	const projectRoot = resolveWorkflowMcpProjectRoot(cwd);
+	try {
+		ensureProjectWorkflowMcpConfig(projectRoot);
+	} catch (err) {
+		if (process.env.GSD_DEBUG === "1") {
+			console.warn(
+				`[claude-code] workflow MCP auto-init failed: ${err instanceof Error ? err.message : String(err)}`,
+			);
+		}
+	}
 }
 
 /**
@@ -1492,9 +1624,9 @@ export function buildSdkOptions(
 	modelId: string,
 	prompt: string,
 	overrides?: { permissionMode?: "bypassPermissions" | "acceptEdits" | "default" | "plan" },
-	extraOptions: Record<string, unknown> & { reasoning?: ThinkingLevel } = {},
+	extraOptions: Record<string, unknown> & { reasoning?: ThinkingLevel; gsdPhase?: string } = {},
 ): Record<string, unknown> {
-	const { reasoning, cwd, ...sdkExtraOptions } = extraOptions;
+	const { reasoning, cwd, gsdPhase, ...sdkExtraOptions } = extraOptions;
 	const sdkCwd = typeof cwd === "string" && cwd.trim().length > 0 ? cwd : process.cwd();
 	// Claude Code runs in the milestone worktree for file/shell work, but workflow MCP
 	// config (.mcp.json) and server discovery live at the project root.
@@ -1578,13 +1710,46 @@ export function buildSdkOptions(
 	const browserMcpTools = !browserExplicitlyBlocked && browserServerName
 		? [`mcp__${browserServerName}__*`]
 		: [];
-	const gsdMcpTools = [...workflowMcpTools, ...browserMcpTools];
+	const phaseUsesBrowserMcp = !gsdPhase || gsdPhase === "run-uat";
+	const allowedBrowserMcpTools = phaseUsesBrowserMcp ? browserMcpTools : [];
+	const inlinePhaseMcpServers = gsdPhase
+		? resolveProjectMcpServerConfigs(
+				projectRoot,
+				[
+					workflowExplicitlyBlocked ? undefined : workflowServerName,
+					phaseUsesBrowserMcp && !browserExplicitlyBlocked ? browserServerName : undefined,
+				],
+				defaultMcpServers.servers,
+			)
+		: undefined;
+	const sdkMcpServers = inlinePhaseMcpServers ?? filteredMcpServers;
+	const strictMcpConfig = !!inlinePhaseMcpServers;
+	// Strict phase configs inline the exact MCP servers GSD needs. Loading
+	// project/local settings at the same time can duplicate those servers and
+	// leave allowed mcp__... tools with no registered backing tool.
+	const settingSources = strictMcpConfig ? [] : ["project", "local"];
+	const exactWorkflowMcpTools = resolveExactWorkflowMcpToolsForPhase(
+		gsdPhase,
+		workflowServerName,
+		workflowExplicitlyBlocked,
+	);
+	const runUatDisallowedTools = gsdPhase === "run-uat" && workflowServerName
+		? [
+				...RUN_UAT_FORBIDDEN_TOOL_NAMES.filter((toolName) => !toolName.startsWith("mcp__")),
+				"WebFetch",
+				"Agent",
+				`mcp__${workflowServerName}__gsd_exec`,
+				`mcp__${workflowServerName}__gsd_summary_save`,
+				`mcp__${workflowServerName}__gsd_save_gate_result`,
+			]
+		: [];
 	const disallowedTools: string[] = [...new Set([
 		"ToolSearch",
-		...(workflowMcpTools.length > 0 ? ["AskUserQuestion"] : []),
+		...(workflowMcpTools.length > 0 || exactWorkflowMcpTools.length > 0 ? ["AskUserQuestion"] : []),
+		...runUatDisallowedTools,
 		...extraDisallowedTools,
 	])];
-	const allowedTools = [
+	const standardClaudeTools = [
 		"Read",
 		"Write",
 		"Edit",
@@ -1594,8 +1759,19 @@ export function buildSdkOptions(
 		"Agent",
 		"WebFetch",
 		"WebSearch",
-		...(workflowMcpTools.length > 0 ? gsdMcpTools : ["AskUserQuestion", ...browserMcpTools]),
 	];
+	const allowedTools = gsdPhase === "run-uat"
+		? [
+				...RUN_UAT_CLAUDE_NATIVE_TOOL_NAMES,
+				...(exactWorkflowMcpTools.length > 0 ? exactWorkflowMcpTools : []),
+				...allowedBrowserMcpTools,
+			]
+		: [
+				...standardClaudeTools,
+				...exactWorkflowMcpTools,
+				...(workflowMcpTools.length > 0 ? workflowMcpTools : ["AskUserQuestion"]),
+				...allowedBrowserMcpTools,
+			];
 	const supportsAdaptive = modelSupportsAdaptiveThinking(modelId);
 	const effort =
 		reasoning && supportsAdaptive
@@ -1619,11 +1795,12 @@ export function buildSdkOptions(
 		cwd: sdkCwd,
 		permissionMode,
 		allowDangerouslySkipPermissions: permissionMode === "bypassPermissions",
-		settingSources: ["project"],
+		settingSources,
 		systemPrompt: { type: "preset", preset: "claude_code" },
 		disallowedTools,
 		...(allowedTools.length > 0 ? { allowedTools } : {}),
-		...(filteredMcpServers ? { mcpServers: filteredMcpServers } : {}),
+		...(sdkMcpServers ? { mcpServers: sdkMcpServers } : {}),
+		...(strictMcpConfig ? { strictMcpConfig: true } : {}),
 		betas: (
 			modelId.includes("sonnet")
 			|| modelId.includes("opus-4-7")
@@ -1954,6 +2131,8 @@ async function pumpSdkMessages(
 		const onExternalToolCall = (options as ClaudeCodeStreamOptions | undefined)?.onExternalToolCall;
 		const onExternalToolResult = (options as ClaudeCodeStreamOptions | undefined)?.onExternalToolResult;
 		const cwd = resolveClaudeCodeCwd(options);
+		autoInitClaudeCodeWorkflowMcp(cwd);
+		const gsdPhase = inferGsdPhaseFromContext(context);
 		const canUseToolHandler = createClaudeCodeCanUseToolHandler(uiContext);
 		// When no UI is available (headless / auto-mode), auto-approve all
 		// tool requests. This replaces the old bypassPermissions workaround.
@@ -1966,6 +2145,7 @@ async function pumpSdkMessages(
 			{ permissionMode },
 			{
 				cwd,
+				gsdPhase,
 				reasoning: options?.reasoning,
 				canUseTool: canUseToolFallback,
 				...(uiContext