@core-ai/core-ai 0.16.0 → 0.18.0

package/dist/index.d.ts

@@ -110,15 +110,17 @@ type ToolChoice = 'auto' | 'none' | 'required' | {
     type: 'tool';
     toolName: string;
 };
+type ToolChoiceMode = 'auto' | 'none' | 'required' | 'tool';
 type ModelCapabilities = {
     reasoning: {
-        supported: boolean;
+        mode: 'unsupported' | 'optional' | 'always-on';
         supportedEfforts: readonly ReasoningEffort[];
         /**
-         * When true, sampling parameters such as `temperature` and `topP`
-         * must not be set alongside `reasoning`.
+         * Whether reasoning changes which sampling parameters or values the
+         * provider accepts.
          */
         restrictsSamplingParams: boolean;
+        supportedToolChoices: readonly ToolChoiceMode[];
     };
 };
 type ChatModel = {
@@ -377,9 +379,50 @@ declare class AbortedError extends CoreAIError {
 declare class StreamAbortedError extends AbortedError {
     constructor(cause?: unknown, provider?: string);
 }
+type ProviderErrorOptions = {
+    statusCode?: number;
+    cause?: unknown;
+};
 declare class ProviderError extends CoreAIError {
     readonly statusCode?: number;
-    constructor(message: string, provider: string, statusCode?: number, cause?: unknown);
+    /**
+     * @param message Human-readable error message (may include provider text).
+     * @param provider Provider id (e.g. `'openai'`, `'anthropic'`).
+     * @param options Optional HTTP status and underlying cause.
+     */
+    constructor(message: string, provider: string, options?: ProviderErrorOptions);
+}
+/**
+ * Base class for transient provider failures that are safe to retry
+ * (rate limits, overload, temporary unavailability).
+ * Discriminate with `instanceof RetryableProviderError`.
+ */
+declare class RetryableProviderError extends ProviderError {
+    constructor(message: string, provider: string, options?: ProviderErrorOptions);
+}
+type ContextLengthExceededErrorOptions = ProviderErrorOptions & {
+    maxTokens?: number;
+    actualTokens?: number;
+};
+declare class ContextLengthExceededError extends ProviderError {
+    readonly maxTokens?: number;
+    readonly actualTokens?: number;
+    constructor(message: string, provider: string, options?: ContextLengthExceededErrorOptions);
+}
+type RateLimitErrorOptions = ProviderErrorOptions & {
+    retryAfterSeconds?: number;
+};
+declare class RateLimitError extends RetryableProviderError {
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, provider: string, options?: RateLimitErrorOptions);
+}
+type ModelOverloadedErrorOptions = ProviderErrorOptions;
+declare class ModelOverloadedError extends RetryableProviderError {
+    constructor(message: string, provider: string, options?: ModelOverloadedErrorOptions);
+}
+type ServiceUnavailableErrorOptions = ProviderErrorOptions;
+declare class ServiceUnavailableError extends RetryableProviderError {
+    constructor(message: string, provider: string, options?: ServiceUnavailableErrorOptions);
 }
 type StructuredOutputErrorOptions = {
     statusCode?: number;
@@ -402,6 +445,32 @@ declare class StructuredOutputValidationError extends StructuredOutputError {
     constructor(message: string, provider: string, issues: string[], options?: StructuredOutputErrorOptions);
 }
 
+/**
+ * Shared helpers for provider error wrappers.
+ * Providers decide which error subclass to throw; these utilities only
+ * extract common SDK shapes and thin HTTP status conventions.
+ * Provider-specific message heuristics stay in each wrap*Error.
+ */
+declare function isRateLimitStatus(statusCode: number | undefined): boolean;
+declare function isTransientUnavailableStatus(statusCode: number | undefined): boolean;
+declare function getErrorMessage(error: unknown): string;
+declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+declare function getString(source: Record<string, unknown> | undefined, key: string): string | undefined;
+/**
+ * Reads a finite numeric HTTP status from common SDK error shapes
+ * (`status` and/or `statusCode`).
+ */
+declare function getHttpStatusCode(error: unknown, keys?: readonly ('status' | 'statusCode')[]): number | undefined;
+declare function isAbortErrorByName(error: unknown): boolean;
+/**
+ * Parses retry delay from a `Headers` instance or plain header map.
+ * Prefers Azure `retry-after-ms` (ceil ms → seconds), then `Retry-After`
+ * as integer seconds or HTTP-date.
+ */
+declare function parseRetryAfterSeconds(headers: Headers | Record<string, string> | undefined): number | undefined;
+/** Reads `Retry-After` from common SDK error shapes that expose `headers`. */
+declare function getRetryAfterSecondsFromError(error: unknown): number | undefined;
+
 declare function defineTool(options: ToolDefinition): ToolDefinition;
 
 /**
@@ -414,6 +483,12 @@ declare function stripModelDateSuffix(modelId: string): string;
 
 declare function clampReasoningEffort(effort: ReasoningEffort, supportedEfforts: readonly ReasoningEffort[]): ReasoningEffort;
 
+declare const UNKNOWN_MODEL: unique symbol;
+type ModelCapabilitiesRegistry<TCapabilities extends ModelCapabilities = ModelCapabilities> = Record<string, TCapabilities> & {
+    [UNKNOWN_MODEL]?: TCapabilities;
+};
+declare function getRegisteredModelCapabilities<TCapabilities extends ModelCapabilities>(registry: ModelCapabilitiesRegistry<TCapabilities> | undefined, modelId: string): TCapabilities | undefined;
+
 declare function asObject(value: unknown): Record<string, unknown>;
 declare function safeParseJsonObject(json: string): Record<string, unknown>;
 
@@ -477,4 +552,4 @@ type GenerateImageParams = ImageGenerateOptions & {
 };
 declare function generateImage(params: GenerateImageParams): Promise<ImageGenerateResult>;
 
-export { AbortedError, type AssistantContentPart, type AssistantMessage, type AssistantTextPart, type BaseGenerateOptions, type ChatInputTokenDetails, type ChatModel, type ChatModelMiddleware, type ChatOutputTokenDetails, type ChatStream, type ChatUsage, CoreAIError, type EmbedOptions, type EmbedProviderOptions, type EmbedResult, type EmbeddingModel, type EmbeddingModelMiddleware, type EmbeddingUsage, type FilePart, type FinishReason, type GenerateObjectOptions, type GenerateObjectResult, type GenerateOptions, type GenerateProviderOptions, type GenerateResult, type GeneratedImage, type ImageGenerateOptions, type ImageGenerateResult, type ImageModel, type ImageModelMiddleware, type ImagePart, type ImageProviderOptions, type Message, type ModelCapabilities, type ObjectStream, type ObjectStreamEvent, ProviderError, type ReasoningConfig, type ReasoningEffort, type ReasoningPart, StreamAbortedError, type StreamEvent, type StreamObjectOptions, StructuredOutputError, StructuredOutputNoObjectGeneratedError, StructuredOutputParseError, StructuredOutputValidationError, type SystemMessage, type TextPart, type ToolCall, type ToolCallPart, type ToolChoice, type ToolDefinition, type ToolResultMessage, type ToolSet, type UserContentPart, type UserMessage, ValidationError, asObject, assistantMessage, clampReasoningEffort, createChatStream, createObjectStream, defineTool, embed, generate, generateImage, generateObject, getProviderMetadata, resultToMessage, safeParseJsonObject, stream, streamObject, stripModelDateSuffix, wrapChatModel, wrapEmbeddingModel, wrapImageModel, zodSchemaToJsonSchema };
+export { AbortedError, type AssistantContentPart, type AssistantMessage, type AssistantTextPart, type BaseGenerateOptions, type ChatInputTokenDetails, type ChatModel, type ChatModelMiddleware, type ChatOutputTokenDetails, type ChatStream, type ChatUsage, ContextLengthExceededError, type ContextLengthExceededErrorOptions, CoreAIError, type EmbedOptions, type EmbedProviderOptions, type EmbedResult, type EmbeddingModel, type EmbeddingModelMiddleware, type EmbeddingUsage, type FilePart, type FinishReason, type GenerateObjectOptions, type GenerateObjectResult, type GenerateOptions, type GenerateProviderOptions, type GenerateResult, type GeneratedImage, type ImageGenerateOptions, type ImageGenerateResult, type ImageModel, type ImageModelMiddleware, type ImagePart, type ImageProviderOptions, type Message, type ModelCapabilities, type ModelCapabilitiesRegistry, ModelOverloadedError, type ModelOverloadedErrorOptions, type ObjectStream, type ObjectStreamEvent, ProviderError, type ProviderErrorOptions, RateLimitError, type RateLimitErrorOptions, type ReasoningConfig, type ReasoningEffort, type ReasoningPart, RetryableProviderError, ServiceUnavailableError, type ServiceUnavailableErrorOptions, StreamAbortedError, type StreamEvent, type StreamObjectOptions, StructuredOutputError, StructuredOutputNoObjectGeneratedError, StructuredOutputParseError, StructuredOutputValidationError, type SystemMessage, type TextPart, type ToolCall, type ToolCallPart, type ToolChoice, type ToolDefinition, type ToolResultMessage, type ToolSet, UNKNOWN_MODEL, type UserContentPart, type UserMessage, ValidationError, asObject, asRecord, assistantMessage, clampReasoningEffort, createChatStream, createObjectStream, defineTool, embed, generate, generateImage, generateObject, getErrorMessage, getHttpStatusCode, getProviderMetadata, getRegisteredModelCapabilities, getRetryAfterSecondsFromError, getString, isAbortErrorByName, isRateLimitStatus, isTransientUnavailableStatus, parseRetryAfterSeconds, resultToMessage, safeParseJsonObject, stream, streamObject, stripModelDateSuffix, wrapChatModel, wrapEmbeddingModel, wrapImageModel, zodSchemaToJsonSchema };

package/dist/index.js

@@ -30,10 +30,57 @@ var StreamAbortedError = class extends AbortedError {
 };
 var ProviderError = class extends CoreAIError {
   statusCode;
-  constructor(message, provider, statusCode, cause) {
-    super(message, cause, provider);
+  /**
+   * @param message Human-readable error message (may include provider text).
+   * @param provider Provider id (e.g. `'openai'`, `'anthropic'`).
+   * @param options Optional HTTP status and underlying cause.
+   */
+  constructor(message, provider, options = {}) {
+    super(message, options.cause, provider);
     this.name = "ProviderError";
-    this.statusCode = statusCode;
+    this.statusCode = options.statusCode;
+  }
+};
+var RetryableProviderError = class extends ProviderError {
+  constructor(message, provider, options = {}) {
+    super(message, provider, options);
+    this.name = "RetryableProviderError";
+  }
+};
+var ContextLengthExceededError = class extends ProviderError {
+  maxTokens;
+  actualTokens;
+  constructor(message, provider, options = {}) {
+    super(message, provider, {
+      statusCode: options.statusCode,
+      cause: options.cause
+    });
+    this.name = "ContextLengthExceededError";
+    this.maxTokens = options.maxTokens;
+    this.actualTokens = options.actualTokens;
+  }
+};
+var RateLimitError = class extends RetryableProviderError {
+  retryAfterSeconds;
+  constructor(message, provider, options = {}) {
+    super(message, provider, {
+      statusCode: options.statusCode ?? 429,
+      cause: options.cause
+    });
+    this.name = "RateLimitError";
+    this.retryAfterSeconds = options.retryAfterSeconds;
+  }
+};
+var ModelOverloadedError = class extends RetryableProviderError {
+  constructor(message, provider, options = {}) {
+    super(message, provider, options);
+    this.name = "ModelOverloadedError";
+  }
+};
+var ServiceUnavailableError = class extends RetryableProviderError {
+  constructor(message, provider, options = {}) {
+    super(message, provider, options);
+    this.name = "ServiceUnavailableError";
   }
 };
 var StructuredOutputError = class extends CoreAIError {
@@ -67,6 +114,107 @@ var StructuredOutputValidationError = class extends StructuredOutputError {
   }
 };
 
+// src/provider-error-utils.ts
+var TRANSIENT_UNAVAILABLE_STATUS_CODES = /* @__PURE__ */ new Set([500, 502, 503, 504]);
+function isRateLimitStatus(statusCode) {
+  return statusCode === 429;
+}
+function isTransientUnavailableStatus(statusCode) {
+  return statusCode !== void 0 && TRANSIENT_UNAVAILABLE_STATUS_CODES.has(statusCode);
+}
+function getErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  const record = asRecord(error);
+  const message = getString(record, "message");
+  if (message) {
+    return message;
+  }
+  return String(error);
+}
+function asRecord(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  return void 0;
+}
+function getString(source, key) {
+  if (!source) {
+    return void 0;
+  }
+  const value = source[key];
+  return typeof value === "string" ? value : void 0;
+}
+function getHttpStatusCode(error, keys = ["status", "statusCode"]) {
+  const record = asRecord(error);
+  if (!record) {
+    return void 0;
+  }
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function isAbortErrorByName(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
+function parseRetryAfterSeconds(headers) {
+  if (!headers) {
+    return void 0;
+  }
+  const retryAfterMs = getHeaderValue(headers, "retry-after-ms");
+  if (retryAfterMs !== void 0) {
+    const ms = Number(retryAfterMs);
+    if (Number.isFinite(ms) && ms >= 0) {
+      return Math.ceil(ms / 1e3);
+    }
+  }
+  const retryAfter = getHeaderValue(headers, "retry-after");
+  if (retryAfter === void 0) {
+    return void 0;
+  }
+  const asSeconds = Number(retryAfter);
+  if (Number.isFinite(asSeconds) && /^\d+$/.test(retryAfter.trim())) {
+    return asSeconds;
+  }
+  const when = Date.parse(retryAfter);
+  if (!Number.isFinite(when)) {
+    return void 0;
+  }
+  const seconds = Math.ceil((when - Date.now()) / 1e3);
+  return seconds >= 0 ? seconds : void 0;
+}
+function getHeaderValue(headers, name) {
+  if (typeof headers.get === "function") {
+    return headers.get(name) ?? void 0;
+  }
+  const record = headers;
+  const direct = record[name];
+  if (typeof direct === "string") {
+    return direct;
+  }
+  const lower = name.toLowerCase();
+  for (const [key, value] of Object.entries(record)) {
+    if (key.toLowerCase() === lower && typeof value === "string") {
+      return value;
+    }
+  }
+  return void 0;
+}
+function getRetryAfterSecondsFromError(error) {
+  const record = asRecord(error);
+  if (!record?.headers || typeof record.headers !== "object") {
+    return void 0;
+  }
+  return parseRetryAfterSeconds(
+    record.headers
+  );
+}
+
 // src/tool.ts
 function defineTool(options) {
   return options;
@@ -115,6 +263,15 @@ function clampReasoningEffort(effort, supportedEfforts) {
   return best;
 }
 
+// src/model-capabilities-registry.ts
+var UNKNOWN_MODEL = /* @__PURE__ */ Symbol("unknown-model");
+function getRegisteredModelCapabilities(registry, modelId) {
+  if (!registry) {
+    return void 0;
+  }
+  return registry[modelId] ?? registry[stripModelDateSuffix(modelId)] ?? registry[UNKNOWN_MODEL];
+}
+
 // src/provider-utils.ts
 function asObject(value) {
   if (value && typeof value === "object" && !Array.isArray(value)) {
@@ -730,15 +887,22 @@ async function generateImage(params) {
 }
 export {
   AbortedError,
+  ContextLengthExceededError,
   CoreAIError,
+  ModelOverloadedError,
   ProviderError,
+  RateLimitError,
+  RetryableProviderError,
+  ServiceUnavailableError,
   StreamAbortedError,
   StructuredOutputError,
   StructuredOutputNoObjectGeneratedError,
   StructuredOutputParseError,
   StructuredOutputValidationError,
+  UNKNOWN_MODEL,
   ValidationError,
   asObject,
+  asRecord,
   assistantMessage,
   clampReasoningEffort,
   createChatStream,
@@ -748,7 +912,16 @@ export {
   generate,
   generateImage,
   generateObject,
+  getErrorMessage,
+  getHttpStatusCode,
   getProviderMetadata,
+  getRegisteredModelCapabilities,
+  getRetryAfterSecondsFromError,
+  getString,
+  isAbortErrorByName,
+  isRateLimitStatus,
+  isTransientUnavailableStatus,
+  parseRetryAfterSeconds,
   resultToMessage,
   safeParseJsonObject,
   stream,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@core-ai/core-ai",
-    "version": "0.16.0",
+    "version": "0.18.0",
     "description": "Type-safe LLM abstraction layer over native provider SDKs",
     "license": "MIT",
     "author": "Omnifact (https://omnifact.ai)",