u-foo 3.0.2 → 3.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Multi-Agent Workspace Protocol. Just add u. claude → uclaude, codex → ucodex.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://ufoo.dev",

package/src/agents/prompts/native/toolDescriptions/readImage.js

@@ -0,0 +1,23 @@
+"use strict";
+
+/**
+ * Tool description for read_image (workspace vision).
+ */
+
+const READ_IMAGE_TOOL_NAME = "read_image";
+
+function getReadImageToolDescription() {
+  return `Read an image file from the workspace so the model can see it.
+
+Usage notes:
+- The path parameter is relative to the workspace root.
+- Supports png, jpeg, gif, and webp. Max size ~5MB.
+- Use this instead of read for screenshots, UI mocks, diagrams, and other binary images.
+- Text files still use read. Do not call read_image on non-image files.
+- Vision is attached for the current model call only; call read_image again if you need the image later.`;
+}
+
+module.exports = {
+  READ_IMAGE_TOOL_NAME,
+  getReadImageToolDescription,
+};

package/src/code/context/assembler.js

@@ -34,6 +34,7 @@ const {
 const { renderExecutionSegmentContext } = require("./executionSegment");
 const { renderPlanModeContext } = require("./planMode");
 const { drainAgentMailboxForTurn } = require("../runtime/agentWakeup");
+const { stripVisionBase64, degradeVisionContent } = require("../providers/visionBlocks");
 
 const DEFAULT_TRANSCRIPT_WINDOW = 12;
 const DEFAULT_RECENT_TOOL_EVENTS = 4;
@@ -291,6 +292,19 @@ function sanitizeModelMessages(messages = []) {
       continue;
     }
 
+    // Drop ephemeral OpenAI vision companion user messages (image_url data URIs)
+    // when rebuilding history so base64 does not re-enter later turns.
+    if (role === "user" && Array.isArray(message.content)) {
+      const hasImageUrl = message.content.some((block) => (
+        block && String(block.type || "").trim().toLowerCase() === "image_url"
+      ));
+      if (hasImageUrl) {
+        const degraded = degradeVisionContent(message.content);
+        out.push({ role: "user", content: degraded });
+        continue;
+      }
+    }
+
     out.push(message);
   }
   return out;
