mixdog 0.9.152 → 0.9.154

package/src/runtime/agent/orchestrator/agent-runtime/agent-dispatch.mjs

@@ -179,20 +179,128 @@ function maintenanceRouteToPreset(routeOrName, agent) {
     return out;
 }
 
+const AGENT_DISPATCH_LIVE_CALLBACKS = Object.freeze([
+    'onSessionStart',
+    'onStageChange',
+    'onReasoningDelta',
+    'onTextDelta',
+    'onTextReset',
+    'onAssistantText',
+    'onAssistantMessageCommitted',
+    'onToolCall',
+    'onToolResult',
+]);
+
+function pickDispatchCallback(factoryOpts, callArgs, name) {
+    if (typeof callArgs?.[name] === 'function') return callArgs[name];
+    if (typeof factoryOpts?.[name] === 'function') return factoryOpts[name];
+    return undefined;
+}
+
 /**
- * Build an agent-backed dispatch callback.
+ * Resolve live Agent-dispatch callbacks.
  *
- * @param {object} opts
- * @param {string} opts.agent       — REQUIRED; canonical agent name (worker, cycle1-agent, ...)
- * @param {string} [opts.taskType]  — optional internal classification stamped on the session
- * @param {string} [opts.preset]    — explicit preset override (bypasses agent → preset lookup)
- * @param {string} [opts.parentSessionId] — parent agent session for trace aggregation
- * @param {string|null} [opts.ownerSessionId] — owning Mixdog session for statusline isolation
- * @param {AbortSignal} [opts.parentSignal] — optional AbortSignal from the fan-out coordinator;
- *   when aborted the agent session's own controller is also aborted so the
- *   provider call tears down promptly (parent→child cascade).
- * @returns {(args: { prompt, preset?, sourceName? }) => Promise<string>}
+ * `liveProjection` is a send-opt. It is true when the caller explicitly
+ * sets it or supplies a live-text callback (onTextDelta / onAssistantText /
+ * onTextReset). Tool/stage/reasoning observers do not un-suppress provider
+ * streaming. The flag must never be written onto the session object.
+ *
+ * @param {object} [factoryOpts]
+ * @param {object} [callArgs]
+ * @returns {{ callbacks: object, liveProjection: boolean }}
+ */
+export function resolveAgentDispatchLiveCallbacks(factoryOpts = {}, callArgs = {}) {
+    const callbacks = {};
+    for (const name of AGENT_DISPATCH_LIVE_CALLBACKS) {
+        const fn = pickDispatchCallback(factoryOpts, callArgs, name);
+        if (fn) callbacks[name] = fn;
+    }
+    const liveProjection = factoryOpts.liveProjection === true
+        || callArgs.liveProjection === true
+        || typeof callbacks.onTextDelta === 'function'
+        || typeof callbacks.onAssistantText === 'function'
+        || typeof callbacks.onTextReset === 'function';
+    return { callbacks, liveProjection };
+}
+
+/**
+ * Adapt askSession's session-less callback signatures to the host contract
+ * by prepending the prepared session on every call:
+ *   onSessionStart(session)
+ *   onStageChange(session, stage, detail)
+ *   onReasoningDelta(session, chunk)
+ *   onTextDelta(session, chunk)
+ *   onTextReset(session, detail)  — return value is passed through unchanged
+ *   onAssistantText(session, text)
+ *   onAssistantMessageCommitted(session)
+ *   onToolCall(session, iteration, calls)
+ *   onToolResult(session, message)
+ */
+export function bindAgentDispatchHostCallbacks(hostCallbacks = {}, session) {
+    const bound = {};
+    if (typeof hostCallbacks.onSessionStart === 'function') {
+        bound.onSessionStart = () => hostCallbacks.onSessionStart(session);
+    }
+    if (typeof hostCallbacks.onStageChange === 'function') {
+        bound.onStageChange = (stage, detail) => hostCallbacks.onStageChange(session, stage, detail);
+    }
+    if (typeof hostCallbacks.onReasoningDelta === 'function') {
+        bound.onReasoningDelta = (chunk) => hostCallbacks.onReasoningDelta(session, chunk);
+    }
+    if (typeof hostCallbacks.onTextDelta === 'function') {
+        bound.onTextDelta = (chunk) => hostCallbacks.onTextDelta(session, chunk);
+    }
+    if (typeof hostCallbacks.onTextReset === 'function') {
+        bound.onTextReset = (detail) => hostCallbacks.onTextReset(session, detail);
+    }
+    if (typeof hostCallbacks.onAssistantText === 'function') {
+        bound.onAssistantText = (text) => hostCallbacks.onAssistantText(session, text);
+    }
+    if (typeof hostCallbacks.onAssistantMessageCommitted === 'function') {
+        bound.onAssistantMessageCommitted = () => hostCallbacks.onAssistantMessageCommitted(session);
+    }
+    if (typeof hostCallbacks.onToolCall === 'function') {
+        bound.onToolCall = (iteration, calls) => hostCallbacks.onToolCall(session, iteration, calls);
+    }
+    if (typeof hostCallbacks.onToolResult === 'function') {
+        bound.onToolResult = (message) => hostCallbacks.onToolResult(session, message);
+    }
+    return bound;
+}
+
+/**
+ * Build the positional `onToolCall` + askOpts bag forwarded to askSession.
+ * `interactiveSessionSurface` is intentionally dropped — that in-memory
+ * hint is owned by the standalone surface and must not be persisted or
+ * re-homed onto a dispatch session.
  */
