@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/agent/retry.js

@@ -33,6 +33,19 @@ const RETRYABLE_PHRASES = [
   /timeout/i,
 ];
 
+// A 404 that means "this model is retired / unknown", as opposed to a 404 that
+// means "wrong base_url". Kept narrow on purpose: a typo'd model id also lands
+// here, and rotating past it is still the better outcome than a dead turn.
+const MODEL_RETIRED_PHRASES = [
+  /no longer available/i,
+  /not found for API version/i,
+  /does not exist/i,
+  /unknown model/i,
+  /model.{0,20}(not found|is not supported)/i,
+  /has been (deprecated|retired|removed)/i,
+  /model is unavailable/i,
+];
+
 const FATAL_STATUS = new Set([400, 401, 403, 404, 422]);
 
 const FATAL_PHRASES = [
@@ -45,6 +58,8 @@ const FATAL_PHRASES = [
 ];
 
 export function isRetryableEngineError(err) {
+  if (err?.name === "AbortError" || err?.code === "ABORT_ERR") return false;
+
   const msg = String(err?.message || err || "");
   if (!msg) return false;
 
@@ -69,9 +84,36 @@ export function isRetryableEngineError(err) {
           /looks like (object|array)|can'?t find closing|unexpected end of json|invalid (json|grammar)/i.test(msg)) {
         return true;
       }
+      // A gateway 400 with no message at all — Zen answers upstream failures
+      // with a bare `{"object":"error","model":"..."}` envelope. There is
+      // nothing in it to fix, and it is as likely to be the vendor behind the
+      // gateway as it is to be our payload, so the chain gets to try the next
+      // model rather than ending the run on an error the user cannot act on.
+      if (/^[a-z0-9_-]+ 400:\s*\{"object":\s*"error"/i.test(msg)) return true;
+      // A gateway that answers 400 (not 404) for a model it no longer serves:
+      //   zen 400: Error from provider (Console): Upstream request failed:
+      //   Model is unavailable
+      // Same situation as a retired model, different status code — the model
+      // is not coming back this turn, so walk the chain.
+      if (MODEL_RETIRED_PHRASES.some((re) => re.test(msg))) return true;
+      // A history-fidelity requirement we may not be able to satisfy: the turn
+      // being replayed came from a different engine (post-rotation) and never
+      // carried the field. Serialising it correctly is zen.js's job; when the
+      // data isn't there, a model that doesn't demand it is the only way out.
+      if (/reasoning_content|thought.?signature/i.test(msg)) return true;
       // explicit schema / param errors are our bug, not transient
       return false;
     }
+    // 404 usually means "you pointed at the wrong endpoint" — fatal, fix it.
+    // But it is ALSO how a provider retires a model:
+    //   gemini 404: This model models/gemini-2.5-flash-lite is no longer
+    //   available. Please update your code to use models/gemini-3.5-flash-lite
+    //   openai 404: The model `x` does not exist or you do not have access
+    // That is exactly what the fallback chain is for. The model is gone for
+    // good, the user cannot act on it mid-turn, and the next model in the
+    // chain will answer — so rotate instead of ending the run on a wall of
+    // provider text. A 404 that is NOT about the model stays fatal.
+    if (status === 404 && MODEL_RETIRED_PHRASES.some((re) => re.test(msg))) return true;
     return false;
   }
   if (status && RETRYABLE_STATUS.has(status)) return true;

package/src/core/agent/run-agent.js

@@ -3,12 +3,14 @@ import {
   extractPseudoToolCalls,
   extractBareFunctionCalls,
   cleanTextOfPseudoToolCalls,
+  looksLikeFabricatedToolLog,
 } from "./tools/tool-call-parser.js";
-import { resolveActiveModel, fallbackModels } from "./model-router.js";
+import { resolveActiveModel, fallbackModels, isFallbackEnabled } from "./model-router.js";
 import { MAX_TOOL_ITERS, ACK_ONLY_TOOLS, MAX_CONSECUTIVE_ACKS, TURN_ENDING_TOOLS } from "./constants.js";
 import { TOOLS } from "./tools/names.js";
 import { pseudoToolSystem, shouldRetryWithPseudoTools } from "./tools/pseudo-tools.js";
 import { filterToolSchemas } from "./tools-overlap.js";
+import { buildRuntimeBlock } from "./prompt-builder.js";
 import { isRetryableEngineError, shortRetryReason } from "./retry.js";
 import {
   securityRiskConfig,
@@ -25,17 +27,57 @@ import {
 } from "./stuck-detector.js";
 import { createGreetingGuard } from "./loop/greeting-guard.js";
 import { createSideEffectLedger } from "./loop/side-effects.js";
+import {
+  describeTurnImages,
+  providerWiresVision,
+  withImageDescription,
+} from "./vision-bridge.js";
+import { messagesForModel } from "./model-capabilities.js";
 
 async function emitProgress(onEvent, event) {
   if (typeof onEvent !== "function") return;
   await onEvent(event);
 }
 
+// How much of one tool result the trace carries. The trace is what gets
+// PERSISTED (message store, web viewer) and what the next turns replay as
+// history, so this cap is the memory a past tool call leaves behind.
+const TRACE_RESULT_CAP = 1200;
+// Longest single string field kept inside a structured result.
+const TRACE_FIELD_CAP = 900;
+
+// Shrink a tool result for the trace WITHOUT destroying its shape. The old
+// version stringified anything over 400 chars and sliced the JSON text, which
+// left a half-open brace: unparseable, so every downstream reader (history
+// replay, viewer) had to show escaped JSON instead of the actual output. Now
+// the envelope survives and only the long string fields inside are clipped —
+// `{ exit_code, stdout }` stays an object whose stdout is trimmed.
 function summarizeForTrace(r) {
   if (r === null || r === undefined) return r;
-  const s = JSON.stringify(r);
-  if (s.length <= 400) return r;
-  return s.slice(0, 380) + "…(truncated)";
+  if (typeof r === "string") {
+    return r.length <= TRACE_RESULT_CAP ? r : r.slice(0, TRACE_RESULT_CAP) + "…(truncated)";
+  }
+  if (typeof r !== "object") return r;
+  try {
+    if (JSON.stringify(r).length <= TRACE_RESULT_CAP) return r;
+  } catch {
+    return String(r).slice(0, TRACE_RESULT_CAP);
+  }
+  const clip = (v, depth) => {
+    if (typeof v === "string") {
+      return v.length <= TRACE_FIELD_CAP ? v : v.slice(0, TRACE_FIELD_CAP) + "…(truncated)";
+    }
+    if (Array.isArray(v)) {
+      const head = v.slice(0, 20).map((x) => clip(x, depth + 1));
+      return v.length > 20 ? [...head, `…(${v.length - 20} more)`] : head;
+    }
+    if (v && typeof v === "object") {
+      if (depth >= 3) return "…(nested)";
+      return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, clip(x, depth + 1)]));
+    }
+    return v;
+  };
+  return clip(r, 0);
 }
 
 function fallbackFinalText(trace, error) {
@@ -50,6 +92,15 @@ function fallbackFinalText(trace, error) {
   return lines.join("\n");
 }
 
+/**
+ * Did the engine stop because it ran out of output budget? Every adapter passes
+ * the provider's own word through: OpenAI-shaped gateways say "length", Gemini
+ * says "MAX_TOKENS".
+ */
+function wasTruncated(result) {
+  return /^(length|max_tokens)$/i.test(String(result?.finish_reason || ""));
+}
+
 function previewTraceResult(result) {
   if (result === null || result === undefined) return "ok";
   if (typeof result === "string") return result.slice(0, 180);
@@ -115,6 +166,59 @@ const WRAPUP_SIGNAL =
   "Talk like a person giving a quick status update. Do NOT emit a tool call, " +
   "JSON, or system jargon like \"iteration\" or \"limit\".]";
 
+// How many times one turn may be nudged past an output-limit truncation before
+// we let it end. A model that answers with a wall of prose every time is not
+// going to start acting on the third try, and the wrap-up still fires.
+const MAX_LENGTH_CONTINUES = 2;
+
+// A model that hits its output cap mid-sentence has not finished; it has been
+// cut off. Every adapter reports that as a finish reason, and the loop used to
+// ignore it: no tool calls in a truncated message means "the model stopped
+// calling tools", which reads as a completed turn. So a routine that wrote six
+// ideas out as YAML instead of filing them, ran out of budget halfway through
+// the sixth, and never called the tool, reported `status: ok` with a reply that
+// began mid-word.
+//
+// This note goes in as a conversation turn so weak models actually answer it,
+// and it asks for the ACTION rather than a shorter essay — writing the work out
+// is what filled the budget in the first place.
+const TRUNCATED_SIGNAL =
+  "[Internal turn note — this is NOT from the user. Your last message hit the " +
+  "output limit and was cut off mid-way, so nothing in it counted as work.\n" +
+  "Do NOT rewrite or continue that text. If the task needs tools — creating a " +
+  "task, writing a file, sending a message — CALL THEM NOW, one step at a time, " +
+  "and keep any prose to a single short line. Composing the result as text is " +
+  "not the same as doing it.]";
+
+// A turn that WROTE tool results instead of producing them.
+//
+// The shipped example (2026-08-29, Telegram): a fallback model answered with
+// five `[result: shell]` lines — invented commands, invented output — and then
+// "Listo, te mandé el WhatsApp". No tool ran. The user was told a message had
+// been sent to a real phone number that was never sent.
+//
+// Nothing in those lines can be recovered: there is no structured call in them,
+// and reconstructing a shell command from hallucinated prose to run it for real
+// would be a far worse failure than the one it fixes. So the model is told the
+// results are not real and asked to do the work — the same in-band correction
+// the truncation case uses, and for the same reason (weak models answer a
+// conversation turn far more reliably than a system suffix).
+const FABRICATED_RESULTS_SIGNAL =
+  "[Internal turn note — this is NOT from the user. Your last message was " +
+  "written as if tools had run, but you called none, so none of those results " +
+  "exist and nothing you described actually happened.\n" +
+  "Lines like `[tool result: …]` in this conversation are a LOG of past calls. " +
+  "They are not a format for you to write in — writing one does not run " +
+  "anything.\n" +
+  "Do the work now: emit real tool calls, one step at a time. If you cannot " +
+  "(no such tool, missing permission, unclear arguments), say that plainly to " +
+  "the user instead — but never report an action you did not take.]";
+
+// How many times one turn may be corrected for this before we let it end. A
+// model that fabricates twice in a row is not going to start acting on the
+// third try, and the wrap-up still fires.
+const MAX_FABRICATION_RETRIES = 2;
+
 /**
  * Shared tool-calling agent loop used by super-agent and future surfaces.
  */
@@ -136,6 +240,7 @@ export async function runAgent({
   onEvent = null,
   signal,
   onToken = null,
+  onReasoningToken = null,
   agentName = "apx",
   suppressTools = null, // optional list of tool names to remove from the registry
   // Per-reply output cap. Defaults to 512 (tuned for chit-chat + small tool
@@ -165,7 +270,7 @@ export async function runAgent({
   const triedHealth = new Map(
     (routing.tried || []).map((t) => [t.modelId, t.healthy !== false])
   );
-  const retryChain = fallbackModels(globalConfig).filter((m) => {
+  const retryChain = (isFallbackEnabled(globalConfig) ? fallbackModels(globalConfig) : []).filter((m) => {
     if (m === activeModel) return false;
     if (triedHealth.get(m) === false) return false;
     return true;
@@ -183,7 +288,8 @@ export async function runAgent({
   }
 
   // Suppression: callers (notably the routine runner) can disable tools whose
-  // output would duplicate post_commands. We filter the schemas the engine
+  // output would duplicate a sink the run already has — a post_command, or the
+  // routine's own `deliver_to`. We filter the schemas the engine
   // sees AND keep a deny-set so a model that hallucinates a suppressed tool
   // call gets a clear error rather than firing.
   let effectiveSchemas = Array.isArray(suppressTools) && suppressTools.length > 0
@@ -194,7 +300,10 @@ export async function runAgent({
     await emitProgress(onEvent, {
       type: "tools_suppressed",
       tools: [...suppressed],
-      reason: "post_commands_overlap",
+      // Why, generically: a post_command pipes this output somewhere, or the
+      // routine's `deliver_to` does. Either way the sink already owns the
+      // message and the loop must not send a second one.
+      reason: "output_sink_overlap",
     });
   }
   // Completion contract: only meaningful when there are real tools to choose
@@ -228,6 +337,9 @@ export async function runAgent({
     // (In `total` the guard returns early anyway, so this is a no-op there.)
     if (toolHandlerCtx) toolHandlerCtx.securityRiskActive = true;
   }
+  // Telegram (and any other abortable surface) kills in-flight shell tools
+  // when a newer turn supersedes this one. Handlers read it at call time.
+  if (toolHandlerCtx && signal) toolHandlerCtx.abortSignal = signal;
 
   const rawHandlers = makeToolHandlers(toolHandlerCtx);
   const handlers = suppressed.size > 0
@@ -235,7 +347,7 @@ export async function runAgent({
         get(target, name) {
           if (typeof name === "string" && suppressed.has(name)) {
             return async () => ({
-              error: `tool "${name}" is suppressed for this invocation (post_commands already cover this output channel)`,
+              error: `tool "${name}" is suppressed for this invocation (this run already delivers to that channel)`,
             });
           }
           return target[name];
@@ -248,6 +360,40 @@ export async function runAgent({
   // that queue into effectiveSchemas at the top of each iteration, so tools
   // activated on step N are callable from step N+1. No session → no-op.
   const toolSession = toolHandlerCtx?.toolSession || null;
+
+  const schemaOnTheWire = (n) =>
+    effectiveSchemas.some((sc) => (sc?.function?.name || sc?.name) === n);
+
+  /**
+   * A tool the model called WITHOUT ever receiving its schema.
+   *
+   * buildLazyToolsBlock puts the NAMES of not-loaded tools in the system prompt
+   * (that is what makes them discoverable), and not every provider refuses a
+   * call to a tool that was never in the request. So the model can name a real
+   * tool and invent its arguments, and the handler will happily run them:
+   * `complete_task` was called as `{project, id}` — `id` is what list_tasks
+   * hands back, the schema says `task`, and `action` was missing entirely — and
+   * "task required" told the model nothing it could act on. It burned three
+   * iterations and left the task open.
+   *
+   * Activating and returning the schema costs one step and makes the retry
+   * informed. It also closes a gap: the role gate (`allowedTools`) only ever
+   * filtered the schemas the model was SENT, so a guessed name walked straight
+   * past it into the handler map, which holds every tool regardless.
+   */
+  const revealUnloadedTool = (session, name) => {
+    const r = session.activate({ names: [name] });
+    if (r.denied?.length) return { error: `tool "${name}" is not available to you` };
+    if (r.unknown?.length) return { error: `unknown tool: ${name}` };
+    const schema = session.pending.find((sc) => (sc?.function?.name || sc?.name) === name);
+    return {
+      error: `tool "${name}" was not loaded, so you called it without its schema — nothing ran.`,
+      activated: name,
+      schema: schema?.function || schema || null,
+      note: "Ya está cargada. Llamala de nuevo usando exactamente los parámetros de arriba.",
+    };
+  };
+
   const drainPendingTools = () => {
     if (!toolSession || toolSession.pending.length === 0) return;
     const seen = new Set(
@@ -266,22 +412,49 @@ export async function runAgent({
     }
   };
 
-  // Attachments ride on THIS turn's user message. Only images are forwarded to
-  // the model (a multimodal engine renders them; the rest ignore the field);
-  // every other kind is already described in the prompt text by the channel
-  // handler, with its local path, so the agent can reach it with file tools.
+  // Attachments ride on THIS turn's user message. Multimodal engines (Gemini,
+  // Claude, GPT via OpenAI-shaped wire) get the pixels. Text-only engines
+  // (zen:big-pickle and most free Zen models) get a short description from the
+  // vision bridge instead — otherwise the agent only sees "[image attached —
+  // saved to …]" and roleplays that the photo never arrived.
   const turnImages = attachments.filter((a) => a?.data && /^image\//.test(a.mime || ""));
+  let turnPrompt = prompt;
+  let imagesForModel = turnImages;
+  if (turnImages.length && !providerWiresVision(activeModel, globalConfig)) {
+    const description = await describeTurnImages(turnImages, globalConfig, { signal });
+    if (description) {
+      turnPrompt = withImageDescription(prompt, description);
+      await emitProgress(onEvent, {
+        type: "vision_bridged",
+        model: activeModel,
+        images: turnImages.length,
+      });
+      // The description replaces the bytes for this text-only model.
+      imagesForModel = [];
+    }
+    // If the bridge is unavailable, keep the internal image field until the
+    // per-model call adapter replaces it with a safe attachment marker. Raw
+    // bytes still never reach a text-only provider.
+  }
   const conversation = [
     ...previousMessages,
     {
       role: "user",
-      content: prompt,
-      ...(turnImages.length > 0 ? { images: turnImages } : {}),
+      content: turnPrompt,
+      ...(imagesForModel.length > 0 ? { images: imagesForModel } : {}),
     },
   ];
   const trace = [];
   const totalUsage = { input_tokens: 0, output_tokens: 0 };
   let lastText = "";
+  // How much of `maxIters` this run actually spent. Returned so a CALLER that
+  // runs the loop more than once for one turn (the judge loop) can subtract it
+  // from a shared budget instead of handing every round the full number again.
+  // Counted in iterations, not tool calls: one iteration can carry several
+  // parallel calls or none, and iterations are what maxIters is denominated in.
+  // The empty-retry below deliberately rewinds `iter`, so it doesn't count here
+  // either — same rule in both places.
+  let itersUsed = 0;
 
   // Collapse repeated greetings within a single turn. A turn can produce several
   // text segments (pre-tool narration + final answer) and weaker models greet in
@@ -297,6 +470,8 @@ export async function runAgent({
   // the turn empty, and the retry does NOT consume an iteration of the tool
   // budget. Bounded so a model that only ever returns empty can't spin forever.
   let emptyRetries = 0;
+  let lengthContinues = 0;
+  let fabricationRetries = 0;
   const MAX_EMPTY_RETRIES = 2;
   // Side-effect dedupe. Weaker models (Gemini especially) sometimes
   // re-emit the SAME tool call across iterations — e.g. send_telegram
@@ -316,6 +491,13 @@ export async function runAgent({
   const stuckDetector = createStuckDetector(stuckCfg);
   let stuckNudged = false;
   let forceWrapUp = false;
+  // Set when the turn closed on the reserved wrap-up step (budget exhausted, or
+  // stuck-aborted). The wrap-up ASKS the user whether to keep going, so such a
+  // turn is waiting on a person — exactly like ask_questions — not unfinished.
+  // Callers that would otherwise "continue" it (the judge loop) must not, or the
+  // user gets the same recap and the same question again every round without
+  // ever being given the chance to answer it.
+  let endedAwaitingUser = false;
   const safeSig = (v) => {
     try {
       return JSON.stringify(v) ?? "";
@@ -331,8 +513,13 @@ export async function runAgent({
   const tryCallEngine = async (params, { allowRetry = true } = {}) => {
     while (true) {
       try {
-        return await callEngine({ ...params, modelId: activeModel });
+        return await callEngine({
+          ...params,
+          messages: messagesForModel(params.messages, activeModel, globalConfig),
+          modelId: activeModel,
+        });
       } catch (e) {
+        if (signal?.aborted || e?.name === "AbortError") throw e;
         if (!allowRetry || retryChain.length === 0 || !isRetryableEngineError(e)) throw e;
         const nextModel = retryChain.shift();
         await emitProgress(onEvent, {
@@ -350,6 +537,12 @@ export async function runAgent({
   };
 
   for (let iter = 0; iter < maxIters; iter++) {
+    if (signal?.aborted) {
+      const err = new Error("aborted");
+      err.name = "AbortError";
+      throw err;
+    }
+    itersUsed = iter + 1;
     // Merge any tools activated via discover_tools on the previous iteration.
     drainPendingTools();
     // Final iteration of a non-contract turn: the model is out of action steps.
@@ -375,9 +568,14 @@ export async function runAgent({
       effectiveSchemas.length > 0 &&
       (useContract ||
         (ackOnlyStreak > 0 && ackOnlyStreak <= MAX_CONSECUTIVE_ACKS));
+    // Built per iteration, not per turn: the fallback router can rotate
+    // providers mid-turn, and a line that named the model we STARTED on would
+    // be exactly the kind of stale fact this block exists to kill.
+    const runtime = buildRuntimeBlock(activeModel);
+    const systemForCall = runtime ? `${system}\n\n${runtime}` : system;
     const baseSystem = usePseudoTools
-      ? pseudoToolSystem(system, effectiveSchemas)
-      : system;
+      ? pseudoToolSystem(systemForCall, effectiveSchemas)
+      : systemForCall;
     let result;
     try {
       result = await tryCallEngine({
@@ -400,6 +598,7 @@ export async function runAgent({
         maxTokens,
         signal,
         onToken: ((!forceTool || isFinalWrapUp) && onToken) ? onToken : null,
+        onReasoningToken: ((!forceTool || isFinalWrapUp) && onReasoningToken) ? onReasoningToken : null,
       });
     } catch (e) {
       if (usePseudoTools && /^ollama:/i.test(String(activeModel || "")) && /ollama\s+500/i.test(String(e?.message || "")) && trace.length > 0) {
@@ -419,11 +618,24 @@ export async function runAgent({
         maxTokens,
         signal,
         onToken: (iter > 0 && onToken) ? onToken : null,
+        onReasoningToken: (iter > 0 && onReasoningToken) ? onReasoningToken : null,
       });
     }
 
     totalUsage.input_tokens += result.usage?.input_tokens || 0;
     totalUsage.output_tokens += result.usage?.output_tokens || 0;
+
+    // The model thinking out loud. Adapters keep it out of `text` so no
+    // surface can leak it by forgetting to strip; it rides its own event for
+    // the ones that want to show it on purpose, and is ignored by the rest.
+    if (result.reasoning) {
+      await emitProgress(onEvent, {
+        type: "assistant_reasoning",
+        reasoning: result.reasoning,
+        iteration: iter + 1,
+      });
+    }
+
     lastText = result.text || "";
 
     let toolCalls = result.tool_calls || (result.message && result.message.tool_calls) || null;
@@ -455,18 +667,62 @@ export async function runAgent({
     }
 
     if (!toolCalls || toolCalls.length === 0) {
-      lastText = cleanTextOfPseudoToolCalls(lastText, callableNames) || lastText;
+      // Checked BEFORE the cleaner, which is what strips the evidence.
+      const rawText = lastText;
+      const fabricated =
+        effectiveSchemas.length > 0 && looksLikeFabricatedToolLog(rawText);
+      // No `|| rawText` fallback. When the cleaner empties a turn, the turn was
+      // markup end to end — a fabricated tool log, or the `[omitted: …]`
+      // annotation the model copied out of its own history — and putting the
+      // markup back is how a reply that was ONLY that annotation went out to
+      // Telegram verbatim on 2026-09-02, twice. There is no answer in there to
+      // rescue: an empty turn is retried below and then falls to the surface's
+      // never-silent floor, which is a wrap-up written for the user.
+      lastText = cleanTextOfPseudoToolCalls(rawText, callableNames);
       // Dud turn (no tools, no text): re-prompt instead of ending empty, and
       // don't let it cost an iteration of the tool budget. `iter -= 1` cancels
       // the loop's `iter++`; the emptyRetries cap stops an all-empty model from
       // looping forever (after which we break and the surface's last-resort
       // floor sends a non-silent reply).
-      if (!String(lastText).trim() && emptyRetries < MAX_EMPTY_RETRIES) {
+      if (!String(lastText).trim() && !fabricated && emptyRetries < MAX_EMPTY_RETRIES) {
         emptyRetries += 1;
         await emitProgress(onEvent, { type: "empty_retry", iteration: iter + 1, attempt: emptyRetries });
         iter -= 1;
         continue;
       }
+      // It narrated the tools instead of calling them. Do NOT let this text
+      // stand as the answer — it reports work that never happened. The
+      // fabricated turn goes into the history so the model can see what it is
+      // being corrected about, followed by the correction.
+      if (fabricated && fabricationRetries < MAX_FABRICATION_RETRIES) {
+        fabricationRetries += 1;
+        await emitProgress(onEvent, {
+          type: "fabricated_results",
+          model: activeModel,
+          iteration: iter + 1,
+          attempt: fabricationRetries,
+        });
+        conversation.push({ role: "assistant", content: rawText });
+        conversation.push({ role: "user", content: FABRICATED_RESULTS_SIGNAL });
+        continue;
+      }
+      // Cut off at the output cap, not finished. Keep the truncated text in the
+      // history (so the model can see what it was doing) and ask for the action.
+      if (wasTruncated(result) && lengthContinues < MAX_LENGTH_CONTINUES) {
+        lengthContinues += 1;
+        await emitProgress(onEvent, {
+          type: "truncated_continue",
+          iteration: iter + 1,
+          attempt: lengthContinues,
+        });
+        conversation.push({ role: "assistant", content: lastText });
+        conversation.push({ role: "user", content: TRUNCATED_SIGNAL });
+        continue;
+      }
+      // The text we just took as the answer IS the wrap-up: it ends by asking
+      // the user whether to continue. Tell the caller so nobody answers on
+      // their behalf.
+      if (isFinalWrapUp) endedAwaitingUser = true;
       break;
     }
 
@@ -485,6 +741,11 @@ export async function runAgent({
       // next request, avoiding the 400 "missing thought_signature" error.
       // Other engines return undefined here, so this field is a no-op for them.
       ...(result._geminiRawParts ? { _geminiRawParts: result._geminiRawParts } : {}),
+      // Same idea for the OpenAI-shaped reasoners: DeepSeek's thinking mode
+      // rejects a replayed assistant turn that lost its `reasoning_content`.
+      // Stored under an underscore so only the adapters that ask for it put it
+      // back on the wire (see zen.js modelReplaysReasoning).
+      ...(result.reasoning ? { _reasoning: result.reasoning } : {}),
     });
 
     let finishSummary = null;
@@ -521,14 +782,21 @@ export async function runAgent({
         },
         iteration: iter + 1,
       });
-      // Dedupe identical side-effecting calls within this turn.
+      // Dedupe identical side-effecting calls within this turn — and, for the
+      // ones a PERSON reads, calls that only differ in how they were worded.
+      // A model relaying something re-words it every time it repeats itself,
+      // so exact args alone let three "same" messages through (see
+      // loop/side-effects.js).
       const sig = sideEffects.signature(name, args);
-      if (sideEffects.seen(sig)) {
+      const restated = sideEffects.seen(sig) ? null : sideEffects.nearDuplicate(name, args);
+      if (sideEffects.seen(sig) || restated) {
         toolResult = {
           ok: true,
           deduped: true,
-          note: `Ya ejecuté "${name}" con estos mismos argumentos en este turno; no lo repito.`,
-          previous: sideEffects.previous(sig),
+          note: restated
+            ? `Ya dije esto mismo con "${name}" en este turno; no lo repito.`
+            : `Ya ejecuté "${name}" con estos mismos argumentos en este turno; no lo repito.`,
+          previous: restated || sideEffects.previous(sig),
         };
         await emitProgress(onEvent, {
           type: "tool_deduped",
@@ -568,14 +836,35 @@ export async function runAgent({
         } else {
           try {
             const handler = handlers[name];
-            toolResult = handler ? await handler(args) : { error: `unknown tool: ${name}` };
+            if (!handler) toolResult = { error: `unknown tool: ${name}` };
+            // Suppression comes first: a suppressed tool was REMOVED from the
+            // schema set on purpose, and telling the model it merely wasn't
+            // loaded would invite it to activate the tool and send twice.
+            else if (toolSession && !suppressed.has(name) && !schemaOnTheWire(name)) {
+              toolResult = revealUnloadedTool(toolSession, name);
+            }
+            else toolResult = await handler(args);
           } catch (e) {
             toolResult = { error: e.message };
           } finally {
             if (toolHandlerCtx) toolHandlerCtx.securityGateCleared = false;
           }
         }
-        sideEffects.record(sig, summarizeForTrace(toolResult));
+        sideEffects.record(sig, summarizeForTrace(toolResult), { name, args });
+      }
+
+      // A tool may return images for the MODEL to see (view_media loads a skill
+      // photo so the model can reason about a position). Lift them off the
+      // result and onto the tool message as `images`, so the engine sends them
+      // as multimodal parts — and keep the base64 OUT of the trace and the JSON
+      // content the model re-reads as text (a dumped data URI there is both a
+      // token bomb and a worked example of pasting base64 into prose).
+      let toolImages = null;
+      if (toolResult && typeof toolResult === "object" && Array.isArray(toolResult.images)) {
+        const usable = toolResult.images.filter((im) => im && im.data && im.mime);
+        if (usable.length) toolImages = usable;
+        const { images, ...rest } = toolResult;
+        toolResult = { ...rest, ...(toolImages ? { images_attached: toolImages.length } : {}) };
       }
 
       const traceItem = {
@@ -605,6 +894,9 @@ export async function runAgent({
         tool_call_id: tc.id || `synth_${iter}_${trace.length}`,
         tool_name: name,
         content: JSON.stringify(toolResult),
+        // Multimodal tool results (view_media): carried beside the JSON so a
+        // vision engine renders them as inlineData parts. Text engines drop it.
+        ...(toolImages ? { images: toolImages } : {}),
       });
 
       // Capture turn-ending intents (e.g. ask_questions). The loop cannot
@@ -681,5 +973,10 @@ export async function runAgent({
     trace,
     model: activeModel,
     routing,
+    // Iterations of `maxIters` consumed. See itersUsed above.
+    iterations: itersUsed,
+    // True when the turn closed on the reserved wrap-up — it asked the user a
+    // question and the next move is theirs. See endedAwaitingUser above.
+    endedAwaitingUser,
   };
 }