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

package/src/commands/app/{command.ts → copilot-command.ts}

@@ -2,17 +2,18 @@ import { createCommand } from 'commander';
 import { basename } from 'node:path';
 
 import { resetDaemon, cleanup, createRunDir } from '../../utils/index.js';
-import { runLogin } from './login.js';
-import { resolveEvalCommandInput, resolveEvalFiles } from '../../eval-resolve.js';
-import { createSession } from './eval.js';
-import { startAppServer } from './server.js';
-import { attachSessionLogger } from './session-logger.js';
+import { runLogin } from './run-login.js';
+import { resolveEvalCommandInput } from '../../resolve-eval-command-input.js';
+import { resolveEvalFiles } from '../../resolve-eval-files.js';
+import { createSession } from './create-session.js';
+import { startAppServer } from './start-app-server.js';
+import { attachSessionLogger } from './attach-session-logger.js';
 import type { CopilotEvalOptions, Plan, Verdict } from './types.js';
-import { formatVerdict } from './format.js';
+import { formatVerdict } from './format-verdict.js';
 import { existsSync, readFileSync } from 'node:fs';
-import { createPlanPrompt } from './prompts/plan.prompt.js';
-import { createStepPrompt } from './prompts/step.prompt.js';
-import { createJudgePrompt } from './prompts/judge.prompt.js';
+import { createPlanPrompt } from './prompts/create-plan-prompt.js';
+import { createStepPrompt } from './prompts/create-step-prompt.js';
+import { createJudgePrompt } from './prompts/create-judge-prompt.js';
 import chalk from 'chalk';
 
 /**
@@ -58,6 +59,7 @@ const _appEvalCommand = createCommand('eval')
     const port = parseInt(options.port, 10);
     const verbose = options.verbose;
 
+    // Reject ambiguous input that selects an eval two different ways
     if (resolvedInput.evalFile && options.eval) {
       console.error('❌ Do not combine a positional eval markdown file with --eval');
       process.exit(1);
@@ -73,9 +75,9 @@ const _appEvalCommand = createCommand('eval')
     const evalFiles = resolvedInput.evalFile
       ? [resolvedInput.evalFile]
       : resolveEvalFiles(absAppPath, options.eval);
-    console.log(
-      `📋 Found ${evalFiles.length} eval(s): ${evalFiles.map((f) => basename(f)).join(', ')}`,
-    );
+    // Summarize which eval files were discovered before the run starts
+    const evalFileNames = evalFiles.map((f) => basename(f)).join(', ');
+    console.log(`📋 Found ${evalFiles.length} eval(s): ${evalFileNames}`);
 
     // Start the app dev server (unless --url provides an already-running URL)
     const { serverProcess, appUrl } = await startAppServer(absAppPath, {
@@ -103,6 +105,7 @@ const _appEvalCommand = createCommand('eval')
 
     let failures = 0;
     try {
+      // Run every resolved eval file sequentially so output stays readable
       for (const evalFilePath of evalFiles) {
         const evalName = basename(evalFilePath, '.md');
         const query = readFileSync(evalFilePath, 'utf-8').trim();
@@ -129,6 +132,7 @@ const _appEvalCommand = createCommand('eval')
           await session.sendAndWait({ prompt: createPlanPrompt(query, ctx) }, 300_000);
 
           const planPath = `${runDir}/plan.json`;
+          // Bail out of this eval when the planning phase produced no plan file
           if (!existsSync(planPath)) {
             console.error(
               chalk.red(
@@ -138,6 +142,7 @@ const _appEvalCommand = createCommand('eval')
             session.disconnect();
             logger.stop();
             failures++;
+            // Skip execution/judging phases; this eval already failed at planning
             continue;
           }
 
@@ -147,6 +152,7 @@ const _appEvalCommand = createCommand('eval')
           // ── Phase 2: Execute + Evaluate each step ──────────────────
           for (const step of plan.steps) {
             console.log(chalk.cyan(`\n── Scenario: ${step.scenario}`));
+            // Print each acceptance criterion the agent will be judged against
             for (const c of step.criteria) {
               console.log(chalk.dim(`   • ${c}`));
             }
@@ -162,9 +168,11 @@ const _appEvalCommand = createCommand('eval')
 
           // Print the verdict
           const verdictPath = `${runDir}/verdict.json`;
+          // Only report a verdict when the judge phase actually produced one
           if (existsSync(verdictPath)) {
             const verdict = JSON.parse(readFileSync(verdictPath, 'utf-8')) as Verdict;
             console.log(formatVerdict(verdict));
+            // A failing verdict counts toward the overall exit-code failure total
             if (!verdict.pass) failures++;
           } else {
             console.error(chalk.red(`❌ Judge did not produce ${verdictPath}.`));
@@ -174,6 +182,7 @@ const _appEvalCommand = createCommand('eval')
           logger?.stop();
           const msg = err instanceof Error ? err.message : String(err);
           console.error(chalk.red(`\n❌ Eval "${evalName}" failed: ${msg}`));
+          // Print the stack trace too when one is available for debugging
           if (err instanceof Error && err.stack) {
             console.error(chalk.dim(err.stack));
           }

package/src/commands/app/{eval.ts → create-session.ts}

@@ -3,12 +3,13 @@ import { join } from 'node:path';
 
 import { ab, abErrorMessage } from '../../utils/index.js';
 import { createAgentBrowserTools } from './tools/index.js';
-import { createWriteFileTool, createAppendFileTool } from './tools/write-file.js';
-import { createReadFileTool } from './tools/read-file.js';
+import { createWriteFileTool } from './tools/create-write-file-tool.js';
+import { createAppendFileTool } from './tools/create-append-file-tool.js';
+import { createReadFileTool } from './tools/create-read-file-tool.js';
 import type { RuntimeExecutionContext } from './types.js';
 import type { CopilotSession, SessionConfig } from '@github/copilot-sdk';
-import { createSystemPrompt } from './prompts/system.prompt.js';
-import { createDevServerContext } from './prompts/system.dev-server.prompt.js';
+import { createSystemPrompt } from './prompts/create-system-prompt.js';
+import { createDevServerContext } from './prompts/create-dev-server-context.js';
 
 /**
  * Lazily imports the Copilot SDK to avoid module resolution errors at CLI startup.
@@ -35,7 +36,7 @@ export const createSession = async (options: SessionOptions): Promise<CopilotSes
   const { ctx, config, defaultToolTimeoutMs } = options;
 
   const { CopilotClient, defineTool, approveAll } = await loadCopilotSdk();
-  const client = new CopilotClient({ autoStart: true });
+  const client = new CopilotClient();
   await client.start();
 
   const fileTools = [
@@ -44,6 +45,7 @@ export const createSession = async (options: SessionOptions): Promise<CopilotSes
     createAppendFileTool(ctx.outDir, defineTool),
   ];
 
+  // Combine built-in browser and file tools with any caller-supplied tools
   const tools = [
     ...createBrowserTools(defineTool, {
       cwd: ctx.outDir,

package/src/commands/app/format-plan.ts

@@ -0,0 +1,26 @@
+import chalk from 'chalk';
+
+import type { Plan } from './types.js';
+import { truncate } from './truncate.js';
+
+/**
+ * Renders a structured plan as a human-readable summary.
+ *
+ * @param plan - The plan to render, containing a summary and ordered steps.
+ * @returns A multi-line string suitable for console output.
+ */
+export function formatPlan(plan: Plan): string {
+  const lines = [
+    '',
+    chalk.bold(`📋 ${plan.summary}`),
+    '',
+    ...plan.steps.flatMap((s, si) => [
+      `  ${chalk.dim(`${si + 1}.`)} ${s.scenario}`,
+      ...s.criteria
+        // Truncate each criterion so long descriptions don't wrap the terminal
+        .map((c) => chalk.dim(`     • ${truncate(c, 70)}`)),
+    ]),
+    '',
+  ];
+  return lines.join('\n');
+}

