u-foo 3.0.1 → 3.0.3

package/src/code/nativeRunner.js

@@ -5,6 +5,7 @@ const {
   resolveKimiUpstreamCredentials,
 } = require("../agents/providers/credentials/kimi");
 const { runToolCall } = require("./dispatch");
+const { runTaskRunTool } = require("./tools/taskRun");
 const { appendUsageRecord } = require("./usageStore");
 const {
   persistToolResultToContext,
@@ -49,20 +50,31 @@ const {
 } = require("./protocol");
 const { stableStringify } = require("./context/stableJson");
 const { getReadToolDescription } = require("../agents/prompts/native/toolDescriptions/read");
+const { getReadImageToolDescription } = require("../agents/prompts/native/toolDescriptions/readImage");
 const { getWriteToolDescription } = require("../agents/prompts/native/toolDescriptions/write");
 const { getEditToolDescription } = require("../agents/prompts/native/toolDescriptions/edit");
 const { getBashToolDescription } = require("../agents/prompts/native/toolDescriptions/bash");
 
 const CORE_TOOL_NAMES = new Set([
   "read",
+  "read_image",
   "write",
   "edit",
   "bash",
   "artifact_read",
   "plan_graph",
+  "task_run",
   "ask_user",
 ]);
-const EXECUTABLE_GRAPH_TOOLS = new Set(["read", "write", "edit", "bash", "artifact_read"]);
+const EXECUTABLE_GRAPH_TOOLS = new Set([
+  "read",
+  "read_image",
+  "write",
+  "edit",
+  "bash",
+  "artifact_read",
+]);
+const CONTROL_PLANE_TOOLS = new Set(["plan_graph", "task_run"]);
 const DEFAULT_OPENAI_BASE_URL = "https://api.openai.com/v1";
 const DEFAULT_ANTHROPIC_BASE_URL = "https://api.anthropic.com/v1";
 const DEFAULT_KIMI_BASE_URL = "https://api.kimi.com/coding/v1";
@@ -78,11 +90,9 @@ const DEFAULT_NATIVE_TIMEOUT_MS = 43200000; // 12 hours
 // via UFOO_UCODE_MAX_TOKENS (positive integer).
 const DEFAULT_OPENAI_MAX_TOKENS = 131072;
 const DEFAULT_ANTHROPIC_MAX_TOKENS = 64000;
-// Extended thinking is on by default for the anthropic transport; the budget
-// stays well below the 64K max_tokens cap as the Messages API requires.
-// UFOO_UCODE_THINKING_BUDGET_TOKENS overrides; 0 or a non-numeric value
-// disables thinking (the payload then omits the field entirely).
-const DEFAULT_ANTHROPIC_THINKING_BUDGET_TOKENS = 10000;
+// Extended thinking defaults live in thinkingLevels.js (medium = 10k).
+// UFOO_UCODE_THINKING=off|low|medium|high|max selects a preset; numeric
+// UFOO_UCODE_THINKING_BUDGET_TOKENS still overrides. 0 disables thinking.
 // Prompt caching is GA on the current Messages API: cache_control blocks need
 // no anthropic-beta header. Kept as a constant so the marker shape stays in
 // one place (system block + last history message, 2 of the 4 allowed
@@ -116,14 +126,40 @@ function resolveMaxTokens(fallback) {
   return normalizePositiveInt(process.env.UFOO_UCODE_MAX_TOKENS, fallback);
 }
 
-function resolveThinkingBudgetTokens() {
-  const raw = process.env.UFOO_UCODE_THINKING_BUDGET_TOKENS;
-  if (raw === undefined || raw === null || String(raw).trim() === "") {
-    return DEFAULT_ANTHROPIC_THINKING_BUDGET_TOKENS;
+function resolveThinkingBudgetTokens(options = {}) {
+  const { resolveThinkingFromEnvAndConfig } = require("./thinkingLevels");
+  const { loadGlobalUcodeConfig } = require("../config");
+  let configLevel = String(options.configLevel || "").trim();
+  if (!configLevel) {
+    try {
+      configLevel = String((loadGlobalUcodeConfig() || {}).ucodeThinking || "").trim();
+    } catch {
+      configLevel = "";
+    }
   }
-  const parsed = Number.parseInt(String(raw), 10);
-  if (!Number.isFinite(parsed) || parsed <= 0) return 0;
-  return Math.floor(parsed);
+  const resolved = resolveThinkingFromEnvAndConfig({
+    env: options.env || process.env,
+    configLevel,
+  });
+  return resolved.budgetTokens;
+}
+
+function resolveReasoningEffort(options = {}) {
+  const { resolveThinkingFromEnvAndConfig } = require("./thinkingLevels");
+  const { loadGlobalUcodeConfig } = require("../config");
+  let configLevel = String(options.configLevel || "").trim();
+  if (!configLevel) {
+    try {
+      configLevel = String((loadGlobalUcodeConfig() || {}).ucodeThinking || "").trim();
+    } catch {
+      configLevel = "";
+    }
+  }
+  const resolved = resolveThinkingFromEnvAndConfig({
+    env: options.env || process.env,
+    configLevel,
+  });
+  return resolved.reasoningEffort || "";
 }
 
 function toUsageInt(value) {
@@ -365,6 +401,23 @@ function buildCoreToolSpecs() {
         },
       },
     },
+    {
+      type: "function",
+      function: {
+        name: "read_image",
+        description: getReadImageToolDescription(),
+        parameters: {
+          type: "object",
+          properties: {
+            path: {
+              type: "string",
+              description: "Workspace-relative path to a png, jpeg, gif, or webp image.",
+            },
+          },
+          required: ["path"],
+        },
+      },
+    },
     {
       type: "function",
       function: {
@@ -446,12 +499,13 @@ function buildCoreToolSpecs() {
       function: {
         name: "plan_graph",
         description: [
-          "Manage the persistent Plan Graph and asynchronous TaskRuns.",
-          "Use create, patch, inspect, or cancel_graph for graph operations, and control for TaskRun lifecycle.",
-          "`control.start_task` starts a `task_loop` asynchronously and returns immediately.",
+          "Manage the persistent Plan Graph and graph-bound TaskRuns.",
+          "TaskRuns are orthogonal to Plan Mode; for a standalone TaskRun without a plan, use `task_run` instead.",
+          "Use create, patch, inspect, or cancel_graph for graph operations, and control for graph-bound TaskRun lifecycle.",
+          "`control.start_task` starts a graph `task_loop` asynchronously and returns immediately.",
           "Use `inline_llm` for work handled by the current graph owner,",
           "`expand` for tasks that must be lowered into child nodes,",
-          "and `task_loop` for asynchronous work in an independent TaskLoop.",
+          "and `task_loop` for asynchronous work in an independent TaskLoop attached to a plan node.",
           "Do not call `plan_graph` together with data-plane tools in the same assistant turn.",
         ].join(" "),
         parameters: {
@@ -517,6 +571,63 @@ function buildCoreToolSpecs() {
         },
       },
     },
+    {
+      type: "function",
+      function: {
+        name: "task_run",
+        description: [
+          "Start, inspect, cancel, fail, or complete a TaskRun.",
+          "TaskRuns are orthogonal to Plan Mode and do not require a plan_graph.",
+          "Use operation=start with an objective for a standalone single-point TaskRun; it returns immediately.",
+          "On complex multi-goal work, decompose into concrete objectives and start one or more TaskRuns.",
+          "Use plan_graph control.start_task only when the TaskRun is attached to a plan_graph task_loop node.",
+          "Do not call `task_run` together with data-plane tools in the same assistant turn.",
+        ].join(" "),
+        parameters: {
+          type: "object",
+          properties: {
+            operation: {
+              type: "string",
+              enum: ["start", "cancel", "fail", "complete", "inspect"],
+              description: [
+                "start creates a standalone TaskRun from objective;",
+                "cancel/fail/complete/inspect address an existing taskRunId",
+                "(cancel/fail may also use nodeId for graph-bound runs).",
+              ].join(" "),
+            },
+            objective: {
+              type: "string",
+              description: "Required for start: concrete TaskRun objective.",
+            },
+            title: {
+              type: "string",
+              description: "Optional short title for start.",
+            },
+            taskRunId: {
+              type: "string",
+              description: "TaskRun id for cancel, fail, complete, or inspect.",
+            },
+            nodeId: {
+              type: "string",
+              description: "Optional graph node id for cancel/fail of a graph-bound TaskRun.",
+            },
+            reason: {
+              type: "string",
+              description: "Optional reason for cancel or fail.",
+            },
+            result: {
+              type: "object",
+              description: "Optional result payload for complete (TaskLoop owner).",
+            },
+            commandId: {
+              type: "string",
+              description: "Optional idempotency key for explicit replay.",
+            },
+          },
+          required: ["operation"],
+        },
+      },
+    },
     {
       type: "function",
       function: {
@@ -772,6 +883,51 @@ function runCoreTool({
     };
   }
 
+  if (normalizedTool === "task_run") {
+    const state = executionState && typeof executionState === "object"
+      ? executionState
+      : emptyExecutionState();
+    const result = runTaskRunTool(safeArgs, {
+      executionState: state,
+      runTool: ({ node, args: nestedArgs, tool: nestedTool, stepId }) => {
+        const nested = runCoreTool({
+          tool: nestedTool,
+          args: nestedArgs,
+          workspaceRoot,
+          onToolEvent,
+          sessionId,
+          onArtifactPersisted,
+          executionState: state,
+          origin: {
+            kind: "task_run",
+            taskRunId: String(safeArgs.taskRunId || ""),
+            nodeId: stepId || (node && node.id) || "",
+            attempt: Number(node && node.attempt) || 0,
+          },
+        });
+        return nested;
+      },
+    });
+    const ok = result.ok !== false && result.status !== "rejected";
+    emitToolEvent(onToolEvent, {
+      tool: "task_run",
+      phase: ok ? "end" : "error",
+      args: safeArgs,
+      result,
+      error: ok
+        ? ""
+        : (Array.isArray(result.errors)
+          ? result.errors.map((e) => e.message || e.code).join("; ")
+          : (result.error || "task_run rejected")),
+      origin,
+    });
+    return {
+      ...result,
+      ok,
+      executionState: result.executionState || state,
+    };
+  }
+
   if (normalizedTool === "ask_user") {
     const state = executionState && typeof executionState === "object"
       ? executionState
@@ -970,6 +1126,12 @@ async function runOpenAiLikeTurn({
     // Kimi k3 rejects any temperature other than 1.
     temperature: normalizeProvider(provider) === "kimi" ? 1 : 0,
   };
+  const reasoningEffort = resolveReasoningEffort();
+  if (reasoningEffort) {
+    // OpenAI-compatible gateways that support reasoning models accept this;
+    // unknown fields are typically ignored by plain chat models.
+    payload.reasoning_effort = reasoningEffort;
+  }
 
   const headers = {
     "content-type": "application/json",
@@ -1715,16 +1877,16 @@ async function runNativeLoop({
     await withFaultPoint("before_tool_exec", () => {});
 
     const callNames = pendingCalls.map((call) => String(call.name || "").trim().toLowerCase());
-    const hasPlanGraph = callNames.includes("plan_graph");
+    const hasControlPlane = callNames.some((name) => CONTROL_PLANE_TOOLS.has(name));
     const hasAskUser = callNames.includes("ask_user");
     const hasDataTool = callNames.some((name) => EXECUTABLE_GRAPH_TOOLS.has(name));
-    if (hasPlanGraph && hasDataTool) {
+    if (hasControlPlane && hasDataTool) {
       // prepareToolCalls already appended the assistant tool_calls / tool_use
       // message; every declared call must get a contiguous tool result via ledger.
       const rejected = {
         ok: false,
         status: "rejected",
-        error: "Do not mix plan_graph with data-plane tools in the same turn",
+        error: "Do not mix plan_graph/task_run with data-plane tools in the same turn",
         code: "MIXED_PLAN_AND_DATA_TOOLS",
       };
       for (const pending of pendingCalls) {
@@ -2078,6 +2240,8 @@ module.exports = {
   resolveCompletionUrl,
   resolveAnthropicMessagesUrl,
   resolveTransport,
+  resolveThinkingBudgetTokens,
+  resolveReasoningEffort,
   buildCoreToolSpecs,
   buildAnthropicToolSpecs,
 };

package/src/code/protocol/protocolValidator.js

@@ -78,7 +78,7 @@ function validateDeclaredBatch(ledger = null, {
 
   const names = calls.map((c) => c.name);
   const hasAskUser = names.includes("ask_user");
-  const hasPlanGraph = names.includes("plan_graph");
+  const hasControlPlane = names.includes("plan_graph") || names.includes("task_run");
   const dataSet = dataPlaneTools instanceof Set
     ? dataPlaneTools
     : new Set(["read", "write", "edit", "bash", "artifact_read"]);
@@ -90,10 +90,10 @@ function validateDeclaredBatch(ledger = null, {
       message: "ask_user must be the only tool call in the turn",
     });
   }
-  if (rejectPlanWithData && hasPlanGraph && hasData) {
+  if (rejectPlanWithData && hasControlPlane && hasData) {
     errors.push({
       code: "MIXED_PLAN_AND_DATA_TOOLS",
-      message: "Do not mix plan_graph with data-plane tools in the same turn",
+      message: "Do not mix plan_graph/task_run with data-plane tools in the same turn",
     });
   }
 

package/src/code/providers/anthropicMessagesTransport.js

@@ -1,6 +1,12 @@
 "use strict";
 
 const { assertTransport } = require("./transportContract");
+const {
+  extractVisionPayload,
+  stripVisionBase64,
+  visionSummaryText,
+  toAnthropicImageBlock,
+} = require("./visionBlocks");
 
 /**
  * Anthropic Messages API transport adapter.
@@ -70,11 +76,32 @@ function createAnthropicMessagesTransport(deps = {}) {
       }));
     },
     appendToolResult({ collected, call, toolResult }) {
+      const vision = extractVisionPayload(toolResult);
+      const isError = Boolean(!toolResult || toolResult.ok === false);
+      if (vision) {
+        const textPayload = stripVisionBase64(toolResult);
+        collected.push({
+          type: "tool_result",
+          tool_use_id: String(call.source.id || ""),
+          content: [
+            {
+              type: "text",
+              text: clipText(
+                `${visionSummaryText(vision, toolResult)}\n${toJsonString(textPayload)}`,
+                12000,
+              ),
+            },
+            toAnthropicImageBlock(vision),
+          ],
+          is_error: isError,
+        });
+        return;
+      }
       collected.push({
         type: "tool_result",
         tool_use_id: String(call.source.id || ""),
         content: clipText(toJsonString(toolResult), 12000),
-        is_error: Boolean(!toolResult || toolResult.ok === false),
+        is_error: isError,
       });
     },
     flushToolResults({ messages, collected }) {

package/src/code/providers/index.js

@@ -4,4 +4,6 @@ module.exports = {
   ...require("./transportContract"),
   ...require("./openaiChatTransport"),
   ...require("./anthropicMessagesTransport"),
+  ...require("./modelsCatalog"),
+  ...require("./visionBlocks"),
 };

package/src/code/providers/modelsCatalog.js

@@ -0,0 +1,304 @@
+"use strict";
+
+/**
+ * Live provider model catalog via the OpenAI-compatible / Anthropic models route.
+ *
+ * Used by /model suggestions and settings validation so ucode only offers
+ * (and preferably accepts) models the configured endpoint actually lists.
+ */
+
+const DEFAULT_ANTHROPIC_BASE_URL = "https://api.anthropic.com/v1";
+const DEFAULT_TIMEOUT_MS = 8000;
+const CACHE_TTL_MS = 60_000;
+
+/** @type {Map<string, { at: number, result: object }>} */
+const modelsCache = new Map();
+
+function clipText(value = "", maxChars = 400) {
+  const text = String(value || "");
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars)}…`;
+}
+
+function resolveOpenAiModelsUrl(baseUrl = "") {
+  const raw = String(baseUrl || "").trim();
+  if (!raw) return "";
+  const normalized = raw.replace(/\/+$/, "");
+  if (/\/models$/i.test(normalized)) return normalized;
+  if (/\/chat\/completions$/i.test(normalized)) {
+    return normalized.replace(/\/chat\/completions$/i, "/models");
+  }
+  if (/\/v1$/i.test(normalized)) return `${normalized}/models`;
+  if (/\/api$/i.test(normalized)) return `${normalized}/v1/models`;
+  return `${normalized}/models`;
+}
+
+function resolveAnthropicModelsUrl(baseUrl = "") {
+  const raw = String(baseUrl || "").trim() || DEFAULT_ANTHROPIC_BASE_URL;
+  const normalized = raw.replace(/\/+$/, "");
+  if (/\/models$/i.test(normalized)) return normalized;
+  if (/\/messages$/i.test(normalized)) {
+    return normalized.replace(/\/messages$/i, "/models");
+  }
+  if (/\/v1$/i.test(normalized)) return `${normalized}/models`;
+  if (/\/api$/i.test(normalized)) return `${normalized}/v1/models`;
+  return `${normalized}/models`;
+}
+
+function resolveModelsUrl({ transport = "", baseUrl = "" } = {}) {
+  if (String(transport || "") === "anthropic-messages") {
+    return resolveAnthropicModelsUrl(baseUrl);
+  }
+  return resolveOpenAiModelsUrl(baseUrl);
+}
+
+function cacheKey({ transport = "", baseUrl = "", apiKey = "", provider = "" } = {}) {
+  const keyTail = apiKey ? String(apiKey).slice(-8) : "";
+  return `${provider}|${transport}|${baseUrl}|${keyTail}`;
+}
+
+function extractModelIds(payload) {
+  const ids = [];
+  const seen = new Set();
+  const push = (value) => {
+    const id = String(value || "").trim();
+    if (!id || seen.has(id)) return;
+    seen.add(id);
+    ids.push(id);
+  };
+
+  if (!payload || typeof payload !== "object") return ids;
+
+  if (Array.isArray(payload.data)) {
+    for (const item of payload.data) {
+      if (!item) continue;
+      if (typeof item === "string") push(item);
+      else push(item.id || item.model || item.name);
+    }
+  }
+
+  if (Array.isArray(payload.models)) {
+    for (const item of payload.models) {
+      if (!item) continue;
+      if (typeof item === "string") push(item);
+      else push(item.id || item.model || item.name);
+    }
+  }
+
+  return ids;
+}
+
+function buildListHeaders({ transport = "", apiKey = "" } = {}) {
+  const headers = {
+    Accept: "application/json",
+  };
+  const key = String(apiKey || "").trim();
+  if (!key) return headers;
+
+  if (String(transport || "") === "anthropic-messages") {
+    headers["x-api-key"] = key;
+    headers["anthropic-version"] = "2023-06-01";
+  } else {
+    headers.Authorization = `Bearer ${key}`;
+  }
+  return headers;
+}
+
+/**
+ * Fetch the provider's models catalog.
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   models: string[],
+ *   url: string,
+ *   error: string,
+ *   status: number,
+ *   cached: boolean,
+ * }>}
+ */
+async function listProviderModels(options = {}) {
+  const transport = String(options.transport || "openai-chat").trim() || "openai-chat";
+  const baseUrl = String(options.baseUrl || "").trim();
+  const apiKey = String(options.apiKey || "").trim();
+  const provider = String(options.provider || "").trim();
+  const timeoutMs = Math.max(1000, Number(options.timeoutMs) || DEFAULT_TIMEOUT_MS);
+  const fetchImpl = typeof options.fetchImpl === "function" ? options.fetchImpl : fetch;
+  const skipCache = options.skipCache === true;
+  const url = resolveModelsUrl({ transport, baseUrl });
+
+  if (!url) {
+    return {
+      ok: false,
+      models: [],
+      url: "",
+      error: "models url unavailable (set ucode base url)",
+      status: 0,
+      cached: false,
+    };
+  }
+
+  const key = cacheKey({ transport, baseUrl, apiKey, provider });
+  if (!skipCache) {
+    const hit = modelsCache.get(key);
+    if (hit && (Date.now() - hit.at) < CACHE_TTL_MS) {
+      return { ...hit.result, cached: true };
+    }
+  }
+
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  const timer = controller
+    ? setTimeout(() => {
+      try { controller.abort(); } catch { /* ignore */ }
+    }, timeoutMs)
+    : null;
+  if (timer && typeof timer.unref === "function") timer.unref();
+
+  try {
+    const response = await fetchImpl(url, {
+      method: "GET",
+      headers: buildListHeaders({ transport, apiKey }),
+      signal: controller ? controller.signal : undefined,
+    });
+    const status = Number(response && response.status) || 0;
+    const bodyText = await response.text().catch(() => "");
+    let payload = null;
+    try {
+      payload = bodyText ? JSON.parse(bodyText) : null;
+    } catch {
+      payload = null;
+    }
+
+    if (!response.ok) {
+      const result = {
+        ok: false,
+        models: [],
+        url,
+        error: `models route failed (${status}): ${clipText(bodyText || response.statusText || "unknown")}`,
+        status,
+        cached: false,
+      };
+      return result;
+    }
+
+    const models = extractModelIds(payload);
+    const result = {
+      ok: true,
+      models,
+      url,
+      error: models.length === 0 ? "models route returned an empty catalog" : "",
+      status,
+      cached: false,
+    };
+    // Cache successful responses even when empty — avoids hammering a broken gateway.
+    modelsCache.set(key, { at: Date.now(), result: { ...result, cached: false } });
+    return result;
+  } catch (err) {
+    const message = err && err.name === "AbortError"
+      ? `models route timed out after ${timeoutMs}ms`
+      : (err && err.message ? err.message : String(err || "models route failed"));
+    return {
+      ok: false,
+      models: [],
+      url,
+      error: message,
+      status: 0,
+      cached: false,
+    };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+function modelSupported(model = "", models = []) {
+  const needle = String(model || "").trim();
+  if (!needle) return false;
+  const list = Array.isArray(models) ? models : [];
+  return list.some((id) => String(id || "").trim() === needle);
+}
+
+/**
+ * Validate a model id against the live catalog.
+ * Soft mode: when the catalog cannot be fetched, allow with a warning.
+ */
+async function confirmModelSupported(options = {}) {
+  const model = String(options.model || "").trim();
+  if (!model) {
+    return {
+      ok: false,
+      allowed: false,
+      model: "",
+      models: [],
+      error: "model id is empty",
+      warning: "",
+      catalog: null,
+    };
+  }
+
+  const catalog = await listProviderModels(options);
+  if (!catalog.ok) {
+    return {
+      ok: false,
+      allowed: options.strict === true ? false : true,
+      model,
+      models: [],
+      error: catalog.error || "models route unavailable",
+      warning: options.strict === true
+        ? ""
+        : `could not confirm model via models route (${catalog.error || "unavailable"}); accepting ${model}`,
+      catalog,
+    };
+  }
+
+  if (catalog.models.length === 0) {
+    return {
+      ok: false,
+      allowed: options.strict === true ? false : true,
+      model,
+      models: [],
+      error: catalog.error || "empty models catalog",
+      warning: options.strict === true
+        ? ""
+        : `models route returned no models; accepting ${model}`,
+      catalog,
+    };
+  }
+
+  if (!modelSupported(model, catalog.models)) {
+    const sample = catalog.models.slice(0, 8).join(", ");
+    const more = catalog.models.length > 8 ? ` (+${catalog.models.length - 8} more)` : "";
+    return {
+      ok: false,
+      allowed: false,
+      model,
+      models: catalog.models,
+      error: `model "${model}" is not in the provider catalog${sample ? ` (available: ${sample}${more})` : ""}`,
+      warning: "",
+      catalog,
+    };
+  }
+
+  return {
+    ok: true,
+    allowed: true,
+    model,
+    models: catalog.models,
+    error: "",
+    warning: "",
+    catalog,
+  };
+}
+
+function clearModelsCache() {
+  modelsCache.clear();
+}
+
+module.exports = {
+  resolveOpenAiModelsUrl,
+  resolveAnthropicModelsUrl,
+  resolveModelsUrl,
+  listProviderModels,
+  confirmModelSupported,
+  modelSupported,
+  extractModelIds,
+  clearModelsCache,
+  CACHE_TTL_MS,
+};