gsd-pi 2.76.0 → 2.77.0-dev.2daa994b6

package/dist/headless.js

@@ -11,7 +11,7 @@
  *   10 — blocked (command reported a blocker)
  *   11 — cancelled (SIGINT/SIGTERM received)
  */
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, writeSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolve } from 'node:path';
 import { RpcClient, SessionManager } from '@gsd/pi-coding-agent';
@@ -616,7 +616,15 @@ async function runHeadlessOnce(options, restartCount) {
     });
     // Signal handling
     const signalHandler = () => {
-        process.stderr.write('\n[headless] Interrupted, stopping child process...\n');
+        // Use writeSync on fd 2 to guarantee the Interrupted marker reaches
+        // consumers before process.exit() truncates pending async writes.
+        try {
+            writeSync(2, '\n[headless] Interrupted, stopping child process...\n');
+        }
+        catch {
+            // Fallback to async write if fd 2 is somehow unavailable.
+            process.stderr.write('\n[headless] Interrupted, stopping child process...\n');
+        }
         interrupted = true;
         exitCode = EXIT_CANCELLED;
         // Kill child process — don't await, just fire and exit.
@@ -635,8 +643,21 @@ async function runHeadlessOnce(options, restartCount) {
         }
         process.exit(exitCode);
     };