package/src/commands/app/format-step-result.ts

@@ -0,0 +1,16 @@
+import chalk from 'chalk';
+
+import type { StepResult } from './types.js';
+import { statusIcon } from './status-icon.js';
+
+/**
+ * Renders a single step execution result.
+ *
+ * @param result - The step result to render, including its outcome, note, and evidence.
+ * @returns A formatted two-line string describing the step outcome.
+ */
+export function formatStepResult(result: StepResult): string {
+  const icon = statusIcon(result.ok);
+  const files = result.evidence.length ? chalk.dim(` [${result.evidence.join(', ')}]`) : '';
+  return `  ${icon}  ${result.criterion}\n${chalk.dim(`     ${result.note}`)}${files}`;
+}

package/src/commands/app/format-verdict.ts

@@ -0,0 +1,43 @@
+import chalk from 'chalk';
+
+import type { Verdict } from './types.js';
+import { statusIcon } from './status-icon.js';
+
+/**
+ * Renders the final verdict as a full-width coloured report.
+ *
+ * @param verdict - The verdict to render, including per-step results, reasoning, and UX feedback.
+ * @returns A multi-line string suitable for console output.
+ */
+export function formatVerdict(verdict: Verdict): string {
+  const bar = '═'.repeat(60);
+  const banner = verdict.pass
+    ? chalk.bgGreen.black.bold(' ✅ PASS ')
+    : chalk.bgRed.white.bold(' ❌ FAIL ');
+
+  const lines = [
+    '',
+    bar,
+    `  ${banner}`,
+    bar,
+    '',
+    ...verdict.steps
+      // Render each step's outcome as a status glyph, criterion, and note
+      .map((s) => `  ${statusIcon(s.ok)}  ${s.criterion}\n${chalk.dim(`     ${s.note}`)}`),
+    '',
+    chalk.dim(`  ${verdict.reasoning}`),
+    '',
+  ];
+
+  // Append optional UX feedback only when the judge actually provided any
+  if (verdict.ux && verdict.ux.length > 0) {
+    lines.push(chalk.bold('  💡 UX Feedback'), '');
+    // List every UX hint as its own bullet line
+    for (const hint of verdict.ux) {
+      lines.push(chalk.yellow(`  • ${hint}`));
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}

package/src/commands/app/prompts/{judge.prompt.ts → create-judge-prompt.ts}

@@ -19,6 +19,7 @@ function collectEvidence(outDir: string): string {
 
   // ── executions.jsonl ──
   const execPath = join(outDir, 'executions.jsonl');
+  // Fall back to a placeholder note when the executions log is missing
   if (existsSync(execPath)) {
     parts.push('### executions.jsonl', readFileSync(execPath, 'utf-8').trim());
   } else {
@@ -27,10 +28,13 @@ function collectEvidence(outDir: string): string {
 
   // ── evidence/ directory ──
   const evidenceDir = join(outDir, 'evidence');
+  // Only scan for evidence files when the directory actually exists
   if (existsSync(evidenceDir)) {
     const files = readdirSync(evidenceDir).sort();
+    // Inline readable text evidence; list binary evidence by name only
     for (const file of files) {
       const ext = extname(file).toLowerCase();
+      // Inline the content of readable text extensions; list other files by name only
       if (TEXT_EXTENSIONS.has(ext)) {
         const content = readFileSync(join(evidenceDir, file), 'utf-8').trim();
         parts.push(`### evidence/${file}`, content);

package/src/commands/app/prompts/{step.prompt.ts → create-step-prompt.ts}

@@ -10,8 +10,9 @@ import type { PlanStep, RuntimeExecutionContext } from '../types.js';
  * @param ctx - Runtime context with output directory and app URL
  * @returns The fully interpolated prompt string
  */
-export const createStepPrompt = (step: PlanStep, ctx: RuntimeExecutionContext): string => {
+export const createStepPrompt = (step: PlanStep, _ctx: RuntimeExecutionContext): string => {
   const slug = slugify(step.scenario);
+  // Render each criterion with its expected pass/fail evidence for the prompt
   const criteriaBlock = step.criteria
     .map((c, i) => `${i + 1}. ${c}\n   Pass: ${step.pass[i] ?? ''}\n   Fail: ${step.fail[i] ?? ''}`)
     .join('\n');

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;
+}