mixdog 1.4.0 → 1.4.2

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

@@ -7,6 +7,7 @@ import {
   PROVIDER_SSE_IDLE_WATCHDOG_ENABLED,
   PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS,
   createTimeoutSignal,
+  providerFirstOutputTimeoutMs,
 } from '../stall-policy.mjs';
 import {
   closeCompatStream,
@@ -23,6 +24,7 @@ import {
   parseCompletedToolCallArgumentsJson,
 } from './lib/openai-tool-args.mjs';
 import { handleCompatResponsesStreamEvent } from './openai-compat-responses-events.mjs';
+import { streamFirstOutputWindow } from './lib/first-output-window.mjs';
 import {
   attachPartialState,
   createResponsesLeakRelay,
@@ -56,6 +58,7 @@ export async function consumeCompatResponsesStream(
     responseOutputText,
     knownToolNames,
     semanticIdleTimeoutMs,
+    sessionId = null,
   } = {}
 ) {
   try {
@@ -68,13 +71,23 @@ export async function consumeCompatResponsesStream(
   const idleEnabled = idleOverrideEnabled || PROVIDER_SSE_IDLE_WATCHDOG_ENABLED;
   // Per-event (last-event-relative) SEMANTIC idle — see the Chat path note.
   const idleMs = idleOverrideEnabled ? Number(semanticIdleTimeoutMs) : PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS;
+  // Until the first semantic output the logical request's first-output window
+  // bounds the stream; a request that already had output runs under the
+  // semantic idle from the stream's opening.
+  const firstOutput = streamFirstOutputWindow({
+    sessionId,
+    onStreamDelta,
+    timeoutMs: providerFirstOutputTimeoutMs(idleMs),
+  });
   const state = createResponsesStreamState();
+  if (firstOutput.outputSeen) state.semanticIdleDeadlineAt = Date.now() + idleMs;
   const reportProgress = (kind) => {
     if (kind !== 'transport') state.semanticIdleDeadlineAt = Date.now() + idleMs;
     try {
       onStreamDelta?.(kind);
     } catch {}
   };
+  const reportLifecycle = (kind) => reportProgress(state.semanticIdleDeadlineAt > 0 ? kind : 'transport');
   let sawFirstEvent = false;
   const { relayLeakText, flushLeak, leakedCalls } = createResponsesLeakRelay({
     state,
@@ -88,6 +101,7 @@ export async function consumeCompatResponsesStream(
     parseResponsesToolCalls,
     responseOutputText,
     onStreamDelta: reportProgress,
+    onLifecycle: reportLifecycle,
     onToolCall,
     onTextDelta,
     onStreamItemStart,
@@ -98,9 +112,8 @@ export async function consumeCompatResponsesStream(
     while (true) {
       const { value: event, done } = await nextAsyncWithWatchdog(iterator, {
         signal: sawFirstEvent ? signal : firstByteTimeout.signal,
-        idleMs,
-        idleDeadlineAt: state.semanticIdleDeadlineAt,
-        idleEnabled: sawFirstEvent && idleEnabled && state.semanticIdleDeadlineAt > 0,
+        ...firstOutput.idleWatch(state.semanticIdleDeadlineAt, idleMs),
+        idleEnabled: sawFirstEvent && idleEnabled,
         idleLabel: `${label} SSE idle`,
         streamLabel: label,
         // Unsafe-to-retry once any tool call (native or recovered-leaked)

package/src/runtime/agent/orchestrator/providers/openai-compat-xai-send.mjs

@@ -131,6 +131,7 @@ export async function sendXaiResponses(provider, messages, useModel, tools, opts
           return await consumeCompatResponsesStream(stream, {
             signal: attemptSignal,
             label: 'xai:responses',
+            sessionId: opts.sessionId,
             onStreamDelta: opts.onStreamDelta,
             onToolCall: opts.onToolCall,
             onTextDelta: opts.onTextDelta,

package/src/runtime/agent/orchestrator/providers/openai-http-sse-response-state/response-events/output-items.mjs

@@ -15,7 +15,7 @@ function outputItemKind(item) {
   return 'semantic';
 }
 
-export function createOutputItemEvents({ state, items, meaningful }) {
+export function createOutputItemEvents({ state, items, meaningful, lifecycle }) {
   const { toolTracker } = state;
 
   const onOutputItemAdded = (item) => {
@@ -52,7 +52,10 @@ export function createOutputItemEvents({ state, items, meaningful }) {
       toolTracker.mark(item);
       state.toolInFlight = true;
     }
-    meaningful(state.toolInFlight ? 'tool' : 'semantic');
+    // A tool call starting is model output; an empty reasoning or message
+    // item is lifecycle (the silent thinking follows it).
+    if (state.toolInFlight) meaningful('tool');
+    else lifecycle('semantic');
   };
 
   const onToolInputDelta = (itemId) => {

package/src/runtime/agent/orchestrator/providers/openai-http-sse-response-state/response-events.mjs

@@ -7,18 +7,28 @@ import { createOutputItemEvents } from './response-events/output-items.mjs';
 import { createTerminalFrameEvents } from './response-events/terminal-frames.mjs';
 import { reportStreamItemStart, responsesItemStart } from '../lib/send-callbacks.mjs';
 
-export function createResponseEvents({ state, items, text, outcome, meaningful, onServerEvent, onStreamItemStart }) {
-  const output = createOutputItemEvents({ state, items, meaningful });
+export function createResponseEvents({
+  state,
+  items,
+  text,
+  outcome,
+  meaningful,
+  lifecycle,
+  onServerEvent,
+  onStreamItemStart,
+}) {
+  const output = createOutputItemEvents({ state, items, meaningful, lifecycle });
   const terminal = createTerminalFrameEvents({ state, items, text, outcome, meaningful });
 
   const handleEvent = (event) => {
     if (!event || typeof event.type !== 'string') return;
     onServerEvent();
     switch (event.type) {
+      // The server's ack is metadata, not model output: it satisfies only the
+      // first-server-event deadline (onServerEvent above).
       case 'response.created':
         if (event.response?.model) state.model = event.response.model;
         if (event.response?.id) state.responseId = event.response.id;
-        meaningful('semantic');
         break;
       case 'response.output_text.delta':
         text.relayLeakText(event.delta || '');

package/src/runtime/agent/orchestrator/providers/openai-http-sse-response-state.mjs

@@ -24,7 +24,8 @@ import { createResponseEvents } from './openai-http-sse-response-state/response-
  * @param {(call: object) => void} [deps.onToolCall]
  * @param {(text: string) => void} [deps.onTextDelta]
  * @param {(kind: string) => void} deps.meaningful  semantic progress (re-arms the idle watchdog)
- * @param {() => void} deps.onServerEvent  first-event → semantic-idle handover
+ * @param {(kind: string) => void} [deps.lifecycle]  item lifecycle without output: progress only after semantic output
+ * @param {() => void} deps.onServerEvent  any parsed server event (satisfies the first-server-event deadline)
  * @param {(detail: object) => void} [deps.onStreamItemStart]  a tool call or phased message started
  */
 export function createHttpSseResponseState({
@@ -33,6 +34,7 @@ export function createHttpSseResponseState({
   onTextDelta,
   onStreamItemStart = null,
   meaningful,
+  lifecycle = () => {},
   onServerEvent,
   label,
 }) {
@@ -40,7 +42,16 @@ export function createHttpSseResponseState({
   const outcome = createResponseOutcome({ state });
   const items = createResponseItems({ state, onToolCall });
   const text = createTextRelay({ state, body, onTextDelta, meaningful, emitToolCall: items.emitToolCall });
-  const events = createResponseEvents({ state, items, text, outcome, meaningful, onServerEvent, onStreamItemStart });
+  const events = createResponseEvents({
+    state,
+    items,
+    text,
+    outcome,
+    meaningful,
+    lifecycle,
+    onServerEvent,
+    onStreamItemStart,
+  });
 
   return {
     handleEvent: events.handleEvent,

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

@@ -1,7 +1,15 @@
 /**
  * openai-http-sse-watchdogs.mjs — liveness gates of one HTTP/SSE fallback
  * stream: the total/external abort relay, the fixed first-server-event
- * deadline, the SEMANTIC idle watchdog, and the cancellable reader.read().
+ * deadline, the first-OUTPUT window, the SEMANTIC idle watchdog, and the
+ * cancellable reader.read().
+ *
+ * Until the model's first semantic output (reasoning, text, a tool call) only
+ * the first-server-event deadline and the first-output window run: server
+ * metadata (response.created / in_progress, an empty reasoning or message
+ * item) and keepalives neither end that phase nor start the semantic-idle
+ * clock, so a model may think silently longer than the idle window. From the
+ * first semantic output on, the semantic idle owns the stream.
  *
  * After headerTimeout.cleanup() the in-flight fetch no longer carries a live
  * signal, so a totalTimeout / external abort that fires during a pending
@@ -17,8 +25,10 @@ import {
   PROVIDER_FIRST_BYTE_TIMEOUT_MS,
   PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS,
   PROVIDER_SSE_IDLE_WATCHDOG_ENABLED,
+  providerFirstOutputTimeoutMs,
   streamStalledError,
 } from '../stall-policy.mjs';
+import { streamFirstOutputWindow } from './lib/first-output-window.mjs';
 
 function positiveOverride(value) {
   const ms = Number(value);
@@ -31,8 +41,18 @@ function positiveOverride(value) {
  * @param {ReadableStreamDefaultReader} deps.reader
  * @param {{ signal?: AbortSignal, cleanup(): void }} deps.totalTimeout
  * @param {() => object} deps.stallPartial  streamed partial state attached to a semantic-idle stall
+ * @param {string|null} [deps.sessionId]  the session whose logical request this stream serves
+ * @param {Function} [deps.onStreamDelta]  the stream's progress callback; without it the stream is a fork of the request
  */
-export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartial, label: LABEL }) {
+export function createHttpSseWatchdogs({
+  opts,
+  reader,
+  totalTimeout,
+  stallPartial,
+  label: LABEL,
+  sessionId = null,
+  onStreamDelta,
+}) {
   let abortReason = null;
   let pendingReadReject = null;
   const rejectPendingRead = (err) => {
@@ -58,9 +78,46 @@ export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartia
     else totalTimeout.signal.addEventListener('abort', onTotalAbort, { once: true });
   }
 
-  // Initial wait is governed only by the fixed first-server-event policy.
-  // Semantic idle begins after a parsed server event, so a lower
-  // semantic-idle override cannot shorten this first-event wait.
+  // SEMANTIC idle watchdog: reset ONLY on meaningful() (text/reasoning/tool
+  // deltas), never on raw bytes/keepalive frames, so a stream that emits some
+  // deltas then goes silent trips a short, named terminal failure instead of
+  // hanging until the 30-min agent watchdog. Disablable via the shared env.
+  let semanticIdleTimer = null;
+  const semanticIdleOverrideMs = positiveOverride(opts?._semanticIdleTimeoutMs);
+  const semanticIdleMs = semanticIdleOverrideMs || PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS;
+  const semanticIdleEnabled = semanticIdleOverrideMs > 0 || PROVIDER_SSE_IDLE_WATCHDOG_ENABLED;
+  // FIRST-OUTPUT window of the logical request this stream serves, retired by
+  // the first semantic output. Metadata-only streams (repeated
+  // response.in_progress, keepalive/ping frames, unknown event types) cannot
+  // refresh it, so a wedge that never produces a token still ends here.
+  const firstOutputOverrideMs = positiveOverride(opts?._firstOutputTimeoutMs);
+  const firstOutput = streamFirstOutputWindow({
+    sessionId,
+    onStreamDelta,
+    timeoutMs: firstOutputOverrideMs || providerFirstOutputTimeoutMs(semanticIdleMs),
+  });
+  const firstOutputEnabled = firstOutputOverrideMs > 0 || semanticIdleEnabled;
+
+  // A stalled stream fails with the named stall error, carrying the streamed
+  // partial state so the agent loop can accept a wedged FINAL no-tool summary
+  // as a successful partial-final instead of dropping the result.
+  // pendingToolUse gates out any mid-flight tool call.
+  const abortStalled = (timeoutMs) => {
+    const partial = stallPartial();
+    const err = streamStalledError(LABEL, timeoutMs, { emittedToolCall: partial.emittedToolCall });
+    try {
+      err.partialContent = partial.content;
+      err.partialToolCalls = partial.toolCalls;
+      err.pendingToolUse = partial.pendingToolUse;
+      err.partialModel = partial.model;
+    } catch {
+      /* best-effort enrichment */
+    }
+    abortStream(err);
+  };
+
+  // Initial wait for any server event is governed by the fixed
+  // first-server-event policy; a lower semantic-idle override cannot shorten it.
   let firstServerEventTimer = null;
   const firstServerEventMs = positiveOverride(opts?._firstServerEventTimeoutMs) || PROVIDER_FIRST_BYTE_TIMEOUT_MS;
   const clearFirstServerEvent = () => {
@@ -82,15 +139,15 @@ export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartia
       firstServerEventTimer.unref?.();
     } catch {}
   };
+  // Until the stream's first output the request's first-output window bounds
+  // it. A request that already had output has none: its stream runs under the
+  // semantic idle from its first server event (noteServerEvent).
+  const armFirstOutput = () => {
+    if (!firstOutput.outputSeen && firstOutputEnabled && firstOutput.timeoutMs > 0) {
+      firstOutput.arm(() => abortStalled(firstOutput.timeoutMs));
+    }
+  };
 
-  // SEMANTIC idle watchdog: reset ONLY on meaningful() (text/reasoning/tool
-  // deltas), never on raw bytes/keepalive frames, so a stream that emits some
-  // deltas then goes silent trips a short, named terminal failure instead of
-  // hanging until the 30-min agent watchdog. Disablable via the shared env.
-  let semanticIdleTimer = null;
-  const semanticIdleOverrideMs = positiveOverride(opts?._semanticIdleTimeoutMs);
-  const semanticIdleMs = semanticIdleOverrideMs || PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS;
-  const semanticIdleEnabled = semanticIdleOverrideMs > 0 || PROVIDER_SSE_IDLE_WATCHDOG_ENABLED;
   const clearSemanticIdle = () => {
     if (semanticIdleTimer) {
       clearTimeout(semanticIdleTimer);
@@ -100,43 +157,22 @@ export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartia
   const armSemanticIdle = () => {
     if (!semanticIdleEnabled || !(semanticIdleMs > 0)) return;
     clearSemanticIdle();
-    semanticIdleTimer = setTimeout(() => {
-      const partial = stallPartial();
-      const err = streamStalledError(LABEL, semanticIdleMs, { emittedToolCall: partial.emittedToolCall });
-      // Partial-final recovery: attach the streamed partial state so the
-      // agent loop can accept a wedged FINAL no-tool summary as a successful
-      // partial-final instead of dropping the result. pendingToolUse gates
-      // out any mid-flight tool call.
-      try {
-        err.partialContent = partial.content;
-        err.partialToolCalls = partial.toolCalls;
-        err.pendingToolUse = partial.pendingToolUse;
-        err.partialModel = partial.model;
-      } catch {
-        /* best-effort enrichment */
-      }
-      abortStream(err);
-    }, semanticIdleMs);
+    semanticIdleTimer = setTimeout(() => abortStalled(semanticIdleMs), semanticIdleMs);
     try {
       semanticIdleTimer.unref?.();
     } catch {}
   };
-  // One-shot latch for the first-server-event → semantic-idle handover. Once
-  // the FIRST real SSE server event arrives, the fixed initial deadline is
-  // satisfied and semantic-idle ownership begins. Arming on every parsed event
-  // let a metadata-only stream (repeated response.in_progress, keepalive/ping
-  // frames, unknown event types) refresh the watchdog forever without
-  // producing a single token. Only meaningful progress re-arms it from then on.
-  let semanticIdleArmed = false;
+  // A parsed server event satisfies the first-server-event deadline and, for a
+  // request that already had output, starts the semantic idle (once: only
+  // output re-arms it).
   const noteServerEvent = () => {
     clearFirstServerEvent();
-    if (!semanticIdleArmed) {
-      semanticIdleArmed = true;
-      armSemanticIdle();
-    }
+    if (firstOutput.outputSeen && !semanticIdleTimer) armSemanticIdle();
   };
+  // Semantic output: the first one ends the first-output phase; every one
+  // re-arms the semantic idle.
   const noteMeaningful = () => {
-    semanticIdleArmed = true;
+    firstOutput.noteOutput();
     armSemanticIdle();
   };
 
@@ -151,6 +187,7 @@ export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartia
   const dispose = () => {
     pendingReadReject = null;
     clearFirstServerEvent();
+    firstOutput.clear();
     clearSemanticIdle();
     try {
       reader.releaseLock?.();
@@ -165,9 +202,11 @@ export function createHttpSseWatchdogs({ opts, reader, totalTimeout, stallPartia
   return {
     abortReason: () => abortReason,
     armFirstServerEvent,
+    armFirstOutput,
     clearSemanticIdle,
     noteServerEvent,
     noteMeaningful,
+    semanticSeen: () => firstOutput.outputSeen,
     read,
     dispose,
   };

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

@@ -183,6 +183,8 @@ export async function sendViaHttpSse({
     totalTimeout,
     stallPartial: () => state.stallPartial(),
     label,
+    sessionId: opts?.sessionId,
+    onStreamDelta,
   });
   const meaningful = (kind = 'semantic') => {
     if (ttftMs == null) ttftMs = Date.now() - sseStartedAt;
@@ -191,12 +193,17 @@ export async function sendViaHttpSse({
       onStreamDelta?.(kind);
     } catch {}
   };
+  // An empty reasoning or message item added: progress only after output.
+  const lifecycle = (kind = 'semantic') => {
+    if (watchdogs.semanticSeen()) meaningful(kind);
+  };
   const state = createHttpSseResponseState({
     body,
     onToolCall,
     onTextDelta,
     onStreamItemStart: typeof opts?.onStreamItemStart === 'function' ? opts.onStreamItemStart : null,
     meaningful,
+    lifecycle,
     onServerEvent: watchdogs.noteServerEvent,
     label,
   });
@@ -210,6 +217,7 @@ export async function sendViaHttpSse({
   let buffer = '';
   try {
     watchdogs.armFirstServerEvent();
+    watchdogs.armFirstOutput();
     while (true) {
       if (totalTimeout.signal?.aborted) {
         watchdogs.clearSemanticIdle();

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

@@ -12,9 +12,11 @@ import { createServer } from 'node:http';
 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 { oauthFailureReason, oauthHttpError, oauthRequestError, oauthResponseJson } from './lib/oauth-token-utils.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,14 +25,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;
-
-function _scrubOAuthLoginBody(text) {
-  return String(text || '')
-    .replace(/"access_token"\s*:\s*"[^"]+"/g, '"access_token":"[REDACTED]"')
-    .replace(/"refresh_token"\s*:\s*"[^"]+"/g, '"refresh_token":"[REDACTED]"')
-    .replace(/"id_token"\s*:\s*"[^"]+"/g, '"id_token":"[REDACTED]"')
-    .replace(/[A-Za-z0-9_-]{32,}\.[A-Za-z0-9._-]+/g, '[REDACTED]');
-}
+// 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;
 
 /**
  * @param {object} deps
@@ -40,34 +37,59 @@ 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, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-      body: new URLSearchParams({
-        grant_type: 'authorization_code',
-        code: cleanCode,
-        redirect_uri: REDIRECT_URI,
-        client_id: clientId,
-        code_verifier: pkce.verifier,
-      }),
-      redirect: 'error',
-      signal: signal
-        ? AbortSignal.any([signal, AbortSignal.timeout(TOKEN_TIMEOUT_MS)])
-        : AbortSignal.timeout(TOKEN_TIMEOUT_MS),
-    });
+    let tokenRes;
+    try {
+      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: redirectUri,
+          client_id: clientId,
+          code_verifier: pkce.verifier,
+        }),
+        redirect: 'error',
+        signal: signal
+          ? AbortSignal.any([signal, AbortSignal.timeout(TOKEN_TIMEOUT_MS)])
+          : AbortSignal.timeout(TOKEN_TIMEOUT_MS),
+      });
+    } catch (err) {
+      throw oauthRequestError('[openai-oauth] token exchange', err);
+    }
     if (!tokenRes.ok) {
       const text = await tokenRes.text().catch(() => '');
-      throw new Error(`[openai-oauth] token exchange ${tokenRes.status}: ${_scrubOAuthLoginBody(text).slice(0, 500)}`);
+      throw oauthHttpError('[openai-oauth] token exchange', tokenRes.status, text, [cleanCode, pkce.verifier]);
     }
-    const json = await tokenRes.json();
+    const json = await oauthResponseJson(tokenRes, '[openai-oauth] token exchange');
     if (!json.access_token || !json.refresh_token) {
       throw new Error('[openai-oauth] token exchange response missing access_token or refresh_token');
     }
@@ -87,7 +109,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);
@@ -161,10 +290,10 @@ export function createOpenAIOAuthLogin(deps) {
           // written; do not leave a keep-alive connection bound to it.
           res.writeHead(200, { 'Content-Type': OAUTH_PAGE_CONTENT_TYPE, Connection: 'close' });
           res.end(oauthSuccessHtml('OpenAI'));
-        } catch {
-          // The shared exchange reports its error through waitForCallback.
+        } catch (err) {
+          // The shared exchange also reports its error through waitForCallback.
           res.writeHead(500, { 'Content-Type': OAUTH_PAGE_CONTENT_TYPE, Connection: 'close' });
-          res.end(oauthErrorHtml('OpenAI could not complete the token exchange.'));
+          res.end(oauthErrorHtml(oauthFailureReason('OpenAI could not complete the token exchange.', err)));
         }
       });
       timeout = setTimeout(() => finish(null), LOGIN_TIMEOUT_MS);