-    process.on('SIGINT', signalHandler);
-    process.on('SIGTERM', signalHandler);
+    // Use prependListener so our handler runs before pi-coding-agent's
+    // LSP-client module-load SIGINT handler, which calls process.exit(0)
+    // and would otherwise short-circuit our exit-code-11 contract.
+    process.prependListener('SIGINT', signalHandler);
+    process.prependListener('SIGTERM', signalHandler);
+    // Emit a deterministic readiness marker so test harnesses can wait for
+    // the SIGINT handler to be live before sending a signal. writeSync on
+    // fd 2 avoids any pipe-buffering race between the marker and subsequent
+    // signal delivery.
+    try {
+        writeSync(2, '[headless] signal-handlers-ready\n');
+    }
+    catch {
+        process.stderr.write('[headless] signal-handlers-ready\n');
+    }
     // Start the RPC session
     try {
         await client.start();

package/dist/loader.js

@@ -3,7 +3,7 @@
 // Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 import { fileURLToPath } from 'url';
 import { dirname, resolve, join, relative, delimiter } from 'path';
-import { existsSync, readFileSync, mkdirSync, symlinkSync, cpSync } from 'fs';
+import { existsSync, readFileSync, readdirSync, statSync, mkdirSync, symlinkSync, cpSync } from 'fs';
 // Fast-path: handle --version/-v and --help/-h before importing any heavy
 // dependencies. This avoids loading the entire pi-coding-agent barrel import
 // (~1s) just to print a version string.
@@ -155,15 +155,42 @@ if (process.env.HTTP_PROXY || process.env.HTTPS_PROXY || process.env.http_proxy
 // On Windows without Developer Mode or admin rights, symlinkSync will throw even for
 // 'junction' type — so we fall back to cpSync (a full directory copy) which works
 // everywhere without elevated permissions.
-const gsdScopeDir = join(gsdNodeModules, '@gsd');
+// Discover linkable workspace packages by scanning packages/*/package.json for
+// `gsd.linkable === true`. This is the single source of truth — the same list
+// read by scripts/link-workspace-packages.cjs and scripts/validate-pack.js.
+// Adding a new linkable package requires only setting `gsd.linkable` in its
+// package.json; there is no enumeration to keep in sync here.
 const packagesDir = join(gsdRoot, 'packages');
-const wsPackages = ['native', 'pi-agent-core', 'pi-ai', 'pi-coding-agent', 'pi-tui'];
+const wsPackages = [];
+try {
+    if (existsSync(packagesDir)) {
+        for (const dir of readdirSync(packagesDir)) {
+            const pkgPath = join(packagesDir, dir);
+            if (!statSync(pkgPath).isDirectory())
+                continue;
+            const pkgJsonPath = join(pkgPath, 'package.json');
+            if (!existsSync(pkgJsonPath))
+                continue;
+            try {
+                const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+                const gsd = pkg.gsd;
+                if (!gsd || gsd.linkable !== true)
+                    continue;
+                if (gsd.scope && gsd.name)
+                    wsPackages.push({ dir, scope: gsd.scope, name: gsd.name });
+            }
+            catch { /* ignore malformed package.json */ }
+        }
+    }
+}
+catch { /* non-fatal — validation below catches missing critical packages */ }
 try {
-    if (!existsSync(gsdScopeDir))
-        mkdirSync(gsdScopeDir, { recursive: true });
     for (const pkg of wsPackages) {
-        const target = join(gsdScopeDir, pkg);
-        const source = join(packagesDir, pkg);
+        const scopeDir = join(gsdNodeModules, pkg.scope);
+        if (!existsSync(scopeDir))
+            mkdirSync(scopeDir, { recursive: true });
+        const target = join(scopeDir, pkg.name);
+        const source = join(packagesDir, pkg.dir);
         if (!existsSync(source) || existsSync(target))
             continue;
         try {
@@ -180,6 +207,7 @@ try {
     }
 }
 catch { /* non-fatal */ }
+const gsdScopeDir = join(gsdNodeModules, '@gsd');
 // Validate critical workspace packages are resolvable. If still missing after the
 // symlink+copy attempts, emit a clear diagnostic instead of a cryptic
 // ERR_MODULE_NOT_FOUND from deep inside cli.js.

package/dist/mcp-server.d.ts

@@ -1,6 +1,11 @@
 /**
  * Minimal tool interface matching GSD's AgentTool shape.
  * Avoids a direct dependency on @gsd/pi-agent-core from this compiled module.
+ *
+ * `details` and `isError` are optional fields that runtime tool implementations
+ * may populate. The MCP transport drops non-standard fields, so the wrapper at
+ * the call site mirrors `details` into `structuredContent` and forwards
+ * `isError` directly. See #4472.
  */
 export interface McpToolDef {
     name: string;
@@ -13,6 +18,8 @@ export interface McpToolDef {
             data?: string;
             mimeType?: string;
         }>;
+        details?: Record<string, unknown>;
+        isError?: boolean;
     }>;
 }
 /**

package/dist/mcp-server.js

@@ -1,3 +1,21 @@
+/**
+ * Strict plain-object guard. True only for object literals and
+ * `Object.create(null)` — not for `Date`, `URL`, `Map`, `Set`, class instances,
+ * or arrays. Used to gate `structuredContent` forwarding so the MCP transport
+ * receives only true JSON objects (the protocol contract). See #4477 review.
+ *
+ * Mirrored in `packages/mcp-server/src/workflow-tools.ts` for the
+ * `adaptExecutorResult` adapter on the workflow path. Keep both copies in
+ * sync if the contract definition needs to evolve.
+ */
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
 // MCP SDK subpath imports use wildcard exports (./*) in @modelcontextprotocol/sdk's
 // package.json export map. The wildcard maps "./foo" → "./dist/cjs/foo" (no .js
 // suffix), so bare subpath specifiers like `${MCP_PKG}/server/stdio` resolve to
@@ -83,7 +101,23 @@ export async function startMcpServer(options) {
                 // by stringifying into a text block so clients see the payload.
                 return { type: 'text', text: JSON.stringify(block) };
             });
-            return { content };
+            // Forward a tool's runtime `details` field to MCP's `structuredContent`
+            // channel. The protocol drops non-standard fields on the wire, so tools
+            // that populate `details` for client-side renderers (e.g. save_gate_result)
+            // would otherwise arrive empty on the other side. See #4472.
+            //
+            // Use a strict plain-object guard (prototype-chain check) rather than just
+            // `typeof === 'object' && !Array.isArray()` — Date, URL, Map, Set, and
+            // class instances would otherwise pass through and end up as
+            // `structuredContent`, violating the protocol's JSON-object contract.
+            // The mirror discipline applies in `workflow-tools.ts adaptExecutorResult`.
+            const base = { content };
+            if (isPlainObject(result.details)) {
+                base.structuredContent = result.details;
+            }
+            if (result.isError === true)
+                base.isError = true;
+            return base;
         }
         catch (err) {
             // AbortError from a cancelled tool surfaces as a normal error — MCP

package/dist/onboarding.js

@@ -60,6 +60,8 @@ const OTHER_PROVIDERS = [
     { value: 'xai', label: 'xAI (Grok)', hint: 'console.x.ai' },
     { value: 'openrouter', label: 'OpenRouter', hint: '200+ models — openrouter.ai/keys' },
     { value: 'mistral', label: 'Mistral', hint: 'console.mistral.ai/api-keys' },
+    { value: 'minimax', label: 'MiniMax', hint: 'platform.minimax.io (Anthropic-compatible recommended)' },
+    { value: 'minimax-cn', label: 'MiniMax CN', hint: 'api.minimaxi.com (Anthropic-compatible)' },
     { value: 'ollama-cloud', label: 'Ollama Cloud' },
     { value: 'custom-openai', label: 'Custom (OpenAI-compatible)', hint: 'Ollama, LM Studio, vLLM, proxies — see docs/providers.md' },
 ];
@@ -131,6 +133,36 @@ function persistDefaultProvider(providerId) {
         // Non-fatal: startup fallback logic will still run.
     }
 }
+/**
+ * Persist the selected default model to settings.json.
+ */
+function persistDefaultModel(modelId) {
+    const settingsPath = join(agentDir, 'settings.json');
+    try {
+        const raw = existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, 'utf-8')) : {};
+        raw.defaultModel = modelId;
+        mkdirSync(dirname(settingsPath), { recursive: true });
+        writeFileSync(settingsPath, JSON.stringify(raw, null, 2), 'utf-8');
+    }
+    catch {
+        // Non-fatal: startup fallback logic will still run.
+    }
+}
+function detectNativeProviderFromBaseUrl(baseUrl) {
+    try {
+        const hostname = new URL(baseUrl).hostname.toLowerCase();
+        if (hostname === 'api.minimax.io' || hostname.endsWith('.minimax.io')) {
+            return 'minimax';
+        }
+        if (hostname === 'api.minimaxi.com' || hostname.endsWith('.minimaxi.com')) {
+            return 'minimax-cn';
+        }
+    }
+    catch {
+        // ignore parse failures; handled by prior validation
+    }
+    return null;
+}
 /** Sentinel returned by runStep when the user cancels — tells the caller
  *  to abort the entire wizard. */
 const STEP_CANCELLED = Symbol('step-cancelled');
