mixdog 1.2.3 → 1.2.5

package/src/runtime/agent/orchestrator/providers/cursor-wire-request.mjs

@@ -61,7 +61,13 @@ function toolResultEntry(message, text, toolNames) {
   const isError = message.mixdog_tool_error === true;
   const toolName = toolNames.get(toolCallId) || '';
   return {
-    toolResult: { toolCallId, content: text, media, isError },
+    toolResult: {
+      toolCallId,
+      content: text,
+      media,
+      isError,
+      ...(message.mixdog_read_window?.lineClipped === true ? { readWindow: { lineClipped: true } } : {}),
+    },
     entry: {
       role: 'tool',
       id: toolCallId,
@@ -170,9 +176,7 @@ export function buildRequestContext(tools, cloudRule) {
           {
             serverName: 'mixdog',
             instructions:
-              'Use the tools provided by the mixdog MCP server for this task. ' +
-              'Follow their descriptions and input schemas. Prefer them over Cursor native tools; ' +
-              'native tools do not directly access the Mixdog environment. ' +
+              'Do not use Cursor native tools; use only the tools provided by the mixdog MCP server, following their descriptions and declared input schemas. ' +
               'If a needed tool is not available, use the provided tool discovery mechanism rather than inventing a tool.',
           },
         ]

package/src/runtime/agent/orchestrator/providers/cursor-wire-stream-bridge.mjs

@@ -4,6 +4,7 @@
  * close verdict and the bounded in-place restart.
  */
 import {
+  MAX_CONNECT_FRAME_BYTES,
   isCursorAuthError,
   isCursorThrottleError,
   isRetryableCursorStreamError,
@@ -13,6 +14,10 @@ import { emitProviderRetryStage, markProviderRecoveryExhausted, retryAfterMsFrom
 import { createFrameParser, cursorError, parseEndStream } from './cursor-wire-transport.mjs';
 import { processServerMessage } from './cursor-wire-stream-messages.mjs';
 
+// A parked HTTP/2 run can still receive parallel execs. Keep their raw chunks
+// with the transport until the next SSE consumer attaches.
+const parkedInputs = new WeakMap();
+
 // Resolves after `ms`, or early when the stream is cancelled.
 function abortableSleep(ms, signal) {
   return new Promise((resolve) => {
@@ -51,7 +56,9 @@ export function createBridgeController(ctx) {
       modelParameters: run.modelParameters,
       maxMode: run.maxMode,
       sessionId: run.sessionId,
+      ownerSessionId: run.ownerSessionId,
       pending: state.pending,
+      executions: state.executions,
       sawTurnEnded: state.sawTurnEnded,
     });
     sink.finish('tool_calls');
@@ -80,13 +87,11 @@ export function createBridgeController(ctx) {
     const serverDelay = retryAfterMsFromError(error);
     // Server advice is honored in full for every retryable kind; local
     // backoff applies only when the server gave none.
-    const delayMs = Number.isFinite(serverDelay)
-      ? serverDelay
-      : backoffMs(throttled ? throttleCount + 1 : retryCount + 1);
+    const backoffAttempt = (throttled ? throttleCount : retryCount) + 1;
+    const delayMs = Number.isFinite(serverDelay) ? serverDelay : backoffMs(backoffAttempt);
     const throttleOk = throttled && throttleCount < tuning.maxThrottleRetries;
     const authOk = authFailure && authCount < tuning.maxAuthRetries;
-    const canRetry =
-      retryCount < tuning.maxRetries && recoveryEligible && (retryable || throttleOk || authOk);
+    const canRetry = retryCount < tuning.maxRetries && recoveryEligible && (retryable || throttleOk || authOk);
     if (!canRetry) {
       // A fresh Cursor run owns its bounded in-place retries. Mark
       // exhaustion so the outer loop does not multiply that budget.
@@ -96,8 +101,7 @@ export function createBridgeController(ctx) {
       // A throttle that spent its bounded retries is final for the turn too.
       if (
         recoveryEligible &&
-        ((retryable && retryCount >= tuning.maxRetries) ||
-          (throttled && throttleCount >= tuning.maxThrottleRetries))
+        ((retryable && retryCount >= tuning.maxRetries) || (throttled && throttleCount >= tuning.maxThrottleRetries))
       ) {
         markProviderRecoveryExhausted(error, { owner: 'cursor-wire', attempts: retryCount + 1 });
       }
@@ -118,6 +122,9 @@ export function createBridgeController(ctx) {
       lastErr: error,
       delayMs,
     });
+    let restartReason = 'transient';
+    if (throttled) restartReason = 'throttle';
+    else if (authFailure) restartReason = 'auth';
     void sleep(delayMs, cancelSignal).then(async () => {
       if (isCancelled() || state.closed) return;
       try {
@@ -126,7 +133,7 @@ export function createBridgeController(ctx) {
           attempt: retryCount,
           fromCheckpoint: !throttled && Boolean(run.conversation.checkpoint),
           visibleOutput: state.visibleOutput,
-          reason: throttled ? 'throttle' : authFailure ? 'auth' : 'transient',
+          reason: restartReason,
           error,
         });
         if (isCancelled() || state.closed) {
@@ -200,6 +207,11 @@ export function createBridgeController(ctx) {
   const attach = (ownedBridge, nextHeartbeat) => {
     live.bridge = ownedBridge;
     live.heartbeat = nextHeartbeat;
+    let inbox = parkedInputs.get(ownedBridge);
+    if (!inbox) {
+      inbox = { chunks: [], bytes: 0 };
+      parkedInputs.set(ownedBridge, inbox);
+    }
     const messageCtx = {
       state,
       filter,
@@ -208,14 +220,26 @@ export function createBridgeController(ctx) {
       tools: run.tools,
       cloudRule: run.cloudRule,
       sessionId: run.sessionId,
+      ownerSessionId: run.ownerSessionId,
     };
     const frameParser = createFrameParser(
       // Server requests answer on whichever bridge is live when they arrive.
       (bytes) => watchdog.progress(processServerMessage(bytes, { ...messageCtx, bridge: live.bridge })),
       (bytes) => onEndStream(ownedBridge, bytes)
     );
-    ownedBridge.onData((chunk) => {
-      if (live.bridge !== ownedBridge || state.closed) return;
+    const receive = (chunk) => {
+      if (live.bridge !== ownedBridge || isCancelled()) return;
+      if (state.closed) {
+        if (inbox.bytes + chunk.byteLength > MAX_CONNECT_FRAME_BYTES) {
+          ownedBridge.close(
+            cursorError('Cursor parked input exceeds the buffer limit', { code: 'stream_buffer_limit' })
+          );
+          return;
+        }
+        inbox.chunks.push(chunk);
+        inbox.bytes += chunk.byteLength;
+        return;
+      }
       state.chunkSeq += 1;
       try {
         frameParser(chunk);
@@ -227,9 +251,15 @@ export function createBridgeController(ctx) {
       } catch (error) {
         ownedBridge.close(error);
       }
-    });
+    };
+    ownedBridge.onData(receive);
     ownedBridge.onClose((error) => onBridgeClose(ownedBridge, nextHeartbeat, frameParser, error));
     watchdog.start();
+    while (!state.closed && !isCancelled() && inbox.chunks.length) {
+      const chunk = inbox.chunks.shift();
+      inbox.bytes -= chunk.byteLength;
+      receive(chunk);
+    }
   };
 
   return { attach };

package/src/runtime/agent/orchestrator/providers/cursor-wire-stream-messages.mjs

@@ -3,12 +3,14 @@
  * to the shared stream state and relayed to the SSE sink. Returns the
  * message's forward-progress kind for the watchdog.
  */
+import { randomUUID } from 'node:crypto';
+import { registerCursorNativeCall } from './cursor-native-context.mjs';
 import { appendAgentTrace } from '../agent-trace.mjs';
 import { decodeMessage } from './cursor-wire-protobuf.mjs';
 import { MAX_CHECKPOINT_BYTES, cursorInteractionProgress } from './cursor-wire-guards.mjs';
 import { buildCursorInteractionResponse } from './cursor-wire-interactions.mjs';
 import { cursorError } from './cursor-wire-transport.mjs';
-import { handleExecMessage, handleKvMessage, sendClientMessage } from './cursor-wire-exec.mjs';
+import { handleExecMessage, handleKvMessage, sendClientMessage, sendToolResult } from './cursor-wire-exec.mjs';
 
 // Unknown fields seen on every live frame: AgentServerMessage field 8 (timing
 // doubles) and InteractionUpdate field 25 (epoch-ms timestamp). Never traced.
@@ -43,6 +45,31 @@ function traceUnknownFields(trace, sessionId, scope, unknown, noise) {
   }
 }
 
+// Parent edit outcomes are diagnostics, not executable calls or read results.
+function traceNativeEditFailure(trace, sessionId, update) {
+  const completed = update.toolCallCompleted;
+  const result = completed?.toolCall?.editToolCall?.result;
+  if (!result) return;
+  const outcome = ['fileNotFound', 'readPermissionDenied', 'writePermissionDenied', 'rejected', 'error'].find(
+    (key) => result[key] !== undefined
+  );
+  if (!outcome) return;
+  try {
+    trace({
+      sessionId,
+      kind: 'cursor_native_edit_failure',
+      provider: 'cursor',
+      payload: {
+        callId: (completed.callId || '').slice(0, 256),
+        modelCallId: (completed.modelCallId || '').slice(0, 256),
+        outcome,
+      },
+    });
+  } catch {
+    /* best-effort */
+  }
+}
+
 // Relays one interaction update to the SSE stream and returns its progress.
 function applyInteractionUpdate(update, state, filter, emit) {
   if (update.textDelta?.text) {
@@ -79,9 +106,32 @@ function applyCheckpointUpdate(update, conversation, state) {
 }
 
 // Announces a newly pending native/MCP tool call as a completion chunk once.
-function announcePendingToolCall(state, pending, emit) {
-  if (state.pending.some((entry) => entry.toolCallId === pending.toolCallId)) return;
+function announcePendingToolCall(state, pending, emit, bridge, ownerSessionId) {
+  state.executions ??= new Map();
+  const executions = state.executions;
+  const execId = pending.exec.execId ?? pending.exec.id;
+  const previous = execId !== undefined ? executions.get(execId) : undefined;
+  if (previous) {
+    if (previous.completedResult) {
+      sendToolResult(
+        bridge,
+        { ...previous, exec: pending.exec },
+        previous.completedResult.result,
+        previous.completedResult.ok
+      );
+    }
+    return;
+  }
+  // A parent call can issue distinct executions; each needs its own local result.
+  if ([...executions.values(), ...state.pending].some((entry) => entry.toolCallId === pending.toolCallId)) {
+    pending.toolCallId = randomUUID();
+  }
+  if (execId !== undefined) executions.set(execId, pending);
+  registerCursorNativeCall(ownerSessionId, pending, executions);
   state.pending.push(pending);
+  // Native execs may await their result before the server completes a step.
+  // The bridge hands off only after all currently received frames are whole.
+  if (pending.native) state.batchBoundaryReady = true;
   emit({
     tool_calls: [
       {
@@ -101,12 +151,24 @@ function announcePendingToolCall(state, pending, emit) {
  */
 export function processServerMessage(
   bytes,
-  { state, filter, emit, conversation, tools, cloudRule, bridge, sessionId = '', trace = appendAgentTrace }
+  {
+    state,
+    filter,
+    emit,
+    conversation,
+    tools,
+    cloudRule,
+    bridge,
+    sessionId = '',
+    ownerSessionId = '',
+    trace = appendAgentTrace,
+  }
 ) {
   const message = decodeMessage('AgentServerMessage', bytes);
   traceUnknownFields(trace, sessionId, 'agent_server_message', message.$unknown, NOISE_SERVER_FIELDS);
   if (message.interactionUpdate) {
     traceUnknownFields(trace, sessionId, 'interaction_update', message.interactionUpdate.$unknown, NOISE_UPDATE_FIELDS);
+    traceNativeEditFailure(trace, sessionId, message.interactionUpdate);
   }
   if (message.interactionUpdate) return applyInteractionUpdate(message.interactionUpdate, state, filter, emit);
   if (message.kvServerMessage) {
@@ -119,7 +181,7 @@ export function processServerMessage(
   }
   if (message.execServerMessage) {
     const handled = handleExecMessage(bridge, message.execServerMessage, tools, cloudRule, (pending) =>
-      announcePendingToolCall(state, pending, emit)
+      announcePendingToolCall(state, pending, emit, bridge, ownerSessionId)
     );
     return handled === false ? 'park' : 'work';
   }

package/src/runtime/agent/orchestrator/providers/cursor-wire.mjs

@@ -328,11 +328,12 @@ function createPendingToolBatchResponse(active, model, key) {
 }
 
 // Stream state shared by the sink, the message router and the bridge controller.
-function freshStreamState(sawTurnEnded) {
+function freshStreamState(sawTurnEnded, executions) {
   return {
     outputTokens: 0,
     contextTokens: null,
     pending: [],
+    executions,
     closed: false,
     sawEnd: false,
     sawTurnEnded: sawTurnEnded === true,
@@ -360,7 +361,9 @@ function createStreamResponse({
   // Owning session, carried into the stored run so a session close can find
   // and tear down the pending batch's bridge/heartbeat.
   sessionId = '',
+  ownerSessionId = sessionId,
   sawTurnEnded = false,
+  executions = new Map(),
   restart = null,
   sleep = undefined,
   onStageChange = null,
@@ -376,7 +379,7 @@ function createStreamResponse({
   const stream = new ReadableStream({
     start(controller) {
       const filter = thinkingFilter();
-      const state = freshStreamState(sawTurnEnded);
+      const state = freshStreamState(sawTurnEnded, executions);
       const tuning = resolveCursorStreamTuning();
       watchdog = createCursorStreamWatchdog({
         idleTimeoutMs: tuning.idleTimeoutMs,
@@ -400,7 +403,7 @@ function createStreamResponse({
         watchdog,
         sink,
         tuning,
-        run: { key, conversation, tools, cloudRule, modelParameters, maxMode, sessionId },
+        run: { key, conversation, tools, cloudRule, modelParameters, maxMode, sessionId, ownerSessionId },
         runs,
         restart,
         sleep,
@@ -449,6 +452,7 @@ function resumeRun(active, toolResults, userText, model, key) {
     }
     const payload = { ...result, content: String(result.content ?? '') };
     if (pendingUserText && pending.exec.execId === lastExecId) {
+      if (pending.native?.resultType === 'readResult') pending.nativeUserMessage = pendingUserText;
       payload.content += `\n\n<user_message>\n${pendingUserText}\n</user_message>`;
       userTextDelivered = true;
     }
@@ -471,7 +475,11 @@ function noUserMessageResponse() {
   });
 }
 
-export async function handleChatCompletion(body, accessToken, { onStageChange = null, getAccessToken = null } = {}) {
+export async function handleChatCompletion(
+  body,
+  accessToken,
+  { onStageChange = null, getAccessToken = null, resetActiveRun = false, ownerSessionId = '' } = {}
+) {
   await warmCursorClientVersion();
   const parsed = parseMessages(body.messages);
   if (
@@ -492,6 +500,7 @@ export async function handleChatCompletion(body, accessToken, { onStageChange =
   const cloudRule = parsed.systems.join('\n\n') || undefined;
   const active = activeRuns.get(key);
   if (
+    !resetActiveRun &&
     active &&
     parsed.toolResults.length &&
     active.bridge.alive &&
@@ -531,6 +540,7 @@ export async function handleChatCompletion(body, accessToken, { onStageChange =
     maxMode,
     key,
     sessionId,
+    ownerSessionId,
     onStageChange,
     restart: async ({ fromCheckpoint, reason, error }) => {
       if (reason === 'throttle') {

package/src/runtime/agent/orchestrator/providers/cursor.mjs

@@ -49,6 +49,7 @@ function toCursorMessages(messages, providerName, { nativePdf } = {}) {
       ...toolMessage,
       mixdog_tool_error: message.toolKind === 'error' || message.isError === true,
       ...(media.length ? { mixdog_tool_media: media } : {}),
+      ...(message.readWindow?.lineClipped === true ? { mixdog_read_window: { lineClipped: true } } : {}),
     });
   }
   return output;
@@ -545,6 +546,9 @@ function selectCursorVariant(group, { effort = null, fast = false } = {}) {
 class CursorProviderBase {
   // Cursor's chat wire has no document block: PDFs lower to text.
   nativePdf = false;
+  // Native read results are judged as exact source windows, so the tool
+  // finalizer reports their clipped lines next to the text.
+  consumesReadWindows = true;
 
   static inputExcludesCache = false;
   // The in-place stream retry budget is the whole recovery: a spent budget
@@ -640,6 +644,13 @@ class CursorProviderBase {
       const response = await runtime.handleChatCompletion(body, accessToken, {
         onStageChange: sendOpts.onStageChange,
         getAccessToken: (options) => this._accessToken({ signal, ...options }),
+        // A deliberate history reset must reach Cursor's private parked run,
+        // not just the orchestrator's providerState.
+        resetActiveRun: Boolean(sendOpts.cacheBreakIntent),
+        // Native read/edit capabilities are process-local. An explicit empty
+        // executor (the model-proxy host: tools run in the server daemon)
+        // keeps every call an ordinary Mixdog tool call.
+        ownerSessionId: String(sendOpts.toolExecutionSessionId ?? (sendOpts.sessionId || '')),
       });
       try {
         sendOpts.onStageChange?.('streaming');
@@ -699,7 +710,9 @@ class CursorProviderBase {
     const sessionScope = String(
       sendOpts.transportScope ||
         sendOpts.sessionId ||
-        sendOpts.providerCacheKey || sendOpts.promptCacheKey || `cursor-call:${randomUUID()}`
+        sendOpts.providerCacheKey ||
+        sendOpts.promptCacheKey ||
+        `cursor-call:${randomUUID()}`
     );
     const openAiTools = tools?.length
       ? toOpenAITools(acceptedWireTools(tools, 'openai', sendOpts.onToolExcluded, '[cursor] tool'))

package/src/runtime/agent/orchestrator/providers/custom-provider-config.mjs

@@ -386,6 +386,14 @@ function catalogLevels(row) {
   return levels.size ? [...levels].sort(byRank) : null;
 }
 
+function reasoningLevelFields(levels) {
+  if (!levels) return {};
+  return {
+    reasoningOptions: levels.length ? [{ type: 'effort', values: [...levels] }] : [],
+    reasoningLevels: [...levels],
+  };
+}
+
 function effectiveRow(base, override, { providerId, discovered, newModelsHidden }) {
   const ov = override || {};
   const reasoning = ov.reasoning || {};
@@ -413,12 +421,7 @@ function effectiveRow(base, override, { providerId, discovered, newModelsHidden
     hidden,
     manual: ov.manual === true,
     supportsReasoning: levels ? levels.some((level) => level !== 'none') : base.supportsReasoning === true,
-    ...(levels
-      ? {
-          reasoningOptions: levels.length ? [{ type: 'effort', values: [...levels] }] : [],
-          reasoningLevels: [...levels],
-        }
-      : {}),
+    ...reasoningLevelFields(levels),
     customReasoning: { wireFormat: reasoning.wireFormat ?? 'standard', wireValues, replay },
     ...(replay ? { reasoningContentField: 'reasoning_content' } : {}),
   };

package/src/runtime/agent/orchestrator/providers/custom-provider.mjs

@@ -173,7 +173,11 @@ export async function createCustomProvider(id, config) {
     if (providerOffersWire(providerId, 'messages')) {
       const { AnthropicProvider } = await import('./anthropic.mjs');
       // The Anthropic SDK appends /v1/messages itself; the endpoint's /v1 base maps to it.
-      messagesEngine = new AnthropicProvider({ ...engine, name: providerId, baseURL: cfg.baseURL.replace(/\/v1$/i, '') });
+      messagesEngine = new AnthropicProvider({
+        ...engine,
+        name: providerId,
+        baseURL: cfg.baseURL.replace(/\/v1$/i, ''),
+      });
       messagesEngine.nativePdf = false;
     }
     class CompatBase extends OpenAICompatProvider {
@@ -207,7 +211,8 @@ export async function createCustomProvider(id, config) {
   // The bound Messages engine reads the parent's model rows, so a routed
   // Messages request carries the same row-driven thinking/effort as the
   // Anthropic protocol.
-  if (provider.messagesEngine) provider.messagesEngine.getCachedModelInfo = (model) => provider.getCachedModelInfo(model);
+  if (provider.messagesEngine)
+    provider.messagesEngine.getCachedModelInfo = (model) => provider.getCachedModelInfo(model);
   provider.customConfig = cfg;
   provider._customKeyless = keyless;
   provider._applyCustomRows(provider._customRows());

package/src/runtime/agent/orchestrator/providers/effort-configuration.mjs

@@ -1,3 +1,4 @@
+import { isVisibleStreamProgress } from '../../../shared/stream-progress.mjs';
 import { anthropicEffortLevelsFor, normalizeAnthropicEffortInput } from './anthropic-effort.mjs';
 import { CUSTOM_EFFORT_LEVELS, customEffortLevels, isCustomProviderName } from './custom-reasoning.mjs';
 import { codexModelSupportsEffortUpdates } from './openai-oauth-catalog.mjs';
@@ -72,19 +73,40 @@ export function isEffortConfigurationRejection(status, text) {
 /**
  * Runs `send(opts)`; when the model rejects the mid-conversation effort
  * update, switches the updates off for it and replays the request once
- * without them. The rejection happens before any output streams.
+ * without them. Never replay after output reached the caller, cancellation,
+ * or an explicit opt-out; a late error is not evidence of missing support.
  */
 export async function withEffortConfigurationFallback(provider, model, opts, send) {
+  let streamed = false;
+  const track =
+    (callback, isProgress = false) =>
+    (...args) => {
+      if (!isProgress || isVisibleStreamProgress(args[0])) streamed = true;
+      return callback(...args);
+    };
+  const tracked = { ...opts };
+  if (typeof opts?.onStreamDelta === 'function') tracked.onStreamDelta = track(opts.onStreamDelta, true);
+  if (typeof opts?.onTextDelta === 'function') tracked.onTextDelta = track(opts.onTextDelta);
+  if (typeof opts?.onToolCall === 'function') tracked.onToolCall = track(opts.onToolCall);
   try {
-    return await send(opts);
+    return await send(tracked);
   } catch (error) {
     const status = error?.status ?? error?.httpStatus;
-    if (opts?._effortConfigurationRetry || !isEffortConfigurationRejection(status, error?.message)) throw error;
+    const emitted =
+      streamed || error?.liveTextEmitted === true || error?.emittedToolCall === true || error?.unsafeToRetry === true;
+    if (
+      opts?._effortConfigurationRetry ||
+      opts?.effortConfigurationEnabled === false ||
+      opts?.signal?.aborted ||
+      emitted ||
+      !isEffortConfigurationRejection(status, error?.message)
+    )
+      throw error;
     markEffortConfigurationUnsupported(provider, model);
     process.stderr.write(
       `[${provider}] ${model} rejected the mid-conversation effort update; retrying once without it\n`
     );
-    return send({ ...opts, effortConfigurationEnabled: false, _effortConfigurationRetry: true });
+    return send({ ...tracked, effortConfigurationEnabled: false, _effortConfigurationRetry: true });
   }
 }
 const OPENAI_PROVIDERS = new Set(['openai', 'openai-oauth']);

package/src/runtime/agent/orchestrator/providers/gemini-cache.mjs

@@ -77,7 +77,9 @@ const GEMINI_CACHE_MIN_TOKENS = 4096;
 // Minimum prefix tokens for an explicit cache, or null when the docs exclude
 // the model from explicit caching.
 export function geminiExplicitCacheMinTokens(model) {
-  const bare = String(model || '').replace(/^models\//i, '').toLowerCase();
+  const bare = String(model || '')
+    .replace(/^models\//i, '')
+    .toLowerCase();
   const major = /^gemini-(\d+)/.exec(bare);
   if (major && Number(major[1]) >= 4) return null;
   if (/^gemini-2\.5-(?:pro|flash)(?!-lite)(?:-|$)/.test(bare)) return 2048;
@@ -263,19 +265,23 @@ export function _resolveGeminiCacheUsage({ usageMetadata, cachedContent, provide
   // the prompt portion.
   const toolUseTokens = firstFinite(usageMetadata?.toolUsePromptTokenCount, usageMetadata?.tool_use_prompt_token_count);
   const inputTokens = hasExplicitPromptTokens ? promptTokens + toolUseTokens : Math.max(0, totalTokens - outputTokens);
-  const reportedCachedTokens = firstFinite(
+  const reportedCachedCount = [
     // generateContent UsageMetadata field.
     usageMetadata?.cachedContentTokenCount,
     usageMetadata?.cached_content_token_count,
     // Newer SDK convenience alias documented for implicit cache hits.
     usageMetadata?.totalCachedTokens,
-    usageMetadata?.total_cached_tokens
-  );
+    usageMetadata?.total_cached_tokens,
+  ]
+    .map((value) => (value == null ? NaN : Number(value)))
+    .find((value) => Number.isFinite(value) && value >= 0);
+  const reportedCachedTokens = reportedCachedCount ?? 0;
   const cachedFallbackTokens = cachedContent ? Number(providerState?.gemini?.cacheTokenSize || 0) || 0 : 0;
-  const rawCachedTokens = reportedCachedTokens > 0 ? reportedCachedTokens : cachedFallbackTokens;
+  // An explicit zero is a measured miss, not missing usage metadata.
+  const rawCachedTokens = reportedCachedCount ?? cachedFallbackTokens;
   const cachedTokens = inputTokens > 0 ? Math.min(rawCachedTokens, inputTokens) : rawCachedTokens;
   let cacheTokenSource = 'none';
-  if (reportedCachedTokens > 0) cacheTokenSource = 'usage_metadata';
+  if (reportedCachedCount !== undefined) cacheTokenSource = 'usage_metadata';
   else if (cachedFallbackTokens > 0) cacheTokenSource = 'cache_create_fallback';
   return {
     inputTokens,

package/src/runtime/agent/orchestrator/providers/gemini-error-contract.mjs

@@ -97,7 +97,10 @@ export function geminiErrorContract({ details, errorDetails, googleStatus, messa
         const scope = scopeOf(String(violation?.quotaId || ''));
         if (scope) scopes.add(scope);
         // A spent allowance is named by the typed violation, not by prose.
-        if (String(violation?.quotaValue ?? '').trim() === '0' || LIMIT_ZERO_RE.test(String(violation?.description || ''))) {
+        if (
+          String(violation?.quotaValue ?? '').trim() === '0' ||
+          LIMIT_ZERO_RE.test(String(violation?.description || ''))
+        ) {
           zeroLimit = true;
         }
       }
@@ -121,7 +124,9 @@ export function geminiErrorContract({ details, errorDetails, googleStatus, messa
     CAPACITY_REASONS.has(reason) ||
     (!reason && scopes.size === 0 && retryAfterMs === undefined && CAPACITY_MESSAGE_RE.test(text));
   // A per-day violation outlasts any per-minute one reported with it.
-  let quotaScope = scopes.has('day') ? 'day' : scopes.has('minute') ? 'minute' : undefined;
+  let quotaScope;
+  if (scopes.has('day')) quotaScope = 'day';
+  else if (scopes.has('minute')) quotaScope = 'minute';
   if (retryAfterMs === undefined) {
     const named = MESSAGE_DELAY_RE.exec(text);
     if (named) retryAfterMs = adviceMs(named[1]);
@@ -158,10 +163,13 @@ export function geminiInBandError(chunk, label) {
   if (!detail || (typeof detail !== 'object' && typeof detail !== 'string')) return null;
   const body = typeof detail === 'object' ? detail : { message: detail };
   const googleStatus = typeof body.status === 'string' ? body.status : '';
-  const status = Number.isFinite(Number(body.code)) && Number(body.code) > 0
-    ? Number(body.code)
-    : GOOGLE_STATUS_HTTP[googleStatus.toUpperCase()];
-  const err = new Error(`${label} in-band error${status ? ` ${status}` : ''}: ${String(body.message || googleStatus || 'unknown').slice(0, 300)}`);
+  const status =
+    Number.isFinite(Number(body.code)) && Number(body.code) > 0
+      ? Number(body.code)
+      : GOOGLE_STATUS_HTTP[googleStatus.toUpperCase()];
+  const err = new Error(
+    `${label} in-band error${status ? ` ${status}` : ''}: ${String(body.message || googleStatus || 'unknown').slice(0, 300)}`
+  );
   err.name = 'GeminiInBandError';
   if (status) {
     err.status = status;

package/src/runtime/agent/orchestrator/providers/gemini-request-body.mjs

@@ -44,10 +44,10 @@ export function buildGeminiRequest(messages, useModel, tools, opts) {
   // explicit opts.includeThoughts still wins.
   const thinkingConfig = geminiThinkingConfig(useModel, opts, { includeThoughts: true });
   const controls = geminiGenerationControls(opts);
-  const generationConfig =
-    thinkingConfig || Object.keys(controls).length
-      ? { ...(thinkingConfig ? { thinkingConfig } : {}), ...controls }
-      : undefined;
+  let generationConfig;
+  if (thinkingConfig || Object.keys(controls).length) {
+    generationConfig = { ...(thinkingConfig ? { thinkingConfig } : {}), ...controls };
+  }
   const systemInstruction =
     messages
       .filter((m) => m.role === 'system')

package/src/runtime/agent/orchestrator/providers/gemini-response.mjs

@@ -149,6 +149,7 @@ export function resolveGeminiUsage(response, opts, cachedContent, useModel) {
 }
 
 export function geminiSendResult(parsed, useModel, opts, resolvedUsage) {
+  if (parsed.providerReplay) parsed.providerReplay.requestContext = { model: useModel };
   return {
     content: parsed.content,
     model: useModel,

package/src/runtime/agent/orchestrator/providers/gemini-rest-stream/watchdogs.mjs

@@ -1,7 +1,11 @@
 // First-byte and idle watchdogs of one Gemini REST SSE body. Either timeout
 // cancels the reader and fails the pending read, so the caller surfaces a typed
-// timeout instead of waiting on a stalled socket.
-import { PROVIDER_SSE_IDLE_TIMEOUT_MS, PROVIDER_SSE_IDLE_WATCHDOG_ENABLED } from '../../stall-policy.mjs';
+// timeout instead of waiting on a stalled socket. The idle timer re-arms only
+// on decoded payloads (semantic progress), so it uses the semantic window.
+// Each timeout names its phase (`timeoutPhase`): 'first-chunk' before any
+// payload, 'idle' after one.
+import { PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS, PROVIDER_SSE_IDLE_WATCHDOG_ENABLED } from '../../stall-policy.mjs';
+import { TIMEOUT_PHASE } from '../../../../shared/provider-timeout-phase.mjs';
 
 export function createRestStreamWatchdogs({ reader, label, firstByteTimeoutMs, timeoutError }) {
   let idleTimedOut = false;
@@ -19,11 +23,18 @@ export function createRestStreamWatchdogs({ reader, label, firstByteTimeoutMs, t
     pendingReject = null;
     reject(err);
   };
-  const idleError = () => timeoutError(`${label} SSE idle`, PROVIDER_SSE_IDLE_TIMEOUT_MS);
+  const idleError = () =>
+    Object.assign(timeoutError(`${label} SSE idle`, PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS), {
+      timeoutPhase: TIMEOUT_PHASE.IDLE,
+    });
 
   let firstByteTimer = setTimeout(() => {
     cancelReader('first byte timeout');
-    failPending(timeoutError(`${label} first byte`, firstByteTimeoutMs));
+    failPending(
+      Object.assign(timeoutError(`${label} first byte`, firstByteTimeoutMs), {
+        timeoutPhase: TIMEOUT_PHASE.FIRST_CHUNK,
+      })
+    );
   }, firstByteTimeoutMs);
   firstByteTimer.unref?.();
   const clearFirstByte = () => {
@@ -46,7 +57,7 @@ export function createRestStreamWatchdogs({ reader, label, firstByteTimeoutMs, t
         idleTimedOut = true;
         cancelReader('SSE idle timeout');
         failPending(idleError());
-      }, PROVIDER_SSE_IDLE_TIMEOUT_MS);
+      }, PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS);
       idleTimer.unref?.();
     },
     // One reader.read() with its reject handle registered for the watchdogs;

package/src/runtime/agent/orchestrator/providers/gemini-retry-policy.mjs

@@ -148,7 +148,12 @@ export async function runGeminiStreamAttempts({ run, signal, onRetry, sleepFn, a
     } catch (err) {
       const waitMs = connected ? geminiMidstreamDelayMs(err, streamAttempt, signal) : null;
       if (waitMs == null) throw err;
-      onRetry?.({ attempt: streamAttempt + 1, maxAttempts: GEMINI_MIDSTREAM_MAX_ATTEMPTS, lastErr: err, delayMs: waitMs });
+      onRetry?.({
+        attempt: streamAttempt + 1,
+        maxAttempts: GEMINI_MIDSTREAM_MAX_ATTEMPTS,
+        lastErr: err,
+        delayMs: waitMs,
+      });
       await sleepWithAbort(waitMs, signal, sleepFn, 'Gemini stream retry wait aborted');
       continue;
     }