mixdog 1.3.5 → 1.4.1

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

@@ -4,7 +4,11 @@
 import { clean } from './session-text.mjs';
 import { mergePendingDeferredToolDelta } from './deferred-tool-delta.mjs';
 import { applyInitialDeferredToolManifestToBp2 } from '../context/collect.mjs';
-import { listedDeferredToolNames } from '../context/deferred-tools.mjs';
+import {
+  listedDeferredToolNames,
+  mcpServerManifestLabel,
+  sanitizeMcpInstructionText,
+} from '../context/deferred-tools.mjs';
 import { parseMcpToolName } from '../../../shared/tool-primitives.mjs';
 import { getMcpServerInstructionsMap, getMcpTools, getMcpToolGeneration } from '../mcp/client.mjs';
 import { filterMcpToolsForSession } from './extension-scopes.mjs';
@@ -380,10 +384,35 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
       session.deferredDiscoveredTools || []
     );
   }
+  const catalog = surfaceCatalog(session, extraTools, options);
+  const defaultNames = surfaceDefaultNames(session, catalog, mode);
+  const selected = new Set(surfaceSelectedNames(session, catalog, defaultNames, providerMode, bridge));
+  session.deferredToolCatalog = catalog;
+  session.deferredToolUsage = MEASURED_TOOL_USAGE;
+  session.deferredDefaultTools = sortedNamesByMeasuredUsage(defaultNames);
+  session.deferredProviderMode = providerMode;
+  session.deferredNativeTools = providerMode === 'native';
+  session.deferredSurfaceMode = mode;
+  const active = installSurfaceTools(session, catalog, selected, mode, bridge);
+  session.deferredCallableTools = sortedNamesByMeasuredUsage(active);
+  if (providerMode === 'native') {
+    const restored = previousExposure === TOOL_EXPOSURE_BRIDGE ? session.nativeDeferredDiscovery || [] : [];
+    delete session.nativeDeferredDiscovery;
+    const discovered = canonicalDeferredToolNames(catalog, [...(session.deferredDiscoveredTools || []), ...restored]);
+    session.deferredSelectedTools = active;
+    session.deferredDiscoveredTools = discovered.filter((name) => !selected.has(name));
+  } else {
+    setDeferredToolState(session, active);
+  }
+  refreshSurfaceManifest(session, exposureChanged);
+  return session;
+}
+
+// The surface's catalog, rebuilt from the full catalog, not just its eager
+// projection. Current definitions still take precedence over retained
+// definitions. Bridge definitions belong to the exposure, never to the catalog.
+function surfaceCatalog(session, extraTools, options) {
   const byName = new Map();
-  // Rebuild from the full catalog, not just its eager projection. Current
-  // definitions still take precedence over retained definitions. Bridge
-  // definitions belong to the exposure, never to the catalog.
   const candidates = filterDisallowedTools(
     filterModelEditTools(
       [...session.tools, ...(extraTools || []), ...deferredCatalogUnion(session)].filter(
@@ -398,7 +427,11 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
     if (!name || byName.has(name)) continue;
     byName.set(name, activeToolForSurface(tool));
   }
-  const catalog = sortedCatalogByMeasuredUsage([...byName.values()]);
+  return sortedCatalogByMeasuredUsage([...byName.values()]);
+}
+
+// The mode's eager tools in `catalog`, less those the session keeps loadable.
+function surfaceDefaultNames(session, catalog, mode) {
   const defaultNames = defaultDeferredToolNames(catalog, mode);
   // Solo keeps `agent` in the deferred pool: loadable on request, never eager.
   // The mode the prompt was built with: a mid-conversation workflow or
@@ -413,19 +446,24 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
   for (const name of Array.isArray(session.workflowOpenedTools) ? session.workflowOpenedTools : []) {
     defaultNames.delete(name);
   }
+  return defaultNames;
+}
+
+// The names the surface selects: the session's stored selection, else the
+// defaults.
+function surfaceSelectedNames(session, catalog, defaultNames, providerMode, bridge) {
   // Bridge sessions expose the mode's core only: a stored (legacy all-selected)
   // selection never widens the wire surface, and load_tool is the bridge's own.
   const storedNames = providerMode === 'native' || bridge ? [] : storedDeferredToolNames(session);
   let selectedNames = storedNames.length ? canonicalDeferredToolNames(catalog, storedNames) : [];
   if (!selectedNames.length || providerMode === 'native') selectedNames = sortedNamesByMeasuredUsage(defaultNames);
   if (bridge) selectedNames = selectedNames.filter((name) => name !== 'load_tool');
-  const selected = new Set(selectedNames);
-  session.deferredToolCatalog = catalog;
-  session.deferredToolUsage = MEASURED_TOOL_USAGE;
-  session.deferredDefaultTools = sortedNamesByMeasuredUsage(defaultNames);
-  session.deferredProviderMode = providerMode;
-  session.deferredNativeTools = providerMode === 'native';
-  session.deferredSurfaceMode = mode;
+  return selectedNames;
+}
+
+// Replace `session.tools` with the selected definitions (plus the bridge's
+// own) and record the exposure; returns the active tool names.
+function installSurfaceTools(session, catalog, selected, mode, bridge) {
   session.tools.length = 0;
   const active = [];
   for (const tool of catalog) {
@@ -439,16 +477,12 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
   if (bridge && catalog.length) session.tools.push(...BRIDGE_SURFACE_TOOLS);
   if (bridge) session.toolExposureMode = TOOL_EXPOSURE_BRIDGE;
   else delete session.toolExposureMode;
-  session.deferredCallableTools = sortedNamesByMeasuredUsage(active);
-  if (providerMode === 'native') {
-    const restored = previousExposure === TOOL_EXPOSURE_BRIDGE ? session.nativeDeferredDiscovery || [] : [];
-    delete session.nativeDeferredDiscovery;
-    const discovered = canonicalDeferredToolNames(catalog, [...(session.deferredDiscoveredTools || []), ...restored]);
-    session.deferredSelectedTools = active;
-    session.deferredDiscoveredTools = discovered.filter((name) => !selected.has(name));
-  } else {
-    setDeferredToolState(session, active);
-  }
+  return active;
+}
+
+// Keep the system prompt's fixed deferred-tool block (BP2) and the announced
+// set in step with the surface.
+function refreshSurfaceManifest(session, exposureChanged) {
   if (exposureChanged && session.messages?.some((m) => m?.role === 'system')) {
     // Replace the previous exposure's fixed block once: the native deferred
     // manifest, or the bridge roster + guidance. History stays as is.
@@ -473,7 +507,6 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
     // the startup pool.
     session.deferredAnnouncedTools = deferredPoolToolNames(session);
   }
-  return session;
 }
 
 export function rebuildDeferredToolSurfaceForProvider(session, provider) {
@@ -669,9 +702,8 @@ function reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools) {
   const lateCatalog = Array.isArray(session.deferredLateToolCatalog) ? session.deferredLateToolCatalog : [];
   // A bridge session judges a removal by the definition it had before this
   // reconciliation (a disconnected late tool leaves the late pool below).
-  const knownBefore = isToolBridgeEnabled(session)
-    ? new Map(deferredCatalogUnion(session).map((tool) => [clean(tool?.name), tool]))
-    : null;
+  const catalogBefore = new Map(deferredCatalogUnion(session).map((tool) => [clean(tool?.name), tool]));
+  const knownBefore = isToolBridgeEnabled(session) ? catalogBefore : null;
   const active = persistentToolSurfaceNames(session);
 
   const liveMcpByName = new Map();
@@ -723,12 +755,14 @@ function reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools) {
   for (const name of previousNames) {
     if (nextNames.has(name)) continue;
     if (knownBefore && !rosterPermits(session, knownBefore.get(name) || { name })) continue;
-    removed.push(name);
+    // The server comes from the definition the session had, so a shortened
+    // name never has to be parsed.
+    removed.push({ name, server: parseMcpToolName(catalogBefore.get(name) || name)?.server || '' });
   }
   if (!added.length && !removed.length) return null;
   mergePendingDeferredToolDelta(session, { added, removed });
   session.updatedAt = Date.now();
-  return [...added.map((entry) => entry.name), ...removed];
+  return [...added, ...removed].map((entry) => entry.name);
 }
 
 /**
@@ -742,6 +776,9 @@ function reconcileDeferredMcpToolCatalogUncached(session, liveMcpTools) {
  * 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;
   if (!session || !Array.isArray(session.tools) || fixedSurfaceSession(session)) return null;
   if (!Array.isArray(session.deferredMcpToolNames) || !Array.isArray(session.deferredAnnouncedTools)) return null;
   // Listed in the boot manifest, or already loaded/discovered: still visible.
@@ -797,7 +834,8 @@ export function selectDeferredTools(session, names, mode, { exact = false } = {}
         const key = clean(raw);
         if (byName.has(key) || byName.has(key.toLowerCase())) return [key];
         const members = mcpServerSelection(catalog, key).map((tool) => clean(tool?.name));
-        return members.length ? members : [key];
+        if (members.length) return members;
+        return [key];
       });
   for (const rawName of new Set(requested)) {
     const requestedName = clean(rawName);
@@ -878,14 +916,67 @@ function resolvableCatalog(session) {
   return filterSessionToolPolicy(tools, session);
 }
 
+// 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.
+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 pending = [];
+  for (const name of names) {
+    const server = parseMcpToolName(byName.get(name) || name)?.server;
+    if (!server || announced.has(server) || !mcpServerManifestLabel(server)) continue;
+    const text = sanitizeMcpInstructionText(map[server]);
+    if (!text) continue;
+    announced.add(server);
+    pending.push({ server, block: `## ${server}\n${text}` });
+  }
+  return pending;
+}
+
+function announceMcpServers(session, pending) {
+  if (!pending.length) return;
+  session.mcpInstructionsAnnounced = [
+    ...new Set([...(session.mcpInstructionsAnnounced || []), ...pending.map((entry) => entry.server)]),
+  ];
+}
+
+function claimMcpServerInstructions(session, catalog, names) {
+  const pending = pendingMcpInstructions(session, catalog, names);
+  announceMcpServers(session, pending);
+  return pending.map((entry) => entry.block).join('\n');
+}
+
 // Pure loader. Input is exact deferred-tool names/aliases; output reports
 // loaded / already-active / missing / blocked tools PLUS pending/failed MCP
 // servers. No listing, no ranking, no substring filter. `options.mcpStatus` is
 // the runtime getter for per-server status.
 export function renderToolSearch(args = {}, session, mode = 'full', options = {}) {
   // Bridge mode: load_tool describes (bounded, paged) and never loads.
-  if (isToolBridgeEnabled(session)) return formatBridgeResult(describeBridgeTools(session, args, { mode }));
   const catalog = resolvableCatalog(session);
+  if (isToolBridgeEnabled(session)) {
+    // The page counts the instruction text inside its size budget; only the
+    // servers whose text made it into the returned page are marked announced.
+    const pendingFor = (names) => pendingMcpInstructions(session, catalog, names);
+    const described = describeBridgeTools(session, args, {
+      mode,
+      instructionsFor: (names) =>
+        pendingFor(names)
+          .map((entry) => entry.block)
+          .join('\n'),
+    });
+    if (!described.error && described.mcpInstructions) {
+      announceMcpServers(
+        session,
+        pendingFor((described.entries || []).map((entry) => clean(entry?.name)).filter(Boolean))
+      );
+    }
+    return formatBridgeResult(described);
+  }
   const requestedNames = parseToolSelection(args.names);
   const { pending: pendingMcpServers, failed: failedMcpServers } = pendingAndFailedMcpServers(options?.mcpStatus);
   const mcpFields = {
@@ -955,11 +1046,15 @@ export function renderToolSearch(args = {}, session, mode = 'full', options = {}
   if (missing.length && failedMcpServers.length) {
     notes.push('Some requested names may belong to a failed MCP server; those tools are unavailable.');
   }
+  // Tools the session already had active (loaded before, or eager) count too:
+  // their server's text may never have been delivered.
+  const mcpInstructions = claimMcpServerInstructions(session, catalog, [...loaded, ...alreadyActive]);
   return JSON.stringify(
     {
       // `selected` retained for back-compat consumers (mode is always 'select').
       selected: { mode: 'select', tools: toolSelection },
       ...(nativeToolSearch ? { nativeToolSearch } : {}),
+      ...(mcpInstructions ? { mcpInstructions } : {}),
       loaded,
       alreadyActive,
       ...(alreadyActiveSchemas.length ? { alreadyActiveSchemas } : {}),

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

@@ -115,7 +115,7 @@ export const SESSION_TOOL = {
       session_id: {
         type: 'string',
         description:
-          'ID from list; required for read/send/cancel/delete, optional for status/bots. send/cancel/delete cannot target the caller.',
+          'ID from list; required for read/send/cancel/delete, optional for status/bots. send/cancel/delete cannot target the caller. read/send/status also take a bot id (its home chat).',
       },
       prompt: { type: 'string', description: 'send: message to enqueue; loads a cold session.' },
       to: {
@@ -264,6 +264,7 @@ export function collectStandaloneToolDefs({
   visualizeToolDefs = [],
   setupToolDefs = [],
   askUserToolDefs = [],
+  handoffUserToolDefs = [],
   reactionToolDefs = [],
   goalTools = [],
   agentTools = [],
@@ -286,6 +287,7 @@ export function collectStandaloneToolDefs({
     ...admitted(visualizeToolDefs, VISUALIZE_RUNTIME_TOOLS),
     ...setupToolDefs,
     ...askUserToolDefs,
+    ...handoffUserToolDefs,
     ...reactionToolDefs,
     ...goalTools,
     ...agentTools,

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

@@ -178,8 +178,11 @@ export function webSearchRouteOrDefault(...routeLikes) {
   });
 }
 
-export function normalizeWorkflowRoute(routeLike, fallback = {}) {
-  return normalizeRouteChain(routeLike, normalizeWorkflowRouteLeaf, fallback);
+// A stored chain may hold a fallback on the main model's own provider (inactive,
+// see executionFallbacks), so reading and re-saving it is lenient; a route the
+// user saves directly passes `{ strict: true }`.
+export function normalizeWorkflowRoute(routeLike, fallback = {}, { strict = false } = {}) {
+  return normalizeRouteChain(routeLike, normalizeWorkflowRouteLeaf, fallback, { strict });
 }
 
 function normalizeWorkflowRouteLeaf(routeLike, fallback = {}) {

package/src/runtime/agent/orchestrator/session/cache/scoped-cache.mjs

@@ -4,9 +4,7 @@
 // touched path; unknown paths still fall back to a full session clear.
 import { join, resolve as _pathResolve, isAbsolute as _pathIsAbs, normalize as _pathNorm } from 'node:path';
 import { _normalizeCacheKey } from './util.mjs';
-import {
-  hasGlobMagic,
-} from '../../tools/builtin/path-utils.mjs';
+import { hasGlobMagic } from '../../tools/builtin/path-utils.mjs';
 import { prepareGrepArgs } from '../../tools/builtin/arg-guard.mjs';
 import { registerCacheInvalidationListener } from '../../tools/builtin/cache-layers.mjs';
 import { setBoundedTextCacheEntry } from './text-cache-budget.mjs';