mixdog 1.4.1 → 1.4.3

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

@@ -1,8 +1,10 @@
 // Deferred-tool catalog: measured-usage ordering, kind/bucket classification,
 // tool_search ranking + auto-selection, and the session tool-surface
 // application/selection logic. Pure module (session objects passed in).
+import { createHash } from 'node:crypto';
 import { clean } from './session-text.mjs';
-import { mergePendingDeferredToolDelta } from './deferred-tool-delta.mjs';
+import { dropPendingDeferredToolAdds, mergePendingDeferredToolDelta } from './deferred-tool-delta.mjs';
+import { isAgentOwner } from '../agent-owner.mjs';
 import { applyInitialDeferredToolManifestToBp2 } from '../context/collect.mjs';
 import {
   listedDeferredToolNames,
@@ -12,7 +14,11 @@ import {
 import { parseMcpToolName } from '../../../shared/tool-primitives.mjs';
 import { getMcpServerInstructionsMap, getMcpTools, getMcpToolGeneration } from '../mcp/client.mjs';
 import { filterMcpToolsForSession } from './extension-scopes.mjs';
-import { isDeferredToolAvailable, isToolPermittedBySessionPolicy } from './deferred-tool-availability.mjs';
+import {
+  isDeferredToolAvailable,
+  isToolPermittedBySessionPolicy,
+  sessionFeatureDenies,
+} from './deferred-tool-availability.mjs';
 import { routeToolExclusionReason } from '../session/loop/provider-tool-exclusions.mjs';
 import { isResponsesFreeformTool, toResponsesCustomTool } from '../providers/custom-tool-wire.mjs';
 import {
@@ -46,21 +52,8 @@ import {
   toolExposureModeForProvider,
 } from './tool-exposure.mjs';
 import { TOOL_BRIDGE_TOOLS } from './tool-defs.mjs';
-export {
-  toolKind,
-  toolSchemaBucket,
-  estimateToolSchemaBreakdown,
-  measuredToolUsage,
-  parseToolSelection,
-  sortedCatalogByMeasuredUsage,
-} from './tool-catalog-schema.mjs';
+export { estimateToolSchemaBreakdown } from './tool-catalog-schema.mjs';
 export { snapshotProviderRequestTools } from './provider-request-snapshot.mjs';
-export {
-  DEFERRED_DEFAULT_FULL_TOOLS,
-  DEFERRED_DEFAULT_LEAD_TOOLS,
-  DEFERRED_DEFAULT_READONLY_TOOLS,
-  MEASURED_TOOL_USAGE,
-} from './tool-catalog-data.mjs';
 
 // Provider modes without native tool search. Their bridge-v1 sessions
 // (tool-exposure.mjs) get the native roster and late delta notices; only a
@@ -548,24 +541,30 @@ export function rebuildDeferredToolSurfaceForProvider(session, provider) {
 // <available-deferred-tools> manifest IN PLACE and pre-mark names announced;
 // bridge-v1 sessions do the same (roster + bridge guidance). Only a fixed
 // surface not yet on the bridge updates its scoped catalog alone. Fully sync
-// and idempotent: no genuinely-new MCP name => no-op / no mutation.
+// and idempotent: no MCP name added or gone => no-op / no mutation.
 export function refreshInitialDeferredMcpSurface(session, liveMcpTools) {
   if (!session || !Array.isArray(session.messages)) return false;
   if (session.deferredProviderMode === 'full') return false;
   const live = filterDisallowedTools(Array.isArray(liveMcpTools) ? liveMcpTools : [], session.disallowedTools);
+  const liveNames = new Set(live.map((tool) => clean(tool?.name)).filter(isMcpToolName));
   const byName = new Map();
+  // Nothing was sent yet: a server gone since create leaves the initial surface.
+  let changed = false;
   for (const tool of Array.isArray(session.deferredToolCatalog) ? session.deferredToolCatalog : []) {
     const name = clean(tool?.name);
+    if (isMcpToolName(name) && !liveNames.has(name)) {
+      changed = true;
+      continue;
+    }
     if (name && !byName.has(name)) byName.set(name, tool);
   }
-  let added = false;
   for (const tool of live) {
     const name = clean(tool?.name);
     if (!name || !isMcpToolName(name) || byName.has(name)) continue;
     byName.set(name, activeToolForSurface(tool));
-    added = true;
+    changed = true;
   }
-  if (!added) return false;
+  if (!changed) return false;
   session.deferredToolCatalog = sortedCatalogByMeasuredUsage([...byName.values()]);
   if (fixedSurfaceSession(session)) {
     session.updatedAt = Date.now();
@@ -720,10 +719,12 @@ function reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools) {
   // connected OR the tool is already loaded, including native history-only
   // discoveries. Availability is determined by deferredMcpToolNames, not this pool.
   const nextByName = new Map();
+  // A built-in a settings gate opened (tool-availability.mjs) is no MCP tool:
+  // its availability is the session's deny set, so it stays.
   for (const tool of lateCatalog) {
     const name = clean(tool?.name);
     if (!name || nextByName.has(name)) continue;
-    if (!liveMcpByName.has(name) && !active.has(name)) continue;
+    if (isMcpToolName(name) && !liveMcpByName.has(name) && !active.has(name)) continue;
     nextByName.set(name, tool);
   }
   for (const [name, tool] of liveMcpByName) nextByName.set(name, tool);
@@ -773,28 +774,84 @@ function reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools) {
  * connected tool the boot manifest never listed and the session has not loaded
  * or discovered rides the next real prompt as one more delta, acknowledged
  * only once the provider accepts that turn.
+ * Only a session whose prompt is never rebuilt at a cold point (a delegated
+ * worker, or a prompt without a recorded identity) is re-armed, by name; any
+ * other session folds its late tools into the rebuilt manifest instead
+ * (foldLateDeferredTools).
  * Returns the re-armed names, or null when there are none.
  */
 export function rearmLateDeferredTools(session) {
   // The compaction also drops the load results that carried a server's
-  // instruction text, so the next load of its tools delivers it again.
-  if (session) delete session.mcpInstructionsAnnounced;
+  // instruction text (the account and configuration guidance, which no prompt
+  // manifest carries), so the next load of its tools delivers it again. It
+  // rides a tool result, never the cached prefix, and ordinary turns still
+  // send it once.
+  if (session) {
+    delete session.mcpInstructionsAnnounced;
+    delete session.mcpInstructionHashes;
+  }
   if (!session || !Array.isArray(session.tools) || fixedSurfaceSession(session)) return null;
-  if (!Array.isArray(session.deferredMcpToolNames) || !Array.isArray(session.deferredAnnouncedTools)) return null;
+  if (session.promptIdentity && !isAgentOwner(session)) return null;
+  if (!Array.isArray(session.deferredAnnouncedTools)) return null;
   // Listed in the boot manifest, or already loaded/discovered: still visible.
   const listed = new Set([...session.deferredAnnouncedTools, ...persistentToolSurfaceNames(session)]);
-  const connected = new Set(session.deferredMcpToolNames);
+  const connected = new Set(Array.isArray(session.deferredMcpToolNames) ? session.deferredMcpToolNames : []);
   const added = [];
   for (const tool of Array.isArray(session.deferredLateToolCatalog) ? session.deferredLateToolCatalog : []) {
     const name = clean(tool?.name);
-    if (!name || !connected.has(name) || listed.has(name) || !rosterPermits(session, tool)) continue;
-    added.push({ name, description: lateAnnouncementDescription(tool?.description) });
+    if (!name || listed.has(name) || !rosterPermits(session, tool)) continue;
+    // MCP tools while connected; a built-in a settings gate opened while permitted.
+    if (isMcpToolName(name) ? !connected.has(name) : !isToolPermittedBySessionPolicy(session, name)) continue;
+    // Names only: the model was told the description before.
+    added.push({ name, description: '' });
   }
   if (!added.length) return null;
   mergePendingDeferredToolDelta(session, { added });
   return added.map((entry) => entry.name);
 }
 
+/**
+ * A cold point (a compaction, a rebuilt prompt): the late tools join the boot
+ * catalog and the rebuilt BP2 manifest lists them, so nothing about them rides
+ * a notice. Pending
+ * announcements the manifest now carries are dropped. Returns the folded names.
+ */
+export function foldLateDeferredTools(session) {
+  if (!session || !Array.isArray(session.tools) || fixedSurfaceSession(session)) return [];
+  const late = Array.isArray(session.deferredLateToolCatalog) ? session.deferredLateToolCatalog : [];
+  const connected = new Set(Array.isArray(session.deferredMcpToolNames) ? session.deferredMcpToolNames : []);
+  const byName = new Map();
+  for (const tool of Array.isArray(session.deferredToolCatalog) ? session.deferredToolCatalog : []) {
+    const name = clean(tool?.name);
+    if (name && !byName.has(name)) byName.set(name, tool);
+  }
+  const folded = [];
+  for (const tool of late) {
+    const name = clean(tool?.name);
+    if (!name || byName.has(name) || !rosterPermits(session, tool)) continue;
+    if (isMcpToolName(name) ? !connected.has(name) : !isToolPermittedBySessionPolicy(session, name)) continue;
+    byName.set(name, activeToolForSurface(tool));
+    folded.push(name);
+  }
+  session.deferredToolCatalog = sortedCatalogByMeasuredUsage([...byName.values()]);
+  // Whatever the boot catalog holds now (folded here, or by the rebuilt surface) leaves the late pool.
+  session.deferredLateToolCatalog = late.filter((tool) => !byName.has(clean(tool?.name)));
+  session.mcpServerInstructions = getMcpServerInstructionsMap(session.mcpScopeId);
+  if (Array.isArray(session.messages) && session.messages.some((m) => m?.role === 'system')) {
+    applyInitialDeferredToolManifestToBp2(session, deferredPoolToolNames(session), { rebuild: true });
+    session.deferredAnnouncedTools = listedDeferredToolNames(
+      session,
+      deferredPoolToolNames(session),
+      renderedDeferredManifest(session)
+    );
+  }
+  // The manifest lists only short triggers, never a server's instruction text:
+  // what a load has told stays as recorded (a compaction clears it).
+  const listed = new Set(Array.isArray(session.deferredAnnouncedTools) ? session.deferredAnnouncedTools : []);
+  dropPendingDeferredToolAdds(session, listed);
+  return folded;
+}
+
 export function scopedMcpToolsFor(session, config = null) {
   return filterMcpToolsForSession(getMcpTools(session?.mcpScopeId), session?.cwd || null, config);
 }
@@ -916,24 +973,41 @@ function resolvableCatalog(session) {
   return filterSessionToolPolicy(tools, session);
 }
 
+const instructionHash = (text) =>
+  createHash('sha256')
+    .update(String(text || ''))
+    .digest('hex')
+    .slice(0, 16);
+
 // A server's instruction text rides the first load_tool naming any of its
-// tools (loaded now, already active, or described on the bridge), once until
-// compaction (`mcpInstructionsAnnounced`; rearmLateDeferredTools clears it with
-// the transcript that held the text): `## <server>` + body, sanitized and
-// capped like the BP2 block it replaces. No text, nothing sent or recorded.
+// tools (loaded now, already active, or described on the bridge), once per
+// text (`mcpInstructionsAnnounced`, `mcpInstructionHashes`: a connector whose
+// accounts changed sends its new text again; a compaction clears the record,
+// rearmLateDeferredTools): `## <server>` + body,
+// sanitized and capped (sanitizeMcpInstructionText, well under 4 KB). No
+// text, nothing sent or recorded.
 function pendingMcpInstructions(session, catalog, names) {
   const map = session?.mcpServerInstructions;
   if (!map || typeof map !== 'object' || !names.length) return [];
   const byName = new Map(catalog.map((tool) => [clean(tool?.name), tool]));
   const announced = new Set(Array.isArray(session.mcpInstructionsAnnounced) ? session.mcpInstructionsAnnounced : []);
+  const hashes =
+    session.mcpInstructionHashes && typeof session.mcpInstructionHashes === 'object'
+      ? session.mcpInstructionHashes
+      : {};
+  const seen = new Set();
   const pending = [];
   for (const name of names) {
     const server = parseMcpToolName(byName.get(name) || name)?.server;
-    if (!server || announced.has(server) || !mcpServerManifestLabel(server)) continue;
+    if (!server || seen.has(server) || !mcpServerManifestLabel(server)) continue;
     const text = sanitizeMcpInstructionText(map[server]);
     if (!text) continue;
-    announced.add(server);
-    pending.push({ server, block: `## ${server}\n${text}` });
+    const hash = instructionHash(text);
+    // Told already, and the text is the one told. A record from before hashes
+    // were kept cannot tell which text it carried: sent once more, and hashed.
+    if (announced.has(server) && hashes[server] === hash) continue;
+    seen.add(server);
+    pending.push({ server, hash, block: `## ${server}\n${text}` });
   }
   return pending;
 }
@@ -943,6 +1017,10 @@ function announceMcpServers(session, pending) {
   session.mcpInstructionsAnnounced = [
     ...new Set([...(session.mcpInstructionsAnnounced || []), ...pending.map((entry) => entry.server)]),
   ];
+  session.mcpInstructionHashes = {
+    ...(session.mcpInstructionHashes || {}),
+    ...Object.fromEntries(pending.map((entry) => [entry.server, entry.hash])),
+  };
 }
 
 function claimMcpServerInstructions(session, catalog, names) {
@@ -1016,7 +1094,9 @@ export function renderToolSearch(args = {}, session, mode = 'full', options = {}
   ]);
   const loaded = toolSelection.added || [];
   const alreadyActive = toolSelection.already || [];
-  const missing = toolSelection.missing || [];
+  // A tool a settings gate closed is named as such, not as unknown.
+  const disabledInSettings = (toolSelection.missing || []).filter((name) => sessionFeatureDenies(session, name));
+  const missing = (toolSelection.missing || []).filter((name) => !disabledInSettings.includes(name));
   const blocked = toolSelection.blocked || [];
   // Native discovery is history-driven: an explicit re-selection must emit
   // the tool reference/spec again even when the callable registry already has
@@ -1040,6 +1120,9 @@ export function renderToolSearch(args = {}, session, mode = 'full', options = {}
     ? { ...nativeToolSearchBase, summary: nativeSummary || nativeToolSearchBase.summary }
     : null;
   const notes = [];
+  if (disabledInSettings.length) {
+    notes.push(`Disabled in settings: ${disabledInSettings.join(', ')}. Do not retry unless the user turns it on.`);
+  }
   if (missing.length && pendingMcpServers.length) {
     notes.push('Some requested names may belong to an MCP server still connecting — retry next turn.');
   }
@@ -1059,6 +1142,7 @@ export function renderToolSearch(args = {}, session, mode = 'full', options = {}
       alreadyActive,
       ...(alreadyActiveSchemas.length ? { alreadyActiveSchemas } : {}),
       missing,
+      ...(disabledInSettings.length ? { disabledInSettings } : {}),
       ...(blocked.length ? { blocked } : {}),
       ...mcpFields,
       activeTools: sortedNamesByMeasuredUsage(

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

@@ -101,7 +101,7 @@ export const SESSION_TOOL = {
           'suggest',
         ],
         description:
-          'status defaults to current; list pages sessions, without sub-agent or archived ones unless include_agents/include_archived; bots shows each bot’s activity, work, approvals, routines and attention flags, or with session_id (a bot id or its chat) its routines and recent 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 (started, not done yet); unknown Project: list-projects first, still ambiguous: ask the user. compact runs after this turn; fork copies it without switching. suggest (Mixy’s chat only) records a proposal made to the user under key; value false records that the user declined it.',
+          'status defaults to current; list pages sessions, without sub-agent or archived ones unless include_agents/include_archived; bots shows each bot’s activity, work, approvals, routines and attention flags, or with session_id (a bot id or its chat) its routines and recent 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; only for a big multi-step plan, smaller work goes to agent) starts a visible agent task session from brief (started, not done yet); unknown Project: list-projects first, still ambiguous: ask the user. compact runs after this turn; fork copies it without switching. suggest (Mixy’s chat only) records a proposal made to the user under key; value false records that the user declined it.',
       },
       title: {
         type: 'string',
@@ -240,6 +240,7 @@ const OFFICE_RUNTIME_TOOLS = ['office'];
 const MEDIA_RUNTIME_TOOLS = ['media'];
 const TIDY_RUNTIME_TOOLS = ['tidy'];
 const VISUALIZE_RUNTIME_TOOLS = ['visualize'];
+const EXPLORE_RUNTIME_TOOLS = ['explore'];
 
 const admitted = (tools, names) => (tools || []).filter((tool) => names.includes(tool?.name));
 
@@ -262,6 +263,7 @@ export function collectStandaloneToolDefs({
   mediaToolDefs = [],
   tidyToolDefs = [],
   visualizeToolDefs = [],
+  exploreToolDefs = [],
   setupToolDefs = [],
   askUserToolDefs = [],
   handoffUserToolDefs = [],
@@ -285,6 +287,7 @@ export function collectStandaloneToolDefs({
     ...admitted(mediaToolDefs, MEDIA_RUNTIME_TOOLS),
     ...admitted(tidyToolDefs, TIDY_RUNTIME_TOOLS),
     ...admitted(visualizeToolDefs, VISUALIZE_RUNTIME_TOOLS),
+    ...admitted(exploreToolDefs, EXPLORE_RUNTIME_TOOLS),
     ...setupToolDefs,
     ...askUserToolDefs,
     ...handoffUserToolDefs,

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

@@ -4,6 +4,8 @@ import { clean } from '../session-text.mjs';
 import { configuredOrchestrationMode } from '../../../../shared/orchestration.mjs';
 import { AGENT_MODE_DELEGATION, MIXY_CONTACTS_INTRO, orchestrationInstructions } from '../orchestration.mjs';
 import { DEFAULT_WORKFLOW_ID, isContactAgentId, normalizeWorkflowId } from '../workflow-ids.mjs';
+import { MIXY_AGENT_ID } from '../../session/agent-home.mjs';
+import { mixyDisplayName } from '../../session/mixy-name.mjs';
 
 export function createWorkflowContext({ packs, agents }) {
   function workflowSummary(pack, { hasAgents = true } = {}) {
@@ -30,7 +32,7 @@ export function createWorkflowContext({ packs, agents }) {
   function workflowContextBlockFromPack(pack) {
     if (!pack) return '';
     // The pack body opens with its own `# <name>` title, so header + description
-    // + body used to repeat the workflow name three times in the prompt. Emit one
+    // + body would repeat the workflow name three times in the prompt. Emit one
     // header line and drop the body's duplicate title (only when it matches).
     const rawBody = String(pack.body || '');
     const firstBreak = rawBody.indexOf('\n');
@@ -59,7 +61,9 @@ export function createWorkflowContext({ packs, agents }) {
   // - coding: the orchestration mode block and the full agent catalog;
   // - agent mode: the fixed delegation block (no per-agent setting) and the
   //   sub-agent catalog — identical for every agent, so their prompts share
-  //   it — plus the contact-agent catalog: every bot but `agentId` itself.
+  //   it — plus the contact-agent catalog: every bot but `agentId` itself,
+  //   and for any bot but Mixy, Mixy first under her display name, so a bot
+  //   asked to hand work to her by that name finds her (session send lead).
   function leadPromptParts(config, dir, { agentMode = false, agentId = '' } = {}) {
     const mode = configuredOrchestrationMode(config);
     const ids = agents.delegatableAgentIds(config, dir);
@@ -79,10 +83,15 @@ export function createWorkflowContext({ packs, agents }) {
       dir,
       ids.filter((id) => !isContact(id))
     );
-    const contacts = agentCatalog(
-      dir,
-      ids.filter((id) => isContact(id) && id !== agentId)
-    );
+    const contacts = [
+      agentId === MIXY_AGENT_ID ? '' : `- ${mixyDisplayName()} (${MIXY_AGENT_ID}): the user's representative bot`,
+      agentCatalog(
+        dir,
+        ids.filter((id) => isContact(id) && id !== agentId)
+      ),
+    ]
+      .filter(Boolean)
+      .join('\n');
     return {
       // An agent-mode Lead without agents has no one to delegate to at all.
       orchestrationContext: subAgents || contacts ? AGENT_MODE_DELEGATION : '',

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

@@ -7,6 +7,7 @@ export const AGENT_DELETED_MARKER = '.deleted';
 export const FIXED_AGENT_SLOTS = Object.freeze([
   // Short one-liners on purpose: these render inside the 260px sidebar rail.
   { id: 'maintainer', label: 'Maintainer', description: 'Memory and upkeep', workflowSlot: 'memory' },
+  { id: 'explore', label: 'Explore', description: 'Codebase exploration', workflowSlot: 'explore' },
 ]);
 export const AGENT_ROLE_IDS = new Set(FIXED_AGENT_SLOTS.map((agent) => agent.id));
 // Slot-backed built-ins run through dedicated maintenance channels, so they are never

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

@@ -14,6 +14,7 @@ import { clearReactionTargets } from '../runtime-core/reaction-tool-defs.mjs';
 import { applyRetryAction, beginIteration, sendProviderRequest, settleSendResult } from './loop/send-phase.mjs';
 import { runToolPhase } from './loop/tool-phase.mjs';
 import { endedWithoutReply } from './loop/turn-limits.mjs';
+import { carryReportOnError } from './loop/turn-report.mjs';
 
 // Facade re-exports: these symbols live in ./loop/ modules and are part of
 // loop.mjs's public surface (imported by scripts/tests and other runtime
@@ -62,29 +63,34 @@ async function runAgentLoop(provider, messages, model, tools, onToolCall, cwd, s
   resetAccountProbePacing();
   const state = createLoopState({ provider, messages, model, tools, cwd, sendOpts });
   // Completion, cancellation, and terminal failures end execution.
-  while (true) {
-    const round = await beginIteration(state);
-    const sent = await sendProviderRequest(state, round);
-    if (applyRetryAction(state, sent.result)) continue;
-    settleSendResult(state, round, sent);
-    // A turn without client tool calls is not automatically the final answer:
-    // the provider may have hit its output ceiling, been cut by a safety
-    // classifier, declared the turn unfinished, or returned nothing. Each case
-    // owns a bounded recovery ladder in ./loop/no-tool-turn.mjs, which either
-    // appended a recovery turn ('continue') or produced the terminal response.
-    if (!state.response.toolCalls?.length) {
-      const outcome = await state.noToolTurn.resolve(state.response, state.iterations);
-      state.response = outcome.response;
-      if (outcome.action === 'continue') continue;
-      break;
-    }
-    await runToolPhase(state, round, sent, onToolCall);
-    // A capped turn that kept calling tools after it was told to reply ends
-    // here with no reply (./loop/turn-limits.mjs).
-    if (state.turnLimitEnded) {
-      state.response = endedWithoutReply(state.response);
-      break;
+  try {
+    while (true) {
+      const round = await beginIteration(state);
+      const sent = await sendProviderRequest(state, round);
+      if (applyRetryAction(state, sent.result)) continue;
+      settleSendResult(state, round, sent);
+      // A turn without client tool calls is not automatically the final answer:
+      // the provider may have hit its output ceiling, been cut by a safety
+      // classifier, declared the turn unfinished, or returned nothing. Each case
+      // owns a bounded recovery ladder in ./loop/no-tool-turn.mjs, which either
+      // appended a recovery turn ('continue') or produced the terminal response.
+      if (!state.response.toolCalls?.length) {
+        const outcome = await state.noToolTurn.resolve(state.response, state.iterations);
+        state.response = outcome.response;
+        if (outcome.action === 'continue') continue;
+        break;
+      }
+      await runToolPhase(state, round, sent, onToolCall);
+      // A capped turn that kept calling tools after it was told to reply ends
+      // here with no reply (./loop/turn-limits.mjs), keeping the answers it
+      // went past.
+      if (state.turnLimitEnded) {
+        state.response = state.noToolTurn.finalize(endedWithoutReply(state.response));
+        break;
+      }
     }
+  } catch (error) {
+    throw carryReportOnError(error, state.noToolTurn.endedReport());
   }
   return finishLoop(state);
 }

package/src/runtime/agent/orchestrator/session/agent-pool-progress.mjs

@@ -4,6 +4,36 @@
 // only — nothing here reads or changes the watchdog's abort policy.
 import { displayProgressStage, lastProgressAt } from '../../../shared/quiet-progress.mjs';
 import { resolveAgentStallThresholds } from '../stall-policy.mjs';
+import { todoProgress } from '../runtime-core/todo-list.mjs';
+import { sessionUsageTotals } from '../../../shared/session-usage-totals.mjs';
+
+/** `rows` with each agent's todo progress taken from its live session when
+ *  this process holds one: the list changes before the session is saved, and
+ *  the stored copy lags. A live session is authoritative, so one without a
+ *  list (cleared) drops the row's stored `todo`; rows with no live session
+ *  keep the stored one. */
+export function withLiveTodo(rows, liveSession) {
+  return rows.map((row) => {
+    const live = row?.sessionId ? liveSession(row.sessionId) : null;
+    if (!live) return row;
+    const { todo: _stored, ...rest } = row;
+    const todo = todoProgress(live);
+    return todo ? { ...rest, todo } : rest;
+  });
+}
+
+/** `rows` with each agent's running token and tool-call totals taken from its
+ *  live session when this process holds one: the counters advance with every
+ *  model response, while the stored copy follows a throttled save. A total the
+ *  live session does not know keeps the stored one. */
+export function withLiveUsage(rows, liveSession) {
+  return rows.map((row) => {
+    const live = row?.sessionId ? liveSession(row.sessionId) : null;
+    if (!live) return row;
+    const { usage, toolCalls } = sessionUsageTotals(live);
+    return { ...row, ...(usage ? { usage } : {}), ...(toolCalls === null ? {} : { toolCalls }) };
+  });
+}
 
 /** `rows` with progress fields on every row `runtimeEntry(sessionId)` reports
  *  in flight. `awaitingTask` marks a row whose agent waits on its background

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

@@ -9,12 +9,19 @@ export interface RoomRow {
   to?: string[] | string;
   toName?: string[] | string;
   failed?: boolean;
+  /** A failed pass row: every member it stands for (a run of failures collapses
+   *  into one row), and why they failed. */
+  names?: string[];
+  /** Stored as one string; a host may hand the distinct reasons as a list. */
+  reason?: string | string[];
+  /** A usage-limit stop (`limit: 'usage'` on a cap row): what ran out, on which model. */
+  usage?: RoomUsageLimit;
   /** A user-kind row another session sent: its session, the sending bot
    *  (none for the user's Lead) and the name it is shown under. */
   fromSession?: string;
   fromAgent?: string;
   fromName?: string;
-  limit?: 'rounds' | 'messages';
+  limit?: 'rounds' | 'messages' | 'usage';
   rounds?: number;
   messages?: number;
   tools?: Array<{ name: string; summary: string }>;
@@ -66,11 +73,27 @@ export interface RoomMemberLabel {
   name: string;
 }
 export type RoomTurnResult = 'speech' | 'pass' | 'stopped' | 'superseded';
-/** A turn's answer; a speech may name the one peer it addressed. */
-export type RoomTurnAnswer = RoomTurnResult | { result: RoomTurnResult; mention?: string };
+/** What stopped a turn on the provider's usage limit (roomUsageLimit). */
+export interface RoomUsageLimit {
+  kind: 'quota_exhausted' | 'entitlement' | 'billing';
+  provider: string;
+  model: string;
+  /** Epoch ms the limit resets; null when unknown. */
+  resetAt: number | null;
+}
+/** The usage-limit stop a failed `turndone` item records, or null. */
+export function roomUsageLimit(done: unknown, route?: { provider?: string; model?: string }): RoomUsageLimit | null;
+/** A turn's answer; a speech may name the one peer it addressed, a failed
+ *  pass says so (`failed`) and, on a usage limit, why (`usage`). */
+export type RoomTurnAnswer =
+  | RoomTurnResult
+  | 'unavailable'
+  | { result: RoomTurnResult | 'unavailable'; mention?: string; failed?: boolean; usage?: RoomUsageLimit | null };
 export interface RoomExchangeResult {
-  outcome: 'done' | 'capped' | 'stopped' | 'superseded';
+  outcome: 'done' | 'capped' | 'stopped' | 'superseded' | 'limited' | 'failed';
   limit?: 'rounds' | 'messages';
+  /** A 'limited' end: the usage limit the turn met. */
+  usage?: RoomUsageLimit;
   rounds: number;
   /** Supervisor steps taken. */
   steps: number;
@@ -118,7 +141,7 @@ export type RoomScene = 'casual' | 'work';
 /** What one supervisor step is told. */
 export interface RoomStep {
   mustPick: boolean;
-  turns: Array<{ id: string; result: RoomTurnResult }>;
+  turns: Array<{ id: string; result: RoomTurnResult; failed?: boolean }>;
   last: string;
   mention: string;
   remaining: { messages: number; steps: number };
@@ -144,6 +167,8 @@ export function runRoomExchange(options: {
   waiting?: boolean;
   /** The called members (`to`) answer and nobody else follows. */
   only?: boolean;
+  /** The sender stated that the request also addressed the whole room; unset, only an empty `to` does. */
+  wholeRoom?: boolean;
 }): Promise<RoomExchangeResult>;
 export function roomDataLabel(value: unknown): string;
 export function roomDataLines(text: unknown): string[];