aether-code 0.43.0 → 0.43.1

package/src/agent.js

@@ -3,66 +3,98 @@
 // tool calls (task done) or max-turns is reached.
 
 import os from "node:os";
+import fs from "node:fs";
 import path from "node:path";
-import { spawn } from "node:child_process";
 import { agentTurnStream, AetherError } from "./api.js";
 import { TOOL_DEFINITIONS, executeTool } from "./tools.js";
 import { unnamespaceToolName } from "./mcp.js";
 import { loadAllSkills, selectSkills, renderSkillsBlock } from "./skills.js";
-import { scanProject, detectVerifyCommand, detectBuildCommand } from "./project-context.js";
-import { c, divider, turn, toolLabel, toolSummary, makeTokenStripper, errorLine, startSpinner } from "./render.js";
+import { c, divider, turn, toolLabel, toolSummary, makeTokenStripper, errorLine, startSpinner, turnStats, fmtTokens } from "./render.js";
 
-const DEFAULT_MAX_TURNS = 25;
+/* ─────────────────────── Image attachment parsing ─────────────────────── */
 
-// Rolling history window (messages) sent upstream per turn. The session keeps
-// the full transcript locally, but we only forward the anchor (first message,
-// which carries the [environment] block) plus the most recent N messages. This
-// bounds per-turn token cost AND keeps us safely under the server's own cap —
-// a long session used to grow unbounded and, past the server's limit, every
-// send failed with "Error: Invalid input." with no recovery but /clear.
-const HISTORY_WINDOW = 100;
+const IMAGE_EXTS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"]);
+const MIME_MAP = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".bmp": "image/bmp",
+};
 
-/**
- * Trim a message array to `maxMessages`, preserving:
- *   - the anchor message at index 0 (the first user turn carries the
- *     [environment] block with real absolute paths — dropping it makes the
- *     model lose cwd/home/desktop);
- *   - tool-call/tool-result pairing at the window boundary: a `tool` message
- *     must immediately follow the assistant message whose `tool_calls` produced
- *     it, so the window is never allowed to BEGIN on an orphaned `tool` result.
- * Returns the original array untouched when it's already within the window.
- */
-export function trimHistory(messages, maxMessages = HISTORY_WINDOW) {
-  if (messages.length <= maxMessages) return messages;
-  const head = [messages[0]];
-  const windowSize = Math.max(1, maxMessages - 1);
-  let window = messages.slice(1).slice(-windowSize);
-  let start = 0;
-  while (start < window.length && window[start]?.role === "tool") start++;
-  window = window.slice(start);
-  return [...head, ...window];
+// Parse @path/to/image references from user input. Supports quoted paths for
+// spaces: @"C:\Users\me\my screenshot.png". Returns { text, images }.
+function parseImages(prompt, cwd) {
+  const re = /@("(?:[^"\\]|\\.)*"|[^\s]+)/g;
+  const images = [];
+  let cleaned = prompt;
+
+  for (const m of [...prompt.matchAll(re)]) {
+    const raw = m[1].replace(/^"|"$/g, "");
+    const ext = path.extname(raw).toLowerCase();
+    if (!IMAGE_EXTS.has(ext)) continue;
+
+    const abs = path.isAbsolute(raw) ? raw : path.resolve(cwd, raw);
+    try {
+      const buf = fs.readFileSync(abs);
+      if (buf.length > 20 * 1024 * 1024) {
+        console.log(c.yellow(`  ⚠ Image too large (>20MB), skipping: ${raw}`));
+        continue;
+      }
+      const mime = MIME_MAP[ext] || "image/png";
+      images.push({
+        url: `data:${mime};base64,${buf.toString("base64")}`,
+        name: path.basename(raw),
+        size: buf.length,
+      });
+      cleaned = cleaned.replace(m[0], "");
+    } catch (e) {
+      console.log(c.yellow(`  ⚠ Could not read image: ${raw} — ${e.code === "ENOENT" ? "file not found" : e.message}`));
+    }
+  }
+
+  return { text: cleaned.replace(/\s{2,}/g, " ").trim() || prompt.trim(), images };
+}
+
+// Build OpenAI-compatible content array with text + images, or plain string
+// when no images are attached.
+function buildContent(text, images) {
+  if (images.length === 0) return text;
+  const parts = [];
+  for (const img of images) {
+    parts.push({ type: "image_url", image_url: { url: img.url } });
+  }
+  parts.push({ type: "text", text });
+  return parts;
 }
 
