mixdog 0.9.62 → 0.9.64

package/src/session-runtime/provider-request-snapshot.mjs

@@ -0,0 +1,338 @@
+// Provider request-tool resolution + JSON-safe snapshot machinery, extracted from tool-catalog.mjs.
+import { clean, LATE_TOOL_ANNOUNCEMENT_SENTINEL } from './session-text.mjs';
+import { estimateToolSchemaTokens, toolSchemaSignature } from '../runtime/agent/orchestrator/session/context-utils.mjs';
+import {
+  applyInitialDeferredToolManifestToBp1,
+  buildDeferredToolManifest,
+  stripDeferredToolManifestBlock,
+} from '../runtime/agent/orchestrator/context/collect.mjs';
+import { getMcpServerInstructionsMap } from '../runtime/agent/orchestrator/mcp/client.mjs';
+import {
+  isResponsesFreeformTool,
+  toResponsesCustomTool,
+} from '../runtime/agent/orchestrator/providers/custom-tool-wire.mjs';
+import {
+  finalizeProviderRequestTools,
+  providerNativeToolPrefixCount,
+} from './provider-request-tools.mjs';
+import {
+  DEFERRED_DEFAULT_FULL_TOOLS,
+  DEFERRED_DEFAULT_LEAD_TOOLS,
+  DEFERRED_DEFAULT_READONLY_TOOLS,
+  DEFERRED_SELECT_ALIASES,
+  MEASURED_TOOL_ORDER,
+  MEASURED_TOOL_USAGE,
+  READONLY_TOOL_NAMES,
+} from './tool-catalog-data.mjs';
+import { parseToolSelection, ANTHROPIC_NATIVE_PROVIDERS } from './tool-catalog-schema.mjs';
+
+export function resolveProviderRequestTools({
+  provider,
+  tools,
+  messages,
+  session,
+} = {}) {
+  const activeTools = Array.isArray(tools) ? tools : [];
+  const normalizedProvider = clean(provider || session?.provider).toLowerCase();
+  if (!ANTHROPIC_NATIVE_PROVIDERS.has(normalizedProvider)
+    || session?.deferredNativeTools !== true
+    || activeTools.length === 0) {
+    return activeTools;
+  }
+  const discovered = new Set(
+    parseToolSelection(session?.deferredDiscoveredTools),
+  );
+  for (const message of Array.isArray(messages) ? messages : []) {
+    const native = message?.nativeToolSearch;
+    const source = clean(native?.provider).toLowerCase();
+    if (source && source !== normalizedProvider
+      && !(ANTHROPIC_NATIVE_PROVIDERS.has(source)
+        && ANTHROPIC_NATIVE_PROVIDERS.has(normalizedProvider))) continue;
+    for (const name of parseToolSelection(native?.toolReferences)) discovered.add(name);
+  }
+  if (discovered.size === 0) return activeTools;
+  const activeNames = new Set(activeTools.map((tool) => clean(tool?.name)).filter(Boolean));
+  const catalog = Array.isArray(session?.deferredToolCatalog) ? session.deferredToolCatalog : [];
+  const deferredTools = catalog
+    .filter((tool) => {
+      const name = clean(tool?.name);
+      return name && discovered.has(name) && !activeNames.has(name);
+    })
+    .map((tool) => ({ ...tool, deferLoading: true }));
+  return deferredTools.length ? [...activeTools, ...deferredTools] : activeTools;
+}
+
+const OMIT_REQUEST_TOOL_VALUE = Symbol('omit-request-tool-value');
+const MAX_PROVIDER_SNAPSHOT_ARRAY_LENGTH = 1_000_000;
+
+function defineEnumerableDataProperty(target, key, value) {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    configurable: false,
+    writable: false,
+  });
+}
+
+function boxedJsonPrimitive(value) {
+  try { return { matched: true, value: Number.prototype.valueOf.call(value) }; } catch {}
+  try { return { matched: true, value: String.prototype.valueOf.call(value) }; } catch {}
+  try { return { matched: true, value: Boolean.prototype.valueOf.call(value) }; } catch {}
+  try { return { matched: true, value: BigInt.prototype.valueOf.call(value) }; } catch {}
+  return { matched: false, value: null };
+}
+
+function providerSnapshotLengthPrimitive(value) {
+  if ((typeof value !== 'object' || value === null) && typeof value !== 'function') return value;
+  const exotic = value[Symbol.toPrimitive];
+  if (exotic !== undefined && exotic !== null) {
+    if (typeof exotic !== 'function') throw new TypeError('invalid length primitive');
+    const primitive = exotic.call(value, 'number');
+    if ((typeof primitive === 'object' && primitive !== null) || typeof primitive === 'function') {
+      throw new TypeError('invalid length primitive');
+    }
+    return primitive;
+  }
+  for (const methodName of ['valueOf', 'toString']) {
+    const method = value[methodName];
+    if (typeof method !== 'function') continue;
+    const primitive = method.call(value);
+    if ((typeof primitive !== 'object' || primitive === null) && typeof primitive !== 'function') {
+      return primitive;
+    }
+  }
+  throw new TypeError('invalid length primitive');
+}
+
+function providerSnapshotArrayLength(rawLength) {
+  let primitive;
+  let numeric;
+  try {
+    primitive = providerSnapshotLengthPrimitive(rawLength);
+    if (typeof primitive === 'bigint' || typeof primitive === 'symbol') {
+      throw new TypeError('invalid length primitive');
+    }
+    numeric = Number(primitive);
+  } catch {
+    throw new TypeError('provider tool snapshot: invalid array length');
+  }
+  if (Number.isNaN(numeric) || numeric <= 0) return 0;
+  if (!Number.isFinite(numeric)) {
+    throw new RangeError(
+      `provider tool snapshot: array length exceeds safe limit ${MAX_PROVIDER_SNAPSHOT_ARRAY_LENGTH}`,
+    );
+  }
+  const effectiveLength = Math.floor(numeric);
+  if (effectiveLength > MAX_PROVIDER_SNAPSHOT_ARRAY_LENGTH) {
+    throw new RangeError(
+      `provider tool snapshot: array length exceeds safe limit ${MAX_PROVIDER_SNAPSHOT_ARRAY_LENGTH}`,
+    );
+  }
+  return effectiveLength;
+}
+
+function normalizeRequestToolJson(value, state, {
+  arrayEntry = false,
+  key = '',
+  applyToJSON = true,
+  seededProperties = null,
+} = {}) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  if (typeof value === 'bigint') {
+    throw new TypeError('provider tool snapshot: BigInt is not JSON-serializable');
+  }
+  if (value === undefined || typeof value === 'function' || typeof value === 'symbol') {
+    return arrayEntry ? null : OMIT_REQUEST_TOOL_VALUE;
+  }
+  if (typeof value !== 'object') {
+    throw new TypeError(`provider tool snapshot: unsupported JSON value type ${typeof value}`);
+  }
+  if (state.active.has(value)) {
+    throw new TypeError('provider tool snapshot: cyclic value is not JSON-serializable');
+  }
+  if (state.memo.has(value)) return state.memo.get(value);
+
+  let capturedProperties = seededProperties;
+  if (applyToJSON) {
+    // JSON reads `toJSON` once before serializing an object. Preserve that
+    // single observation for an own-enumerable non-function (and for a
+    // callable that returns `this`) so property traversal cannot invoke a
+    // stateful accessor a second time.
+    const toJSONDescriptor = Object.getOwnPropertyDescriptor(value, 'toJSON');
+    const toJSON = value.toJSON;
+    if (typeof toJSON === 'function') {
+      // Keep the source guarded through both hook execution and replacement
+      // normalization. A hook returning itself, or any replacement graph that
+      // points back to its source, is a JSON cycle rather than another hook
+      // invocation.
+      state.active.add(value);
+      try {
+        const replacement = toJSON.call(value, key);
+        const normalized = normalizeRequestToolJson(replacement, state, {
+          arrayEntry,
+          key,
+          applyToJSON: false,
+          seededProperties: null,
+        });
+        state.memo.set(value, normalized);
+        return normalized;
+      } finally {
+        state.active.delete(value);
+      }
+    }
+    if (toJSONDescriptor?.enumerable) {
+      capturedProperties = { ...(seededProperties || {}), toJSON };
+    }
+  }
+  const boxed = boxedJsonPrimitive(value);
+  if (boxed.matched) {
+    return normalizeRequestToolJson(boxed.value, state, { arrayEntry, key });
+  }
+
+  const isArray = Array.isArray(value);
+  const normalized = isArray ? [] : {};
+  state.active.add(value);
+  try {
+    if (isArray) {
+      // JSON.stringify captures array length once. Accessors may mutate the
+      // source array, but they cannot extend or shorten this iteration bound.
+      const rawLength = value.length;
+      const length = providerSnapshotArrayLength(rawLength);
+      for (let index = 0; index < length; index += 1) {
+        const entry = value[index];
+        normalized.push(normalizeRequestToolJson(entry, state, {
+          arrayEntry: true,
+          key: String(index),
+        }));
+      }
+    } else {
+      // JSON-compatible request schemas are own-enumerable data. Normalize class
+      // instances/accessors to a plain record, ignore inherited mutable fields,
+      // and define keys explicitly so an own "__proto__" remains ordinary data.
+      for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== 'string') continue;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor?.enumerable) continue;
+        // Deferred catalog selection captures `name` once before touching the
+        // candidate schema. Seed that captured value here so a stateful/throwing
+        // getter is never observed a second time during JSON normalization.
+        const entry = capturedProperties && Object.hasOwn(capturedProperties, key)
+          ? capturedProperties[key]
+          : value[key];
+        const child = normalizeRequestToolJson(entry, state, { key });
+        if (child !== OMIT_REQUEST_TOOL_VALUE) defineEnumerableDataProperty(normalized, key, child);
+      }
+    }
+  } finally {
+    state.active.delete(value);
+  }
+  Object.freeze(normalized);
+  state.memo.set(value, normalized);
+  return normalized;
+}
+
+// Establish one immutable request-attempt snapshot. Nested schema records are
+// cloned before freezing, so a catalog refresh or in-place schema mutation
+// after this boundary cannot change either provider bytes or their signature.
+export function snapshotProviderRequestTools(options = {}) {
+  const {
+    provider,
+    tools,
+    nativeTools,
+    messages,
+    session,
+  } = options;
+  const activeTools = Array.isArray(tools) ? tools : [];
+  const state = { active: new WeakSet(), memo: new WeakMap() };
+  const snapshots = [];
+  const names = new Set();
+  const activeCandidateRefs = new WeakSet();
+  // Anthropic native definitions are already provider-wire objects. Preserve
+  // their prior prepend order and duplicate behavior, but freeze the exact
+  // bytes into the same request snapshot used for accounting and retries.
+  if (ANTHROPIC_NATIVE_PROVIDERS.has(clean(provider || session?.provider).toLowerCase())) {
+    for (const nativeTool of Array.isArray(nativeTools) ? nativeTools : []) {
+      if (!nativeTool || typeof nativeTool !== 'object') continue;
+      const normalized = normalizeRequestToolJson(nativeTool, state);
+      if (normalized && typeof normalized === 'object' && !Array.isArray(normalized)) {
+        snapshots.push(normalized);
+      }
+    }
+  }
+  const nativePrefixCount = snapshots.length;
+  const finish = () => finalizeProviderRequestTools(snapshots, nativePrefixCount);
+  const appendSnapshot = (candidate, selectedName = null, deferred = false) => {
+    const normalized = normalizeRequestToolJson(candidate, state, {
+      seededProperties: selectedName === null ? null : { name: selectedName },
+    });
+    if (deferred && (
+      !normalized
+      || typeof normalized !== 'object'
+      || Array.isArray(normalized)
+      || typeof normalized.name !== 'string'
+      || !clean(normalized.name)
+      || normalized.name !== selectedName
+    )) {
+      throw new TypeError(`provider tool snapshot: selected tool identity mismatch for ${JSON.stringify(selectedName)}`);
+    }
+    if (!normalized || typeof normalized !== 'object' || Array.isArray(normalized)) return;
+    const name = clean(normalized.name);
+    if (!name || names.has(name)) return;
+    names.add(name);
+    if (!deferred) {
+      snapshots.push(normalized);
+      return;
+    }
+    const deferredSnapshot = {};
+    for (const key of Object.keys(normalized)) {
+      if (key === 'deferLoading' || key === 'defer_loading') continue;
+      defineEnumerableDataProperty(deferredSnapshot, key, normalized[key]);
+    }
+    defineEnumerableDataProperty(deferredSnapshot, 'deferLoading', true);
+    snapshots.push(Object.freeze(deferredSnapshot));
+  };
+
+  // Active candidates are provider-visible by definition: normalize each once,
+  // then perform all validation/dedupe from the plain snapshot only.
+  for (const tool of activeTools) {
+    if (tool && typeof tool === 'object') activeCandidateRefs.add(tool);
+    appendSnapshot(tool);
+  }
+
+  const normalizedProvider = clean(provider || session?.provider).toLowerCase();
+  if (!ANTHROPIC_NATIVE_PROVIDERS.has(normalizedProvider)
+    || session?.deferredNativeTools !== true
+    // Native definitions preserve their historical prepend behavior, but they
+    // do not make an otherwise all-deferred catalog eligible for expansion.
+    || names.size === 0) {
+    return finish();
+  }
+  const discovered = new Set(parseToolSelection(session?.deferredDiscoveredTools));
+  for (const message of Array.isArray(messages) ? messages : []) {
+    const native = message?.nativeToolSearch;
+    const source = clean(native?.provider).toLowerCase();
+    if (source && source !== normalizedProvider
+      && !(ANTHROPIC_NATIVE_PROVIDERS.has(source)
+        && ANTHROPIC_NATIVE_PROVIDERS.has(normalizedProvider))) continue;
+    for (const name of parseToolSelection(native?.toolReferences)) discovered.add(name);
+  }
+  if (discovered.size === 0) return finish();
+
+  // Catalog arrays have no separate key map, so `name` is their explicit
+  // selection key contract: capture it once, skip undiscovered/duplicate
+  // entries without touching schemas, and seed selected normalization with the
+  // captured value to avoid a second getter evaluation.
+  const seenCatalogRefs = new WeakSet();
+  for (const tool of Array.isArray(session?.deferredToolCatalog) ? session.deferredToolCatalog : []) {
+    if (tool && typeof tool === 'object') {
+      if (activeCandidateRefs.has(tool) || seenCatalogRefs.has(tool)) continue;
+      seenCatalogRefs.add(tool);
+    }
+    const capturedName = tool?.name;
+    const selectionName = typeof capturedName === 'string' ? clean(capturedName) : '';
+    if (!selectionName || !discovered.has(selectionName) || names.has(selectionName)) continue;
+    appendSnapshot(tool, capturedName, true);
+  }
+  return finish();
+}