+export function buildAgentDispatchAskSessionArgs(factoryOpts = {}, callArgs = {}, extraAskOpts = {}, session = null) {
+    const { callbacks, liveProjection } = resolveAgentDispatchLiveCallbacks(factoryOpts, callArgs);
+    const bound = session && typeof session === 'object'
+        ? bindAgentDispatchHostCallbacks(callbacks, session)
+        : callbacks;
+    const onToolCall = typeof bound.onToolCall === 'function' ? bound.onToolCall : null;
+    const askOpts = { liveProjection };
+    for (const name of AGENT_DISPATCH_LIVE_CALLBACKS) {
+        if (name === 'onToolCall') continue;
+        if (typeof bound[name] === 'function') askOpts[name] = bound[name];
+    }
+    const extraCompact = extraAskOpts.onCompactEvent;
+    if (typeof extraCompact === 'function') {
+        const callerCompact = askOpts.onCompactEvent;
+        askOpts.onCompactEvent = (event) => {
+            extraCompact(event);
+            try { callerCompact?.(event); } catch { /* best-effort */ }
+        };
+    }
+    for (const [key, value] of Object.entries(extraAskOpts)) {
+        if (key === 'onCompactEvent' || key === 'liveProjection') continue;
+        if (key === 'interactiveSessionSurface') continue;
+        if (value !== undefined) askOpts[key] = value;
+    }
+    return { onToolCall, askOpts };
+}
+
 // runtime-liveness keeps one parent link per session because askSession swaps
 // its controller at turn start.  Agent dispatch can have several independent
 // cancellation sources, so collapse them before installing that one link.
@@ -227,16 +335,59 @@ export function composeAgentDispatchAbortSignal(signals) {
     };
 }
 
