mixdog 1.3.0 → 1.3.1

package/src/runtime/agent/orchestrator/providers/provider-error-kind.mjs

@@ -335,8 +335,19 @@ const CODE_KINDS = new Map(
     quota_exhausted: ['quota_exceeded', 'quota_exhausted', 'usage_limit_reached', 'provider_accounts_exhausted'],
     context_overflow: ['context_length_exceeded', 'context_window_exceeded', 'model_context_window_exceeded'],
     request_too_large: ['request_too_large', 'payload_too_large', 'request_entity_too_large'],
-    auth: ['invalid_api_key', 'authentication_error', 'unauthenticated', 'unauthorized', 'invalid_authentication'],
-    permission: ['permission_error', 'permission_denied', 'forbidden'],
+    // Google names a rejected or expired key with an ErrorInfo reason on an
+    // INVALID_ARGUMENT 400; the reason outranks the envelope status.
+    auth: [
+      'invalid_api_key',
+      'authentication_error',
+      'unauthenticated',
+      'unauthorized',
+      'invalid_authentication',
+      'api_key_invalid',
+      'api_key_expired',
+      'access_token_expired',
+    ],
+    permission: ['permission_error', 'permission_denied', 'forbidden', 'service_disabled', 'api_key_service_blocked'],
     overloaded: [
       'server_is_overloaded',
       'overloaded_error',
@@ -374,6 +385,7 @@ const CODE_KINDS = new Map(
       'not_found',
       'not_found_error',
       'model_not_found',
+      'model_not_supported',
       'unsupported_parameter',
     ],
   }).flatMap(([kind, codes]) => codes.map((code) => [code, kind]))

package/src/runtime/agent/orchestrator/providers/retry-executor.mjs

@@ -150,6 +150,13 @@ function isOverloadFailure(status, errorKind) {
   return status === 529 || errorKind === 'overloaded';
 }
 
+function exceedsAdviceCeiling(caught, opts) {
+  const ceiling = Number(opts.maxRetryAfterMs);
+  if (!(ceiling > 0)) return false;
+  const advised = retryAfterMsFromError(caught);
+  return advised != null && advised > ceiling;
+}
+
 // Decides whether `caught` may be re-issued: returns the error to throw (the
 // caught one, the exhausted-marked one on the last attempt, or the model
 // fallback trigger) or null when the next attempt may run — and only then
@@ -206,6 +213,16 @@ function retryVerdict(caught, { opts, attempt, maxAttempts, state }) {
     const typedQuota = QUOTA_KINDS.has(providerErrorKind(caught, { quotaFlags: false }).kind);
     if (typedQuota || opts.retry429 === false || status !== 429) return caught;
   }
+  // Opt-in `maxRetryAfterMs`: a server wait longer than the caller will sit
+  // through is a lock-out, not a retry. It surfaces now (with its advice for
+  // the notice and the account pool) instead of parking the send for it.
+  if (exceedsAdviceCeiling(caught, opts)) {
+    return markProviderRecoveryExhausted(caught, {
+      owner: opts.recoveryOwner || 'withRetry',
+      attempts: attempt + 1,
+      terminal: true,
+    });
+  }
   // Background calls (titles and the like) never retry an overload: during a
   // capacity cascade every retry multiplies gateway load, and nobody is
   // waiting on the result.

package/src/runtime/agent/orchestrator/runtime-core/orchestration.mjs

@@ -23,9 +23,11 @@ tool and brief each agent as the Lead rules describe.`;
 export const AGENT_MODE_DELEGATION = `# Delegation
 
 Handle conversation yourself. Delegate specialised work to sub-agents. Hand
