u-foo 3.0.0 → 3.0.1

package/package.json

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

package/src/code/agent.js

@@ -520,9 +520,22 @@ async function runNaturalLanguageTask(task = "", state = {}, options = {}) {
     : null;
   const pushToolLog = createToolLogCollector(logs, onToolLog);
 
-  // Detect bug fix tasks and use decomposed runner
-  const isBugFixTask = /\b(?:fix(?:es|ed|ing)?|bugs?|issues?|problems?|errors?|broken)\b|doesn't work|not work/i.test(taskText);
-  const useDecomposition = isBugFixTask && !options.disableDecomposition;
+  // Structural / explicit upgrade to decomposed runner (not keyword "fix").
+  const { shouldUpgradeToDecomposition } = require("./taskRoute");
+  const routeDecision = shouldUpgradeToDecomposition(taskText, {
+    disableDecomposition: options.disableDecomposition,
+    forceDecomposition: options.forceDecomposition,
+    forceDirect: options.forceDirect,
+    failureCount: options.failureCount,
+    modelRequestedUpgrade: options.modelRequestedUpgrade,
+    hasPlanGraph: Boolean(
+      state.executionState
+      && state.executionState.planGraph
+      && state.executionState.planGraph.graphId
+    ),
+  });
+  const useDecomposition = Boolean(routeDecision.upgrade);
+  state.lastRouteDecision = routeDecision;
   const analysisTask = isProjectAnalysisTask(taskText);
   const workspaceRoot = String(state.workspaceRoot || process.cwd());
   ensureContextSessionState(state);
@@ -1124,6 +1137,7 @@ module.exports = {
   runSingleCommand,
   runNaturalLanguageTask,
   resumeAfterUserInteraction,
+  submitUserInteractionAnswer: (...args) => require("./protocol/suspension").submitUserInteractionAnswer(...args),
   formatNlResult,
   normalizeToolLogEvent,
   isProjectAnalysisTask,

package/src/code/context/executionSegment.js

@@ -8,11 +8,16 @@ const {
 } = require("./planGraph");
 
 function emptyExecutionState() {
+  // Durable execution control plane. Field ownership: see
+  // src/code/protocol/ownership.js (STATE_OWNERSHIP / DURABLE_FIELDS).
   return {
     currentSegmentId: "",
     mode: "single_action",
     planMode: false,
     planModeSource: "",
+    // R5 orthognal fields (dual-written with planMode during migration)
+    planningPolicy: "direct_allowed",
+    executionOwner: { kind: "none", id: "" },
     steps: {},
     modifiedFiles: [],
     lastExitCodes: [],

package/src/code/context/planMode.js

@@ -63,6 +63,11 @@ function setPlanMode(executionState = null, enabled = true, {
   const next = Boolean(enabled);
   const wasOn = state.planMode === true;
   state.planMode = next;
+  // R5 dual-write: Plan Mode UI maps to planningPolicy only.
+  state.planningPolicy = next ? "graph_required" : "direct_allowed";
+  if (!state.executionOwner || typeof state.executionOwner !== "object") {
+    state.executionOwner = { kind: "none", id: "" };
+  }
   if (next) {
     if (!wasOn) state.planModeEnteredAt = new Date().toISOString();
     state.planModeReason = String(reason || state.planModeReason || "").trim();
@@ -101,7 +106,9 @@ function planHasNodes(executionState = null) {
 }
 
 function planModeBlocksDirectTool(tool = "", executionState = null) {
-  if (!isPlanModeEnabled(executionState)) return false;
+  const { getPlanningPolicy } = require("../protocol/controlPlane");
+  const policy = getPlanningPolicy(executionState);
+  if (policy !== "graph_required") return false;
   const name = String(tool || "").trim().toLowerCase();
   return name === "write" || name === "edit" || name === "bash";
 }

package/src/code/index.js

@@ -19,6 +19,7 @@ const {
   runSingleCommand,
   runNaturalLanguageTask,
   resumeAfterUserInteraction,
+  submitUserInteractionAnswer,
   formatNlResult,
   resolvePlannerProvider,
   parseAgentArgs,
@@ -62,6 +63,7 @@ module.exports = {
   runSingleCommand,
   runNaturalLanguageTask,
   resumeAfterUserInteraction,
+  submitUserInteractionAnswer,
   formatNlResult,
   resolvePlannerProvider,
   parseAgentArgs,

package/src/code/nativeRunner.js

@@ -34,6 +34,19 @@ const {
   getPendingUserInteraction,
 } = require("./context/userInteraction");
 const { checkWriteAllowed } = require("./runtime/workspaceLease");
+const {
+  createToolCallLedger,
+  declareCalls,
+  markExecuting,
+  deferCall,
+  resolveCall,
+  snapshotLedger,
+  runProviderTurnGate,
+  withFaultPoint,
+  checkFaultPoint,
+  materializeResolvedToolResults,
+  materializeAnswerToolResult,
+} = require("./protocol");
 const { stableStringify } = require("./context/stableJson");
 const { getReadToolDescription } = require("../agents/prompts/native/toolDescriptions/read");
 const { getWriteToolDescription } = require("../agents/prompts/native/toolDescriptions/write");
@@ -1460,140 +1473,76 @@ async function runAnthropicTurn({
   });
 }
 
-// Transport descriptors: everything the shared native loop needs that differs
-// between the OpenAI chat-completions and Anthropic messages protocols —
-// request URL resolution, initial message shaping, turn execution, and
-// assistant/tool-result message formatting.
+const {
+  createOpenAiChatTransport,
+  createAnthropicMessagesTransport,
+} = require("./providers");
+
+// Transport descriptors: wire-format only. Plan Mode / leases / policy live in the loop.
 const TRANSPORTS = {
-  "openai-chat": {
+  "openai-chat": createOpenAiChatTransport({
     resolveUrl: resolveCompletionUrl,
-    prepareMessages({ messages, systemPrompt, prompt }) {
-      const systemText = String(systemPrompt || "").trim();
-      const hasSystem = messages.some((entry) => String(entry.role || "").trim() === "system");
-      if (systemText && !hasSystem) {
-        messages.unshift({ role: "system", content: systemText });
-      }
-      messages.push({ role: "user", content: String(prompt || "") });
-    },
     runTurn: runOpenAiLikeTurn,
-    getToolCalls(turnResult) {
-      return Array.isArray(turnResult.toolCalls)
-        ? turnResult.toolCalls.filter((call) => call && call.function && typeof call.function === "object")
-        : [];
-    },
-    appendFinalAssistantMessage({ messages, turnResult }) {
-      const text = String(turnResult.text || "").trim();
-      if (text) {
-        messages.push({
-          role: "assistant",
-          content: text,
-        });
-      }
-    },
-    prepareToolCalls({ messages, toolCalls }) {
-      const assistantToolCalls = [];
-      for (const call of toolCalls) {
-        const callId = String(call.id || `call_${randomUUID()}`);
-        const name = normalizeToolName(call.function.name || "");
-        const args = normalizeToolCallArgs(call.function.arguments || "");
-
-        assistantToolCalls.push({
-          id: callId,
-          type: "function",
-          function: {
-            name: name || String(call.function.name || ""),
-            arguments: toJsonString(args),
-          },
-        });
-      }
+    normalizeToolName,
+    normalizeToolCallArgs,
+    toJsonString,
+    clipText,
+  }),
+  "anthropic-messages": createAnthropicMessagesTransport({
+    resolveUrl: resolveAnthropicMessagesUrl,
+    runTurn: runAnthropicTurn,
+    toJsonString,
+    clipText,
+  }),
+};
 
-      if (assistantToolCalls.length === 0) return null;
+function pendingToolCallId(pending = null) {
+  if (!pending || !pending.source) return "";
+  return String(pending.source.id || "").trim();
+}
 
-      messages.push({
-        role: "assistant",
-        content: null,
-        tool_calls: assistantToolCalls,
-      });
+function shadowDeclarePendingCalls(ledger, pendingCalls = []) {
+  const entries = (Array.isArray(pendingCalls) ? pendingCalls : []).map((pending) => ({
+    callId: pendingToolCallId(pending) || `call_${randomUUID()}`,
+    name: String(pending && pending.name || "").trim().toLowerCase(),
+    args: pending && pending.args != null ? pending.args : {},
+  }));
+  // Keep source ids aligned when we had to synthesize.
+  for (let i = 0; i < entries.length; i += 1) {
+    const pending = pendingCalls[i];
+    if (pending && pending.source && !pending.source.id) {
+      pending.source.id = entries[i].callId;
+    }
+  }
+  return declareCalls(ledger, entries);
+}
 
-      return assistantToolCalls.map((toolCall) => ({
-        name: toolCall.function.name,
-        args: normalizeToolCallArgs(toolCall.function.arguments),
-        source: toolCall,
-      }));
-    },
-    appendToolResult({ messages, call, toolResult }) {
-      messages.push({
-        role: "tool",
-        tool_call_id: call.source.id,
-        content: clipText(toJsonString(toolResult), 12000),
-      });
-    },
-  },
-  "anthropic-messages": {
-    resolveUrl: resolveAnthropicMessagesUrl,
-    prepareMessages({ messages, prompt }) {
-      messages.push({
-        role: "user",
-        content: String(prompt || ""),
-      });
-    },
-    runTurn: runAnthropicTurn,
-    getToolCalls(turnResult) {
-      return Array.isArray(turnResult.toolCalls) ? turnResult.toolCalls : [];
-    },
-    appendFinalAssistantMessage({ messages, turnResult }) {
-      const assistantContent = Array.isArray(turnResult.assistantContent)
-        ? turnResult.assistantContent
-        : [];
-      if (assistantContent.length > 0) {
-        messages.push({
-          role: "assistant",
-          content: assistantContent,
-        });
-      } else if (String(turnResult.text || "").trim()) {
-        messages.push({
-          role: "assistant",
-          content: [
-            {
-              type: "text",
-              text: String(turnResult.text || ""),
-            },
-          ],
-        });
-      }
-    },
-    prepareToolCalls({ messages, turnResult, toolCalls }) {
-      const assistantContent = Array.isArray(turnResult.assistantContent)
-        ? turnResult.assistantContent
-        : [];
-
-      messages.push({
-        role: "assistant",
-        content: assistantContent,
-      });
+function shadowResolvePending(ledger, pending, toolResult) {
+  if (!ledger) return;
+  const callId = pendingToolCallId(pending);
+  if (!callId) return;
+  resolveCall(ledger, callId, {
+    result: toolResult,
+    isError: Boolean(!toolResult || toolResult.ok === false),
+  });
+}
 
-      return toolCalls.map((call) => ({
-        name: call.name,
-        args: call.args,
-        source: call,
-      }));
-    },
-    appendToolResult({ collected, call, toolResult }) {
-      collected.push({
-        type: "tool_result",
-        tool_use_id: String(call.source.id || ""),
-        content: clipText(toJsonString(toolResult), 12000),
-        is_error: Boolean(!toolResult || toolResult.ok === false),
-      });
-    },
-    flushToolResults({ messages, collected }) {
-      messages.push({
-        role: "user",
-        content: collected,
-      });
-    },
-  },
-};
+function pendingByIdMap(pendingCalls = []) {
+  const map = Object.create(null);
+  for (const pending of pendingCalls) {
+    const id = pendingToolCallId(pending);
+    if (id) map[id] = pending;
+  }
+  return map;
+}
+
+function flushLedgerToolResults(ledger, transport, messages, pendingCalls) {
+  return materializeResolvedToolResults(ledger, {
+    transport,
+    messages,
+    pendingById: pendingByIdMap(pendingCalls),
+  });
+}
 
 async function runNativeLoop({
   transport,
@@ -1644,6 +1593,14 @@ async function runNativeLoop({
   ensurePendingUserPrompts(executionState);
   const toolBudget = resolveNativeToolBudget();
   const usage = createUsageTotals();
+  // Shadow Tool Call Ledger (R1). Observes declare/defer/resolve; does not
+  // materialize Provider messages yet. STRICT via UFOO_UCODE_PROTOCOL_STRICT=1.
+  let activeLedger = null;
+  let lastProtocolLedger = null;
+
+  if (resume) {
+    await withFaultPoint("before_provider_resume", () => {});
+  }
 
   function injectPendingUserReminders() {
     const nudges = drainUserPrompts(executionState);
@@ -1661,6 +1618,10 @@ async function runNativeLoop({
 
     injectPendingUserReminders();
 
+    if (activeLedger) {
+      runProviderTurnGate(activeLedger);
+    }
+
     const turnResult = await transport.runTurn({
       url: requestUrl,
       apiKey,
@@ -1730,6 +1691,7 @@ async function runNativeLoop({
         messages,
         usage,
         executionState,
+        protocolLedger: lastProtocolLedger || snapshotLedger(activeLedger),
       };
     }
 
@@ -1742,61 +1704,55 @@ async function runNativeLoop({
         messages,
         usage,
         executionState,
+        protocolLedger: lastProtocolLedger || snapshotLedger(activeLedger),
       };
     }
 
+    activeLedger = createToolCallLedger({ provider, sessionId });
+    shadowDeclarePendingCalls(activeLedger, pendingCalls);
+    lastProtocolLedger = snapshotLedger(activeLedger);
+    await withFaultPoint("after_prepare_tool_calls", () => {});
+    await withFaultPoint("before_tool_exec", () => {});
+
     const callNames = pendingCalls.map((call) => String(call.name || "").trim().toLowerCase());
     const hasPlanGraph = callNames.includes("plan_graph");
     const hasAskUser = callNames.includes("ask_user");
     const hasDataTool = callNames.some((name) => EXECUTABLE_GRAPH_TOOLS.has(name));
     if (hasPlanGraph && hasDataTool) {
       // prepareToolCalls already appended the assistant tool_calls / tool_use
-      // message; every declared call must get a contiguous tool result.
-      const collectedResults = [];
+      // 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",
+        code: "MIXED_PLAN_AND_DATA_TOOLS",
+      };
       for (const pending of pendingCalls) {
-        transport.appendToolResult({
-          messages,
-          collected: collectedResults,
-          call: pending,
-          toolResult: {
-            ok: false,
-            status: "rejected",
-            error: "Do not mix plan_graph with data-plane tools in the same turn",
-            code: "MIXED_PLAN_AND_DATA_TOOLS",
-          },
-        });
+        shadowResolvePending(activeLedger, pending, rejected);
         toolCallsExecuted += 1;
         toolErrors += 1;
       }
-      if (typeof transport.flushToolResults === "function") {
-        transport.flushToolResults({ messages, collected: collectedResults });
-      }
+      flushLedgerToolResults(activeLedger, transport, messages, pendingCalls);
+      lastProtocolLedger = snapshotLedger(activeLedger);
       continue;
     }
     if (hasAskUser && pendingCalls.length > 1) {
-      const collectedResults = [];
+      const rejected = {
+        ok: false,
+        status: "rejected",
+        error: "ask_user must be the only tool call in the turn",
+        code: "ASK_USER_MUST_BE_ALONE",
+      };
       for (const pending of pendingCalls) {
-        transport.appendToolResult({
-          messages,
-          collected: collectedResults,
-          call: pending,
-          toolResult: {
-            ok: false,
-            status: "rejected",
-            error: "ask_user must be the only tool call in the turn",
-            code: "ASK_USER_MUST_BE_ALONE",
-          },
-        });
+        shadowResolvePending(activeLedger, pending, rejected);
         toolCallsExecuted += 1;
         toolErrors += 1;
       }
-      if (typeof transport.flushToolResults === "function") {
-        transport.flushToolResults({ messages, collected: collectedResults });
-      }
+      flushLedgerToolResults(activeLedger, transport, messages, pendingCalls);
+      lastProtocolLedger = snapshotLedger(activeLedger);
       continue;
     }
 
-    const collectedResults = [];
     let deferredAskUser = null;
     for (const pending of pendingCalls) {
       const pendingName = String(pending.name || "").trim().toLowerCase();
@@ -1814,12 +1770,7 @@ async function runNativeLoop({
         };
         toolCallsExecuted += 1;
         toolErrors += 1;
-        transport.appendToolResult({
-          messages,
-          collected: collectedResults,
-          call: pending,
-          toolResult: blocked,
-        });
+        shadowResolvePending(activeLedger, pending, blocked);
         continue;
       }
       if (planModeBlocksDirectTool(pendingName, executionState)) {
@@ -1833,12 +1784,7 @@ async function runNativeLoop({
         };
         toolCallsExecuted += 1;
         toolErrors += 1;
-        transport.appendToolResult({
-          messages,
-          collected: collectedResults,
-          call: pending,
-          toolResult: blocked,
-        });
+        shadowResolvePending(activeLedger, pending, blocked);
         continue;
       }
       const leaseCheck = checkWriteAllowed(executionState, {
@@ -1858,12 +1804,7 @@ async function runNativeLoop({
         };
         toolCallsExecuted += 1;
         toolErrors += 1;
-        transport.appendToolResult({
-          messages,
-          collected: collectedResults,
-          call: pending,
-          toolResult: blocked,
-        });
+        shadowResolvePending(activeLedger, pending, blocked);
         continue;
       }
 
@@ -1882,6 +1823,7 @@ async function runNativeLoop({
         }
         : null;
 
+      markExecuting(activeLedger, pendingToolCallId(pending));
       const toolResult = runCoreTool({
         tool: pending.name,
         args: pending.args,
@@ -1911,6 +1853,7 @@ async function runNativeLoop({
             transport: provider === "anthropic" ? "anthropic-messages" : "openai-chat",
           };
         }
+        deferCall(activeLedger, pendingToolCallId(pending), { reason: "ask_user" });
         deferredAskUser = { call: pending, interactionId: toolResult.interactionId || "" };
         continue;
       }
@@ -1923,17 +1866,11 @@ async function runNativeLoop({
         lastTool: pending.name,
         lastError: toolResult && toolResult.error ? String(toolResult.error) : "",
       });
-      transport.appendToolResult({
-        messages,
-        collected: collectedResults,
-        call: pending,
-        toolResult,
-      });
+      shadowResolvePending(activeLedger, pending, toolResult);
     }
 
-    if (typeof transport.flushToolResults === "function") {
-      transport.flushToolResults({ messages, collected: collectedResults });
-    }
+    flushLedgerToolResults(activeLedger, transport, messages, pendingCalls);
+    lastProtocolLedger = snapshotLedger(activeLedger);
 
     if (deferredAskUser) {
       return {
@@ -1945,6 +1882,7 @@ async function runNativeLoop({
         executionState,
         waitingUserInteraction: true,
         interactionId: deferredAskUser.interactionId || "",
+        protocolLedger: lastProtocolLedger,
       };
     }
 
@@ -1959,33 +1897,30 @@ async function runNativeLoop({
         executionState,
         waitingUserInteraction: true,
         interactionId: (getPendingUserInteraction(executionState) || {}).id || "",
+        protocolLedger: lastProtocolLedger,
       };
     }
   }
 }
 
-function appendAnswerToolResult(messages = [], resume = null, answer = {}) {
-  const call = resume && resume.call ? resume.call : null;
-  if (!call || !call.source) return { ok: false, error: "missing deferred tool call" };
-  const transportName = String(resume.transport || "openai-chat");
-  const content = clipText(toJsonString(answer), 12000);
-  if (transportName === "anthropic-messages") {
-    messages.push({
-      role: "user",
-      content: [{
-        type: "tool_result",
-        tool_use_id: String(call.source.id || resume.toolCallId || ""),
-        content,
-        is_error: false,
-      }],
-    });
-  } else {
-    messages.push({
-      role: "tool",
-      tool_call_id: String(call.source.id || resume.toolCallId || ""),
-      content,
-    });
+function appendAnswerToolResult(messages = [], resume = null, answer = {}, options = {}) {
+  const materialized = materializeAnswerToolResult(messages, resume, answer);
+  if (!materialized.ok) return materialized;
+  const ledger = options && options.ledger ? options.ledger : null;
+  if (ledger) {
+    const call = resume && resume.call ? resume.call : null;
+    const callId = String(
+      (call && call.source && call.source.id) || (resume && resume.toolCallId) || ""
+    ).trim();
+    if (callId) {
+      resolveCall(ledger, callId, {
+        result: answer,
+        isError: false,
+        allowFromDeferred: true,
+      });
+    }
   }
+  checkFaultPoint("after_answer_commit");
   return { ok: true };
 }
 
@@ -2118,6 +2053,7 @@ async function runNativeAgentTask({
       streamed: Boolean(runResult.streamed) && typeof onStreamDelta === "function",
       waitingUserInteraction: Boolean(runResult.waitingUserInteraction),
       interactionId: runResult.interactionId || "",
+      protocolLedger: runResult.protocolLedger || null,
     };
   } catch (err) {
     const message = err && err.message ? err.message : "native runner failed";

package/src/code/protocol/controlPlane.js

@@ -0,0 +1,93 @@
+"use strict";
+
+/**
+ * Orthogonal control-plane fields (R5).
+ *
+ * planningPolicy: whether direct side-effect tools are allowed without a graph.
+ * executionOwner: who currently owns workspace / loop advancement.
+ *
+ * Dual-write with legacy planMode boolean during migration.
+ */
+
+const PLANNING_POLICIES = Object.freeze(["direct_allowed", "graph_required"]);
+
+function emptyExecutionOwner() {
+  return { kind: "none", id: "" };
+}
+
+function normalizePlanningPolicy(value = "") {
+  const raw = String(value || "").trim().toLowerCase();
+  if (PLANNING_POLICIES.includes(raw)) return raw;
+  return "";
+}
+
+function normalizeExecutionOwner(owner = null) {
+  if (!owner || typeof owner !== "object") return emptyExecutionOwner();
+  const kind = String(owner.kind || "none").trim().toLowerCase();
+  if (kind === "agent_loop" || kind === "task_run") {
+    return {
+      kind,
+      id: String(owner.id || owner.taskRunId || owner.agentLoopId || "").trim(),
+    };
+  }
+  return emptyExecutionOwner();
+}
+
+/**
+ * Sync planningPolicy ↔ planMode. Prefer explicit planningPolicy when present.
+ */
+function syncPlanningFields(executionState = null) {
+  const state = executionState && typeof executionState === "object" ? executionState : {};
+  const explicit = normalizePlanningPolicy(state.planningPolicy);
+  if (explicit) {
+    state.planningPolicy = explicit;
+    state.planMode = explicit === "graph_required";
+  } else if (state.planMode === true) {
+    state.planningPolicy = "graph_required";
+  } else {
+    state.planningPolicy = "direct_allowed";
+    state.planMode = false;
+  }
+  state.executionOwner = normalizeExecutionOwner(state.executionOwner);
+  return state;
+}
+
+function setPlanningPolicy(executionState = null, policy = "direct_allowed", {
+  reason = "",
+  source = "",
+} = {}) {
+  const state = syncPlanningFields(executionState);
+  const next = normalizePlanningPolicy(policy) || "direct_allowed";
+  state.planningPolicy = next;
+  // Dual-write legacy bool
+  const { setPlanMode } = require("../context/planMode");
+  setPlanMode(state, next === "graph_required", { reason, source });
+  state.planningPolicy = next;
+  return state;
+}
+
+function getPlanningPolicy(executionState = null) {
+  return syncPlanningFields(executionState).planningPolicy;
+}
+
+function setExecutionOwner(executionState = null, owner = null) {
+  const state = syncPlanningFields(executionState);
+  state.executionOwner = normalizeExecutionOwner(owner);
+  return state.executionOwner;
+}
+
+function getExecutionOwner(executionState = null) {
+  return syncPlanningFields(executionState).executionOwner;
+}
+
+module.exports = {
+  PLANNING_POLICIES,
+  emptyExecutionOwner,
+  normalizePlanningPolicy,
+  normalizeExecutionOwner,
+  syncPlanningFields,
+  setPlanningPolicy,
+  getPlanningPolicy,
+  setExecutionOwner,
+  getExecutionOwner,
+};