@@ -435,16 +449,18 @@ function persistToolResultToContext({
   rawResult = {},
   segmentId = "",
 } = {}) {
+  const rawForStorage = stripVisionBase64(rawResult);
   const saved = saveArtifact(workspaceRoot, sessionId, {
     type: "tool_result",
     tool,
     args,
-    raw: rawResult,
+    raw: rawForStorage,
     createdBy: tool,
   });
   const artifactId = saved.artifact && saved.artifact.artifactId
     ? saved.artifact.artifactId
     : "";
+  // Reduce from the live result so vision base64 stays available for this turn.
   const reduced = reduceToolResult(tool, rawResult, artifactId, args);
   return {
     artifactId,

package/src/code/context/planMode.js

@@ -181,7 +181,7 @@ function formatPlanModeStatus(executionState = null) {
     lines.push("Rules while ON:");
     lines.push("  - Use plan_graph to create/expand/complete the plan");
     lines.push("  - write / edit / bash are blocked as direct tools");
-    lines.push("  - read / artifact_read allowed for exploration");
+    lines.push("  - read / read_image / artifact_read allowed for exploration");
     lines.push("  - Runtime auto-advances ready tool nodes after plan_graph");
     lines.push("  - User leaves with /plan off (agents cannot toggle Plan Mode)");
   } else {
@@ -223,7 +223,7 @@ function renderPlanModeContext(executionState = null) {
   }
 
   lines.push(
-    "Allowed direct tools: read, artifact_read, plan_graph, ask_user.",
+    "Allowed direct tools: read, read_image, artifact_read, plan_graph, ask_user.",
     "Blocked direct tools: write, edit, bash (route them as plan_graph tool nodes or task_loop).",
     "Plan Mode constrains the Agent Loop only; running TaskLoops are not paused or reconfigured by /plan off.",
     "Only the user can leave Plan Mode (/plan off). That does not cancel the graph or TaskRuns — use cancel_graph / control.cancel_task.",

package/src/code/context/promptLayers.js

@@ -31,7 +31,7 @@ const {
 } = require("../skills");
 const { hashContent } = require("./artifacts");
 
-const PROMPT_VERSION = "native-v6";
+const PROMPT_VERSION = "native-v7";
 
 function buildImmutablePrefix() {
   return [
@@ -44,23 +44,24 @@ function buildImmutablePrefix() {
     getOutputEfficiencySection(),
     [
       "Tool calling grammar:",
-      "- Use read, write, edit, bash, and artifact_read for direct, single-goal work, even when it takes several tool calls.",
+      "- Use read, write, edit, bash, and artifact_read for direct, single-goal text work, even when it takes several tool calls.",
+      "- Use read_image to load workspace png/jpeg/gif/webp images for vision. Do not use read on binary images. Vision is attached for the active model call only; call read_image again if you need the image later.",
       "- TaskRuns are orthogonal to Plan Mode. A TaskRun does not require Plan Mode or a plan_graph. Use task_run operation=start with an objective for a standalone single-point TaskRun; it starts asynchronously and returns immediately.",
       "- On complex or multi-goal requests, automatically decompose into concrete sub-objectives and start TaskRun(s) via task_run. Prefer task_run for independent or loosely coupled tracks; use plan_graph only when you need durable dependencies, checkpoints, or a shared executable plan.",
       "- Use plan_graph for durable graph structure: create, patch, inspect, cancel_graph, and control. Graph-bound TaskRuns use plan_graph control.start_task on execution.kind=task_loop nodes.",
-      "- Plan Mode is a runtime posture for the Agent Loop, not an agent tool. While Plan Mode is ON, direct write, edit, and bash calls from the Agent Loop are blocked; read and artifact_read remain available. TaskRuns still run independently of Plan Mode.",
+      "- Plan Mode is a runtime posture for the Agent Loop, not an agent tool. While Plan Mode is ON, direct write, edit, and bash calls from the Agent Loop are blocked; read, read_image, and artifact_read remain available. TaskRuns still run independently of Plan Mode.",
       "- In the Agent Loop, plan_graph operation=create automatically enables Plan Mode. The user may also use /plan on or /plan off.",
       "- Turning Plan Mode off does not cancel an existing graph or running TaskRuns. Cancel with task_run (standalone) or plan_graph operation=cancel_graph / control.cancel_task (graph-bound).",
       "- When the user enables Plan Mode and no active graph exists, create a plan_graph before performing side effects.",
       "- After an accepted plan_graph create or patch, Runtime automatically advances ready tool nodes. Never invent or request an execute_graph tool.",
-      "- Do not call plan_graph or task_run together with read, write, edit, bash, or artifact_read in the same assistant turn.",
+      "- Do not call plan_graph or task_run together with read, read_image, write, edit, bash, or artifact_read in the same assistant turn.",
       "- When an active graph is waiting on a task, advance that node through plan_graph instead of bypassing it with direct workspace tools: use patch.expand_node for execution.kind=expand, control.complete_task (nodeId) for execution.kind=inline_llm, or control.start_task for execution.kind=task_loop.",
       "- control.complete_task with nodeId completes a waiting_llm inline_llm task for the current Graph owner. control.complete_task with taskRunId (or task_run complete) is reserved for the owning TaskLoop. Do not directly complete expand or aggregate tasks.",
       "- While Plan Mode is ON, workspace mutations must be represented as plan_graph tool nodes or performed inside a running TaskRun/task_loop.",
       "- Treat a User reminder as the latest user instruction. Reconcile it before continuing from tool results. If it is compatible with the active plan, resume the waiting plan node; otherwise patch, cancel, or replan first.",
       "- TaskLoops do not consume User reminders. The Agent Loop is woken by runtime task_started, task_succeeded, task_failed, and task_cancelled events.",
       "- Runtime enforces TaskRun concurrency limits and workspace write leases. Direct Agent write, edit, or bash calls may be rejected while writing TaskRuns are active.",
-      "- Tool results may contain an artifactId. Use artifact_read to hydrate raw stored output or a slice of it; use read for workspace file paths.",
+      "- Tool results may contain an artifactId. Use artifact_read to hydrate raw stored output or a slice of it; use read for workspace text paths; use read_image for workspace images.",
       "- Use ask_user only when user input is required to proceed. It must be the only tool call in the turn. Use kind=approval for yes/no confirmation, kind=choice for numbered options, and kind=chat for free text.",
       "- The answer to ask_user is returned only as that tool's result, not as a separate user message or pending User reminder. Continue from the returned answer and do not repeat the question.",
       "- ask_user is available only to the Agent Loop. It pauses the Agent Loop, but running TaskRuns continue unless explicitly cancelled.",

package/src/code/context/reducers.js

@@ -287,9 +287,43 @@ function reduceArtifactReadResult(raw = {}, artifactId = "") {
   };
 }
 
+function reduceReadImageResult(raw = {}, artifactId = "") {
+  const source = raw && typeof raw === "object" ? raw : {};
+  const pathText = String(source.path || "").trim();
+  const mediaType = String(source.mediaType || "").trim();
+  const bytes = Number.isFinite(source.bytes) ? source.bytes : null;
+  const preview = source.ok === false
+    ? clipText(String(source.error || "read_image failed"), PREVIEW_MAX_CHARS)
+    : clipText(
+      `image ${pathText || "file"} (${mediaType || "unknown"}, ${bytes != null ? `${bytes} bytes` : "size?"})`,
+      PREVIEW_MAX_CHARS,
+    );
+  const modelPayload = {
+    ok: source.ok !== false,
+    kind: "image",
+    artifactId,
+    path: pathText,
+    mediaType,
+    bytes,
+    preview,
+  };
+  if (source.error) modelPayload.error = String(source.error);
+  // Keep base64 in the in-memory model payload for the current turn only.
+  // Artifacts / transcript strip it via stripVisionBase64 before persistence.
+  if (modelPayload.ok && source.base64) {
+    modelPayload.base64 = String(source.base64);
+  }
+  return {
+    preview,
+    summary: `read_image ${pathText || "file"} (${mediaType || "image"})`,
+    modelPayload,
+  };
+}
+
 function reduceToolResult(tool = "", raw = {}, artifactId = "", args = {}) {
   const name = String(tool || "").trim().toLowerCase();
   if (name === "read") return reduceReadResult(raw, artifactId);
+  if (name === "read_image") return reduceReadImageResult(raw, artifactId);
   if (name === "bash") return reduceBashResult(raw, artifactId, args);
   if (name === "write") return reduceWriteResult(raw, artifactId);
   if (name === "edit") return reduceEditResult(raw, artifactId);
@@ -318,6 +352,7 @@ module.exports = {
   parseSearchMatches,
   reduceToolResult,
   reduceReadResult,
+  reduceReadImageResult,
   reduceBashResult,
   reduceTestResult,
   reduceGitDiffResult,

package/src/code/context/transcriptSync.js

@@ -5,6 +5,7 @@ const {
   createTranscriptEventId,
   appendTranscriptEvent,
 } = require("./transcript");
+const { stripVisionBase64, degradeVisionContent } = require("../providers/visionBlocks");
 
 function messageRole(message = {}) {
   return String(message && message.role || "").trim().toLowerCase();
@@ -35,6 +36,24 @@ function parseToolArtifactContent(content = "") {
   }
 }
 
+function contentForStorage(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    const hasVision = content.some((block) => {
+      if (!block || typeof block !== "object") return false;
+      const type = String(block.type || "").trim().toLowerCase();
+      return type === "image" || type === "image_url"
+        || (type === "tool_result" && Array.isArray(block.content));
+    });
+    if (hasVision) return degradeVisionContent(stripVisionBase64(content));
+    return stripVisionBase64(content);
+  }
+  if (content && typeof content === "object") {
+    return stripVisionBase64(content);
+  }
+  return content;
+}
+
 function messageToTranscriptEventForStorage(message = {}, extra = {}) {
   if (!message || typeof message !== "object") return null;
   const role = messageRole(message);
@@ -60,9 +79,10 @@ function messageToTranscriptEventForStorage(message = {}, extra = {}) {
         toolCallId: message.tool_call_id ? String(message.tool_call_id) : undefined,
       });
     }
-    const preview = typeof message.content === "string"
-      ? message.content.slice(0, 600)
-      : JSON.stringify(message.content).slice(0, 600);
+    const stored = contentForStorage(message.content);
+    const preview = typeof stored === "string"
+      ? stored.slice(0, 600)
+      : JSON.stringify(stored).slice(0, 600);
     return normalizeTranscriptEvent({
       ...base,
       role: "tool",
@@ -75,14 +95,14 @@ function messageToTranscriptEventForStorage(message = {}, extra = {}) {
   if (role === "assistant" && Array.isArray(message.tool_calls) && message.tool_calls.length > 0) {
     return normalizeTranscriptEvent({
       ...base,
-      content: message.content,
+      content: contentForStorage(message.content),
       toolCalls: message.tool_calls,
     });
   }
 
   return normalizeTranscriptEvent({
     ...base,
-    content: message.content,
+    content: contentForStorage(message.content),
   });
 }
 

package/src/code/dispatch.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const { runReadTool } = require("./tools/read");
+const { runReadImageTool } = require("./tools/readImage");
 const { runWriteTool } = require("./tools/write");
 const { runEditTool } = require("./tools/edit");
 const { runBashTool } = require("./tools/bash");
@@ -11,6 +12,7 @@ const { runAskUserTool } = require("./tools/askUser");
 
 const TOOL_NAMES = [
   "read",
+  "read_image",
   "write",
   "edit",
   "bash",
@@ -23,6 +25,7 @@ const TOOL_NAMES = [
 function normalizeToolName(value = "") {
   const text = String(value || "").trim().toLowerCase();
   if (text === "read") return "read";
+  if (text === "read_image" || text === "read-image" || text === "readimage") return "read_image";
   if (text === "write") return "write";
   if (text === "edit") return "edit";
   if (text === "bash") return "bash";
@@ -44,6 +47,7 @@ function runToolCall(input = {}, options = {}) {
     };
   }
   if (tool === "read") return runReadTool(args, options);
+  if (tool === "read_image") return runReadImageTool(args, options);
   if (tool === "write") return runWriteTool(args, options);
   if (tool === "edit") return runEditTool(args, options);
   if (tool === "artifact_read") return runArtifactReadTool(args, options);

package/src/code/imageIngest.js

@@ -0,0 +1,367 @@
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const { mediaTypeFromPath, sniffMediaType, MAX_IMAGE_BYTES } = require("./tools/readImage");
+
+const IMAGE_EXT_RE = /\.(png|jpe?g|gif|webp)$/i;
+const FILE_URL_RE = /^file:\/\//i;
+
+function uploadsDir(workspaceRoot = "", sessionId = "") {
+  const root = path.resolve(String(workspaceRoot || process.cwd()));
+  const sid = String(sessionId || "session").trim().replace(/[^a-zA-Z0-9._-]+/g, "_") || "session";
+  return path.join(root, ".ufoo", "agent", "ucode", "uploads", sid);
+}
+
+function safeBaseName(filePath = "") {
+  const base = path.basename(String(filePath || "image.png"));
+  const cleaned = base.replace(/[^\w.\-()+ ]+/g, "_").replace(/\s+/g, " ").trim();
+  if (!cleaned) return "image.png";
+  if (!IMAGE_EXT_RE.test(cleaned)) return `${cleaned}.png`;
+  return cleaned.slice(0, 120);
+}
+
+function decodeFileUrl(value = "") {
+  const text = String(value || "").trim();
+  if (!FILE_URL_RE.test(text)) return text;
+  try {
+    const parsed = new URL(text);
+    if (parsed.protocol !== "file:") return text;
+    return decodeURIComponent(parsed.pathname || "");
+  } catch {
+    return text.replace(FILE_URL_RE, "");
+  }
+}
+
+function looksLikeImagePath(candidate = "") {
+  const text = decodeFileUrl(String(candidate || "").trim().replace(/^['"]|['"]$/g, ""));
+  if (!text || !IMAGE_EXT_RE.test(text)) return false;
+  if (text.startsWith("/") || /^[A-Za-z]:[\\/]/.test(text) || text.startsWith("~")) return true;
+  // Relative paths ending in image ext (drag from cwd listings)
+  if (!/\s/.test(text) && IMAGE_EXT_RE.test(text)) return true;
+  return false;
+}
+
+function expandHome(filePath = "") {
+  const text = String(filePath || "");
+  if (text.startsWith("~/")) return path.join(os.homedir(), text.slice(2));
+  return text;
+}
+
+/**
+ * Extract image file paths from terminal paste / drag-drop text.
+ * Supports file://, quoted paths with spaces, and bare absolute paths.
+ */
+function extractImagePathsFromPaste(text = "") {
+  const raw = String(text || "");
+  if (!raw.trim()) return [];
+  const found = [];
+  const seen = new Set();
+
+  function pushPath(candidate) {
+    let next = decodeFileUrl(String(candidate || "").trim());
+    next = next.replace(/^['"]|['"]$/g, "");
+    if (!looksLikeImagePath(next)) return;
+    next = expandHome(next);
+    const key = path.resolve(next);
+    if (seen.has(key)) return;
+    seen.add(key);
+    found.push(next);
+  }
+
+  // Quoted paths (possibly with spaces)
+  const quoted = /["']([^"']+\.(?:png|jpe?g|gif|webp))["']/gi;
+  let match;
+  while ((match = quoted.exec(raw))) {
+    pushPath(match[1]);
+  }
+
+  // file:// URLs
+  const fileUrls = /file:\/\/[^\s"'<>]+/gi;
+  while ((match = fileUrls.exec(raw))) {
+    pushPath(match[0]);
+  }
+
+  // Bare tokens / lines
+  for (const line of raw.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (looksLikeImagePath(trimmed)) {
+      pushPath(trimmed);
+      continue;
+    }
+    for (const token of trimmed.split(/\s+/)) {
+      if (looksLikeImagePath(token)) pushPath(token);
+    }
+  }
+
+  return found;
+}
+
+function stripExtractedPathsFromText(text = "", paths = []) {
+  let out = String(text || "");
+  for (const p of paths) {
+    const variants = [
+      `"${p}"`,
+      `'${p}'`,
+      p,
+      p.startsWith("/") ? `file://${p}` : "",
+      p.startsWith("/") ? `file://${encodeURI(p)}` : "",
+    ].filter(Boolean);
+    for (const v of variants) {
+      out = out.split(v).join(" ");
+    }
+  }
+  return out
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .replace(/[ \t]{2,}/g, " ")
+    .replace(/\s+"/g, " ")
+    .replace(/"\s+/g, " ")
+    .replace(/\s+'/g, " ")
+    .replace(/'\s+/g, " ")
+    .trim();
+}
+
+function formatImageLogLabel({ relPath = "", fileName = "", path: pathText = "" } = {}) {
+  const name = String(fileName || "").trim()
+    || path.basename(String(relPath || pathText || "").trim())
+    || "image";
+  return `[image: ${name}]`;
+}
+
+function formatUserLogWithAttachments(userText = "", attachments = []) {
+  const labels = (Array.isArray(attachments) ? attachments : [])
+    .map((item) => formatImageLogLabel(item))
+    .filter(Boolean);
+  const body = String(userText || "").trim();
+  if (labels.length === 0) return body;
+  if (!body) return labels.join(" ");
+  return `${labels.join(" ")} ${body}`;
+}
+
+function buildAttachedImagesPromptPrefix(attachments = []) {
+  const list = Array.isArray(attachments) ? attachments : [];
+  if (list.length === 0) return "";
+  const lines = [
+    "[Attached images — call read_image on each path]",
+    ...list.map((item) => `- ${item.relPath || item.path || ""}`).filter((line) => line !== "- "),
+    "",
+  ];
+  return lines.join("\n");
+}
+
+function ingestImageFile({
+  sourcePath = "",
+  workspaceRoot = process.cwd(),
+  sessionId = "",
+  buffer = null,
+  preferredName = "",
+} = {}) {
+  const root = path.resolve(String(workspaceRoot || process.cwd()));
+  let data = buffer;
+  let fromPath = String(sourcePath || "").trim();
+
+  if (!data) {
+    if (!fromPath) {
+      return { ok: false, error: "sourcePath or buffer required" };
+    }
+    fromPath = expandHome(decodeFileUrl(fromPath));
+    try {
+      const stat = fs.statSync(fromPath);
+      if (!stat.isFile()) return { ok: false, error: `not a file: ${fromPath}` };
+      if (stat.size > MAX_IMAGE_BYTES) {
+        return {
+          ok: false,
+          error: `image too large (${stat.size} bytes); max ${MAX_IMAGE_BYTES}`,
+        };
+      }
+      data = fs.readFileSync(fromPath);
+    } catch (err) {
+      return { ok: false, error: err && err.message ? err.message : "read failed" };
+    }
+  }
+
+  if (!Buffer.isBuffer(data)) {
+    return { ok: false, error: "image buffer required" };
+  }
+  if (data.length > MAX_IMAGE_BYTES) {
+    return {
+      ok: false,
+      error: `image too large (${data.length} bytes); max ${MAX_IMAGE_BYTES}`,
+    };
+  }
+
+  const sniffed = sniffMediaType(data);
+  const fromName = mediaTypeFromPath(preferredName || fromPath);
+  const mediaType = sniffed || fromName;
+  if (!mediaType) {
+    return { ok: false, error: "unsupported image type (use png, jpeg, gif, or webp)" };
+  }
+
+  const ext = mediaType === "image/jpeg"
+    ? ".jpg"
+    : mediaType === "image/gif"
+      ? ".gif"
+      : mediaType === "image/webp"
+        ? ".webp"
+        : ".png";
+
+  let base = safeBaseName(preferredName || fromPath || `clipboard${ext}`);
+  if (!IMAGE_EXT_RE.test(base)) base = `${base}${ext}`;
+  // Normalize extension to sniffed type
+  base = `${path.basename(base, path.extname(base))}${ext}`;
+
+  const dir = uploadsDir(root, sessionId);
+  fs.mkdirSync(dir, { recursive: true });
+  const stamp = Date.now().toString(36);
+  const destName = `${stamp}-${base}`;
+  const absPath = path.join(dir, destName);
+  fs.writeFileSync(absPath, data);
+
+  const relPath = path.relative(root, absPath).split(path.sep).join("/");
+  return {
+    ok: true,
+    relPath,
+    absPath,
+    fileName: base,
+    mediaType,
+    bytes: data.length,
+  };
+}
+
+function tryIngestClipboardImage({
+  workspaceRoot = process.cwd(),
+  sessionId = "",
+  platform = process.platform,
+  execFile = execFileSync,
+} = {}) {
+  if (platform !== "darwin") {
+    return { ok: false, error: "clipboard image ingest is only supported on macOS" };
+  }
+
+  const tmpPath = path.join(
+    os.tmpdir(),
+    `ufoo-clipboard-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}.png`,
+  );
+  // AppleScript: write clipboard PNGf to a temp file.
+  const script = [
+    `set outPath to POSIX file ${JSON.stringify(tmpPath)}`,
+    "try",
+    "  set pngData to the clipboard as «class PNGf»",
+    "  set fileRef to open for access outPath with write permission",
+    "  set eof of fileRef to 0",
+    "  write pngData to fileRef",
+    "  close access fileRef",
+    '  return "ok"',
+    "on error errMsg number errNum",
+    "  try",
+    "    close access outPath",
+    "  end try",
+    '  return "err:" & errMsg',
+    "end try",
+  ].join("\n");
+
+  let resultText = "";
+  try {
+    resultText = String(execFile("osascript", ["-e", script], {
+      encoding: "utf8",
+      timeout: 5000,
+      maxBuffer: 1024 * 1024,
+    }) || "").trim();
+  } catch (err) {
+    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+    return {
+      ok: false,
+      error: err && err.message ? err.message : "clipboard read failed",
+    };
+  }
+
+  if (!resultText.startsWith("ok")) {
+    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+    return {
+      ok: false,
+      error: resultText.replace(/^err:/, "").trim() || "no PNG image on clipboard",
+    };
+  }
+
+  try {
+    const ingested = ingestImageFile({
+      sourcePath: tmpPath,
+      workspaceRoot,
+      sessionId,
+      preferredName: `clipboard-${Date.now().toString(36)}.png`,
+    });
+    return ingested;
+  } finally {
+    try { fs.unlinkSync(tmpPath); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Handle a paste chunk: ingest image paths and/or macOS clipboard bitmap.
+ * Returns text to insert into the editor (paths removed) plus attachments.
+ */
+function handleImagePaste(text = "", {
+  workspaceRoot = process.cwd(),
+  sessionId = "",
+  tryClipboard = true,
+  platform = process.platform,
+  execFile = execFileSync,
+} = {}) {
+  const raw = String(text || "");
+  const paths = extractImagePathsFromPaste(raw);
+  const attachments = [];
+  const errors = [];
+
+  for (const sourcePath of paths) {
+    const ingested = ingestImageFile({ sourcePath, workspaceRoot, sessionId });
+    if (ingested.ok) attachments.push(ingested);
+    else errors.push(ingested.error || "ingest failed");
+  }
+
+  let remaining = stripExtractedPathsFromText(raw, paths);
+
+  // If paste had no usable text/paths, try clipboard PNG (Cmd+V of a screenshot).
+  const trimmedRemaining = remaining.trim();
+  const looksEmptyOrBinary = !trimmedRemaining
+    || /[\x00-\x08\x0e-\x1f]/.test(raw)
+    || (Buffer.byteLength(raw, "utf8") > 200 && paths.length === 0 && !/\s/.test(raw.slice(0, 40)));
+
+  if (tryClipboard && attachments.length === 0 && looksEmptyOrBinary) {
+    const clip = tryIngestClipboardImage({
+      workspaceRoot,
+      sessionId,
+      platform,
+      execFile,
+    });
+    if (clip.ok) {
+      attachments.push(clip);
+      remaining = "";
+    } else if (paths.length === 0 && !trimmedRemaining) {
+      errors.push(clip.error || "clipboard ingest failed");
+    }
+  }
+
+  return {
+    text: remaining,
+    attachments,
+    errors,
+  };
+}
+
+module.exports = {
+  IMAGE_EXT_RE,
+  uploadsDir,
+  safeBaseName,
+  extractImagePathsFromPaste,
+  stripExtractedPathsFromText,
+  formatImageLogLabel,
+  formatUserLogWithAttachments,
+  buildAttachedImagesPromptPrefix,
+  ingestImageFile,
+  tryIngestClipboardImage,
+  handleImagePaste,
+};