@pure01fx/dsh-openai-codex-auth 0.11.2 → 0.13.0

package/lib/native-websocket.js

@@ -1,5 +1,6 @@
 /** WebSocket v2 Responses transport with bounded session state and sticky HTTP fallback. */
 import { createHash } from 'node:crypto';
+import { retryError, remainingRetryDelay, sleepRetry, jsonRetryAfterMs } from './retry-after.js';
 import { networkTelemetry, trackNetwork, observeNetworkOutput } from './network-telemetry.js';
 import { LlmError, ProviderRequestId, attributionHeaders, } from '@deepseek-ai/dsh-llm';
 import { nativeCodexAuthorityHash } from './catalog.js';
@@ -22,7 +23,7 @@ const INITIAL_CONNECTION_RETRY_DELAY_MS = 5_000;
 const MAX_CONNECTION_RETRY_DELAY_MS = 60_000;
 const MAX_TURN_STATE_BYTES = 4096;
 function failure(message, code, cause) {
-    return new LlmError(message, code, cause === undefined ? undefined : { cause });
+    return retryError(message, code, cause === undefined ? undefined : { cause });
 }
 function reconnectable(code) {
     return [
@@ -36,9 +37,8 @@ function failedStepRetryable(code) {
 }
 function failedStepRetry(error) {
     const facts = error.failure;
-    const providerRetryAfterMs = facts.providerRetryAfterMs === undefined
-        ? undefined : Math.min(facts.providerRetryAfterMs, DEFAULT_MAX_RETRY_DELAY_MS);
-    return new LlmError(`native Codex response stream was interrupted: ${error.message}`, NATIVE_CODEX_STREAM_INTERRUPTED_CODE, {
+    const providerRetryAfterMs = facts.providerRetryAfterMs;
+    return retryError(`native Codex response stream was interrupted: ${error.message}`, NATIVE_CODEX_STREAM_INTERRUPTED_CODE, {
         cause: error,
         ...(facts.status === undefined ? {} : { status: facts.status }),
         ...(providerRetryAfterMs === undefined ? {} : { providerRetryAfterMs }),
@@ -65,26 +65,6 @@ function retryCount(value) {
     }
     return resolved;
 }
-function sleep(delayMs, signal) {
-    if (signal?.aborted) {
-        return Promise.reject(failure('native Codex WebSocket retry wait was aborted', 'ABORTED'));
-    }
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(done, delayMs);
-        const abort = () => {
-            clearTimeout(timer);
-            signal?.removeEventListener('abort', abort);
-            const reason = signal?.reason;
-            reject(reason instanceof LlmError
-                ? reason : failure('native Codex WebSocket retry wait was aborted', 'ABORTED'));
-        };
-        function done() {
-            signal?.removeEventListener('abort', abort);
-            resolve();
-        }
-        signal?.addEventListener('abort', abort, { once: true });
-    });
-}
 function socketCredential(credential) {
     return createHash('sha256')
         .update(credential.accountId).update('\0').update(credential.accessToken)
@@ -98,7 +78,8 @@ function sessionKey(generation, routingId) {
 function turnKey(generation) {
     for (let index = generation.messages.length - 1; index >= 0; index--) {
         const message = generation.messages[index];
-        if (message?.source.kind === 'user') {
+        // RequestUserInput doesn't have source or id
+        if (message && 'source' in message && message.source?.kind === 'user' && 'id' in message) {
             return createHash('sha256').update(String(message.id)).digest('base64url');
         }
     }
@@ -122,15 +103,17 @@ function withRequestMetadata(request, turnState, responsesLite) {
         },
     };
 }
-function normalizedOutputItem(event) {
+function normalizedOutputItem(event, translator) {
     if (event.type !== 'response.output_item.done' || event.item === undefined)
         return undefined;
     const item = event.item;
     const id = replayableItemId(item.id);
     if (item.type === 'message') {
+        const phase = item.id === undefined ? undefined : translator.messagePhase(item.id);
         return {
             type: 'message', ...(id === undefined ? {} : { id }), role: 'assistant',
             content: (item.content ?? []).map(part => ({ type: 'output_text', text: part.text })),
+            ...(phase === undefined ? {} : { phase }),
         };
     }
     if (item.type === 'reasoning') {
@@ -163,10 +146,9 @@ function eventHeader(event, name) {
 }
 function eventErrorFacts(event, status) {
     const requestId = eventHeader(event, 'x-request-id');
-    const retryAfter = eventHeader(event, 'retry-after');
-    const seconds = retryAfter === undefined ? undefined : Number(retryAfter);
-    const retryMs = seconds !== undefined && Number.isFinite(seconds) && seconds > 0
-        ? Math.min(seconds * 1_000, 120_000) : undefined;
+    const nested = typeof event.error === 'object' && event.error !== null
+        ? event.error : undefined;
+    const retryMs = jsonRetryAfterMs(nested?.headers) ?? jsonRetryAfterMs(event.headers);
     return {
         ...(status === undefined ? {} : { status }),
         ...(retryMs === undefined ? {} : { providerRetryAfterMs: retryMs }),
@@ -186,28 +168,28 @@ function eventFailure(event) {
     const facts = eventErrorFacts(event, status);
     if (providerCode === 'websocket_connection_limit_reached'
         || providerCode === 'previous_response_not_found') {
-        return new LlmError('native Codex WebSocket requested a fresh connection', 'WS_RETRYABLE_RESET', facts);
+        return retryError('native Codex WebSocket requested a fresh connection', 'WS_RETRYABLE_RESET', facts);
     }
     if (providerCode === 'unauthorized' || providerCode === 'invalid_api_key' || status === 401) {
-        return new LlmError('native Codex WebSocket authentication failed', 'WS_AUTH', facts);
+        return retryError('native Codex WebSocket authentication failed', 'WS_AUTH', facts);
     }
     if (status === 403)
-        return new LlmError('native Codex WebSocket authorization failed', 'AUTH', facts);
+        return retryError('native Codex WebSocket authorization failed', 'AUTH', facts);
     const classified = responsesFailure(providerCode, typeof error.message === 'string' ? error.message : undefined);
     if (classified.code !== 'SERVER') {
         const delay = facts?.providerRetryAfterMs ?? classified.failure.providerRetryAfterMs;
-        return new LlmError(classified.message, classified.code === 'RATE_LIMIT' ? 'RATE_LIMITED' : classified.code, {
+        return retryError(classified.message, classified.code === 'RATE_LIMIT' ? 'RATE_LIMITED' : classified.code, {
             ...facts,
-            ...(delay === undefined ? {} : { providerRetryAfterMs: Math.min(delay, 120_000) }),
+            ...(delay === undefined ? {} : { providerRetryAfterMs: delay }),
         });
     }
     if (providerCode === 'usage_limit_reached' || status === 429) {
-        return new LlmError('native Codex WebSocket rate limit was reached', 'RATE_LIMITED', facts);
+        return retryError('native Codex WebSocket rate limit was reached', 'RATE_LIMITED', facts);
     }
     if (status !== undefined && status >= 500) {
-        return new LlmError('native Codex WebSocket service failed', 'WS_RETRYABLE', facts);
+        return retryError('native Codex WebSocket service failed', 'WS_RETRYABLE', facts);
     }
-    return new LlmError('native Codex WebSocket request was rejected', 'INVALID_REQUEST', facts);
+    return retryError('native Codex WebSocket request was rejected', 'INVALID_REQUEST', facts);
 }
 /** Prefer WebSocket v2; once safe retries exhaust, keep that DSH session on HTTP. */
 export class NativeCodexWebSocketTransport {
@@ -238,9 +220,9 @@ export class NativeCodexWebSocketTransport {
         this.maxRetryDelayMs = boundedPositive(options.maxRetryDelayMs, DEFAULT_MAX_RETRY_DELAY_MS, 120_000, 'WebSocket maximum retry delay');
     }
     retryDelay(retry, error) {
-        const providerDelay = error.failure.providerRetryAfterMs;
+        const providerDelay = remainingRetryDelay(error);
         if (providerDelay !== undefined)
-            return Math.min(providerDelay, this.maxRetryDelayMs);
+            return providerDelay;
         const exponential = Math.min(this.initialRetryDelayMs * (2 ** retry), this.maxRetryDelayMs);
         const random = this.options.random?.() ?? Math.random();
         const jitter = 0.9 + Math.max(0, Math.min(1, random)) * 0.2;
@@ -249,12 +231,12 @@ export class NativeCodexWebSocketTransport {
     async wait(retry, error, signal, telemetry) {
         const delay = this.retryDelay(retry, error);
         telemetry.retry(delay);
-        await (this.options.sleep ?? sleep)(delay, signal);
+        await (this.options.sleep ?? sleepRetry)(delay, signal);
     }
     async waitForConnection(delayMs, signal, telemetry) {
         telemetry.retry(delayMs, 'connection');
         this.options.warn?.(`native Codex network is unavailable; reconnecting in ${delayMs}ms`);
-        await (this.options.sleep ?? sleep)(delayMs, signal);
+        await (this.options.sleep ?? sleepRetry)(delayMs, signal);
     }
     closeEntry(entry) {
         entry.socket?.close();
@@ -424,7 +406,8 @@ export class NativeCodexWebSocketTransport {
                 if (nextTurnState !== undefined)
                     entry.turnState = nextTurnState;
             }
-            const output = normalizedOutputItem(event);
+            const chunks = translator.push(event);
+            const output = normalizedOutputItem(event, translator);
             if (output !== undefined)
                 outputItems.push(output);
             if (event.type === 'response.completed') {
@@ -435,7 +418,6 @@ export class NativeCodexWebSocketTransport {
                 const responseId = typeof response?.id === 'string' ? response.id : '';
                 entry.protocol.complete(responseId, outputItems);
             }
-            const chunks = translator.push(event);
             if (!prewarm)
                 for (const chunk of chunks)
                     yield chunk;
@@ -616,7 +598,11 @@ export class NativeCodexWebSocketTransport {
                     }
                     if (failureValue.code === 'WS_UPGRADE_REQUIRED' || retryable) {
                         entry.disabled = true;
-                        telemetry.retry(0);
+                        if (remainingRetryDelay(failureValue) !== undefined) {
+                            await this.wait(reconnects, failureValue, signal, telemetry);
+                        }
+                        else
+                            telemetry.retry(0);
                         yield* this.http.stream(activeGeneration, fallbackMode(), telemetry);
                         requestCompleted = true;
                         return;

package/lib/replay.d.ts

@@ -2,10 +2,13 @@
 import { type ContentBlock } from '@deepseek-ai/dsh-llm';
 export declare const NATIVE_CODEX_REPLAY_KIND = "openai-codex-native.responses-replay";
 export declare const NATIVE_CODEX_REPLAY_VERSION = 1;
+export type CodexMessagePhase = 'commentary' | 'partial_answer' | 'final_answer';
+export declare function isCodexMessagePhase(value: unknown): value is CodexMessagePhase;
 export type NativeCodexReplayDescriptor = {
     type: 'message';
     id?: string;
     blocks: number[];
+    phase?: CodexMessagePhase;
 } | {
     type: 'reasoning';
     id?: string;

package/lib/replay.js

@@ -2,6 +2,9 @@
 import { LlmError } from '@deepseek-ai/dsh-llm';
 export const NATIVE_CODEX_REPLAY_KIND = 'openai-codex-native.responses-replay';
 export const NATIVE_CODEX_REPLAY_VERSION = 1;
+export function isCodexMessagePhase(value) {
+    return value === 'commentary' || value === 'partial_answer' || value === 'final_answer';
+}
 function failure(message, code = 'INVALID_REPLAY_STATE') {
     return new LlmError(message, code);
 }
@@ -55,10 +58,12 @@ function parseDescriptor(value) {
     }
     if (row.type === 'message') {
         const blocks = validateBlockArray(row.blocks);
-        if (blocks === undefined || !onlyKeys(row, ['type', 'id', 'blocks'])) {
+        if (blocks === undefined || (row.phase !== undefined && !isCodexMessagePhase(row.phase))
+            || !onlyKeys(row, ['type', 'id', 'blocks', 'phase'])) {
             throw failure('native Codex message replay descriptor is invalid');
         }
-        return { type: 'message', ...(id === undefined ? {} : { id }), blocks };
+        return { type: 'message', ...(id === undefined ? {} : { id }), blocks,
+            ...(row.phase === undefined ? {} : { phase: row.phase }) };
     }
     if (row.type === 'reasoning') {
         const blocks = validateBlockArray(row.blocks);
@@ -179,6 +184,7 @@ export function replayAssistantInput(content, source) {
             input.push({
                 type: 'message', ...(item.id === undefined ? {} : { id: item.id }),
                 role: 'assistant', content: parts,
+                ...(item.phase === undefined ? {} : { phase: item.phase }),
             });
         }
         else if (item.type === 'reasoning') {

package/lib/responses.d.ts

@@ -1,6 +1,6 @@
 import { ToolCallId, LlmError, type ContentBlock, type GenerateOptions, type StreamChunk, type TokenUsage, type ToolSchema } from '@deepseek-ai/dsh-llm';
 import { type ParseSseOptions } from './sse.js';
-import { type NativeCodexReplaySource } from './replay.js';
+import { type CodexMessagePhase, type NativeCodexReplaySource } from './replay.js';
 export declare const DEFAULT_CODEX_INSTRUCTIONS = "You are Codex, an AI coding agent. Help the user with software engineering tasks.";
 export type CodexImageDetail = 'auto' | 'low' | 'high' | 'original';
 export interface ResolvedImagePart {
@@ -9,18 +9,14 @@ export interface ResolvedImagePart {
     dataBase64: string;
     detail?: CodexImageDetail;
 }
-export interface ResolvedToolResultPart {
-    type: 'tool-result';
-    toolCallId: ToolCallId;
-    content: readonly ResolvedContentPart[];
-    isError?: boolean;
-}
 export type ResolvedContentPart = Exclude<ContentBlock, {
-    type: 'image' | 'tool-result';
-}> | ResolvedImagePart | ResolvedToolResultPart;
+    type: 'image';
+}> | ResolvedImagePart;
 export interface ResolvedMessage {
-    role: 'system' | 'user' | 'assistant';
+    role: 'system' | 'user' | 'assistant' | 'tool' | 'developer';
     content: readonly ResolvedContentPart[];
+    toolCallId?: ToolCallId;
+    isError?: boolean;
     replaySource?: NativeCodexReplaySource;
 }
 export interface ResponsesRequestInput {
@@ -57,7 +53,7 @@ export interface ResponsesUsage {
 /** Map provider totals to DSH's strict disjoint token counts. */
 export declare function mapResponsesUsage(usage: ResponsesUsage): TokenUsage;
 /** Classify in-band failure data without reflecting provider text. */
-export declare function responsesFailure(code?: string, message?: string): LlmError;
+export declare function responsesFailure(code?: string, message?: string, headers?: unknown): LlmError;
 interface ResponsesOutputItem {
     type?: string;
     id?: string;
@@ -68,6 +64,7 @@ interface ResponsesOutputItem {
     encrypted_content?: string;
     summary?: unknown[];
     status?: string;
+    phase?: CodexMessagePhase | null;
     content?: Array<{
         type?: string;
         text?: string;
@@ -90,6 +87,7 @@ export interface ResponsesStreamEvent {
         error?: {
             code?: string;
             message?: string;
+            headers?: unknown;
         };
         incomplete_details?: {
             reason?: string;
@@ -107,11 +105,15 @@ export declare class ResponsesStreamTranslator {
     private readonly replayContext?;
     private readonly blocks;
     private readonly order;
+    private readonly messagePhases;
     private readonly replayCapture;
     private nextIndex;
     private sawToolCall;
     terminated: boolean;
     constructor(replayContext?: ResponsesReplayContext | undefined);
+    /** The same effective phase feeds durable replay and WebSocket prefix comparison. */
+    messagePhase(id: string): CodexMessagePhase | undefined;
+    private captureMessagePhase;
     private append;
     private fill;
     private open;

package/lib/responses.js

@@ -2,7 +2,8 @@
 import { createHash } from 'node:crypto';
 import { ToolCallId, CONTEXT_WINDOW_EXCEEDED_CODE, EMPTY_RESPONSE_CODE, isContextWindowExceededError, isQuotaExceededError, LlmError, QUOTA_EXCEEDED_CODE, } from '@deepseek-ai/dsh-llm';
 import { parseSse } from './sse.js';
-import { NativeCodexReplayCapture, replayAssistantInput, replayableItemId, } from './replay.js';
+import { jsonRetryAfterMs, retryError } from './retry-after.js';
+import { NativeCodexReplayCapture, isCodexMessagePhase, replayAssistantInput, replayableItemId, } from './replay.js';
 export const DEFAULT_CODEX_INSTRUCTIONS = 'You are Codex, an AI coding agent. Help the user with software engineering tasks.';
 const CALL_ID_MAX_LENGTH = 64;
 const CALL_ID_PREFIX = 'call_';
@@ -26,12 +27,12 @@ function imageItem(image) {
     return { type: 'input_image', image_url: `data:${image.mediaType};base64,${image.dataBase64}`,
         ...image.detail === undefined ? {} : { detail: image.detail } };
 }
-function toolOutput(block) {
-    const images = block.content.some(part => part.type === 'image');
+function toolOutput(content) {
+    const images = content.some(part => part.type === 'image');
     if (!images) {
-        return block.content.map(part => part.type === 'text' ? part.text : '').join('');
+        return content.map(part => part.type === 'text' ? part.text : '').join('');
     }
-    return block.content.map((part) => {
+    return content.map((part) => {
         if (part.type === 'text')
             return { type: 'input_text', text: part.text };
         if (part.type === 'image' && 'dataBase64' in part)
@@ -67,6 +68,29 @@ export function toResponsesInput(messages, system) {
             input.push({ type: 'message', role: message.role, content });
             content = [];
         };
+        // Handle tool messages separately - they have no content blocks, just top-level fields
+        if (message.role === 'tool') {
+            if (message.toolCallId === undefined) {
+                throw fixedError('native Codex tool message requires toolCallId', 'INVALID_ARGS');
+            }
+            input.push({
+                type: 'function_call_output',
+                call_id: String(message.toolCallId),
+                output: toolOutput(message.content),
+                ...message.isError === true ? { is_error: true } : {},
+            });
+            continue;
+        }
+        // Handle developer messages - map to developer role in Responses API
+        if (message.role === 'developer') {
+            for (const block of message.content) {
+                if (block.type === 'text') {
+                    content.push({ type: 'input_text', text: block.text });
+                }
+            }
+            flush();
+            continue;
+        }
         for (const block of message.content) {
             if (message.role === 'system') {
                 if (block.type === 'text')
@@ -89,18 +113,15 @@ export function toResponsesInput(messages, system) {
                     content.push(imageItem(block));
                     break;
                 case 'tool-call':
+                    if (message.role !== 'assistant') {
+                        throw fixedError('native Codex tool calls require assistant messages', 'INVALID_ARGS');
+                    }
                     flush();
                     input.push({
                         type: 'function_call', call_id: String(block.id),
                         name: block.name, arguments: block.arguments,
                     });
                     break;
-                case 'tool-result':
-                    flush();
-                    input.push({
-                        type: 'function_call_output', call_id: String(block.toolCallId), output: toolOutput(block),
-                    });
-                    break;
                 case 'reasoning':
                     break; // Visible reasoning is never replayed; M4 may add encrypted items.
                 default:
@@ -191,11 +212,21 @@ export function codexRequestBody(options, messages, mode = {}) {
         ...mode.serviceTier === undefined ? {} : { service_tier: mode.serviceTier },
         ...options.sessionId === undefined ? {} : { prompt_cache_key: String(options.sessionId) },
     };
+    const baseInstructions = mode.responsesLite?.instructionsTemplate ?? instructions;
+    const prefixNamespace = uuidBytes(uuidV5(UUID_NAMESPACE_OID, String(options.sessionId ?? options.model)));
+    const instructionPrefix = baseInstructions.length === 0 ? [] : [{
+            type: 'message',
+            id: `msg_${uuidV5(prefixNamespace, baseInstructions)}`,
+            role: 'developer',
+            content: [{ type: 'input_text', text: baseInstructions }],
+            internal_chat_message_metadata_passthrough: {
+                content_item_kinds: ['model.base_instructions'],
+            },
+        }];
     if (mode.responsesLite === undefined) {
         return {
             ...common,
-            instructions,
-            input,
+            input: [...instructionPrefix, ...input],
             ...options.tools !== undefined && options.tools.length > 0
                 ? { tools: toResponsesTools(options.tools) } : {},
             parallel_tool_calls: true,
@@ -204,7 +235,6 @@ export function codexRequestBody(options, messages, mode = {}) {
         };
     }
     const tools = toResponsesLiteTools(options.tools ?? []);
-    const baseInstructions = mode.responsesLite.instructionsTemplate ?? instructions;
     const contextualInstructions = mode.responsesLite.instructionsTemplate !== undefined
         && resolved.instructions !== undefined && resolved.instructions !== baseInstructions
         ? [{
@@ -212,21 +242,12 @@ export function codexRequestBody(options, messages, mode = {}) {
                 content: [{ type: 'input_text', text: resolved.instructions }],
             }]
         : [];
-    const prefixNamespace = uuidBytes(uuidV5(UUID_NAMESPACE_OID, String(options.sessionId ?? options.model)));
     const prefix = [{
             type: 'additional_tools',
             id: `at_${uuidV5(prefixNamespace, JSON.stringify(tools))}`,
             role: 'developer',
             tools,
-        }, {
-            type: 'message',
-            id: `msg_${uuidV5(prefixNamespace, baseInstructions)}`,
-            role: 'developer',
-            content: [{ type: 'input_text', text: baseInstructions }],
-            internal_chat_message_metadata_passthrough: {
-                content_item_kinds: ['model.base_instructions'],
-            },
-        }];
+        }, ...instructionPrefix];
     return {
         ...common,
         input: [...prefix, ...contextualInstructions, ...input],
@@ -273,10 +294,11 @@ function retryDelay(message) {
     const value = Number(match[1]);
     if (!Number.isFinite(value) || value <= 0)
         return undefined;
-    return Math.min(match[2]?.toLowerCase() === 'ms' ? value : value * 1000, 600_000);
+    const delay = match[2]?.toLowerCase() === 'ms' ? value : value * 1000;
+    return Number.isFinite(delay) && delay <= Number.MAX_SAFE_INTEGER ? delay : undefined;
 }
 /** Classify in-band failure data without reflecting provider text. */
-export function responsesFailure(code, message) {
+export function responsesFailure(code, message, headers) {
     const detail = `${code ?? ''} ${message ?? ''}`;
     if (code === 'context_length_exceeded' || code === 'context_window_exceeded'
         || isContextWindowExceededError(detail)) {
@@ -288,8 +310,8 @@ export function responsesFailure(code, message) {
         return fixedError('native Codex account quota is exhausted', QUOTA_EXCEEDED_CODE);
     }
     if (code === 'rate_limit_exceeded' || code === 'slow_down') {
-        const delay = retryDelay(message);
-        return new LlmError('native Codex request was rate limited', 'RATE_LIMIT', {
+        const delay = jsonRetryAfterMs(headers) ?? retryDelay(message);
+        return retryError('native Codex request was rate limited', 'RATE_LIMIT', {
             ...delay === undefined ? {} : { providerRetryAfterMs: delay },
         });
     }
@@ -299,7 +321,10 @@ export function responsesFailure(code, message) {
     if (code === 'bio_policy') {
         return fixedError('native Codex rejected the request', 'INVALID_REQUEST');
     }
-    return fixedError('native Codex reported a failed response', 'SERVER');
+    const delay = jsonRetryAfterMs(headers);
+    return retryError('native Codex reported a failed response', 'SERVER', {
+        ...delay === undefined ? {} : { providerRetryAfterMs: delay },
+    });
 }
 function eventItemId(event) {
     if (typeof event.item_id === 'string' && event.item_id.length > 0)
@@ -323,6 +348,7 @@ export class ResponsesStreamTranslator {
     replayContext;
     blocks = new Map();
     order = [];
+    messagePhases = new Map();
     replayCapture;
     nextIndex = 0;
     sawToolCall = false;
@@ -333,6 +359,18 @@ export class ResponsesStreamTranslator {
             ? undefined
             : new NativeCodexReplayCapture(replayContext.provider, replayContext.model);
     }
+    /** The same effective phase feeds durable replay and WebSocket prefix comparison. */
+    messagePhase(id) {
+        return this.messagePhases.get(id);
+    }
+    captureMessagePhase(item) {
+        if (item.phase === undefined || item.phase === null)
+            return;
+        if (!isCodexMessagePhase(item.phase) || typeof item.id !== 'string' || item.id.length === 0) {
+            throw fixedError('native Codex message phase is invalid', 'MALFORMED_RESPONSE');
+        }
+        this.messagePhases.set(item.id, item.phase);
+    }
     append(block, delta) {
         block.text += delta;
     }
@@ -380,6 +418,8 @@ export class ResponsesStreamTranslator {
         switch (event.type) {
             case 'response.output_item.added': {
                 const item = event.item;
+                if (item?.type === 'message')
+                    this.captureMessagePhase(item);
                 if (item?.type !== 'function_call')
                     return chunks;
                 if (item.id === undefined || item.id.length === 0
@@ -463,6 +503,8 @@ export class ResponsesStreamTranslator {
                         });
                 }
                 else if (item.type === 'message') {
+                    this.captureMessagePhase(item);
+                    const phase = this.messagePhase(item.id);
                     if (!Array.isArray(item.content)) {
                         throw fixedError('native Codex message item has invalid content', 'MALFORMED_RESPONSE');
                     }
@@ -487,6 +529,7 @@ export class ResponsesStreamTranslator {
                     if (this.replayContext !== undefined)
                         this.replayCapture?.add({
                             type: 'message', ...(replayId === undefined ? {} : { id: replayId }), blocks: refs,
+                            ...(phase === undefined ? {} : { phase }),
                         });
                 }
                 else if (item.type === 'reasoning') {
@@ -575,7 +618,7 @@ export class ResponsesStreamTranslator {
                 return chunks;
             }
             case 'response.failed':
-                throw responsesFailure(event.response?.error?.code, event.response?.error?.message);
+                throw responsesFailure(event.response?.error?.code, event.response?.error?.message, event.response?.error?.headers);
             case 'error':
                 throw responsesFailure(event.code, event.message);
             default:

package/lib/retry-after.d.ts

@@ -0,0 +1,9 @@
+/** Server advice is separate from the client's bounded exponential backoff. */
+import { LlmError } from '@deepseek-ai/dsh-llm';
+export declare function retryAfterMs(raw: unknown): number | undefined;
+export declare function jsonRetryAfterMs(headers: unknown): number | undefined;
+export declare function retryError(message: string, code: string, options?: ConstructorParameters<typeof LlmError>[2]): LlmError;
+export declare function inheritRetryDeadline(error: LlmError, source: LlmError): LlmError;
+export declare function remainingRetryDelay(error: LlmError): number | undefined;
+/** Node timers overflow above 2^31-1; chunk long waits without shortening advice. */
+export declare function sleepRetry(delay: number, signal?: AbortSignal): Promise<void>;

package/lib/retry-after.js

@@ -0,0 +1,109 @@
+/** Server advice is separate from the client's bounded exponential backoff. */
+import { LlmError } from '@deepseek-ai/dsh-llm';
+const deadlines = new WeakMap();
+function httpDate(value) {
+    const standard = /^([A-Za-z]{3}), ([0-9]{2}) ([A-Za-z]{3}) ([0-9]{4}) ([0-9]{2}:[0-9]{2}:[0-9]{2}) GMT$/.exec(value);
+    const obsolete = /^([A-Za-z]+), ([0-9]{2})-([A-Za-z]{3})-([0-9]{2}) ([0-9]{2}:[0-9]{2}:[0-9]{2}) GMT$/.exec(value);
+    const ascii = /^([A-Za-z]{3}) ([A-Za-z]{3}) ([ 0-9][0-9]) ([0-9]{2}:[0-9]{2}:[0-9]{2}) ([0-9]{4})$/.exec(value);
+    const parts = standard ?? obsolete;
+    const weekday = parts?.[1] ?? ascii?.[1];
+    const day = parts?.[2] ?? ascii?.[3];
+    const month = parts?.[3] ?? ascii?.[2];
+    const year = parts?.[4] ?? ascii?.[5];
+    const time = parts?.[5] ?? ascii?.[4];
+    if (!weekday || !day || !month || !year || !time)
+        return undefined;
+    const timestamp = Date.parse(value.endsWith('GMT') ? value : value + ' GMT');
+    if (!Number.isFinite(timestamp))
+        return undefined;
+    const date = new Date(timestamp);
+    const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+    const weekdays = obsolete
+        ? ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']
+        : ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+    // Date.parse normalizes impossible dates; HTTP header parsing must reject them.
+    if (date.getUTCDate() !== Number(day) || months[date.getUTCMonth()] !== month
+        || weekdays[date.getUTCDay()] !== weekday
+        || (obsolete ? date.getUTCFullYear() % 100 : date.getUTCFullYear()) !== Number(year)
+        || date.toISOString().slice(11, 19) !== time)
+        return undefined;
+    return timestamp;
+}
+export function retryAfterMs(raw) {
+    if (typeof raw !== 'string' && typeof raw !== 'number')
+        return undefined;
+    const text = String(raw);
+    if (/[^\t\x20-\x7e]/.test(text))
+        return undefined;
+    const value = text.trim();
+    let delay;
+    if (/^\d+$/.test(value))
+        delay = Number(value) * 1000;
+    else {
+        const timestamp = httpDate(value);
+        if (timestamp === undefined)
+            return undefined;
+        delay = Math.max(0, timestamp - Date.now());
+    }
+    return Number.isSafeInteger(delay) && delay >= 0 ? delay : undefined;
+}
+export function jsonRetryAfterMs(headers) {
+    if (typeof headers !== 'object' || headers === null || Array.isArray(headers))
+        return undefined;
+    let value;
+    // serde_json's ordered map inserts later case variants over earlier ones.
+    for (const key of Object.keys(headers).sort()) {
+        const raw = headers[key];
+        if (key.toLowerCase() === 'retry-after'
+            && (typeof raw === 'string' || typeof raw === 'number' || typeof raw === 'boolean')
+            && !/[^\t\x20-\x7e]/.test(String(raw)))
+            value = raw;
+    }
+    return retryAfterMs(value);
+}
+export function retryError(message, code, options) {
+    const delay = options?.providerRetryAfterMs;
+    // The host permits only positive duration metadata; retain zero advice locally.
+    const normalized = { ...options };
+    if (delay === 0)
+        delete normalized.providerRetryAfterMs;
+    const error = new LlmError(message, code, normalized);
+    const inherited = options?.cause instanceof LlmError ? deadlines.get(options.cause) : undefined;
+    if (inherited !== undefined || delay !== undefined) {
+        deadlines.set(error, inherited ?? performance.now() + delay);
+    }
+    return error;
+}
+export function inheritRetryDeadline(error, source) {
+    const deadline = deadlines.get(source);
+    if (deadline !== undefined)
+        deadlines.set(error, deadline);
+    return error;
+}
+export function remainingRetryDelay(error) {
+    let deadline = deadlines.get(error);
+    if (deadline === undefined) {
+        const delay = error.failure.providerRetryAfterMs;
+        if (delay === undefined)
+            return undefined;
+        deadline = performance.now() + delay;
+        deadlines.set(error, deadline);
+    }
+    return Math.max(0, Math.ceil(deadline - performance.now()));
+}
+/** Node timers overflow above 2^31-1; chunk long waits without shortening advice. */
+export async function sleepRetry(delay, signal) {
+    const deadline = performance.now() + delay;
+    do {
+        if (signal?.aborted)
+            throw signal.reason instanceof LlmError ? signal.reason : new LlmError('native Codex retry wait was aborted', 'ABORTED');
+        const remaining = Math.max(0, Math.ceil(deadline - performance.now()));
+        if (remaining === 0)
+            return;
+        await new Promise((resolve, reject) => {
+            const abort = () => { clearTimeout(timer); reject(signal?.reason instanceof LlmError ? signal.reason : new LlmError('native Codex retry wait was aborted', 'ABORTED')); };
+            const timer = setTimeout(() => { signal?.removeEventListener('abort', abort); resolve(); }, Math.min(remaining, 2_147_483_647));
+            signal?.addEventListener('abort', abort, { once: true });
+        });
+    } while (true);
+}