@mindstudio-ai/remy 0.1.313 → 0.1.314

package/dist/index.js

@@ -1389,179 +1389,6 @@ var init_sdkConsultant = __esm({
   }
 });
 
-// src/usageLedger.ts
-import fs8 from "fs";
-function nanoToDollars(nano) {
-  return typeof nano === "number" ? nano / 1e9 : void 0;
-}
-function recordUsage(entry) {
-  try {
-    if (fd === null) {
-      fs8.mkdirSync(".logs", { recursive: true });
-      fd = fs8.openSync(LEDGER_FILE, "a");
-    }
-    fs8.writeSync(fd, JSON.stringify(entry) + "\n");
-  } catch {
-  }
-}
-var LEDGER_FILE, fd;
-var init_usageLedger = __esm({
-  "src/usageLedger.ts"() {
-    "use strict";
-    LEDGER_FILE = ".logs/usage.ndjson";
-    fd = null;
-  }
-});
-
-// src/subagents/common/runMindstudioCli.ts
-function stripFlags(args2) {
-  const out = [];
-  for (let i = 0; i < args2.length; i++) {
-    const arg = args2[i];
-    if (arg === "--no-meta") {
-      continue;
-    }
-    if (arg === "--output-key") {
-      i++;
-      continue;
-    }
-    out.push(arg);
-  }
-  return out;
-}
-async function runMindstudioCliResult(args2, options) {
-  const cleanArgs = stripFlags(args2);
-  const cliAction = args2[0];
-  const agentName = options?.caller ?? "mindstudio-cli";
-  const start = Date.now();
-  const res = await runCli("mindstudio", cleanArgs, options);
-  if (!res.ok) {
-    return { ok: false, value: formatCliResult(res) };
-  }
-  const truncNote = res.truncated ? "\n\n[output truncated]" : "";
-  let envelope;
-  try {
-    envelope = JSON.parse(res.output);
-  } catch {
-    return { ok: true, value: res.output + truncNote };
-  }
-  if (envelope && typeof envelope === "object" && Array.isArray(envelope.results)) {
-    const durationMs = Date.now() - start;
-    for (const step of envelope.results) {
-      if (typeof step?.billingCost === "number") {
-        recordUsage({
-          ts: Date.now(),
-          agentName,
-          cliAction: `${cliAction}:${step.stepType ?? "step"}`,
-          cost: nanoToDollars(step.billingCost),
-          inputTokens: 0,
-          outputTokens: 0,
-          durationMs,
-          toolNames: []
-        });
-      }
-    }
-    return { ok: true, value: JSON.stringify(envelope.results) + truncNote };
-  }
-  if (typeof envelope?.$billingCost === "number") {
-    recordUsage({
-      ts: Date.now(),
-      agentName,
-      cliAction,
-      cost: nanoToDollars(envelope.$billingCost),
-      billingEvents: envelope.$billingEvents,
-      // CLI billing isn't expressed as input/output tokens for most actions
-      // (image gen is per-image, scrape per-page, etc). `numUnits` inside each
-      // billingEvent carries the per-event unit count.
-      inputTokens: 0,
-      outputTokens: 0,
-      durationMs: Date.now() - start,
-      toolNames: []
-    });
-  }
-  if (options?.outputKey) {
-    const v = envelope?.[options.outputKey];
-    if (v === void 0 || v === null) {
-      return { ok: false, value: JSON.stringify(stripDollarKeys(envelope)) };
-    }
-    const value = typeof v === "string" ? v : JSON.stringify(v);
-    return { ok: true, value: value + truncNote };
-  }
-  return {
-    ok: true,
-    value: JSON.stringify(stripDollarKeys(envelope)) + truncNote
-  };
-}
-async function runMindstudioCli(args2, options) {
-  return (await runMindstudioCliResult(args2, options)).value;
-}
-function stripDollarKeys(envelope) {
-  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
-    return envelope;
-  }
-  const out = {};
-  for (const [k, v] of Object.entries(envelope)) {
-    if (!k.startsWith("$")) {
-      out[k] = v;
-    }
-  }
-  return out;
-}
-var init_runMindstudioCli = __esm({
-  "src/subagents/common/runMindstudioCli.ts"() {
-    "use strict";
-    init_runCli();
-    init_usageLedger();
-  }
-});
-
-// src/tools/common/searchGoogle.ts
-var FETCH_TOP_N, searchGoogleTool;
-var init_searchGoogle = __esm({
-  "src/tools/common/searchGoogle.ts"() {
-    "use strict";
-    init_runMindstudioCli();
-    init_runCli();
-    FETCH_TOP_N = 5;
-    searchGoogleTool = {
-      definition: {
-        name: "searchGoogle",
-        description: "Search Google and return results. Use for research, finding documentation, looking up APIs, or any task where web search would help. The top results come back with their page content already included, so read those before reaching for scrapeWebUrl \u2014 you only need that for URLs this did not return, or for a result further down the list.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            query: {
-              type: "string",
-              description: "The search query."
-            }
-          },
-          required: ["query"]
-        }
-      },
-      async execute(input, context) {
-        const query = input.query;
-        return runMindstudioCli(
-          [
-            "search-google",
-            "--query",
-            query,
-            "--export-type",
-            "json",
-            "--fetch-top-n",
-            String(FETCH_TOP_N)
-          ],
-          {
-            outputKey: "results",
-            maxBuffer: SEARCH_MAX_BUFFER,
-            onLog: context?.onLog,
-            caller: "parent"
-          }
-        );
-      }
-    };
-  }
-});
-
 // src/tools/common/setProjectMetadata.ts
 var setProjectMetadataTool;
 var init_setProjectMetadata = __esm({
@@ -1601,7 +1428,7 @@ var init_setProjectMetadata = __esm({
 });
 
 // src/assets.ts
-import fs9 from "fs";
+import fs8 from "fs";
 import path3 from "path";
 function assetPath(...segments) {
   return path3.join(ASSETS_BASE, ...segments);
@@ -1609,7 +1436,7 @@ function assetPath(...segments) {
 function readAsset(...segments) {
   const full = assetPath(...segments);
   try {
-    return fs9.readFileSync(full, "utf-8").trim();
+    return fs8.readFileSync(full, "utf-8").trim();
   } catch {
     throw new Error(`Required asset missing: ${full}`);
   }
@@ -1617,7 +1444,7 @@ function readAsset(...segments) {
 function readJsonAsset(fallback, ...segments) {
   const full = assetPath(...segments);
   try {
-    return JSON.parse(fs9.readFileSync(full, "utf-8"));
+    return JSON.parse(fs8.readFileSync(full, "utf-8"));
   } catch {
     return fallback;
   }
@@ -1683,6 +1510,30 @@ var init_sentinel = __esm({
   }
 });
 
+// src/usageLedger.ts
+import fs9 from "fs";
+function nanoToDollars(nano) {
+  return typeof nano === "number" ? nano / 1e9 : void 0;
+}
+function recordUsage(entry) {
+  try {
+    if (fd === null) {
+      fs9.mkdirSync(".logs", { recursive: true });
+      fd = fs9.openSync(LEDGER_FILE, "a");
+    }
+    fs9.writeSync(fd, JSON.stringify(entry) + "\n");
+  } catch {
+  }
+}
+var LEDGER_FILE, fd;
+var init_usageLedger = __esm({
+  "src/usageLedger.ts"() {
+    "use strict";
+    LEDGER_FILE = ".logs/usage.ndjson";
+    fd = null;
+  }
+});
+
 // src/compaction/index.ts
 async function compactConversation(messages, apiConfig, model, signal) {
   const endIndex = findSafeInsertionPoint(messages);
@@ -2096,7 +1947,7 @@ var init_compaction = __esm({
     init_api();
     init_assets();
     init_sentinel();
-    init_tools8();
+    init_tools9();
     init_logger();
     init_usageLedger();
     log2 = createLogger("compaction");
@@ -2200,6 +2051,13 @@ var init_surfaces = __esm({
         modelType: "text",
         userPickable: true
       },
+      research: {
+        default: "claude-5-sonnet",
+        label: "Research Agent",
+        description: "Researches using the web and reports back with citations.",
+        modelType: "text",
+        userPickable: true
+      },
       copyEditor: {
         default: "claude-5-sonnet",
         label: "Copy Agent",
@@ -4322,6 +4180,108 @@ var init_queryDatabase = __esm({
   }
 });
 
+// src/subagents/common/runMindstudioCli.ts
+function stripFlags(args2) {
+  const out = [];
+  for (let i = 0; i < args2.length; i++) {
+    const arg = args2[i];
+    if (arg === "--no-meta") {
+      continue;
+    }
+    if (arg === "--output-key") {
+      i++;
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}
+async function runMindstudioCliResult(args2, options) {
+  const cleanArgs = stripFlags(args2);
+  const cliAction = args2[0];
+  const agentName = options?.caller ?? "mindstudio-cli";
+  const start = Date.now();
+  const res = await runCli("mindstudio", cleanArgs, options);
+  if (!res.ok) {
+    return { ok: false, value: formatCliResult(res) };
+  }
+  const truncNote = res.truncated ? "\n\n[output truncated]" : "";
+  let envelope;
+  try {
+    envelope = JSON.parse(res.output);
+  } catch {
+    return { ok: true, value: res.output + truncNote };
+  }
+  if (envelope && typeof envelope === "object" && Array.isArray(envelope.results)) {
+    const durationMs = Date.now() - start;
+    for (const step of envelope.results) {
+      if (typeof step?.billingCost === "number") {
+        recordUsage({
+          ts: Date.now(),
+          agentName,
+          cliAction: `${cliAction}:${step.stepType ?? "step"}`,
+          cost: nanoToDollars(step.billingCost),
+          inputTokens: 0,
+          outputTokens: 0,
+          durationMs,
+          toolNames: []
+        });
+      }
+    }
+    return { ok: true, value: JSON.stringify(envelope.results) + truncNote };
+  }
+  if (typeof envelope?.$billingCost === "number") {
+    recordUsage({
+      ts: Date.now(),
+      agentName,
+      cliAction,
+      cost: nanoToDollars(envelope.$billingCost),
+      billingEvents: envelope.$billingEvents,
+      // CLI billing isn't expressed as input/output tokens for most actions
+      // (image gen is per-image, scrape per-page, etc). `numUnits` inside each
+      // billingEvent carries the per-event unit count.
+      inputTokens: 0,
+      outputTokens: 0,
+      durationMs: Date.now() - start,
+      toolNames: []
+    });
+  }
+  if (options?.outputKey) {
+    const v = envelope?.[options.outputKey];
+    if (v === void 0 || v === null) {
+      return { ok: false, value: JSON.stringify(stripDollarKeys(envelope)) };
+    }
+    const value = typeof v === "string" ? v : JSON.stringify(v);
+    return { ok: true, value: value + truncNote };
+  }
+  return {
+    ok: true,
+    value: JSON.stringify(stripDollarKeys(envelope)) + truncNote
+  };
+}
+async function runMindstudioCli(args2, options) {
+  return (await runMindstudioCliResult(args2, options)).value;
+}
+function stripDollarKeys(envelope) {
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
+    return envelope;
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(envelope)) {
+    if (!k.startsWith("$")) {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+var init_runMindstudioCli = __esm({
+  "src/subagents/common/runMindstudioCli.ts"() {
+    "use strict";
+    init_runCli();
+    init_usageLedger();
+  }
+});
+
 // src/tools/_helpers/uploadImage.ts
 import { readFile, stat } from "fs/promises";
 import { basename, extname, resolve } from "path";
@@ -5653,7 +5613,7 @@ The first-party SDK (@mindstudio-ai/agent) provides access to 200+ AI models (Op
 ## What Remy apps are NOT good for
 
 - Native mobile apps (iOS/Android). Mobile-responsive web apps are fine.
-- Fast-twitch multiplayer and live co-editing (shared cursors, 60fps sync) \u2014 client\u2192server is always a method invoke, so sub-100ms bidirectional interaction isn't a fit.
+- Real-time action games (server-authoritative simulation, guaranteed-order sync) \u2014 event delivery is at-most-once and ordering is the app's job, so there is no server tick to build one on.
 </platform_brief>`;
 }
 var init_context = __esm({
@@ -5818,7 +5778,7 @@ var log9, CAPTURE_COMMANDS, browserAutomationTool;
 var init_browserAutomation = __esm({
   "src/subagents/browserAutomation/index.ts"() {
     "use strict";
-    init_tools8();
+    init_tools9();
     init_runner();
     init_tools2();
     init_tools();
@@ -5983,62 +5943,175 @@ var init_screenshot2 = __esm({
   }
 });
 
-// src/subagents/designExpert/tools/searchGoogle.ts
-var searchGoogle_exports = {};
-__export(searchGoogle_exports, {
-  definition: () => definition,
-  execute: () => execute
-});
-async function execute(input, onLog) {
+// src/subagents/research/tools.ts
+async function executeSearchGoogle(input, onLog, caller) {
+  const fetchTopN = Math.max(0, Math.round(Number(input.fetchTopN) || 0));
   return runMindstudioCli(
     [
       "search-google",
       "--query",
-      input.query,
+      String(input.query),
       "--export-type",
       "json",
       "--fetch-top-n",
-      String(FETCH_TOP_N2)
+      String(fetchTopN)
     ],
     {
       outputKey: "results",
+      maxBuffer: SEARCH_MAX_BUFFER,
       onLog,
-      caller: "designExpert",
-      maxBuffer: SEARCH_MAX_BUFFER
+      caller
     }
   );
 }
-var FETCH_TOP_N2, definition;
-var init_searchGoogle2 = __esm({
-  "src/subagents/designExpert/tools/searchGoogle.ts"() {
+async function executeScrapeWebUrl(input, onLog, caller) {
+  return runMindstudioCli(
+    [
+      "scrape-url",
+      "--url",
+      String(input.url),
+      "--page-options",
+      JSON.stringify({ onlyMainContent: true })
+    ],
+    {
+      maxBuffer: SCRAPE_MAX_BUFFER,
+      onLog,
+      caller
+    }
+  );
+}
+var searchGoogleDefinition, scrapeWebUrlDefinition, RESEARCH_TOOLS;
+var init_tools3 = __esm({
+  "src/subagents/research/tools.ts"() {
     "use strict";
+    init_tools();
     init_runMindstudioCli();
     init_runCli();
-    FETCH_TOP_N2 = 5;
-    definition = {
+    init_bash();
+    searchGoogleDefinition = {
       name: "searchGoogle",
-      description: 'Search Google for web results. Reserch modern design trends in industries or verticals, "best [domain] apps 2026", ui patterns, or find something specific if the the user has an explicit reference. Searching for and reading case studies is a great way to get information and context about a project\'s domain. Prioritize authoritative sources like Figma and other design leaders, avoid random blog spam. The top results come back with their page content already included, so read those directly \u2014 only use `scrapeWebUrl` for a result further down the list, or for a URL this did not return.',
+      description: "Search Google. Returns ~25 results (title, description, URL) \u2014 fast (~5s) when `fetchTopN` is omitted. Set `fetchTopN` (3\u20135) to also get the top results' page content inline, capped at ~4,000 chars per page \u2014 one call delivers excerpts, but it is much slower (~30\u201360s). Default pattern: fire SERP-only searches in parallel, then scrape the specific pages worth reading in full.",
       inputSchema: {
         type: "object",
         properties: {
           query: {
             type: "string",
             description: "The search query."
+          },
+          fetchTopN: {
+            type: "number",
+            description: "Also fetch page content (capped ~4,000 chars each) for this many top results. Omit for a fast SERP-only search."
           }
         },
         required: ["query"]
       }
     };
+    scrapeWebUrlDefinition = {
+      name: "scrapeWebUrl",
+      description: "Fetch a web page as markdown. Renders JavaScript, so client-rendered pages come back complete. Returns the full page \u2014 long docs can run tens of thousands of tokens, so fetch only pages you have chosen to read, and fire independent fetches in parallel. For code hosted on GitHub/npm, prefer cloning with bash over scraping the repo page.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          url: {
+            type: "string",
+            description: "The URL to fetch."
+          }
+        },
+        required: ["url"]
+      }
+    };
+    RESEARCH_TOOLS = [
+      ...COMMON_READ_TOOLS,
+      searchGoogleDefinition,
+      scrapeWebUrlDefinition,
+      bashTool.definition
+    ];
+  }
+});
+
+// src/subagents/research/index.ts
+async function runResearch(task, context) {
+  const specIndex = loadSpecIndex();
+  const parts = [BASE_PROMPT2, loadPlatformBrief()];
+  parts.push("<!-- cache_breakpoint -->");
+  if (specIndex) {
+    parts.push(specIndex);
+  }
+  const system = parts.join("\n\n");
+  const result = await runSubAgent({
+    system,
+    task,
+    tools: RESEARCH_TOOLS,
+    externalTools: /* @__PURE__ */ new Set(),
+    executeTool: (name, toolInput, toolCallId, onLog, sams) => {
+      const childCtx = toolCallId ? {
+        ...deriveContext(context, toolCallId, onLog),
+        subAgentMessages: sams
+      } : context;
+      if (name === "searchGoogle") {
+        return executeSearchGoogle(toolInput, childCtx.onLog, "research");
+      }
+      if (name === "scrapeWebUrl") {
+        return executeScrapeWebUrl(toolInput, childCtx.onLog, "research");
+      }
+      return executeTool(name, toolInput, childCtx);
+    },
+    apiConfig: context.apiConfig,
+    model: resolveModel("research", context.models, context.model),
+    subAgentId: "research",
+    signal: context.signal,
+    parentToolId: context.toolCallId,
+    requestId: context.requestId,
+    onEvent: context.onEvent,
+    resolveExternalTool: context.resolveExternalTool,
+    toolRegistry: context.toolRegistry
+  });
+  context.subAgentMessages?.set(context.toolCallId, result.messages);
+  return result.text;
+}
+var BASE_PROMPT2, researchTool;
+var init_research = __esm({
+  "src/subagents/research/index.ts"() {
+    "use strict";
+    init_assets();
+    init_runner();
+    init_context();
+    init_tools9();
+    init_tools3();
+    init_surfaces();
+    BASE_PROMPT2 = readAsset("subagents/research", "prompt.md");
+    researchTool = {
+      definition: {
+        name: "research",
+        description: "Your researcher. Hand it a question and it searches the web, reads the pages and source code that matter, and returns a distilled, citation-backed report. Use it for both objective research like third-party APIs and services, as well as for subjective things like current trends, patterns, and approaches (from architecture to UI to even just high-level framings and ideas). Brief it neutrally: state the question and the relevant project context, not the answer you expect.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            task: {
+              type: "string",
+              description: "What you need to find out, in natural language, plus any project context it cannot get from reading the spec. Phrase it as a question to answer, not a conclusion to confirm."
+            }
+          },
+          required: ["task"]
+        }
+      },
+      async execute(input, context) {
+        if (!context) {
+          return "Error: research requires execution context";
+        }
+        return runResearch(input.task, context);
+      }
+    };
   }
 });
 
 // src/subagents/designExpert/tools/scrapeWebUrl.ts
 var scrapeWebUrl_exports = {};
 __export(scrapeWebUrl_exports, {
-  definition: () => definition2,
-  execute: () => execute2
+  definition: () => definition,
+  execute: () => execute
 });
-async function execute2(input, onLog) {
+async function execute(input, onLog) {
   const pageOptions = { onlyMainContent: true };
   return runMindstudioCli(
     [
@@ -6051,15 +6124,15 @@ async function execute2(input, onLog) {
     { onLog, caller: "designExpert", maxBuffer: SCRAPE_MAX_BUFFER }
   );
 }
-var definition2;
+var definition;
 var init_scrapeWebUrl = __esm({
   "src/subagents/designExpert/tools/scrapeWebUrl.ts"() {
     "use strict";
     init_runMindstudioCli();
     init_runCli();
-    definition2 = {
+    definition = {
       name: "scrapeWebUrl",
-      description: "Fetch the content of a web page as markdown. Use when reading sites from search results or specific things the user wants to incorporate.",
+      description: "Fetch the content of a web page as markdown. Use for reading a specific URL \u2014 a site the user referenced, a brand to match, a page the researcher cited that you want in full.",
       inputSchema: {
         type: "object",
         properties: {
@@ -6078,14 +6151,14 @@ var init_scrapeWebUrl = __esm({
 var renderImage_exports = {};
 __export(renderImage_exports, {
   RENDER_ANALYZE_PROMPT: () => RENDER_ANALYZE_PROMPT,
-  definition: () => definition3,
-  execute: () => execute3
+  definition: () => definition2,
+  execute: () => execute2
 });
 import { mkdir, unlink, writeFile } from "fs/promises";
 import { tmpdir } from "os";
 import { dirname, join, resolve as resolve2, sep } from "path";
 import { randomUUID } from "crypto";
-async function execute3(input, onLog, context) {
+async function execute2(input, onLog, context) {
   const html = typeof input.html === "string" ? input.html : "";
   const width = Math.round(Number(input.width));
   const height = Math.round(Number(input.height));
@@ -6169,7 +6242,7 @@ async function execute3(input, onLog, context) {
     ]
   });
 }
-var MIN_DIMENSION, MAX_DIMENSION, RENDER_ANALYZE_PROMPT, definition3;
+var MIN_DIMENSION, MAX_DIMENSION, RENDER_ANALYZE_PROMPT, definition2;
 var init_renderImage = __esm({
   "src/subagents/designExpert/tools/images/renderImage.ts"() {
     "use strict";
@@ -6182,7 +6255,7 @@ var init_renderImage = __esm({
     MIN_DIMENSION = 16;
     MAX_DIMENSION = 4096;
     RENDER_ANALYZE_PROMPT = 'You are reviewing a browser-rendered graphic (composed from HTML/CSS by a designer) for fidelity. Report: whether the composition fills the full canvas or leaves unintended gaps at any edge, any clipped or overflowing text, whether custom webfonts appear to have loaded (distinctive letterforms vs generic fallback serif/sans), any misalignment or uneven spacing, any unintended scrollbars or default-styling artifacts, and \u2014 if the background is transparent \u2014 any fringing or stray opaque pixels at the edges. Then briefly describe the overall composition and how polished it looks. Be concise and practical. Respond only with your analysis as Markdown (starting with the title "Render Review") and absolutely no other text. Do not use emojis - use unicode if you need symbols.';
-    definition3 = {
+    definition2 = {
       name: "renderImage",
       description: "Render a self-contained HTML document in a real browser and capture it as a hosted PNG at exact pixel dimensions, with a fidelity review included. Deterministic \u2014 exact hex colors, real loaded webfonts, precise geometry \u2014 unlike generateImages, which is an image model. Use for token-exact graphics: Open Graph share cards, wordmarks, flat/geometric icon tiles, badges, any composition where letterforms and spacing carry the design. Compose with HTML/CSS (link webfonts from CDNs \u2014 the renderer waits for them to load); inline existing SVG markup when needed, but never hand-write new SVG path data.",
       inputSchema: {
@@ -6222,8 +6295,8 @@ var init_renderImage = __esm({
 // src/subagents/designExpert/tools/analyzeDesign.ts
 var analyzeDesign_exports = {};
 __export(analyzeDesign_exports, {
-  definition: () => definition4,
-  execute: () => execute4
+  definition: () => definition3,
+  execute: () => execute3
 });
 import { readFile as readFile2 } from "fs/promises";
 import { extname as extname2, join as join2 } from "path";
@@ -6245,7 +6318,7 @@ function splitFrontmatter(raw) {
     html: raw.slice(match[0].length)
   };
 }
-async function execute4(input, onLog, context) {
+async function execute3(input, onLog, context) {
   const url = String(input.url ?? "").trim();
   if (!url) {
     return "Error: url is required.";
@@ -6349,7 +6422,7 @@ ${basePrompt}` : basePrompt;
     renderedHeight: rendered.height
   });
 }
-var DESIGN_REFERENCE_PROMPT, definition4, IMAGE_EXT_RE, HTML_EXTS, HTML_RENDER_WIDTH, HTML_RENDER_START_HEIGHT;
+var DESIGN_REFERENCE_PROMPT, definition3, IMAGE_EXT_RE, HTML_EXTS, HTML_RENDER_WIDTH, HTML_RENDER_START_HEIGHT;
 var init_analyzeDesign = __esm({
   "src/subagents/designExpert/tools/analyzeDesign.ts"() {
     "use strict";
@@ -6384,7 +6457,7 @@ Identify the specific design moves that make this page interesting and unique, d
 
 Respond only with your analysis as Markdown and absolutely no other text. Do not use emojis - use unicode if you need symbols.
 `;
-    definition4 = {
+    definition3 = {
       name: "analyzeDesign",
       description: "Analyze the visual design of a website, an image (URL or file on disk), or an HTML document on disk. Websites are screenshotted first; an HTML file is rendered in a real browser first and the render is analyzed, which is how you look at a wireframe you authored. Provides static image analysis only, will not capture animations or video. With no prompt, a website or image gets a full design reference analysis (mood, color, typography, layout, distinctiveness) and a rendered HTML document gets a fidelity review (clipping, overflow, webfont loading, alignment). Provide a custom prompt to ask a specific design question instead. Use a bulleted list to ask many questions at once.",
       inputSchema: {
@@ -6412,10 +6485,10 @@ Respond only with your analysis as Markdown and absolutely no other text. Do not
 // src/subagents/designExpert/tools/analyzeImage.ts
 var analyzeImage_exports = {};
 __export(analyzeImage_exports, {
-  definition: () => definition5,
-  execute: () => execute5
+  definition: () => definition4,
+  execute: () => execute4
 });
-async function execute5(input, onLog, context) {
+async function execute4(input, onLog, context) {
   const prompt = buildScreenshotAnalysisPrompt({
     prompt: input.prompt
   });
@@ -6428,14 +6501,14 @@ async function execute5(input, onLog, context) {
   });
   return JSON.stringify({ url, analysis });
 }
-var definition5;
+var definition4;
 var init_analyzeImage2 = __esm({
   "src/subagents/designExpert/tools/analyzeImage.ts"() {
     "use strict";
     init_analyzeImage();
     init_screenshot();
     init_surfaces();
-    definition5 = {
+    definition4 = {
       name: "analyzeImage",
       description: "Analyze an image using a vision model. Provides static image analysis only, will not capture animations or video. Returns an objective description of what is visible \u2014 shapes, colors, layout, text, artifacts. Use for factual inventory of image contents, not for subjective design judgment - the vision model providing the analysis has no sense of design. You are the design expert - use the analysis tool for factual inventory, then apply your own expertise for quality and suitability assessments. Optionally provide specific questions about what you're looking for. Use a bulleted list to ask many questions at once. If you are analyzing a screenshot of the app preview, you can reuse the same screenshot URL multiple times to ask multiple questions.",
       inputSchema: {
@@ -6703,10 +6776,10 @@ var init_imageGenerator = __esm({
 // src/subagents/designExpert/tools/images/generateImages.ts
 var generateImages_exports = {};
 __export(generateImages_exports, {
-  definition: () => definition6,
-  execute: () => execute6
+  definition: () => definition5,
+  execute: () => execute5
 });
-async function execute6(input, onLog, context) {
+async function execute5(input, onLog, context) {
   return generateImageAssets({
     prompts: input.prompts,
     width: input.width,
@@ -6733,13 +6806,13 @@ async function execute6(input, onLog, context) {
     )
   });
 }
-var definition6;
+var definition5;
 var init_generateImages = __esm({
   "src/subagents/designExpert/tools/images/generateImages.ts"() {
     "use strict";
     init_imageGenerator();
     init_surfaces();
-    definition6 = {
+    definition5 = {
       name: "generateImages",
       description: "Generate images. Returns CDN URLs with a quality analysis for each image. Produces high-quality results for everything from photorealistic images and abstract/creative visuals. Pass multiple prompts to generate in parallel. No need to analyze images separately after generating \u2014 the analysis is included.",
       inputSchema: {
@@ -6778,10 +6851,10 @@ var init_generateImages = __esm({
 // src/subagents/designExpert/tools/images/editImages.ts
 var editImages_exports = {};
 __export(editImages_exports, {
-  definition: () => definition7,
-  execute: () => execute7
+  definition: () => definition6,
+  execute: () => execute6
 });
-async function execute7(input, onLog, context) {
+async function execute6(input, onLog, context) {
   return generateImageAssets({
     prompts: input.prompts,
     sourceImages: input.sourceImages,
@@ -6808,13 +6881,13 @@ async function execute7(input, onLog, context) {
     )
   });
 }
-var definition7;
+var definition6;
 var init_editImages = __esm({
   "src/subagents/designExpert/tools/images/editImages.ts"() {
     "use strict";
     init_imageGenerator();
     init_surfaces();
-    definition7 = {
+    definition6 = {
       name: "editImages",
       description: "Edit or transform existing images. Provide one or more source image URLs as reference and a prompt describing the desired edit. Use for compositing, style transfer, subject transformation, blending multiple references, or incorporating one or more references into something new. Returns CDN URLs with analysis.",
       inputSchema: {
@@ -6855,7 +6928,7 @@ var init_editImages = __esm({
 
 // src/subagents/copyEditor/tools.ts
 var COPY_EDITOR_TOOLS;
-var init_tools3 = __esm({
+var init_tools4 = __esm({
   "src/subagents/copyEditor/tools.ts"() {
     "use strict";
     init_tools();
@@ -6864,17 +6937,17 @@ var init_tools3 = __esm({
 });
 
 // src/subagents/copyEditor/index.ts
-var BASE_PROMPT2, copyEditorTool;
+var BASE_PROMPT3, copyEditorTool;
 var init_copyEditor = __esm({
   "src/subagents/copyEditor/index.ts"() {
     "use strict";
     init_assets();
     init_runner();
     init_context();
-    init_tools8();
-    init_tools3();
+    init_tools9();
+    init_tools4();
     init_surfaces();
-    BASE_PROMPT2 = readAsset("subagents/copyEditor", "prompt.md");
+    BASE_PROMPT3 = readAsset("subagents/copyEditor", "prompt.md");
     copyEditorTool = {
       definition: {
         name: "copyEditor",
@@ -6895,7 +6968,7 @@ var init_copyEditor = __esm({
           return "Error: copy editor requires execution context";
         }
         const specIndex = loadSpecIndex();
-        const parts = [BASE_PROMPT2];
+        const parts = [BASE_PROMPT3];
         parts.push("<!-- cache_breakpoint -->");
         if (specIndex) {
           parts.push(specIndex);
@@ -6933,18 +7006,18 @@ var init_copyEditor = __esm({
 // src/subagents/designExpert/tools/polishCopy.ts
 var polishCopy_exports = {};
 __export(polishCopy_exports, {
-  definition: () => definition8,
-  execute: () => execute8
+  definition: () => definition7,
+  execute: () => execute7
 });
-async function execute8(input, _onLog, context) {
+async function execute7(input, _onLog, context) {
   return copyEditorTool.execute(input, context);
 }
-var definition8;
+var definition7;
 var init_polishCopy = __esm({
   "src/subagents/designExpert/tools/polishCopy.ts"() {
     "use strict";
     init_copyEditor();
-    definition8 = {
+    definition7 = {
       name: "polishCopy",
       description: "Hand off any user-facing copy you've written \u2014 headlines, captions, labels, body text \u2014 and get back a sharper version: better built for its audience and free of the fingerprints that make writing read as AI. It elevates how the copy communicates without inventing facts or claims you didn't give it. Give it the text plus what it's for (where it appears, the audience).",
       inputSchema: {
@@ -6982,10 +7055,10 @@ A loaded reference drops out of the conversation once it ages out. Re-read it at
 // src/subagents/designExpert/tools/loadSkill.ts
 var loadSkill_exports = {};
 __export(loadSkill_exports, {
-  definition: () => definition9,
-  execute: () => execute9
+  definition: () => definition8,
+  execute: () => execute8
 });
-async function execute9(input) {
+async function execute8(input) {
   const id = String(input.skill ?? "");
   const skill = designSkillCatalog.get(id);
   if (!skill) {
@@ -7001,12 +7074,12 @@ This reference lives at ${skill.path}. Re-read it with readFile if you need it a
     return `Error loading skill "${id}": ${err.message}`;
   }
 }
-var definition9;
+var definition8;
 var init_loadSkill2 = __esm({
   "src/subagents/designExpert/tools/loadSkill.ts"() {
     "use strict";
     init_catalog2();
-    definition9 = {
+    definition8 = {
       name: "loadSkill",
       description: "Load the full craft reference for a design surface that isn't in your prompt. The available skills and the trigger for each are listed in <available_skills>. Load one before designing in its area, not after \u2014 these are hard-won technique recipes, and the defaulted version of these surfaces is exactly what they exist to prevent. Calling this is cheap and expected \u2014 if you're unsure whether you need it, load it.",
       inputSchema: {
@@ -7031,8 +7104,8 @@ var init_loadSkill2 = __esm({
 var createWireframe_exports = {};
 __export(createWireframe_exports, {
   WIREFRAMES_DIR: () => WIREFRAMES_DIR,
-  definition: () => definition10,
-  execute: () => execute10
+  definition: () => definition9,
+  execute: () => execute9
 });
 import { mkdir as mkdir2, stat as stat2, writeFile as writeFile2 } from "fs/promises";
 import { join as join3 } from "path";
@@ -7103,7 +7176,7 @@ async function uploadMirror(context, slug, content) {
     return { ok: false, note: err.message };
   }
 }
-async function execute10(input, onLog, context) {
+async function execute9(input, onLog, context) {
   if (!context) {
     return "Error: createWireframe requires execution context";
   }
@@ -7149,7 +7222,7 @@ async function execute10(input, onLog, context) {
   }
   return lines.join("\n");
 }
-var log10, WIREFRAMES_DIR, UPLOAD_TIMEOUT_MS2, definition10, SLUG_RE;
+var log10, WIREFRAMES_DIR, UPLOAD_TIMEOUT_MS2, definition9, SLUG_RE;
 var init_createWireframe = __esm({
   "src/subagents/designExpert/tools/createWireframe.ts"() {
     "use strict";
@@ -7158,7 +7231,7 @@ var init_createWireframe = __esm({
     log10 = createLogger("createWireframe");
     WIREFRAMES_DIR = "src/.wireframes";
     UPLOAD_TIMEOUT_MS2 = 3e4;
-    definition10 = {
+    definition9 = {
       name: "createWireframe",
       description: "Generate a wireframe from self-contained HTML+CSS you author and write it to disk as a design artifact. This is how a wireframe comes to exist \u2014 the way generateImages is how an image comes to exist \u2014 and the developer builds from the file it creates. The result also hands back the reference line that embeds the wireframe in your response and in specs; paste it wherever the wireframe belongs and it renders as a live preview. Calling again with the same slug revises the wireframe in place, so existing references stay current \u2014 a revision is a call to this tool, never a prose description of changes to an earlier wireframe.",
       inputSchema: {
@@ -7197,13 +7270,13 @@ async function executeDesignExpertTool(name, input, context, toolCallId, onLog)
   const childContext = context && toolCallId ? deriveContext(context, toolCallId, onLog) : context;
   return tool.execute(input, onLog, childContext);
 }
-var tools, DESIGN_EXPERT_TOOLS;
-var init_tools4 = __esm({
+var research, tools, DESIGN_EXPERT_TOOLS;
+var init_tools5 = __esm({
   "src/subagents/designExpert/tools/index.ts"() {
     "use strict";
-    init_tools8();
+    init_tools9();
     init_tools();
-    init_searchGoogle2();
+    init_research();
     init_scrapeWebUrl();
     init_analyzeDesign();
     init_analyzeImage2();
@@ -7214,8 +7287,29 @@ var init_tools4 = __esm({
     init_loadSkill2();
     init_createWireframe();
     init_screenshot2();
+    research = {
+      definition: {
+        name: "research",
+        description: "Your researcher, for design questions your built-in catalogs and expertise do not settle: how leading products present a specific kind of data or interaction, current conventions or best practices for a pattern, general-purpose ideas and inspiration. It searches the web, reads the sources that matter, and returns a distilled report with citations and concrete specifics. Brief it neutrally: the question or topic, not the answer you expect.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            task: {
+              type: "string",
+              description: "What you need to find out, in natural language, with enough product context to make the findings relevant."
+            }
+          },
+          required: ["task"]
+        }
+      },
+      execute: (input, _onLog, context) => {
+        if (!context) {
+          return Promise.resolve("Error: research requires execution context");
+        }
+        return runResearch(input.task, context);
+      }
+    };
     tools = {
-      searchGoogle: searchGoogle_exports,
       scrapeWebUrl: scrapeWebUrl_exports,
       analyzeDesign: analyzeDesign_exports,
       analyzeImage: analyzeImage_exports,
@@ -7229,7 +7323,8 @@ var init_tools4 = __esm({
       polishCopy: polishCopy_exports,
       loadSkill: loadSkill_exports,
       // Appended last: tool order is part of the subagent's prompt-cache prefix.
-      createWireframe: createWireframe_exports
+      createWireframe: createWireframe_exports,
+      research
     };
     DESIGN_EXPERT_TOOLS = [
       ...COMMON_READ_TOOLS,
@@ -7708,9 +7803,9 @@ var DESCRIPTION, RENDER_WRITE_TOOL_NAMES, DESIGN_EXPERT_RENDER_TOOLS, designExpe
 var init_designExpert = __esm({
   "src/subagents/designExpert/index.ts"() {
     "use strict";
-    init_tools8();
+    init_tools9();
     init_runner();
-    init_tools4();
+    init_tools5();
     init_tools();
     init_prompt2();
     init_validateWireframeRefs();
@@ -7766,7 +7861,7 @@ Visual design expert. Describe the situation and what you need \u2014 the agent
 
 // src/subagents/productVision/tools.ts
 var VISION_TOOLS;
-var init_tools5 = __esm({
+var init_tools6 = __esm({
   "src/subagents/productVision/tools.ts"() {
     "use strict";
     init_tools();
@@ -7936,7 +8031,7 @@ var init_executor = __esm({
 function getProductVisionPrompt() {
   const specIndex = loadSpecIndex();
   const roadmapIndex = loadRoadmapIndex();
-  const parts = [BASE_PROMPT3, loadPlatformBrief()];
+  const parts = [BASE_PROMPT4, loadPlatformBrief()];
   parts.push("<!-- cache_breakpoint -->");
   if (specIndex) {
     parts.push(specIndex);
@@ -7946,13 +8041,13 @@ function getProductVisionPrompt() {
   }
   return parts.join("\n\n");
 }
-var BASE_PROMPT3;
+var BASE_PROMPT4;
 var init_prompt3 = __esm({
   "src/subagents/productVision/prompt.ts"() {
     "use strict";
     init_assets();
     init_context();
-    BASE_PROMPT3 = readAsset("subagents/productVision", "prompt.md");
+    BASE_PROMPT4 = readAsset("subagents/productVision", "prompt.md");
   }
 });
 
@@ -7961,9 +8056,9 @@ var productVisionTool;
 var init_productVision = __esm({
   "src/subagents/productVision/index.ts"() {
     "use strict";
-    init_tools8();
+    init_tools9();
     init_runner();
-    init_tools5();
+    init_tools6();
     init_tools();
     init_executor();
     init_prompt3();
@@ -8039,7 +8134,7 @@ var init_productVision = __esm({
 
 // src/subagents/codeSanityCheck/tools.ts
 var SANITY_CHECK_TOOLS;
-var init_tools6 = __esm({
+var init_tools7 = __esm({
   "src/subagents/codeSanityCheck/tools.ts"() {
     "use strict";
     init_tools();
@@ -8088,23 +8183,40 @@ var init_tools6 = __esm({
           },
           required: ["command"]
         }
+      },
+      // Appended last: tool order is part of the subagent's prompt-cache prefix.
+      {
+        name: "research",
+        description: "Deep researcher. When the plan hinges on an unfamiliar third-party service, API, or claim you cannot settle with a quick search, hand it the question \u2014 it researches properly (multiple sources, official docs, reading real source code) and returns a distilled, citation-backed report. Quick package-liveness checks stay on searchGoogle; use this when being wrong would be expensive. Brief it neutrally: the question, not the answer you expect.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            task: {
+              type: "string",
+              description: "What you need to find out, in natural language."
+            }
+          },
+          required: ["task"]
+        }
       }
     ];
   }
 });
 
 // src/subagents/codeSanityCheck/index.ts
-var BASE_PROMPT4, codeSanityCheckTool;
+var BASE_PROMPT5, codeSanityCheckTool;
 var init_codeSanityCheck = __esm({
   "src/subagents/codeSanityCheck/index.ts"() {
     "use strict";
     init_assets();
     init_runner();
     init_context();
-    init_tools8();
-    init_tools6();
+    init_tools9();
+    init_tools7();
+    init_research();
+    init_tools3();
     init_surfaces();
-    BASE_PROMPT4 = readAsset("subagents/codeSanityCheck", "prompt.md");
+    BASE_PROMPT5 = readAsset("subagents/codeSanityCheck", "prompt.md");
     codeSanityCheckTool = {
       definition: {
         name: "codeSanityCheck",
@@ -8125,7 +8237,7 @@ var init_codeSanityCheck = __esm({
           return "Error: code sanity check requires execution context";
         }
         const specIndex = loadSpecIndex();
-        const parts = [BASE_PROMPT4, loadPlatformBrief()];
+        const parts = [BASE_PROMPT5, loadPlatformBrief()];
         parts.push("<!-- cache_breakpoint -->");
         if (specIndex) {
           parts.push(specIndex);
@@ -8141,6 +8253,16 @@ var init_codeSanityCheck = __esm({
               ...deriveContext(context, toolCallId, onLog),
               subAgentMessages: sams
             } : context;
+            if (name === "searchGoogle") {
+              return executeSearchGoogle(
+                { ...toolInput, fetchTopN: 5 },
+                childCtx.onLog,
+                "codeSanityCheck"
+              );
+            }
+            if (name === "research") {
+              return runResearch(String(toolInput.task ?? ""), childCtx);
+            }
             return executeTool(name, toolInput, childCtx);
           },
           apiConfig: context.apiConfig,
@@ -8284,7 +8406,7 @@ The copy in <overview_copy> is final \u2014 it was authored and edited before it
 
 // src/subagents/specSync/tools.ts
 var SPEC_SYNC_TOOLS;
-var init_tools7 = __esm({
+var init_tools8 = __esm({
   "src/subagents/specSync/tools.ts"() {
     "use strict";
     init_tools();
@@ -8319,19 +8441,19 @@ var init_lock = __esm({
 });
 
 // src/subagents/specSync/index.ts
-var BASE_PROMPT5, MSFM_DOCS, specSyncTool;
+var BASE_PROMPT6, MSFM_DOCS, specSyncTool;
 var init_specSync = __esm({
   "src/subagents/specSync/index.ts"() {
     "use strict";
     init_assets();
     init_runner();
     init_context();
-    init_tools8();
+    init_tools9();
     init_writeBuildOverview();
-    init_tools7();
+    init_tools8();
     init_lock();
     init_surfaces();
-    BASE_PROMPT5 = readAsset("subagents/specSync", "prompt.md");
+    BASE_PROMPT6 = readAsset("subagents/specSync", "prompt.md");
     MSFM_DOCS = `<mindstudio_flavored_markdown_spec_docs>
 ${readAsset(
       "prompt",
@@ -8370,7 +8492,7 @@ ${readAsset(
         }
         const specIndex = loadSpecIndex();
         const parts = [
-          BASE_PROMPT5,
+          BASE_PROMPT6,
           loadPlatformBrief(),
           MSFM_DOCS,
           "<!-- cache_breakpoint -->"
@@ -8502,7 +8624,7 @@ function executeTool(name, input, context) {
   return tool.execute(input, context);
 }
 var ALL_TOOLS, SUBAGENT_TOOL_NAMES;
-var init_tools8 = __esm({
+var init_tools9 = __esm({
   "src/tools/index.ts"() {
     "use strict";
     init_readSpec();
@@ -8516,7 +8638,6 @@ var init_tools8 = __esm({
     init_promptUser();
     init_confirmDestructiveAction();
     init_sdkConsultant();
-    init_searchGoogle();
     init_setProjectMetadata();
     init_compactConversation();
     init_loadSkill();
@@ -8541,6 +8662,7 @@ var init_tools8 = __esm({
     init_codeSanityCheck();
     init_copyEditor();
     init_specSync();
+    init_research();
     init_scrapeWebUrl2();
     init_writeBuildOverview();
     ALL_TOOLS = [
@@ -8550,7 +8672,6 @@ var init_tools8 = __esm({
       confirmDestructiveActionTool,
       askMindStudioSdkTool,
       scrapeWebUrlTool,
-      searchGoogleTool,
       setProjectMetadataTool,
       designExpertTool,
       productVisionTool,
@@ -8589,7 +8710,8 @@ var init_tools8 = __esm({
       // Appended rather than grouped: position is part of the cache prefix, so a
       // new tool goes at the end to leave every existing session's prefix intact.
       loadSkillTool,
-      testJewelTool
+      testJewelTool,
+      researchTool
     ];
     SUBAGENT_TOOL_NAMES = /* @__PURE__ */ new Set([
       "visualDesignExpert",
@@ -8598,7 +8720,8 @@ var init_tools8 = __esm({
       "copyEditor",
       "specSync",
       "runAutomatedBrowserTest",
-      "askMindStudioSdk"
+      "askMindStudioSdk",
+      "research"
     ]);
   }
 });
@@ -10110,7 +10233,7 @@ var init_agent = __esm({
   "src/agent.ts"() {
     "use strict";
     init_api();
-    init_tools8();
+    init_tools9();
     init_session();
     init_logger();
     init_usageLedger();
@@ -10821,7 +10944,7 @@ var init_headless = __esm({
     init_attachments();
     init_planFile();
     init_stats();
-    init_tools8();
+    init_tools9();
     init_messageQueue();
     init_resolve();
     init_sentinel();