@prestyj/ai 4.3.164 → 4.3.200

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 type Provider = "anthropic" | "xiaomi" | "openai" | "glm" | "moonshot" | "minimax" | "deepseek" | "openrouter" | "palsu";
-type ThinkingLevel = "low" | "medium" | "high" | "max";
+type ThinkingLevel = "low" | "medium" | "high" | "xhigh";
 type CacheRetention = "none" | "short" | "long";
 interface TextContent {
     type: "text";
@@ -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:
@@ -185,6 +189,12 @@ interface StreamOptions {
      *  stalls — broken SSE connections (transient CDN / proxy issues) often
      *  recover when the same request is issued over a plain HTTP request/response. */
     streaming?: boolean;
+    /** Override the User-Agent sent with OAuth-authenticated Anthropic requests.
+     *  Anthropic's OAuth edge rejects requests whose claude-cli version lags too
+     *  far behind the real Claude Code release; callers that track the live
+     *  version should pass it here. Ignored for non-Anthropic providers and for
+     *  Anthropic requests using a regular API key. */
+    userAgent?: string;
 }
 
 /**
@@ -292,17 +302,84 @@ 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
+ * ezcoder 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 ezcoder. Retry — if it persists, check status.openai.com.
+ *
+ *   ✗ ezcoder hit an unexpected error.
+ *     Cannot read property 'foo' of undefined
+ *     → This is a ezcoder bug — please report it.
+ */
+type ErrorSource = "provider" | "ezcoder" | "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 EZCoderAIError 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 EZCoderAIError {
     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;
+
+/**
+ * Provider-level diagnostic hook. Mirrors the pattern used by gg-agent's
+ * setStreamDiagnostic — the host app wires a callback (typically writing to
+ * a debug log) and providers call `providerDiag(...)` to record interesting
+ * lifecycle events (e.g. raw SSE event types and timings).
+ */
+type ProviderDiagnosticFn = (phase: string, data?: Record<string, unknown>) => void;
+/** Register a diagnostic callback for provider-level tracing. */
+declare function setProviderDiagnostic(fn: ProviderDiagnosticFn | null): void;
 
 interface PalsuProviderState {
     callCount: number;
@@ -373,4 +450,4 @@ interface PalsuProviderConfig {
  */
 declare function registerPalsuProvider(config?: PalsuProviderConfig): PalsuProviderHandle;
 
-export { type AssistantMessage, type CacheRetention, type ContentPart, type DoneEvent, EZCoderAIError, type ErrorEvent, EventStream, 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, EZCoderAIError, type ErrorEvent, type ErrorSource, EventStream, type FormattedError, type ImageContent, type Message, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type Provider, type ProviderDiagnosticFn, 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, setProviderDiagnostic, stream };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 
 type Provider = "anthropic" | "xiaomi" | "openai" | "glm" | "moonshot" | "minimax" | "deepseek" | "openrouter" | "palsu";
-type ThinkingLevel = "low" | "medium" | "high" | "max";
+type ThinkingLevel = "low" | "medium" | "high" | "xhigh";
 type CacheRetention = "none" | "short" | "long";
 interface TextContent {
     type: "text";
@@ -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:
@@ -185,6 +189,12 @@ interface StreamOptions {
      *  stalls — broken SSE connections (transient CDN / proxy issues) often
      *  recover when the same request is issued over a plain HTTP request/response. */
     streaming?: boolean;
+    /** Override the User-Agent sent with OAuth-authenticated Anthropic requests.
+     *  Anthropic's OAuth edge rejects requests whose claude-cli version lags too
+     *  far behind the real Claude Code release; callers that track the live
+     *  version should pass it here. Ignored for non-Anthropic providers and for
+     *  Anthropic requests using a regular API key. */
+    userAgent?: string;
 }
 
 /**
@@ -292,17 +302,84 @@ 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
+ * ezcoder 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 ezcoder. Retry — if it persists, check status.openai.com.
+ *
+ *   ✗ ezcoder hit an unexpected error.
+ *     Cannot read property 'foo' of undefined
+ *     → This is a ezcoder bug — please report it.
+ */
+type ErrorSource = "provider" | "ezcoder" | "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 EZCoderAIError 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 EZCoderAIError {
     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;
+
+/**
+ * Provider-level diagnostic hook. Mirrors the pattern used by gg-agent's
+ * setStreamDiagnostic — the host app wires a callback (typically writing to
+ * a debug log) and providers call `providerDiag(...)` to record interesting
+ * lifecycle events (e.g. raw SSE event types and timings).
+ */
+type ProviderDiagnosticFn = (phase: string, data?: Record<string, unknown>) => void;
+/** Register a diagnostic callback for provider-level tracing. */
+declare function setProviderDiagnostic(fn: ProviderDiagnosticFn | null): void;
 
 interface PalsuProviderState {
     callCount: number;
@@ -373,4 +450,4 @@ interface PalsuProviderConfig {
  */
 declare function registerPalsuProvider(config?: PalsuProviderConfig): PalsuProviderHandle;
 
-export { type AssistantMessage, type CacheRetention, type ContentPart, type DoneEvent, EZCoderAIError, type ErrorEvent, EventStream, 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, EZCoderAIError, type ErrorEvent, type ErrorSource, EventStream, type FormattedError, type ImageContent, type Message, type PalsuModelConfig, type PalsuModelHandle, type PalsuProviderConfig, type PalsuProviderHandle, type PalsuProviderState, type PalsuResponse, type PalsuResponseFactory, type Provider, type ProviderDiagnosticFn, 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, setProviderDiagnostic, stream };