package/src/session-runtime/session-text.mjs

@@ -42,14 +42,14 @@ const SYNTHETIC_SESSION_TEXT_PATTERNS = Object.freeze([
   /^the async (?:agent|shell) task\b/i,
 ]);
 
-export function stripSessionDisplayEnvelope(value) {
+function stripSessionDisplayEnvelope(value) {
   return String(value ?? '')
     .replace(/^# Session\r?\n(?:(?:Cwd|Model|Workflow):[^\r\n]*(?:\r?\n|$))+(?:\r?\n)?/i, '')
     .replace(/^#\s*Session\s+Cwd:\s+.*?\s+Model:\s+.*?\s+Workflow:\s+\S+\s*/i, '')
     .replace(/^#\s*Session\s+Cwd:\s+\S+(?:\s+Model:\s+\S*)?(?:\s+Workflow:\s+\S*)?\s*/i, '');
 }
 
-export function stripInjectedSessionText(value) {
+function stripInjectedSessionText(value) {
   let text = String(value ?? '');
   for (const tag of INJECTED_DISPLAY_BLOCK_TAGS) {
     const block = new RegExp(`<${tag}\\b[^>]*>[\\s\\S]*?(?:<\\/${tag}\\s*>|$)`, 'gi');
@@ -59,7 +59,7 @@ export function stripInjectedSessionText(value) {
   return text;
 }
 
-export function isSyntheticSessionText(text) {
+function isSyntheticSessionText(text) {
   const value = String(text || '').trim();
   return SYNTHETIC_SESSION_TEXT_PATTERNS.some((pattern) => pattern.test(value));
 }
@@ -102,7 +102,7 @@ export function isLateToolAnnouncement(text) {
 // "MCP tools available: UnityMCP (12 tools)". MCP tool entries in the manifest
 // are `- mcp__<server>__<tool>: ...` lines; the server name is the segment
 // after the `mcp__` prefix. Returns '' for non-announcement text.
-export function summarizeLateToolAnnouncement(text) {
+function summarizeLateToolAnnouncement(text) {
   const value = String(text || '');
   if (!isLateToolAnnouncement(value)) return '';
   const block = value.match(/<available-deferred-tools>([\s\S]*?)<\/available-deferred-tools>/i);

package/src/session-runtime/tool-catalog-schema.mjs

@@ -0,0 +1,197 @@
+// Tool schema/kind classification + measured-usage ordering, extracted from tool-catalog.mjs.
+import { clean, LATE_TOOL_ANNOUNCEMENT_SENTINEL } from './session-text.mjs';
+import { estimateToolSchemaTokens, toolSchemaSignature } from '../runtime/agent/orchestrator/session/context-utils.mjs';
+import {
+  applyInitialDeferredToolManifestToBp1,
+  buildDeferredToolManifest,
+  stripDeferredToolManifestBlock,
+} from '../runtime/agent/orchestrator/context/collect.mjs';
+import { getMcpServerInstructionsMap } from '../runtime/agent/orchestrator/mcp/client.mjs';
+import {
+  isResponsesFreeformTool,
+  toResponsesCustomTool,
+} from '../runtime/agent/orchestrator/providers/custom-tool-wire.mjs';
+import {
+  finalizeProviderRequestTools,
+  providerNativeToolPrefixCount,
+} from './provider-request-tools.mjs';
+import {
+  DEFERRED_DEFAULT_FULL_TOOLS,
+  DEFERRED_DEFAULT_LEAD_TOOLS,
+  DEFERRED_DEFAULT_READONLY_TOOLS,
+  DEFERRED_SELECT_ALIASES,
+  MEASURED_TOOL_ORDER,
+  MEASURED_TOOL_USAGE,
+  READONLY_TOOL_NAMES,
+} from './tool-catalog-data.mjs';
+
+const toolSchemaBreakdownMemo = new WeakMap();
+
+function sameToolSchemaEntries(cached, tools) {
+  if (!cached || cached.entries.length !== tools.length) return false;
+  const nativePrefixCount = providerNativeToolPrefixCount(tools);
+  for (let index = 0; index < tools.length; index += 1) {
+    const entry = cached.entries[index];
+    const tool = tools[index];
+    if (entry.tool !== tool
+      || entry.name !== tool?.name
+      || entry.description !== tool?.description
+      || entry.inputSchema !== tool?.inputSchema
+      || entry.input_schema !== tool?.input_schema
+      || entry.parameters !== tool?.parameters
+      || entry.schema !== tool?.schema
+      || entry.deferLoading !== tool?.deferLoading
+      || entry.defer_loading !== tool?.defer_loading
+      || entry.annotationsMixdogKind !== tool?.annotations?.mixdogKind
+      || entry.annotationsAgentHidden !== tool?.annotations?.agentHidden
+      || entry.native !== (index < nativePrefixCount)
+      || entry.wireSignature !== toolSchemaSignature(toolMeteringList(tool, index < nativePrefixCount))) return false;
+  }
+  return true;
+}
+
+function toolMeteringList(tool, native) {
+  return native ? finalizeProviderRequestTools([tool], 1) : [tool];
+}
+
+function toolSchemaEntry(tool, native = false) {
+  return {
+    tool,
+    name: tool?.name,
+    description: tool?.description,
+    inputSchema: tool?.inputSchema,
+    input_schema: tool?.input_schema,
+    parameters: tool?.parameters,
+    schema: tool?.schema,
+    deferLoading: tool?.deferLoading,
+    defer_loading: tool?.defer_loading,
+    annotationsMixdogKind: tool?.annotations?.mixdogKind,
+    annotationsAgentHidden: tool?.annotations?.agentHidden,
+    native,
+    wireSignature: toolSchemaSignature(toolMeteringList(tool, native)),
+  };
+}
+export function toolKind(tool) {
+  const name = clean(tool?.name);
+  if (name.startsWith('mcp__')) return 'mcp';
+  if (name.startsWith('skill:') || tool?.annotations?.mixdogKind === 'skill') return 'skill';
+  if (name === 'Skill' || name.startsWith('skill_') || name === 'skills_list' || name === 'skill_view') return 'skill';
+  if (tool?.annotations?.agentHidden) return 'control';
+  if (['apply_patch', 'shell'].includes(name)) return 'mutation';
+  return 'tool';
+}
+
+export function toolSchemaBucket(tool) {
+  const name = clean(tool?.name);
+  const kind = toolKind(tool);
+  if (kind === 'mcp') return 'mcp';
+  if (kind === 'skill') return 'skills';
+  if (name === 'memory' || name === 'recall' || name.includes('memory')) return 'memory';
+  if (name === 'search' || name === 'web_fetch') return 'web';
+  if (['read', 'grep', 'find', 'glob', 'list', 'code_graph', 'explore'].includes(name)) return 'code';
+  if (['shell', 'apply_patch'].includes(name)) return 'mutation';
+  if (name === 'agent' || name === 'delegate') return 'agents';
+  if (name === 'session_manage') return 'session';
+  if (name.includes('channel') || name.includes('discord') || name.includes('webhook')) return 'channels';
+  if (name.includes('provider') || name === 'load_tool' || name === 'tool_search' || name === 'cwd') return 'setup';
+  if (kind === 'control') return 'control';
+  return 'other';
+}
+
+export function estimateToolSchemaBreakdown(tools) {
+  if (Array.isArray(tools)) {
+    const cached = toolSchemaBreakdownMemo.get(tools);
+    if (sameToolSchemaEntries(cached, tools)) return cached.value;
+  }
+  const out = {};
+  const list = Array.isArray(tools) ? tools : [];
+  const nativePrefixCount = providerNativeToolPrefixCount(list);
+  for (let index = 0; index < list.length; index += 1) {
+    const tool = list[index];
+    const bucket = toolSchemaBucket(tool);
+    const row = out[bucket] || { count: 0, tokens: 0 };
+    row.count += 1;
+    row.tokens += estimateToolSchemaTokens(toolMeteringList(tool, index < nativePrefixCount));
+    out[bucket] = row;
+  }
+  if (Array.isArray(tools)) {
+    toolSchemaBreakdownMemo.set(tools, {
+      entries: tools.map((tool, index) => toolSchemaEntry(tool, index < nativePrefixCount)),
+      value: out,
+    });
+  }
+  return out;
+}
+
+export function measuredToolUsage(name) {
+  return MEASURED_TOOL_USAGE[clean(name)] || 0;
+}
+
+export function parseToolSelection(value) {
+  if (Array.isArray(value)) return value.map(clean).filter(Boolean);
+  if (value && typeof value !== 'string' && typeof value[Symbol.iterator] === 'function') {
+    return [...value].map(clean).filter(Boolean);
+  }
+  return String(value || '').replace(/^select\s*:/i, '')
+    .split(/[,\s]+/)
+    .map(clean)
+    .filter(Boolean);
+}
+
+export function parseToolSearchQuerySelection(query) {
+  const match = clean(query).match(/^select\s*:\s*(.+)$/i);
+  return match ? parseToolSelection(match[1]) : [];
+}
+
+export function measuredToolRank(name) {
+  const index = MEASURED_TOOL_ORDER.indexOf(clean(name));
+  return index === -1 ? Number.MAX_SAFE_INTEGER : index;
+}
+
+export function sortedCatalogByMeasuredUsage(catalog) {
+  return (catalog || [])
+    .map((tool, index) => ({ tool, index }))
+    .sort((a, b) => {
+      const au = measuredToolUsage(a.tool?.name);
+      const bu = measuredToolUsage(b.tool?.name);
+      if (bu !== au) return bu - au;
+      const ar = measuredToolRank(a.tool?.name);
+      const br = measuredToolRank(b.tool?.name);
+      if (ar !== br) return ar - br;
+      return a.index - b.index;
+    })
+    .map((entry) => entry.tool);
+}
+
+export function activeToolForSurface(tool) {
+  if (!tool || typeof tool !== 'object') return tool;
+  return JSON.parse(JSON.stringify(tool));
+}
+
+export function deferredProviderMode(provider) {
+  const p = clean(provider).toLowerCase();
+  if (p === 'gemini') return 'manifest';
+  if (p === 'anthropic' || p === 'anthropic-oauth'
+    || p === 'openai' || p === 'openai-oauth') {
+    return 'native';
+  }
+  // xAI/Grok and every other OpenAI-compatible backend have no native
+  // tool_search/tool_search_output contract. Give them one complete canonical
+  // function array instead of a load-driven array whose bytes churn.
+  return 'canonical';
+}
+
+export function nativeProviderFamily(provider) {
+  const p = clean(provider).toLowerCase();
+  if (p === 'openai' || p === 'openai-oauth') return 'openai';
+  if (p === 'anthropic' || p === 'anthropic-oauth') return 'anthropic';
+  return '';
+}
+
+export const ANTHROPIC_NATIVE_PROVIDERS = new Set(['anthropic', 'anthropic-oauth']);
+
+// Pure projection of the tool definitions that the next provider request will
+// serialize. Anthropic's native deferred surface sends the base active tools
+// plus only definitions that have actually been discovered through the
+// session/native tool-search history. Every other provider already receives
+// its canonical/native surface in `tools`, so preserve that array verbatim.