@equinor/fusion-framework-cli-plugin-copilot 2.0.2 → 2.0.3

package/src/commands/app/{login.ts → run-login.ts}

@@ -28,11 +28,13 @@ import {
  */
 export async function runLogin(absAppPath: string, port: number, host: string): Promise<void> {
   const pkgJsonPath = join(absAppPath, 'package.json');
+  // Login needs a valid Fusion app directory; bail out clearly if this isn't one
   if (!existsSync(pkgJsonPath)) {
     console.error(`❌ No package.json found at ${absAppPath}`);
     process.exit(1);
   }
   const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as { name?: string };
+  // The app name is required to resolve the appKey later
   if (!pkgJson.name) {
     console.error(`❌ package.json at ${absAppPath} has no "name" field`);
     process.exit(1);
@@ -51,6 +53,7 @@ export async function runLogin(absAppPath: string, port: number, host: string):
 
   const serverUrl = `http://localhost:${port}`;
   const ready = await waitForServer(serverUrl, 60);
+  // Abort login when the dev server never comes up within the timeout
   if (!ready) {
     console.error('❌ Server failed to start within 60s');
     cleanup(serverProcess);
@@ -79,6 +82,7 @@ export async function runLogin(absAppPath: string, port: number, host: string):
     300_000,
   );
 
+  // Report success or a soft timeout without failing the login flow
   if (initialized) {
     await sleep(2000);
     console.log('✅ Login complete — session saved.');

package/src/commands/app/{server.ts → start-app-server.ts}

@@ -22,10 +22,12 @@ export interface AppServerResult {
  */
 function freePort(port: number): void {
   try {
+    // Drop the empty string lsof emits when no matching process was found
     const pids = execSync(`lsof -ti tcp:${port}`, { encoding: 'utf-8' })
       .trim()
       .split('\n')
       .filter(Boolean);
+    // Terminate each stale process bound to the port
     for (const pid of pids) {
       try {
         process.kill(parseInt(pid, 10), 'SIGTERM');
@@ -33,6 +35,7 @@ function freePort(port: number): void {
         // already dead
       }
     }
+    // Only log when we actually killed something
     if (pids.length) {
       console.log(`🔄 Killed stale process(es) on port ${port}: ${pids.join(', ')}`);
     }
@@ -63,11 +66,13 @@ export async function startAppServer(
   }
 
   const pkgJsonPath = join(absAppPath, 'package.json');
+  // Startup needs a valid Fusion app directory; bail out clearly if this isn't one
   if (!existsSync(pkgJsonPath)) {
     console.error(`❌ No package.json found at ${absAppPath}`);
     process.exit(1);
   }
   const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf-8')) as { name?: string };
+  // The app name is required to resolve the appKey later
   if (!pkgJson.name) {
     console.error(`❌ package.json at ${absAppPath} has no "name" field`);
     process.exit(1);
@@ -92,6 +97,7 @@ export async function startAppServer(
 
   const serverUrl = `http://localhost:${options.port}`;
   const ready = await waitForServer(serverUrl, 60);
+  // Abort startup when the dev server never comes up within the timeout
   if (!ready) {
     console.error('❌ Server failed to start within 60s');
     cleanup(serverProcess);

package/src/commands/app/status-icon.ts

@@ -0,0 +1,16 @@
+import chalk from 'chalk';
+
+/**
+ * Renders a status glyph for a step or verdict outcome.
+ *
+ * @param ok - Outcome value: `true` (pass), `false` (fail), or a string label
+ *   such as `'blocked'` or `'flaky'` for anything in between.
+ * @returns A single coloured glyph representing the outcome.
+ */
+export function statusIcon(ok: boolean | string): string {
+  // A literal boolean outcome maps directly to pass/fail glyphs
+  if (ok === true) return chalk.green('✔');
+  // An explicit failure gets its own glyph, distinct from unknown/other states
+  if (ok === false) return chalk.red('✖');
+  return chalk.yellow('⚠'); // "blocked", "flaky", etc.
+}

package/src/commands/app/tools/{write-file.ts → create-append-file-tool.ts}

@@ -1,4 +1,4 @@
-import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { appendFileSync, mkdirSync } from 'node:fs';
 import { dirname, isAbsolute, join } from 'node:path';
 
 import type { DefineTool } from './types.js';
@@ -18,55 +18,20 @@ import type { DefineTool } from './types.js';
 function resolveSafe(baseDir: string, input: string): string {
   // If the model echoed the full absolute path from the prompt, strip the base prefix.
   const relative = isAbsolute(input)
-    ? input.startsWith(baseDir + '/') || input.startsWith(baseDir + '\\')
+    ? input.startsWith(`${baseDir}/`) || input.startsWith(`${baseDir}\\`)
       ? input.slice(baseDir.length + 1)
       : (() => {
           throw new Error(`Absolute path outside output directory: ${input}`);
         })()
     : input;
   const resolved = join(baseDir, relative);
+  // Reject any resolved path that escapes the allowed base directory
   if (!resolved.startsWith(baseDir)) {
     throw new Error(`Path escapes the output directory: ${input}`);
   }
   return resolved;
 }
 
-/**
- * Creates the write-file tool so the agent can save artifacts
- * (plan.json, verdict.json, etc.) to the run output directory.
- *
- * @param baseDir - The run output directory that scopes all writes
- * @param defineTool - Copilot SDK helper used to declare tools
- * @returns Copilot tool definition for writing a file
- */
-export function createWriteFileTool(baseDir: string, defineTool: DefineTool) {
-  return defineTool('write_file', {
-    description:
-      'Write content to a file in the output directory. Creates parent directories as needed.',
-    parameters: {
-      type: 'object' as const,
-      properties: {
-        path: {
-          type: 'string',
-          description: 'File path relative to the output directory (e.g. "plan.json")',
-        },
-        content: {
-          type: 'string',
-          description: 'The full file content to write',
-        },
-      },
-      required: ['path', 'content'],
-    },
-    handler: async (args) => {
-      const { path, content } = args as { path: string; content: string };
-      const resolved = resolveSafe(baseDir, path);
-      mkdirSync(dirname(resolved), { recursive: true });
-      writeFileSync(resolved, content);
-      return `Wrote ${content.length} bytes to ${path}`;
-    },
-  });
-}
-
 /**
  * Creates the append-file tool so the agent can append lines
  * to artifacts like executions.jsonl.
@@ -97,7 +62,7 @@ export function createAppendFileTool(baseDir: string, defineTool: DefineTool) {
       const { path, content } = args as { path: string; content: string };
       const resolved = resolveSafe(baseDir, path);
       mkdirSync(dirname(resolved), { recursive: true });
-      appendFileSync(resolved, content.endsWith('\n') ? content : content + '\n');
+      appendFileSync(resolved, content.endsWith('\n') ? content : `${content}\n`);
       return `Appended to ${path}`;
     },
   });

package/src/commands/app/tools/{find.ts → create-find-tool.ts}

@@ -40,8 +40,11 @@ export function createFindTool(context: AgentBrowserToolContext, defineTool: Def
         fillValue?: string;
       };
       const command = ['find', by, value];
+      // Append optional refinements only when the caller actually provided them
       if (action) command.push(action);
+      // Attach the accessible-name filter when the caller supplied one
       if (name) command.push('--name', name);
+      // Attach the fill value when the action is 'fill'
       if (fillValue) command.push(fillValue);
       return context.invoke(command);
     },

package/src/commands/app/tools/{read-file.ts → create-read-file-tool.ts}

@@ -27,13 +27,14 @@ const IMAGE_MIME: Record<string, string> = {
  */
 function resolveSafe(baseDir: string, input: string): string {
   const relative = isAbsolute(input)
-    ? input.startsWith(baseDir + '/') || input.startsWith(baseDir + '\\')
+    ? input.startsWith(`${baseDir}/`) || input.startsWith(`${baseDir}\\`)
       ? input.slice(baseDir.length + 1)
       : (() => {
           throw new Error(`Absolute path outside output directory: ${input}`);
         })()
     : input;
   const resolved = join(baseDir, relative);
+  // Reject any resolved path that escapes the allowed base directory
   if (!resolved.startsWith(baseDir)) {
     throw new Error(`Path escapes the output directory: ${input}`);
   }
@@ -72,6 +73,7 @@ export function createReadFileTool(baseDir: string, defineTool: DefineTool) {
       const { path } = args as { path: string };
       const resolved = resolveSafe(baseDir, path);
 
+      // Report a friendly message instead of throwing when the path doesn't exist
       if (!existsSync(resolved)) {
         return `File not found: ${path}`;
       }

package/src/commands/app/tools/{screenshot.ts → create-screenshot-tool.ts}

@@ -26,15 +26,18 @@ function resolveScreenshotArtifactName(
   requestedPath: string | undefined,
   format: 'jpeg' | 'png',
 ): string | undefined {
+  // No requested path means the caller doesn't need a specific artifact name
   if (!requestedPath) return undefined;
   const fileName = basename(requestedPath);
   const currentExtension = extname(fileName).toLowerCase();
   const expectedExtension = format === 'jpeg' ? '.jpg' : '.png';
 
+  // The extension already matches the selected format; reuse it verbatim
   if (currentExtension === expectedExtension) {
     return fileName;
   }
 
+  // Swap a mismatched extension for the one that matches the selected format
   if (currentExtension.length > 0) {
     return `${fileName.slice(0, -currentExtension.length)}${expectedExtension}`;
   }
@@ -53,6 +56,7 @@ function resolveScreenshotDirectory(
   evidenceDir: string,
   requestedDirectory: string | undefined,
 ): string {
+  // No requested directory means the default evidence directory is used
   if (!requestedDirectory) {
     return evidenceDir;
   }
@@ -150,10 +154,12 @@ export function createScreenshotTool(context: AgentBrowserToolContext, defineToo
         screenshotDirectory,
       ];
 
+      // Overlay numbered element labels only when the model explicitly asked for it
       if (annotate) {
         command.push('--annotate');
       }
 
+      // JPEG quality only applies when the selected format is actually JPEG
       if (screenshotFormat === 'jpeg') {
         const screenshotQuality = Math.min(100, Math.max(0, quality ?? 60));
         command.push('--screenshot-quality', String(screenshotQuality));

package/src/commands/app/tools/{scroll.ts → create-scroll-tool.ts}

@@ -33,11 +33,13 @@ export function createScrollTool(context: AgentBrowserToolContext, defineTool: D
         amount?: number;
         target?: string;
       };
+      // A target ref overrides plain direction/amount scrolling
       if (target) {
         return context.invoke(['scrollintoview', target]);
       }
       const scrollDirection = direction ?? 'down';
       const command = ['scroll', scrollDirection];
+      // Only pass an explicit pixel amount when the caller provided one
       if (amount) command.push(String(amount));
       return context.invoke(command);
     },

package/src/commands/app/tools/{wait.ts → create-wait-tool.ts}

@@ -30,9 +30,13 @@ export function createWaitTool(context: AgentBrowserToolContext, defineTool: Def
         load?: string;
         timeout?: number;
       };
+      // Prefer whichever single wait condition the caller specified, in priority order
       if (text) return context.invoke(['wait', '--text', text], 60_000);
+      // Fall back to waiting on a page load state
       if (load) return context.invoke(['wait', '--load', load], 60_000);
+      // Fall back to waiting on a specific element/selector
       if (selector) return context.invoke(['wait', selector], 60_000);
+      // A plain timeout falls back to a bare delay instead of an invoke command
       if (timeout) {
         await new Promise((resolve) => setTimeout(resolve, timeout));
         return `Waited ${timeout}ms`;

package/src/commands/app/tools/create-write-file-tool.ts

@@ -0,0 +1,69 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+
+import type { DefineTool } from './types.js';
+
+/**
+ * Resolves a path within a base directory, rejecting escapes.
+ *
+ * Accepts both relative paths and absolute paths that fall within
+ * the base directory. Strips the base prefix from absolute paths
+ * before resolving to handle models that echo full paths from prompts.
+ *
+ * @param baseDir - The allowed root directory
+ * @param input - The user-provided path (relative or absolute within baseDir)
+ * @returns The resolved absolute path
+ * @throws {Error} When the path escapes the base directory
+ */
+function resolveSafe(baseDir: string, input: string): string {
+  // If the model echoed the full absolute path from the prompt, strip the base prefix.
+  const relative = isAbsolute(input)
+    ? input.startsWith(`${baseDir}/`) || input.startsWith(`${baseDir}\\`)
+      ? input.slice(baseDir.length + 1)
+      : (() => {
+          throw new Error(`Absolute path outside output directory: ${input}`);
+        })()
+    : input;
+  const resolved = join(baseDir, relative);
+  // Reject any resolved path that escapes the allowed base directory
+  if (!resolved.startsWith(baseDir)) {
+    throw new Error(`Path escapes the output directory: ${input}`);
+  }
+  return resolved;
+}
+
+/**
+ * Creates the write-file tool so the agent can save artifacts
+ * (plan.json, verdict.json, etc.) to the run output directory.
+ *
+ * @param baseDir - The run output directory that scopes all writes
+ * @param defineTool - Copilot SDK helper used to declare tools
+ * @returns Copilot tool definition for writing a file
+ */
+export function createWriteFileTool(baseDir: string, defineTool: DefineTool) {
+  return defineTool('write_file', {
+    description:
+      'Write content to a file in the output directory. Creates parent directories as needed.',
+    parameters: {
+      type: 'object' as const,
+      properties: {
+        path: {
+          type: 'string',
+          description: 'File path relative to the output directory (e.g. "plan.json")',
+        },
+        content: {
+          type: 'string',
+          description: 'The full file content to write',
+        },
+      },
+      required: ['path', 'content'],
+    },
+    handler: async (args) => {
+      const { path, content } = args as { path: string; content: string };
+      const resolved = resolveSafe(baseDir, path);
+      mkdirSync(dirname(resolved), { recursive: true });
+      writeFileSync(resolved, content);
+      return `Wrote ${content.length} bytes to ${path}`;
+    },
+  });
+}

package/src/commands/app/tools/index.ts

@@ -1,23 +1,23 @@
-import { createClickTool } from './click.js';
-import { createErrorsTool } from './errors.js';
-import { createFillTool } from './fill.js';
-import { createFindTool } from './find.js';
-import { createGetUrlTool } from './get-url.js';
-import { createGoBackTool } from './go-back.js';
-import { createHoverTool } from './hover.js';
-import { createNavigateTool } from './navigate.js';
-import { createPressKeyTool } from './press-key.js';
-import { createReloadTool } from './reload.js';
-import { createEvalJsTool } from './eval-js.js';
-import { createGetStylesTool } from './get-styles.js';
-import { AgentBrowserToolRegistry } from './registry.js';
-import { createScreenshotTool } from './screenshot.js';
-import { createScrollTool } from './scroll.js';
-import { createSelectTool } from './select.js';
-import { createSnapshotTool } from './snapshot.js';
-import { createTypeTextTool } from './type-text.js';
+import { createClickTool } from './create-click-tool.js';
+import { createErrorsTool } from './create-errors-tool.js';
+import { createFillTool } from './create-fill-tool.js';
+import { createFindTool } from './create-find-tool.js';
+import { createGetUrlTool } from './create-get-url-tool.js';
+import { createGoBackTool } from './create-go-back-tool.js';
+import { createHoverTool } from './create-hover-tool.js';
+import { createNavigateTool } from './create-navigate-tool.js';
+import { createPressKeyTool } from './create-press-key-tool.js';
+import { createReloadTool } from './create-reload-tool.js';
+import { createEvalJsTool } from './create-eval-js-tool.js';
+import { createGetStylesTool } from './create-get-styles-tool.js';
+import { AgentBrowserToolRegistry } from './AgentBrowserToolRegistry.js';
+import { createScreenshotTool } from './create-screenshot-tool.js';
+import { createScrollTool } from './create-scroll-tool.js';
+import { createSelectTool } from './create-select-tool.js';
+import { createSnapshotTool } from './create-snapshot-tool.js';
+import { createTypeTextTool } from './create-type-text-tool.js';
 import type { AgentBrowserToolContext, AgentBrowserToolList, DefineTool } from './types.js';
-import { createWaitTool } from './wait.js';
+import { createWaitTool } from './create-wait-tool.js';
 
 /**
  * Creates the full set of Copilot browser tools for an eval session.

package/src/commands/app/truncate.ts

@@ -0,0 +1,10 @@
+/**
+ * Truncates a string to a maximum length, appending an ellipsis when cut.
+ *
+ * @param str - The string to truncate.
+ * @param max - Maximum length of the returned string, including the ellipsis.
+ * @returns The original string, or a shortened version ending in `…`.
+ */
+export function truncate(str: string, max: number): string {
+  return str.length > max ? `${str.slice(0, max - 1)}…` : str;
+}

package/src/commands/app/try-format-message.ts

@@ -0,0 +1,42 @@
+import type { Plan, StepResult, Verdict } from './types.js';
+import { formatPlan } from './format-plan.js';
+import { formatStepResult } from './format-step-result.js';
+import { formatVerdict } from './format-verdict.js';
+
+/**
+ * Attempts to detect the JSON shape of an assistant message and format it.
+ *
+ * Returns `null` when the content is not a recognised structure, so the
+ * caller can fall back to plain-text rendering.
+ *
+ * @param content - Raw assistant message content, expected to be a JSON string.
+ * @returns A formatted string for a recognised plan, step result, or verdict, or `null` otherwise.
+ */
+export function tryFormatMessage(content: string): string | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content.trim());
+  } catch {
+    return null;
+  }
+  // Only object shapes can be matched against the recognised message formats
+  if (!parsed || typeof parsed !== 'object') return null;
+
+  // Verdict: { pass, reasoning, steps[] }
+  if ('pass' in parsed && 'steps' in parsed && Array.isArray((parsed as Verdict).steps)) {
+    return formatVerdict(parsed as Verdict);
+  }
+
+  // Plan: { summary, steps[] }
+  if ('summary' in parsed && 'steps' in parsed && Array.isArray((parsed as Plan).steps)) {
+    return formatPlan(parsed as Plan);
+  }
+
+  // Step result: { criterion, ok, note }
+  if ('criterion' in parsed && 'ok' in parsed && 'note' in parsed) {
+    return formatStepResult(parsed as StepResult);
+  }
+
+  // No recognised shape matched; caller should fall back to plain-text rendering
+  return null;
+}

package/src/exit-with-resolution-error.ts

@@ -0,0 +1,15 @@
+/**
+ * Prints a CLI resolution error and exits the current process.
+ *
+ * @param message - Primary error message.
+ * @param detail - Optional follow-up detail shown on the next line.
+ * @returns This function never returns because the process exits.
+ */
+export function exitWithResolutionError(message: string, detail?: string): never {
+  console.error(`❌ ${message}`);
+  // Only print the detail line when one was provided
+  if (detail) {
+    console.error(`   ${detail}`);
+  }
+  process.exit(1);
+}

package/src/index.ts

@@ -1,5 +1,5 @@
 import type { Command } from 'commander';
-import { copilotCommand } from './commands/app/command.js';
+import { copilotCommand } from './commands/app/copilot-command.js';
 
 /**
  * Registers the `copilot` CLI plugin with the Fusion Framework CLI.

package/src/resolve-eval-command-input.ts

@@ -0,0 +1,59 @@
+import { basename, dirname, extname, resolve } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+
+import { exitWithResolutionError } from './exit-with-resolution-error.js';
+
+/**
+ * Normalized positional input for the `copilot app eval` command.
+ *
+ * When the user passes an application directory, `evalFile` is undefined.
+ * When the user passes a direct `eval/*.md` file path, `appPath` is derived
+ * from the file location and `evalFile` points to the selected markdown file.
+ */
+export interface EvalCommandInput {
+  /** Absolute path to the Fusion application directory. */
+  appPath: string;
+  /** Optional absolute path to the directly selected eval markdown file. */
+  evalFile?: string;
+}
+
+/**
+ * Resolves the positional `copilot app eval` argument.
+ *
+ * Supports both application directory paths and direct paths to markdown files
+ * inside an application's `eval/` directory.
+ *
+ * @param inputPath - Positional CLI argument passed to the eval command.
+ * @returns Normalized application path and optional direct eval file path.
+ */
+export function resolveEvalCommandInput(inputPath: string): EvalCommandInput {
+  const absInput = resolve(inputPath);
+
+  // A non-markdown path is treated as the application directory itself
+  if (extname(absInput) !== '.md') {
+    return { appPath: absInput };
+  }
+
+  // The direct eval file path must actually exist on disk
+  if (!existsSync(absInput)) {
+    exitWithResolutionError(`Eval file not found: ${absInput}`);
+  }
+
+  // Reject directories passed off as a direct eval file path
+  if (!statSync(absInput).isFile()) {
+    exitWithResolutionError(`Eval path is not a file: ${absInput}`);
+  }
+
+  const evalDir = dirname(absInput);
+  // Direct eval files must live inside an `eval/` directory so appPath can be derived
+  if (basename(evalDir) !== 'eval') {
+    exitWithResolutionError(
+      `Direct eval file path must point to a markdown file inside an eval directory: ${absInput}`,
+    );
+  }
+
+  return {
+    appPath: dirname(evalDir),
+    evalFile: absInput,
+  };
+}

package/src/resolve-eval-files.ts

@@ -0,0 +1,57 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { extname, isAbsolute, join, resolve } from 'node:path';
+
+import { exitWithResolutionError } from './exit-with-resolution-error.js';
+
+/**
+ * Resolves eval markdown files for a Fusion application.
+ *
+ * @param appPath - Path to the Fusion application directory
+ * @param evalOpt - Value of the `--eval` CLI option (name, path, or `undefined`)
+ * @returns Array of absolute paths to eval markdown files
+ */
+export function resolveEvalFiles(appPath: string, evalOpt?: string): string[] {
+  const absApp = resolve(appPath);
+
+  // No --eval option: run every eval file found in the app's eval/ directory
+  if (!evalOpt) {
+    const evalDir = join(absApp, 'eval');
+    // Fail fast when the application has no eval directory to scan
+    if (!existsSync(evalDir)) {
+      exitWithResolutionError(
+        `No eval directory found at ${evalDir}`,
+        'Create eval/*.md files or use --eval <file>',
+      );
+    }
+    const files = readdirSync(evalDir)
+      // Keep only markdown files, sorted for stable ordering, resolved to absolute paths
+      .filter((f) => f.endsWith('.md'))
+      .sort()
+      // Resolve each filename to its absolute path within the eval directory
+      .map((f) => join(evalDir, f));
+
+    // Surface a clear error instead of silently running zero eval files
+    if (files.length === 0) {
+      exitWithResolutionError(`No .md files found in ${evalDir}`);
+    }
+    return files;
+  }
+
+  // A path-like --eval value (absolute or containing separators) is a direct file reference
+  if (isAbsolute(evalOpt) || evalOpt.includes('/') || evalOpt.includes('\\')) {
+    const absPath = isAbsolute(evalOpt) ? evalOpt : resolve(evalOpt);
+    // Validate the direct file path exists before returning it
+    if (!existsSync(absPath)) {
+      exitWithResolutionError(`Eval file not found: ${absPath}`);
+    }
+    return [absPath];
+  }
+
+  const evalFileName = extname(evalOpt) === '.md' ? evalOpt : `${evalOpt}.md`;
+  const evalFile = join(absApp, 'eval', evalFileName);
+  // Otherwise treat --eval as a bare name inside the app's eval/ directory
+  if (!existsSync(evalFile)) {
+    exitWithResolutionError(`Eval file not found: ${evalFile}`);
+  }
+  return [evalFile];
+}

package/src/utils/ab-error-message.ts

@@ -0,0 +1,31 @@
+/**
+ * Extracts the user-facing error message from an agent-browser failure.
+ *
+ * Strips ANSI escape codes from stderr and returns only the diagnostic
+ * lines prefixed with `✗` or `⚠`. Falls back to the first 200 characters
+ * of the error message when no diagnostic lines are found.
+ *
+ * @param err - The caught error (typically from {@link ab})
+ * @returns A single-line summary suitable for console output
+ */
+export function abErrorMessage(err: unknown): string {
+  // Non-Error throws have no structured message to extract
+  if (!(err instanceof Error)) return String(err);
+  const e = err as Error & { stderr?: string };
+  // Prefer the raw stderr stream when it was captured on the error
+  if (e.stderr) {
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping ANSI escape sequences
+    const ansiPattern = /\x1B\[[0-9;]*m/g;
+    const lines = e.stderr
+      .replace(ansiPattern, '')
+      .split('\n')
+      // Keep only the diagnostic lines agent-browser prefixes with a status glyph
+      .map((l) => l.trim())
+      // Filter down to lines that look like agent-browser's own status output
+      .filter((l) => l.startsWith('✗') || l.startsWith('⚠'));
+    // Only report an assembled diagnostic summary when matching lines were found
+    if (lines.length) return lines.join(' | ');
+  }
+  const match = e.message.match(/[✗⚠].+/);
+  return match ? match[0] : e.message.slice(0, 200);
+}

package/src/utils/{agent-browser.ts → ab.ts}

@@ -1,10 +1,8 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, unlinkSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-/** Persistent Chrome profile directory used across agent-browser sessions. */
-export const PROFILE_DIR = `${homedir()}/.fusion-smoke-profile`;
+import { PROFILE_DIR } from './helpers.js';
 
 /**
  * Runs an agent-browser command with the persistent Chrome profile.
@@ -22,6 +20,7 @@ export function ab(args: string[], timeoutMs = 30_000): string {
   // Remove stale SingletonLock left by a previous Chrome crash to prevent
   // "Failed to create SingletonLock: File exists" errors.
   const lockPath = join(PROFILE_DIR, 'SingletonLock');
+  // Only attempt removal when a stale lock file is actually present
   if (existsSync(lockPath)) {
     try {
       unlinkSync(lockPath);
@@ -37,30 +36,3 @@ export function ab(args: string[], timeoutMs = 30_000): string {
     cwd: process.cwd(),
   }).trim();
 }
-
-/**
- * Extracts the user-facing error message from an agent-browser failure.
- *
- * Strips ANSI escape codes from stderr and returns only the diagnostic
- * lines prefixed with `✗` or `⚠`. Falls back to the first 200 characters
- * of the error message when no diagnostic lines are found.
- *
- * @param err - The caught error (typically from {@link ab})
- * @returns A single-line summary suitable for console output
- */
-export function abErrorMessage(err: unknown): string {
-  if (!(err instanceof Error)) return String(err);
-  const e = err as Error & { stderr?: string };
-  if (e.stderr) {
-    // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping ANSI escape sequences
-    const ansiPattern = /\x1B\[[0-9;]*m/g;
-    const lines = e.stderr
-      .replace(ansiPattern, '')
-      .split('\n')
-      .map((l) => l.trim())
-      .filter((l) => l.startsWith('✗') || l.startsWith('⚠'));
-    if (lines.length) return lines.join(' | ');
-  }
-  const match = e.message.match(/[✗⚠].+/);
-  return match ? match[0] : e.message.slice(0, 200);
-}