mixdog 1.4.1 → 1.4.3

package/src/runtime/agent/orchestrator/runtime-core/todo-list.mjs

@@ -0,0 +1,367 @@
+// The per-owner step list behind the `todo` tool. One list lives on each
+// session record (`session.todo`: the Lead session, and each agent session),
+// so it is saved with the session, survives a daemon restart and compaction,
+// and is never shared between a Lead and its agents.
+//
+// Every mutation replaces `session.todo` with a new object: the published
+// snapshot is memoized by that identity, and change listeners republish it.
+import { emitSessionActivityChange } from '../../../shared/session-activity-signal.mjs';
+import { MAX_TODO_ITEMS, MAX_TODO_TEXT_LENGTH, TODO_OPS, TODO_STATUSES } from './todo-tool-defs.mjs';
+
+const DEFAULT_TODO_PHASE = 'Tasks';
+const OPEN_STATUSES = new Set(['pending', 'in_progress']);
+const listeners = new Set();
+const snapshots = new WeakMap();
+
+const oneLine = (value) =>
+  String(value ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+function itemText(value, what = 'item') {
+  const text = oneLine(value);
+  if (!text) throw new Error(`todo: ${what} wording is required`);
+  if ([...text].length > MAX_TODO_TEXT_LENGTH) {
+    throw new Error(`todo: ${what} exceeds ${MAX_TODO_TEXT_LENGTH} characters`);
+  }
+  return text;
+}
+
+function normalizeTask(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const content = oneLine(raw.content);
+  if (!content) return null;
+  const status = TODO_STATUSES.includes(raw.status) ? raw.status : 'pending';
+  const task = { content, status };
+  if (status === 'blocked' && oneLine(raw.blocker)) task.blocker = oneLine(raw.blocker);
+  if (oneLine(raw.note)) task.note = oneLine(raw.note);
+  return task;
+}
+
+/** The session's phases, normalized (stored records are untrusted). */
+export function todoPhases(session) {
+  const phases = Array.isArray(session?.todo?.phases) ? session.todo.phases : [];
+  return phases
+    .map((phase) => ({
+      name: oneLine(phase?.name) || DEFAULT_TODO_PHASE,
+      tasks: (Array.isArray(phase?.tasks) ? phase.tasks : []).map(normalizeTask).filter(Boolean),
+    }))
+    .filter((phase) => phase.tasks.length > 0);
+}
+
+const allTasks = (phases) => phases.flatMap((phase) => phase.tasks);
+
+/** Exactly one in_progress while actionable work exists: several keep the
+ *  earliest, none starts the earliest pending. Blocked never starts itself. */
+function normalizeTodoPhases(phases) {
+  const tasks = allTasks(phases);
+  const active = tasks.filter((task) => task.status === 'in_progress');
+  for (const task of active.slice(1)) task.status = 'pending';
+  if (active.length === 0) {
+    const next = tasks.find((task) => task.status === 'pending');
+    if (next) next.status = 'in_progress';
+  }
+  return phases.filter((phase) => phase.tasks.length > 0);
+}
+
+function todoCounts(phases) {
+  const tasks = allTasks(phases);
+  return {
+    completed: tasks.filter((task) => task.status === 'completed').length,
+    abandoned: tasks.filter((task) => task.status === 'abandoned').length,
+    total: tasks.length,
+  };
+}
+
+/** Pending and in-progress items: the work the completion check asks about. */
+export function openTodoItems(session) {
+  return allTasks(todoPhases(session)).filter((task) => OPEN_STATUSES.has(task.status));
+}
+
+/** Every item not completed or dropped (blocked included): what an agent
+ *  leaves undone when it ends. */
+export function unfinishedTodoItems(session) {
+  return allTasks(todoPhases(session)).filter((task) => task.status !== 'completed' && task.status !== 'abandoned');
+}
+
+/** The published session snapshot; null for an empty list. Identity-stable
+ *  while the list is unchanged. */
+export function todoSnapshot(session) {
+  const record = session?.todo;
+  if (!record || typeof record !== 'object') return null;
+  if (snapshots.has(record)) return snapshots.get(record);
+  const phases = todoPhases(session);
+  const snapshot = phases.length ? { phases, ...todoCounts(phases) } : null;
+  snapshots.set(record, snapshot);
+  return snapshot;
+}
+
+/** Agent status rows: `{ completed, total, current? }`, or null. */
+export function todoProgress(session) {
+  const snapshot = todoSnapshot(session);
+  if (!snapshot) return null;
+  const current = allTasks(snapshot.phases).find((task) => task.status === 'in_progress')?.content;
+  // Rows show completed/total directly, so dropped items leave the total.
+  return {
+    completed: snapshot.completed,
+    total: snapshot.total - snapshot.abandoned,
+    ...(current ? { current } : {}),
+  };
+}
+
+export function onTodoChange(listener) {
+  if (typeof listener !== 'function') return () => {};
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** A list with items, every one completed or dropped. */
+export function todoAllClosed(session) {
+  return todoPhases(session).length > 0 && unfinishedTodoItems(session).length === 0;
+}
+
+/** Let go of the session's list. */
+export function clearTodo(session, at = Date.now()) {
+  session.todo = null;
+  session.updatedAt = at;
+  publish(session);
+}
+
+function commitPhases(session, phases, at = Date.now()) {
+  session.todo = { phases, updatedAt: at };
+  session.updatedAt = at;
+  publish(session);
+}
+
+function publish(session) {
+  // The Agents pool shows each agent's progress: it re-reads on this pulse.
+  emitSessionActivityChange(session.id || '');
+  for (const listener of [...listeners]) {
+    try {
+      listener({ sessionId: session.id || null, todo: todoSnapshot(session) });
+    } catch {
+      /* a listener never breaks the tool */
+    }
+  }
+}
+
+const MARKS = { completed: 'x', in_progress: '>', pending: ' ', blocked: '!', abandoned: '-' };
+
+function progressLabel(phases) {
+  const { completed, abandoned, total } = todoCounts(phases);
+  return `${completed}/${total - abandoned}`;
+}
+
+/** The whole list as text: init/view replies and context re-injection. */
+function renderTodoList(phases) {
+  if (!phases.length) return 'todo: empty';
+  const lines = [progressLabel(phases)];
+  for (const phase of phases) {
+    lines.push(phase.name);
+    for (const task of phase.tasks) {
+      const detail = task.blocker ? ` — blocked: ${task.blocker}` : task.note ? ` — ${task.note}` : '';
+      lines.push(`  [${MARKS[task.status]}] ${task.content}${detail}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function summaryLine(phases, op, content) {
+  const tasks = allTasks(phases);
+  const parts = [progressLabel(phases), `${op}: ${content}`];
+  const current = tasks.find((task) => task.status === 'in_progress');
+  if (current) parts.push(`next: ${current.content}`);
+  else if (tasks.some((task) => task.status === 'blocked')) parts.push('next: none (blocked items wait)');
+  else parts.push('all closed');
+  return parts.join(' · ');
+}
+
+function initPhases(args) {
+  let source;
+  if (Array.isArray(args.phases) && args.phases.length) source = args.phases;
+  else if (Array.isArray(args.items) && args.items.length) {
+    source = [{ name: oneLine(args.phase) || DEFAULT_TODO_PHASE, items: args.items }];
+  } else throw new Error('todo: init requires items or phases');
+  const seen = new Set();
+  const phaseNames = new Set();
+  const phases = source.map((entry) => {
+    const name = itemText(entry?.name, 'phase');
+    if (phaseNames.has(name)) throw new Error(`todo: duplicate phase "${name}"`);
+    phaseNames.add(name);
+    const items = Array.isArray(entry?.items) ? entry.items : [];
+    if (!items.length) throw new Error(`todo: phase "${name}" has no items`);
+    return {
+      name,
+      tasks: items.map((raw) => {
+        const content = itemText(raw);
+        if (seen.has(content)) throw new Error(`todo: duplicate item "${content}"`);
+        seen.add(content);
+        return { content, status: 'pending' };
+      }),
+    };
+  });
+  if (seen.size > MAX_TODO_ITEMS) throw new Error(`todo: at most ${MAX_TODO_ITEMS} items`);
+  return phases;
+}
+
+function findTask(phases, rawContent) {
+  const content = oneLine(rawContent);
+  if (!content) throw new Error('todo: item (its exact wording) is required');
+  for (const phase of phases) {
+    const index = phase.tasks.findIndex((task) => task.content === content);
+    if (index >= 0) return { phase, index, task: phase.tasks[index] };
+  }
+  throw new Error(`todo: no item "${content}"; view the list for exact wordings`);
+}
+
+const OPS = {
+  start(phases, args) {
+    const { task } = findTask(phases, args.item);
+    if (task.status === 'completed') throw new Error(`todo: "${task.content}" is completed and stays closed`);
+    if (task.status === 'blocked') throw new Error(`todo: "${task.content}" is blocked; unblock it first`);
+    for (const other of allTasks(phases)) if (other.status === 'in_progress') other.status = 'pending';
+    task.status = 'in_progress';
+    return task.content;
+  },
+  done(phases, args) {
+    const { task } = findTask(phases, args.item);
+    task.status = 'completed';
+    delete task.blocker;
+    const note = oneLine(args.note);
+    if (note) task.note = note;
+    return task.content;
+  },
+  drop(phases, args) {
+    const { task } = findTask(phases, args.item);
+    if (task.status === 'completed') throw new Error(`todo: "${task.content}" is completed and stays closed`);
+    task.status = 'abandoned';
+    delete task.blocker;
+    return task.content;
+  },
+  block(phases, args) {
+    const { task } = findTask(phases, args.item);
+    if (task.status === 'completed' || task.status === 'abandoned') {
+      throw new Error(`todo: "${task.content}" is ${task.status}; only open items can block`);
+    }
+    task.status = 'blocked';
+    task.blocker = itemText(args.reason, 'block reason');
+    return task.content;
+  },
+  unblock(phases, args) {
+    const { task } = findTask(phases, args.item);
+    if (task.status !== 'blocked') throw new Error(`todo: "${task.content}" is not blocked`);
+    task.status = 'pending';
+    delete task.blocker;
+    return task.content;
+  },
+  append(phases, args) {
+    const items = Array.isArray(args.items) ? args.items.map((raw) => itemText(raw)) : [];
+    if (!items.length) throw new Error('todo: append requires items');
+    const existing = new Set(allTasks(phases).map((task) => task.content));
+    for (const content of items) {
+      if (existing.has(content)) throw new Error(`todo: item "${content}" already exists`);
+      existing.add(content);
+    }
+    if (existing.size > MAX_TODO_ITEMS) throw new Error(`todo: at most ${MAX_TODO_ITEMS} items`);
+    const name = oneLine(args.phase) || phases.at(-1)?.name || DEFAULT_TODO_PHASE;
+    let phase = phases.find((candidate) => candidate.name === name);
+    if (!phase) {
+      phase = { name, tasks: [] };
+      phases.push(phase);
+    }
+    phase.tasks.push(...items.map((content) => ({ content, status: 'pending' })));
+    return items.join(', ');
+  },
+  rm(phases, args) {
+    const { phase, index, task } = findTask(phases, args.item);
+    phase.tasks.splice(index, 1);
+    return task.content;
+  },
+};
+
+/** Run one `todo` call against the owner session. Returns the reply text. */
+export function executeTodoTool(session, args = {}) {
+  if (!session || typeof session !== 'object') throw new Error('todo: no session owns this call');
+  const op = oneLine(args?.op).toLowerCase();
+  if (!TODO_OPS.includes(op)) throw new Error(`todo: op must be one of ${TODO_OPS.join(', ')}`);
+  if (op === 'view') return renderTodoList(todoPhases(session));
+  if (op === 'init') {
+    // Replacing a list that still has unfinished work would silently erase it
+    // (a follow-up ask re-initing mid-request): make the model close each first.
+    const unfinished = unfinishedTodoItems(session);
+    if (unfinished.length) {
+      const named = unfinished.slice(0, 5).map((task) => `"${task.content}"`);
+      if (unfinished.length > named.length) named.push(`${unfinished.length - named.length} more`);
+      throw new Error(
+        `todo: init would erase unfinished items (${named.join(', ')}); done or drop each first, or append to add asks`
+      );
+    }
+    const phases = normalizeTodoPhases(initPhases(args));
+    commitPhases(session, phases);
+    return renderTodoList(phases);
+  }
+  const phases = structuredClone(todoPhases(session));
+  if (!phases.length) throw new Error('todo: the list is empty; init it first');
+  const content = OPS[op](phases, args);
+  const next = normalizeTodoPhases(phases);
+  commitPhases(session, next);
+  return summaryLine(next, op, content);
+}
+
+/** Lines naming what an agent leaves undone, '' when nothing is. */
+export function notDoneReport(session) {
+  const unfinished = unfinishedTodoItems(session);
+  if (!unfinished.length) return '';
+  return [
+    'Not done:',
+    ...unfinished.map((task) => `- ${task.content}${task.blocker ? ` (blocked: ${task.blocker})` : ''}`),
+  ].join('\n');
+}
+
+/** The open list as a hidden reminder (after compaction, or appended to a
+ *  Goal continuation); '' when nothing is open. */
+export function todoContextBlock(session, lead = 'Open todo items (exact wordings):', { whole = false } = {}) {
+  const phases = todoPhases(session);
+  if (!phases.length) return '';
+  if (!whole && !allTasks(phases).some((task) => task.status !== 'completed' && task.status !== 'abandoned')) {
+    return '';
+  }
+  return ['<todo_state>', lead, renderTodoList(phases), '</todo_state>'].join('\n');
+}
+
+// Legacy Goal task statuses as todo statuses.
+const LEGACY_GOAL_TASK_STATUS = {
+  pending: 'pending',
+  in_progress: 'in_progress',
+  completed: 'completed',
+  dropped: 'abandoned',
+  awaiting_approval: 'blocked',
+};
+
+/** Move a legacy Goal record's tasks into the session's list (once; the Goal
+ *  record drops them afterwards). Items already listed keep their state. */
+export function adoptLegacyGoalTasks(session, legacyTasks) {
+  if (!session || !Array.isArray(legacyTasks) || !legacyTasks.length) return false;
+  const phases = structuredClone(todoPhases(session));
+  const existing = new Set(allTasks(phases).map((task) => task.content));
+  const adopted = [];
+  for (const raw of legacyTasks) {
+    // Migrated wording stays whole (old tasks allowed longer text); the
+    // length limit applies only to newly authored items.
+    const content = oneLine(raw?.text ?? raw?.content);
+    if (!content || existing.has(content)) continue;
+    existing.add(content);
+    const status = LEGACY_GOAL_TASK_STATUS[oneLine(raw?.status).toLowerCase()] || 'pending';
+    adopted.push(status === 'blocked' ? { content, status, blocker: 'awaiting user approval' } : { content, status });
+  }
+  if (!adopted.length) return false;
+  const name = phases.length ? 'Goal' : DEFAULT_TODO_PHASE;
+  let phase = phases.find((candidate) => candidate.name === name);
+  if (!phase) {
+    phase = { name, tasks: [] };
+    phases.push(phase);
+  }
+  phase.tasks.push(...adopted);
+  commitPhases(session, normalizeTodoPhases(phases));
+  return true;
+}

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

@@ -0,0 +1,47 @@
+// The model-facing `todo` step list. Its description is the only guidance the
+// model gets about it: nothing is added to the system prompt or rules.
+export const TODO_OPS = Object.freeze(['init', 'start', 'done', 'drop', 'block', 'unblock', 'append', 'rm', 'view']);
+export const TODO_STATUSES = Object.freeze(['pending', 'in_progress', 'completed', 'abandoned', 'blocked']);
+export const MAX_TODO_ITEMS = 50;
+export const MAX_TODO_TEXT_LENGTH = 200;
+
+const itemList = { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: MAX_TODO_ITEMS };
+
+export const TODO_TOOL = Object.freeze({
+  name: 'todo',
+  title: 'Todo',
+  annotations: {
+    title: 'Todo',
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+    agentHidden: false,
+  },
+  description:
+    'The step list for this request; the Lead and each agent keep their own. Use it whenever the work has three or more steps or several asks (a delegated brief with several parts counts); skip it only for a single step or a plain answer. Create it before the first real action: init with every ask as its own item, in order, covering investigation through verification. A follow-up that adds to the request: append its asks and any steps you discover; init is for a new, unrelated request and refuses while items are open. An item is named by its outcome in 3-8 words and keeps that exact wording; it is how you refer to it — lost the wording: view, never guess. Keep it current while you work, not at the end: the moment an item is finished and its result is read, mark it done with your next call — never batch completions. The runtime keeps exactly one item in progress; done moves it to the next. Send todo beside your next real tool call; when no real call is due, call it alone rather than skip the update. Waiting on the user, an agent or a shell: block it with a reason; unblock when it can move; done only after reading the result.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      op: { type: 'string', enum: TODO_OPS },
+      items: { ...itemList, description: 'init (one default phase) / append: item wordings.' },
+      phases: {
+        type: 'array',
+        minItems: 1,
+        items: {
+          type: 'object',
+          properties: { name: { type: 'string' }, items: itemList },
+          required: ['name', 'items'],
+          additionalProperties: false,
+        },
+        description: 'init: named phases instead of items.',
+      },
+      item: { type: 'string', description: 'start/done/drop/block/unblock/rm: exact item wording.' },
+      phase: { type: 'string', description: 'append: target phase (default last; new name adds one).' },
+      note: { type: 'string', description: 'done: optional one-line evidence.' },
+      reason: { type: 'string', description: 'block: what it waits on.' },
+    },
+    required: ['op'],
+    additionalProperties: false,
+  },
+});

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

@@ -0,0 +1,155 @@
+// Settings-gated tool availability for a live session. A session records the
+// gates it was built with in `disallowedTools`; when a gate moves, a
+// conversation is never re-prefixed: an opened tool joins the late deferred
+// catalog (deferredLateToolCatalog — never the boot catalog, whose bytes a
+// native request keeps) and a closed one joins the enforced deny set. The next
+// prompt's deferred_tools_delta names both, and the prompt is folded at the
+// next cache-cold point (promptFoldPending).
+import { clean } from './session-text.mjs';
+import { FEATURE_GATED_TOOL_NAMES, SETTING_GATED_TOOL_NAMES, featureDisallowedToolsFor } from './builtin-features.mjs';
+import { mergePendingDeferredToolDelta } from './deferred-tool-delta.mjs';
+import { sessionAllowlistExcludes } from './deferred-tool-availability.mjs';
+import { isAgentOwner } from '../agent-owner.mjs';
+import { agentMcpToolPermission, connectorPolicyAgentOf, projectMcpToolDisabled } from '../mcp/agent-connectors.mjs';
+import { reactionDisabled } from '../session/manager/session-tool-surface.mjs';
+import { browserBridgeAvailableSync } from '../../../browser-bridge/client.mjs';
+import { computerBridgeAvailableSync } from '../../../computer-bridge/client.mjs';
+import { terminalBridgeAvailableSync } from '../../../terminal-bridge/client.mjs';
+
+const GATED = new Set(FEATURE_GATED_TOOL_NAMES);
+const SETTING_GATED = new Set(SETTING_GATED_TOOL_NAMES);
+// web_fetch keeps its gate under the transports it is routed to (pre-dispatch-deny.mjs).
+const FETCH_TRANSPORTS = new Set(['local_fetch', 'image_fetch']);
+
+// MCP scope → the live gate list of the session runtime serving it.
+const liveGateSources = new Map();
+
+/** A session runtime's live gate list (its in-memory settings) for model
+ *  calls in its MCP scope. Returns the unregister function. */
+export function registerLiveFeatureGates(scopeId, featureDisallowedTools) {
+  const key = scopeId ?? null;
+  liveGateSources.set(key, featureDisallowedTools);
+  return () => {
+    if (liveGateSources.get(key) === featureDisallowedTools) liveGateSources.delete(key);
+  };
+}
+
+/**
+ * The setting that turns off `name` right now, or null. A session's deny set
+ * takes moved gates at its next turn start; this covers a turn already
+ * running when a setting changed.
+ */
+export function settingDisabledTool(name, scopeId) {
+  const source = liveGateSources.get(scopeId ?? null);
+  return typeof source === 'function' ? settingDisabledIn(name, source()) : null;
+}
+
+/** The setting of the live gate list `denied` that turns off `name`, or null. */
+export function settingDisabledIn(name, denied) {
+  const gated = FETCH_TRANSPORTS.has(name) ? 'web_fetch' : name;
+  return SETTING_GATED.has(gated) && (denied || []).includes(gated) ? gated : null;
+}
+
+/** The feature gates as they stand: `config` plus live desktop-bridge presence. */
+export function liveFeatureDisallowedTools(config, { toolProfile } = {}) {
+  return featureDisallowedToolsFor(config, {
+    browserAvailable: browserBridgeAvailableSync(),
+    computerAvailable: computerBridgeAvailableSync(),
+    terminalAvailable: terminalBridgeAvailableSync(),
+    toolProfile,
+  });
+}
+
+function knownTools(session) {
+  const known = new Map();
+  for (const key of ['tools', 'deferredToolCatalog', 'deferredLateToolCatalog']) {
+    for (const tool of Array.isArray(session?.[key]) ? session[key] : []) {
+      const name = clean(tool?.name);
+      if (name && !known.has(name)) known.set(name, tool);
+    }
+  }
+  return known;
+}
+
+/**
+ * Bring `session`'s settings-gated tools to `featureDenied` (the live gate
+ * list) without touching its request prefix. `definitionsFor(names)` supplies
+ * definitions for opened tools the session never held. Returns
+ * `{ added, removed }` when a gate moved, else null.
+ */
+export function stageToolAvailability(session, featureDenied, definitionsFor = () => []) {
+  if (!session || !Array.isArray(session.tools)) return null;
+  const live = new Set((featureDenied || []).map(String).filter((name) => GATED.has(name)));
+  session.featureDeniedTools = [...live].sort();
+  const disallowed = (session.disallowedTools || []).map(String);
+  const denied = new Set(disallowed);
+  // Denials that are not settings: the caller's, and react outside a bot chat.
+  const fixed = new Set((session.callerDisallowedTools || []).map(String));
+  if (reactionDisabled(session, isAgentOwner(session))) fixed.add('react');
+  const closed = [...live].filter((name) => !denied.has(name));
+  const opened = disallowed.filter((name) => GATED.has(name) && !live.has(name) && !fixed.has(name));
+  if (!closed.length && !opened.length) return null;
+  const known = knownTools(session);
+  const missing = opened.filter((name) => !known.has(name));
+  const fresh = missing.length
+    ? (definitionsFor(missing) || []).filter((tool) => missing.includes(clean(tool?.name)))
+    : [];
+  for (const tool of fresh) {
+    if (!known.has(clean(tool.name))) known.set(clean(tool.name), tool);
+  }
+  if (fresh.length) {
+    session.deferredLateToolCatalog = [...(session.deferredLateToolCatalog || []), ...fresh];
+  }
+  const openedSet = new Set(opened);
+  session.disallowedTools = [...disallowed.filter((name) => !openedSet.has(name)), ...closed];
+  const visible = (name) => known.has(name) && !sessionAllowlistExcludes(session, name);
+  const added = opened.filter(visible);
+  const removed = closed.filter(visible);
+  mergePendingDeferredToolDelta(session, {
+    added: added.map((name) => ({ name, description: known.get(name)?.description || '' })),
+    removed,
+  });
+  // A delegated worker is never folded (agent-profile-fold.mjs): its opened
+  // tools are re-announced after a compaction instead (rearmLateDeferredTools).
+  if (!isAgentOwner(session)) session.promptFoldPending = true;
+  session.updatedAt = Date.now();
+  return { added, removed };
+}
+
+// The connector tools among the session's known tools that its agent's
+// connector policy and its project's connector switches let it run now.
+function permittedConnectorTools(session, known) {
+  const agent = connectorPolicyAgentOf(session);
+  return [...known.keys()]
+    .filter(
+      (name) =>
+        name.startsWith('mcp__') &&
+        agentMcpToolPermission(agent, name) !== 'disabled' &&
+        !projectMcpToolDisabled(session, name)
+    )
+    .sort();
+}
+
+/**
+ * Connector switches (an agent's policy, a project's connector off/on) gate
+ * MCP tools at call time (pre-dispatch-deny.mjs); this tells the model. The
+ * first call records the baseline; later moves join the deferred_tools_delta.
+ * Returns `{ added, removed }` when the permitted set moved, else null.
+ */
+export function stageConnectorAvailability(session) {
+  if (!session || !Array.isArray(session.tools)) return null;
+  const known = knownTools(session);
+  const permitted = permittedConnectorTools(session, known);
+  const previous = session.agentConnectorTools;
+  session.agentConnectorTools = permitted;
+  if (!Array.isArray(previous)) return null;
+  const added = permitted.filter((name) => !previous.includes(name));
+  const removed = previous.filter((name) => !permitted.includes(name));
+  if (!added.length && !removed.length) return null;
+  mergePendingDeferredToolDelta(session, {
+    added: added.map((name) => ({ name, description: known.get(name)?.description || '' })),
+    removed,
+  });
+  session.updatedAt = Date.now();
+  return { added, removed };
+}

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

@@ -1,6 +1,7 @@
 // Canonical route order — the single surface order wherever tools serialize:
 // locator → path → content → symbol → read → edit → execute.
 export const ROUTE_TOOL_ORDER = Object.freeze([
+  'explore',
   'find',
   'glob',
   'list',
@@ -44,6 +45,11 @@ export const DEFERRED_DEFAULT_FULL_TOOLS = Object.freeze([
   'read',
   'edit',
   'apply_patch',
+  // Loaded up front so looking something up never costs a load_tool hop;
+  // web_fetch stays deferred (it usually follows a search).
+  'web_search',
+  // Every session's own step list: always loaded, never a load_tool hop.
+  'todo',
   'Skill',
   'load_tool',
 ]);
@@ -54,10 +60,14 @@ export const DEFERRED_DEFAULT_READONLY_TOOLS = Object.freeze([
   'grep',
   'code_graph',
   'read',
+  'web_search',
+  'todo',
   'Skill',
   'load_tool',
 ]);
 export const DEFERRED_DEFAULT_LEAD_TOOLS = Object.freeze([
+  // Present only once Explore has a model (builtin-features.mjs).
+  'explore',
   'find',
   'glob',
   'list',
@@ -80,6 +90,8 @@ export const DEFERRED_DEFAULT_LEAD_TOOLS = Object.freeze([
   // A bot's reaction, likewise: only a bot's chat with the user has it at all
   // (session-tool-surface.mjs reactionDisabled).
   'react',
+  'web_search',
+  'todo',
   'Skill',
   'load_tool',
 ]);