mixdog 1.4.0 → 1.4.1

package/src/runtime/agent/orchestrator/providers/openai-oauth-login.mjs

@@ -13,8 +13,9 @@ import { randomBytes } from 'node:crypto';
 import { createOAuthPkce, parseOAuthCodeInput } from './lib/oauth-pkce.mjs';
 import { OAUTH_PAGE_CONTENT_TYPE, oauthErrorHtml, oauthSuccessHtml } from './lib/oauth-page.mjs';
 import { openLoginUrl } from './lib/open-login-url.mjs';
+import { sleepWithAbort } from './retry-backoff.mjs';
 
-const TOKEN_URL = 'https://auth.openai.com/oauth/token';
+const DEFAULT_ISSUER = 'https://auth.openai.com';
 const AUTHORIZE_URL = 'https://auth.openai.com/oauth/authorize';
 const CODEX_OAUTH_SCOPE = 'openid profile email offline_access api.connectors.read api.connectors.invoke';
 const CALLBACK_HOST = '127.0.0.1';
@@ -23,6 +24,9 @@ const CALLBACK_PATH = '/auth/callback';
 const REDIRECT_URI = `http://localhost:${CALLBACK_PORT}${CALLBACK_PATH}`;
 const LOGIN_TIMEOUT_MS = 5 * 60_000;
 const TOKEN_TIMEOUT_MS = 30_000;
