u-foo 2.5.11 → 2.5.13

package/package.json

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

package/src/agents/controller/ufooAgent.js

@@ -640,6 +640,31 @@ function stripMarkdownFence(text = "") {
   return raw;
 }
 
+function toNonNegativeInt(value) {
+  const num = Number(value);
+  if (!Number.isFinite(num) || num < 0) return 0;
+  return Math.floor(num);
+}
+
+// Maps provider usage payloads (OpenAI chat, Anthropic messages, Codex responses)
+// onto the metric fields read by extractModelMetrics in loopRuntime.js.
+function extractUsageTokens(usage = null) {
+  const item = usage && typeof usage === "object" ? usage : {};
+  return {
+    input_tokens: toNonNegativeInt(item.input_tokens || item.prompt_tokens),
+    output_tokens: toNonNegativeInt(item.output_tokens || item.completion_tokens),
+    cache_read_tokens: toNonNegativeInt(
+      item.cache_read_tokens
+        || item.cache_read_input_tokens
+        || item.cached_input_tokens
+        || (item.input_tokens_details && item.input_tokens_details.cached_tokens)
+    ),
+    cache_creation_tokens: toNonNegativeInt(
+      item.cache_creation_tokens || item.cache_creation_input_tokens
+    ),
+  };
+}
+
 async function runNativeRouterCall({
   projectRoot,
   prompt,
@@ -708,7 +733,7 @@ async function runUfooAgent({
       console.error(`[ufoo-agent] native provider failed: ${res.error || "unknown error"}`);
       return { ok: false, error: res.error };
     } else {
-      res = { ok: true, output: res.output, sessionId: "", provider: res.provider, model: res.model };
+      res = { ok: true, output: res.output, sessionId: "", provider: res.provider, model: res.model, usage: res.usage };
     }
   }
 
@@ -746,6 +771,7 @@ async function runUfooAgent({
     ok: true,
     payload,
     meta: {
+      ...extractUsageTokens(res.usage),
       memory_prefix_tokens: memoryPrefixResult.estimated_tokens || 0,
       cache_semistatic_hit: memoryPrefixResult.cache_semistatic_hit || 0,
       cache_semistatic_miss: memoryPrefixResult.cache_semistatic_miss || 0,

package/src/agents/internal/internalRunner.js

@@ -327,7 +327,7 @@ async function handleEvent(
   };
 
   if (threadRuntime && threadRuntime.enabled && threadRuntime.thread) {
-    await handleThreadedEvent({
+    return handleThreadedEvent({
       agentType,
       provider,
       publisher,
@@ -338,7 +338,6 @@ async function handleEvent(
       threadRuntime,
       tracker,
     });
-    return;
   }
 
   const errorText = `[internal:${agentType}] error: no thread runtime available for provider ${provider}; cliRunner fallback has been removed`;
@@ -374,6 +373,31 @@ function summarizeThreadToolCall(event = {}) {
   return [name, compactToolDetail(detail)].filter(Boolean).join(" · ");
 }
 
+function toNonNegativeInt(value) {
+  const num = Number(value);
+  if (!Number.isFinite(num) || num < 0) return 0;
+  return Math.floor(num);
+}
+
+// Normalizes provider usage payloads (claude/codex thread events) onto the
+// metric fields read by extractModelMetrics in agents/controller/loopRuntime.js.
+function normalizeTurnUsage(usage = null) {
+  const item = usage && typeof usage === "object" ? usage : {};
+  return {
+    input_tokens: toNonNegativeInt(item.input_tokens || item.prompt_tokens),
+    output_tokens: toNonNegativeInt(item.output_tokens || item.completion_tokens),
+    cache_read_tokens: toNonNegativeInt(
+      item.cache_read_tokens
+        || item.cache_read_input_tokens
+        || item.cached_input_tokens
+        || (item.input_tokens_details && item.input_tokens_details.cached_tokens)
+    ),
+    cache_creation_tokens: toNonNegativeInt(
+      item.cache_creation_tokens || item.cache_creation_input_tokens
+    ),
+  };
+}
+
 async function handleThreadedEvent({
   agentType,
   provider,
@@ -387,6 +411,8 @@ async function handleThreadedEvent({
 }) {
   try {
     const plainReplyParts = [];
+    let turnUsage = null;
+    let stopReason = "";
     if (tracker && typeof tracker.notifyTurnStart === "function") {
       tracker.notifyTurnStart();
     }
@@ -409,6 +435,11 @@ async function handleThreadedEvent({
         if (streamToPublisher && summary) {
           emitStreamDelta(`\nTool: ${summary}\n`);
         }
+      } else if (event.type === "usage" && event.usage) {
+        turnUsage = normalizeTurnUsage(event.usage);
+      } else if (event.type === "turn_completed") {
+        if (event.usage) turnUsage = normalizeTurnUsage(event.usage);
+        if (event.stopReason) stopReason = String(event.stopReason);
       } else if (event.type === "turn_failed") {
         throw new Error(event.error || `thread turn failed for ${agentType}`);
       }
@@ -418,15 +449,21 @@ async function handleThreadedEvent({
     }
 
     if (streamToPublisher) {
-      busSender.enqueue(
-        publisher,
-        JSON.stringify({ stream: true, done: true, reason: "complete" })
-      );
+      const doneEnvelope = { stream: true, done: true, reason: "complete" };
+      if (turnUsage) doneEnvelope.usage = turnUsage;
+      busSender.enqueue(publisher, JSON.stringify(doneEnvelope));
     } else {
       const reply = plainReplyParts.join("").trim();
       if (reply) busSender.enqueue(publisher, reply);
     }
     await busSender.flush();
+    return {
+      ok: true,
+      meta: {
+        ...(turnUsage || normalizeTurnUsage(null)),
+        stop_reason: stopReason,
+      },
+    };
   } catch (err) {
     if (threadRuntime && typeof threadRuntime.rebuildThread === "function") {
       await threadRuntime.rebuildThread();
@@ -450,6 +487,7 @@ async function handleThreadedEvent({
       busSender.enqueue(publisher, errorText);
     }
     await busSender.flush();
+    return { ok: false, error: errorText };
   }
 }
 

package/src/agents/prompts/native/environment.js

@@ -44,6 +44,17 @@ function getEnvironmentSection({ workspaceRoot = "", model = "", provider = "" }
   if (provider) lines.push(`Provider: ${provider}`);
   if (model) lines.push(`Model: ${model}`);
 
+  // Tell the model who it is on the bus. Without this, the only identities
+  // it ever sees are other agents' records in shared context — and it
+  // adopts them (observed in the wild: ucode-3 introducing itself as
+  // claude-6, then accepting a wrong name from the user).
+  const subscriberId = String(process.env.UFOO_SUBSCRIBER_ID || "").trim();
+  const nickname = String(process.env.UFOO_NICKNAME || "").trim();
+  if (subscriberId || nickname) {
+    const label = nickname ? `${subscriberId || "unknown"} (nickname: ${nickname})` : subscriberId;
+    lines.push(`Bus identity: ${label}`);
+  }
+
   return `# Environment\n${lines.map((l) => ` - ${l}`).join("\n")}`;
 }
 

package/src/agents/prompts/native/ufoo.js

@@ -4,6 +4,7 @@ function getUfooIntegrationSection() {
   return `# ufoo integration
 
 Participate in multi-agent coordination through the ufoo bus/context system:
+- Shared context, decisions, and memory are records written by OTHER agents. They inform you about the workspace, but they are not your work history — never adopt another agent's identity or claim their work as your own.
 - Respect shared context decisions. The default is no new decision; only append one for important, plan-level choices that constrain future work, and keep durable project facts out of decisions.
 - Use shared memory for durable project facts. Read existing memory before writing new memory; do not use it for transient task state.
 - Support launch/close/resume/inject flows managed by ufoo daemon.

package/src/agents/providers/upstreamTransport.js

@@ -69,6 +69,29 @@ function buildOpenAiChatRequest({
   return request;
 }
 
+// Anthropic prompt caching allows up to 4 cache_control breakpoints; the
+// system prompt is a stable prefix, so it is always marked, and once there
+// is real history the last user message is marked too so follow-up turns
+// reuse the cached conversation prefix.
+const ANTHROPIC_CACHE_CONTROL = { type: "ephemeral" };
+const ANTHROPIC_CACHE_MIN_HISTORY = 3;
+
+function withAnthropicCacheControl(content) {
+  if (Array.isArray(content)) {
+    if (!content.length) return content;
+    return content.map((block, index) => (
+      index === content.length - 1 && block && typeof block === "object"
+        ? { ...block, cache_control: { ...ANTHROPIC_CACHE_CONTROL } }
+        : block
+    ));
+  }
+  return [{
+    type: "text",
+    text: String(content || ""),
+    cache_control: { ...ANTHROPIC_CACHE_CONTROL },
+  }];
+}
+
 function buildAnthropicMessagesRequest({
   model = "",
   systemPrompt = "",
@@ -82,13 +105,20 @@ function buildAnthropicMessagesRequest({
   if (!requestMessages.length) {
     requestMessages.push({ role: "user", content: String(prompt || "") });
   }
+  if (requestMessages.length >= ANTHROPIC_CACHE_MIN_HISTORY) {
+    for (let i = requestMessages.length - 1; i >= 0; i -= 1) {
+      if (requestMessages[i].role !== "user") continue;
+      requestMessages[i].content = withAnthropicCacheControl(requestMessages[i].content);
+      break;
+    }
+  }
   const request = {
     model: String(model || "").trim(),
     max_tokens: maxTokens,
     messages: requestMessages,
     temperature,
   };
-  if (systemPrompt) request.system = systemPrompt;
+  if (systemPrompt) request.system = withAnthropicCacheControl(String(systemPrompt));
   if (Array.isArray(tools) && tools.length > 0) {
     request.tools = tools.slice();
   }

package/src/app/chat/dashboardView.js

@@ -72,6 +72,7 @@ function formatLoopSummary(loopSummary) {
   const rounds = Number(loopSummary.rounds) || 0;
   const toolCalls = Number(loopSummary.tool_calls) || 0;
   const totalTokens = Number(loopSummary.total_tokens) || 0;
+  const inputTokens = Number(loopSummary.input_tokens) || 0;
   const cacheReadTokens = Number(loopSummary.cache_read_tokens) || 0;
   const cacheCreationTokens = Number(loopSummary.cache_creation_tokens) || 0;
   const terminalReason = String(loopSummary.terminal_reason || "").trim();
@@ -87,7 +88,12 @@ function formatLoopSummary(loopSummary) {
     `tok${totalTokens}`,
   ];
   if (cacheReadTokens > 0 || cacheCreationTokens > 0) {
-    parts.push(`cache${cacheReadTokens}/${cacheCreationTokens}`);
+    let cachePart = `cache${cacheReadTokens}/${cacheCreationTokens}`;
+    if (cacheReadTokens > 0) {
+      const hitRate = Math.round((cacheReadTokens / (cacheReadTokens + inputTokens)) * 100);
+      cachePart += `(${hitRate}%)`;
+    }
+    parts.push(cachePart);
   }
   if (toolDistribution) {
     parts.push(toolDistribution);

package/src/code/agent.js

@@ -141,6 +141,18 @@ function computeExtendedTimeout(baseTimeoutMs) {
   return Math.min(1800000, Math.max(base * 2, base + 120000));
 }
 
+// Reasoning models routinely blew the old 10min budget across a multi-turn
+// tool loop. Total per-task budget defaults to 30min and can be raised per
+// call, via --timeout-ms, or via UFOO_UCODE_TASK_TIMEOUT_MS.
+const DEFAULT_NL_TASK_TIMEOUT_MS = 1800000;
+
+function resolveNlTaskTimeoutMs(value) {
+  if (Number.isFinite(value) && value > 0) return Math.max(1000, Math.floor(value));
+  const env = Number(process.env.UFOO_UCODE_TASK_TIMEOUT_MS);
+  if (Number.isFinite(env) && env > 0) return Math.max(1000, Math.floor(env));
+  return DEFAULT_NL_TASK_TIMEOUT_MS;
+}
+
 function enrichNativeError(errorMessage = "") {
   const text = String(errorMessage || "").trim();
   if (!text) return "nl task failed";
@@ -168,6 +180,9 @@ function enrichNativeError(errorMessage = "") {
   ) {
     return `${text}. Check provider/url/key via /settings ucode show.`;
   }
+  if (lower.includes("cli timeout")) {
+    return `${text}. Task budget exceeded; raise it with --timeout-ms or UFOO_UCODE_TASK_TIMEOUT_MS.`;
+  }
   return text;
 }
 
@@ -394,7 +409,7 @@ async function runNaturalLanguageTask(task = "", state = {}, options = {}) {
     state.provider || process.env.UFOO_UCODE_PROVIDER || ""
   );
   const model = String(state.model || process.env.UFOO_UCODE_MODEL || "").trim();
-  const timeoutMs = Number.isFinite(state.timeoutMs) ? state.timeoutMs : 600000;
+  const timeoutMs = resolveNlTaskTimeoutMs(state.timeoutMs);
   let streamed = false;
   let streamLastChar = "";
   let toolEventsThisAttempt = 0;
@@ -715,6 +730,8 @@ module.exports = {
   resolvePlannerProvider,
   extractJsonSummary,
   enrichNativeError,
+  resolveNlTaskTimeoutMs,
+  DEFAULT_NL_TASK_TIMEOUT_MS,
   resolveUcodeProviderModel,
   buildSessionSnapshotFromState,
   persistSessionState,

package/src/code/nativeRunner.js

@@ -5,6 +5,7 @@ const {
   resolveKimiUpstreamCredentials,
 } = require("../agents/providers/credentials/kimi");
 const { runToolCall } = require("./dispatch");
+const { appendUsageRecord } = require("./usageStore");
 const { getReadToolDescription } = require("../agents/prompts/native/toolDescriptions/read");
 const { getWriteToolDescription } = require("../agents/prompts/native/toolDescriptions/write");
 const { getEditToolDescription } = require("../agents/prompts/native/toolDescriptions/edit");
@@ -25,6 +26,11 @@ const DEFAULT_MAX_NATIVE_TOOL_ERRORS = 5;
 // via UFOO_UCODE_MAX_TOKENS (positive integer).
 const DEFAULT_OPENAI_MAX_TOKENS = 131072;
 const DEFAULT_ANTHROPIC_MAX_TOKENS = 64000;
+// 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
+// breakpoints).
+const ANTHROPIC_CACHE_CONTROL = Object.freeze({ type: "ephemeral" });
 
 function nowMs() {
   return Date.now();
@@ -53,6 +59,58 @@ function resolveMaxTokens(fallback) {
   return normalizePositiveInt(process.env.UFOO_UCODE_MAX_TOKENS, fallback);
 }
 
+function toUsageInt(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return 0;
+  return Math.floor(parsed);
+}
+
+function createUsageTotals() {
+  return {
+    turns: 0,
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheCreation: 0,
+  };
+}
+
+function addUsageTotals(totals, usage = null) {
+  if (!usage || typeof usage !== "object") return totals;
+  totals.input += toUsageInt(usage.input);
+  totals.output += toUsageInt(usage.output);
+  totals.cacheRead += toUsageInt(usage.cacheRead);
+  totals.cacheCreation += toUsageInt(usage.cacheCreation);
+  return totals;
+}
+
+// OpenAI-compatible streams end with one usage chunk carrying whole-turn
+// totals (prompt_tokens_details.cached_tokens counts the cache hits).
+function readOpenAiUsage(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const details = raw.prompt_tokens_details && typeof raw.prompt_tokens_details === "object"
+    ? raw.prompt_tokens_details
+    : {};
+  return {
+    input: toUsageInt(raw.prompt_tokens),
+    output: toUsageInt(raw.completion_tokens),
+    cacheRead: toUsageInt(details.cached_tokens),
+    cacheCreation: 0,
+  };
+}
+
+// Anthropic reports input/cache tokens once on message_start; output tokens
+// arrive per message_delta. The non-streaming body carries the full totals.
+function readAnthropicUsage(raw, { includeOutput = false } = {}) {
+  if (!raw || typeof raw !== "object") return null;
+  return {
+    input: toUsageInt(raw.input_tokens),
+    output: includeOutput ? toUsageInt(raw.output_tokens) : 0,
+    cacheRead: toUsageInt(raw.cache_read_input_tokens),
+    cacheCreation: toUsageInt(raw.cache_creation_input_tokens),
+  };
+}
+
 function enforceNativeToolBudget({
   toolCallsExecuted = 0,
   toolErrors = 0,
@@ -576,6 +634,8 @@ async function runOpenAiLikeTurn({
     tools: buildCoreToolSpecs(),
     tool_choice: "auto",
     stream: true,
+    // Ask for the terminal usage chunk so token/cache accounting works.
+    stream_options: { include_usage: true },
     // Kimi k3 rejects any temperature other than 1.
     temperature: normalizeProvider(provider) === "kimi" ? 1 : 0,
   };
@@ -592,6 +652,7 @@ async function runOpenAiLikeTurn({
   let responseText = "";
   let nextSyntheticIndex = 0;
   let lastSyntheticIndex = -1;
+  let streamUsage = null;
 
   return runSseRequest({
     url,
@@ -612,12 +673,18 @@ async function runOpenAiLikeTurn({
       return {
         text,
         toolCalls,
+        usage: readOpenAiUsage(data && data.usage),
       };
     },
     onEvent: ({ data }) => {
       const chunk = parseJsonSafe(data, null);
       if (!chunk || typeof chunk !== "object") return;
 
+      // The usage chunk carries empty choices, so read it before the
+      // choice guard below; latest wins (it reports whole-turn totals).
+      const chunkUsage = readOpenAiUsage(chunk.usage);
+      if (chunkUsage) streamUsage = chunkUsage;
+
       const choice = chunk.choices && chunk.choices[0] ? chunk.choices[0] : null;
       if (!choice || typeof choice !== "object") return;
 
@@ -695,6 +762,8 @@ async function runOpenAiLikeTurn({
       const fallbackBlock = parseSseDataBlock(rawBuffer);
       if (fallbackBlock && fallbackBlock !== "[DONE]") {
         const chunk = parseJsonSafe(fallbackBlock, null);
+        const tailUsage = readOpenAiUsage(chunk && chunk.usage);
+        if (tailUsage) streamUsage = tailUsage;
         const choice = chunk && chunk.choices && chunk.choices[0] ? chunk.choices[0] : null;
         if (choice && choice.delta && typeof choice.delta.content === "string" && choice.delta.content) {
           responseText += choice.delta.content;
@@ -709,6 +778,7 @@ async function runOpenAiLikeTurn({
       toolCalls: Array.from(toolCallMap.entries())
         .sort((a, b) => a[0] - b[0])
         .map((entry) => entry[1]),
+      usage: streamUsage,
     }),
   });
 }
@@ -751,6 +821,48 @@ function extractAnthropicToolCalls(content = []) {
     }));
 }
 
+// Mark the newest message with a cache breakpoint so the append-only history
+// prefix is served from the prompt cache. The payload gets a copy: stamping
+// cache_control onto the shared history array would leave stale breakpoints
+// behind as later turns append, eventually exceeding the 4-breakpoint limit.
+function withAnthropicCacheBreakpoint(messages = []) {
+  if (!Array.isArray(messages) || messages.length === 0) return messages;
+  const copy = messages.slice();
+  const lastIndex = copy.length - 1;
+  const last = copy[lastIndex];
+  if (!last || typeof last !== "object" || Array.isArray(last)) return copy;
+  if (typeof last.content === "string") {
+    if (!last.content) return copy;
+    copy[lastIndex] = {
+      ...last,
+      content: [
+        {
+          type: "text",
+          text: last.content,
+          cache_control: { ...ANTHROPIC_CACHE_CONTROL },
+        },
+      ],
+    };
+    return copy;
+  }
+  if (Array.isArray(last.content) && last.content.length > 0) {
+    const blocks = last.content.slice();
+    const blockIndex = blocks.length - 1;
+    const block = blocks[blockIndex];
+    if (block && typeof block === "object" && !Array.isArray(block)) {
+      blocks[blockIndex] = {
+        ...block,
+        cache_control: { ...ANTHROPIC_CACHE_CONTROL },
+      };
+      copy[lastIndex] = {
+        ...last,
+        content: blocks,
+      };
+    }
+  }
+  return copy;
+}
+
 async function runAnthropicTurn({
   url = "",
   apiKey = "",
@@ -766,13 +878,21 @@ async function runAnthropicTurn({
   const payload = {
     model,
     max_tokens: resolveMaxTokens(DEFAULT_ANTHROPIC_MAX_TOKENS),
-    messages,
+    messages: withAnthropicCacheBreakpoint(messages),
     tools: buildAnthropicToolSpecs(),
     stream: true,
   };
   const systemText = String(systemPrompt || "").trim();
   if (systemText) {
-    payload.system = systemText;
+    // Block form with a cache breakpoint; the system prompt is the most
+    // stable prefix of every request.
+    payload.system = [
+      {
+        type: "text",
+        text: systemText,
+        cache_control: { ...ANTHROPIC_CACHE_CONTROL },
+      },
+    ];
   }
 
   const headers = {
@@ -787,6 +907,7 @@ async function runAnthropicTurn({
   let responseText = "";
   let nextSyntheticBlockIndex = 0;
   let lastBlockIndex = -1;
+  const turnUsage = { input: 0, output: 0, cacheRead: 0, cacheCreation: 0 };
 
   return runSseRequest({
     url,
@@ -804,10 +925,12 @@ async function runAnthropicTurn({
       if (text && typeof onTextDelta === "function") {
         onTextDelta(text);
       }
+      addUsageTotals(turnUsage, readAnthropicUsage(data && data.usage, { includeOutput: true }));
       return {
         text,
         assistantContent: content,
         toolCalls: extractAnthropicToolCalls(content),
+        usage: turnUsage,
       };
     },
     onEvent: ({ event, data }) => {
@@ -821,6 +944,28 @@ async function runAnthropicTurn({
         throw new Error(errMsg);
       }
 
+      if (event === "message_start") {
+        const messageUsage = readAnthropicUsage(
+          payloadChunk.message && typeof payloadChunk.message === "object"
+            ? payloadChunk.message.usage
+            : null
+        );
+        if (messageUsage) {
+          turnUsage.input = messageUsage.input;
+          turnUsage.cacheRead = messageUsage.cacheRead;
+          turnUsage.cacheCreation = messageUsage.cacheCreation;
+        }
+        return;
+      }
+
+      if (event === "message_delta") {
+        const deltaUsage = payloadChunk.usage && typeof payloadChunk.usage === "object"
+          ? payloadChunk.usage
+          : {};
+        turnUsage.output += toUsageInt(deltaUsage.output_tokens);
+        return;
+      }
+
       if (event === "content_block_start") {
         let index;
         if (Number.isFinite(payloadChunk.index)) {
@@ -957,6 +1102,7 @@ async function runAnthropicTurn({
         text: responseText,
         assistantContent,
         toolCalls: extractAnthropicToolCalls(assistantContent),
+        usage: turnUsage,
       };
     },
   });
@@ -1133,6 +1279,7 @@ async function runNativeLoop({
   let toolCallsExecuted = 0;
   let toolErrors = 0;
   const toolBudget = resolveNativeToolBudget();
+  const usage = createUsageTotals();
 
   while (true) {
     guards.ensureActive();
@@ -1159,6 +1306,9 @@ async function runNativeLoop({
       },
     });
 
+    usage.turns += 1;
+    addUsageTotals(usage, turnResult && turnResult.usage);
+
     const toolCalls = transport.getToolCalls(turnResult);
 
     if (toolCalls.length === 0) {
@@ -1172,6 +1322,7 @@ async function runNativeLoop({
         streamed,
         toolCallsExecuted,
         messages,
+        usage,
       };
     }
 
@@ -1182,6 +1333,7 @@ async function runNativeLoop({
         streamed,
         toolCallsExecuted,
         messages,
+        usage,
       };
     }
 
@@ -1312,12 +1464,27 @@ async function runNativeAgentTask({
         : ""
     );
 
+    const usage = runResult.usage && typeof runResult.usage === "object"
+      ? runResult.usage
+      : createUsageTotals();
+    appendUsageRecord(workspaceRoot, {
+      sessionId: nextSessionId,
+      model: runtime.model,
+      provider: runtime.provider,
+      turns: usage.turns,
+      input: usage.input,
+      output: usage.output,
+      cacheRead: usage.cacheRead,
+      cacheCreation: usage.cacheCreation,
+    });
+
     return {
       ok: true,
       error: "",
       output: outputText,
       messages: cloneMessageList(runResult.messages),
       sessionId: nextSessionId,
+      usage,
       // The loop marks streamed=true whenever it receives a stream callback;
       // only report it when the caller actually registered one.
       streamed: Boolean(runResult.streamed) && typeof onStreamDelta === "function",

package/src/code/repl.js

@@ -21,6 +21,7 @@ const {
   getPendingBusCount,
   shouldAutoConsumeBus,
 } = require("./busConsumer");
+const { summarizeSessionUsage } = require("./usageStore");
 
 function printPrompt(stdout = process.stdout) {
   stdout.write("> ");
@@ -74,6 +75,20 @@ function extractAgentNickname(agentId = "") {
   return base;
 }
 
+function formatSessionUsageStatus(summary = {}) {
+  const source = summary && typeof summary === "object" ? summary : {};
+  const input = Number(source.input) || 0;
+  const output = Number(source.output) || 0;
+  const cacheRead = Number(source.cacheRead) || 0;
+  const cacheCreation = Number(source.cacheCreation) || 0;
+  const denominator = cacheRead + input;
+  const hitRate = denominator > 0 ? (cacheRead / denominator) * 100 : 0;
+  return [
+    `Session tokens: input=${input} output=${output} cache_read=${cacheRead} cache_creation=${cacheCreation}`,
+    `Cache hit rate: ${hitRate.toFixed(1)}% (cache_read/(cache_read+input))`,
+  ].join("\n");
+}
+
 function runSingleCommand(line = "", workspaceRoot = process.cwd()) {
   const text = normalizeLine(line);
   if (!text) return { kind: "empty" };
@@ -86,6 +101,7 @@ function runSingleCommand(line = "", workspaceRoot = process.cwd()) {
         "  help",
         "  exit|quit",
         "  ubus|/ubus",
+        "  status|/status",
         "  skills [list]",
         "  skills show <name>",
         "  bg|/bg <task>",
@@ -107,6 +123,11 @@ function runSingleCommand(line = "", workspaceRoot = process.cwd()) {
       kind: "ubus",
     };
   }
+  if (text === "status" || text === "/status") {
+    return {
+      kind: "status",
+    };
+  }
   const skillsMatch = text.match(/^(?:\/skills|skills)(?:\s+(.*))?$/i);
   if (skillsMatch) {
     const args = String(skillsMatch[1] || "").trim().split(/\s+/).filter(Boolean);
@@ -228,7 +249,7 @@ async function runUcodeCoreAgent({
   appendSystemPrompt = "",
   systemPrompt = "",
   sessionId = "",
-  timeoutMs = 600000,
+  timeoutMs = 0,
   jsonOutput = false,
   forceTui = false,
   disableTui = false,
@@ -240,6 +261,7 @@ async function runUcodeCoreAgent({
     formatNlResult,
     persistSessionState,
     resumeSessionState,
+    resolveNlTaskTimeoutMs,
     resolveUcodeProviderModel,
     runNaturalLanguageTask,
   } = require("./agent");
@@ -263,7 +285,7 @@ async function runUcodeCoreAgent({
     }),
     nlMessages: [],
     sessionId: resolveSessionId(String(sessionId || "").trim()),
-    timeoutMs,
+    timeoutMs: resolveNlTaskTimeoutMs(Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : NaN),
     jsonOutput,
   };
   persistSessionState(state);
@@ -410,6 +432,13 @@ async function runUcodeCoreAgent({
       if (result.kind === "help" || result.kind === "tool" || result.kind === "skills" || result.kind === "error") {
         stdout.write(`${result.output}\n`);
       }
+      if (result.kind === "status") {
+        const usageSummary = summarizeSessionUsage({
+          workspaceRoot: runtimeWorkspace,
+          sessionId: state.sessionId,
+        });
+        stdout.write(`${formatSessionUsageStatus(usageSummary)}\n`);
+      }
       if (result.kind === "ubus") {
         const ubusResult = await runUbusCommand(state, {
           workspaceRoot: runtimeWorkspace,
@@ -542,7 +571,7 @@ function parseAgentArgs(argv = []) {
     appendSystemPrompt: "",
     systemPrompt: "",
     sessionId: "",
-    timeoutMs: 600000,
+    timeoutMs: 0,
     jsonOutput: false,
     forceTui: false,
     disableTui: false,
@@ -607,4 +636,5 @@ module.exports = {
   runSingleCommand,
   extractAgentNickname,
   parseAgentArgs,
+  formatSessionUsageStatus,
 };

package/src/code/usageStore.js

@@ -0,0 +1,101 @@
+const fs = require("fs");
+const path = require("path");
+
+function getUsageFilePath(workspaceRoot = process.cwd()) {
+  const root = path.resolve(workspaceRoot || process.cwd());
+  return path.join(root, ".ufoo", "agent", "ucode", "usage.jsonl");
+}
+
+function toUsageCount(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return 0;
+  return Math.floor(parsed);
+}
+
+function buildUsageRecord(input = {}) {
+  const source = input && typeof input === "object" ? input : {};
+  return {
+    ts: String(source.ts || "").trim() || new Date().toISOString(),
+    sessionId: String(source.sessionId || "").trim(),
+    model: String(source.model || "").trim(),
+    provider: String(source.provider || "").trim(),
+    turns: toUsageCount(source.turns),
+    input: toUsageCount(source.input),
+    output: toUsageCount(source.output),
+    cacheRead: toUsageCount(source.cacheRead),
+    cacheCreation: toUsageCount(source.cacheCreation),
+  };
+}
+
+function appendUsageRecord(workspaceRoot = process.cwd(), record = {}) {
+  const row = buildUsageRecord(record);
+  const filePath = getUsageFilePath(workspaceRoot);
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.appendFileSync(filePath, `${JSON.stringify(row)}\n`, "utf8");
+    return {
+      ok: true,
+      error: "",
+      filePath,
+      record: row,
+    };
+  } catch (err) {
+    // Usage accounting is observability only: never let a write failure
+    // break the agent loop.
+    return {
+      ok: false,
+      error: err && err.message ? err.message : "failed to append usage",
+      filePath,
+      record: row,
+    };
+  }
+}
+
+function createUsageSummary() {
+  return {
+    records: 0,
+    turns: 0,
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheCreation: 0,
+  };
+}
+
+function summarizeSessionUsage({ workspaceRoot = process.cwd(), sessionId = "" } = {}) {
+  const summary = createUsageSummary();
+  const targetSessionId = String(sessionId || "").trim();
+  let raw = "";
+  try {
+    raw = fs.readFileSync(getUsageFilePath(workspaceRoot), "utf8");
+  } catch {
+    return summary;
+  }
+  for (const line of String(raw).split(/\r?\n/)) {
+    const text = line.trim();
+    if (!text) continue;
+    let row = null;
+    try {
+      row = JSON.parse(text);
+    } catch {
+      continue;
+    }
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    if (targetSessionId && String(row.sessionId || "").trim() !== targetSessionId) continue;
+    summary.records += 1;
+    summary.turns += toUsageCount(row.turns);
+    summary.input += toUsageCount(row.input);
+    summary.output += toUsageCount(row.output);
+    summary.cacheRead += toUsageCount(row.cacheRead);
+    summary.cacheCreation += toUsageCount(row.cacheCreation);
+  }
+  return summary;
+}
+
+module.exports = {
+  getUsageFilePath,
+  buildUsageRecord,
+  appendUsageRecord,
+  createUsageSummary,
+  summarizeSessionUsage,
+};

package/src/ui/ink/DashboardBar.js

@@ -74,6 +74,7 @@ function formatLoopSummary(loopSummary) {
   const rounds = Number(loopSummary.rounds) || 0;
   const toolCalls = Number(loopSummary.tool_calls) || 0;
   const totalTokens = Number(loopSummary.total_tokens) || 0;
+  const inputTokens = Number(loopSummary.input_tokens) || 0;
   const cacheReadTokens = Number(loopSummary.cache_read_tokens) || 0;
   const cacheCreationTokens = Number(loopSummary.cache_creation_tokens) || 0;
   const terminalReason = String(loopSummary.terminal_reason || "").trim();
@@ -81,7 +82,12 @@ function formatLoopSummary(loopSummary) {
   if (rounds <= 0 && toolCalls <= 0 && totalTokens <= 0 && !terminalReason && !toolDistribution) return "";
   const parts = [`r${rounds}`, `tc${toolCalls}`, `tok${totalTokens}`];
   if (cacheReadTokens > 0 || cacheCreationTokens > 0) {
-    parts.push(`cache${cacheReadTokens}/${cacheCreationTokens}`);
+    let cachePart = `cache${cacheReadTokens}/${cacheCreationTokens}`;
+    if (cacheReadTokens > 0) {
+      const hitRate = Math.round((cacheReadTokens / (cacheReadTokens + inputTokens)) * 100);
+      cachePart += `(${hitRate}%)`;
+    }
+    parts.push(cachePart);
   }
   if (toolDistribution) parts.push(toolDistribution);
   if (terminalReason) parts.push(terminalReason);