@agentprojectcontext/apx 1.80.2 → 1.89.1

package/src/core/agent/author-line.js

@@ -0,0 +1,110 @@
+// One short line, written by the model instead of written for it.
+//
+// A few messages are the host's to TRIGGER but not to word: the ack after a
+// /reset, the closing of a turn that came back empty. They lived in the i18n
+// dicts as one canned string per case per language — copy that ages in place
+// while the agent's voice moves on, and that has to be re-translated by hand
+// every time a language is added. This asks the model for the line instead.
+//
+// Deliberately NOT a turn: no tools, no history, no persistence, no streaming.
+// One directive in, one line out. It never throws and never blocks for long —
+// an unusable engine, a timeout or an empty answer all come back as "", and the
+// caller falls through to its own floor. That floor is the reason this can be
+// best-effort: nothing here is allowed to be the difference between a reply and
+// silence.
+import { callEngine } from "../engines/index.js";
+import { stripReasoning } from "../util/thinking.js";
+
+/** How long the caller waits for a line it could also do without. */
+export const AUTHOR_LINE_TIMEOUT_MS = 8000;
+
+// The only fixed text left: an instruction to the model, not copy for the user.
+// It says how to write, never what to say — the what is the caller's
+// `instruction`, and the words are the model's.
+const SYSTEM = [
+  "You are the assistant, writing ONE short line to the user in a chat you are already in.",
+  "Write it in the user's language and in your own voice — natural, specific, never a template.",
+  "Plain text only: no markdown, no quotes around it, no preamble, no sign-off.",
+  "Output the line and nothing else.",
+].join("\n");
+
+/**
+ * The most specific language tag the config has. `user.locale` before
+ * `user.language` on purpose: "es" comes back as neutral Spanish, "es-AR" comes
+ * back in voseo — the difference between a line that sounds like the agent and
+ * one that sounds like a translation of it.
+ */
+function languageTag(globalConfig, override) {
+  return String(override || globalConfig?.user?.locale || globalConfig?.user?.language || "").trim();
+}
+
+/** Strip the wrapper a model puts around a line it was asked to produce. */
+function cleanLine(raw) {
+  let s = stripReasoning(String(raw || "")).answer.trim();
+  if (!s) return "";
+  // A fenced block around a one-liner is packaging, not content.
+  s = s.replace(/^```[a-z]*\s*/i, "").replace(/\s*```$/, "").trim();
+  // Same for quotes the model wrapped the whole line in.
+  if (s.length > 1 && /^["'“”«](.|\n)*["'“”»]$/.test(s)) s = s.slice(1, -1).trim();
+  // It was asked for one line; blank lines mean it wrote a note instead.
+  return s.replace(/\n{2,}/g, "\n").trim();
+}
+
+/**
+ * Ask the super-agent's model for a single line.
+ *
+ * @param {object}  o
+ * @param {object}  o.globalConfig  config snapshot (names the model + language)
+ * @param {string}  o.instruction   what the line has to do, addressed to the model
+ * @param {string} [o.model]        write with this model instead of the super-agent's.
+ *                                  A project agent's line is its own to word — it is
+ *                                  the one whose voice the thread is in.
+ * @param {string} [o.context]      what just happened, so the line can be specific
+ * @param {string} [o.lang]         override the tag to write in; defaults to the config's locale
+ * @param {number} [o.maxTokens]
+ * @param {number} [o.timeoutMs]
+ * @param {AbortSignal} [o.signal]  caller's own abort (combined with the timeout)
+ * @param {Function} [o.callEngineFn] injectable for tests
+ * @returns {Promise<string>} the line, or "" when the caller should use its floor
+ */
+export async function authorLine({
+  globalConfig,
+  instruction,
+  model = "",
+  context = "",
+  lang = "",
+  maxTokens = 160,
+  timeoutMs = AUTHOR_LINE_TIMEOUT_MS,
+  signal = null,
+  callEngineFn = callEngine,
+}) {
+  const modelId = model || globalConfig?.super_agent?.model || "";
+  if (!modelId || !instruction) return "";
+
+  const parts = [instruction];
+  if (context) parts.push(context);
+  // A language hint, not a phrasing one: /reset carries no user prose to mirror,
+  // so without this the model answers a bare command in whatever it defaults to.
+  const tag = languageTag(globalConfig, lang);
+  if (tag) parts.push(`Write in this language (BCP-47 tag): ${tag}.`);
+
+  // A line nobody is waiting on must not hold the turn open. The caller's own
+  // abort still wins when it fires first.
+  const timeout = AbortSignal.timeout(Math.max(1000, timeoutMs));
+  const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+
+  try {
+    const r = await callEngineFn({
+      modelId,
+      system: SYSTEM,
+      messages: [{ role: "user", content: parts.join("\n\n") }],
+      config: globalConfig,
+      maxTokens,
+      signal: combined,
+    });
+    return cleanLine(r?.text);
+  } catch {
+    // Engine down, model unknown, timed out, aborted: all the same answer.
+    return "";
+  }
+}

package/src/core/agent/build-agent-system.js

@@ -9,25 +9,24 @@
 import fs from "node:fs";
 import { readAgentMemory } from "./memory.js";
 import { apcProjectFile, apcSkillFile } from "../apc/paths.js";
+import { listField, agentSkills } from "./skills/declared.js";
+import { loadAgentSkills, renderAgentSkillsBlock } from "./skills/agent-skills.js";
 import {
   PROMPTS,
   buildChannelContextBlock,
   buildVoiceModeBlock,
+  buildMobilityModeBlock,
   buildRelationshipBlock,
   buildUserContextBlock,
   buildSegmentDiscipline,
 } from "./prompt-builder.js";
 import { readJson } from "#core/util/json-file.js";
+import { resolveAgentName } from "../identity/self.js";
 
 // Cap the injected agent body so an over-long authored file can't blow the
 // token budget. Mirrors PROJECT_AGENTS_MAX_CHARS for AGENTS.md.
 const AGENT_BODY_MAX_CHARS = 6000;
 
-function listField(value) {
-  if (Array.isArray(value)) return value.map(String).map((s) => s.trim()).filter(Boolean);
-  return String(value || "").split(",").map((s) => s.trim()).filter(Boolean);
-}
-
 function projectName(project) {
   if (project?.name) return project.name;
   try {
@@ -38,9 +37,7 @@ function projectName(project) {
   }
 }
 
-export function agentSkills(agent) {
-  return listField(agent?.fields?.Skills);
-}
+export { agentSkills };
 
 /**
  * Build the system prompt for a project agent.
@@ -103,25 +100,28 @@ export function buildAgentSystem(project, agent, {
   // agents talk through the same surfaces; they need the same formatting rules.
   const channelBlock = buildChannelContextBlock(channel, channelMeta);
   const voiceBlock = buildVoiceModeBlock(voice);
+  const mobilityBlock = buildMobilityModeBlock(!!channelMeta?.mobility);
   const segmentDiscipline = buildSegmentDiscipline({ channel: channelLow, voice });
 
   // Relationship block — "you're talking to <owner>" / "<contact>" / "<guest>".
   const relationship = buildRelationshipBlock(sender);
 
-  // Declared tool hints (informational — actual callables come from runtime).
+  // Declared tool allowlist. The names here are what this agent may call;
+  // the runtime maps catalog aliases (glob, memory_get, …) to native tools.
   const declaredTools = listField(fields.Tools);
   const toolHints = declaredTools.length
     ? [
-        "## Declared tool hints (agent-level expectations)",
+        "## Tools you may call this turn",
         declaredTools.join(", "),
-        "Actual callable tools depend on the invocation surface — use whatever the runtime sends this turn.",
+        "Do not invent tools outside this list. If a needed tool is missing, say so instead of faking the call.",
       ].join("\n")
     : "";
 
   // Invocation context (who called me, through what, for what).
   const invocationCtx = buildInvocationContext({ invocation, runtime, caller, routine });
 
-  // Per-agent memory (lives under <project>/.apc/agents/<slug>/memory.md).
+  // Per-agent memory — ~/.apx/projects/<apx_id>/agents/<slug>/memory.md,
+  // never inside the repo (core/agent/memory.js).
   const memory = readAgentMemory(project, agent.slug);
   const memoryBlock = memory ? "# Memory\n" + memory : "";
 
@@ -129,6 +129,10 @@ export function buildAgentSystem(project, agent, {
   // small and specific to this agent).
   const projectSkills = buildProjectSkills(project, agent);
 
+  // How to reach the owner with something that happens outside this chat. Every
+  // project agent gets it (the super-agent, which IS Roby, never does).
+  const ownerNotice = buildOwnerNoticeProtocol(agent.slug, projectName(project));
+
   return [
     roleBlock,
     profileLines.join("\n"),
@@ -139,9 +143,11 @@ export function buildAgentSystem(project, agent, {
     channelBlock,
     toolHints,
     invocationCtx,
+    ownerNotice,
     projectSkills,
     ...extraParts.filter(Boolean),
     voiceBlock,
+    mobilityBlock,
     PROMPTS.ACTION_DISCIPLINE,
     segmentDiscipline,
   ]
@@ -149,6 +155,35 @@ export function buildAgentSystem(project, agent, {
     .join("\n\n");
 }
 
+/**
+ * The owner-notice protocol. A project agent is NOT the orchestrator: when
+ * something the owner should know happens outside the conversation it is in, it
+ * does not ping the owner's phone itself — it relays to Roby, tagged with an
+ * urgency the owner chose the meaning of. `blocker` reaches them in the act;
+ * `status`/`fyi` wait for the end-of-day digest. This is the same split the
+ * a2a severity contract enforces (core/routines/signals.js).
+ */
+function buildOwnerNoticeProtocol(slug, project) {
+  const proj = project || "<project>";
+  const superName = resolveAgentName() || "Roby";
+  return [
+    "# Reaching the owner",
+    `You are not ${superName} (the super-agent / orchestrator). When something the owner needs to know happens outside`,
+    "the conversation you are in — a routine result, a problem you hit — do NOT message their phone",
+    `yourself. Relay it to ${superName} and let ${superName} decide how and when to tell them:`,
+    "```",
+    `apx send ${slug} default "<one clear line>" --deliver --project ${proj}`,
+    "```",
+    `Tag how urgent it is, so ${superName} knows how fast to surface it:`,
+    "- `--severity blocker` — a critical problem the owner must see NOW. Alerts them in the act,",
+    "  crossing quiet hours and the interruption budget. Use it only for what truly cannot wait.",
+    "- `--severity status` — routine progress or an FYI. Folded into the end-of-day digest, never an",
+    "  interruption. (`fyi` is the same, lowest priority.)",
+    "Always also leave the full detail in your own web chat: the relay is the heads-up, your chat is",
+    "where the owner reads the whole thing and replies.",
+  ].join("\n");
+}
+
 function buildInvocationContext({ invocation, runtime, caller, routine }) {
   const lines = [`## Invocation`, `invocation: ${invocation}`];
   if (runtime) lines.push(`runtime: ${runtime}`);
@@ -177,11 +212,10 @@ function buildProjectSkills(project, agent) {
   if (fs.existsSync(apxSkill)) {
     parts.push("## APX\n" + fs.readFileSync(apxSkill, "utf8").trim());
   }
-  for (const skill of agentSkills(agent)) {
-    const skillPath = apcSkillFile(project.path, skill);
-    if (fs.existsSync(skillPath)) {
-      parts.push(`## Skill: ${skill}\n` + fs.readFileSync(skillPath, "utf8").trim());
-    }
-  }
+  // The agent's declared skills, with progressive disclosure: a small skill is
+  // injected whole, a large one (or one with images) as a card the agent pages
+  // with read_skill / attach_media / view_media. See skills/agent-skills.js.
+  const declared = renderAgentSkillsBlock(loadAgentSkills(project, agent));
+  if (declared) parts.push(declared);
   return parts.join("\n\n");
 }

package/src/core/agent/channels/voice-context.js

@@ -14,7 +14,9 @@
 //   wantsSuggestions — whether the surface can render the trailing
 //                      `suggestions` JSON block (deck/desktop UI can; raw
 //                      Telegram cannot)
-//   channel       — resolved surface ("deck"/"desktop"/"telegram"/…)
+//   channel       — resolved surface ("deck"/"desktop"/"telegram"). A channel
+//                   this file does not recognise resolves to "api", not to
+//                   itself — see the `default` branch for why
 //   channelMeta   — surface metadata (e.g. `{ voice: true }` flags spoken mode)
 import { CHANNELS } from "../../constants/channels.js";
 
@@ -93,6 +95,19 @@ export function buildVoiceChannelContext(channel, { projectId, language = "es" }
     case CHANNELS.TELEGRAM:
       return { ...base, contextNote: dynamicNote, channel: CHANNELS.TELEGRAM, channelMeta: {} };
     default:
-      return { ...base, contextNote: dynamicNote, channel: channel || CHANNELS.API, channelMeta: {} };
+      // An unrecognised channel does NOT pass through. The cases above ARE the
+      // surfaces this pre-processor knows how to shape; a string it does not
+      // recognise is by definition one it can make no claim about, and trusting
+      // it let the CALLER pick a surface's behaviour by naming it. That is a
+      // budget decision, not a label: `channelToolIters` (agent/constants.js)
+      // hands `web`/`web_sidebar` a run-to-completion ceiling because those are
+      // the surfaces a human WATCHES, so POST /voice/turn with
+      // `channel: "web"` would have run a SPOKEN turn uncapped — the opposite
+      // of what a voice answer wants, which is short and fast.
+      //
+      // So an unknown channel falls back to `api`, the bounded default, exactly
+      // as an absent one already did. This keeps the budget keyed on the real
+      // surface: a new one here is one more `case`, added deliberately.
+      return { ...base, contextNote: dynamicNote, channel: CHANNELS.API, channelMeta: {} };
   }
 }

package/src/core/agent/closing-floor.js

@@ -0,0 +1,117 @@
+// The never-silent floor: what a surface says when a turn's closing came back
+// empty.
+//
+// runAgent re-prompts a dud turn (MAX_EMPTY_RETRIES) and then gives up, and the
+// comment where it gives up hands the problem on: "the surface's last-resort
+// floor sends a non-silent reply". Telegram had one. The web did not —
+// `result.text` went out verbatim, so an empty turn rendered as an empty bubble
+// and was written to the thread as an empty assistant row, which is what the
+// NEXT turn reads back as the answer it gave.
+//
+// Two layers, and the order is the whole point:
+//
+//   1. the model writes the closing itself, from what the turn actually did;
+//   2. the canned i18n line goes out ONLY when the model cannot answer either —
+//      usually the same outage that emptied the turn in the first place.
+//
+// Never silent beats never canned, in that order. A turn that DID answer never
+// reaches the floor: it costs a model call, and it must never speak over a real
+// reply.
+import { authorLine } from "./author-line.js";
+import { summarizeToolTrace, formatToolSummary } from "./tool-summary.js";
+import { t, resolveLang } from "#core/i18n/index.js";
+
+// Addressed to the model, not to the user: what the line has to DO. The words
+// are the model's — see author-line.js.
+const INSTRUCTION_WORKED =
+  "You worked on the user's request but the closing message never got written. " +
+  "Write it now: where the work got to, and whether you should keep going if something is left.";
+const INSTRUCTION_NOTHING =
+  "Your reply came back empty. Write the one line that should have gone out — " +
+  "acknowledge them without claiming a result you do not have.";
+
+/**
+ * The line to send when there is no closing text. Callers decide WHEN they are
+ * in that situation (the rules differ per surface — Telegram also treats a
+ * closing that merely repeats the last streamed piece as nothing to send) and
+ * what counts as having worked; this owns what gets said.
+ *
+ * @param {object}   o
+ * @param {object}   o.globalConfig  config snapshot — names the model and the language
+ * @param {string}  [o.model]        write with this model instead of the super-agent's
+ *                                   (a project agent's line is its own to word)
+ * @param {boolean} [o.worked]       did the turn do anything the user saw? Decides
+ *                                   between "here's where it got to" and a bare ack
+ * @param {string}  [o.lastText]     the last thing the turn actually said
+ * @param {object}  [o.toolSummary]  summarizeToolTrace() output, for what it did
+ * @param {Function}[o.authorLineFn] injectable for tests
+ * @returns {Promise<{text: string, authored: boolean}>} `authored` is false when the
+ *          canned floor spoke — worth logging, because it means two model calls
+ *          in a row came back with nothing.
+ */
+export async function closingFloorLine({
+  globalConfig,
+  model = "",
+  worked = false,
+  lastText = "",
+  toolSummary = null,
+  authorLineFn = authorLine,
+}) {
+  const authored = await authorLineFn({
+    globalConfig,
+    ...(model ? { model } : {}),
+    instruction: worked ? INSTRUCTION_WORKED : INSTRUCTION_NOTHING,
+    context: [
+      lastText ? `The last thing you said to them was: ${lastText}` : "",
+      toolSummary ? `What you did this turn: ${formatToolSummary(toolSummary)}` : "",
+    ].filter(Boolean).join("\n"),
+  });
+  const lang = resolveLang(globalConfig);
+  return {
+    text: authored || t(worked ? "reply.fallback_continue" : "reply.fallback_done", { lang }),
+    authored: Boolean(authored),
+  };
+}
+
+/**
+ * The floor as a request/response surface needs it: hand it the turn's reply and
+ * get back the text to send, persist and render.
+ *
+ * A non-empty reply comes back untouched and costs nothing — no model call, no
+ * canned sentence written over an answer the model did give. Only an empty one
+ * is floored, and `floored` says so for the log.
+ *
+ * NOT for an aborted turn. An interruption that wrote nothing is meant to leave
+ * no bubble at all; flooring it would answer a question the user withdrew.
+ *
+ * @param {object}   o
+ * @param {object}   o.globalConfig
+ * @param {string}  [o.model]        the model to write with (a project agent's own)
+ * @param {string}  [o.text]         the turn's reply, as it came back
+ * @param {string}  [o.streamedText] the last text the turn streamed, if any
+ * @param {object[]}[o.trace]        the turn's tool calls
+ * @param {Function}[o.authorLineFn] injectable for tests
+ * @returns {Promise<{text: string, authored: boolean, floored: boolean}>}
+ */
+export async function floorReplyText({
+  globalConfig,
+  model = "",
+  text = "",
+  streamedText = "",
+  trace = [],
+  authorLineFn = authorLine,
+}) {
+  if (String(text || "").trim()) return { text, authored: false, floored: false };
+  const toolSummary = summarizeToolTrace(trace);
+  const { text: line, authored } = await closingFloorLine({
+    globalConfig,
+    model,
+    // On the web the mid-turn prose was already rendered, so "worked" is not a
+    // guess: either the user watched text arrive or a tool ran.
+    worked: Boolean(String(streamedText || "").trim()) || Boolean(toolSummary),
+    lastText: String(streamedText || "").trim(),
+    toolSummary,
+    authorLineFn,
+  });
+  return { text: line, authored, floored: true };
+}

package/src/core/agent/constants.js

@@ -1,3 +1,4 @@
+import { CHANNELS } from "#core/constants/channels.js";
 // Per-turn tool-loop budget for conversational surfaces (telegram/desktop/voice
 // /deck). The LAST of these iterations is reserved by run-agent.js for a
 // tool-free, model-authored wrap-up — so a multi-step task gets ~N-1 action
@@ -5,16 +6,124 @@
 // Coding surfaces (web Code / terminal Build) raise this via maxIters and use
 // the finish-tool completionContract instead.
 export const MAX_TOOL_ITERS = 10;
-// Telegram is the "do real work for me" conversational surface (the super-agent
-// Roby): it needs to chain explore→edit→verify→close autonomously, not stop
-// after ~9 actions and ask "want me to continue?". A budget of 10 left only one
-// usable action step before the reserved wrap-up, so multi-step tasks routinely
-// cut off mid-job. We give it a real autonomy budget (mirroring the TUI Code
-// surface's maxIters:40) while keeping it below the coding surfaces. The
-// reserved final-step wrap-up still applies, but now only fires when a task
-// genuinely exhausts this budget — a rare safety floor, not the default close.
-// Overridable per-deployment via config.super_agent.telegram_max_iters.
-export const TELEGRAM_TOOL_ITERS = 24;
+// Telegram is an owner-controlled work surface too. Its live action notices
+// make long turns observable, so stopping after a small count and asking
+// "should I continue?" is friction rather than a guardrail. This is a runaway
+// backstop: the loop normally ends when work is done, while stuck detection
+// still aborts repeats. Overridable via config.super_agent.telegram_max_iters.
+export const TELEGRAM_TOOL_ITERS = 1000;
+// A background routine that does NOT report to Telegram has no human waiting on
+// a bounded chat turn: nobody is going to read a "want me to keep going?"
+// wrap-up, let alone answer it. Capping such a run at the conversational budget
+// just filed a half-finished record — Magui hitting ~23 steps and stopping
+// mid-backlog. So a non-Telegram routine runs until the work is actually done:
+// the loop already ends on its own the moment the model stops calling tools
+// (run-agent.js), and this high finite ceiling stays only as a runaway backstop.
+// Overridable per-deployment via config.super_agent.routine_max_iters.
+export const ROUTINE_UNCAPPED_TOOL_ITERS = 1000;
+// The web chat — big chat and docked sidebar — is the surface you WATCH: every
+// tool call renders live, streaming survives a refresh, and a person is one
+// click from stopping the turn. The bounded budget exists for the surface where
+// none of that is true. On Telegram a turn scrolls past on a phone with no way
+// to see it going wrong, so stopping to ask IS the guardrail. On web the human
+// is the guardrail, and being asked "want me to keep going?" every 9 actions is
+// pure friction — the whole point of the surface is that it finishes the job.
+//
+// So web runs like a non-Telegram routine: until the work is actually done. The
+// loop already ends on its own the moment the model stops calling tools, stuck
+// detection aborts the repeat-loops, and this ceiling is only the runaway
+// backstop — not a normal stopping point.
+// Overridable per-deployment via config.super_agent.web_max_iters.
+export const WEB_TOOL_ITERS = ROUTINE_UNCAPPED_TOOL_ITERS;
+// A GROUP speaker gets its own number, and this is the one place that says why.
+// A group turn runs the same loop on the same watched surface as the web chat —
+// it streams live and, since the cascade registers in active-turns, Stop reaches
+// it — so by the surface rule above it would inherit WEB_TOOL_ITERS. It used to,
+// by accident: run-group-turn.js passes `channel: WEB` (for the channel PROMPT)
+// and the budget fell out of that string.
+//
+// What the surface rule does not model is the CASCADE. One owner line can
+// produce up to MAX_TURNS_PER_MESSAGE (10, group/turn-resolver.js) agent
+// replies, each a full loop run, so handing every speaker the 1:1 ceiling makes
+// one message worth ten of them — 10x whatever number is written down, which is
+// not a ceiling anybody chose. Same failure the judge rounds had, and the same
+// answer: the budget belongs to the OWNER'S turn, and the runs it fans out into
+// have to fit inside it.
+//
+// So: generous enough for genuine multi-step work (5x the conversational
+// default — a speaker asked to go look something up has real room), small
+// enough that ten of them is still a number picked on purpose. The invariant
+// that keeps it honest, asserted in tests/web-iter-budget.test.js:
+//
+//   GROUP_TOOL_ITERS * MAX_TURNS_PER_MESSAGE <= WEB_TOOL_ITERS
+//
+// — one owner message in a room can never cost more than one owner message in a
+// 1:1 web chat. Raise either factor and that test says so.
+//
+// Exhausting it is not a dead end: the last iteration is the tool-free wrap-up,
+// so the speaker closes with how far it got and the room carries on. A group is
+// a conversation; solo work that genuinely needs hundreds of steps belongs in
+// that agent's own chat, which has the ceiling for it.
+// Overridable per-deployment via config.super_agent.group_max_iters.
+export const GROUP_TOOL_ITERS = 50;
+// ONE TURN, ONE BUDGET. Every number above is the budget for a TURN, not for
+// one pass of the tool loop — and a turn can run the loop more than once, when
+// the completion judge sends it back to finish something (agent/judge.js). Those
+// rounds SHARE the number: each gets what the rounds before it left. Before
+// this, every round was handed the full budget again and nothing summed, so the
+// real ceiling was (1 + judge.max_iterations) × the number written here — 3×1000
+// on web from a single message. That ceiling was never a decision anyone made;
+// it was the product of two settings that didn't know about each other.
+//
+// The alternative was a separate, smaller budget for verification rounds. It was
+// rejected for the reason this comment exists: a second number does not tell you
+// what one turn may spend, it just makes you multiply two numbers instead of
+// one. The budget answers "how many tool steps before we stop and ask the
+// human", and that question is about the turn.
+//
+// The floor below is what a round needs to be worth running: one action step,
+// plus the tool-free closing step run-agent.js reserves. With less than that a
+// round can only produce a "ran out of room" recap — over the top of an answer
+// we already have — so the judge loop stops instead of starting one.
+export const MIN_JUDGE_ROUND_ITERS = 2;
+// The channels WEB_TOOL_ITERS applies to. Coding surfaces (web_code, code) are
+// deliberately absent: they set their own budget alongside the completion
+// contract, and that pairing is what makes them stop on `finish` rather than on
+// a count.
+const RUN_TO_COMPLETION_CHANNELS = new Set([CHANNELS.WEB, CHANNELS.WEB_SIDEBAR]);
+
+/**
+ * Default tool-loop budget for a turn on `channel`, or null when the channel
+ * has no opinion and runAgent's own default should stand. An explicit
+ * `maxIters` from the caller always wins over this.
+ *
+ * Keyed on the SURFACE, not on who is answering: the budget is about whether a
+ * human can watch the turn work, which is just as true of a project agent as it
+ * is of the super-agent. Both reach it — runSuperAgent for Roby, runAgentTurn
+ * for everyone else — because a chat that stops every 9 actions to ask is the
+ * same friction whichever agent is in it.
+ *
+ * Telegram resolves its budget at its own call site (channels/telegram/reply.js)
+ * and routines at theirs (routines/runner.js); this covers the surfaces that
+ * reach the loop through the plain daemon chat routes.
+ */
+export function channelToolIters(config, channel) {
+  if (!RUN_TO_COMPLETION_CHANNELS.has(channel)) return null;
+  const raw = Number(config?.super_agent?.web_max_iters);
+  return Number.isFinite(raw) && raw > 0 ? raw : WEB_TOOL_ITERS;
+}
+
+/**
+ * Tool-loop budget for ONE speaker in a group cascade. Passed as an explicit
+ * `maxIters` by run-group-turn.js rather than resolved from the channel: the
+ * group turn runs on `channel: WEB` so the agent gets the web channel prompt,
+ * and `channelToolIters` must keep meaning what it means for a 1:1 web chat.
+ * See GROUP_TOOL_ITERS for why a room is not simply a watched chat.
+ */
+export function groupToolIters(config) {
+  const raw = Number(config?.super_agent?.group_max_iters);
+  return Number.isFinite(raw) && raw > 0 ? raw : GROUP_TOOL_ITERS;
+}
 // Defined in tools/names.js, next to the names they reference.
 export { ACK_ONLY_TOOLS, TURN_ENDING_TOOLS } from "./tools/names.js";
 export const MAX_CONSECUTIVE_ACKS = 2;
@@ -22,4 +131,3 @@ export const MAX_CONSECUTIVE_ACKS = 2;
 // tool runs we break the loop — even under completionContract — because the
 // task literally cannot advance without a human reply. Without this, models
 // under forced toolChoice spam the same question across iterations.
-

package/src/core/agent/engine-call.js

@@ -0,0 +1,56 @@
+// One-shot engine calls that survive a bad minute.
+//
+// The agent loop has always walked a fallback chain: a 429 or a 5xx rotates to
+// the next model and the turn continues. Every OTHER caller went straight to
+// callEngine with a single model id and no chain, so the same rate limit that
+// the super-agent shrugged off ended a delegated call outright — "how can it
+// rate-limit her if it doesn't rate-limit him" has a boring answer, and this is
+// it. `call_agent` was the one that showed: Roby delegates to a project agent,
+// Zen answers 429, and the sub-call dies while Roby's own turn would have moved
+// to Gemini without saying a word.
+//
+// Same classifier as the loop (retry.js), same chain (model-router.js), so the
+// two agree about what "retryable" means and which model comes next.
+import { callEngine } from "../engines/index.js";
+import { fallbackModels, isFallbackEnabled } from "./model-router.js";
+import { messagesForModel } from "./model-capabilities.js";
+import { isRetryableEngineError, shortRetryReason } from "./retry.js";
+
+/**
+ * callEngine, walking the configured fallback chain on retryable failures.
+ *
+ * @param {object} params        forwarded to callEngine (minus modelId)
+ * @param {string} params.modelId the model to try first
+ * @param {object} params.config  global/project config; supplies the chain
+ * @param {(ev:{model:string,reason:string,retry_with:string})=>void} [onRotate]
+ *        called before each rotation, so a caller can log why the model changed
+ * @returns {Promise<object>} the engine result, plus `model` — the one that
+ *          actually answered, which is not always the one that was asked.
+ */
+export async function callEngineWithFallback({ modelId, config, ...rest }, { onRotate } = {}) {
+  const chain = isFallbackEnabled(config)
+    ? fallbackModels(config).filter((m) => m && m !== modelId)
+    : [];
+  let active = modelId;
+  for (;;) {
+    try {
+      const out = await callEngine({
+        ...rest,
+        messages: messagesForModel(rest.messages, active, config),
+        config,
+        modelId: active,
+      });
+      return { ...out, model: active };
+    } catch (e) {
+      if (e?.name === "AbortError" || rest.signal?.aborted) throw e;
+      if (!chain.length || !isRetryableEngineError(e)) throw e;
+      const next = chain.shift();
+      try {
+        onRotate?.({ model: active, reason: shortRetryReason(e), retry_with: next });
+      } catch {
+        /* logging must not break the call */
+      }
+      active = next;
+    }
+  }
+}