@mindstudio-ai/remy 0.1.26 → 0.1.27

package/dist/headless.js

@@ -1,7 +1,7 @@
 // src/headless.ts
 import { createInterface } from "readline";
-import fs20 from "fs";
-import path13 from "path";
+import fs21 from "fs";
+import path14 from "path";
 
 // src/config.ts
 import fs2 from "fs";
@@ -300,14 +300,11 @@ function buildSystemPrompt(onboardingState, viewContext) {
     loadSpecFileMetadata(),
     loadProjectFileListing()
   ].filter(Boolean).join("\n");
-  const now = (/* @__PURE__ */ new Date()).toLocaleString("en-US", {
-    dateStyle: "full",
-    timeStyle: "long"
-  });
+  const now = (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").replace(/\.\d+Z$/, " UTC");
   const template = `
 {{static/identity.md}}
 
-The current date is ${now}.
+Current date/time: ${now}
 
 <platform_docs>
   <platform>
@@ -1142,7 +1139,7 @@ var promptUserTool = {
                     }
                   ]
                 },
-                description: "Options for select and checklist types. Each can be a string or { label, description }."
+                description: "Options for select and checklist types. Each can be a string or { label, description }. Image URLs (e.g. https://i.mscdn.ai/...) are rendered as visual previews, so use the URL directly as the option string when presenting images for the user to choose between."
               },
               multiple: {
                 type: "boolean",
@@ -1243,27 +1240,75 @@ var confirmDestructiveActionTool = {
 };
 
 // src/subagents/common/runCli.ts
-import { exec } from "child_process";
+import { spawn } from "child_process";
 function runCli(cmd, options) {
   return new Promise((resolve) => {
-    exec(
-      cmd,
-      {
-        timeout: options?.timeout ?? 6e4,
-        maxBuffer: options?.maxBuffer ?? 1024 * 1024
-      },
-      (err, stdout, stderr) => {
-        if (stdout.trim()) {
-          resolve(stdout.trim());
-          return;
+    const timeout = options?.timeout ?? 6e4;
+    const maxBuffer = options?.maxBuffer ?? 1024 * 1024;
+    const cmdWithLogs = options?.jsonLogs && !cmd.includes("--json-logs") ? cmd.replace(/^(mindstudio\s+\S+)/, "$1 --json-logs") : cmd;
+    const child = spawn("sh", ["-c", cmdWithLogs], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const logs = [];
+    let stdout = "";
+    let stderr = "";
+    let stdoutSize = 0;
+    let stderrSize = 0;
+    let killed = false;
+    child.stdout.on("data", (chunk) => {
+      stdoutSize += chunk.length;
+      if (stdoutSize <= maxBuffer) {
+        stdout += chunk.toString();
+      } else if (!killed) {
+        killed = true;
+        child.kill();
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderrSize += chunk.length;
+      if (stderrSize > maxBuffer) {
+        if (!killed) {
+          killed = true;
+          child.kill();
         }
-        if (err) {
-          resolve(`Error: ${stderr.trim() || err.message}`);
-          return;
+        return;
+      }
+      const text = chunk.toString();
+      stderr += text;
+      for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed[0] !== "{") {
+          continue;
+        }
+        try {
+          const entry = JSON.parse(trimmed);
+          if (entry.type === "log" && entry.value) {
+            const prefix = entry.tag ? `[${entry.tag}]` : "[log]";
+            logs.push(`${prefix} ${entry.value}`);
+          }
+        } catch {
         }
-        resolve("(no response)");
       }
-    );
+    });
+    const timer = setTimeout(() => {
+      killed = true;
+      child.kill();
+    }, timeout);
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      const logBlock = logs.length > 0 ? logs.join("\n") + "\n\n" : "";
+      const out = stdout.trim();
+      if (out) {
+        resolve(logBlock + out);
+        return;
+      }
+      if (code !== 0 || killed) {
+        const errMsg = stderr.trim() || (killed ? "Process timed out" : `Exit code ${code}`);
+        resolve(logBlock + `Error: ${errMsg}`);
+        return;
+      }
+      resolve(logBlock + "(no response)");
+    });
   });
 }
 
@@ -1670,7 +1715,7 @@ ${unifiedDiff(input.path, content, updated)}`;
 };
 
 // src/tools/code/bash.ts
