@proteinjs/conversation 2.6.0 → 2.7.0

package/src/OpenAiResponses.ts

@@ -6,11 +6,23 @@ import type { Function } from './Function';
 import { UsageData, UsageDataAccumulator } from './UsageData';
 import { ChatCompletionMessageParamFactory } from './ChatCompletionMessageParamFactory';
 import type { GenerateResponseReturn, ToolInvocationProgressEvent, ToolInvocationResult } from './OpenAi';
-import { DEFAULT_MODEL } from './OpenAi';
+import { TiktokenModel } from 'tiktoken';
 
-export const DEFAULT_RESPONSES_MODEL = 'gpt-5.2';
+export const DEFAULT_RESPONSES_MODEL = 'gpt-5.2' as TiktokenModel;
 export const DEFAULT_MAX_TOOL_CALLS = 50;
 
+/** Default hard cap for background-mode polling duration (ms): 1 hour. */
+export const DEFAULT_MAX_BACKGROUND_WAIT_MS = 60 * 60 * 1000;
+
+/** Best-effort timeout for cancel calls (avoid hanging abort/timeout paths). */
+const DEFAULT_CANCEL_TIMEOUT_MS = 10_000;
+
+/**
+ * Responses API service tier.
+ * See: Responses API `service_tier` request param and response field.
+ */
+export type OpenAiServiceTier = 'auto' | 'default' | 'flex' | 'priority' | (string & {});
+
 export type OpenAiResponsesParams = {
   modules?: ConversationModule[];
   /** If provided, only these functions will be exposed to the model. */
@@ -18,18 +30,24 @@ export type OpenAiResponsesParams = {
   logLevel?: LogLevel;
 
   /** Default model when none is provided per call. */
-  defaultModel?: string;
+  defaultModel?: TiktokenModel;
 
   /** Default cap for tool calls (per call). */
   maxToolCalls?: number;
+
+  /** Default hard cap for background-mode polling duration (ms). Default: 1 hour. */
+  maxBackgroundWaitMs?: number;
 };
 
 export type GenerateTextParams = {
   messages: (string | ChatCompletionMessageParam)[];
-  model?: string;
+  model?: TiktokenModel;
 
   abortSignal?: AbortSignal;
 
+  /** Hard cap for background-mode polling duration (ms). Default: 1 hour. */
+  maxBackgroundWaitMs?: number;
+
   /** Sampling & limits */
   temperature?: number;
   topP?: number;
@@ -49,14 +67,20 @@ export type GenerateTextParams = {
 
   /** If true, run using Responses API background mode (polling). */
   backgroundMode?: boolean;
+
+  /** Optional Responses API service tier override (per-request). */
+  serviceTier?: OpenAiServiceTier;
 };
 
 export type ResponsesGenerateObjectParams<S> = {
   messages: (string | ChatCompletionMessageParam)[];
-  model?: string;
+  model?: TiktokenModel;
 
   abortSignal?: AbortSignal;
 
+  /** Hard cap for background-mode polling duration (ms). Default: 1 hour. */
+  maxBackgroundWaitMs?: number;
+
   /** Zod schema or JSON Schema */
   schema: S;
 
@@ -79,6 +103,9 @@ export type ResponsesGenerateObjectParams<S> = {
 
   /** If true, run using Responses API background mode (polling). */
   backgroundMode?: boolean;
+
+  /** Optional Responses API service tier override (per-request). */
+  serviceTier?: OpenAiServiceTier;
 };
 
 /**
@@ -96,8 +123,9 @@ export class OpenAiResponses {
 
   private readonly modules: ConversationModule[];
   private readonly allowedFunctionNames?: string[];
-  private readonly defaultModel: string;
+  private readonly defaultModel: TiktokenModel;
   private readonly defaultMaxToolCalls: number;
+  private readonly defaultMaxBackgroundWaitMs: number;
 
   private modulesProcessed = false;
   private processingModulesPromise: Promise<void> | null = null;
@@ -112,8 +140,15 @@ export class OpenAiResponses {
     this.modules = opts.modules ?? [];
     this.allowedFunctionNames = opts.allowedFunctionNames;
 
-    this.defaultModel = (opts.defaultModel ?? DEFAULT_RESPONSES_MODEL).trim();
+    this.defaultModel = opts.defaultModel ?? DEFAULT_RESPONSES_MODEL;
     this.defaultMaxToolCalls = typeof opts.maxToolCalls === 'number' ? opts.maxToolCalls : DEFAULT_MAX_TOOL_CALLS;
+
+    this.defaultMaxBackgroundWaitMs =
+      typeof opts.maxBackgroundWaitMs === 'number' &&
+      Number.isFinite(opts.maxBackgroundWaitMs) &&
+      opts.maxBackgroundWaitMs > 0
+        ? Math.floor(opts.maxBackgroundWaitMs)
+        : DEFAULT_MAX_BACKGROUND_WAIT_MS;
   }
 
   /** Plain text generation (supports tool calling). */
@@ -128,6 +163,7 @@ export class OpenAiResponses {
     });
 
     const maxToolCalls = typeof args.maxToolCalls === 'number' ? args.maxToolCalls : this.defaultMaxToolCalls;
+    const maxBackgroundWaitMs = this.resolveMaxBackgroundWaitMs(args.maxBackgroundWaitMs);
 
     const result = await this.run({
       model,
@@ -140,7 +176,9 @@ export class OpenAiResponses {
       reasoningEffort: args.reasoningEffort,
       maxToolCalls,
       backgroundMode,
+      maxBackgroundWaitMs,
       textFormat: undefined,
+      serviceTier: args.serviceTier,
     });
 
     if (args.onUsageData) {
@@ -167,6 +205,7 @@ export class OpenAiResponses {
     });
 
     const maxToolCalls = typeof args.maxToolCalls === 'number' ? args.maxToolCalls : this.defaultMaxToolCalls;
+    const maxBackgroundWaitMs = this.resolveMaxBackgroundWaitMs(args.maxBackgroundWaitMs);
     const textFormat = this.buildTextFormat(args.schema);
 
     const result = await this.run({
@@ -180,10 +219,17 @@ export class OpenAiResponses {
       reasoningEffort: args.reasoningEffort,
       maxToolCalls,
       backgroundMode,
+      maxBackgroundWaitMs,
       textFormat,
+      serviceTier: args.serviceTier,
     });
 
-    const object = this.parseAndValidateStructuredOutput<T>(result.message, args.schema);
+    const object = this.parseAndValidateStructuredOutput<T>(result.message, args.schema, {
+      model,
+      maxOutputTokens: args.maxTokens,
+      requestedServiceTier: args.serviceTier,
+      serviceTier: result.serviceTier,
+    });
 
     const outcome = {
       object,
@@ -202,7 +248,7 @@ export class OpenAiResponses {
   // -----------------------------------------
 
   private async run(args: {
-    model: string;
+    model: TiktokenModel;
     messages: (string | ChatCompletionMessageParam)[];
 
     temperature?: number;
@@ -216,12 +262,15 @@ export class OpenAiResponses {
 
     maxToolCalls: number;
     backgroundMode: boolean;
+    maxBackgroundWaitMs: number;
 
     textFormat?: unknown;
-  }): Promise<GenerateResponseReturn> {
+
+    serviceTier?: OpenAiServiceTier;
+  }): Promise<GenerateResponseReturn & { serviceTier?: OpenAiServiceTier }> {
     // UsageDataAccumulator is typed around TiktokenModel; keep accumulator model stable,
     // and (optionally) report the actual model via upstream telemetry if you later choose to.
-    const usage = new UsageDataAccumulator({ model: DEFAULT_MODEL });
+    const usage = new UsageDataAccumulator({ model: args.model });
     const toolInvocations: ToolInvocationResult[] = [];
 
     const tools = this.buildResponseTools(this.functions);
@@ -235,7 +284,8 @@ export class OpenAiResponses {
     for (;;) {
       const response = await this.createResponseAndMaybeWait({
         model: args.model,
-        instructions: previousResponseId ? undefined : instructions,
+        // Always pass instructions; they are not carried over with previous_response_id.
+        instructions,
         input: nextInput,
         previousResponseId,
         tools,
@@ -245,10 +295,22 @@ export class OpenAiResponses {
         reasoningEffort: args.reasoningEffort,
         textFormat: args.textFormat,
         backgroundMode: args.backgroundMode,
+        maxBackgroundWaitMs: args.maxBackgroundWaitMs,
         abortSignal: args.abortSignal,
+        serviceTier: args.serviceTier,
       });
 
-      this.addUsageFromResponse(response, usage);
+      this.addUsageFromResponse(response, usage, { requestedServiceTier: args.serviceTier });
+
+      // For structured outputs we should not attempt to parse incomplete/failed/cancelled responses.
+      // For plain-text generation, we allow "incomplete" to pass through (partial output),
+      // but still fail on other non-completed statuses.
+      this.throwIfResponseUnusable(response as any, {
+        allowIncomplete: !args.textFormat,
+        model: args.model,
+        maxOutputTokens: args.maxTokens,
+        requestedServiceTier: args.serviceTier,
+      });
 
       const functionCalls = this.extractFunctionCalls(response);
       if (functionCalls.length < 1) {
@@ -256,7 +318,12 @@ export class OpenAiResponses {
         if (!message) {
           throw new Error(`Response was empty`);
         }
-        return { message, usagedata: usage.usageData, toolInvocations };
+        return {
+          message,
+          usagedata: usage.usageData,
+          toolInvocations,
+          serviceTier: response.service_tier ? response.service_tier : undefined,
+        };
       }
 
       if (toolCallsExecuted + functionCalls.length > args.maxToolCalls) {
@@ -287,6 +354,263 @@ export class OpenAiResponses {
     }
   }
 
+  private throwIfResponseUnusable(
+    response: any,
+    opts: {
+      allowIncomplete: boolean;
+      model?: string;
+      maxOutputTokens?: number;
+      requestedServiceTier?: OpenAiServiceTier;
+    }
+  ): void {
+    const statusRaw = typeof response?.status === 'string' ? String(response.status) : '';
+    const status = statusRaw.toLowerCase();
+
+    if (!status || status === 'completed') {
+      return;
+    }
+
+    if (status === 'incomplete' && opts.allowIncomplete) {
+      return;
+    }
+
+    const id = typeof response?.id === 'string' ? response.id : '';
+    const reason = response?.incomplete_details?.reason;
+    const apiErr = response?.error;
+
+    const serviceTier =
+      typeof response?.service_tier === 'string' && response.service_tier.trim() ? response.service_tier.trim() : '';
+
+    const directOutputText = typeof response?.output_text === 'string' ? response.output_text : '';
+    const assistantText = this.extractAssistantText(response as any);
+
+    const outTextLen = directOutputText ? directOutputText.length : 0;
+    const assistantLen = assistantText ? assistantText.length : 0;
+
+    const usage = response?.usage;
+    const inputTokens = typeof usage?.input_tokens === 'number' ? usage.input_tokens : undefined;
+    const outputTokens = typeof usage?.output_tokens === 'number' ? usage.output_tokens : undefined;
+    const totalTokens =
+      typeof usage?.total_tokens === 'number'
+        ? usage.total_tokens
+        : typeof inputTokens === 'number' && typeof outputTokens === 'number'
+          ? inputTokens + outputTokens
+          : undefined;
+
+    let msg = `Responses API returned status="${status}"`;
+    if (id) {
+      msg += ` (id=${id})`;
+    }
+    msg += `.`;
+
+    const details: Record<string, unknown> = {
+      response_id: id || undefined,
+      status,
+      model: typeof opts.model === 'string' && opts.model.trim() ? opts.model : undefined,
+      max_output_tokens: typeof opts.maxOutputTokens === 'number' ? opts.maxOutputTokens : undefined,
+
+      requested_service_tier:
+        typeof opts.requestedServiceTier === 'string' && opts.requestedServiceTier.trim()
+          ? opts.requestedServiceTier.trim()
+          : undefined,
+      service_tier: serviceTier || undefined,
+
+      incomplete_reason: typeof reason === 'string' && reason.trim() ? reason : undefined,
+      api_error: apiErr ?? undefined,
+
+      usage_input_tokens: inputTokens,
+      usage_output_tokens: outputTokens,
+      usage_total_tokens: totalTokens,
+
+      output_text_len: outTextLen || undefined,
+      output_text_tail: outTextLen > 0 ? truncateTail(directOutputText, 400) : undefined,
+
+      assistant_text_len: assistantLen || undefined,
+      assistant_text_tail: assistantLen > 0 ? truncateTail(assistantText, 400) : undefined,
+    };
+
+    const extra: string[] = [];
+    if (details.model) {
+      extra.push(`model=${details.model}`);
+    }
+    if (typeof details.max_output_tokens === 'number') {
+      extra.push(`max_output_tokens=${details.max_output_tokens}`);
+    }
+    if (typeof details.requested_service_tier === 'string') {
+      extra.push(`requested_service_tier=${details.requested_service_tier}`);
+    }
+    if (typeof details.service_tier === 'string') {
+      extra.push(`service_tier=${details.service_tier}`);
+    }
+    if (details.incomplete_reason) {
+      extra.push(`reason=${details.incomplete_reason}`);
+    }
+    if (typeof details.output_text_len === 'number') {
+      extra.push(`output_text_len=${details.output_text_len}`);
+    }
+    if (typeof details.assistant_text_len === 'number') {
+      extra.push(`assistant_text_len=${details.assistant_text_len}`);
+    }
+
+    if (extra.length > 0) {
+      msg += ` ${extra.join(' ')}.`;
+    }
+
+    throw new OpenAiResponsesError({
+      code: 'RESPONSE_STATUS',
+      message: msg,
+      details,
+    });
+  }
+
+  private toOpenAiApiError(
+    error: unknown,
+    meta: {
+      operation: 'responses.create' | 'responses.retrieve' | 'responses.cancel';
+      model?: string;
+      reasoningEffort?: OpenAIApi.Chat.Completions.ChatCompletionReasoningEffort;
+      backgroundMode?: boolean;
+      responseId?: string;
+      previousResponseId?: string;
+      pollAttempt?: number;
+      aborted?: boolean;
+      waitedMs?: number;
+      maxWaitMs?: number;
+      lastStatus?: string;
+      requestedServiceTier?: OpenAiServiceTier;
+      serviceTier?: string;
+    }
+  ): OpenAiResponsesError {
+    const status = extractHttpStatus(error);
+    const requestId = extractRequestId(error);
+    const retryable = isRetryableHttpStatus(status);
+
+    const errMsg = error instanceof Error ? error.message : String(error ?? '');
+    const errName = error instanceof Error ? error.name : undefined;
+
+    const aborted = meta.aborted === true || isAbortError(error);
+
+    let msg = `OpenAI ${meta.operation} failed.`;
+    const extra: string[] = [];
+
+    if (aborted) {
+      extra.push(`aborted=true`);
+    }
+    if (typeof status === 'number') {
+      extra.push(`status=${status}`);
+    }
+    if (requestId) {
+      extra.push(`requestId=${requestId}`);
+    }
+    if (meta.responseId) {
+      extra.push(`responseId=${meta.responseId}`);
+    }
+    if (meta.backgroundMode) {
+      extra.push(`background=true`);
+    }
+    if (typeof meta.pollAttempt === 'number') {
+      extra.push(`pollAttempt=${meta.pollAttempt}`);
+    }
+    if (typeof meta.waitedMs === 'number') {
+      extra.push(`waitedMs=${meta.waitedMs}`);
+    }
+    if (typeof meta.maxWaitMs === 'number') {
+      extra.push(`maxWaitMs=${meta.maxWaitMs}`);
+    }
+    if (typeof meta.lastStatus === 'string' && meta.lastStatus.trim()) {
+      extra.push(`lastStatus=${meta.lastStatus.trim()}`);
+    }
+    if (typeof meta.model === 'string' && meta.model.trim()) {
+      extra.push(`model=${meta.model.trim()}`);
+    }
+    if (meta.reasoningEffort) {
+      extra.push(`reasoningEffort=${meta.reasoningEffort}`);
+    }
+    if (typeof meta.requestedServiceTier === 'string' && meta.requestedServiceTier.trim()) {
+      extra.push(`requested_service_tier=${meta.requestedServiceTier.trim()}`);
+    }
+    if (typeof meta.serviceTier === 'string' && meta.serviceTier.trim()) {
+      extra.push(`service_tier=${meta.serviceTier.trim()}`);
+    }
+
+    if (extra.length > 0) {
+      msg += ` ${extra.join(' ')}.`;
+    }
+    if (errMsg) {
+      msg += ` error=${JSON.stringify(errMsg)}.`;
+    }
+
+    const details: Record<string, unknown> = {
+      operation: meta.operation,
+      status: typeof status === 'number' ? status : undefined,
+      request_id: requestId,
+      response_id: meta.responseId,
+      previous_response_id: meta.previousResponseId,
+      background: meta.backgroundMode ? true : undefined,
+      poll_attempt: meta.pollAttempt,
+      waited_ms: meta.waitedMs,
+      max_wait_ms: meta.maxWaitMs,
+      last_status: typeof meta.lastStatus === 'string' && meta.lastStatus.trim() ? meta.lastStatus.trim() : undefined,
+      model: typeof meta.model === 'string' && meta.model.trim() ? meta.model.trim() : undefined,
+      reasoning_effort: meta.reasoningEffort,
+      requested_service_tier:
+        typeof meta.requestedServiceTier === 'string' && meta.requestedServiceTier.trim()
+          ? meta.requestedServiceTier.trim()
+          : undefined,
+      service_tier:
+        typeof meta.serviceTier === 'string' && meta.serviceTier.trim() ? meta.serviceTier.trim() : undefined,
+      error_name: errName,
+      aborted: aborted ? true : undefined,
+    };
+
+    return new OpenAiResponsesError({
+      code: 'OPENAI_API',
+      message: msg,
+      details,
+      cause: error,
+      retryable,
+    });
+  }
+
+  private resolveMaxBackgroundWaitMs(ms?: number): number {
+    const n =
+      typeof ms === 'number' && Number.isFinite(ms) && ms > 0 ? Math.floor(ms) : this.defaultMaxBackgroundWaitMs;
+    // Ensure we never return a non-positive number even if misconfigured elsewhere.
+    return n > 0 ? n : DEFAULT_MAX_BACKGROUND_WAIT_MS;
+  }
+
+  private async cancelResponseBestEffort(
+    responseId: string
+  ): Promise<
+    | { attempted: false }
+    | { attempted: true; ok: true }
+    | { attempted: true; ok: false; error?: Record<string, unknown> }
+  > {
+    if (!responseId) {
+      return { attempted: false };
+    }
+
+    try {
+      const resp = await this.client.responses.cancel(responseId);
+
+      // Docs show cancelled as the post-cancel status.
+      if (resp?.status === 'cancelled') {
+        return { attempted: true, ok: true };
+      }
+
+      return {
+        attempted: true,
+        ok: false,
+        error: {
+          message: 'Cancel did not return status=cancelled',
+          status: resp?.status,
+        },
+      };
+    } catch (e: unknown) {
+      return { attempted: true, ok: false, error: safeErrorSummary(e) };
+    }
+  }
+
   private async createResponseAndMaybeWait(args: {
     model: string;
     instructions?: string;
@@ -302,14 +626,11 @@ export class OpenAiResponses {
     textFormat?: unknown;
 
     backgroundMode: boolean;
+    maxBackgroundWaitMs: number;
     abortSignal?: AbortSignal;
-  }): Promise<{
-    id?: string;
-    status?: string;
-    output_text?: string;
-    output?: unknown[];
-    usage?: unknown;
-  }> {
+
+    serviceTier?: OpenAiServiceTier;
+  }): Promise<OpenAIApi.Responses.Response> {
     const body: Record<string, unknown> = {
       model: args.model,
       input: args.input,
@@ -343,77 +664,197 @@ export class OpenAiResponses {
       body.text = { format: args.textFormat };
     }
 
+    if (typeof args.serviceTier === 'string' && args.serviceTier.trim()) {
+      body.service_tier = args.serviceTier.trim();
+    }
+
     if (args.backgroundMode) {
       body.background = true;
       body.store = true;
     }
 
-    const created = await this.client.responses.create(
-      body as never,
-      args.abortSignal ? { signal: args.abortSignal } : undefined
-    );
+    let created: OpenAIApi.Responses.Response;
+    try {
+      created = await this.client.responses.create(
+        body as never,
+        args.abortSignal ? { signal: args.abortSignal } : undefined
+      );
+    } catch (error: unknown) {
+      throw this.toOpenAiApiError(error, {
+        operation: 'responses.create',
+        model: args.model,
+        reasoningEffort: args.reasoningEffort,
+        backgroundMode: args.backgroundMode,
+        previousResponseId: args.previousResponseId,
+        aborted: args.abortSignal?.aborted ? true : undefined,
+        requestedServiceTier: args.serviceTier,
+      });
+    }
 
     if (!args.backgroundMode) {
-      return created as unknown as {
-        id?: string;
-        status?: string;
-        output_text?: string;
-        output?: unknown[];
-        usage?: unknown;
-      };
+      return created;
     }
 
     if (!created?.id) {
-      return created as unknown as {
-        id?: string;
-        status?: string;
-        output_text?: string;
-        output?: unknown[];
-        usage?: unknown;
-      };
+      return created;
     }
 
-    return await this.waitForCompletion(created.id, args.abortSignal);
+    return await this.waitForCompletion(created.id, args.abortSignal, {
+      model: args.model,
+      reasoningEffort: args.reasoningEffort,
+      maxWaitMs: this.resolveMaxBackgroundWaitMs(args.maxBackgroundWaitMs),
+      requestedServiceTier: args.serviceTier,
+    });
   }
 
   private async waitForCompletion(
     responseId: string,
-    abortSignal?: AbortSignal
-  ): Promise<{
-    id?: string;
-    status?: string;
-    output_text?: string;
-    output?: unknown[];
-    usage?: unknown;
-  }> {
-    let delayMs = 500;
+    abortSignal?: AbortSignal,
+    ctx?: {
+      model?: string;
+      reasoningEffort?: OpenAIApi.Chat.Completions.ChatCompletionReasoningEffort;
+      maxWaitMs?: number;
+      requestedServiceTier?: OpenAiServiceTier;
+    }
+  ): Promise<OpenAIApi.Responses.Response> {
+    this.logger.debug({ message: 'Waiting for completion', obj: { responseId } });
+    const maxWaitMs = this.resolveMaxBackgroundWaitMs(ctx?.maxWaitMs);
+
+    const startedAtMs = Date.now();
+
+    const delayMs = 1000;
+    let pollAttempt = 0;
+
+    let lastStatus = '';
+    let cancelAttempted = false;
+
+    const warnEveryMs = 10 * 60 * 1000;
+    let nextWarnAtMs = warnEveryMs;
+
+    const throwPollingStop = async (args: { kind: 'aborted' | 'timeout'; cause?: unknown }): Promise<never> => {
+      const waitedMs = Date.now() - startedAtMs;
+
+      // Best-effort cancellation to stop server-side work when we're done waiting.
+      let cancel: Awaited<ReturnType<OpenAiResponses['cancelResponseBestEffort']>> | undefined = undefined;
+      if (!cancelAttempted) {
+        cancelAttempted = true;
+        cancel = await this.cancelResponseBestEffort(responseId);
+      }
+
+      const baseDetails: Record<string, unknown> = {
+        operation: 'responses.retrieve',
+        response_id: responseId,
+        background: true,
+        poll_attempt: pollAttempt,
+        waited_ms: waitedMs,
+        max_wait_ms: maxWaitMs,
+        last_status: lastStatus || undefined,
+        model: typeof ctx?.model === 'string' && ctx.model.trim() ? ctx.model.trim() : undefined,
+        reasoning_effort: ctx?.reasoningEffort,
+        requested_service_tier:
+          typeof ctx?.requestedServiceTier === 'string' && ctx.requestedServiceTier.trim()
+            ? ctx.requestedServiceTier.trim()
+            : undefined,
+        aborted: args.kind === 'aborted' ? true : undefined,
+        timeout: args.kind === 'timeout' ? true : undefined,
+        cancel_attempted: cancel?.attempted ? true : undefined,
+        cancel_ok: cancel && cancel.attempted && 'ok' in cancel ? (cancel as any).ok : undefined,
+        cancel_timed_out: cancel && cancel.attempted && (cancel as any).timedOut ? true : undefined,
+        cancel_error: cancel && cancel.attempted && (cancel as any).error ? (cancel as any).error : undefined,
+      };
+
+      if (args.cause) {
+        baseDetails.polling_cause = safeErrorSummary(args.cause);
+      }
+
+      const msg =
+        args.kind === 'timeout'
+          ? `Background response exceeded max wait (maxWaitMs=${maxWaitMs}) while polling (id=${responseId}).`
+          : `Background polling aborted (id=${responseId}).`;
+
+      throw new OpenAiResponsesError({
+        code: 'OPENAI_API',
+        message: msg,
+        details: baseDetails,
+        cause: args.cause,
+      });
+    };
 
     for (;;) {
+      const waitedMs = Date.now() - startedAtMs;
+
+      // Abort wins immediately.
       if (abortSignal?.aborted) {
-        throw new Error(`Request aborted`);
+        await throwPollingStop({ kind: 'aborted' });
       }
 
-      const resp = await this.client.responses.retrieve(
-        responseId,
-        undefined,
-        abortSignal ? { signal: abortSignal } : undefined
-      );
+      // Max wait cap (1h default) to prevent runaway polling.
+      if (waitedMs >= maxWaitMs) {
+        await throwPollingStop({ kind: 'timeout' });
+      }
 
-      const status = typeof (resp as any)?.status === 'string' ? String((resp as any).status).toLowerCase() : '';
-      if (status === 'completed' || status === 'failed' || status === 'cancelled' || status === 'incomplete') {
-        return resp as unknown as {
-          id?: string;
-          status?: string;
-          output_text?: string;
-          output?: unknown[];
-          usage?: unknown;
-        };
+      // Warn every 10 minutes elapsed (best-effort; may log slightly after the boundary).
+      if (waitedMs >= nextWarnAtMs) {
+        nextWarnAtMs += warnEveryMs;
+
+        this.logger.warn({
+          message: `Background polling still in progress`,
+          obj: {
+            responseId,
+            status: lastStatus || undefined,
+            waitedMs,
+            pollAttempt,
+            model: typeof ctx?.model === 'string' && ctx.model.trim() ? ctx.model.trim() : undefined,
+            reasoningEffort: ctx?.reasoningEffort,
+            serviceTier:
+              typeof ctx?.requestedServiceTier === 'string' && ctx.requestedServiceTier.trim()
+                ? ctx.requestedServiceTier.trim()
+                : undefined,
+          },
+        });
       }
 
-      this.logger.debug({ message: `Polling response`, obj: { responseId, status, delayMs } });
+      pollAttempt += 1;
+
+      let resp: OpenAIApi.Responses.Response;
+      try {
+        resp = await this.client.responses.retrieve(
+          responseId,
+          undefined,
+          abortSignal ? { signal: abortSignal } : undefined
+        );
+      } catch (error: unknown) {
+        // If the request was aborted mid-flight, treat it as an abort and still attempt cancellation.
+        if (abortSignal?.aborted || isAbortError(error)) {
+          await throwPollingStop({ kind: 'aborted', cause: error });
+        }
+
+        throw this.toOpenAiApiError(error, {
+          operation: 'responses.retrieve',
+          model: ctx?.model,
+          reasoningEffort: ctx?.reasoningEffort,
+          backgroundMode: true,
+          responseId,
+          pollAttempt,
+          waitedMs,
+          maxWaitMs,
+          lastStatus,
+          requestedServiceTier: ctx?.requestedServiceTier,
+        });
+      }
 
-      await sleep(delayMs);
-      delayMs = Math.min(5000, Math.floor(delayMs * 1.5));
+      const status = typeof resp?.status === 'string' ? resp.status : '';
+      lastStatus = status;
+
+      // Terminal states
+      if (status === 'completed' || status === 'failed' || status === 'incomplete' || status === 'cancelled') {
+        return resp;
+      }
+
+      this.logger.debug({ message: `Polling response`, obj: { responseId, status, delayMs, pollAttempt, waitedMs } });
+
+      // Sleep but wake early if aborted, so abort latency is low.
+      await sleepWithAbort(delayMs, abortSignal);
     }
   }
 
@@ -641,48 +1082,32 @@ export class OpenAiResponses {
   // Usage + text extraction
   // -----------------------------------------
 
-  private addUsageFromResponse(response: { usage?: unknown }, usage: UsageDataAccumulator): void {
-    const u = response.usage;
-    if (!u || typeof u !== 'object') {
+  private addUsageFromResponse(
+    response: OpenAIApi.Responses.Response,
+    usage: UsageDataAccumulator,
+    ctx?: { requestedServiceTier?: OpenAiServiceTier }
+  ): void {
+    if (!response.usage) {
       return;
     }
 
-    const rec = u as Record<string, unknown>;
-    const input = typeof rec.input_tokens === 'number' ? rec.input_tokens : 0;
-    const output = typeof rec.output_tokens === 'number' ? rec.output_tokens : 0;
-    const total = typeof rec.total_tokens === 'number' ? rec.total_tokens : input + output;
-
-    let cached = 0;
-    let reasoning = 0;
-
-    const inputDetails = rec.input_tokens_details;
-    if (inputDetails && typeof inputDetails === 'object') {
-      const id = inputDetails as Record<string, unknown>;
-      cached = typeof id.cached_tokens === 'number' ? id.cached_tokens : 0;
-    }
-
-    const outputDetails = rec.output_tokens_details;
-    if (outputDetails && typeof outputDetails === 'object') {
-      const od = outputDetails as Record<string, unknown>;
-      reasoning = typeof od.reasoning_tokens === 'number' ? od.reasoning_tokens : 0;
-    }
-
-    usage.addTokenUsage({
-      promptTokens: input,
-      cachedPromptTokens: cached,
-      completionTokens: output,
-      reasoningTokens: reasoning,
-      totalTokens: total,
-    });
+    usage.addTokenUsage(
+      {
+        inputTokens: response.usage.input_tokens,
+        cachedInputTokens: response.usage.input_tokens_details.cached_tokens,
+        outputTokens: response.usage.output_tokens,
+        reasoningTokens: response.usage.output_tokens_details.reasoning_tokens,
+        totalTokens: response.usage.total_tokens,
+      },
+      { serviceTier: response.service_tier ?? ctx?.requestedServiceTier }
+    );
   }
 
   private extractAssistantText(response: { output_text?: string; output?: unknown[] }): string {
-    const direct = typeof response.output_text === 'string' ? response.output_text.trim() : '';
-    if (direct) {
-      return direct;
-    }
-
     const out = Array.isArray(response.output) ? response.output : [];
+
+    let lastJoined = '';
+
     for (const item of out) {
       if (!item || typeof item !== 'object') {
         continue;
@@ -717,10 +1142,19 @@ export class OpenAiResponses {
 
       const joined = pieces.join('\n').trim();
       if (joined) {
-        return joined;
+        lastJoined = joined;
       }
     }
 
+    if (lastJoined) {
+      return lastJoined;
+    }
+
+    const direct = typeof response.output_text === 'string' ? response.output_text.trim() : '';
+    if (direct) {
+      return direct;
+    }
+
     return '';
   }
 
@@ -744,8 +1178,12 @@ export class OpenAiResponses {
     };
   }
 
-  private parseAndValidateStructuredOutput<T>(text: string, schema: unknown): T {
-    const parsed = this.parseJson(text);
+  private parseAndValidateStructuredOutput<T>(
+    text: string,
+    schema: unknown,
+    ctx?: { model?: string; maxOutputTokens?: number; requestedServiceTier?: OpenAiServiceTier; serviceTier?: string }
+  ): T {
+    const parsed = this.parseJson(text, ctx);
 
     if (this.isZodSchema(schema)) {
       const res = schema.safeParse(parsed);
@@ -765,7 +1203,10 @@ export class OpenAiResponses {
     return typeof (schema as any).safeParse === 'function';
   }
 
-  private parseJson(text: string): any {
+  private parseJson(
+    text: string,
+    ctx?: { model?: string; maxOutputTokens?: number; requestedServiceTier?: OpenAiServiceTier; serviceTier?: string }
+  ): any {
     const cleaned = String(text ?? '')
       .trim()
       .replace(/^```(?:json)?/i, '')
@@ -774,7 +1215,9 @@ export class OpenAiResponses {
 
     try {
       return JSON.parse(cleaned);
-    } catch {
+    } catch (err1: unknown) {
+      const firstErrMsg = err1 instanceof Error ? err1.message : String(err1);
+
       const s = cleaned;
       const firstObj = s.indexOf('{');
       const firstArr = s.indexOf('[');
@@ -785,10 +1228,102 @@ export class OpenAiResponses {
       const end = Math.max(lastObj, lastArr);
 
       if (start >= 0 && end > start) {
-        return JSON.parse(s.slice(start, end + 1));
+        const candidate = s.slice(start, end + 1);
+        try {
+          return JSON.parse(candidate);
+        } catch (err2: unknown) {
+          const secondErrMsg = err2 instanceof Error ? err2.message : String(err2);
+
+          const pos2rel = extractJsonParsePosition(secondErrMsg);
+          const pos2 = typeof pos2rel === 'number' ? start + pos2rel : undefined;
+
+          const pos1 = extractJsonParsePosition(firstErrMsg);
+          const pos = typeof pos2 === 'number' ? pos2 : pos1;
+
+          const lc = extractJsonParseLineCol(secondErrMsg) ?? extractJsonParseLineCol(firstErrMsg);
+
+          const details: Record<string, unknown> = {
+            model: typeof ctx?.model === 'string' && ctx.model.trim() ? ctx.model : undefined,
+            max_output_tokens: typeof ctx?.maxOutputTokens === 'number' ? ctx.maxOutputTokens : undefined,
+
+            requested_service_tier:
+              typeof ctx?.requestedServiceTier === 'string' && String(ctx.requestedServiceTier).trim()
+                ? String(ctx.requestedServiceTier).trim()
+                : undefined,
+            service_tier:
+              typeof ctx?.serviceTier === 'string' && ctx.serviceTier.trim() ? ctx.serviceTier.trim() : undefined,
+
+            cleaned_len: s.length,
+            cleaned_head: truncateHead(s, 250),
+            cleaned_tail: truncateTail(s, 500),
+
+            json_start: start,
+            json_end: end,
+            json_candidate_len: candidate.length,
+
+            first_error: firstErrMsg,
+            second_error: secondErrMsg,
+
+            error_pos: typeof pos === 'number' ? pos : undefined,
+            error_line: lc?.line,
+            error_column: lc?.column,
+            error_context: typeof pos === 'number' ? snippetAround(s, pos, 160) : undefined,
+          };
+
+          const msg =
+            `Failed to parse model output as JSON. ` +
+            `cleaned_len=${s.length} json_start=${start} json_end=${end}. ` +
+            `first_error=${JSON.stringify(firstErrMsg)} second_error=${JSON.stringify(secondErrMsg)}.`;
+
+          throw new OpenAiResponsesError({
+            code: 'JSON_PARSE',
+            message: msg,
+            details,
+            cause: err2,
+          });
+        }
       }
 
-      throw new Error(`Failed to parse model output as JSON`);
+      const pos = extractJsonParsePosition(firstErrMsg);
+      const lc = extractJsonParseLineCol(firstErrMsg);
+
+      const details: Record<string, unknown> = {
+        model: typeof ctx?.model === 'string' && ctx.model.trim() ? ctx.model : undefined,
+        max_output_tokens: typeof ctx?.maxOutputTokens === 'number' ? ctx.maxOutputTokens : undefined,
+
+        requested_service_tier:
+          typeof ctx?.requestedServiceTier === 'string' && String(ctx.requestedServiceTier).trim()
+            ? String(ctx.requestedServiceTier).trim()
+            : undefined,
+        service_tier:
+          typeof ctx?.serviceTier === 'string' && ctx.serviceTier.trim() ? ctx.serviceTier.trim() : undefined,
+
+        cleaned_len: s.length,
+        cleaned_head: truncateHead(s, 250),
+        cleaned_tail: truncateTail(s, 500),
+
+        json_start: start >= 0 ? start : undefined,
+        json_end: end >= 0 ? end : undefined,
+
+        first_error: firstErrMsg,
+
+        error_pos: typeof pos === 'number' ? pos : undefined,
+        error_line: lc?.line,
+        error_column: lc?.column,
+        error_context: typeof pos === 'number' ? snippetAround(s, pos, 160) : undefined,
+      };
+
+      const msg =
+        `Failed to parse model output as JSON. ` +
+        `cleaned_len=${s.length}. ` +
+        `error=${JSON.stringify(firstErrMsg)}.`;
+
+      throw new OpenAiResponsesError({
+        code: 'JSON_PARSE',
+        message: msg,
+        details,
+        cause: err1,
+      });
     }
   }
 
@@ -1038,9 +1573,8 @@ export class OpenAiResponses {
   // Model/background defaults
   // -----------------------------------------
 
-  private resolveModel(model?: string): string {
-    const m = (model ?? this.defaultModel).trim();
-    return m.length > 0 ? m : DEFAULT_RESPONSES_MODEL;
+  private resolveModel(model?: TiktokenModel): TiktokenModel {
+    return model ?? this.defaultModel;
   }
 
   private resolveBackgroundMode(args: {
@@ -1071,6 +1605,265 @@ export class OpenAiResponses {
   }
 }
 
+export type OpenAiResponsesErrorCode = 'OPENAI_API' | 'RESPONSE_STATUS' | 'JSON_PARSE';
+
+export class OpenAiResponsesError extends Error {
+  public readonly code: OpenAiResponsesErrorCode;
+  public readonly details: Record<string, unknown>;
+  public readonly cause?: unknown;
+  public readonly retryable: boolean;
+
+  constructor(args: {
+    code: OpenAiResponsesErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+    retryable?: boolean;
+  }) {
+    super(args.message);
+    this.name = 'OpenAiResponsesError';
+    this.code = args.code;
+    this.details = args.details ?? {};
+    this.cause = args.cause;
+    this.retryable = typeof args.retryable === 'boolean' ? args.retryable : true;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+function truncateHead(text: string, max: number): string {
+  const s = String(text ?? '');
+  if (max <= 0) {
+    return '';
+  }
+  if (s.length <= max) {
+    return s;
+  }
+  return s.slice(0, max) + '...';
+}
+
+function truncateTail(text: string, max: number): string {
+  const s = String(text ?? '');
+  if (max <= 0) {
+    return '';
+  }
+  if (s.length <= max) {
+    return s;
+  }
+  return '...' + s.slice(s.length - max);
+}
+
+function extractJsonParsePosition(errMsg: string): number | undefined {
+  const m = String(errMsg ?? '').match(/at position\s+(\d+)/i);
+  if (!m) {
+    return undefined;
+  }
+  const n = Number(m[1]);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function extractJsonParseLineCol(errMsg: string): { line?: number; column?: number } | undefined {
+  const m = String(errMsg ?? '').match(/line\s+(\d+)\s+column\s+(\d+)/i);
+  if (!m) {
+    return undefined;
+  }
+  const line = Number(m[1]);
+  const column = Number(m[2]);
+  return {
+    line: Number.isFinite(line) ? line : undefined,
+    column: Number.isFinite(column) ? column : undefined,
+  };
+}
+
+function snippetAround(text: string, pos: number, radius: number): string {
+  const s = String(text ?? '');
+  const p = Math.max(0, Math.min(s.length, Number.isFinite(pos) ? pos : 0));
+  const r = Math.max(0, radius);
+
+  const start = Math.max(0, p - r);
+  const end = Math.min(s.length, p + r);
+
+  const before = s.slice(start, p);
+  const after = s.slice(p, end);
+
+  const left = start > 0 ? '...' : '';
+  const right = end < s.length ? '...' : '';
+
+  return `${left}${before}<<HERE>>${after}${right}`;
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+/**
+ * Sleep, but wake early if the signal is aborted.
+ * (We do not throw here; the caller should check `signal.aborted` and act.)
+ */
+function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void> {
+  if (!signal) {
+    return sleep(ms);
+  }
+  if (signal.aborted) {
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve) => {
+    const t = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+
+    const onAbort = () => {
+      cleanup();
+      resolve();
+    };
+
+    const cleanup = () => {
+      try {
+        clearTimeout(t);
+      } catch {
+        // ignore
+      }
+      try {
+        signal.removeEventListener?.('abort', onAbort as any);
+      } catch {
+        // ignore
+      }
+    };
+
+    try {
+      signal.addEventListener?.('abort', onAbort as any, { once: true });
+    } catch {
+      // If addEventListener isn't available, fall back to plain sleep.
+    }
+  });
+}
+
+function extractHttpStatus(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object') {
+    return undefined;
+  }
+  const rec = error as Record<string, unknown>;
+  const status = rec.status;
+  if (typeof status === 'number' && Number.isFinite(status)) {
+    return status;
+  }
+  const statusCode = rec.statusCode;
+  if (typeof statusCode === 'number' && Number.isFinite(statusCode)) {
+    return statusCode;
+  }
+  return undefined;
+}
+
+function extractRequestId(error: unknown): string | undefined {
+  if (!error || typeof error !== 'object') {
+    return undefined;
+  }
+  const rec = error as Record<string, unknown>;
+
+  const direct = rec.request_id ?? rec.requestId;
+  if (typeof direct === 'string' && direct.trim()) {
+    return direct.trim();
+  }
+
+  const headers = rec.headers as any;
+  if (!headers) {
+    return undefined;
+  }
+
+  if (typeof headers.get === 'function') {
+    const v = headers.get('x-request-id');
+    return typeof v === 'string' && v.trim() ? v.trim() : undefined;
+  }
+
+  if (typeof headers === 'object' && !Array.isArray(headers)) {
+    for (const k of Object.keys(headers)) {
+      if (String(k).toLowerCase() !== 'x-request-id') {
+        continue;
+      }
+      const v = (headers as any)[k];
+      return typeof v === 'string' && v.trim() ? v.trim() : undefined;
+    }
+  }
+
+  return undefined;
+}
+
+function isRetryableHttpStatus(status: number | undefined): boolean {
+  if (typeof status !== 'number') {
+    return true;
+  }
+  if (status === 408 || status === 409 || status === 429) {
+    return true;
+  }
+  if (status >= 500) {
+    return true;
+  }
+  return false;
+}
+
+function isAbortError(error: unknown): boolean {
+  if (!error) {
+    return false;
+  }
+
+  // Most fetch implementations:
+  //  - error.name === 'AbortError'
+  //  - or error.code === 'ABORT_ERR'
+  if (error instanceof Error) {
+    const name = String(error.name ?? '').toLowerCase();
+    if (name === 'aborterror') {
+      return true;
+    }
+    const msg = String(error.message ?? '').toLowerCase();
+    // Keep this conservative; don't treat every "abort" substring as abort.
+    if (msg === 'aborted' || msg === 'request aborted') {
+      return true;
+    }
+  }
+
+  if (typeof error === 'object') {
+    const rec = error as Record<string, unknown>;
+    const code = rec.code;
+    if (typeof code === 'string' && code.toUpperCase() === 'ABORT_ERR') {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function safeErrorSummary(error: unknown): Record<string, unknown> {
+  if (!error) {
+    return { message: 'Unknown error' };
+  }
+
+  const status = extractHttpStatus(error);
+  const requestId = extractRequestId(error);
+
+  if (error instanceof OpenAiResponsesError) {
+    return {
+      name: error.name,
+      message: error.message,
+      code: error.code,
+      details: error.details,
+      status: typeof status === 'number' ? status : undefined,
+      request_id: requestId,
+    };
+  }
+
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      status: typeof status === 'number' ? status : undefined,
+      request_id: requestId,
+    };
+  }
+
+  return {
+    message: String(error),
+    status: typeof status === 'number' ? status : undefined,
+    request_id: requestId,
+  };
+}