@prestyj/ai 4.3.164 → 4.3.201

package/dist/index.js

@@ -1,20 +1,164 @@
 // src/errors.ts
 var EZCoderAIError = class extends Error {
+  source;
+  requestId;
+  hint;
   constructor(message, options) {
-    super(message, options);
+    super(message, { cause: options?.cause });
     this.name = "EZCoderAIError";
+    this.source = options?.source ?? "ezcoder";
+    this.requestId = options?.requestId;
+    this.hint = options?.hint;
   }
 };
 var ProviderError = class extends EZCoderAIError {
   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 EZCoderAIError) {
+    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("ezcoder", 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 ezcoder issue \u2014 retry shortly.",
+        ...requestId ? { requestId } : {}
+      };
+    case "auth":
+      return {
+        headline: "Authentication issue.",
+        source,
+        message,
+        guidance: hint ?? "Run `ezcoder 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 "ezcoder":
+      return {
+        headline: "ezcoder hit an unexpected error.",
+        source,
+        message,
+        guidance: hint ?? "This looks like a ezcoder 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 "ezcoder";
+}
+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 \`ezcoder 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 ezcoder 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 ezcoder 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 ezcoder issue.`;
+  }
+  if (statusCode === 502 || lower.includes("bad gateway")) {
+    return `${name} returned a bad gateway. Retry \u2014 this is on their side, not ezcoder.`;
+  }
+  if (statusCode === 503 || lower.includes("service unavailable")) {
+    return `${name} is temporarily unavailable. Retry shortly \u2014 not a ezcoder 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 ezcoder. Retry \u2014 if it keeps happening, check ${status}.` : `This is an error from ${name}, not ezcoder. 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 ezcoder 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 ezcoder. Retry \u2014 if it persists, check ${status}.` : `This is an error from ${name}, not ezcoder. 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" };
@@ -382,8 +542,8 @@ function supportsAdaptiveThinking(model) {
 }
 function toAnthropicThinking(level, maxTokens, model) {
   if (supportsAdaptiveThinking(model)) {
-    let effort = level;
-    if (level === "max" && !model.includes("opus")) {
+    let effort = level === "xhigh" ? "max" : level;
+    if (effort === "max" && !model.includes("opus")) {
       effort = "high";
     }
     return {
@@ -392,7 +552,7 @@ function toAnthropicThinking(level, maxTokens, model) {
       outputConfig: { effort }
     };
   }
-  const effectiveLevel = level === "max" ? "high" : level;
+  const effectiveLevel = level === "xhigh" ? "high" : level;
   const budgetMap = {
     low: Math.max(1024, Math.floor(maxTokens * 0.25)),
     medium: Math.max(2048, Math.floor(maxTokens * 0.5)),
@@ -525,8 +685,8 @@ function toOpenAIToolChoice(choice) {
   if (choice === "required") return "required";
   return { type: "function", function: { name: choice.name } };
 }
-function toOpenAIReasoningEffort(level) {
-  return level === "max" ? "high" : level;
+function toOpenAIReasoningEffort(level, _model) {
+  return level;
 }
 function normalizeAnthropicStopReason(reason) {
   switch (reason) {
@@ -558,6 +718,23 @@ function normalizeOpenAIStopReason(reason) {
 }
 
 // src/providers/anthropic.ts
+function isJsonObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function uniqueToolsByName(tools) {
+  const seen = /* @__PURE__ */ new Set();
+  const unique = [];
+  for (const tool of tools) {
+    if (!tool.name) {
+      unique.push(tool);
+      continue;
+    }
+    if (seen.has(tool.name)) continue;
+    seen.add(tool.name);
+    unique.push(tool);
+  }
+  return unique;
+}
 function createClient(options) {
   const isOAuth = options.apiKey?.startsWith("sk-ant-oat");
   return new Anthropic({
@@ -570,7 +747,10 @@ function createClient(options) {
     maxRetries: 2,
     ...isOAuth ? {
       defaultHeaders: {
-        "user-agent": "claude-cli/2.1.75",
+        // Anthropic's OAuth edge validates the claude-cli version. Callers
+        // (ezcoder) resolve the live version at runtime; the literal here
+        // is the offline fallback for direct gg-ai consumers.
+        "user-agent": options.userAgent ?? "claude-cli/2.1.75 (external, cli)",
         "x-app": "cli"
       }
     } : {}
@@ -584,6 +764,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 ? [
@@ -614,13 +795,28 @@ async function* runStream(options) {
     ...options.temperature != null && !thinking ? { temperature: options.temperature } : {},
     ...options.topP != null ? { top_p: options.topP } : {},
     ...options.stop ? { stop_sequences: options.stop } : {},
-    ...options.tools?.length || options.serverTools?.length || options.webSearch ? {
-      tools: [
-        ...options.tools?.length ? toAnthropicTools(options.tools) : [],
-        ...options.serverTools ?? [],
-        ...options.webSearch ? [{ type: "web_search_20250305", name: "web_search" }] : []
-      ]
-    } : {},
+    ...options.tools?.length || options.serverTools?.length || options.webSearch ? (() => {
+      const reservedServerNames = /* @__PURE__ */ new Set();
+      if (options.webSearch) reservedServerNames.add("web_search");
+      for (const t of options.serverTools ?? []) {
+        const name = t.name;
+        if (name) reservedServerNames.add(name);
+      }
+      const clientTools = options.tools?.length ? toAnthropicTools(
+        uniqueToolsByName(options.tools.filter((t) => !reservedServerNames.has(t.name))),
+        {
+          ...supportsFirstPartyToolExtras && cacheControl ? { cacheControl } : {},
+          ...supportsFirstPartyToolExtras ? { enableFineGrainedToolStreaming: true } : {}
+        }
+      ) : [];
+      return {
+        tools: uniqueToolsByName([
+          ...clientTools,
+          ...options.serverTools ?? [],
+          ...options.webSearch ? [{ type: "web_search_20250305", name: "web_search" }] : []
+        ])
+      };
+    })() : {},
     ...options.toolChoice && options.tools?.length ? { tool_choice: toAnthropicToolChoice(options.toolChoice) } : {},
     ...(() => {
       const contextEdits = [
@@ -697,6 +893,7 @@ async function* runStream(options) {
           if (block.type === "tool_use") {
             accum.toolId = block.id;
             accum.toolName = block.name;
+            accum.input = block.input;
           } else if (block.type === "server_tool_use") {
             accum.toolId = block.id;
             accum.toolName = block.name;
@@ -705,7 +902,11 @@ async function* runStream(options) {
             accum.raw = block;
           }
           blocks.set(idx, accum);
-          yield keepalive;
+          if (block.type === "thinking") {
+            yield { type: "thinking_delta", text: "" };
+          } else {
+            yield keepalive;
+          }
           break;
         }
         case "content_block_delta": {
@@ -748,10 +949,13 @@ async function* runStream(options) {
             });
             yield keepalive;
           } else if (accum.type === "tool_use") {
-            let args = {};
-            try {
-              args = JSON.parse(accum.argsJson);
-            } catch {
+            let args = isJsonObject(accum.input) ? accum.input : {};
+            if (accum.argsJson) {
+              try {
+                const parsed = JSON.parse(accum.argsJson);
+                args = isJsonObject(parsed) ? parsed : {};
+              } catch {
+              }
             }
             const tc = {
               type: "tool_call",
@@ -949,8 +1153,15 @@ function messageToResponse(message) {
 }
 function toError(err) {
   if (err instanceof Anthropic.APIError) {
-    return new ProviderError("anthropic", err.message, {
+    const errorBody = err.error;
+    const nestedError = errorBody?.error;
+    const requestId = err.requestID ?? err.request_id ?? (typeof errorBody?.request_id === "string" ? errorBody.request_id : void 0) ?? (typeof nestedError?.request_id === "string" ? nestedError.request_id : void 0) ?? void 0;
+    const bodyMessage = typeof nestedError?.message === "string" ? nestedError.message : typeof errorBody?.message === "string" ? errorBody.message : void 0;
+    const bodyType = typeof nestedError?.type === "string" ? nestedError.type : typeof errorBody?.type === "string" ? errorBody.type : typeof err.type === "string" ? err.type : void 0;
+    const message = bodyType && bodyMessage ? `${bodyType}: ${bodyMessage}` : bodyMessage ?? err.message;
+    return new ProviderError("anthropic", message, {
       statusCode: err.status,
+      ...requestId ? { requestId } : {},
       cause: err
     });
   }
@@ -962,6 +1173,38 @@ function toError(err) {
 
 // src/providers/openai.ts
 import OpenAI from "openai";
+
+// src/providers/prompt-cache-key.ts
+var MAX_PROMPT_CACHE_KEY_LENGTH = 64;
+function normalizePromptCacheKey(key) {
+  if (key.length <= MAX_PROMPT_CACHE_KEY_LENGTH) return key;
+  const hash = fnv1aHash(key);
+  const prefixLength = MAX_PROMPT_CACHE_KEY_LENGTH - hash.length - 1;
+  return `${key.slice(0, prefixLength)}:${hash}`;
+}
+function fnv1aHash(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index++) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+// src/providers/openai.ts
+function isJsonObject2(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function parseToolArguments(argsJson) {
+  if (!argsJson) return {};
+  try {
+    const parsed = JSON.parse(argsJson);
+    const unwrapped = typeof parsed === "string" ? JSON.parse(parsed) : parsed;
+    return isJsonObject2(unwrapped) ? unwrapped : {};
+  } catch {
+    return {};
+  }
+}
 function createClient2(options) {
   return new OpenAI({
     apiKey: options.apiKey,
@@ -993,19 +1236,22 @@ async function* runStream2(options) {
     ...effectiveTemp != null && !options.thinking ? { temperature: effectiveTemp } : {},
     ...options.topP != null ? { top_p: options.topP } : {},
     ...options.stop ? { stop: options.stop } : {},
-    ...options.thinking && !usesThinkingParam ? { reasoning_effort: toOpenAIReasoningEffort(options.thinking) } : {},
+    ...options.thinking && !usesThinkingParam ? { reasoning_effort: toOpenAIReasoningEffort(options.thinking, options.model) } : {},
     ...options.tools?.length ? { tools: toOpenAITools(options.tools) } : {},
     ...options.toolChoice && options.tools?.length ? { tool_choice: toOpenAIToolChoice(options.toolChoice) } : {},
     ...useStreaming ? { stream_options: { include_usage: true } } : {}
   };
   if (options.provider === "openai" || options.provider === "moonshot") {
     const paramsAny = params;
-    paramsAny.prompt_cache_key = "ezcoder";
+    paramsAny.prompt_cache_key = normalizePromptCacheKey(options.promptCacheKey ?? "ezcoder");
     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" };
@@ -1063,6 +1309,9 @@ async function* runStream2(options) {
       if (!cacheRead && typeof usageAny.cached_tokens === "number" && usageAny.cached_tokens > 0) {
         cacheRead = usageAny.cached_tokens;
       }
+      if (!cacheRead && typeof usageAny.prompt_cache_hit_tokens === "number" && usageAny.prompt_cache_hit_tokens > 0) {
+        cacheRead = usageAny.prompt_cache_hit_tokens;
+      }
       inputTokens = chunk.usage.prompt_tokens - cacheRead;
     }
     if (!choice) continue;
@@ -1113,11 +1362,7 @@ async function* runStream2(options) {
     contentParts.push({ type: "text", text: textAccum });
   }
   for (const [, tc] of toolCallAccum) {
-    let args = {};
-    try {
-      args = JSON.parse(tc.argsJson);
-    } catch {
-    }
+    const args = parseToolArguments(tc.argsJson);
     const toolCall = {
       type: "tool_call",
       id: tc.id,
@@ -1170,11 +1415,7 @@ function* synthesizeEventsFromCompletion(completion, thinkingEnabled) {
           argsJson
         };
       }
-      let args = {};
-      try {
-        args = JSON.parse(argsJson);
-      } catch {
-      }
+      const args = parseToolArguments(argsJson);
       yield {
         type: "toolcall_done",
         id: tc.id,
@@ -1202,11 +1443,7 @@ function completionToResponse(completion) {
     const toolCalls = msg.tool_calls;
     if (toolCalls) {
       for (const tc of toolCalls) {
-        let args = {};
-        try {
-          args = JSON.parse(tc.function?.arguments ?? "{}");
-        } catch {
-        }
+        const args = parseToolArguments(tc.function?.arguments ?? "");
         const toolCall = {
           type: "tool_call",
           id: tc.id,
@@ -1228,6 +1465,9 @@ function completionToResponse(completion) {
     if (!cacheRead && typeof usageAny.cached_tokens === "number" && usageAny.cached_tokens > 0) {
       cacheRead = usageAny.cached_tokens;
     }
+    if (!cacheRead && typeof usageAny.prompt_cache_hit_tokens === "number" && usageAny.prompt_cache_hit_tokens > 0) {
+      cacheRead = usageAny.prompt_cache_hit_tokens;
+    }
     inputTokens = completion.usage.prompt_tokens - cacheRead;
   }
   const stopReason = normalizeOpenAIStopReason(choice?.finish_reason ?? null);
@@ -1242,19 +1482,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
     });
   }
@@ -1266,7 +1506,34 @@ function toError2(err, provider = "openai") {
 
 // src/providers/openai-codex.ts
 import os from "os";
+
+// src/utils/diag.ts
+var _diagFn = null;
+function setProviderDiagnostic(fn) {
+  _diagFn = fn;
+}
+function providerDiag(phase, data) {
+  _diagFn?.(phase, data);
+}
+
+// src/providers/openai-codex.ts
 var DEFAULT_BASE_URL = "https://chatgpt.com/backend-api";
+function isJsonObject3(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+function parseToolArguments2(argsJson) {
+  if (!argsJson) return {};
+  try {
+    const parsed = JSON.parse(argsJson);
+    const unwrapped = typeof parsed === "string" ? JSON.parse(parsed) : parsed;
+    return isJsonObject3(unwrapped) ? unwrapped : {};
+  } catch {
+    return {};
+  }
+}
+function outputTextKey(itemId, contentIndex) {
+  return `${itemId ?? ""}:${contentIndex ?? 0}`;
+}
 function streamOpenAICodex(options) {
   return new StreamResult(runStream3(options));
 }
@@ -1288,15 +1555,17 @@ async function* runStream3(options) {
   if (options.tools?.length) {
     body.tools = toCodexTools(options.tools);
   }
+  body.prompt_cache_key = normalizePromptCacheKey(options.promptCacheKey ?? "ezcoder");
+  if (options.cacheRetention === "long") {
+    body.prompt_cache_retention = "24h";
+  }
   if (options.temperature != null && !options.thinking) {
     body.temperature = options.temperature;
   }
-  if (options.thinking) {
-    body.reasoning = {
-      effort: options.thinking,
-      summary: "auto"
-    };
-  }
+  body.reasoning = {
+    effort: options.thinking ?? "none",
+    summary: "auto"
+  };
   const headers = {
     "Content-Type": "application/json",
     Accept: "text/event-stream",
@@ -1308,6 +1577,11 @@ async function* runStream3(options) {
   if (options.accountId) {
     headers["chatgpt-account-id"] = options.accountId;
   }
+  const cacheScopeId = body.prompt_cache_key;
+  if (cacheScopeId) {
+    headers["session_id"] = cacheScopeId;
+    headers["x-client-request-id"] = cacheScopeId;
+  }
   const response = await fetch(url, {
     method: "POST",
     headers,
@@ -1316,19 +1590,23 @@ 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") ?? response.headers.get("x-oai-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.`;
+      if (options.model === "gpt-5.5-pro") {
+        hint = "Use gpt-5.5 instead. OpenAI's Codex model catalog does not list gpt-5.5-pro.";
+      } else {
+        hint = "This model is not available through Codex for the authenticated account. Run /model and choose a model listed for OpenAI Codex, or check your Codex model picker/usage limits.";
+      }
+    } else if (response.status === 404 && text.includes("does not exist")) {
+      hint = "This model is not in the current OpenAI Codex catalog for this account. Try gpt-5.5, gpt-5.4, gpt-5.4-mini, or gpt-5.3-codex.";
     }
     throw new ProviderError("openai", message, {
-      statusCode: response.status
+      statusCode: response.status,
+      ...requestId ? { requestId } : {},
+      ...hint ? { hint } : {}
     });
   }
   if (!response.body) {
@@ -1337,27 +1615,84 @@ Hint: codex-mini-latest requires an OpenAI Pro ($200/mo) or Max subscription. GP
   const contentParts = [];
   let textAccum = "";
   const toolCalls = /* @__PURE__ */ new Map();
+  const outputItemTypes = /* @__PURE__ */ new Map();
+  const outputTextByPart = /* @__PURE__ */ new Map();
   let inputTokens = 0;
   let outputTokens = 0;
+  let cacheRead = 0;
+  const diagStart = Date.now();
+  const diagSeen = /* @__PURE__ */ new Set();
   for await (const event of parseSSE(response.body)) {
     const type = event.type;
     if (!type) continue;
+    if (!diagSeen.has(type)) {
+      diagSeen.add(type);
+      providerDiag("codex_event_first", { type, sinceStartMs: Date.now() - diagStart });
+    }
     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;
-      textAccum += delta;
-      yield { type: "text_delta", text: delta };
+      const itemId = event.item_id;
+      const contentIndex = event.content_index;
+      const key = outputTextKey(itemId, contentIndex);
+      outputTextByPart.set(key, `${outputTextByPart.get(key) ?? ""}${delta}`);
+      if (itemId && outputItemTypes.get(itemId) === "reasoning") {
+        if (options.thinking) yield { type: "thinking_delta", text: delta };
+      } else {
+        textAccum += delta;
+        yield { type: "text_delta", text: delta };
+      }
+    }
+    if (type === "response.output_text.done") {
+      const fullText = event.text;
+      if (fullText) {
+        const itemId = event.item_id;
+        const contentIndex = event.content_index;
+        const key = outputTextKey(itemId, contentIndex);
+        const streamedText = outputTextByPart.get(key) ?? "";
+        const missingText = streamedText ? fullText.slice(streamedText.length) : fullText;
+        outputTextByPart.set(key, fullText);
+        if (missingText && fullText.startsWith(streamedText)) {
+          if (itemId && outputItemTypes.get(itemId) === "reasoning") {
+            if (options.thinking) yield { type: "thinking_delta", text: missingText };
+          } else {
+            textAccum += missingText;
+            yield { type: "text_delta", text: missingText };
+          }
+        }
+      }
     }
-    if (type === "response.reasoning_summary_text.delta") {
+    if (type === "response.reasoning_summary_text.delta" || type === "response.reasoning_summary.delta" || type === "response.reasoning_text.delta" || type === "response.reasoning.delta") {
       const delta = event.delta;
-      yield { type: "thinking_delta", text: delta };
+      if (options.thinking) yield { type: "thinking_delta", text: delta };
+    }
+    if (type === "response.output_item.added") {
+      const item = event.item;
+      const itemId = item?.id;
+      const itemType = item?.type;
+      if (itemId && itemType) {
+        outputItemTypes.set(itemId, itemType);
+      }
+      if (itemType === "reasoning" && options.thinking) {
+        yield { type: "thinking_delta", text: "" };
+      }
     }
     if (type === "response.output_item.added") {
       const item = event.item;
@@ -1403,11 +1738,7 @@ Hint: codex-mini-latest requires an OpenAI Pro ($200/mo) or Max subscription. GP
         const id = `${callId}|${itemId}`;
         const tc = toolCalls.get(id);
         if (tc) {
-          let args = {};
-          try {
-            args = JSON.parse(tc.argsJson);
-          } catch {
-          }
+          const args = parseToolArguments2(tc.argsJson);
           yield {
             type: "toolcall_done",
             id: tc.id,
@@ -1421,7 +1752,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;
       }
     }
@@ -1430,11 +1762,7 @@ Hint: codex-mini-latest requires an OpenAI Pro ($200/mo) or Max subscription. GP
     contentParts.push({ type: "text", text: textAccum });
   }
   for (const [, tc] of toolCalls) {
-    let args = {};
-    try {
-      args = JSON.parse(tc.argsJson);
-    } catch {
-    }
+    const args = parseToolArguments2(tc.argsJson);
     const toolCall = {
       type: "tool_call",
       id: tc.id,
@@ -1451,7 +1779,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;
@@ -1593,6 +1921,24 @@ 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 detail = parsed.detail;
+    const message = error?.message ?? parsed.message ?? (typeof detail === "string" ? detail : void 0);
+    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 {
@@ -1852,12 +2198,15 @@ export {
   EventStream,
   ProviderError,
   StreamResult,
+  formatError,
+  formatErrorForDisplay,
   palsuAssistantMessage,
   palsuText,
   palsuThinking,
   palsuToolCall,
   providerRegistry,
   registerPalsuProvider,
+  setProviderDiagnostic,
   stream
 };
 //# sourceMappingURL=index.js.map