@kenkaiiii/gg-ai 4.3.165 → 4.3.167

package/dist/index.d.cts

@@ -157,6 +157,10 @@ interface StreamOptions {
     signal?: AbortSignal;
     /** Prompt cache retention preference. Providers map this to their supported values. Default: "short". */
     cacheRetention?: CacheRetention;
+    /** Stable per-session cache routing key for providers that support it (OpenAI, Moonshot). */
+    promptCacheKey?: string;
+    /** OpenAI service tier for latency-sensitive requests. Only sent to first-party OpenAI API calls. */
+    serviceTier?: "auto" | "default" | "flex" | "priority";
     /** OpenAI ChatGPT account ID (from OAuth JWT) for codex endpoint */
     accountId?: string;
     /** Enable provider-native web search. Each provider uses its own format:
@@ -292,17 +296,74 @@ declare class ProviderRegistryImpl {
 /** Global provider registry. Import this to register custom providers. */
 declare const providerRegistry: ProviderRegistryImpl;
 
+/**
+ * Error model for gg-ai and downstream consumers.
+ *
+ * Every error users see should answer one question: "is this me or them?"
+ * That answer drives whether they retry, switch model, log in, or report a
+ * ggcoder bug. The `FormattedError` shape captures it in plain English:
+ *
+ *   ✗ OpenAI returned an error.
+ *     An error occurred while processing your request...
+ *     → This is an OpenAI issue, not ggcoder. Retry — if it persists, check status.openai.com.
+ *
+ *   ✗ ggcoder hit an unexpected error.
+ *     Cannot read property 'foo' of undefined
+ *     → This is a ggcoder bug — please report it.
+ */
+type ErrorSource = "provider" | "ggcoder" | "network" | "auth";
+interface FormattedError {
+    /** Plain-English headline, e.g. "OpenAI returned an error." */
+    headline: string;
+    /** Machine-readable classification. */
+    source: ErrorSource;
+    /** Detailed message body from the underlying error (no JSON, no tag prefix). */
+    message: string;
+    /** Action line — tells the user whether to retry, switch model, log in, or report a bug. */
+    guidance: string;
+    /** Provider name when source === "provider". */
+    provider?: string;
+    /** HTTP status code if known. */
+    statusCode?: number;
+    /** Provider request ID, kept for telemetry / debug — not shown by default. */
+    requestId?: string;
+}
 declare class GGAIError extends Error {
-    constructor(message: string, options?: ErrorOptions);
+    readonly source: ErrorSource;
+    readonly requestId?: string;
+    readonly hint?: string;
+    constructor(message: string, options?: {
+        source?: ErrorSource;
+        requestId?: string;
+        hint?: string;
+        cause?: unknown;
+    });
 }
 declare class ProviderError extends GGAIError {
     readonly provider: string;
     readonly statusCode?: number;
     constructor(provider: string, message: string, options?: {
         statusCode?: number;
+        requestId?: string;
+        hint?: string;
         cause?: unknown;
     });
 }
+/**
+ * Normalise any thrown value into a structured display object. Always returns
+ * a non-empty `headline` and `guidance` so the UI never has to second-guess
+ * what to show the user.
+ */
+declare function formatError(err: unknown): FormattedError;
+/**
+ * Render a FormattedError as a multi-line string for terminal display.
+ *
+ * Format:
+ *   <headline>
+ *     <message>
+ *     → <guidance>
+ */
+declare function formatErrorForDisplay(err: unknown): string;
 
 interface PalsuProviderState {
     callCount: number;
@@ -373,4 +434,4 @@ interface PalsuProviderConfig {
  */
 declare function registerPalsuProvider(config?: PalsuProviderConfig): PalsuProviderHandle;
 
-export { type AssistantMessage, type CacheRetention, type ContentPart, type DoneEvent, type ErrorEvent, EventStream, GGAIError, type ImageContent, type Message, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type Provider, type ProviderEntry, ProviderError, type ProviderStreamFn, type RawContent, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, palsuAssistantMessage, palsuText, palsuThinking, palsuToolCall, providerRegistry, registerPalsuProvider, stream };
+export { type AssistantMessage, type CacheRetention, type ContentPart, type DoneEvent, type ErrorEvent, type ErrorSource, EventStream, type FormattedError, GGAIError, type ImageContent, type Message, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type Provider, type ProviderEntry, ProviderError, type ProviderStreamFn, type RawContent, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, formatError, formatErrorForDisplay, palsuAssistantMessage, palsuText, palsuThinking, palsuToolCall, providerRegistry, registerPalsuProvider, stream };

package/dist/index.d.ts

@@ -157,6 +157,10 @@ interface StreamOptions {
     signal?: AbortSignal;
     /** Prompt cache retention preference. Providers map this to their supported values. Default: "short". */
     cacheRetention?: CacheRetention;
+    /** Stable per-session cache routing key for providers that support it (OpenAI, Moonshot). */
+    promptCacheKey?: string;
+    /** OpenAI service tier for latency-sensitive requests. Only sent to first-party OpenAI API calls. */
+    serviceTier?: "auto" | "default" | "flex" | "priority";
     /** OpenAI ChatGPT account ID (from OAuth JWT) for codex endpoint */
     accountId?: string;
     /** Enable provider-native web search. Each provider uses its own format:
@@ -292,17 +296,74 @@ declare class ProviderRegistryImpl {
 /** Global provider registry. Import this to register custom providers. */
 declare const providerRegistry: ProviderRegistryImpl;
 
+/**
+ * Error model for gg-ai and downstream consumers.
+ *
+ * Every error users see should answer one question: "is this me or them?"
+ * That answer drives whether they retry, switch model, log in, or report a
+ * ggcoder bug. The `FormattedError` shape captures it in plain English:
+ *
+ *   ✗ OpenAI returned an error.
+ *     An error occurred while processing your request...
+ *     → This is an OpenAI issue, not ggcoder. Retry — if it persists, check status.openai.com.
+ *
+ *   ✗ ggcoder hit an unexpected error.
+ *     Cannot read property 'foo' of undefined
+ *     → This is a ggcoder bug — please report it.
+ */
+type ErrorSource = "provider" | "ggcoder" | "network" | "auth";
+interface FormattedError {
+    /** Plain-English headline, e.g. "OpenAI returned an error." */
+    headline: string;
+    /** Machine-readable classification. */
+    source: ErrorSource;
+    /** Detailed message body from the underlying error (no JSON, no tag prefix). */
+    message: string;
+    /** Action line — tells the user whether to retry, switch model, log in, or report a bug. */
+    guidance: string;
+    /** Provider name when source === "provider". */
+    provider?: string;
+    /** HTTP status code if known. */
+    statusCode?: number;
+    /** Provider request ID, kept for telemetry / debug — not shown by default. */
+    requestId?: string;
+}
 declare class GGAIError extends Error {
-    constructor(message: string, options?: ErrorOptions);
+    readonly source: ErrorSource;
+    readonly requestId?: string;
+    readonly hint?: string;
+    constructor(message: string, options?: {
+        source?: ErrorSource;
+        requestId?: string;
+        hint?: string;
+        cause?: unknown;
+    });
 }
 declare class ProviderError extends GGAIError {
     readonly provider: string;
     readonly statusCode?: number;
     constructor(provider: string, message: string, options?: {
         statusCode?: number;
+        requestId?: string;
+        hint?: string;
         cause?: unknown;
     });
 }
+/**
+ * Normalise any thrown value into a structured display object. Always returns
+ * a non-empty `headline` and `guidance` so the UI never has to second-guess
+ * what to show the user.
+ */
+declare function formatError(err: unknown): FormattedError;
+/**
+ * Render a FormattedError as a multi-line string for terminal display.
+ *
+ * Format:
+ *   <headline>
+ *     <message>
+ *     → <guidance>
+ */
+declare function formatErrorForDisplay(err: unknown): string;
 
 interface PalsuProviderState {
     callCount: number;
@@ -373,4 +434,4 @@ interface PalsuProviderConfig {
  */
 declare function registerPalsuProvider(config?: PalsuProviderConfig): PalsuProviderHandle;
 
-export { type AssistantMessage, type CacheRetention, type ContentPart, type DoneEvent, type ErrorEvent, EventStream, GGAIError, type ImageContent, type Message, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type Provider, type ProviderEntry, ProviderError, type ProviderStreamFn, type RawContent, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, palsuAssistantMessage, palsuText, palsuThinking, palsuToolCall, providerRegistry, registerPalsuProvider, stream };
+export { type AssistantMessage, type CacheRetention, type ContentPart, type DoneEvent, type ErrorEvent, type ErrorSource, EventStream, type FormattedError, GGAIError, type ImageContent, type Message, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type Provider, type ProviderEntry, ProviderError, type ProviderStreamFn, type RawContent, type ServerToolCall, type ServerToolCallEvent, type ServerToolDefinition, type ServerToolResult, type ServerToolResultEvent, type StopReason, type StreamEvent, type StreamOptions, type StreamResponse, StreamResult, type SystemMessage, type TextContent, type TextDeltaEvent, type ThinkingContent, type ThinkingDeltaEvent, type ThinkingLevel, type Tool, type ToolCall, type ToolCallDeltaEvent, type ToolCallDoneEvent, type ToolChoice, type ToolResult, type ToolResultContent, type ToolResultMessage, type Usage, type UserMessage, formatError, formatErrorForDisplay, palsuAssistantMessage, palsuText, palsuThinking, palsuToolCall, providerRegistry, registerPalsuProvider, stream };

package/dist/index.js

@@ -1,20 +1,164 @@
 // src/errors.ts
 var GGAIError = class extends Error {
+  source;
+  requestId;
+  hint;
   constructor(message, options) {
-    super(message, options);
+    super(message, { cause: options?.cause });
     this.name = "GGAIError";
+    this.source = options?.source ?? "ggcoder";
+    this.requestId = options?.requestId;
+    this.hint = options?.hint;
   }
 };
 var ProviderError = class extends GGAIError {
   provider;
   statusCode;
   constructor(provider, message, options) {
-    super(`[${provider}] ${message}`, { cause: options?.cause });
+    super(message, {
+      source: "provider",
+      requestId: options?.requestId,
+      hint: options?.hint,
+      cause: options?.cause
+    });
     this.name = "ProviderError";
     this.provider = provider;
     this.statusCode = options?.statusCode;
   }
 };
+var PROVIDER_DISPLAY = {
+  openai: "OpenAI",
+  anthropic: "Anthropic",
+  glm: "Z.AI (GLM)",
+  moonshot: "Moonshot",
+  deepseek: "DeepSeek",
+  openrouter: "OpenRouter",
+  xiaomi: "Xiaomi (MiMo)",
+  minimax: "MiniMax"
+};
+var PROVIDER_STATUS_URL = {
+  openai: "status.openai.com",
+  anthropic: "status.anthropic.com"
+};
+function providerDisplayName(provider) {
+  return PROVIDER_DISPLAY[provider] ?? provider;
+}
+function formatError(err) {
+  if (err instanceof ProviderError) {
+    const name = providerDisplayName(err.provider);
+    const cleanMessage = cleanProviderMessage(err.message);
+    return {
+      headline: `${name} returned an error.`,
+      source: "provider",
+      message: cleanMessage,
+      provider: err.provider,
+      statusCode: err.statusCode,
+      requestId: err.requestId,
+      guidance: err.hint ?? providerGuidance(err.provider, cleanMessage, err.statusCode)
+    };
+  }
+  if (err instanceof GGAIError) {
+    return finaliseBySource(err.source, err.message, err.requestId, err.hint);
+  }
+  if (err instanceof Error) {
+    const source = inferSource(err);
+    return finaliseBySource(source, err.message, void 0, void 0);
+  }
+  return finaliseBySource("ggcoder", String(err), void 0, void 0);
+}
+function finaliseBySource(source, message, requestId, hint) {
+  switch (source) {
+    case "network":
+      return {
+        headline: "Network error \u2014 couldn't reach the provider.",
+        source,
+        message,
+        guidance: hint ?? "Check your internet connection. Not a ggcoder issue \u2014 retry shortly.",
+        ...requestId ? { requestId } : {}
+      };
+    case "auth":
+      return {
+        headline: "Authentication issue.",
+        source,
+        message,
+        guidance: hint ?? "Run `ggcoder login` to refresh your credentials.",
+        ...requestId ? { requestId } : {}
+      };
+    case "provider":
+      return {
+        headline: "Provider returned an error.",
+        source,
+        message,
+        guidance: hint ?? providerGuidance(void 0, message, void 0),
+        ...requestId ? { requestId } : {}
+      };
+    case "ggcoder":
+      return {
+        headline: "ggcoder hit an unexpected error.",
+        source,
+        message,
+        guidance: hint ?? "This looks like a ggcoder bug \u2014 please report it to the developer (see /help).",
+        ...requestId ? { requestId } : {}
+      };
+  }
+}
+function formatErrorForDisplay(err) {
+  const f = formatError(err);
+  const lines = [f.headline];
+  if (f.message && f.message !== f.headline) lines.push(`  ${f.message}`);
+  lines.push(`  \u2192 ${f.guidance}`);
+  return lines.join("\n");
+}
+function cleanProviderMessage(message) {
+  return message.replace(/^\[[^\]]+\]\s*/, "").trim();
+}
+function inferSource(err) {
+  const msg = err.message.toLowerCase();
+  const code = err.code ?? "";
+  if (code === "ECONNREFUSED" || code === "ETIMEDOUT" || code === "ENOTFOUND" || code === "ECONNRESET" || msg.includes("fetch failed") || msg.includes("network request failed")) {
+    return "network";
+  }
+  if (msg.includes("not logged in") || msg.includes("token exchange failed") || msg.includes("token refresh failed") || msg.includes("invalid_grant")) {
+    return "auth";
+  }
+  return "ggcoder";
+}
+function providerGuidance(provider, message, statusCode) {
+  const name = provider ? providerDisplayName(provider) : "the provider";
+  const status = provider ? PROVIDER_STATUS_URL[provider] : void 0;
+  const lower = message.toLowerCase();
+  if (statusCode === 401 || lower.includes("unauthorized") || lower.includes("invalid api key")) {
+    return `Authentication failed with ${name}. Run \`ggcoder login\` to refresh your credentials.`;
+  }
+  if (lower.includes("overloaded") || lower.includes("engine_overloaded")) {
+    return `${name}'s servers are overloaded right now. Retry in a moment \u2014 not a ggcoder issue.`;
+  }
+  if (lower.includes("insufficient balance") || lower.includes("quota exceeded") || lower.includes("recharge") || lower.includes("no resource package")) {
+    return `Your ${name} account has a billing or quota issue \u2014 check your balance. Not a ggcoder issue.`;
+  }
+  if (statusCode === 429 || lower.includes("rate limit") || lower.includes("too many requests")) {
+    return `${name} rate limit hit. Wait a moment then retry \u2014 not a ggcoder issue.`;
+  }
+  if (statusCode === 502 || lower.includes("bad gateway")) {
+    return `${name} returned a bad gateway. Retry \u2014 this is on their side, not ggcoder.`;
+  }
+  if (statusCode === 503 || lower.includes("service unavailable")) {
+    return `${name} is temporarily unavailable. Retry shortly \u2014 not a ggcoder issue.`;
+  }
+  if (statusCode === 500 || lower.includes("server_error") || lower.includes("500") && lower.includes("internal server error")) {
+    return status ? `This is an error from ${name}, not ggcoder. Retry \u2014 if it keeps happening, check ${status}.` : `This is an error from ${name}, not ggcoder. Retry \u2014 if it keeps happening, try a different model with /model.`;
+  }
+  if (lower.includes("timeout") || lower.includes("timed out")) {
+    return `Request to ${name} timed out. Their servers may be slow \u2014 retry. Not a ggcoder issue.`;
+  }
+  if (lower.includes("does not recognize the requested model") || lower.includes("model") && (lower.includes("not exist") || lower.includes("not found") || lower.includes("no access"))) {
+    return `${name} doesn't recognise this model on your account. Use /model to switch, or check your subscription tier.`;
+  }
+  if (lower.includes("context_length_exceeded") || lower.includes("prompt is too long")) {
+    return `Context window for this ${name} model is full. Run /compact to shrink history, or start a new session.`;
+  }
+  return status ? `This is an error from ${name}, not ggcoder. Retry \u2014 if it persists, check ${status}.` : `This is an error from ${name}, not ggcoder. Retry \u2014 if it persists, try a different model with /model.`;
+}
 
 // src/providers/anthropic.ts
 import Anthropic from "@anthropic-ai/sdk";
@@ -246,9 +390,18 @@ function toAnthropicToolResultContent(content) {
     };
   });
 }
+function remapAnthropicToolCallId(id, idMap) {
+  if (/^[a-zA-Z0-9_-]+$/.test(id)) return id;
+  const existing = idMap.get(id);
+  if (existing) return existing;
+  const mapped = id.replace(/[^a-zA-Z0-9_-]/g, "_");
+  idMap.set(id, mapped);
+  return mapped;
+}
 function toAnthropicMessages(messages, cacheControl) {
   let systemText;
   const out = [];
+  const idMap = /* @__PURE__ */ new Map();
   for (const msg of messages) {
     if (msg.role === "system") {
       systemText = msg.content;
@@ -283,7 +436,7 @@ function toAnthropicMessages(messages, cacheControl) {
         if (part.type === "tool_call")
           return {
             type: "tool_use",
-            id: part.id,
+            id: remapAnthropicToolCallId(part.id, idMap),
             name: part.name,
             input: part.args
           };
@@ -308,7 +461,7 @@ function toAnthropicMessages(messages, cacheControl) {
         role: "user",
         content: msg.content.map((result) => ({
           type: "tool_result",
-          tool_use_id: result.toolCallId,
+          tool_use_id: remapAnthropicToolCallId(result.toolCallId, idMap),
           content: toAnthropicToolResultContent(result.content),
           is_error: result.isError
         }))
@@ -364,12 +517,19 @@ function toAnthropicMessages(messages, cacheControl) {
   }
   return { system, messages: out };
 }
-function toAnthropicTools(tools) {
-  return tools.map((tool) => ({
-    name: tool.name,
-    description: tool.description,
-    input_schema: tool.rawInputSchema ?? zodToJsonSchema(tool.parameters)
-  }));
+function toAnthropicTools(tools, options) {
+  return tools.map((tool, index) => {
+    const anthropicTool = {
+      name: tool.name,
+      description: tool.description,
+      input_schema: tool.rawInputSchema ?? zodToJsonSchema(tool.parameters),
+      ...options?.enableFineGrainedToolStreaming ? { eager_input_streaming: true } : {}
+    };
+    if (options?.cacheControl && index === tools.length - 1) {
+      anthropicTool.cache_control = options.cacheControl;
+    }
+    return anthropicTool;
+  });
 }
 function toAnthropicToolChoice(choice) {
   if (choice === "auto") return { type: "auto" };
@@ -588,6 +748,7 @@ async function* runStream(options) {
   const isOAuth = options.apiKey?.startsWith("sk-ant-oat");
   const useStreaming = options.streaming !== false;
   const cacheControl = toAnthropicCacheControl(options.cacheRetention, options.baseUrl);
+  const supportsFirstPartyToolExtras = !options.baseUrl || options.baseUrl.includes("api.anthropic.com");
   const downgradedMessages = downgradeUnsupportedImages(options.messages, options.supportsImages);
   const { system: rawSystem, messages } = toAnthropicMessages(downgradedMessages, cacheControl);
   const system = isOAuth ? [
@@ -620,7 +781,10 @@ async function* runStream(options) {
     ...options.stop ? { stop_sequences: options.stop } : {},
     ...options.tools?.length || options.serverTools?.length || options.webSearch ? {
       tools: [
-        ...options.tools?.length ? toAnthropicTools(options.tools) : [],
+        ...options.tools?.length ? toAnthropicTools(options.tools, {
+          ...supportsFirstPartyToolExtras && cacheControl ? { cacheControl } : {},
+          ...supportsFirstPartyToolExtras ? { enableFineGrainedToolStreaming: true } : {}
+        }) : [],
         ...options.serverTools ?? [],
         ...options.webSearch ? [{ type: "web_search_20250305", name: "web_search" }] : []
       ]
@@ -953,8 +1117,10 @@ function messageToResponse(message) {
 }
 function toError(err) {
   if (err instanceof Anthropic.APIError) {
+    const requestId = err.request_id ?? err.error?.request_id;
     return new ProviderError("anthropic", err.message, {
       statusCode: err.status,
+      ...requestId ? { requestId } : {},
       cause: err
     });
   }
@@ -1004,12 +1170,15 @@ async function* runStream2(options) {
   };
   if (options.provider === "openai" || options.provider === "moonshot") {
     const paramsAny = params;
-    paramsAny.prompt_cache_key = "ggcoder";
+    paramsAny.prompt_cache_key = options.promptCacheKey ?? "ggcoder";
     const retention = options.cacheRetention ?? "short";
     if (retention === "long") {
       paramsAny.prompt_cache_retention = "24h";
     }
   }
+  if (options.provider === "openai" && options.serviceTier) {
+    params.service_tier = options.serviceTier;
+  }
   if (usesThinkingParam) {
     if (options.thinking) {
       params.thinking = { type: "enabled" };
@@ -1246,19 +1415,19 @@ function completionToResponse(completion) {
 }
 function toError2(err, provider = "openai") {
   if (err instanceof OpenAI.APIError) {
-    let msg = err.message;
     const body = err.error;
-    if (body) {
-      const modelName = body.model || "";
-      const _code = body.code || "";
-      const message = body.message || "";
-      if (modelName === "codex-mini-latest" || message.includes("codex-mini-latest")) {
-        msg = `codex-mini-latest requires an OpenAI Pro or Max subscription. You currently have access to GPT-5.4 and GPT-5.4 Mini with your account.`;
-      }
-      msg += ` | body: ${JSON.stringify(body)}`;
-    }
-    return new ProviderError(provider, msg, {
+    const bodyMessage = typeof body?.message === "string" && body.message.trim() ? body.message.trim() : void 0;
+    const modelName = typeof body?.model === "string" ? body.model : "";
+    const cleanMessage = bodyMessage ?? err.message;
+    let hint;
+    if (modelName === "codex-mini-latest" || cleanMessage.includes("codex-mini-latest")) {
+      hint = "codex-mini-latest requires an OpenAI Pro or Max subscription. Your account currently has access to GPT-5.4 and GPT-5.4 Mini.";
+    }
+    const requestId = err.request_id ?? (typeof body?.request_id === "string" ? body.request_id : void 0);
+    return new ProviderError(provider, cleanMessage, {
       statusCode: err.status,
+      ...requestId ? { requestId } : {},
+      ...hint ? { hint } : {},
       cause: err
     });
   }
@@ -1292,6 +1461,9 @@ async function* runStream3(options) {
   if (options.tools?.length) {
     body.tools = toCodexTools(options.tools);
   }
+  if (options.promptCacheKey) {
+    body.prompt_cache_key = options.promptCacheKey;
+  }
   if (options.temperature != null && !options.thinking) {
     body.temperature = options.temperature;
   }
@@ -1320,19 +1492,19 @@ async function* runStream3(options) {
   });
   if (!response.ok) {
     const text = await response.text().catch(() => "");
-    let message = `Codex API error (${response.status}): ${text}`;
+    const parsed = parseCodexErrorBody(text);
+    const message = parsed.message ?? `Codex API returned HTTP ${response.status}.`;
+    const requestId = parsed.requestId ?? response.headers.get("x-request-id") ?? response.headers.get("openai-request-id") ?? void 0;
+    let hint;
     if (response.status === 400 && text.includes("not supported")) {
-      message += `
-
-Hint: Codex models require a ChatGPT Plus ($20/mo) or Pro ($200/mo) subscription. The "codex-spark" variants require ChatGPT Pro. Ensure your account has an active subscription at https://chatgpt.com/settings`;
-    }
-    if (response.status === 404 && text.includes("does not exist")) {
-      message += `
-
-Hint: codex-mini-latest requires an OpenAI Pro ($200/mo) or Max subscription. GPT-5.4 and GPT-5.4 Mini work with any active ChatGPT plan.`;
+      hint = 'Codex models require a ChatGPT Plus ($20/mo) or Pro ($200/mo) subscription. The "codex-spark" variants require ChatGPT Pro. Check your subscription at https://chatgpt.com/settings.';
+    } else if (response.status === 404 && text.includes("does not exist")) {
+      hint = "codex-mini-latest requires an OpenAI Pro ($200/mo) or Max subscription. GPT-5.4 and GPT-5.4 Mini work with any active ChatGPT plan.";
     }
     throw new ProviderError("openai", message, {
-      statusCode: response.status
+      statusCode: response.status,
+      ...requestId ? { requestId } : {},
+      ...hint ? { hint } : {}
     });
   }
   if (!response.body) {
@@ -1343,16 +1515,27 @@ Hint: codex-mini-latest requires an OpenAI Pro ($200/mo) or Max subscription. GP
   const toolCalls = /* @__PURE__ */ new Map();
   let inputTokens = 0;
   let outputTokens = 0;
+  let cacheRead = 0;
   for await (const event of parseSSE(response.body)) {
     const type = event.type;
     if (!type) continue;
     if (type === "error") {
-      const msg = event.message || JSON.stringify(event);
-      throw new ProviderError("openai", `Codex error: ${msg}`);
+      const nested = event.error ?? void 0;
+      const message = nested?.message ?? event.message ?? "Codex stream emitted an error chunk without a message.";
+      const code = nested?.code ?? nested?.type ?? event.code ?? "server_error";
+      const requestId = extractCodexRequestId(message) ?? event.request_id;
+      throw new ProviderError("openai", message, {
+        ...requestId != null ? { requestId } : {},
+        ...code === "server_error" ? { statusCode: 500 } : {}
+      });
     }
     if (type === "response.failed") {
-      const msg = event.error?.message || "Codex response failed";
-      throw new ProviderError("openai", msg);
+      const nested = event.error;
+      const message = nested?.message ?? "Codex response failed.";
+      const requestId = extractCodexRequestId(message) ?? event.request_id;
+      throw new ProviderError("openai", message, {
+        ...requestId != null ? { requestId } : {}
+      });
     }
     if (type === "response.output_text.delta") {
       const delta = event.delta;
@@ -1425,7 +1608,8 @@ Hint: codex-mini-latest requires an OpenAI Pro ($200/mo) or Max subscription. GP
       const resp = event.response;
       const usage = resp?.usage;
       if (usage) {
-        inputTokens = usage.input_tokens ?? 0;
+        cacheRead = usage.input_tokens_details?.cached_tokens ?? 0;
+        inputTokens = (usage.input_tokens ?? 0) - cacheRead;
         outputTokens = usage.output_tokens ?? 0;
       }
     }
@@ -1455,7 +1639,7 @@ Hint: codex-mini-latest requires an OpenAI Pro ($200/mo) or Max subscription. GP
       content: contentParts.length > 0 ? contentParts : textAccum || ""
     },
     stopReason,
-    usage: { inputTokens, outputTokens }
+    usage: { inputTokens, outputTokens, ...cacheRead > 0 && { cacheRead } }
   };
   yield { type: "done", stopReason };
   return streamResponse;
@@ -1597,6 +1781,23 @@ function toCodexTools(tools) {
     strict: null
   }));
 }
+function extractCodexRequestId(message) {
+  const match = message.match(/request ID ([a-z0-9-]{8,})/i);
+  return match?.[1];
+}
+function parseCodexErrorBody(text) {
+  if (!text) return {};
+  try {
+    const parsed = JSON.parse(text);
+    const error = parsed.error;
+    const message = error?.message ?? parsed.message;
+    const requestId = parsed.request_id ?? error?.request_id ?? (message ? extractCodexRequestId(message) : void 0);
+    return { ...message ? { message } : {}, ...requestId ? { requestId } : {} };
+  } catch {
+    const trimmed = text.trim().slice(0, 240);
+    return trimmed ? { message: trimmed } : {};
+  }
+}
 
 // src/provider-registry.ts
 var ProviderRegistryImpl = class {
@@ -1856,6 +2057,8 @@ export {
   GGAIError,
   ProviderError,
   StreamResult,
+  formatError,
+  formatErrorForDisplay,
   palsuAssistantMessage,
   palsuText,
   palsuThinking,