-import { exec as exec2 } from "child_process";
+import { exec } from "child_process";
 var DEFAULT_TIMEOUT_MS = 12e4;
 var DEFAULT_MAX_LINES3 = 500;
 var bashTool = {
@@ -1704,7 +1749,7 @@ var bashTool = {
     const maxLines = input.maxLines === 0 ? Infinity : input.maxLines || DEFAULT_MAX_LINES3;
     const timeoutMs = input.timeout ? input.timeout * 1e3 : DEFAULT_TIMEOUT_MS;
     return new Promise((resolve) => {
-      exec2(
+      exec(
         input.command,
         {
           timeout: timeoutMs,
@@ -1744,7 +1789,7 @@ var bashTool = {
 };
 
 // src/tools/code/grep.ts
-import { exec as exec3 } from "child_process";
+import { exec as exec2 } from "child_process";
 var DEFAULT_MAX = 50;
 function formatResults(stdout, max) {
   const lines = stdout.trim().split("\n");
@@ -1791,12 +1836,12 @@ var grepTool = {
     const rgCmd = `rg -n --no-heading --max-count=${max}${globFlag} '${escaped}' ${searchPath}`;
     const grepCmd = `grep -rn --max-count=${max} '${escaped}' ${searchPath} --include='*.ts' --include='*.tsx' --include='*.js' --include='*.json' --include='*.md'`;
     return new Promise((resolve) => {
-      exec3(rgCmd, { maxBuffer: 512 * 1024 }, (err, stdout) => {
+      exec2(rgCmd, { maxBuffer: 512 * 1024 }, (err, stdout) => {
         if (stdout?.trim()) {
           resolve(formatResults(stdout, max));
           return;
         }
-        exec3(grepCmd, { maxBuffer: 512 * 1024 }, (_err, grepStdout) => {
+        exec2(grepCmd, { maxBuffer: 512 * 1024 }, (_err, grepStdout) => {
           if (grepStdout?.trim()) {
             resolve(formatResults(grepStdout, max));
           } else {
@@ -2027,36 +2072,64 @@ var runMethodTool = {
   }
 };
 
+// src/tools/_helpers/screenshot.ts
+var SCREENSHOT_ANALYSIS_PROMPT = "Describe everything visible on screen from top to bottom \u2014 every element, its position, its size relative to the viewport, its colors, its content. Be thorough and spatial. After the inventory, note anything that looks visually broken (overlapping elements, clipped text, misaligned components).";
+async function captureAndAnalyzeScreenshot(promptOrOptions) {
+  let prompt;
+  let viewportOnly = false;
+  if (typeof promptOrOptions === "object" && promptOrOptions !== null) {
+    prompt = promptOrOptions.prompt;
+    viewportOnly = promptOrOptions.viewportOnly ?? false;
+  } else {
+    prompt = promptOrOptions;
+  }
+  const ssResult = await sidecarRequest(
+    "/screenshot",
+    { fullPage: !viewportOnly },
+    { timeout: 12e4 }
+  );
+  log.debug("Screenshot response", { ssResult });
+  const url = ssResult?.url || ssResult?.screenshotUrl;
+  if (!url) {
+    throw new Error(
+      `No URL in sidecar response. The browser may not be ready yet. Response: ${JSON.stringify(ssResult)}`
+    );
+  }
+  if (prompt === false) {
+    return url;
+  }
+  const analysisPrompt = prompt || SCREENSHOT_ANALYSIS_PROMPT;
+  const analysis = await runCli(
+    `mindstudio analyze-image --prompt ${JSON.stringify(analysisPrompt)} --image-url ${JSON.stringify(url)} --output-key analysis --no-meta`
+  );
+  return JSON.stringify({ url, analysis });
+}
+
 // src/tools/code/screenshot.ts
-var DEFAULT_PROMPT = "Describe this app screenshot for a developer who cannot see it. What is visible on screen: the layout, content, interactive elements, any loading or error states. Be concise and factual.";
 var screenshotTool = {
   definition: {
     name: "screenshot",
-    description: "Capture a screenshot of the app preview and get a description of what's on screen. Optionally provide a specific question about what you're looking for.",
+    description: "Capture a screenshot of the app preview and get a description of what's on screen. Optionally provide a specific question about what you're looking for. Set viewportOnly to capture just what the user sees on screen.",
     inputSchema: {
       type: "object",
       properties: {
         prompt: {
           type: "string",
           description: "Optional question about the screenshot. If omitted, returns a general description of what's visible."
+        },
+        viewportOnly: {
+          type: "boolean",
+          description: "Capture only the visible viewport instead of the full scrollable page. Use when checking above-the-fold layout or viewport-relative sizing like 100vh."
         }
       }
     }
   },
   async execute(input) {
     try {
-      const { url } = await sidecarRequest(
-        "/screenshot",
-        {},
-        { timeout: 12e4 }
-      );
-      const analysisPrompt = input.prompt || DEFAULT_PROMPT;
-      const analysis = await runCli(
-        `mindstudio analyze-image --prompt ${JSON.stringify(analysisPrompt)} --image-url ${JSON.stringify(url)} --output-key analysis --no-meta`
-      );
-      return `Screenshot: ${url}
-
-${analysis}`;
+      return await captureAndAnalyzeScreenshot({
+        prompt: input.prompt,
+        viewportOnly: input.viewportOnly
+      });
     } catch (err) {
       return `Error taking screenshot: ${err.message}`;
     }
@@ -2124,7 +2197,9 @@ async function runSubAgent(config) {
         ...apiConfig,
         model,
         subAgentId,
-        system,
+        system: `${system}
+
+Current date/time: ${(/* @__PURE__ */ new Date()).toISOString().replace("T", " ").replace(/\.\d+Z$/, " UTC")}`,
         messages: cleanMessagesForApi(messages),
         tools,
         signal
@@ -2244,6 +2319,13 @@ async function runSubAgent(config) {
       })
     );
     for (const r of results) {
+      const block = contentBlocks.find(
+        (b) => b.type === "tool" && b.id === r.id
+      );
+      if (block?.type === "tool") {
+        block.result = r.result;
+        block.isError = r.isError;
+      }
       messages.push({
         role: "user",
         content: r.result,
@@ -2269,8 +2351,18 @@ var BROWSER_TOOLS = [
             properties: {
               command: {
                 type: "string",
-                enum: ["snapshot", "click", "type", "wait", "evaluate"],
-                description: "snapshot: accessibility tree of the page (waits for network to settle). click: click an element (animated cursor, full event sequence). type: type text into input (one char at a time, works with React/Vue/Svelte). wait: wait for an element to appear (polls 100ms, waits for network). evaluate: run JS in the page."
+                enum: [
+                  "snapshot",
+                  "click",
+                  "type",
+                  "select",
+                  "wait",
+                  "navigate",
+                  "evaluate",
+                  "styles",
+                  "screenshot"
+                ],
+                description: "snapshot: accessibility tree of the page (waits for network to settle). click: click an element (animated cursor, full event sequence). type: type text into input (one char at a time, works with React/Vue/Svelte). select: select a dropdown option by text. wait: wait for an element to appear (polls 100ms, waits for network). navigate: navigate to a URL within the app (waits for load, subsequent steps run on new page). evaluate: run JS in the page. styles: read computed CSS styles from elements (pass properties array with camelCase names, or omit for defaults). screenshot: full-page viewport-stitched screenshot (returns base64 JPEG with dimensions)."
               },
               ref: {
                 type: "string",
@@ -2292,6 +2384,10 @@ var BROWSER_TOOLS = [
                 type: "string",
                 description: "CSS selector fallback (last resort)."
               },
+              option: {
+                type: "string",
+                description: "For select: the option text to select from a dropdown."
+              },
               clear: {
                 type: "boolean",
                 description: "For type: clear the field before typing."
@@ -2303,6 +2399,15 @@ var BROWSER_TOOLS = [
               script: {
                 type: "string",
                 description: "For evaluate: JavaScript to run in the page."
+              },
+              url: {
+                type: "string",
+                description: 'For navigate: the URL to navigate to (e.g., "/quiz", "/settings").'
+              },
+              properties: {
+                type: "array",
+                items: { type: "string" },
+                description: 'For styles: camelCase CSS property names to read (e.g., ["backgroundColor", "borderRadius", "fontSize"]). Omit for a default set.'
               }
             },
             required: ["command"]
@@ -2329,7 +2434,7 @@ var BROWSER_TOOLS = [
     }
   }
 ];
-var BROWSER_EXTERNAL_TOOLS = /* @__PURE__ */ new Set(["browserCommand", "screenshot"]);
+var BROWSER_EXTERNAL_TOOLS = /* @__PURE__ */ new Set(["browserCommand"]);
 
 // src/subagents/browserAutomation/prompt.ts
 import fs13 from "fs";
@@ -2355,13 +2460,13 @@ ${appSpec}
 var browserAutomationTool = {
   definition: {
     name: "runAutomatedBrowserTest",
-    description: "Run an automated browser test against the live preview. The test agent always starts on the main page, so include navigation instructions if the test involves a sub-page. The browser uses the current user roles and dev database state, so run a scenario first if you need specific data or roles. Use after writing or modifying frontend code, to reproduce user-reported issues, or to test end-to-end flows.",
+    description: "Run an automated browser test against the live preview. Describe what to test \u2014 the agent figures out how. Use after writing or modifying frontend code, to reproduce user-reported issues, or to test end-to-end flows.",
     inputSchema: {
       type: "object",
       properties: {
         task: {
           type: "string",
-          description: "What to test, in natural language. Include how to navigate to the relevant page and what data/roles to expect."
+          description: "What to test, in natural language. Keep it brief \u2014 the agent reads the spec and figures out navigation, data setup, and test strategy on its own."
         }
       },
       required: ["task"]
@@ -2389,6 +2494,13 @@ var browserAutomationTool = {
       tools: BROWSER_TOOLS,
       externalTools: BROWSER_EXTERNAL_TOOLS,
       executeTool: async (name) => {
+        if (name === "screenshot") {
+          try {
+            return await captureAndAnalyzeScreenshot();
+          } catch (err) {
+            return `Error taking screenshot: ${err.message}`;
+          }
+        }
         if (name === "resetBrowser") {
           try {
             await sidecarRequest("/reset-browser", {}, { timeout: 5e3 });
@@ -2405,7 +2517,50 @@ var browserAutomationTool = {
       signal: context.signal,
       parentToolId: context.toolCallId,
       onEvent: context.onEvent,
-      resolveExternalTool: context.resolveExternalTool
+      resolveExternalTool: async (id, name, input2) => {
+        if (!context.resolveExternalTool) {
+          return "Error: no external tool resolver";
+        }
+        const result2 = await context.resolveExternalTool(id, name, input2);
+        if (name === "browserCommand") {
+          try {
+            const parsed = JSON.parse(result2);
+            const screenshotSteps = (parsed.steps || []).filter(
+              (s) => s.command === "screenshot" && s.result?.url
+            );
+            if (screenshotSteps.length > 0) {
+              const batchInput = screenshotSteps.map((s) => ({
+                stepType: "analyzeImage",
+                step: {
+                  imageUrl: s.result.url,
+                  prompt: SCREENSHOT_ANALYSIS_PROMPT
+                }
+              }));
+              const batchResult = await runCli(
+                `mindstudio batch --no-meta ${JSON.stringify(JSON.stringify(batchInput))}`,
+                { timeout: 12e4 }
+              );
+              try {
+                const analyses = JSON.parse(batchResult);
+                let ai = 0;
+                for (const step of parsed.steps) {
+                  if (step.command === "screenshot" && step.result?.url && ai < analyses.length) {
+                    step.result.analysis = analyses[ai]?.output?.analysis || analyses[ai]?.output || "";
+                    ai++;
+                  }
+                }
+              } catch {
+                log.debug("Failed to parse batch analysis result", {
+                  batchResult
+                });
+              }
+              return JSON.stringify(parsed);
+            }
+          } catch {
+          }
+        }
+        return result2;
+      }
     });
     context.subAgentMessages?.set(context.toolCallId, result.messages);
     return result.text;
@@ -2413,13 +2568,14 @@ var browserAutomationTool = {
 };
 
 // src/subagents/designExpert/tools.ts
-var DESIGN_REFERENCE_PROMPT = `Analyze this website/app screenshot as a design reference. Assess:
-1) Mood/aesthetic
-2) Color palette with approximate hex values and palette strategy
-3) Typography style
-4) Layout composition (symmetric/asymmetric, grid structure, whitespace usage, content density)
-5) What makes it distinctive and interesting vs generic AI-generated interfaces
-Be specific and concise.`;
+import fs14 from "fs";
+import path8 from "path";
+var base2 = import.meta.dirname ?? path8.dirname(new URL(import.meta.url).pathname);
+function resolvePath(filename) {
+  const local4 = path8.join(base2, filename);
+  return fs14.existsSync(local4) ? local4 : path8.join(base2, "subagents", "designExpert", filename);
+}
+var DESIGN_REFERENCE_PROMPT = fs14.readFileSync(resolvePath("prompts/tool-prompts/design-analysis.md"), "utf-8").trim();
 var DESIGN_EXPERT_TOOLS = [
   {
     name: "searchGoogle",
@@ -2473,24 +2629,33 @@ var DESIGN_EXPERT_TOOLS = [
   },
   {
     name: "screenshot",
-    description: "Capture a screenshot of the app preview. Returns a CDN URL. Use to review the current state of the UI being built.",
+    description: "Capture a screenshot of the app preview. Returns a CDN URL with visual analysis. Use to review the current state of the UI being built. Set viewportOnly to capture just what the user sees on screen.",
     inputSchema: {
       type: "object",
-      properties: {}
+      properties: {
+        prompt: {
+          type: "string",
+          description: "Optional specific question about the screenshot."
+        },
+        viewportOnly: {
+          type: "boolean",
+          description: "Capture only the visible viewport instead of the full scrollable page. Use when checking above-the-fold layout or viewport-relative sizing like 100vh."
+        }
+      }
     }
   },
   {
-    name: "searchProductScreenshots",
-    description: 'Search for screenshots of real products and apps. Use to find what existing products look like ("stripe dashboard", "linear app", "notion workspace"). Returns image results of actual product UI. Use this for layout and design research on real products, NOT for abstract design inspiration.',
+    name: "runBrowserTest",
+    description: "Run an automated browser test against the live app preview. Use to verify visual implementation: check computed styles, navigate between pages, take analyzed screenshots. Describe what you want to verify and the browser agent handles the interaction.",
     inputSchema: {
       type: "object",
       properties: {
-        product: {
+        task: {
           type: "string",
-          description: 'The product or app to find screenshots of (e.g., "stripe dashboard", "figma editor", "mercury banking app").'
+          description: 'What to verify, in natural language. E.g., "Check that the hero section cards have border-radius: 24px and the correct rotation angles" or "Navigate to /about and screenshot it".'
         }
       },
-      required: ["product"]
+      required: ["task"]
     }
   },
   {
@@ -2519,22 +2684,14 @@ var DESIGN_EXPERT_TOOLS = [
     }
   }
 ];
-async function executeDesignExpertTool(name, input) {
+async function executeDesignExpertTool(name, input, context) {
   switch (name) {
     case "screenshot": {
       try {
-        const { url } = await sidecarRequest(
-          "/screenshot",
-          {},
-          { timeout: 12e4 }
-        );
-        const analysisPrompt = input.prompt || "Describe this app screenshot for a visual designer reviewing the current state. What is visible: layout, typography, colors, spacing, imagery. Note anything that looks broken or off. Be concise.";
-        const analysis = await runCli(
-          `mindstudio analyze-image --prompt ${JSON.stringify(analysisPrompt)} --image-url ${JSON.stringify(url)} --output-key analysis --no-meta`
-        );
-        return `Screenshot: ${url}
-
-${analysis}`;
+        return await captureAndAnalyzeScreenshot({
+          prompt: input.prompt,
+          viewportOnly: input.viewportOnly
+        });
       } catch (err) {
         return `Error taking screenshot: ${err.message}`;
       }
@@ -2573,12 +2730,6 @@ ${analysis}`;
 
 ${analysis}`;
     }
-    case "searchProductScreenshots": {
-      const query = `${input.product} product screenshot UI 2026`;
-      return runCli(
-        `mindstudio search-google-images --query ${JSON.stringify(query)} --export-type json --output-key images --no-meta`
-      );
-    }
     case "generateImages": {
       const prompts = input.prompts;
       const width = input.width || 2048;
@@ -2594,7 +2745,8 @@ ${analysis}`;
           }
         });
         const url = await runCli(
-          `mindstudio generate-image '${step}' --output-key imageUrl --no-meta`
+          `mindstudio generate-image '${step}' --output-key imageUrl --no-meta`,
+          { jsonLogs: true }
         );
         imageUrls = [url];
       } else {
@@ -2609,7 +2761,8 @@ ${analysis}`;
           }
         }));
         const batchResult = await runCli(
-          `mindstudio batch '${JSON.stringify(steps)}' --no-meta`
+          `mindstudio batch '${JSON.stringify(steps)}' --no-meta`,
+          { jsonLogs: true }
         );
         try {
           const parsed = JSON.parse(batchResult);
@@ -2620,20 +2773,24 @@ ${analysis}`;
           return batchResult;
         }
       }
-      const analyses = await Promise.all(
+      const images = await Promise.all(
         imageUrls.map(async (url, i) => {
           if (url.startsWith("Error")) {
-            return `Image ${i + 1}: ${url}`;
+            return { prompt: prompts[i], error: url };
           }
           const analysis = await runCli(
             `mindstudio analyze-image --prompt ${JSON.stringify(ANALYZE_PROMPT)} --image-url ${JSON.stringify(url)} --output-key analysis --no-meta`
           );
-          return `**Image ${i + 1}:** ${url}
-Prompt: ${prompts[i]}
-Analysis: ${analysis}`;
+          return { url, prompt: prompts[i], analysis, width, height };
         })
       );
-      return analyses.join("\n\n");
+      return `%%JSON%%${JSON.stringify({ images })}`;
+    }
+    case "runBrowserTest": {
+      if (!context) {
+        return "Error: browser testing requires execution context (only available in headless mode)";
+      }
+      return browserAutomationTool.execute({ task: input.task }, context);
     }
     default:
       return `Error: unknown tool "${name}"`;
@@ -2641,17 +2798,17 @@ Analysis: ${analysis}`;
 }
 
 // src/subagents/designExpert/prompt.ts
-import fs15 from "fs";
-import path9 from "path";
+import fs16 from "fs";
+import path10 from "path";
 
 // src/subagents/common/context.ts
-import fs14 from "fs";
-import path8 from "path";
+import fs15 from "fs";
+import path9 from "path";
 function walkMdFiles2(dir, skip) {
   const files = [];
   try {
-    for (const entry of fs14.readdirSync(dir, { withFileTypes: true })) {
-      const full = path8.join(dir, entry.name);
+    for (const entry of fs15.readdirSync(dir, { withFileTypes: true })) {
+      const full = path9.join(dir, entry.name);
       if (entry.isDirectory()) {
         if (!skip?.has(entry.name)) {
           files.push(...walkMdFiles2(full, skip));
@@ -2671,7 +2828,7 @@ function loadFilesAsXml(dir, tag, skip) {
   }
   const sections = files.map((f) => {
     try {
-      const content = fs14.readFileSync(f, "utf-8").trim();
+      const content = fs15.readFileSync(f, "utf-8").trim();
       return `<file path="${f}">
 ${content}
 </file>`;
@@ -2741,17 +2898,17 @@ The first-party SDK (@mindstudio-ai/agent) provides access to 200+ AI models (Op
 }
 
 // src/subagents/designExpert/prompt.ts
-var base2 = import.meta.dirname ?? path9.dirname(new URL(import.meta.url).pathname);
-function resolvePath(filename) {
-  const local4 = path9.join(base2, filename);
-  return fs15.existsSync(local4) ? local4 : path9.join(base2, "subagents", "designExpert", filename);
+var base3 = import.meta.dirname ?? path10.dirname(new URL(import.meta.url).pathname);
+function resolvePath2(filename) {
+  const local4 = path10.join(base3, filename);
+  return fs16.existsSync(local4) ? local4 : path10.join(base3, "subagents", "designExpert", filename);
 }
 function readFile(filename) {
-  return fs15.readFileSync(resolvePath(filename), "utf-8").trim();
+  return fs16.readFileSync(resolvePath2(filename), "utf-8").trim();
 }
 function readJson(filename, fallback) {
   try {
-    return JSON.parse(fs15.readFileSync(resolvePath(filename), "utf-8"));
+    return JSON.parse(fs16.readFileSync(resolvePath2(filename), "utf-8"));
   } catch {
     return fallback;
   }
@@ -2788,7 +2945,6 @@ function getDesignExpertPrompt() {
   const pairings = sample(fontData.pairings, 20);
   const images = sample(inspirationImages, 15);
   const fontList = fonts.map((f) => {
-    const tags = f.tags.length ? ` (${f.tags.join(", ")})` : "";
     let cssInfo = "";
     if (f.source === "fontshare") {
       cssInfo = ` CSS: ${fontData.cssUrlPattern.replace("{slug}", f.slug).replace("{weights}", f.weights.join(","))}`;
@@ -2797,7 +2953,8 @@ function getDesignExpertPrompt() {
     } else if (f.source === "open-foundry") {
       cssInfo = " (self-host required)";
     }
-    return `- **${f.name}** \u2014 ${f.category}${tags}. Weights: ${f.weights.join(", ")}.${f.variable ? " Variable." : ""}${f.italics ? " Has italics." : ""}${cssInfo}`;
+    const desc = f.description ? ` ${f.description}` : "";
+    return `- **${f.name}** \u2014 ${f.category}. Weights: ${f.weights.join(", ")}.${f.variable ? " Variable." : ""}${f.italics ? " Has italics." : ""}${cssInfo}${desc}`;
   }).join("\n");
   const pairingList = pairings.map(
     (p) => `- **${p.heading.font}** (${p.heading.weight}) heading + **${p.body.font}** (${p.body.weight}) body`
@@ -2815,13 +2972,13 @@ ${fontList}
 ${pairingList}
 </fonts_to_consider>` : "";
   const imageList = images.map((img) => `- ${img.analysis}`).join("\n\n");
-  const inspirationSection = images.length ? `<inspiration_images>
+  const inspirationSection = images.length ? `<design_inspiration>
 ## Design inspiration
 
-This is what the bar looks like. These are real sites that made it onto curated design galleries because they did something bold, intentional, and memorable. Study the moves they make \u2014 the confident color choices, the unexpected layouts, the typography that carries the whole page. Your recommendations should feel like they belong in this company.
+This is what the bar looks like. These are real sites that made it onto curated design galleries because they did something bold, intentional, and memorable. Use them as inspiration and let the takeaways guide your work. Your designs should feel like they belong in this company.
 
 ${imageList}
-</inspiration_images>` : "";
+</design_inspiration>` : "";
   const specContext = loadSpecContext();
   let prompt = PROMPT_TEMPLATE.replace(
     "{{fonts_to_consider}}",
@@ -2863,7 +3020,7 @@ var designExpertTool = {
       task: input.task,
       tools: DESIGN_EXPERT_TOOLS,
       externalTools: /* @__PURE__ */ new Set(),
-      executeTool: executeDesignExpertTool,
+      executeTool: (name, input2) => executeDesignExpertTool(name, input2, context),
       apiConfig: context.apiConfig,
       model: context.model,
       subAgentId: "visualDesignExpert",
@@ -2976,8 +3133,8 @@ var VISION_TOOLS = [
 ];
 
 // src/subagents/productVision/executor.ts
-import fs16 from "fs";
-import path10 from "path";
+import fs17 from "fs";
+import path11 from "path";
 var ROADMAP_DIR = "src/roadmap";
 function formatRequires(requires) {
   return requires.length === 0 ? "[]" : `[${requires.map((r) => `"${r}"`).join(", ")}]`;
@@ -2993,9 +3150,10 @@ async function executeVisionTool(name, input) {
         requires,
         body
       } = input;
-      const filePath = path10.join(ROADMAP_DIR, `${slug}.md`);
+      const filePath = path11.join(ROADMAP_DIR, `${slug}.md`);
       try {
-        fs16.mkdirSync(ROADMAP_DIR, { recursive: true });
+        fs17.mkdirSync(ROADMAP_DIR, { recursive: true });
+        const oldContent = fs17.existsSync(filePath) ? fs17.readFileSync(filePath, "utf-8") : "";
         const content = `---
 name: ${itemName}
 type: roadmap
@@ -3007,20 +3165,24 @@ requires: ${formatRequires(requires)}
 
 ${body}
 `;
-        fs16.writeFileSync(filePath, content, "utf-8");
-        return `Wrote ${filePath}`;
+        fs17.writeFileSync(filePath, content, "utf-8");
+        const lineCount = content.split("\n").length;
+        const label = oldContent ? "Updated" : "Wrote";
+        return `${label} ${filePath} (${lineCount} lines)
+${unifiedDiff(filePath, oldContent, content)}`;
       } catch (err) {
         return `Error writing ${filePath}: ${err.message}`;
       }
     }
     case "updateRoadmapItem": {
       const { slug } = input;
-      const filePath = path10.join(ROADMAP_DIR, `${slug}.md`);
+      const filePath = path11.join(ROADMAP_DIR, `${slug}.md`);
       try {
-        if (!fs16.existsSync(filePath)) {
+        if (!fs17.existsSync(filePath)) {
           return `Error: ${filePath} does not exist`;
         }
-        let content = fs16.readFileSync(filePath, "utf-8");
+        const oldContent = fs17.readFileSync(filePath, "utf-8");
+        let content = oldContent;
         if (input.status) {
           content = content.replace(
             /^status:\s*.+$/m,
@@ -3072,21 +3234,25 @@ ${input.appendHistory}
 `;
           }
         }
-        fs16.writeFileSync(filePath, content, "utf-8");
-        return `Updated ${filePath}`;
+        fs17.writeFileSync(filePath, content, "utf-8");
+        const lineCount = content.split("\n").length;
+        return `Updated ${filePath} (${lineCount} lines)
+${unifiedDiff(filePath, oldContent, content)}`;
       } catch (err) {
         return `Error updating ${filePath}: ${err.message}`;
       }
     }
     case "deleteRoadmapItem": {
       const { slug } = input;
-      const filePath = path10.join(ROADMAP_DIR, `${slug}.md`);
+      const filePath = path11.join(ROADMAP_DIR, `${slug}.md`);
       try {
-        if (!fs16.existsSync(filePath)) {
+        if (!fs17.existsSync(filePath)) {
           return `Error: ${filePath} does not exist`;
         }
-        fs16.unlinkSync(filePath);
-        return `Deleted ${filePath}`;
+        const oldContent = fs17.readFileSync(filePath, "utf-8");
+        fs17.unlinkSync(filePath);
+        return `Deleted ${filePath}
+${unifiedDiff(filePath, oldContent, "")}`;
       } catch (err) {
         return `Error deleting ${filePath}: ${err.message}`;
       }
@@ -3097,12 +3263,12 @@ ${input.appendHistory}
 }
 
 // src/subagents/productVision/prompt.ts
-import fs17 from "fs";
-import path11 from "path";
-var base3 = import.meta.dirname ?? path11.dirname(new URL(import.meta.url).pathname);
-var local2 = path11.join(base3, "prompt.md");
-var PROMPT_PATH2 = fs17.existsSync(local2) ? local2 : path11.join(base3, "subagents", "productVision", "prompt.md");
-var BASE_PROMPT2 = fs17.readFileSync(PROMPT_PATH2, "utf-8").trim();
+import fs18 from "fs";
+import path12 from "path";
+var base4 = import.meta.dirname ?? path12.dirname(new URL(import.meta.url).pathname);
+var local2 = path12.join(base4, "prompt.md");
+var PROMPT_PATH2 = fs18.existsSync(local2) ? local2 : path12.join(base4, "subagents", "productVision", "prompt.md");
+var BASE_PROMPT2 = fs18.readFileSync(PROMPT_PATH2, "utf-8").trim();
 function getProductVisionPrompt() {
   const specContext = loadSpecContext();
   const roadmapContext = loadRoadmapContext();
@@ -3156,8 +3322,8 @@ var productVisionTool = {
 };
 
 // src/subagents/codeSanityCheck/index.ts
-import fs18 from "fs";
-import path12 from "path";
+import fs19 from "fs";
+import path13 from "path";
 
 // src/subagents/codeSanityCheck/tools.ts
 var SANITY_CHECK_TOOLS = [
@@ -3251,10 +3417,10 @@ var SANITY_CHECK_TOOLS = [
 ];
 
 // src/subagents/codeSanityCheck/index.ts
-var base4 = import.meta.dirname ?? path12.dirname(new URL(import.meta.url).pathname);
-var local3 = path12.join(base4, "prompt.md");
-var PROMPT_PATH3 = fs18.existsSync(local3) ? local3 : path12.join(base4, "subagents", "codeSanityCheck", "prompt.md");
-var BASE_PROMPT3 = fs18.readFileSync(PROMPT_PATH3, "utf-8").trim();
+var base5 = import.meta.dirname ?? path13.dirname(new URL(import.meta.url).pathname);
+var local3 = path13.join(base5, "prompt.md");
+var PROMPT_PATH3 = fs19.existsSync(local3) ? local3 : path13.join(base5, "subagents", "codeSanityCheck", "prompt.md");
+var BASE_PROMPT3 = fs19.readFileSync(PROMPT_PATH3, "utf-8").trim();
 var codeSanityCheckTool = {
   definition: {
     name: "codeSanityCheck",
@@ -3381,11 +3547,11 @@ function executeTool(name, input, context) {
 }
 
 // src/session.ts
-import fs19 from "fs";
+import fs20 from "fs";
 var SESSION_FILE = ".remy-session.json";
 function loadSession(state) {
   try {
-    const raw = fs19.readFileSync(SESSION_FILE, "utf-8");
+    const raw = fs20.readFileSync(SESSION_FILE, "utf-8");
     const data = JSON.parse(raw);
     if (Array.isArray(data.messages) && data.messages.length > 0) {
       state.messages = sanitizeMessages(data.messages);
@@ -3433,7 +3599,7 @@ function sanitizeMessages(messages) {
 }
 function saveSession(state) {
   try {
-    fs19.writeFileSync(
+    fs20.writeFileSync(
       SESSION_FILE,
       JSON.stringify({ messages: state.messages }, null, 2),
       "utf-8"
@@ -3444,7 +3610,7 @@ function saveSession(state) {
 function clearSession(state) {
   state.messages = [];
   try {
-    fs19.unlinkSync(SESSION_FILE);
+    fs20.unlinkSync(SESSION_FILE);
   } catch {
   }
 }
@@ -4151,13 +4317,46 @@ async function runTurn(params) {
 }
 
 // src/headless.ts
-var BASE_DIR = import.meta.dirname ?? path13.dirname(new URL(import.meta.url).pathname);
-var ACTIONS_DIR = path13.join(BASE_DIR, "actions");
+var BASE_DIR = import.meta.dirname ?? path14.dirname(new URL(import.meta.url).pathname);
+var ACTIONS_DIR = path14.join(BASE_DIR, "actions");
 function loadActionPrompt(name) {
-  return fs20.readFileSync(path13.join(ACTIONS_DIR, `${name}.md`), "utf-8").trim();
+  return fs21.readFileSync(path14.join(ACTIONS_DIR, `${name}.md`), "utf-8").trim();
+}
+function emit(event, data, requestId) {
+  const payload = { event, ...data };
+  if (requestId) {
+    payload.requestId = requestId;
+  }
+  process.stdout.write(JSON.stringify(payload) + "\n");
 }
-function emit(event, data) {
-  process.stdout.write(JSON.stringify({ event, ...data }) + "\n");
+function handleGetHistory(state) {
+  return { messages: state.messages };
+}
+function handleClear(state) {
+  clearSession(state);
+  return {};
+}
+function handleCancel(currentAbort, pendingTools) {
+  if (currentAbort) {
+    currentAbort.abort();
+  }
+  for (const [id, pending] of pendingTools) {
+    clearTimeout(pending.timeout);
+    pending.resolve("Error: cancelled");
+    pendingTools.delete(id);
+  }
+  return {};
+}
+function dispatchSimple(requestId, eventName, handler) {
+  try {
+    const data = handler();
+    if (eventName) {
+      emit(eventName, data, requestId);
+    }
+    emit("completed", { success: true }, requestId);
+  } catch (err) {
+    emit("completed", { success: false, error: err.message }, requestId);
+  }
 }
 async function startHeadless(opts = {}) {
   const stderrWrite = (...args) => {
@@ -4176,72 +4375,15 @@ async function startHeadless(opts = {}) {
   const state = createAgentState();
   const resumed = loadSession(state);
   if (resumed) {
-    emit("session_restored", {
-      messageCount: state.messages.length
-    });
+    emit("session_restored", { messageCount: state.messages.length });
   }
   let running = false;
   let currentAbort = null;
+  let currentRequestId;
+  let completedEmitted = false;
   const EXTERNAL_TOOL_TIMEOUT_MS = 3e5;
   const pendingTools = /* @__PURE__ */ new Map();
   const earlyResults = /* @__PURE__ */ new Map();
-  function onEvent(e) {
-    switch (e.type) {
-      case "text":
-        emit("text", {
-          text: e.text,
-          ...e.parentToolId && { parentToolId: e.parentToolId }
-        });
-        break;
-      case "thinking":
-        emit("thinking", {
-          text: e.text,
-          ...e.parentToolId && { parentToolId: e.parentToolId }
-        });
-        break;
-      case "tool_input_delta":
-        emit("tool_input_delta", {
-          id: e.id,
-          name: e.name,
-          result: e.result,
-          ...e.parentToolId && { parentToolId: e.parentToolId }
-        });
-        break;
-      case "tool_start":
-        emit("tool_start", {
-          id: e.id,
-          name: e.name,
-          input: e.input,
-          ...e.partial && { partial: true },
-          ...e.parentToolId && { parentToolId: e.parentToolId }
-        });
-        break;
-      case "tool_done":
-        emit("tool_done", {
-          id: e.id,
-          name: e.name,
-          result: e.result,
-          isError: e.isError,
-          ...e.parentToolId && { parentToolId: e.parentToolId }
-        });
-        break;
-      case "turn_started":
-        emit("turn_started");
-        break;
-      case "turn_done":
-        emit("turn_done");
-        break;
-      case "turn_cancelled":
-        emit("turn_cancelled");
-        break;
-      case "error":
-        emit("error", { error: e.error });
-        break;
-      case "status":
-        emit("status", { message: e.message });
-        break;
-    }
-  }
   const USER_FACING_TOOLS = /* @__PURE__ */ new Set([
     "promptUser",
     "confirmDestructiveAction",
@@ -4272,6 +4414,158 @@ async function startHeadless(opts = {}) {
       });
     });
   }
+  function onEvent(e) {
+    const rid = currentRequestId;
+    switch (e.type) {
+      // Suppressed — caller already knows the request started
+      case "turn_started":
+        return;
+      // Terminal events — translate to `completed`
+      case "turn_done":
+        completedEmitted = true;
+        emit("completed", { success: true }, rid);
+        return;
+      case "turn_cancelled":
+        completedEmitted = true;
+        emit("completed", { success: false, error: "cancelled" }, rid);
+        return;
+      // Streaming events — forward with requestId
+      case "text":
+        emit(
+          "text",
+          {
+            text: e.text,
+            ...e.parentToolId && { parentToolId: e.parentToolId }
+          },
+          rid
+        );
+        return;
+      case "thinking":
+        emit(
+          "thinking",
+          {
+            text: e.text,
+            ...e.parentToolId && { parentToolId: e.parentToolId }
+          },
+          rid
+        );
+        return;
+      case "tool_input_delta":
+        emit(
+          "tool_input_delta",
+          {
+            id: e.id,
+            name: e.name,
+            result: e.result,
+            ...e.parentToolId && { parentToolId: e.parentToolId }
+          },
+          rid
+        );
+        return;
+      case "tool_start":
+        emit(
+          "tool_start",
+          {
+            id: e.id,
+            name: e.name,
+            input: e.input,
+            ...e.partial && { partial: true },
+            ...e.parentToolId && { parentToolId: e.parentToolId }
+          },
+          rid
+        );
+        return;
+      case "tool_done":
+        emit(
+          "tool_done",
+          {
+            id: e.id,
+            name: e.name,
+            result: e.result,
+            isError: e.isError,
+            ...e.parentToolId && { parentToolId: e.parentToolId }
+          },
+          rid
+        );
+        return;
+      case "status":
+        emit("status", { message: e.message }, rid);
+        return;
+      case "error":
+        emit("error", { error: e.error }, rid);
+        return;
+    }
+  }
+  async function handleMessage(parsed, requestId) {
+    if (running) {
+      emit(
+        "error",
+        { error: "Agent is already processing a message" },
+        requestId
+      );
+      emit(
+        "completed",
+        { success: false, error: "Agent is already processing a message" },
+        requestId
+      );
+      return;
+    }
+    running = true;
+    currentRequestId = requestId;
+    currentAbort = new AbortController();
+    completedEmitted = false;
+    const attachments = parsed.attachments;
+    if (attachments?.length) {
+      console.warn(
+        `[headless] Message has ${attachments.length} attachment(s):`,
+        attachments.map((a) => a.url)
+      );
+    }
+    let userMessage = parsed.text ?? "";
+    const isCommand = !!parsed.runCommand;
+    if (parsed.runCommand === "sync") {
+      userMessage = loadActionPrompt("sync");
+    } else if (parsed.runCommand === "publish") {
+      userMessage = loadActionPrompt("publish");
+    } else if (parsed.runCommand === "buildFromInitialSpec") {
+      userMessage = loadActionPrompt("buildFromInitialSpec");
+    }
+    const onboardingState = parsed.onboardingState ?? "onboardingFinished";
+    const system = buildSystemPrompt(
+      onboardingState,
+      parsed.viewContext
+    );
+    try {
+      await runTurn({
+        state,
+        userMessage,
+        attachments,
+        apiConfig: config,
+        system,
+        model: opts.model,
+        onboardingState,
+        signal: currentAbort.signal,
+        onEvent,
+        resolveExternalTool,
+        hidden: isCommand
+      });
+      if (!completedEmitted) {
+        emit(
+          "completed",
+          { success: false, error: "Turn ended unexpectedly" },
+          requestId
+        );
+      }
+    } catch (err) {
+      if (!completedEmitted) {
+        emit("error", { error: err.message }, requestId);
+        emit("completed", { success: false, error: err.message }, requestId);
+      }
+    }
+    currentAbort = null;
+    currentRequestId = void 0;
+    running = false;
+  }
   const rl = createInterface({ input: process.stdin });
   rl.on("line", async (line) => {
     let parsed;
@@ -4281,82 +4575,42 @@ async function startHeadless(opts = {}) {
       emit("error", { error: "Invalid JSON on stdin" });
       return;
     }
-    if (parsed.action === "tool_result" && parsed.id) {
-      const pending = pendingTools.get(parsed.id);
+    const { action, requestId } = parsed;
+    if (action === "tool_result" && parsed.id) {
+      const id = parsed.id;
+      const result = parsed.result ?? "";
+      const pending = pendingTools.get(id);
       if (pending) {
-        pendingTools.delete(parsed.id);
-        pending.resolve(parsed.result ?? "");
+        pendingTools.delete(id);
+        pending.resolve(result);
       } else {
-        earlyResults.set(parsed.id, parsed.result ?? "");
+        earlyResults.set(id, result);
       }
       return;
     }
-    if (parsed.action === "get_history") {
-      emit("history", {
-        messages: state.messages
-      });
+    if (action === "get_history") {
+      dispatchSimple(requestId, "history", () => handleGetHistory(state));
       return;
     }
-    if (parsed.action === "clear") {
-      clearSession(state);
-      emit("session_cleared");
+    if (action === "clear") {
+      dispatchSimple(requestId, "session_cleared", () => handleClear(state));
       return;
     }
-    if (parsed.action === "cancel") {
-      if (currentAbort) {
-        currentAbort.abort();
-      }
-      for (const [id, pending] of pendingTools) {
-        clearTimeout(pending.timeout);
-        pending.resolve("Error: cancelled");
-        pendingTools.delete(id);
-      }
+    if (action === "cancel") {
+      handleCancel(currentAbort, pendingTools);
+      emit("completed", { success: true }, requestId);
       return;
     }
-    if (parsed.action === "message" && (parsed.text || parsed.runCommand)) {
-      if (running) {
-        emit("error", { error: "Agent is already processing a message" });
-        return;
-      }
-      running = true;
-      currentAbort = new AbortController();
-      if (parsed.attachments?.length) {
-        console.warn(
-          `[headless] Message has ${parsed.attachments.length} attachment(s):`,
-          parsed.attachments.map((a) => a.url)
-        );
-      }
-      let userMessage = parsed.text ?? "";
-      const isCommand = !!parsed.runCommand;
-      if (parsed.runCommand === "sync") {
-        userMessage = loadActionPrompt("sync");
-      } else if (parsed.runCommand === "publish") {
-        userMessage = loadActionPrompt("publish");
-      } else if (parsed.runCommand === "buildFromInitialSpec") {
-        userMessage = loadActionPrompt("buildFromInitialSpec");
-      }
-      const onboardingState = parsed.onboardingState ?? "onboardingFinished";
-      const system = buildSystemPrompt(onboardingState, parsed.viewContext);
-      try {
-        await runTurn({
-          state,
-          userMessage,
-          attachments: parsed.attachments,
-          apiConfig: config,
-          system,
-          model: opts.model,
-          onboardingState,
-          signal: currentAbort.signal,
-          onEvent,
-          resolveExternalTool,
-          hidden: isCommand
-        });
-      } catch (err) {
-        emit("error", { error: err.message });
-      }
-      currentAbort = null;
-      running = false;
+    if (action === "message") {
+      await handleMessage(parsed, requestId);
+      return;
     }
+    emit("error", { error: `Unknown action: ${action}` }, requestId);
+    emit(
+      "completed",
+      { success: false, error: `Unknown action: ${action}` },
+      requestId
+    );
   });
   rl.on("close", () => {
     emit("stopping");