+/**
+ * Build an agent-backed dispatch callback.
+ *
+ * @param {object} opts
+ * @param {string} opts.agent       — REQUIRED; canonical agent name (worker, cycle1-agent, ...)
+ * @param {string} [opts.taskType]  — optional internal classification stamped on the session
+ * @param {string} [opts.preset]    — explicit preset override (bypasses agent → preset lookup)
+ * @param {string} [opts.parentSessionId] — parent agent session for trace aggregation
+ * @param {string|null} [opts.ownerSessionId] — owning Mixdog session for statusline isolation
+ * @param {AbortSignal} [opts.parentSignal] — optional AbortSignal from the fan-out coordinator;
+ *   when aborted the agent session's own controller is also aborted so the
+ *   provider call tears down promptly (parent→child cascade).
+ * @param {boolean} [opts.liveProjection] — request provider onTextDelta / mid-turn
+ *   text for this Agent. Never persisted on the session.
+ * @param {function} [opts.onSessionStart]
+ * @param {function} [opts.onStageChange]
+ * @param {function} [opts.onReasoningDelta]
+ * @param {function} [opts.onTextDelta]
+ * @param {function} [opts.onTextReset] — must return `true` to ack a retry retraction
+ * @param {function} [opts.onAssistantText]
+ * @param {function} [opts.onAssistantMessageCommitted]
+ * @param {function} [opts.onToolCall]
+ * @param {function} [opts.onToolResult]
+ * @returns {(args: { prompt, preset?, sourceName?, liveProjection?, onSessionStart?, onStageChange?, onReasoningDelta?, onTextDelta?, onTextReset?, onAssistantText?, onAssistantMessageCommitted?, onToolCall?, onToolResult? }) => Promise<string>}
+ */
 export function makeAgentDispatch(opts = {}) {
     if (!opts.agent || typeof opts.agent !== 'string') {
         throw new Error('[agent-dispatch] opts.agent is required');
     }
     const agent = opts.agent;
 
-    return async function agentDispatch({ prompt, preset: presetArg, sourceName: sourceNameArg, parentSignal: callParentSignal, idleTimeoutMs: callIdleTimeoutMs, cwd: callCwd, sessionId: callSessionId }) {
+    return async function agentDispatch(callArgs = {}) {
+        const {
+            prompt,
+            preset: presetArg,
+            sourceName: sourceNameArg,
+            parentSignal: callParentSignal,
+            idleTimeoutMs: callIdleTimeoutMs,
+            cwd: callCwd,
+            sessionId: callSessionId,
+        } = callArgs;
         if (typeof prompt !== 'string' || !prompt) {
             throw new Error(`[agent-dispatch] prompt required for agent "${agent}"`);
         }
+        const prepare = typeof opts.prepareAgentSession === 'function'
+            ? opts.prepareAgentSession
+            : prepareAgentSession;
+        const ask = typeof opts.askSession === 'function' ? opts.askSession : askSession;
+        const updateStatus = typeof opts.updateSessionStatus === 'function'
+            ? opts.updateSessionStatus
+            : updateSessionStatus;
+        const close = typeof opts.closeSession === 'function' ? opts.closeSession : closeSession;
+        const readSession = typeof opts.getSession === 'function' ? opts.getSession : getSession;
         const admission = opts.resourceAdmission || resourceAdmission;
         const admissionAbortLink = composeAgentDispatchAbortSignal([
             opts.parentSignal,
@@ -334,7 +485,7 @@ export function makeAgentDispatch(opts = {}) {
         // pooled or resumed. Cache prefix matching happens at the provider
         // layer (account-level), not the session level.
         const finalPrompt = prompt;
-        const { session } = prepareAgentSession({
+        const { session } = prepare({
             agent,
             presetName,
             preset,
@@ -359,7 +510,7 @@ export function makeAgentDispatch(opts = {}) {
             process.stderr.write(`[agent-dispatch] agent=${agent} tool-list (${_toolNames.length}): ${_toolNames.join(',')}\n`);
         } catch { /* best-effort diagnostic */ }
 
-        await updateSessionStatus(session.id, 'running');
+        await updateStatus(session.id, 'running');
         // Parent→child abort cascade: when opts.parentSignal (factory) or
         // callParentSignal (per-call) fires, abort the sub-session's own
         // controller so the provider call tears down promptly. Best-effort:
@@ -368,7 +519,7 @@ export function makeAgentDispatch(opts = {}) {
         const _linkSignal = _managerMod?.linkParentSignalToSession;
         const _getProgressSnapshot = _managerMod?.getSessionProgressSnapshot;
         const _getLastProgressAt = _managerMod?.getSessionLastProgressAt;
-        const _getSession = _managerMod?.getSession || getSession;
+        const _getSession = _managerMod?.getSession || readSession;
         // Watchdog policy is split:
         // - firstResponseTimeoutMs cuts quickly only when the model produces no
         //   first stream/tool activity at all.
@@ -442,12 +593,13 @@ export function makeAgentDispatch(opts = {}) {
             : null;
         if (_idleTimer && typeof _idleTimer.unref === 'function') _idleTimer.unref();
         let terminalStatus = 'idle';
+        let closeReason = 'ephemeral-done';
         process.stderr.write(`[agent-dispatch] agent=${agent} preset=${presetName} model=${preset.model} provider=${preset.provider} session=${session.id}\n`);
         const _agentDispatchT0 = Date.now();
         let _handoffMsgStart = 0;
         try {
-            _handoffMsgStart = resolveHandoffMessageStartIndex(getSession(session.id));
-            const result = await askSession(session.id, finalPrompt, null, null, cwd, undefined, {
+            _handoffMsgStart = resolveHandoffMessageStartIndex(readSession(session.id));
+            const { onToolCall, askOpts } = buildAgentDispatchAskSessionArgs(opts, callArgs, {
                 onCompactEvent: (event) => {
                     try {
                         const label = agentCompactEventLabel(event);
@@ -458,7 +610,10 @@ export function makeAgentDispatch(opts = {}) {
                         );
                     } catch { /* best-effort compact visibility */ }
                 },
-            });
+            }, session);
+            // liveProjection is a send-opt on askOpts only. Do not stamp it
+            // (or interactiveSessionSurface) onto `session`.
+            const result = await ask(session.id, finalPrompt, null, onToolCall, cwd, undefined, askOpts);
             process.stderr.write(`[agent-dispatch] agent=${agent} session=${session.id} elapsed=${Date.now() - _agentDispatchT0}ms\n`);
             const raw = result?.content || '';
             // Brief cap. Agent role answers (recall/search)
@@ -468,25 +623,23 @@ export function makeAgentDispatch(opts = {}) {
             // majority of answers untouched. Opt-out via `brief:false` when
             // the caller explicitly wants the full synthesis.
             if (opts.brief === false) {
-                try { closeSession(session.id, 'ephemeral-done'); } catch { /* ignore */ }
                 return raw;
             }
             const out = applyBriefCap(raw);
-            try { closeSession(session.id, 'ephemeral-done'); } catch { /* ignore */ }
             return out;
         } catch (err) {
-            const partial = watchdogPartialHandoffFromError(err, getSession(session.id), _handoffMsgStart)
+            terminalStatus = 'error';
+            closeReason = 'ephemeral-error';
+            const partial = watchdogPartialHandoffFromError(err, readSession(session.id), _handoffMsgStart)
                 ?? (salvagePartialRequested(err, _abortLink?.signal)
-                    ? partialHandoffTextFromSession(getSession(session.id), _handoffMsgStart)
+                    ? partialHandoffTextFromSession(readSession(session.id), _handoffMsgStart)
                     : null);
             if (partial) {
                 terminalStatus = 'idle';
-                try { closeSession(session.id, 'ephemeral-done'); } catch { /* ignore */ }
+                closeReason = 'ephemeral-done';
                 if (opts.brief === false) return partial;
                 return applyBriefCap(partial);
             }
-            terminalStatus = 'error';
-            try { closeSession(session.id, 'ephemeral-error'); } catch { /* ignore */ }
             throw err;
         } finally {
             _abortLink.dispose();
@@ -496,7 +649,11 @@ export function makeAgentDispatch(opts = {}) {
             // Always flip out of 'running' before returning so the sweep never
             // leaves a stateless Pool C session stuck in 'running' when the
             // try/catch falls through in unexpected ways.
-            try { await updateSessionStatus(session.id, terminalStatus); } catch { /* ignore */ }
+            try { await updateStatus(session.id, terminalStatus); } catch { /* ignore */ }
+            // closeSession plants a tombstone, after which status writes are
+            // rejected. Publish the terminal projection before closing so
+            // live Agent panes cannot retain their preceding busy:true state.
+            try { close(session.id, closeReason); } catch { /* ignore */ }
         }
         });
         } finally {

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

@@ -59,6 +59,7 @@ function normalizeAgentCompactionConfig(value = {}) {
  * @param {number}  [opts.maxLoopIterations]
  * @param {string}  [opts.parentSessionId]
  * @param {string|null} [opts.ownerSessionId] - owning Mixdog MCP instance id for statusline isolation
+ * @param {string|null} [opts.visibility] - catalog visibility scope
  * @param {string|null} [opts.mcpScopeId] - owning session-runtime MCP registry scope
  * @returns {{ session: object, effectiveCwd: string|null }}
  */
@@ -77,6 +78,7 @@ export function prepareAgentSession({
     maxLoopIterations,
     parentSessionId,
     ownerSessionId,
+    visibility,
     clientHostPid,
     agentTag,
     cacheKeyOverride,
@@ -115,7 +117,9 @@ export function prepareAgentSession({
         maxLoopIterations: Number.isFinite(effectiveMaxLoopIterations) ? effectiveMaxLoopIterations : undefined,
         sourceType: sourceType || undefined,
         sourceName: sourceName || undefined,
+        parentSessionId: parentSessionId || null,
         ownerSessionId: effectiveOwnerSessionId || null,
+        visibility: visibility || null,
         clientHostPid: clientHostPid || null,
         compaction: compaction || undefined,
         mcpScopeId: mcpScopeId || null,

package/src/runtime/agent/orchestrator/cache-break-trace.mjs

@@ -0,0 +1,109 @@
+import { appendAgentTrace } from './agent-trace.mjs';
+
+const HASH_CHARS = 16;
+
+function cleanText(value, max = 120) {
+    if (value == null || value === '') return null;
+    return String(value).replace(/[\r\n\t]+/g, ' ').slice(0, max);
+}
+
+function cleanHash(value) {
+    const text = cleanText(value, 128);
+    return text ? text.slice(0, HASH_CHARS) : null;
+}
+
+function finiteNumber(value) {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : null;
+}
+
+export function buildCacheBreakPayload(record = {}) {
+    const payload = {
+        classification: cleanText(record.classification) || 'unknown',
+        reason: cleanText(record.reason) || 'unknown',
+        source: cleanText(record.source),
+        provider: cleanText(record.provider),
+        model: cleanText(record.model),
+        transport: cleanText(record.transport),
+        intentional_transition: cleanText(record.intentionalTransition),
+        index: finiteNumber(record.index),
+        previous_count: finiteNumber(record.previousCount),
+        next_count: finiteNumber(record.nextCount),
+        previous_hash: cleanHash(record.previousHash),
+        next_hash: cleanHash(record.nextHash),
+        previous_request_prefix_hash: cleanHash(record.previousRequestPrefixHash),
+        next_request_prefix_hash: cleanHash(record.nextRequestPrefixHash),
+        request_prefix_changed: record.requestPrefixChanged === true,
+        cached_tokens: finiteNumber(record.cachedTokens),
+        prompt_tokens: finiteNumber(record.promptTokens),
+        uncached_tokens: finiteNumber(record.uncachedTokens),
+        cache_ratio: finiteNumber(record.cacheRatio),
+        actual_cache_miss: record.actualCacheMiss === true,
+        input_prefix_mismatch_index: finiteNumber(record.inputPrefixMismatchIndex),
+        input_prefix_mismatch_previous_count: finiteNumber(record.inputPrefixMismatchPreviousCount),
+        input_prefix_mismatch_current_count: finiteNumber(record.inputPrefixMismatchCurrentCount),
+        input_prefix_mismatch_expected_type: cleanText(record.inputPrefixMismatchExpectedType),
+        input_prefix_mismatch_expected_hash: cleanHash(record.inputPrefixMismatchExpectedHash),
+        input_prefix_mismatch_actual_type: cleanText(record.inputPrefixMismatchActualType),
+        input_prefix_mismatch_actual_hash: cleanHash(record.inputPrefixMismatchActualHash),
+    };
+    return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== null));
+}
+
+export function formatCacheBreakLine(record = {}) {
+    const payload = buildCacheBreakPayload(record);
+    const fields = [
+        ['classification', payload.classification],
+        ['reason', payload.reason],
+        ['source', payload.source],
+        ['session', cleanText(record.sessionId, 160)],
+        ['provider', payload.provider],
+        ['model', payload.model],
+        ['iteration', finiteNumber(record.iteration)],
+        ['index', payload.index],
+        ['previousCount', payload.previous_count],
+        ['nextCount', payload.next_count],
+        ['previousHash', payload.previous_hash],
+        ['nextHash', payload.next_hash],
+        ['inputMismatchIndex', payload.input_prefix_mismatch_index],
+        ['intent', payload.intentional_transition],
+        ['cachedTokens', payload.cached_tokens],
+        ['promptTokens', payload.prompt_tokens],
+    ].filter(([, value]) => value !== null && value !== undefined);
+    return `[cache-break] ${fields.map(([key, value]) => (
+        typeof value === 'string' ? `${key}=${JSON.stringify(value)}` : `${key}=${value}`
+    )).join(' ')}`;
+}
+
+export function traceCacheBreak(record = {}, options = {}) {
+    const payload = buildCacheBreakPayload(record);
+    const traceFn = options.traceFn === null
+        ? null
+        : (typeof options.traceFn === 'function' ? options.traceFn : appendAgentTrace);
+    if (traceFn) {
+        try {
+            traceFn({
+                sessionId: record.sessionId || null,
+                iteration: finiteNumber(record.iteration),
+                kind: 'cache_break',
+                classification: payload.classification,
+                reason: payload.reason,
+                source: payload.source || null,
+                provider: payload.provider || null,
+                model: payload.model || null,
+                transport: payload.transport || null,
+                payload,
+            });
+        } catch { /* cache diagnostics never affect provider execution */ }
+    }
+    const explicitStderr = typeof options.stderrFn === 'function';
+    if (options.stderr !== false && (explicitStderr || !process.env.NODE_TEST_CONTEXT)) {
+        try {
+            const write = explicitStderr
+                ? options.stderrFn
+                : (line) => process.stderr.write(line);
+            write(`${formatCacheBreakLine(record)}\n`);
+        } catch { /* cache diagnostics never affect provider execution */ }
+    }
+    return payload;
+}

package/src/runtime/agent/orchestrator/config.mjs

@@ -1,6 +1,7 @@
 import { resolvePluginData } from '../../shared/plugin-paths.mjs';
 import { readSection, updateSection, updateSectionAsync, getAgentApiKey, AGENT_PROVIDER_ENV } from '../../shared/config.mjs';
 import {
+    DEFAULT_DISABLED_AGENT_IDS,
     agentRouteStorageNeedsMigration,
     canonicalizeAgentRouteStorage,
 } from '../../shared/agent-route-config.mjs';
@@ -147,7 +148,7 @@ export const DEFAULT_PRESETS = Object.freeze([
     Object.freeze({ id: 'opus-mid', name: 'OPUS MID', type: 'agent', provider: 'anthropic-oauth', model: resolveAnthropicFamilyModel('opus'), effort: 'medium', tools: 'full' }),
     Object.freeze({ id: 'opus-high', name: 'OPUS HIGH', type: 'agent', provider: 'anthropic-oauth', model: resolveAnthropicFamilyModel('opus'), effort: 'high', tools: 'full' }),
 ]);
-function buildDefaultConfig(options = {}) {
+export function buildDefaultConfig(options = {}) {
     const detectCredentials = options.detectCredentials !== false;
     const providers = {};
     // API providers — enabled if env key exists
@@ -196,7 +197,11 @@ function buildDefaultConfig(options = {}) {
     // Local providers — opt-in via setup UI after HTTP ping confirms server is running
     providers.ollama = { enabled: false, baseURL: 'http://localhost:11434/v1' };
     providers.lmstudio = { enabled: false, baseURL: 'http://localhost:1234/v1' };
-    return { providers, workflow: { active: 'default' } };
+    return {
+        providers,
+        disabledAgents: [...DEFAULT_DISABLED_AGENT_IDS],
+        workflow: { active: 'default' },
+    };
 }
 
 function hasKeys(value) {

package/src/runtime/agent/orchestrator/providers/admission-scheduler.mjs

@@ -201,7 +201,12 @@ export class ProviderAdmissionScheduler {
         // owns a slot, so reacquiring the same lane could deadlock a full wave.
         const current = this.context.getStore();
         if (current?.scheduler === this && current.key === laneKey) {
-            return Promise.resolve().then(() => task(signal));
+            return Promise.resolve().then(() => task(signal, {
+                queueWaitMs: 0,
+                active: current.lane.active,
+                queued: current.lane.queue.length,
+                limit: Number.isFinite(current.lane.limit) ? current.lane.limit : null,
+            }));
         }
         if (this.closedReason) return Promise.reject(this.closedReason);
         if (signal?.aborted) return Promise.reject(abortError(signal));
@@ -323,7 +328,14 @@ export class ProviderAdmissionScheduler {
                 priority: item.priority,
                 rateLimited: false,
             };
-            this.context.run(admission, () => Promise.resolve().then(() => item.task(controller.signal)))
+            const admissionMetrics = {
+                queueWaitMs: Math.max(0, this.now() - item.queuedAt),
+                active: lane.active,
+                queued: lane.queue.length,
+                limit: Number.isFinite(lane.limit) ? lane.limit : null,
+            };
+            this.context.run(admission, () => Promise.resolve().then(() =>
+                item.task(controller.signal, admissionMetrics)))
                 .then((value) => {
                     // A retry that eventually succeeds is not evidence that
                     // the lane should begin recovery from the 429 it just saw.
@@ -582,7 +594,7 @@ export function wrapProviderAdmission(provider, providerName, scheduler = provid
         // resource controller reacquires the agent lease before model output
         // continues through local context/tool processing.
         return resourceAdmission.runYielded(() =>
-            scheduler.run(key, (admissionSignal) => {
+            scheduler.run(key, (admissionSignal, admissionMetrics) => {
                 // Admission is the common request-clock boundary for WS/SSE/HTTP.
                 // Queue wait therefore cannot consume first-byte or agent-watchdog
                 // time. Provider-local retry remains the sole retry owner.
@@ -590,6 +602,7 @@ export function wrapProviderAdmission(provider, providerName, scheduler = provid
                 return originalSend.call(this, messages, model, tools, {
                     ...opts,
                     signal: admissionSignal,
+                    _providerAdmission: admissionMetrics,
                 });
             }, {
                 signal,

package/src/runtime/agent/orchestrator/providers/lib/anthropic-request-utils.mjs

@@ -325,7 +325,15 @@ export function deferredAnthropicTools(activeTools, messages, opts, provider) {
             if (key) discovered.add(key);
         }
     }
-    const catalog = Array.isArray(opts.session.deferredToolCatalog) ? opts.session.deferredToolCatalog : [];
+    const catalogByName = new Map();
+    for (const tool of [
+        ...(Array.isArray(opts.session.deferredToolCatalog) ? opts.session.deferredToolCatalog : []),
+        ...(Array.isArray(opts.session.deferredLateToolCatalog) ? opts.session.deferredLateToolCatalog : []),
+    ]) {
+        const name = String(tool?.name || '').trim();
+        if (name) catalogByName.set(name, tool);
+    }
+    const catalog = [...catalogByName.values()];
     return catalog
         .filter((tool) => tool?.name && discovered.has(String(tool.name)) && !active.has(String(tool.name)))
         .map((tool) => ({ ...tool, deferLoading: true }));

package/src/runtime/agent/orchestrator/providers/media-normalization.mjs

@@ -35,11 +35,25 @@ function geminiInlineInfo(block) {
     return { data, mimeType: cleanMimeType(inline.mimeType || inline.mime_type || inline.mediaType || inline.media_type) };
 }
 
-// Inline document/file part ({ type: 'file', data, mimeType, filename? }) as
-// submitted by the desktop composer (PDF attachments). Providers receive it
-// as their native document shape; estimators must never serialize its base64.
+// Inline document/file parts arrive in two canonical runtime shapes:
+// - desktop attachments: { type: 'file', data, mimeType, filename? }
+// - read(PDF): { type: 'document', source: { type: 'base64', media_type, data } }
+// Providers receive both as their native document shape; estimators and stored
+// history must never serialize either base64 payload as text.
 function fileInfo(block) {
-    if (!block || typeof block !== 'object' || block.type !== 'file') return null;
+    if (!block || typeof block !== 'object') return null;
+    if (block.type === 'document') {
+        const source = block.source;
+        if (source?.type !== 'base64' || typeof source.data !== 'string' || !source.data) return null;
+        const mimeType = String(
+            source.media_type || source.mediaType || block.mimeType || block.mediaType || 'application/pdf',
+        ).trim().toLowerCase() || 'application/pdf';
+        const filename = typeof block.title === 'string' && block.title
+            ? block.title
+            : (typeof block.filename === 'string' && block.filename ? block.filename : '');
+        return { data: source.data, mimeType, filename };
+    }
+    if (block.type !== 'file') return null;
     const data = isAttachmentReference(block)
         ? readAttachmentBase64(block)
         : (typeof block.data === 'string' ? block.data : '');
@@ -496,11 +510,18 @@ export function splitToolContentForOpenAIResponses(content) {
 }
 
 export function splitToolContentForXaiResponses(content) {
-    const mediaContent = mediaPartsOnly(
-        normalizeContentForOpenAIResponses(content, { role: 'user' }),
-        new Set(['input_image']),
-    );
-    if (!mediaContent.length) return { output: contentToText(content, ''), mediaContent: null };
+    const normalized = normalizeContentForOpenAIResponses(content, { role: 'user' });
+    const mediaContent = mediaPartsOnly(normalized, new Set(['input_image']));
+    if (!mediaContent.length) {
+        const hasDocument = normalized.some((part) => part?.type === 'input_file');
+        return {
+            output: contentToText(
+                content,
+                hasDocument ? '[tool result included document content unavailable to xAI Responses]' : '',
+            ),
+            mediaContent: null,
+        };
+    }
     return {
         // xAI documents function_call_output as text/JSON; media remains a
         // following user input, without replaying the tool-result text there.

package/src/runtime/agent/orchestrator/providers/openai-codex-metadata.mjs

@@ -6,6 +6,7 @@ import { createHash, randomUUID } from 'crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { getPluginData } from '../config.mjs';
+import { activateCodexTurnState } from './openai-turn-state.mjs';
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 let _installationId = null;
@@ -206,39 +207,30 @@ export function _codexWsCompatibilityHeaders(context = {}) {
 export function _withCodexWsClientMetadata(frame, entry, enabled, context = {}) {
     if (!enabled || !frame || typeof frame !== 'object') return frame;
     const base = _codexMetadataBase(entry, context);
-    const requestKind = _codexRequestKind(context?.sendOpts, context?.poolKey || '');
-    const isPrewarmRequest = requestKind === 'prewarm';
+    const explicitLogicalTurnId = _cleanMetaString(
+        context?.sendOpts?.turnId
+        || context?.sendOpts?.codexTurnId
+        || context?.sendOpts?.session?.turnId,
+    );
+    const logicalTurnId = explicitLogicalTurnId
+        ? _codexUuidV7(explicitLogicalTurnId)
+        : base.turn_id;
+    const turnStateScope = _cleanMetaString(context?.poolKey);
     const metadata = {
         ...base,
         ...(frame.client_metadata && typeof frame.client_metadata === 'object' ? frame.client_metadata : {}),
         'x-codex-ws-stream-request-start-ms': String(Date.now()),
     };
     if (entry && typeof entry === 'object') {
-        // x-codex-turn-state is scoped to ONE turn while
-        // pooled sockets span turns: attribute a captured token to the FIRST
-        // turn that observes it, then drop it once turn_id moves on. An empty
-        // turn_id (parity prewarm) is a valid owner, so the check is against
-        // null rather than falsiness.
-        if (entry.turnState) {
-            if (entry.turnStateTurnId == null) {
-                entry.turnStateTurnId = base.turn_id;
-            } else if (entry.turnStateTurnId !== base.turn_id) {
-                // Codex startup prewarm owns the handshake turn-state until
-                // the first real turn consumes that prewarmed client session.
-                // Adopt it once across prewarm→turn; ordinary turn changes
-                // still retire the old token.
-                if (entry.turnStateFromPrewarm === true && !isPrewarmRequest) {
-                    entry.turnStateTurnId = base.turn_id;
-                } else {
-                    entry.turnState = null;
-                    entry.turnStateTurnId = null;
-                }
-            }
-        }
-        if (!isPrewarmRequest && entry.turnStateFromPrewarm === true) {
-            entry.turnStateFromPrewarm = false;
+        const priorTurnId = entry.turnStateTurnId;
+        if (turnStateScope && logicalTurnId) {
+            entry.turnState = activateCodexTurnState(turnStateScope, logicalTurnId, entry);
+        } else if (priorTurnId != null && priorTurnId !== logicalTurnId) {
+            entry.turnState = null;
         }
-        entry.currentTurnId = base.turn_id;
+        entry.turnStateScope = turnStateScope || null;
+        entry.turnStateTurnId = logicalTurnId || null;
+        entry.currentTurnId = logicalTurnId || null;
     }
     if (entry?.turnState) metadata['x-codex-turn-state'] = String(entry.turnState);
     return { ...frame, client_metadata: metadata };