-export const MOD_RE =
-  /\b(refactor|fix|add|adds?|change|update|implement|creat|writ|remov|delet|rename|extract|move|replace|build|generate|insert|append|convert|migrat|wire|hook|edit|modif|patch|integrat)/i;
+// Friendly file size: 1.2MB, 450KB, 128B
+function fmtSize(bytes) {
+  if (bytes >= 1_048_576) return (bytes / 1_048_576).toFixed(1) + "MB";
+  if (bytes >= 1024) return (bytes / 1024).toFixed(0) + "KB";
+  return bytes + "B";
+}
+
+const DEFAULT_MAX_TURNS = 25;
 
-export function envContext(cwd) {
+// Environment block prepended to the first user message so the model can
+// resolve named locations to real absolute paths.
+function envContext(cwd) {
   const home = os.homedir();
   const desktop = path.join(home, "Desktop");
   const documents = path.join(home, "Documents");
   const win = process.platform === "win32";
+  // OS-specific shell guidance: gemma tends to emit Unix commands (mkdir -p,
+  // touch, &&-chains) which FAIL in Windows cmd.exe ("The syntax of the command
+  // is incorrect"). Steer it to the file tools (which are cross-platform and
+  // auto-create parent dirs) and OS-appropriate shell usage.
   const shellNote = win
     ? `shell: Windows cmd.exe. To create files OR directories, use the write_file tool — ` +
       `it creates any missing parent folders automatically. Do NOT use shell "mkdir -p", ` +
       `"touch", "ls", "rm", "cp", "mv", or "&&"-chained Unix commands; they FAIL in cmd.exe. ` +
       `Run programs/tests with their interpreter (python, node, java, etc.).`
     : `shell: POSIX sh. Standard Unix commands are available. write_file still auto-creates parent dirs.`;
-
-  let projectBlock = "";
-  try {
-    projectBlock = scanProject(cwd);
-  } catch { /* non-fatal */ }
-
   return (
     `[environment]\n` +
     `os: ${process.platform}\n` +
@@ -74,8 +106,7 @@ export function envContext(cwd) {
     `When the user names a location ("my desktop", "home", "documents"), write to ` +
     `the matching ABSOLUTE path above (e.g. desktop -> ${desktop}). Otherwise ` +
     `work under the cwd. Use absolute paths when a specific location is named.\n` +
-    `[/environment]\n\n` +
-    (projectBlock ? projectBlock + "\n" : "")
+    `[/environment]\n\n`
   );
 }
 
@@ -111,6 +142,15 @@ export async function runAgent({
     process.stderr.write(c.yellow(`(skill load failed: ${e.message})\n`));
   }
   const referencedPaths = [];
+
+  // Parse image attachments (@path/to/image.png) from the user's prompt.
+  const { text: cleanPrompt, images: attachedImages } = parseImages(initialPrompt, cwd);
+  if (attachedImages.length > 0) {
+    for (const img of attachedImages) {
+      console.log(`\n${c.cyan("●")} ${c.cyan(c.bold("image"))} ${c.gray(img.name)} ${c.gray(`(${fmtSize(img.size)})`)}`);
+    }
+  }
+
   // Two callers: one-shot (initialPrompt only, fresh conversation) and REPL
   // (priorMessages + initialPrompt to continue an ongoing chat).
   // On the FIRST message of a session, prepend an environment block so the
@@ -118,9 +158,11 @@ export async function runAgent({
   // X on my desktop" became `mkdir X` in whatever dir aether was launched from
   // (e.g. C:\WINDOWS\system32). Only prepended once — later turns carry it in
   // history.
+  const firstText = priorMessages ? cleanPrompt : envContext(cwd) + cleanPrompt;
+  const firstContent = buildContent(firstText, attachedImages);
   const messages = priorMessages
-    ? [...priorMessages, { role: "user", content: initialPrompt }]
-    : [{ role: "user", content: envContext(cwd) + initialPrompt }];
+    ? [...priorMessages, { role: "user", content: firstContent }]
+    : [{ role: "user", content: firstContent }];
   let totalCredits = 0;
   let totalIn = 0;
   let totalOut = 0;
@@ -137,29 +179,30 @@ export async function runAgent({
   // Completeness guard: gemma sometimes reads files then narrates the fix as
   // text, or refactors one file but forgets the others. If a MODIFICATION task
   // finishes having read files it never edited, we nudge it once to finish.
+  const MOD_RE =
+    /\b(refactor|fix|add|adds?|change|update|implement|creat|writ|remov|delet|rename|extract|move|replace|build|generate|insert|append|convert|migrat|wire|hook|edit|modif|patch|integrat)/i;
   const looksLikeModification = MOD_RE.test(initialPrompt);
   let appliedNothingNudges = 0;
-  let verifyRounds = 0;
-  let buildRounds = 0;
 
   for (let i = 0; i < maxTurns; i++) {
-    // No turn header and no leading blank here — each step (assistant text and
-    // each tool label) begins with its own "\n● ", so spacing stays exactly one
-    // blank line per step instead of stacking up.
+    const turnStart = Date.now();
 
     // Stream the assistant's response. Print text deltas as they arrive,
     // along with tool-call announcements as soon as the model commits to
     // calling a particular tool (i.e. the `name` arrives in the stream).
     const announced = new Set();
     let lastWasText = false;
+    let streamedChars = 0;
     const stripper = makeTokenStripper();
+    let leakBuf = "";
+    let leakSuppressing = false;
 
     // Select skills for this turn against the current user prompt + any
     // paths the model has read so far. Prepend the matching skills' bodies
     // to the last user message of a shallow-cloned messages array — we
     // don't want skill text accumulating in the persisted history, only
     // being available to the model for the turn where it's relevant.
-    const turnMessages = trimHistory(buildTurnMessages(messages, allSkills, referencedPaths));
+    const turnMessages = buildTurnMessages(messages, allSkills, referencedPaths);
 
     let res;
     // "Thinking" spinner: shown from request-send until the first token or tool
@@ -173,19 +216,34 @@ export async function runAgent({
         tools,
         model,
         onDelta: (text) => {
-          // Buffered strip of leaked model channel/control tokens (which can
-          // be split across stream chunks) before display.
+          streamedChars += text.length;
+          spinner.update({ tokens: Math.ceil(streamedChars / 3.5) });
           const clean = stripper.push(text);
           if (!clean) return;
-          // Don't open a "● " bullet for leading whitespace (e.g. when a whole
-          // turn's text was suppressed as a leak, leaving only a stray newline).
-          if (!lastWasText && !clean.trim()) return;
+
+          // Suppress model echoing tool results (response:web_search, [{snippet:, etc.)
+          leakBuf += clean;
+          if (leakBuf.length < 40 && /^[\s\n]*(?:response:|[\[{]"?(?:snippet|title|url))/.test(leakBuf)) return;
+          if (leakSuppressing) {
+            if (clean.includes("\n\n")) { leakSuppressing = false; leakBuf = ""; }
+            return;
+          }
+          const checkBuf = leakBuf.trim();
+          if (checkBuf && /^response:\w|^\[\{(?:"?snippet|"?title)/.test(checkBuf)) {
+            leakSuppressing = true;
+            leakBuf = "";
+            return;
+          }
+          const emit = leakBuf;
+          leakBuf = "";
+
+          if (!lastWasText && !emit.trim()) return;
           stopSpin();
           if (!lastWasText) {
             process.stdout.write("\n" + c.cyan("● "));
             lastWasText = true;
           }
-          process.stdout.write(clean);
+          process.stdout.write(emit);
         },
         onToolCallDelta: (delta) => {
           // Just close the streamed text line when the model starts a tool
@@ -215,13 +273,13 @@ export async function runAgent({
       process.stdout.write(tail);
     }
     if (lastWasText) process.stdout.write("\n");
+    const turnIn = res.usage?.prompt_tokens ?? 0;
+    const turnOut = res.usage?.completion_tokens ?? 0;
     totalCredits += res.creditsCharged ?? 0;
-    totalIn += res.usage?.prompt_tokens ?? 0;
-    totalOut += res.usage?.completion_tokens ?? 0;
+    totalIn += turnIn;
+    totalOut += turnOut;
     if (typeof res.balanceAfter === "number") lastBalance = res.balanceAfter;
     onTokens({ totalCredits, totalIn, totalOut, balance: lastBalance });
-    // Per-turn cost line removed for a cleaner look — the session summary at the
-    // end carries the totals.
 
     // Push assistant message into history
     messages.push({
@@ -250,88 +308,6 @@ export async function runAgent({
         messages.push({ role: "user", content: msg });
         continue; // give the model another turn to finish
       }
-      // Auto-build: if we wrote source files, detect the build toolchain and
-      // compile automatically. If build fails, feed errors back to the model
-      // so it can fix and recompile. Max 5 rounds to avoid infinite loops.
-      if (filesTouched.size > 0 && buildRounds < 5) {
-        const buildResult = await runBuild(cwd, [...filesTouched.keys()]);
-        if (buildResult && !buildResult.ok) {
-          buildRounds++;
-          console.log("\n" + c.yellow("●") + " " + c.bold("auto-build") + c.gray(` (${buildResult.label}) — round ${buildRounds}/5`));
-          console.log(c.red("  └─") + " " + c.gray("build failed — feeding errors back to fix"));
-          const errPreview = buildResult.output.length > 6000
-            ? buildResult.output.slice(0, 6000) + "\n…(truncated)"
-            : buildResult.output;
-          messages.push({
-            role: "user",
-            content:
-              `AUTO-BUILD FAILED (${buildResult.label}):\n\`\`\`\n${errPreview}\n\`\`\`\n` +
-              `Fix the build errors NOW using edit_file. Do not explain — just fix the code and move on.`,
-          });
-          continue;
-        }
-        if (buildResult && buildResult.ok) {
-          console.log("\n" + c.green("●") + " " + c.bold("auto-build") + c.gray(` (${buildResult.label}) — success`));
-          // If there's a run command and we haven't already run it, execute the result
-          if (buildResult.runCmd && buildRounds === 0) {
-            const runResult = await runBuiltProgram(cwd, buildResult.runCmd, buildResult.label);
-            if (runResult && !runResult.ok && buildRounds < 5) {
-              buildRounds++;
-              console.log(c.yellow("  ├─") + " " + c.bold("auto-run") + c.gray(` — crashed (exit ${runResult.code})`));
-              const errPreview = runResult.output.length > 6000
-                ? runResult.output.slice(0, 6000) + "\n…(truncated)"
-                : runResult.output;
-              messages.push({
-                role: "user",
-                content:
-                  `BUILD SUCCEEDED but the program CRASHED when run:\n\`\`\`\n${errPreview}\n\`\`\`\n` +
-                  `Fix the runtime error NOW using edit_file. Do not explain — just fix and move on.`,
-              });
-              continue;
-            }
-            if (runResult && runResult.ok) {
-              const preview = runResult.output.length > 2000
-                ? runResult.output.slice(0, 2000) + "\n…(truncated)"
-                : runResult.output;
-              if (runResult.timedOut) {
-                console.log(c.green("  ├─") + " " + c.bold("auto-run") + c.gray(" — running (still alive after 10s)"));
-              } else {
-                console.log(c.green("  ├─") + " " + c.bold("auto-run") + c.gray(` — exit 0`));
-              }
-              if (preview.trim()) {
-                const lines = preview.trim().split("\n").slice(0, 15);
-                for (const line of lines) {
-                  console.log(c.gray("  │  " + line));
-                }
-              }
-            }
-          }
-        }
-      }
-      // Auto-verify: if we touched files, run the project's typecheck/lint
-      // and feed errors back so the model can self-correct without the user
-      // having to say "fix that." At most 2 verify rounds to avoid infinite loops.
-      if (filesTouched.size > 0 && verifyRounds < 2) {
-        const verifyResult = await runVerify(cwd);
-        if (verifyResult && !verifyResult.ok) {
-          verifyRounds++;
-          console.log("\n" + c.yellow("●") + " " + c.bold("auto-verify") + c.gray(` (${verifyResult.label})`));
-          console.log(c.red("  └─") + " " + c.gray("errors found — feeding back to fix"));
-          const errPreview = verifyResult.output.length > 4000
-            ? verifyResult.output.slice(0, 4000) + "\n…(truncated)"
-            : verifyResult.output;
-          messages.push({
-            role: "user",
-            content:
-              `AUTO-VERIFY FAILED (${verifyResult.label}):\n\`\`\`\n${errPreview}\n\`\`\`\n` +
-              `Fix these errors NOW using edit_file. Do not explain — just fix and move on.`,
-          });
-          continue;
-        }
-        if (verifyResult && verifyResult.ok) {
-          console.log("\n" + c.green("●") + " " + c.bold("auto-verify") + c.gray(` (${verifyResult.label}) — passed`));
-        }
-      }
       if (filesTouched.size) {
         console.log("\n" + c.bold("Files") + c.gray(` in ${cwd}`));
         for (const [p, action] of filesTouched) {
@@ -400,133 +376,44 @@ export async function runAgent({
       const summary = toolSummary(call.function.name, result);
       if (summary) console.log(summary);
 
+      // Cap tool result content sent to the model to prevent it from
+      // echoing raw data (snippets, HTML dumps) back as text output.
+      let toolContent = result.output ?? (result.ok ? "(no output)" : "Failed.");
+      if (call.function.name === "web_search") {
+        try {
+          const arr = JSON.parse(toolContent);
+          if (Array.isArray(arr)) {
+            toolContent = JSON.stringify(arr.map((r) => ({
+              title: r.title, url: r.url,
+              snippet: (r.snippet || "").slice(0, 120),
+            })));
+          }
+        } catch { /* leave as-is */ }
+      } else if (call.function.name === "web_fetch") {
+        if (toolContent.length > 12000) toolContent = toolContent.slice(0, 12000) + "\n...(truncated)";
+      } else if (call.function.name === "read_file") {
+        if (toolContent.length > 30000) toolContent = toolContent.slice(0, 30000) + "\n...(truncated)";
+      }
       messages.push({
         role: "tool",
         tool_call_id: call.id,
-        content: result.output ?? (result.ok ? "(no output)" : "Failed."),
+        content: toolContent,
       });
     }
-  }
 
-  console.log(c.yellow(`\nReached max turns (${maxTurns}). Stopping.`));
-  return { ok: false, error: new Error("Max turns reached"), totalCredits, totalIn, totalOut, balance: lastBalance, messages };
-}
-
-// A build/verify command failing because the TOOLCHAIN ITSELF is missing (e.g.
-// g++/cargo/dotnet not installed) is not a code bug — it must NOT be reported as
-// "build failed" and fed back to the model, which would derail the run into
-// 5 rounds of "fixing" code that's actually fine. These are the shell's
-// command-not-found messages (Windows cmd.exe + POSIX sh); real compiler
-// diagnostics look like `main.cpp:5:10: error: ...` and never match these.
-// Matches ONLY the shell's "I can't find this executable" messages — Windows
-// cmd.exe ("'g++' is not recognized…") and POSIX sh ("g++: command not found",
-// "sh: 1: g++: not found"). Real compiler diagnostics (`main.cpp:5: error:`,
-// `fatal error: foo.h: No such file or directory`) never match these, so a
-// genuine build error is still reported and fixed.
-const TOOLCHAIN_MISSING_RE =
-  /is not recognized as an internal or external command|: command not found|: not found\b/i;
-
-// Auto-verify: run the project's typecheck/lint command silently and return
-// { ok, output, label }. Returns null if no verify command is detected OR the
-// toolchain isn't installed (skip, don't report a false failure).
-let cachedVerify = undefined;
-async function runVerify(cwd) {
-  if (cachedVerify === undefined) cachedVerify = detectVerifyCommand(cwd);
-  if (!cachedVerify) return null;
-  const { cmd, label } = cachedVerify;
-  return new Promise((resolve) => {
-    const child = spawn(cmd, [], { cwd, shell: true, stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    const timer = setTimeout(() => { child.kill("SIGTERM"); }, 60_000);
-    child.stdout.on("data", (d) => { stdout += d.toString(); });
-    child.stderr.on("data", (d) => { stderr += d.toString(); });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      const output = (stdout + "\n" + stderr).trim();
-      // Toolchain not installed → skip silently rather than nag the model.
-      if (code !== 0 && TOOLCHAIN_MISSING_RE.test(output)) { resolve(null); return; }
-      resolve({ ok: code === 0, output, label });
-    });
-    child.on("error", () => {
-      clearTimeout(timer);
-      resolve(null);
+    // Per-turn stats line — shows elapsed time, token flow, and tool count.
+    const stats = turnStats({
+      elapsed: Date.now() - turnStart,
+      tokensIn: turnIn,
+      tokensOut: turnOut,
+      tools: toolCalls.length,
+      credits: res.creditsCharged ?? 0,
     });
-  });
-}
-
-// Auto-build: detect the build toolchain from written files and compile.
-// Returns { ok, output, label, runCmd } or null if no buildable project detected.
-let cachedBuild = undefined;
-async function runBuild(cwd, touchedFiles) {
-  // Re-detect every time because the model may create new files (e.g. Makefile)
-  // or change the project structure between rounds.
-  const detected = detectBuildCommand(cwd, touchedFiles);
-  if (!detected) {
-    // Fallback: if we previously detected a build command, reuse it (the model
-    // may have only edited files this round, not created new ones).
-    if (cachedBuild) return runBuildCmd(cwd, cachedBuild);
-    return null;
+    if (stats) console.log(stats);
   }
-  cachedBuild = detected;
-  return runBuildCmd(cwd, detected);
-}
-
-async function runBuildCmd(cwd, { cmd, label, type, runCmd }) {
-  return new Promise((resolve) => {
-    const child = spawn(cmd, [], { cwd, shell: true, stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    const timer = setTimeout(() => { child.kill("SIGTERM"); }, 120_000);
-    child.stdout.on("data", (d) => { stdout += d.toString(); });
-    child.stderr.on("data", (d) => { stderr += d.toString(); });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      const output = (stdout + "\n" + stderr).trim();
-      // Compiler/toolchain not installed → skip auto-build silently instead of
-      // reporting a build failure and derailing the run.
-      if (code !== 0 && TOOLCHAIN_MISSING_RE.test(output)) { resolve(null); return; }
-      resolve({ ok: code === 0, output, label, type, runCmd });
-    });
-    child.on("error", () => {
-      clearTimeout(timer);
-      // ENOENT (command not found) → toolchain missing → skip.
-      resolve(null);
-    });
-  });
-}
 
-// Run the compiled/interpreted program after a successful build.
-// Returns { ok, output, code, timedOut } or null on spawn error.
-async function runBuiltProgram(cwd, runCmd, label) {
-  return new Promise((resolve) => {
-    const child = spawn(runCmd, [], { cwd, shell: true, stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    let timedOut = false;
-    const timer = setTimeout(() => { timedOut = true; child.kill("SIGTERM"); }, 10_000);
-    child.stdout.on("data", (d) => {
-      stdout += d.toString();
-      if (stdout.length > 50_000) { child.kill("SIGTERM"); }
-    });
-    child.stderr.on("data", (d) => {
-      stderr += d.toString();
-      if (stderr.length > 50_000) { child.kill("SIGTERM"); }
-    });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      const output = (stdout + "\n" + stderr).trim();
-      if (timedOut) {
-        resolve({ ok: true, output, code: null, timedOut: true });
-      } else {
-        resolve({ ok: code === 0, output, code, timedOut: false });
-      }
-    });
-    child.on("error", (err) => {
-      clearTimeout(timer);
-      resolve({ ok: false, output: err.message, code: null, timedOut: false });
-    });
-  });
+  console.log(c.yellow(`\nReached max turns (${maxTurns}). Stopping.`));
+  return { ok: false, error: new Error("Max turns reached"), totalCredits, totalIn, totalOut, balance: lastBalance, messages };
 }
 
 /**
@@ -543,7 +430,7 @@ async function runBuiltProgram(cwd, runCmd, label) {
  * worse than no skills at all. Prepending into the user message keeps
  * both layers active.
  */
-export function buildTurnMessages(messages, allSkills, referencedPaths) {
+function buildTurnMessages(messages, allSkills, referencedPaths) {
   if (allSkills.length === 0) return messages;
   // Find the latest user message — that's where the current task lives.
   let lastUserIdx = -1;
@@ -551,16 +438,30 @@ export function buildTurnMessages(messages, allSkills, referencedPaths) {
     if (messages[i].role === "user") { lastUserIdx = i; break; }
   }
   if (lastUserIdx === -1) return messages;
-  const prompt = typeof messages[lastUserIdx].content === "string"
-    ? messages[lastUserIdx].content
-    : "";
+  // Content can be a string or a multimodal array (when images are attached).
+  // Extract the text portion for skill selection; prepend skills to text only.
+  const rawContent = messages[lastUserIdx].content;
+  let prompt;
+  if (typeof rawContent === "string") {
+    prompt = rawContent;
+  } else if (Array.isArray(rawContent)) {
+    const textPart = rawContent.find((p) => p.type === "text");
+    prompt = textPart?.text ?? "";
+  } else {
+    prompt = "";
+  }
   const active = selectSkills({ skills: allSkills, prompt, referencedPaths });
   if (active.length === 0) return messages;
   const block = renderSkillsBlock(active);
   const cloned = [...messages];
-  cloned[lastUserIdx] = {
-    ...cloned[lastUserIdx],
-    content: `${block}\n\n---\n\n${prompt}`,
-  };
+  // Inject skill block into the text portion of the content.
+  if (typeof rawContent === "string") {
+    cloned[lastUserIdx] = { ...cloned[lastUserIdx], content: `${block}\n\n---\n\n${prompt}` };
+  } else if (Array.isArray(rawContent)) {
+    const newParts = rawContent.map((p) =>
+      p.type === "text" ? { ...p, text: `${block}\n\n---\n\n${p.text}` } : p,
+    );
+    cloned[lastUserIdx] = { ...cloned[lastUserIdx], content: newParts };
+  }
   return cloned;
 }