+// Codex device-code login: the user has 15 minutes to enter the code.
+const DEVICE_LOGIN_TIMEOUT_MS = 15 * 60_000;
+const DEFAULT_DEVICE_INTERVAL_S = 5;
 
 function _scrubOAuthLoginBody(text) {
   return String(text || '')
@@ -40,21 +44,41 @@ function _scrubOAuthLoginBody(text) {
  * @param {(...tokens:string[])=>(object|null)} deps.identityFromTokens
  * @param {(token:string)=>number} deps.expiryFromAccessToken
  * @param {(tokens:object)=>void} deps.saveTokens
+ * @param {string} [deps.issuer] auth server base URL (tests point it at a fake server)
+ * @param {(ms:number, signal?:AbortSignal)=>Promise<void>} [deps.sleep] device-poll wait (tests inject a fast one)
+ * @param {()=>number} [deps.now]
+ * @param {number} [deps.deviceTimeoutMs] device-code login deadline (tests shorten it)
+ * @param {number} [deps.requestTimeoutMs] deadline of the device-code start request (tests shorten it)
  */
 export function createOpenAIOAuthLogin(deps) {
-  const { clientId, originator, extractAccountId, identityFromTokens, expiryFromAccessToken, saveTokens } = deps;
+  const {
+    clientId,
+    originator,
+    extractAccountId,
+    identityFromTokens,
+    expiryFromAccessToken,
+    saveTokens,
+    issuer = DEFAULT_ISSUER,
+    sleep = sleepWithAbort,
+    now = Date.now,
+    deviceTimeoutMs = DEVICE_LOGIN_TIMEOUT_MS,
+    requestTimeoutMs = TOKEN_TIMEOUT_MS,
+  } = deps;
+  const issuerBase = issuer.replace(/\/+$/, '');
+  const tokenUrl = `${issuerBase}/oauth/token`;
+  const deviceApiBase = `${issuerBase}/api/accounts`;
 
-  async function exchangeAuthorizationCode({ pkce, code, signal = null }) {
+  async function exchangeAuthorizationCode({ pkce, code, redirectUri = REDIRECT_URI, signal = null }) {
     signal?.throwIfAborted();
     const cleanCode = String(code || '').trim();
     if (!cleanCode) throw new Error('[openai-oauth] authorization code is required');
-    const tokenRes = await fetch(TOKEN_URL, {
+    const tokenRes = await fetch(tokenUrl, {
       method: 'POST',
       headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
       body: new URLSearchParams({
         grant_type: 'authorization_code',
         code: cleanCode,
-        redirect_uri: REDIRECT_URI,
+        redirect_uri: redirectUri,
         client_id: clientId,
         code_verifier: pkce.verifier,
       }),
@@ -87,7 +111,114 @@ export function createOpenAIOAuthLogin(deps) {
     return tokens;
   }
 
+  const postJson = (path, body, signal) =>
+    fetch(`${deviceApiBase}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      redirect: 'error',
+      signal,
+    });
+
+  // Codex device-code flow (`codex login --device-auth`): the user enters a
+  // short code at the verification URL on any machine; this host polls until
+  // the server hands back an authorization code, then exchanges it with the
+  // deviceauth redirect URI. Resolves null when the server has no device flow.
+  async function beginDeviceLogin() {
+    // No login deadline or cancel handle exists yet, so the start request
+    // carries its own timeout; it also bounds reading the response body.
+    const startSignal = AbortSignal.timeout(requestTimeoutMs);
+    const res = await postJson('/deviceauth/usercode', { client_id: clientId }, startSignal);
+    if (res.status === 404) return null;
+    if (!res.ok) throw new Error(`[openai-oauth] device code request failed with status ${res.status}`);
+    const started = await res.json();
+    const userCode = started.user_code || started.usercode;
+    const deviceAuthId = started.device_auth_id;
+    if (!userCode || !deviceAuthId)
+      throw new Error('[openai-oauth] device code response missing user_code or device_auth_id');
+    const interval = Number(String(started.interval ?? '').trim());
+    const intervalMs = (Number.isFinite(interval) && interval > 0 ? interval : DEFAULT_DEVICE_INTERVAL_S) * 1000;
+    const url = `${issuerBase}/codex/device`;
+
+    const controller = new AbortController();
+    const { signal } = controller;
+    const timedOut = () => new Error('[openai-oauth] device auth timed out after 15 minutes');
+    // One poll, aborted at the login deadline so a stalled request cannot
+    // outlive it. A reply that arrives in time is honoured whatever the clock
+    // says afterwards (the user did authorize).
+    const pollOnce = async (left) => {
+      const deadlineController = new AbortController();
+      const timer = setTimeout(() => deadlineController.abort(), left);
+      try {
+        const poll = await postJson(
+          '/deviceauth/token',
+          { device_auth_id: deviceAuthId, user_code: userCode },
+          AbortSignal.any([signal, deadlineController.signal])
+        );
+        if (poll.ok) return { granted: await poll.json() };
+        // 403/404: the user has not approved the code yet.
+        if (poll.status !== 403 && poll.status !== 404) {
+          throw new Error(`[openai-oauth] device auth failed with status ${poll.status}`);
+        }
+        return { granted: null };
+      } catch (err) {
+        if (!signal.aborted && deadlineController.signal.aborted) throw timedOut();
+        throw err;
+      } finally {
+        clearTimeout(timer);
+      }
+    };
+    const pollForCode = async () => {
+      const deadline = now() + deviceTimeoutMs;
+      for (;;) {
+        const left = deadline - now();
+        if (left <= 0) throw timedOut();
+        const { granted } = await pollOnce(left);
+        if (granted) return granted;
+        await sleep(Math.min(intervalMs, Math.max(0, deadline - now())), signal);
+      }
+    };
+    const waitForCallback = (async () => {
+      try {
+        const granted = await pollForCode();
+        return await exchangeAuthorizationCode({
+          pkce: { verifier: granted.code_verifier },
+          code: granted.authorization_code,
+          redirectUri: `${issuerBase}/deviceauth/callback`,
+          signal,
+        });
+      } catch (err) {
+        // A cancelled login settles empty, as the browser flow does.
+        if (signal.aborted) return null;
+        throw err;
+      }
+    })();
+    // A cancelled or expired login may reject before a host attaches a listener.
+    waitForCallback.catch(() => {});
+    process.stderr.write(
+      `\n[openai-oauth] To log in to ChatGPT (OpenAI OAuth), open:\n${url}\nand enter this code: ${userCode}\n\n`
+    );
+    return {
+      provider: 'openai-oauth',
+      url,
+      userCode,
+      waitForCallback,
+      cancel: () => controller.abort(),
+    };
+  }
+
+  // Without a browser on this host (headless/SSH) the device-code flow is used;
+  // like Codex, a server that has none (404) falls back to the browser flow.
   async function beginOAuthLogin({ openBrowser = true } = {}) {
+    if (!openBrowser) {
+      const device = await beginDeviceLogin();
+      if (device) return device;
+      process.stderr.write('\n[openai-oauth] Device code login is not enabled; falling back to browser login.\n');
+    }
+    return await beginBrowserLogin({ openBrowser });
+  }
+
+  async function beginBrowserLogin({ openBrowser }) {
     const pkce = createOAuthPkce(64);
     const state = randomBytes(16).toString('hex');
     const url = new URL(AUTHORIZE_URL);

package/src/runtime/agent/orchestrator/providers/openai-ws-stream/event-switch.mjs

@@ -27,11 +27,22 @@ export function createWsEventSwitch({
     // already cleared the pre-stream watchdog and armed the single idle timer.
     // response.created is a MEANINGFUL frame, so it also satisfies the
     // first-meaningful watchdog (keepalive/metadata frames never reach here,
-    // so they never clear it). Semantic idle is not armed until actual model
-    // progress; transport-only reasoning heartbeats are bounded by the outer
-    // first-visible ceiling instead.
+    // so they never clear it). It is still metadata, not model output: it
+    // neither ends the first-output phase nor arms the semantic idle, and the
+    // agent sees it as transport.
     watchdogs.clearFirstMeaningful();
-    progress('semantic');
+    progress('transport');
+  }
+
+  // A tool item starting is model output: it resets the semantic-idle timer so
+  // long server-side tool latency after item-added (before any arg delta) is
+  // not mistaken for a silent stall. An empty reasoning or message item is
+  // progress only once the model has produced output; before that the silent
+  // thinking follows it.
+  function onItemAdded() {
+    const kind = response.toolInFlight ? 'tool' : watchdogs.semanticSeen() ? 'semantic' : null;
+    if (kind) watchdogs.bumpSemantic();
+    progress(kind ?? 'transport');
   }
 
   function onOutputTextDelta(delta) {
@@ -84,11 +95,7 @@ export function createWsEventSwitch({
       case 'response.output_item.added':
         response.noteItemAdded(event.item);
         reportStreamItemStart(onStreamItemStart, responsesItemStart(event.item));
-        // Item lifecycle is genuine progress: reset the semantic-idle timer so
-        // long server-side tool latency after item-added (before any arg
-        // delta) is not mistaken for a silent stall.
-        watchdogs.resetSemantic();
-        progress(response.toolInFlight ? 'tool' : 'semantic');
+        onItemAdded();
         break;
       case 'response.function_call_arguments.delta':
       case 'response.custom_tool_call_input.delta':
@@ -115,9 +122,10 @@ export function createWsEventSwitch({
         const kind = response.completeOutputItem(event.item);
         // A stream that names the phase only on the finished message.
         if (event.item?.type === 'message') reportStreamItemStart(onStreamItemStart, responsesItemStart(event.item));
-        // Item-done is genuine lifecycle progress — reset semantic idle so
-        // latency before the next item/args does not stall.
-        watchdogs.resetSemantic();
+        // A completed item (reasoning, message, tool call) is model output —
+        // it ends the first-output phase and resets semantic idle so latency
+        // before the next item/args does not stall.
+        watchdogs.bumpSemantic();
         progress(kind);
         break;
       }

package/src/runtime/agent/orchestrator/providers/openai-ws-stream.mjs

@@ -24,11 +24,13 @@ import {
   PROVIDER_SSE_IDLE_WATCHDOG_ENABLED,
   PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS,
   PROVIDER_WS_SEMANTIC_IDLE_TIMEOUT_MS,
+  providerFirstOutputTimeoutMs,
 } from '../stall-policy.mjs';
 import { _wsErrLabel, WS_MAX_INCOMING_FRAME_BYTES } from './openai-ws-pool.mjs';
 import { createWsResponseState } from './openai-ws-response-state.mjs';
 import { createWsTextRelay } from './openai-ws-text-relay.mjs';
 import { createWsStreamWatchdogs } from './openai-ws-watchdogs.mjs';
+import { streamFirstOutputWindow } from './lib/first-output-window.mjs';
 import {
   enableSessionTransportTracking,
   disableSessionTransportTracking,
@@ -85,6 +87,7 @@ function resolveStreamTimeouts(_timeouts) {
     interChunkMs: _positiveInt(_timeouts?.interChunkMs, WS_INTER_CHUNK_MS),
     maxIncomingFrameBytes: _positiveInt(_timeouts?.maxIncomingFrameBytes, WS_MAX_INCOMING_FRAME_BYTES),
     firstMeaningfulMs: _positiveInt(_timeouts?.firstMeaningfulMs, PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS),
+    firstOutputMs: _positiveInt(_timeouts?.firstOutputMs, providerFirstOutputTimeoutMs(semanticIdleMs)),
     semanticIdleMs,
     semanticIdleEnabled: PROVIDER_SSE_IDLE_WATCHDOG_ENABLED && semanticIdleMs > 0,
   };
@@ -112,7 +115,8 @@ export async function _streamResponse({
   if (socket?.readyState === WebSocket.OPEN) {
     markSessionTransportActivity(state?.sessionId);
   }
-  const { maxIncomingFrameBytes, ...timeouts } = resolveStreamTimeouts(_timeouts);
+  const { maxIncomingFrameBytes, firstOutputMs, ...timeouts } = resolveStreamTimeouts(_timeouts);
+  const firstOutput = streamFirstOutputWindow({ sessionId: state?.sessionId, onStreamDelta, timeoutMs: firstOutputMs });
   const streamingStart = Date.now();
   // Mid-stream retry classifier needs to distinguish "stream died before we
   // even saw response.created" from "stream died after we had a partial
@@ -182,6 +186,7 @@ export async function _streamResponse({
       streamingStart,
       currentModel: () => response.model,
       timeouts,
+      firstOutput,
       attachPartialState,
       fail,
     });
@@ -256,6 +261,7 @@ export async function _streamResponse({
     if (!handlers.attach()) return;
     watchdogs.armPreStream();
     watchdogs.armFirstMeaningful();
+    watchdogs.armFirstOutput();
     // No proactive client ping: Codex's Responses WebSocket uses the library
     // default (automatic pong replies, no periodic client ping). Incoming
     // frames remain bounded by the 300s stream idle timeout.

package/src/runtime/agent/orchestrator/providers/openai-ws-watchdogs.mjs

@@ -1,14 +1,18 @@
 /**
- * openai-ws-watchdogs.mjs — the four timers that bound one Responses WS
+ * openai-ws-watchdogs.mjs — the five timers that bound one Responses WS
  * stream, and what each one proves when it fires:
  *
  *   pre-stream      — no server event at all after response.create (a wedged
  *                     post-upgrade socket); cleared by ANY frame.
  *   first-meaningful — no response.created / content / tool-arg delta, even
  *                     while keepalive frames keep arriving; cleared once.
+ *   first-output    — no semantic output (reasoning, text, tool call) within
+ *                     the first-output window; metadata, empty items and
+ *                     keepalives never clear or extend it; cleared once.
  *   inter-chunk     — byte silence mid-stream; reset by EVERY frame.
- *   semantic idle   — deltas then silence (keepalives only); reset only by
- *                     meaningful output and item lifecycle.
+ *   semantic idle   — deltas then silence (keepalives only); armed by the
+ *                     first semantic output, then reset by meaningful output
+ *                     and item lifecycle.
  *
  * Every expiry hands a tagged error to `fail`, which owns terminalError, the
  * socket close and the settle; the timers never touch the Promise.
@@ -23,6 +27,8 @@ import { streamStalledError } from '../stall-policy.mjs';
  * @param {number} deps.streamingStart
  * @param {() => string} deps.currentModel
  * @param {{ preResponseCreatedMs: number, firstMeaningfulMs: number, interChunkMs: number, semanticIdleMs: number, semanticIdleEnabled: boolean }} deps.timeouts
+ * @param {ReturnType<typeof import('./lib/first-output-window.mjs').streamFirstOutputWindow>} deps.firstOutput
+ *   the logical request's first-output window
  * @param {(err: Error) => Error} deps.attachPartialState
  * @param {(err: Error, closeReason: string) => void} deps.fail
  */
@@ -32,6 +38,7 @@ export function createWsStreamWatchdogs({
   streamingStart,
   currentModel,
   timeouts,
+  firstOutput,
   attachPartialState,
   fail,
 }) {
@@ -90,23 +97,25 @@ export function createWsStreamWatchdogs({
       fail(err, 'inter_chunk_timeout');
     }, interChunkMs);
   };
+  // A semantic stall (first-output or idle window): partial-final recovery
+  // attaches the streamed partial state so a wedged FINAL no-tool summary can
+  // be accepted as partial-final success by the loop. pendingToolUse gates
+  // out mid-flight tools.
+  const failStalled = (event, timeoutMs) => {
+    traceWsTimeout(event, timeoutMs);
+    const err = streamStalledError('Responses WS', timeoutMs, {
+      emittedToolCall: !!midState?.emittedToolCall,
+    });
+    attachPartialState(err);
+    try {
+      err.wsCloseCode = 4000;
+    } catch {}
+    fail(err, event);
+  };
   const resetSemanticIdle = () => {
     if (!semanticIdleEnabled) return;
     if (semanticIdleTimer) clearTimeout(semanticIdleTimer);
-    semanticIdleTimer = setTimeout(() => {
-      traceWsTimeout('semantic_idle_timeout', semanticIdleMs);
-      const err = streamStalledError('Responses WS', semanticIdleMs, {
-        emittedToolCall: !!midState?.emittedToolCall,
-      });
-      // Partial-final recovery: attach streamed partial state so a wedged
-      // FINAL no-tool summary can be accepted as partial-final success by
-      // the loop. pendingToolUse gates out mid-flight tools.
-      attachPartialState(err);
-      try {
-        err.wsCloseCode = 4000;
-      } catch {}
-      fail(err, 'semantic_idle_timeout');
-    }, semanticIdleMs);
+    semanticIdleTimer = setTimeout(() => failStalled('semantic_idle_timeout', semanticIdleMs), semanticIdleMs);
     try {
       semanticIdleTimer.unref?.();
     } catch {}
@@ -164,24 +173,41 @@ export function createWsStreamWatchdogs({
         firstMeaningfulTimer.unref?.();
       } catch {}
     },
+    /** Fires if the logical request produces no semantic output by its
+     *  first-output deadline. Metadata (response.created / in_progress), empty
+     *  item lifecycle and keepalive frames never clear or extend it, and the
+     *  shorter semantic idle does not run before the first output, so a model
+     *  may think silently past the idle window. A request that already had
+     *  output has none: its stream runs under the semantic idle from its
+     *  first frame (resetIdle). */
+    armFirstOutput() {
+      if (!firstOutput.outputSeen && semanticIdleEnabled && firstOutput.timeoutMs > 0) {
+        firstOutput.arm(() => failStalled('first_output_timeout', firstOutput.timeoutMs));
+      }
+    },
     /** Called on EVERY parsed server event: any frame proves the socket is
      *  live. Also clears the pre-stream watchdog in case the first event is
-     *  not response.created. */
+     *  not response.created, and starts the semantic idle (once) for a
+     *  request that already had output. */
     resetIdle() {
       clearPreStream();
       resetInterChunk();
+      if (firstOutput.outputSeen && !semanticIdleTimer) resetSemanticIdle();
     },
-    /** Meaningful-output progress: text/reasoning/tool-arg deltas. The
-     *  first one also satisfies the first-meaningful watchdog. */
+    /** Meaningful-output progress: text/reasoning/tool output. The first one
+     *  also satisfies the first-meaningful watchdog and ends the first-output
+     *  phase. */
     bumpSemantic() {
       clearFirstMeaningful();
+      firstOutput.noteOutput();
       resetSemanticIdle();
     },
-    /** Item lifecycle progress (added/done) without a delta. */
-    resetSemantic: resetSemanticIdle,
+    /** Whether the model has produced semantic output on this stream. */
+    semanticSeen: () => firstOutput.outputSeen,
     /** response.created is meaningful on its own. */
     clearFirstMeaningful,
     clearAll() {
+      firstOutput.clear();
       if (idleTimer) clearTimeout(idleTimer);
       if (interChunkTimer) {
         clearTimeout(interChunkTimer);

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

@@ -684,6 +684,18 @@ export function refreshProviderCatalogsOnStartup() {
   return _startupCatalogRefreshPromise;
 }
 
+// Force-refresh only the named providers' catalogs, each bounded like the full
+// refresh. It leaves the 24h window, the catalog revision and every other
+// provider's cache alone.
+export function refreshProviderCatalogsFor(names) {
+  const pending = [];
+  for (const [name, provider] of availableProviderEntries()) {
+    const refreshFn = names.includes(name) ? providerCatalogRefreshFn(provider) : null;
+    if (refreshFn) pending.push(boundedCatalogRefresh(name, provider, refreshFn, 'catalog refresh'));
+  }
+  return Promise.allSettled(pending);
+}
+
 // Refresh the complete catalog at most once per 24h process window. The timer
 // above calls this automatically when the window expires; callers may bypass
 // that window after an explicit auth/config/model-refresh action.

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

@@ -8,9 +8,9 @@ export const ASK_USER_TOOL_DEFS = Object.freeze([
     name: 'ask_user',
     title: 'Ask User',
     trigger:
-      'Ask the user 1–4 multiple-choice questions and wait; when a plan needs the user to pick between clear options, instead of listing them in chat. Also hands the user a page or app step (CAPTCHA, sign-in, 2FA, a secret).',
+      'Ask the user 1–4 multiple-choice questions and wait; when a plan needs the user to pick between clear options, instead of listing them in chat.',
     description:
-      'Ask the user multiple-choice questions and wait. Only for a decision only the user can make, with clear options; never for minor choices or approval of requested work, and open questions go in chat. Do not repeat the options in your message. A step only the user can do on a page or app (CAPTCHA, human check, sign-in, 2FA, a password) is a handoff here, never a request in plain chat.',
+      'Ask the user multiple-choice questions and wait. Only for a decision only the user can make, with clear options; never for minor choices or approval of requested work, and open questions go in chat. Do not repeat the options in your message. A step only the user can do on a page or app (CAPTCHA, human check, sign-in, 2FA, a password) goes to handoff_user, never a request in plain chat. Load handoff_user directly if needed; browser/computer skills are not prerequisites.',
     annotations: {
       title: 'Ask User',
       readOnlyHint: true,
@@ -52,10 +52,37 @@ export const ASK_USER_TOOL_DEFS = Object.freeze([
             required: ['question', 'header', 'options'],
           },
         },
+      },
+      additionalProperties: false,
+    },
+  },
+]);
+
+// The deferred handoff tool: loaded with the browser-use and computer-use
+// skills (dependencies.tools), the only surfaces a handoff targets.
+export const HANDOFF_USER_TOOL_DEFS = Object.freeze([
+  {
+    name: 'handoff_user',
+    title: 'Hand Off To User',
+    trigger:
+      'Hand the user a page or app step (CAPTCHA, sign-in, 2FA, a secret); loads with the browser-use and computer-use skills.',
+    description:
+      'A step only the user can do on a page or app (CAPTCHA, human check, sign-in, 2FA, a password) is a handoff here, never a request in plain chat.',
+    annotations: {
+      title: 'Hand Off To User',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: false,
+      agentHidden: true,
+    },
+    inputSchema: {
+      type: 'object',
+      properties: {
         handoff: {
           type: 'object',
           description:
-            'Instead of questions: secret = the user types a password, sign-in, new password or one-time code into that field of the page (you never see it; result entered/user_skipped/no_field/page_changed/blocked/expired); takeover = the user does a step (sign-in, CAPTCHA, 2FA) and says done.',
+            'secret = the user types a password, sign-in, new password or one-time code into that field of the page (you never see it; result entered/user_skipped/no_field/page_changed/blocked/expired); takeover = the user does a step and says done.',
           properties: {
             kind: { type: 'string', enum: ['secret', 'takeover'] },
             surface: { type: 'string', enum: ['browser', 'computer'] },
@@ -83,26 +110,26 @@ export const ASK_USER_TOOL_DEFS = Object.freeze([
           additionalProperties: false,
         },
       },
+      required: ['handoff'],
       additionalProperties: false,
     },
   },
 ]);
 
-/** The handoff of an ask_user call ({ kind, surface, target, field, instructions }), or null. */
-export function validateAskUserHandoff(args) {
+/** The handoff of a handoff_user call ({ kind, surface, target, field, instructions, … }). */
+export function validateUserHandoff(args) {
   const handoff = args?.handoff;
-  if (handoff == null) return null;
-  if (args.questions != null) throw new Error('ask_user takes questions or a handoff, not both');
-  if (typeof handoff !== 'object' || Array.isArray(handoff)) throw new Error('ask_user handoff must be an object');
+  if (handoff == null) throw new Error('handoff_user needs a handoff');
+  if (typeof handoff !== 'object' || Array.isArray(handoff)) throw new Error('handoff_user handoff must be an object');
   if (handoff.kind !== 'secret' && handoff.kind !== 'takeover') {
-    throw new Error('ask_user handoff kind is secret or takeover');
+    throw new Error('handoff_user handoff kind is secret or takeover');
   }
   if (handoff.surface !== 'browser' && handoff.surface !== 'computer') {
-    throw new Error('ask_user handoff surface is browser or computer');
+    throw new Error('handoff_user handoff surface is browser or computer');
   }
   const text = (key, limit) => (typeof handoff[key] === 'string' ? handoff[key].trim().slice(0, limit) : '');
   if (handoff.kind === 'takeover' && !text('instructions', 2000)) {
-    throw new Error('ask_user takeover needs instructions');
+    throw new Error('handoff_user takeover needs instructions');
   }
   const login = handoffLogin(handoff);
   let need = login ? 'sign_in' : 'action';
@@ -125,10 +152,10 @@ export function validateAskUserHandoff(args) {
 function handoffLogin(handoff) {
   if (handoff.purpose == null) return null;
   if (handoff.purpose !== 'login' || handoff.kind !== 'takeover' || handoff.surface !== 'browser') {
-    throw new Error('ask_user purpose login is a browser takeover');
+    throw new Error('handoff_user purpose login is a browser takeover');
   }
   const page = loginPageUrl(handoff.url);
-  if (!page) throw new Error('ask_user login needs an https url (http only on localhost)');
+  if (!page) throw new Error('handoff_user login needs an https url (http only on localhost)');
   return page;
 }
 
@@ -159,6 +186,7 @@ function handoffIdentity(handoff) {
 
 /** Throws a clear error when the questions are malformed; returns the list. */
 export function validateAskUserQuestions(args) {
+  if (args?.handoff != null) throw new Error('ask_user takes questions only; a page or app step goes to handoff_user');
   const questions = args?.questions;
   if (!Array.isArray(questions) || questions.length < 1 || questions.length > ASK_USER_MAX_QUESTIONS) {
     throw new Error(`ask_user requires 1-${ASK_USER_MAX_QUESTIONS} questions`);

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

@@ -10,7 +10,7 @@ same change scope rather than splitting every file or step.`,
   swarm: `Delegate every independent scope to its own agent; a scope is one
 verifiable deliverable, not a bundle of steps. Treat disjoint file or
 module sets as independent and merge scopes only on a true output
-dependency. Prefer parallel scopes over sequential slices in one agent.`,
+dependency.`,
 };
 
 const SOLO = `# Orchestration Mode: Solo
@@ -34,14 +34,16 @@ self-contained brief.`;
 export function orchestrationInstructions(value) {
   const mode = normalizeOrchestrationMode(value);
   if (mode === 'none') return SOLO;
+  // Focused already says Lead executes the main scope directly.
+  const oneScope =
+    mode === 'focused' ? '' : '\nIf the plan has only one implementation scope, Lead executes it directly.';
   return `# Orchestration Mode: ${mode[0].toUpperCase()}${mode.slice(1)}
 
 ${BATCHING[mode]}
 
 The mode sets how work splits; an agent's description sets its role and when
 it runs. Splitting applies to every role alike — implementation, review,
-investigation, writing — by file, module, commit range or risk area.
-If the plan has only one implementation scope, Lead executes it directly.
+investigation, writing — by file, module, commit range or risk area.${oneScope}
 
 Delegation is for work whose size justifies a brief. When the brief would have
 to spell out the edits themselves — a few localized changes whose sites Lead
@@ -49,9 +51,8 @@ already holds — Lead makes them directly in every mode; the number of files or
 scopes does not change this.
 
 Dispatch all ready independent scopes in one turn. Only a scope that requires
-another's output waits. Brief each agent as the Lead rules describe.
-A running agent receives only changes within its own scope; a new independent
-need goes to a new agent. When scopes touch the same file, name one owner for
+another's output waits.
+A new independent need goes to a new agent. When scopes touch the same file, name one owner for
 that file in each brief.
 Use only available agents; when none fits a role, Lead does that work itself
 and never changes settings to enable one.`;

package/src/runtime/agent/orchestrator/runtime-core/session-text.mjs

@@ -84,12 +84,16 @@ export function cleanSessionPreview(text, max = 160) {
   const limit = Math.max(16, Number(max) || 160);
   // Previews run on truncated source: an injected block that lost its closing
   // tag still must not become the preview.
-  return stripInjectedBlocks(stripSessionDisplayEnvelope(text), { dropUnterminated: true })
+  const cleaned = stripInjectedBlocks(stripSessionDisplayEnvelope(text), { dropUnterminated: true })
     .replace(/\[(?:Pasted text|Image)\s*#?\d+(?:\s*(?::[^\]\r\n]*|\+\d+\s+lines))?\]/gi, ' ')
     .replace(/^Reference files:\s*/i, '')
     .replace(/\s+/g, ' ')
-    .trim()
-    .slice(0, limit);
+    .trim();
+  if (cleaned.length <= limit) return cleaned;
+  // A slice of a longer string keeps that whole string alive in V8. Previews
+  // outlive their message (summary rows, catalog caches, the preview memo), so
+  // the cut is copied out: a 160-char preview must not pin the whole reply.
+  return JSON.parse(JSON.stringify(cleaned.slice(0, limit)));
 }
 
 // Stable sentinel carried in late-tool (deferred MCP) announcement reminders.

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';