-substantial coding to a new coding-mode task session (\`session create\`) with
+substantial coding to a new agent task session (\`session create\`) with
 a self-contained brief: start it when already requested, otherwise suggest it. Then relay the
-result in your own words.`;
+result in your own words. Work sent to an existing session (\`session send\`)
+reports back only when its result says reportsBack: true; promise to report
+only then.`;
 
 /** Mixy only: it also routes requests to the user's contact agents. */
 export const MIXY_CONTACTS_INTRO = `You also coordinate the user's contact agents: route a request to the

package/src/runtime/agent/orchestrator/runtime-core/tool-defs.mjs

@@ -73,9 +73,9 @@ export const SESSION_TOOL = {
     openWorldHint: false,
     agentHidden: true,
   },
-  trigger: 'Session lookup/control, coding task sessions, title, compact, fork, Project and worktrees.',
+  trigger: 'Session lookup/control, agent task sessions, title, compact, fork, Project and worktrees.',
   description:
-    'Inspect sessions or control another by exact ID, never a guessed one. send acknowledges queue intake, not completion. Cancel/delete and worktree actions require the user’s request. Other actions affect only the current session.',
+    'Inspect sessions or control another by exact ID, never a guessed one. send acknowledges queue intake, not completion; promise a report of it only when its result has reportsBack: true. Cancel/delete and worktree actions require the user’s request. Other actions affect only the current session. Pass files on with attachments; a reported turn returns the files it produced as attachments.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -102,7 +102,7 @@ export const SESSION_TOOL = {
           'prune-worktrees',
         ],
         description:
-          'status defaults to current; list pages sessions; read returns latest items; send queues prompt; cancel stops the turn; delete removes the session. create (agent conversations) starts a visible coding task session from brief and reports its turns back; unknown Project: list-projects first, still ambiguous: ask the user. compact runs after this turn; fork copies it without switching. merge-worktree merges into the Project’s checked-out branch; remove-worktree returns to the Project (repeat on WORKTREE_REMOVAL_INCOMPLETE); list-worktrees includes retaining sessions; prune-worktrees removes only clean, merged, unretained worktrees.',
+          'status defaults to current; list pages sessions; read returns latest items; send queues prompt (reportsBack: the turn result reports back here); cancel stops the turn; delete removes the session. create (bot conversations) starts a visible agent task session from brief and reports its turns back; unknown Project: list-projects first, still ambiguous: ask the user. compact runs after this turn; fork copies it without switching. merge-worktree merges into the Project’s checked-out branch; remove-worktree returns to the Project (repeat on WORKTREE_REMOVAL_INCOMPLETE); list-worktrees includes retaining sessions; prune-worktrees removes only clean, merged, unretained worktrees.',
       },
       title: { type: 'string', description: 'rename: new current-session title; create: task title.' },
       session_id: {
@@ -147,8 +147,18 @@ export const SESSION_TOOL = {
       value: { type: 'boolean', description: 'favorite/archive: on or off.' },
       brief: { type: 'string', description: 'create: self-contained instruction, the first message.' },
       project: { type: 'string', description: 'create: registered Project name or existing directory.' },
-      model: { type: 'string', description: 'create: provider/model or preset; default route otherwise.' },
+      model: {
+        type: 'string',
+        description: 'create: provider/model or preset; default is the Lead model (else the last-used one).',
+      },
       notify: { type: 'boolean', description: 'create: report results back, default true.' },
+      attachments: {
+        type: 'array',
+        items: { type: 'string' },
+        maxItems: 8,
+        description:
+          'send/create: files the target turn receives as real attachments (images, PDF/Office, text): an attachment of this conversation by its file name (a user upload, e.g. its [Image: source: name]) or id (a reported file’s [attachment:id]), or a file path inside this session’s folders. Secret files are refused.',
+      },
     },
     additionalProperties: false,
   },

package/src/runtime/agent/orchestrator/runtime-core/workflow/agents.mjs

@@ -9,6 +9,15 @@ import { readJsonSafe, readTextSafe } from '../fs-utils.mjs';
 import { SHARED_SCAN_REVALIDATE_MS, createSharedScanCache } from './shared-scan-cache.mjs';
 import { isHiddenAgent } from '../../internal-agents.mjs';
 import { isAgentDisabled } from '../../../../shared/agent-route-config.mjs';
+import { agentDefinitionKind } from '../../../../shared/agent-kind.mjs';
+import {
+  BOTS_DIR,
+  MIXY_BOT_ID,
+  botStoreActive,
+  isStoreBot,
+  migratedBotIds,
+  userDefinitionDir,
+} from '../../../../shared/agent-store.mjs';
 import {
   AGENT_DELETED_MARKER,
   AGENT_ROLE_IDS,
@@ -21,17 +30,22 @@ import {
   setAgentDefinitionCache,
 } from '../workflow-ids.mjs';
 
-// Yields its fs requests; see shared-scan-cache.mjs.
-function* scanCustomAgentIds(userRoot, shippedRoot) {
+// Yields its fs requests; see shared-scan-cache.mjs. With the bot store
+// active, bots/ is scanned too and the agents/ originals of the ids the split
+// copied are skipped (agent-store.mjs).
+function* scanCustomAgentIds(userRoot, shippedRoot, botsRoot = null, migrated = new Set()) {
   const ids = new Set();
-  for (const root of [userRoot, shippedRoot]) {
+  for (const root of [...(botsRoot ? [botsRoot] : []), userRoot, shippedRoot]) {
     const entries = yield { op: 'readdir', path: root };
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
       const id = normalizeWorkflowId(entry.name);
-      // `lead` is Mixy's own folder (PERSONA.md, AGENT.md), never an agent.
+      // `lead` is the Lead's own folder, `mixy` Mixy's: neither is an agent.
       if (!id || id === 'lead' || AGENT_ROLE_IDS.has(id) || isHiddenAgent(id)) continue;
-      if (root !== userRoot && (yield { op: 'exists', path: join(userRoot, id, AGENT_DELETED_MARKER) })) continue;
+      if (root === botsRoot && id === MIXY_BOT_ID) continue;
+      if (root === userRoot && migrated.has(id)) continue;
+      if (root === botsRoot && entry.name !== id) continue;
+      if (root === shippedRoot && (yield { op: 'exists', path: join(userRoot, id, AGENT_DELETED_MARKER) })) continue;
       if (!(yield { op: 'exists', path: join(root, entry.name, 'AGENT.md') })) continue;
       ids.add(id);
     }
@@ -57,15 +71,24 @@ const agentListCache = createSharedScanCache();
 
 export function createWorkflowAgents({ rootDir, dataDir, readMarkdownDocument, normalizeAgentPermissionOrNone }) {
   function agentSourceDirs(dir, id) {
+    // A store bot reads only its own folder (agent-store.mjs).
+    if (isStoreBot(dir || dataDir, id)) return [userDefinitionDir(dir || dataDir, id)];
     const userDir = join(dir || dataDir, 'agents', id);
     if (existsSync(join(userDir, AGENT_DELETED_MARKER))) return [userDir];
     return [userDir, join(rootDir, 'agents', id)];
   }
 
   function agentScan(dir) {
-    const userRoot = join(dir || dataDir, 'agents');
+    const base = dir || dataDir;
+    const userRoot = join(base, 'agents');
     const shippedRoot = join(rootDir, 'agents');
-    return { key: `${userRoot}\n${shippedRoot}`, makeScan: () => scanCustomAgentIds(userRoot, shippedRoot) };
+    const store = botStoreActive(base);
+    const migrated = store ? migratedBotIds(base) : new Set();
+    const botsRoot = store ? join(base, BOTS_DIR) : null;
+    return {
+      key: `${userRoot}\n${shippedRoot}\n${botsRoot || ''}\n${[...migrated].join(',')}`,
+      makeScan: () => scanCustomAgentIds(userRoot, shippedRoot, botsRoot, migrated),
+    };
   }
 
   function listCustomAgentIds(dir) {
@@ -101,6 +124,13 @@ export function createWorkflowAgents({ rootDir, dataDir, readMarkdownDocument, n
         description: clean(manifest.description) || slot?.description || '',
         permission: normalizeAgentPermissionOrNone(doc.frontmatter.permission),
         frontmatter: doc.frontmatter,
+        // bot | agent | null, decided read-only (shared/agent-kind.mjs).
+        kind: agentDefinitionKind({
+          frontmatterKind: doc.frontmatter.kind,
+          ...(d !== join(rootDir, 'agents', agentId)
+            ? { dataDir: dir || dataDir, shippedRoot: rootDir, id: agentId, manifest, body }
+            : {}),
+        }),
         body,
         // Optional PERSONA.md beside AGENT.md (same dir, same cache entry).
         persona: (readTextSafe(join(d, 'PERSONA.md')) || '').trim(),

package/src/runtime/agent/orchestrator/runtime-core/workflow/context.mjs

@@ -63,16 +63,18 @@ export function createWorkflowContext({ packs, agents }) {
   function leadPromptParts(config, dir, { agentMode = false, mixy = false } = {}) {
     const mode = configuredOrchestrationMode(config);
     const ids = agents.delegatableAgentIds(config, dir);
+    const isContact = (id) => isContactAgentId(id, agents.loadAgentDefinition(dir, id)?.kind);
     if (!agentMode) {
-      const catalog = agentCatalog(dir, ids);
+      // Bots are never a coding Lead's agents: only Mixy hands them work.
+      const workflowIds = ids.filter((id) => !isContact(id));
+      const catalog = agentCatalog(dir, workflowIds);
       return {
         // Solo without agents has nothing to delegate to on request either.
-        orchestrationContext: mode === 'none' && !ids.length ? '' : orchestrationInstructions(mode),
+        orchestrationContext: mode === 'none' && !workflowIds.length ? '' : orchestrationInstructions(mode),
         agentCatalogContext: catalog ? `# Available Agents\n\n${catalog}` : '',
         contactCatalogContext: '',
       };
     }