@@ -558,9 +590,22 @@ async function runCustomOpenAIFlow(p, pc, authStorage) {
     if (p.isCancel(modelId) || !modelId)
         return false;
     const trimmedModelId = modelId.trim();
+    const nativeProvider = detectNativeProviderFromBaseUrl(trimmedUrl);
+    if (nativeProvider) {
+        const envVar = nativeProvider === 'minimax' ? 'MINIMAX_API_KEY' : 'MINIMAX_CN_API_KEY';
+        authStorage.set(nativeProvider, { type: 'api_key', key: trimmedKey });
+        persistDefaultProvider(nativeProvider);
+        persistDefaultModel(trimmedModelId);
+        process.env[envVar] = trimmedKey;
+        p.log.success(`${pc.green('MiniMax')} detected — configured as native provider (${pc.cyan(nativeProvider)})`);
+        p.log.info(`Model: ${pc.cyan(trimmedModelId)}`);
+        p.log.info(pc.dim('Using Anthropic-compatible MiniMax integration for full model metadata and clean thinking output.'));
+        return true;
+    }
     // Save API key to auth storage
     authStorage.set('custom-openai', { type: 'api_key', key: trimmedKey });
     persistDefaultProvider('custom-openai');
+    persistDefaultModel(trimmedModelId);
     // Write or merge into models.json
     const modelsJsonPath = join(agentDir, 'models.json');
     let config = { providers: {} };

package/dist/provider-migrations.d.ts

@@ -5,6 +5,24 @@ type AnthropicMigrationDeps = {
     defaultProvider: string | undefined;
     env?: NodeJS.ProcessEnv;
 };
+type MigrationModel = {
+    provider: string;
+    id: string;
+};
+type AnthropicDefaultMigrationDeps = {
+    authStorage: Pick<AuthStorage, "getCredentialsForProvider">;
+    isClaudeCodeReady: boolean;
+    settingsManager: {
+        getDefaultProvider(): string | undefined;
+        getDefaultModel(): string | undefined;
+        setDefaultModelAndProvider(provider: string, modelId: string): void;
+    };
+    modelRegistry: {
+        getAvailable(): MigrationModel[];
+    };
+    env?: NodeJS.ProcessEnv;
+};
 export declare function hasDirectAnthropicApiKey(authStorage: Pick<AuthStorage, "getCredentialsForProvider">, env?: NodeJS.ProcessEnv): boolean;
 export declare function shouldMigrateAnthropicToClaudeCode({ authStorage, isClaudeCodeReady, defaultProvider, env, }: AnthropicMigrationDeps): boolean;
+export declare function migrateAnthropicDefaultToClaudeCode({ authStorage, isClaudeCodeReady, settingsManager, modelRegistry, env, }: AnthropicDefaultMigrationDeps): boolean;
 export {};

package/dist/provider-migrations.js

@@ -10,3 +10,17 @@ export function shouldMigrateAnthropicToClaudeCode({ authStorage, isClaudeCodeRe
     }
     return !hasDirectAnthropicApiKey(authStorage, env);
 }
+export function migrateAnthropicDefaultToClaudeCode({ authStorage, isClaudeCodeReady, settingsManager, modelRegistry, env = process.env, }) {
+    const defaultProvider = settingsManager.getDefaultProvider();
+    if (!shouldMigrateAnthropicToClaudeCode({ authStorage, isClaudeCodeReady, defaultProvider, env })) {
+        return false;
+    }
+    const defaultModel = settingsManager.getDefaultModel();
+    const target = modelRegistry.getAvailable().find((model) => model.provider === "claude-code" && model.id === defaultModel) ||
+        modelRegistry.getAvailable().find((model) => model.provider === "claude-code");
+    if (!target) {
+        return false;
+    }
+    settingsManager.setDefaultModelAndProvider(target.provider, target.id);
+    return true;
+}

package/dist/resource-loader.d.ts

@@ -2,7 +2,47 @@ import { DefaultResourceLoader } from '@gsd/pi-coding-agent';
 export { discoverExtensionEntryPaths } from './extension-discovery.js';
 export declare function getExtensionKey(entryPath: string, extensionsDir: string): string;
 export declare function readManagedResourceVersion(agentDir: string): string | null;
+/**
+ * Computes a content fingerprint of a resources directory (defaults to the
+ * bundled resourcesDir).
+ *
+ * Walks all files under `rootDir` and hashes `${relativePath}:${sha256(contents)}`
+ * for each one. Using the file *contents* — not size — is what distinguishes
+ * this from the earlier implementation and closes #4787: a same-size edit
+ * (e.g. swapping one word for another word of the same byte length) produces
+ * a different file hash, bumps the aggregate fingerprint, and therefore
+ * triggers a full resync in `initResources`. The old path+size approach
+ * silently cached stale prompts across upgrades.
+ *
+ * Cost is ~1-2ms for a typical resources tree (~100 small .md files) —
+ * still negligible at startup. Files are streamed via `readFileSync` but
+ * bundled prompts are tiny so this is fine.
+ *
+ * Exported for unit tests and for callers that want to check a different
+ * directory (e.g. pre-install verification).
+ */
+export declare function computeResourceFingerprint(rootDir?: string): string;
 export declare function getNewerManagedResourceVersion(agentDir: string, currentVersion: string): string | null;
+/**
+ * Syncs a single bundled resource directory into the agent directory.
+ *
+ * 1. Makes the destination writable (handles Nix store read-only copies).
+ * 2. Removes destination subdirs that exist in source to clear stale files,
+ *    while preserving user-created directories.
+ * 3. Copies source into destination.
+ * 4. Makes the result writable for the next upgrade cycle.
+ */
+export declare function syncResourceDir(srcDir: string, destDir: string): void;
+/** Check if any @gsd* scopes exist in internal but not in hoisted node_modules */
+export declare function hasMissingWorkspaceScopes(hoisted: string, internal: string): boolean;
+/**
+ * Create a real node_modules directory containing symlinks from both the
+ * hoisted root (external deps) and internal root (@gsd/* workspace packages).
+ * Used for pnpm global installs where @gsd/* isn't hoisted.
+ */
+export declare function reconcileMergedNodeModules(agentNodeModules: string, hoisted: string, internal: string): void;
+/** Build a cache fingerprint from packageRoot + sorted entry names of both directories */
+export declare function mergedFingerprint(hoisted: string, internal: string): string;
 /**
  * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
  *
@@ -21,6 +61,6 @@ export declare function getNewerManagedResourceVersion(agentDir: string, current
  *
  * Inspectable: `ls ~/.gsd/agent/extensions/`
  */
-export declare function initResources(agentDir: string): void;
+export declare function initResources(agentDir: string, skillsDir?: string): void;
 export declare function hasStaleCompiledExtensionSiblings(extensionsDir: string, sourceDir?: string): boolean;
 export declare function buildResourceLoader(agentDir: string): DefaultResourceLoader;

package/dist/resource-loader.js

@@ -101,17 +101,27 @@ function readManagedResourceManifest(agentDir) {
     }
 }
 /**
- * Computes a lightweight content fingerprint of the bundled resources directory.
+ * Computes a content fingerprint of a resources directory (defaults to the
+ * bundled resourcesDir).
  *
- * Walks all files under resourcesDir and hashes their relative paths + sizes.
- * This catches same-version content changes (npm link dev workflow, hotfixes
- * within a release) without the cost of reading every file's contents.
+ * Walks all files under `rootDir` and hashes `${relativePath}:${sha256(contents)}`
+ * for each one. Using the file *contents* — not size — is what distinguishes
+ * this from the earlier implementation and closes #4787: a same-size edit
+ * (e.g. swapping one word for another word of the same byte length) produces
+ * a different file hash, bumps the aggregate fingerprint, and therefore
+ * triggers a full resync in `initResources`. The old path+size approach
+ * silently cached stale prompts across upgrades.
  *
- * ~1ms for a typical resources tree (~100 files) — just stat calls, no reads.
+ * Cost is ~1-2ms for a typical resources tree (~100 small .md files) —
+ * still negligible at startup. Files are streamed via `readFileSync` but
+ * bundled prompts are tiny so this is fine.
+ *
+ * Exported for unit tests and for callers that want to check a different
+ * directory (e.g. pre-install verification).
  */
