u-foo 3.0.2 → 3.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "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.",
@@ -232,6 +232,7 @@ function renderPlanModeContext(executionState = null) {
     "  2) expand_node on the current ready/waiting task when needed",
     "  3) Runtime executes ready tools / TaskLoops; continue from results",
     "  4) control.complete_task (inline) or control.start_task (task_loop)",
+    "Do not end the turn with text only while a task is waiting — advance it.",
     "Do not mix plan_graph with data-plane tools in the same turn.",
   );
 

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,25 @@ 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.",
+      "- Do not end a turn with text only while the plan is still waiting on a task; expand, start, or complete that node. Runtime will auto-continue if you stop early, but prefer advancing in the same turn.",
       "- 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/context/userNudge.js

@@ -104,6 +104,52 @@ function buildContinuationUserPrompt(userText = "", executionState = null) {
   return formatUserReminderMessage([text], { waitingFor: waiting });
 }
 
+const PLAN_AUTO_CONTINUE_STOP_REASONS = new Set([
+  "approval_required",
+  "graph_terminal",
+  "scheduler_deadlock",
+]);
+
+/**
+ * Whether the Agent Loop should keep going after a text-only model turn
+ * because the plan graph is still waiting on an agent-actionable task.
+ */
+function shouldAutoContinuePlan(executionState = null) {
+  if (!executionState || typeof executionState !== "object") return false;
+  if (executionState.pendingUserInteraction) return false;
+  const pg = executionState.planGraph && typeof executionState.planGraph === "object"
+    ? executionState.planGraph
+    : null;
+  if (!pg) return false;
+  const waiting = pg.waitingFor && typeof pg.waitingFor === "object" ? pg.waitingFor : null;
+  if (!waiting || !waiting.id) return false;
+  if (String(waiting.type || "").trim().toLowerCase() !== "task") return false;
+  const yieldReason = String(pg.lastYieldReason || "").trim().toLowerCase();
+  if (yieldReason && PLAN_AUTO_CONTINUE_STOP_REASONS.has(yieldReason)) return false;
+  return true;
+}
+
+/**
+ * Internal reminder injected by runtime when the model ends a turn while the
+ * plan is still waiting on a task. Same shape as user nudges.
+ */
+function buildPlanAutoContinueReminder(executionState = null) {
+  const waiting = executionState
+    && executionState.planGraph
+    && executionState.planGraph.waitingFor
+    ? executionState.planGraph.waitingFor
+    : null;
+  if (!waiting || !waiting.id) return "";
+  return formatUserReminderMessage(
+    [
+      "Continue the active plan. Serve the waiting task now via plan_graph "
+        + "(expand_node, control.start_task, or control.complete_task as appropriate). "
+        + "Do not end the turn with text only while this node is waiting.",
+    ],
+    { waitingFor: waiting },
+  );
+}
+
 module.exports = {
   ensurePendingUserPrompts,
   enqueueUserPrompt,
@@ -113,4 +159,7 @@ module.exports = {
   shouldFrameAsUserReminder,
   formatUserReminderMessage,
   buildContinuationUserPrompt,
+  shouldAutoContinuePlan,
+  buildPlanAutoContinueReminder,
+  PLAN_AUTO_CONTINUE_STOP_REASONS,
 };

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);