-    const isContact = (id) => isContactAgentId(id, agents.loadAgentDefinition(dir, id)?.frontmatter?.kind);
     const subAgents = agentCatalog(
       dir,
       ids.filter((id) => !isContact(id))

package/src/runtime/agent/orchestrator/session/agent-room.d.mts

@@ -29,6 +29,10 @@ export interface RoomRow {
   /** Host → log only: a user row's files as the composer sent them, which the
    *  log's intake stores (agent-room-delivery.mjs) and replaces with the above. */
   upload?: { parts: unknown[]; pastedImages?: Record<string, unknown>; pastedTexts?: Record<string, unknown> };
+  /** Host → log only: a speech row's member session and the start of the
+   *  turn that spoke; the log's intake stores the files that turn produced
+   *  (agent-room-delivery.mjs) as the row's `parts` / `attachments`. */
+  artifactsFrom?: { sessionId: string; since: number };
   text: string;
 }
 /** A stored file reference (attachments/store.mjs): an image, a file, or an

package/src/runtime/agent/orchestrator/session/agent-room.mjs

@@ -6,9 +6,10 @@
 // (`sess_rmem_<room>_<agent>`) and is handed only the rows new since it last
 // spoke. What another agent said reaches a member as DATA inside an explicit
 // boundary, with every harness tag escaped and every line relabelled, so a peer
-// can never forge a control frame or pose as the user. Files come only with the
-// user's own rows: stored references, handed as content to the members the
-// message reaches, once each.
+// can never forge a control frame or pose as the user. Files come with the
+// user's own rows and with a member's speech (the files its turn produced,
+// session-runtime/handoff-attachments.mjs): stored references, handed as
+// content to the members the row reaches, once each.
 import { escapeHarnessTags } from '../../../shared/shell-output-summary.mjs';
 import { normalizeMessageAttachments, transcriptAttachmentFields } from '../../../shared/transcript-metadata.mjs';
 import { agentHomeSessionId } from './agent-home.mjs';
@@ -465,6 +466,12 @@ export function roomTurnPrompt({
       if (shareTools) {
         for (const tool of row.tools || []) lines.push(...peerLines(`(tool ${label(tool.name)}) ${tool.summary}`));
       }
+      // The files this member's turn produced follow its words, still data.
+      const files = storedParts(row.parts);
+      if (files.length) {
+        lines.push(...peerLines(`(files from ${label(row.name || row.speaker)} follow)`));
+        content.push({ type: 'text', text: lines.splice(0).join('\n') }, ...files);
+      }
       continue;
     }
     if (open) lines.push('</room-transcript>');
@@ -547,9 +554,11 @@ export function normalizeRoomRow(row = {}) {
     .map((target) => ({ id: cleanName(target.id), name: cleanName(target.name) }))
     .filter((target, index, list) => target.id && list.findIndex((other) => other.id === target.id) === index)
     .slice(0, ROOM_MAX_MEMBERS);
-  // Files are the user's alone: what the log's intake stored for the row.
-  const parts = row.kind === 'user' ? storedParts(row.parts) : [];
-  const attachments = row.kind === 'user' ? normalizeMessageAttachments(row.attachments) : [];
+  // Files are the user's uploads or the files a member's turn produced: what
+  // the log's intake stored for the row.
+  const carriesFiles = row.kind === 'user' || row.kind === 'speech';
+  const parts = carriesFiles ? storedParts(row.parts) : [];
+  const attachments = carriesFiles ? normalizeMessageAttachments(row.attachments) : [];
   const images = row.kind === 'user' ? storedImages(row.images) : [];
   return {
     id,
@@ -623,8 +632,8 @@ export function roomRowItem(message, id) {
     room: { ...room, id: messageId },
     ...(messageId ? { messageId } : {}),
     ...(Number.isFinite(at) ? { at } : {}),
-    // A user row's files, in the fields a chat prompt's row draws them from.
-    ...(room.kind === 'user' ? transcriptAttachmentFields(message.meta.transcript) : {}),
+    // A user row's (or member speech's) files, in the fields a chat prompt's row draws them from.
+    ...(room.kind === 'user' || room.kind === 'speech' ? transcriptAttachmentFields(message.meta.transcript) : {}),
     ...(room.kind === 'user' && Array.isArray(images) && images.length ? { images } : {}),
   };
 }

package/src/runtime/agent/orchestrator/session/human-gate/gate.mjs

@@ -5,13 +5,18 @@
 // turns an outbound call (outbound-policy.mjs) into an `ask` whatever the
 // hooks or the agent's permission said short of a deny, unless the agent's
 // permission for that action kind (store.mjs) is `allow`; `block` denies it
-// without a card. Other surfaces (group rooms) call it with their own
+// without a card. The outbound rule applies ONLY while a bot acts (see
+// actingBotId); an ordinary coding session's outbound call passes with the
+// hook decision unchanged. Other surfaces (group rooms) call it with their own
 // decision to get the same outbound rule. After the user answered,
 // recordHumanDecision stores a "don't ask again" grant and the audit line. Unattended runs (schedule, webhook, room member) register a
 // port here (session-runtime/held-requests.mjs) that turns their asks into
 // held requests instead of an approval card.
 import { MIXY_AGENT_ID, agentIdOfHomeSession } from '../agent-home.mjs';
 import { serverConnector } from '../../mcp/server-connectors.mjs';
+import { readAgentDefinitionKind } from '../../../../shared/agent-kind.mjs';
+import { isContactAgentId } from '../../../../shared/agent-route-config.mjs';
+import { mixdogRoot, resolvePluginData } from '../../../../shared/plugin-paths.mjs';
 import { roomMemberOfSession } from '../agent-room.mjs';
 import { classifyOutboundCall, isRememberableAction } from './outbound-policy.mjs';
 import { humanGateStore } from './store.mjs';
@@ -33,12 +38,33 @@ export function unattendedApprovalPort() {
   return unattendedPort;
 }
 
+/** The agent a session is bound to: its unattended run's owner, a room
+ *  member, a home thread's agent; '' for any other (coding) session. */
+function boundAgentId(sessionId) {
+  const run = unattendedPort?.runOf?.(sessionId);
+  if (run?.agentId) return run.agentId;
+  return roomMemberOfSession(sessionId)?.agentId || agentIdOfHomeSession(sessionId) || '';
+}
+
 /** The agent a session acts for: its unattended run's owner, a room member,
  *  a home thread's agent, else Mixy. */
 export function agentIdForSession(sessionId) {
-  const run = unattendedPort?.runOf?.(sessionId);
-  if (run?.agentId) return run.agentId;
-  return roomMemberOfSession(sessionId)?.agentId || agentIdOfHomeSession(sessionId) || MIXY_AGENT_ID;
+  return boundAgentId(sessionId) || MIXY_AGENT_ID;
+}
+
+/** The bot a session acts for, or '' when none: Mixy in her own home thread
+ *  (or her unattended run / room member session), or a contact agent (`kind:
+ *  bot`, isContactAgentId) in its home thread, room member session or
+ *  unattended run. A coding Lead (also id 'lead'), its workflow agents and
+ *  their sub-agent sessions are bound to nothing here, so they are no bot.
+ *  A sub-agent of a bot has its own session id and no link back to the
+ *  caller in this layer, so it is not gated either. */
+function actingBotId(sessionId) {
+  const id = boundAgentId(sessionId);
+  if (!id) return '';
+  if (id === MIXY_AGENT_ID) return id;
+  const kind = readAgentDefinitionKind({ dataDir: resolvePluginData(), shippedRoot: mixdogRoot(), id });
+  return isContactAgentId(id, kind) ? id : '';
 }
 
 const actionOf = (decision) => String(decision?.action || decision?.decision || '').toLowerCase();
@@ -97,7 +123,8 @@ export async function humanGateDecision(call, decision, ctx = {}) {
   if (action === 'deny' || action === 'block') return { decision, request: null, gate: null };
   const agentId = agentIdForSession(ctx.sessionId);
   const annotations = ctx.annotations ?? (await mcpAnnotations(call?.name, ctx.mcpScopeId));
-  const outbound = classifyOutboundCall({ name: call?.name, args: call?.args, annotations });
+  const classified = classifyOutboundCall({ name: call?.name, args: call?.args, annotations });
+  const outbound = classified && actingBotId(ctx.sessionId) ? classified : null;
   if (!outbound) {
     if (action !== 'ask') return { decision, request: null, gate: null };
     return {

package/src/runtime/agent/orchestrator/session/loop/loop-state.mjs

@@ -8,6 +8,7 @@ import { resolveLiveToolCwd } from './tool-exec.mjs';
 import { createSteeringDrain } from './steering.mjs';
 import { createNoToolTurnResolver } from './no-tool-turn.mjs';
 import { classifyTerminationReason } from './termination.mjs';
+import { routeUsageSegments } from './usage.mjs';
 
 // Consecutive identical-AND-failing tool calls (same name+args, error result)
 // tolerated across iterations before the loop refuses to re-execute and steers
@@ -153,5 +154,13 @@ export function finishLoop(state) {
     providerStateUpdated: state.providerStateUpdated,
     terminationReason: classifyTerminationReason(response, { sessionAgent: state.sessionAgent }),
     providerContinuations: state.noToolTurn.providerContinuations,
+    ...(state.routeUsageHops?.length
+      ? {
+          usageSegments: routeUsageSegments(state.routeUsageHops, state.lastUsage, {
+            provider: state.sessionRef?.provider,
+            model: state.sessionRef?.model,
+          }),
+        }
+      : {}),
   };
 }

package/src/runtime/agent/orchestrator/session/loop/route-fallback.mjs

@@ -1,4 +1,7 @@
-import { canFallbackRoute } from '../../../../shared/model-route-fallback.mjs';
+import { routeFallbackVerdict } from '../../../../shared/model-route-fallback.mjs';
+import { providerErrorKind } from '../../providers/provider-error-kind.mjs';
+import { displayModelName } from '../../../../shared/model-display.mjs';
+import { presentErrorText } from '../../../../shared/err-text.mjs';
 import { getProvider, initProviders } from '../../providers/registry.mjs';
 import { loadConfig } from '../../config.mjs';
 import { ensureProviderEnabled } from '../../runtime-core/config-helpers.mjs';
@@ -7,19 +10,107 @@ import { pinSessionWireRoute } from '../../providers/wire-route.mjs';
 import { buildRequestSendOptions } from '../manager/ask-turn-loop-options.mjs';
 import { prepareTurnEffortConfiguration } from '../../providers/effort-configuration.mjs';
 import { resolveSessionContextMeta } from '../manager/context-meta.mjs';
+import { stripProviderReplayMessages } from '../manager/provider-replay.mjs';
+
+// The short reason a notice gives for leaving a model, by provider kind.
+const HOP_REASONS = {
+  quota_exhausted: 'usage limit reached',
+  entitlement: 'not included in the plan',
+  billing: 'out of credits',
+  rate_limited: 'rate-limited',
+  overloaded: 'unavailable',
+  transient: 'unavailable',
+  service_tier_unavailable: 'unavailable',
+  auth: 'sign-in failed',
+  permission: 'access denied',
+  invalid_request: 'model not available',
+  context_overflow: 'context too long',
+};
+
+const routeLabel = (route) => displayModelName(route.model, route.provider) || `${route.provider}/${route.model}`;
+
+/** The muted transcript line for a hop: `<from> <reason> — switched to <to>.` */
+export function routeFallbackNoticeText(from, to, error) {
+  const reason = HOP_REASONS[providerErrorKind(error).kind] || 'unavailable';
+  return `${routeLabel(from)} ${reason} — switched to ${routeLabel(to)}.`;
+}
+
+function routeFailure(route, error) {
+  return {
+    provider: route.provider,
+    model: route.model,
+    kind: providerErrorKind(error).kind,
+    error: presentErrorText(error),
+  };
+}
+
+// The chain ended after at least one hop: the final error keeps its own kind
+// and names every model that was tried and why each failed. `skipped` is the
+// next route when the chain stopped before it (a context overflow whose next
+// window is no larger), so the text says why instead of "every model failed".
+function annotateEndedChain(session, error, skipped = null) {
+  const tried = session?.routeFallbackFailures;
+  if (!tried?.length || !error || typeof error !== 'object' || error.routeFallbackAttempts) return;
+  const attempts = [...tried, routeFailure(session, error)];
+  try {
+    error.routeFallbackAttempts = attempts;
+    const lines = attempts.map((attempt) => `${routeLabel(attempt)}: ${attempt.error}`).join('; ');
+    const head = skipped
+      ? `Fallback chain stopped before ${routeLabel(skipped)} (its context window is not larger) — tried`
+      : 'Every model in the fallback chain failed —';
+    error.message = `${error.message}\n${head} ${lines}`;
+    if (skipped) error.routeFallbackStoppedBefore = { provider: skipped.provider, model: skipped.model };
+  } catch {
+    /* frozen errors keep their own message */
+  }
+}
+
+// A context overflow moves only to a model whose window is larger.
+async function nextContextGrows(state, next) {
+  const config = ensureProviderEnabled(loadConfig(), next.provider);
+  await initProviders(config.providers, { signal: state.signal });
+  state.throwIfAborted();
+  const provider = getProvider(next.provider);
+  if (!provider) return false;
+  const current = resolveSessionContextMeta(state.provider, state.sessionRef.model, state.sessionRef).rawContextWindow;
+  const window = resolveSessionContextMeta(provider, next.model, next).rawContextWindow;
+  return Number(window) > Number(current || state.sessionRef.selectedContextWindow || 0);
+}
 
 export async function advanceAgentRoute(state, error) {
   const session = state.sessionRef;
-  const index = session?.routeFallbackIndex || 0;
-  const next = session?.routeFallbacks?.[index];
-  const committed = state.toolCallsTotal > 0 || state.response != null;
-  if (!session?.agent || !next || !canFallbackRoute(error, { signal: state.signal, committed })) return false;
+  if (!session?.agent || !session.routeFallbacks?.length) return false;
+  const index = session.routeFallbackIndex || 0;
+  const next = session.routeFallbacks[index];
+  // Only THIS request must have produced nothing (its stream outcome says so):
+  // earlier requests of the turn may have run tools. Their calls and results
+  // are already in the live turn, which the next model continues from, so no
+  // completed tool runs again.
+  const verdict = routeFallbackVerdict(error, { signal: state.signal });
+  const hops = verdict === 'hop' || (verdict === 'context' && next && (await nextContextGrows(state, next)));
+  if (!next || !hops) {
+    if (verdict !== 'stay') annotateEndedChain(session, error, next || null);
+    return false;
+  }
   state.throwIfAborted();
   const config = ensureProviderEnabled(loadConfig(), next.provider);
   await initProviders(config.providers, { signal: state.signal });
   state.throwIfAborted();
   const provider = getProvider(next.provider);
   if (!provider) throw new Error(`Provider "${next.provider}" not available`);
+  const failed = routeFailure(session, error);
+  // The left model's share of the turn ends here: the running total at the
+  // switch bounds it, so each model's tokens are booked at its own rates.
+  state.routeUsageHops = [
+    ...(state.routeUsageHops || []),
+    { provider: session.provider, model: session.model, usage: state.lastUsage ? { ...state.lastUsage } : null },
+  ];
+  const notice = routeFallbackNoticeText(session, next, error);
+  // Saved with the new route: a crash before the live turn is checkpointed
+  // again recovers that turn without the previous provider's native state.
+  if (session.activeTurnCheckpoint && typeof session.activeTurnCheckpoint === 'object') {
+    session.activeTurnCheckpoint = { ...session.activeTurnCheckpoint, routeChanged: true };
+  }
   const oldOptions = buildRequestSendOptions({
     sessionId: state.sessionId,
     session,
@@ -41,9 +132,12 @@ export async function advanceAgentRoute(state, error) {
   );
   if (!updated) throw new Error('agent session closed during model fallback');
   updated.routeFallbackIndex = index + 1;
+  updated.routeFallbackFailures = [...(session.routeFallbackFailures || []), failed];
   await pinSessionWireRoute(updated, provider);
   state.throwIfAborted();
-  state.messages.splice(0, state.messages.length, ...updated.messages);
+  // The live turn (prompt, assistant tool calls, tool results) carries on;
+  // only the previous provider's native replay state is dropped from it.
+  state.messages.splice(0, state.messages.length, ...stripProviderReplayMessages(state.messages));
   updated.liveTurnMessages = state.messages;
   state.sessionRef = updated;
   state.provider = provider;
@@ -67,6 +161,14 @@ export async function advanceAgentRoute(state, error) {
       signal: state.signal,
     })
   );
+  try {
+    process.stderr.write(
+      `[route-fallback] ${failed.provider}/${failed.model} (${failed.kind}) -> ${updated.provider}/${updated.model}\n`
+    );
+    state.opts.onStageChange?.('notice', { tone: 'info', message: notice });
+  } catch {
+    /* display-only */
+  }
   state.opts.onStageChange?.('connecting', {
     provider: updated.provider,
     model: updated.model,

package/src/runtime/agent/orchestrator/session/loop/send-phase.mjs

@@ -7,7 +7,6 @@ import { traceCacheBreak } from '../../cache-break-trace.mjs';
 import { resolveLiveToolCwd } from './tool-exec.mjs';
 import { notifySkillsApplied, prepareExplicitSkills, recordAppliedSkills } from '../explicit-skills.mjs';
 import { addUsage, usageDeltaEvent } from './usage.mjs';
-import { isVisibleStreamProgress } from '../../../../shared/stream-progress.mjs';
 import { prepareProviderRequest } from './request-boundary.mjs';
 import { applyStepEffort } from './step-auto-effort.mjs';
 import { projectProviderRequest } from './request-projection.mjs';
@@ -182,15 +181,10 @@ export async function sendProviderRequest(state, round) {
     tools: round.sendTools,
     opts,
   });
-  // The first visible token of this request, for its generation time (queue,
-  // preflight and time-to-first-token stay out of the speed figures).
-  let firstVisibleAt = 0;
-  const callerOnStreamDelta = opts.onStreamDelta;
-  const observeStreamDelta = (kind, ...rest) => {
-    if (!firstVisibleAt && isVisibleStreamProgress(kind)) firstVisibleAt = Date.now();
-    return callerOnStreamDelta?.(kind, ...rest);
-  };
-  opts.onStreamDelta = observeStreamDelta;
+  // The request's time for the speed figures, the wait for the first token
+  // included: the span the usage ledger recorded as `duration_ms` (stamped on
+  // the response); wall time only for a response no ledger row timed.
+  const requestStartedAt = Date.now();
   let result;
   try {
     result = await runWithProviderRequestToolsScope(round.requestToolScope, () =>
@@ -218,8 +212,6 @@ export async function sendProviderRequest(state, round) {
     sideQuestion?.discard();
     if (!(await advanceAgentRoute(state, error))) throw error;
     result = { action: 'retry_route' };
-  } finally {
-    if (opts.onStreamDelta === observeStreamDelta) opts.onStreamDelta = callerOnStreamDelta;
   }
   if (result.action === 'proceed') sideQuestion?.settle(result.response);
   else sideQuestion?.discard();
@@ -230,7 +222,9 @@ export async function sendProviderRequest(state, round) {
     prefixGuardCandidate,
     sendStartedAt,
     sendEndedAt,
-    generationMs: firstVisibleAt ? Math.max(0, sendEndedAt - firstVisibleAt) : 0,
+    requestMs: Number.isFinite(result.response?.usageDurationMs)
+      ? Math.max(0, result.response.usageDurationMs)
+      : Math.max(0, sendEndedAt - requestStartedAt),
     preSendMs,
     toolResumeMs,
   };
@@ -443,7 +437,7 @@ export function settleSendResult(state, round, sent) {
             usage: reportedUsage,
             sendTools: round.sendTools,
             toolCalls: response.toolCalls?.length || 0,
-            generationMs: sent.generationMs,
+            requestMs: sent.requestMs,
           })
         )
       );