-function computeResourceFingerprint() {
+export function computeResourceFingerprint(rootDir = resourcesDir) {
     const entries = [];
-    collectFileEntries(resourcesDir, resourcesDir, entries);
+    collectFileEntries(rootDir, rootDir, entries);
     entries.sort();
     return createHash('sha256').update(entries.join('\n')).digest('hex').slice(0, 16);
 }
@@ -125,8 +135,17 @@ function collectFileEntries(dir, root, out) {
         }
         else {
             const rel = relative(root, fullPath);
-            const size = statSync(fullPath).size;
-            out.push(`${rel}:${size}`);
+            // Hash the file contents — see function doc for #4787 rationale.
+            let contentHash;
+            try {
+                contentHash = createHash('sha256').update(readFileSync(fullPath)).digest('hex');
+            }
+            catch {
+                // Unreadable file — fall back to a stable marker so the entry still
+                // contributes to the aggregate hash and future reads will re-hash.
+                contentHash = 'unreadable';
+            }
+            out.push(`${rel}:${contentHash}`);
         }
     }
 }
@@ -188,7 +207,7 @@ function makeTreeWritable(dirPath) {
  * 3. Copies source into destination.
  * 4. Makes the result writable for the next upgrade cycle.
  */
-function syncResourceDir(srcDir, destDir) {
+export function syncResourceDir(srcDir, destDir) {
     makeTreeWritable(destDir);
     if (existsSync(srcDir)) {
         pruneStaleSiblingFiles(srcDir, destDir);
@@ -282,7 +301,7 @@ function ensureNodeModulesSymlink(agentDir) {
     reconcileMergedNodeModules(agentNodeModules, hoistedNodeModules, internalNodeModules);
 }
 /** Check if any @gsd* scopes exist in internal but not in hoisted node_modules */
-function hasMissingWorkspaceScopes(hoisted, internal) {
+export function hasMissingWorkspaceScopes(hoisted, internal) {
     if (!existsSync(internal))
         return false;
     try {
@@ -326,7 +345,7 @@ function reconcileSymlink(link, target) {
  * hoisted root (external deps) and internal root (@gsd/* workspace packages).
  * Used for pnpm global installs where @gsd/* isn't hoisted.
  */
-function reconcileMergedNodeModules(agentNodeModules, hoisted, internal) {
+export function reconcileMergedNodeModules(agentNodeModules, hoisted, internal) {
     // Fast path: if already merged for this packageRoot + same directory contents, skip.
     // The fingerprint includes entry names from both roots so `pnpm add/remove` triggers rebuild.
     const marker = join(agentNodeModules, '.gsd-merged');
@@ -400,7 +419,7 @@ function reconcileMergedNodeModules(agentNodeModules, hoisted, internal) {
     }
 }
 /** Build a cache fingerprint from packageRoot + sorted entry names of both directories */
-function mergedFingerprint(hoisted, internal) {
+export function mergedFingerprint(hoisted, internal) {
     try {
         const h = readdirSync(hoisted).sort().join(',');
         const i = readdirSync(internal).sort().join(',');
@@ -506,7 +525,7 @@ function pruneRemovedBundledExtensions(manifest, agentDir) {
  *
  * Inspectable: `ls ~/.gsd/agent/extensions/`
  */
-export function initResources(agentDir) {
+export function initResources(agentDir, skillsDir = join(homedir(), '.agents', 'skills')) {
     mkdirSync(agentDir, { recursive: true });
     const currentVersion = getBundledGsdVersion();
     const manifest = readManagedResourceManifest(agentDir);
@@ -538,13 +557,7 @@ export function initResources(agentDir) {
     // Sync bundled resources — overwrite so updates land on next launch.
     syncResourceDir(bundledExtensionsDir, join(agentDir, 'extensions'));
     syncResourceDir(join(resourcesDir, 'agents'), join(agentDir, 'agents'));
-    // Skills are no longer force-synced here. Users install skills via the
-    // skills.sh CLI (`npx skills add <repo>`) into ~/.agents/skills/ which
-    // is the industry-standard Agent Skills ecosystem directory.
-    //
-    // Migration from the legacy ~/.gsd/agent/skills/ directory is handled
-    // above the manifest check so it runs on every launch (including retries
-    // after partial copy failures).
+    syncResourceDir(join(resourcesDir, 'skills'), skillsDir);
     // Sync GSD-WORKFLOW.md to agentDir as a fallback for when GSD_WORKFLOW_PATH
     // env var is not set (e.g. fork/dev builds, alternative entry points).
     const workflowSrc = join(resourcesDir, 'GSD-WORKFLOW.md');

package/dist/resources/agents/researcher.md

@@ -1,7 +1,7 @@
 ---
 name: researcher
 description: Web researcher that finds and synthesizes current information using Brave Search
-tools: search-the-web, bash
+tools: search-the-web, bash, capture_thought, memory_query, gsd_graph
 ---
 
 You are a web researcher. You find current, accurate information using web search and synthesize it into a clear, well-structured report.

package/dist/resources/extensions/browser-tools/capture.js

@@ -21,6 +21,15 @@ async function getSharp() {
     }
     return _sharp;
 }
+/**
+ * Test-only seam: override the cached sharp module. Pass `null` to simulate
+ * an environment where the sharp native dep is unavailable; pass `undefined`
+ * to clear the cache and let the next getSharp() call re-import. See
+ * tests/capture-sharp-optional.test.cjs.
+ */
+export function __setSharpForTesting(value) {
+    _sharp = value;
+}
 import { formatCompactStateSummary } from "./utils.js";
 // Anthropic vision: 1568px is the recommended optimal width. Height is capped
 // generously at 8000px so tall full-page screenshots remain readable rather

package/dist/resources/extensions/browser-tools/tests/browser-tools-integration.test.mjs

@@ -12,76 +12,25 @@
 import { describe, it, before, after } from "node:test";
 import assert from "node:assert/strict";
 import { chromium } from "playwright";
-import { readFileSync } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const ROOT = resolve(__dirname, "..");
 
 // ---------------------------------------------------------------------------
-// Source extraction — get the IIFE strings we need for injection
+// Source loading — import the IIFE builders directly via jiti.
+// The test-only named exports in tools/intent.ts and tools/forms.ts exist
+// exactly so this test can call the real, in-tree builders. No brace
+// walking, no regex stripping — a refactor of the signatures just updates
+// the import surface, not the test.
 // ---------------------------------------------------------------------------
 
-// 1. EVALUATE_HELPERS_SOURCE — exported constant, extract via jiti
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
 const jiti = require("jiti")(__dirname, { interopDefault: true, debug: false });
 const { EVALUATE_HELPERS_SOURCE } = jiti("../evaluate-helpers.ts");
-
-// 2. Intent scoring — module-private buildIntentScoringScript.
-//    Extract the function from source, wrap it, and eval to get the builder.
-const intentSource = readFileSync(resolve(ROOT, "tools/intent.ts"), "utf-8");
-
-function extractBuildIntentScoringScript() {
-  // Match the function body: starts with "function buildIntentScoringScript"
-  // and returns a template literal string. We extract up to the matching closing brace.
-  const startMarker = "function buildIntentScoringScript(intent: string, scope?: string): string {";
-  const startIdx = intentSource.indexOf(startMarker);
-  if (startIdx === -1) throw new Error("Could not find buildIntentScoringScript in intent.ts");
-
-  // Walk from start, counting braces to find the end
-  let depth = 0;
-  let foundFirst = false;
-  let endIdx = startIdx;
-  for (let i = startIdx; i < intentSource.length; i++) {
-    if (intentSource[i] === "{") { depth++; foundFirst = true; }
-    if (intentSource[i] === "}") depth--;
-    if (foundFirst && depth === 0) { endIdx = i + 1; break; }
-  }
-
-  let fnBody = intentSource.slice(startIdx, endIdx);
-  // Strip TypeScript type annotations
-  fnBody = fnBody.replace(/\(intent:\s*string,\s*scope\?:\s*string\):\s*string/, "(intent, scope)");
-  return new Function("return " + fnBody)();
-}
-
-const buildIntentScoringScript = extractBuildIntentScoringScript();
-
-// 3. Form analysis — module-private buildFormAnalysisScript.
-const formsSource = readFileSync(resolve(ROOT, "tools/forms.ts"), "utf-8");
-
-function extractBuildFormAnalysisScript() {
-  const startMarker = "function buildFormAnalysisScript(selector?: string): string {";
-  const startIdx = formsSource.indexOf(startMarker);
-  if (startIdx === -1) throw new Error("Could not find buildFormAnalysisScript in forms.ts");
-
-  let depth = 0;
-  let foundFirst = false;
-  let endIdx = startIdx;
-  for (let i = startIdx; i < formsSource.length; i++) {
-    if (formsSource[i] === "{") { depth++; foundFirst = true; }
-    if (formsSource[i] === "}") depth--;
-    if (foundFirst && depth === 0) { endIdx = i + 1; break; }
-  }
-
-  let fnBody = formsSource.slice(startIdx, endIdx);
-  // Strip TypeScript type annotation
-  fnBody = fnBody.replace(/\(selector\?:\s*string\):\s*string/, "(selector)");
-  return new Function("return " + fnBody)();
-}
-
-const buildFormAnalysisScript = extractBuildFormAnalysisScript();
+const { buildIntentScoringScript } = jiti("../tools/intent.ts");
+const { buildFormAnalysisScript } = jiti("../tools/forms.ts");
 
 // ---------------------------------------------------------------------------
 // Browser lifecycle

package/dist/resources/extensions/browser-tools/tests/browser-tools-unit.test.cjs

@@ -387,32 +387,44 @@ describe("formatArtifactTimestamp", () => {
 // ---------------------------------------------------------------------------
 
 describe("EVALUATE_HELPERS_SOURCE", () => {
-	it("is a parseable string (valid JavaScript)", () => {
-		assert.doesNotThrow(() => {
-			new Function(EVALUATE_HELPERS_SOURCE);
-		});
-	});
+	// Behaviour test: executing the source in a Node vm sandbox must
+	// populate a `window.__pi` namespace with every expected helper.
+	// No source grep — we actually run the code and verify the resulting
+	// object shape.
+	it("executing the source assigns all expected helpers to window.__pi", () => {
+		const vm = require("node:vm");
+		const expectedFunctions = [
+			"cssPath",
+			"simpleHash",
+			"isVisible",
+			"isEnabled",
+			"inferRole",
+			"accessibleName",
+			"isInteractiveEl",
+			"domPath",
+			"selectorHints",
+		];
 
-	const expectedFunctions = [
-		"cssPath",
-		"simpleHash",
-		"isVisible",
-		"isEnabled",
-		"inferRole",
-		"accessibleName",
-		"isInteractiveEl",
-		"domPath",
-		"selectorHints",
-	];
-
-	for (const fnName of expectedFunctions) {
-		it(`contains assignment for pi.${fnName}`, () => {
-			assert.ok(
-				EVALUATE_HELPERS_SOURCE.includes(`pi.${fnName} = function`),
-				`Expected pi.${fnName} = function assignment in source`,
+		// Playwright evaluates the source in a page context where `window`
+		// exists, so the helpers attach to `window.__pi`. Provide a minimal
+		// window stub in a vm context so we avoid polluting the test globals.
+		const sandbox = { window: {} };
+		const script = new vm.Script(EVALUATE_HELPERS_SOURCE);
+		script.runInNewContext(sandbox, { timeout: 1000 });
+
+		assert.ok(
+			sandbox.window.__pi && typeof sandbox.window.__pi === "object",
+			"executing EVALUATE_HELPERS_SOURCE must assign window.__pi",
+		);
+
+		for (const fnName of expectedFunctions) {
+			assert.equal(
+				typeof sandbox.window.__pi[fnName],
+				"function",
+				`window.__pi.${fnName} must be a function after executing the source`,
 			);
-		});
-	}
+		}
+	});
 });
 
 // ---------------------------------------------------------------------------