@framers/agentos 0.1.0

package/dist/core/llm/providers/IProvider.d.ts

@@ -0,0 +1,327 @@
+/**
+ * @fileoverview Core provider contract and shared types for integrating Large Language / Multimodal Model services
+ * into AgentOS. Implementations wrap concrete vendor SDKs or HTTP APIs (OpenAI, Anthropic, Ollama, OpenRouter, etc.)
+ * and normalize their capabilities into a consistent surface area used by higher‑level orchestration layers
+ * (PromptEngine, GMIManager, Utility AI components).
+ *
+ * Design Goals:
+ * 1. Capability Normalization – Chat vs legacy completion, tool/function calling, streaming deltas, embeddings.
+ * 2. Deterministic Streaming Semantics – Every streamed chunk is a full `ModelCompletionResponse` fragment with:
+ *    - optional `responseTextDelta` (string diff)
+ *    - optional `toolCallsDeltas[]` capturing incremental tool argument assembly
+ *    - `isFinal` flag to indicate terminal chunk and stable usage metrics.
+ * 3. Introspection – Lightweight model catalog (`listAvailableModels`, `getModelInfo`) enabling routing & cost decisions.
+ * 4. Resilience & Diagnostics – Uniform error envelope attached to `ModelCompletionResponse.error` for both
+ *    streaming and non‑streaming calls so upstream layers can surface actionable messages.
+ * 5. Strict Initialization Lifecycle – `initialize()` must succeed before any other mutating call.
+ *
+ * Error Handling Philosophy:
+ * - Provider implementations SHOULD translate vendor‑specific errors into a stable structure:
+ *   { message, type?, code?, details? }.
+ * - Transient failures (network timeouts, rate limit backoffs) MAY be surfaced inline; upstream retry policies live above.
+ * - Streaming calls MUST emit a terminal chunk with `isFinal: true` even on error (with `error` populated) so consumers
+ *   can perform consistent teardown.
+ *
+ * Concurrency & Cancellation:
+ * - Implementations MAY support externally triggered abort via custom option (e.g. `customModelParams.abortSignal`).
+ * - If supported, aborted streams MUST still resolve the generator cleanly (no thrown error) after emitting a final
+ *   chunk with `isFinal: true` and an `error` describing the cancellation reason.
+ *
+ * Token Usage & Cost:
+ * - `usage.totalTokens` MUST be present on final responses (streaming or non‑streaming).
+ * - Interim streaming chunks SHOULD omit usage or provide partials; callers should treat usage as unstable until final.
+ * - `costUSD` is optional; if provided should reflect estimated or actual vendor pricing for the call.
+ *
+ * @module backend/agentos/core/llm/providers/IProvider
+ */
+/**
+ * Represents a part of a multimodal message content.
+ */
+export type MessageContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'low' | 'high' | 'auto';
+    };
+} | {
+    type: 'tool_result';
+    tool_use_id: string;
+    content?: string | Array<Record<string, any>>;
+    is_error?: boolean;
+} | {
+    type: string;
+    [key: string]: any;
+};
+/**
+ * Generic type for message content, which can be simple text or
+ * a structured array for multimodal inputs (e.g., text and image parts).
+ */
+export type MessageContent = string | Array<MessageContentPart>;
+/**
+ * Represents a single message in a conversation, conforming to a structure
+ * widely adopted by chat-based LLM APIs.
+ */
+export interface ChatMessage {
+    /** The role of the entity sending the message. */
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /** The content of the message. Can be simple text or structured for multimodal inputs. */
+    content: MessageContent | null;
+    /** An optional name for the message author. */
+    name?: string;
+    /** Identifier for the tool call, present in 'tool' role messages that are responses to a tool call. */
+    tool_call_id?: string;
+    /** A list of tool calls requested by the assistant. */
+    tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+}
+/**
+ * General options for model completion requests (both chat and legacy text completion, though chat is prioritized).
+ * These options control aspects like creativity, response length, and penalties.
+ */
+export interface ModelCompletionOptions {
+    /** Identifier of the model to use for completion. */
+    modelId?: string;
+    /**
+     * Controls randomness: lower values make the output more focused and deterministic.
+     * Higher values (e.g., 0.8) make it more random.
+     */
+    temperature?: number;
+    /**
+     * Nucleus sampling: the model considers only tokens with probabilities summing up to topP.
+     * Lower values (e.g., 0.1) mean more restricted, less random output.
+     */
+    topP?: number;
+    /**
+     * The maximum number of tokens to generate in the completion.
+     */
+    maxTokens?: number;
+    /**
+     * Positive values penalize new tokens based on whether they appear in the text so far,
+     * increasing the model's likelihood to talk about new topics.
+     */
+    presencePenalty?: number;
+    /**
+     * Positive values penalize new tokens based on their existing frequency in the text so far,
+     * decreasing the model's likelihood to repeat the same line verbatim.
+     */
+    frequencyPenalty?: number;
+    /** Sequences where the API will stop generating further tokens. */
+    stopSequences?: string[];
+    /** A unique identifier representing your end-user. */
+    userId?: string;
+    /** Allows overriding the default API key for a specific user or request. */
+    apiKeyOverride?: string;
+    /** For provider-specific parameters not covered by the common options. */
+    customModelParams?: Record<string, unknown>;
+    /**
+     * Optional AbortSignal for caller-driven cancellation. If aborted:
+     *  - Streaming providers MUST emit a terminal chunk with `isFinal: true` and `error.type='abort'`.
+     *  - Non-streaming calls SHOULD throw a cancellation error (or return error response if already partially processed).
+     */
+    abortSignal?: AbortSignal;
+    /** Indicates if a streaming response is expected. */
+    stream?: boolean;
+    /** Schemas of tools the model can call. */
+    tools?: Array<Record<string, unknown>>;
+    /** Controls how the model uses tools. */
+    toolChoice?: string | Record<string, unknown>;
+    /** Specifies the format of the response, e.g. for JSON mode. */
+    responseFormat?: {
+        type: 'text' | 'json_object' | string;
+    };
+}
+/**
+ * Represents token usage information from a model call, including cost estimation.
+ */
+export interface ModelUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens: number;
+    costUSD?: number;
+}
+/**
+ * Represents a single choice in a model's completion response.
+ */
+export interface ModelCompletionChoice {
+    index: number;
+    message: ChatMessage;
+    text?: string;
+    logprobs?: unknown;
+    finishReason: string | null;
+}
+/**
+ * Represents the full response from a model completion call (non-streaming or a single chunk of a stream).
+ */
+export interface ModelCompletionResponse {
+    /** Provider‑assigned unique identifier for the request or chunk series. */
+    id: string;
+    /** Stable object/type discriminator (e.g. 'chat.completion.chunk', 'chat.completion'). */
+    object: string;
+    /** Unix epoch seconds when the provider created this response/chunk. */
+    created: number;
+    /** Resolved model identifier actually used (may differ from requested if routing / aliasing applied). */
+    modelId: string;
+    /** One or more choices; for multi‑choice inference some providers return >1. */
+    choices: ModelCompletionChoice[];
+    /** Token usage & optional cost metrics (present on final chunk; may be partial/omitted on deltas). */
+    usage?: ModelUsage;
+    /** Unified error envelope; present ONLY if an error occurred for this request/chunk. */
+    error?: {
+        /** Human readable message suitable for UI display or logging. */
+        message: string;
+        /** Optional provider/classification type (e.g. 'rate_limit', 'invalid_request'). */
+        type?: string;
+        /** Numeric or string code for programmatic handling. */
+        code?: string | number;
+        /** Raw provider payload or structured diagnostic details. */
+        details?: unknown;
+    };
+    /** Incremental append‑only text delta for streaming; NOT cumulative. Undefined on non‑streaming final response. */
+    responseTextDelta?: string;
+    /** Array of incremental tool/function call argument deltas building up tool invocation payloads. */
+    toolCallsDeltas?: Array<{
+        /** Choice index if multiple parallel choices produce tool calls. */
+        index: number;
+        /** Stable tool call id once assigned by provider (may appear after initial delta). */
+        id?: string;
+        /** Type discriminator; currently 'function' for OpenAI‑style tools. */
+        type?: 'function';
+        /** Function metadata with incremental argument assembly. */
+        function?: {
+            /** Function name (first provided delta should include). */
+            name?: string;
+            /** Partial argument JSON fragment (streamed). Concatenate & then parse when final. */
+            arguments_delta?: string;
+        };
+    }>;
+    /** Indicates terminal chunk in a stream. MUST be true on last emission (success or error). */
+    isFinal?: boolean;
+}
+/**
+ * Options for embedding generation requests at the provider level.
+ */
+export interface ProviderEmbeddingOptions {
+    model?: string;
+    userId?: string;
+    apiKeyOverride?: string;
+    customModelParams?: Record<string, unknown>;
+    encodingFormat?: 'float' | 'base64';
+    dimensions?: number;
+    inputType?: 'search_document' | 'search_query' | 'classification' | 'clustering' | string;
+}
+/**
+ * Represents a single vector embedding object as returned by a provider.
+ */
+export interface EmbeddingObject {
+    object: 'embedding';
+    embedding: number[];
+    index: number;
+}
+/**
+ * Represents the response from an embedding generation call from a provider.
+ */
+export interface ProviderEmbeddingResponse {
+    object: 'list';
+    data: EmbeddingObject[];
+    model: string;
+    usage: {
+        prompt_tokens: number;
+        total_tokens: number;
+        costUSD?: number;
+    };
+    error?: {
+        message: string;
+        type?: string;
+        code?: string | number;
+        details?: unknown;
+    };
+}
+/**
+ * Represents detailed information about a specific AI model available from a provider.
+ */
+export interface ModelInfo {
+    modelId: string;
+    providerId: string;
+    displayName?: string;
+    description?: string;
+    capabilities: Array<'completion' | 'chat' | 'embeddings' | 'vision_input' | 'tool_use' | 'json_mode' | string>;
+    contextWindowSize?: number;
+    inputTokenLimit?: number;
+    outputTokenLimit?: number;
+    pricePer1MTokensInput?: number;
+    pricePer1MTokensOutput?: number;
+    pricePer1MTokensTotal?: number;
+    supportsStreaming?: boolean;
+    defaultTemperature?: number;
+    minSubscriptionTierLevel?: number;
+    isDefaultModel?: boolean;
+    embeddingDimension?: number;
+    lastUpdated?: string;
+    status?: 'active' | 'beta' | 'deprecated' | string;
+}
+/**
+ * @interface IProvider
+ * @description Defines the contract for an AI Model Provider.
+ */
+export interface IProvider {
+    /** Unique provider identifier (e.g. 'openai', 'ollama', 'openrouter'). */
+    readonly providerId: string;
+    /** Indicates successful initialization; all operational methods MUST guard against !isInitialized. */
+    readonly isInitialized: boolean;
+    /** Optional default model to fall back to when caller does not specify one. */
+    readonly defaultModelId?: string;
+    /**
+     * Perform one‑time (or idempotent) initialization: validate credentials, prime model catalog, set defaults.
+     * SHOULD throw on unrecoverable misconfiguration (e.g., missing API key) rather than silently degrade.
+     * Multiple calls MAY reset internal caches (implementation specific).
+     */
+    initialize(config: Record<string, any>): Promise<void>;
+    /**
+     * Single shot (non‑streaming) completion. Provider MUST return a fully assembled
+     * `ModelCompletionResponse` with `isFinal` either omitted or true, containing full text in `choices[].message.content`.
+     * @param modelId Target model identifier (may be validated or routed).
+     * @param messages Prior conversation messages (system+user+assistant+tool) shaped per unified ChatMessage.
+     * @param options Completion tuning & feature flags (temperature, tools, json mode, etc.).
+     * @throws Error if provider not initialized or request irrecoverably invalid.
+     */
+    generateCompletion(modelId: string, messages: ChatMessage[], options: ModelCompletionOptions): Promise<ModelCompletionResponse>;
+    /**
+     * Streaming completion. Returns an async generator yielding incremental deltas.
+     * REQUIRED invariants:
+     *  - First chunk SHOULD include `id`, `modelId`, `object`, and MAY start text/tool deltas.
+     *  - `responseTextDelta` values MUST be append‑only segments (caller concatenates in order).
+     *  - Tool call reconstruction: concatenate `arguments_delta` per (index,id) then JSON parse when final.
+     *  - Exactly one chunk MUST set `isFinal: true` (last). Final chunk SHOULD include usage & any error.
+     *  - If an error occurs mid‑stream, emit a final chunk with `error` populated then end generator.
+     * @returns AsyncGenerator<ModelCompletionResponse>
+     */
+    generateCompletionStream(modelId: string, messages: ChatMessage[], options: ModelCompletionOptions): AsyncGenerator<ModelCompletionResponse, void, undefined>;
+    /**
+     * Generate embeddings for a batch of input texts. Provider MAY chunk internally but MUST return consolidated
+     * response with ordering preserved (indices map to input position).
+     */
+    generateEmbeddings(modelId: string, texts: string[], options?: ProviderEmbeddingOptions): Promise<ProviderEmbeddingResponse>;
+    /** List available models, optionally filtered by required capability (e.g. 'embeddings'). */
+    listAvailableModels(filter?: {
+        capability?: 'completion' | 'chat' | 'embeddings' | string;
+    }): Promise<ModelInfo[]>;
+    /** Retrieve detailed metadata about a specific model; undefined if unknown or catalog not loaded. */
+    getModelInfo(modelId: string): Promise<ModelInfo | undefined>;
+    /** Lightweight health signal; SHOULD avoid heavy network calls. */
+    checkHealth(): Promise<{
+        isHealthy: boolean;
+        details?: unknown;
+    }>;
+    /** Graceful teardown: release sockets, abort inflight requests, flush caches. Idempotent. */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=IProvider.d.ts.map

package/dist/core/llm/providers/IProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IProvider.d.ts","sourceRoot":"","sources":["../../../../src/core/llm/providers/IProvider.ts"],"names":[],"mappings":"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"}

package/dist/core/llm/providers/IProvider.js

@@ -0,0 +1,39 @@
+// File: backend/agentos/core/llm/providers/IProvider.ts
+/**
+ * @fileoverview Core provider contract and shared types for integrating Large Language / Multimodal Model services
+ * into AgentOS. Implementations wrap concrete vendor SDKs or HTTP APIs (OpenAI, Anthropic, Ollama, OpenRouter, etc.)
+ * and normalize their capabilities into a consistent surface area used by higher‑level orchestration layers
+ * (PromptEngine, GMIManager, Utility AI components).
+ *
+ * Design Goals:
+ * 1. Capability Normalization – Chat vs legacy completion, tool/function calling, streaming deltas, embeddings.
+ * 2. Deterministic Streaming Semantics – Every streamed chunk is a full `ModelCompletionResponse` fragment with:
+ *    - optional `responseTextDelta` (string diff)
+ *    - optional `toolCallsDeltas[]` capturing incremental tool argument assembly
+ *    - `isFinal` flag to indicate terminal chunk and stable usage metrics.
+ * 3. Introspection – Lightweight model catalog (`listAvailableModels`, `getModelInfo`) enabling routing & cost decisions.
+ * 4. Resilience & Diagnostics – Uniform error envelope attached to `ModelCompletionResponse.error` for both
+ *    streaming and non‑streaming calls so upstream layers can surface actionable messages.
+ * 5. Strict Initialization Lifecycle – `initialize()` must succeed before any other mutating call.
+ *
+ * Error Handling Philosophy:
+ * - Provider implementations SHOULD translate vendor‑specific errors into a stable structure:
+ *   { message, type?, code?, details? }.
+ * - Transient failures (network timeouts, rate limit backoffs) MAY be surfaced inline; upstream retry policies live above.
+ * - Streaming calls MUST emit a terminal chunk with `isFinal: true` even on error (with `error` populated) so consumers
+ *   can perform consistent teardown.
+ *
+ * Concurrency & Cancellation:
+ * - Implementations MAY support externally triggered abort via custom option (e.g. `customModelParams.abortSignal`).
+ * - If supported, aborted streams MUST still resolve the generator cleanly (no thrown error) after emitting a final
+ *   chunk with `isFinal: true` and an `error` describing the cancellation reason.
+ *
+ * Token Usage & Cost:
+ * - `usage.totalTokens` MUST be present on final responses (streaming or non‑streaming).
+ * - Interim streaming chunks SHOULD omit usage or provide partials; callers should treat usage as unstable until final.
+ * - `costUSD` is optional; if provided should reflect estimated or actual vendor pricing for the call.
+ *
+ * @module backend/agentos/core/llm/providers/IProvider
+ */
+export {};
+//# sourceMappingURL=IProvider.js.map

package/dist/core/llm/providers/IProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IProvider.js","sourceRoot":"","sources":["../../../../src/core/llm/providers/IProvider.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG"}

package/dist/core/llm/providers/errors/OllamaProviderError.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Defines a custom error class for Ollama-specific provider errors.
+ * This extends the base {@link ProviderError} to include details specific to Ollama API interactions.
+ * @module backend/agentos/core/llm/providers/errors/OllamaProviderError
+ * @see {@link ./ProviderError.ts}
+ */
+import { ProviderError } from './ProviderError';
+/**
+ * Represents an error specific to the Ollama provider.
+ * It can include additional context like HTTP status codes or specific Ollama error messages.
+ *
+ * @example
+ * try {
+ * // Ollama API call
+ * } catch (error) {
+ * if (error instanceof OllamaProviderError) {
+ * console.error(`Ollama Error (Status: ${error.httpStatus || 'N/A'}): ${error.message}`);
+ * // Handle Ollama-specific error properties
+ * } else {
+ * // Handle other errors
+ * }
+ * }
+ */
+export declare class OllamaProviderError extends ProviderError {
+    /** HTTP status code from the API response (e.g., 400, 404, 500). */
+    readonly httpStatus?: number;
+    /**
+     * Creates an instance of OllamaProviderError.
+     * @param {string} message - A human-readable description of the error.
+     * @param {string} code - A unique AgentOS internal code identifying the type of error (e.g., 'CONNECTION_FAILED', 'API_ERROR').
+     * @param {number} [httpStatus] - HTTP status code from the API response.
+     * @param {unknown} [details] - Optional underlying error object or additional context from Ollama.
+     */
+    constructor(message: string, code: string, httpStatus?: number, details?: unknown);
+}
+//# sourceMappingURL=OllamaProviderError.d.ts.map

package/dist/core/llm/providers/errors/OllamaProviderError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OllamaProviderError.d.ts","sourceRoot":"","sources":["../../../../../src/core/llm/providers/errors/OllamaProviderError.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;IACpD,oEAAoE;IACpE,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpC;;;;;;OAMG;gBAED,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,OAAO;CAQpB"}

package/dist/core/llm/providers/errors/OllamaProviderError.js

@@ -0,0 +1,40 @@
+// File: backend/agentos/core/llm/providers/errors/OllamaProviderError.ts
+/**
+ * @fileoverview Defines a custom error class for Ollama-specific provider errors.
+ * This extends the base {@link ProviderError} to include details specific to Ollama API interactions.
+ * @module backend/agentos/core/llm/providers/errors/OllamaProviderError
+ * @see {@link ./ProviderError.ts}
+ */
+import { ProviderError } from './ProviderError.js';
+/**
+ * Represents an error specific to the Ollama provider.
+ * It can include additional context like HTTP status codes or specific Ollama error messages.
+ *
+ * @example
+ * try {
+ * // Ollama API call
+ * } catch (error) {
+ * if (error instanceof OllamaProviderError) {
+ * console.error(`Ollama Error (Status: ${error.httpStatus || 'N/A'}): ${error.message}`);
+ * // Handle Ollama-specific error properties
+ * } else {
+ * // Handle other errors
+ * }
+ * }
+ */
+export class OllamaProviderError extends ProviderError {
+    /**
+     * Creates an instance of OllamaProviderError.
+     * @param {string} message - A human-readable description of the error.
+     * @param {string} code - A unique AgentOS internal code identifying the type of error (e.g., 'CONNECTION_FAILED', 'API_ERROR').
+     * @param {number} [httpStatus] - HTTP status code from the API response.
+     * @param {unknown} [details] - Optional underlying error object or additional context from Ollama.
+     */
+    constructor(message, code, httpStatus, details) {
+        super(message, code, 'ollama', details); // ProviderId is 'ollama'
+        this.name = 'OllamaProviderError';
+        this.httpStatus = httpStatus;
+        Object.setPrototypeOf(this, OllamaProviderError.prototype);
+    }
+}
+//# sourceMappingURL=OllamaProviderError.js.map

package/dist/core/llm/providers/errors/OllamaProviderError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OllamaProviderError.js","sourceRoot":"","sources":["../../../../../src/core/llm/providers/errors/OllamaProviderError.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IAIpD;;;;;;OAMG;IACH,YACE,OAAe,EACf,IAAY,EACZ,UAAmB,EACnB,OAAiB;QAEjB,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,yBAAyB;QAClE,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAE7B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC7D,CAAC;CACF"}

package/dist/core/llm/providers/errors/OpenAIProviderError.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Defines a custom error class for OpenAI-specific provider errors.
+ * This extends the base {@link ProviderError} to include details specific to OpenAI API interactions.
+ * @module backend/agentos/core/llm/providers/errors/OpenAIProviderError
+ * @see {@link ./ProviderError.ts}
+ */
+import { ProviderError } from './ProviderError';
+/**
+ * Represents an error specific to the OpenAI provider.
+ * It includes additional context like OpenAI-specific error codes, types, and HTTP status.
+ *
+ * @example
+ * try {
+ * // OpenAI API call
+ * } catch (error) {
+ * if (error instanceof OpenAIProviderError) {
+ * console.error(`OpenAI Error (${error.openaiErrorCode || 'N/A'}): ${error.message}`);
+ * // Handle OpenAI-specific error properties
+ * } else {
+ * // Handle other errors
+ * }
+ * }
+ */
+export declare class OpenAIProviderError extends ProviderError {
+    /** OpenAI-specific error code from the API response (e.g., "invalid_api_key", "rate_limit_exceeded"). */
+    readonly openaiErrorCode?: string;
+    /** OpenAI error type classification (e.g., "invalid_request_error", "api_error"). */
+    readonly openaiErrorType?: string;
+    /** HTTP status code from the API response (e.g., 400, 401, 429, 500). */
+    readonly httpStatus?: number;
+    /**
+     * Creates an instance of OpenAIProviderError.
+     * @param {string} message - A human-readable description of the error.
+     * @param {string} code - A unique AgentOS internal code identifying the type of error (e.g., 'API_REQUEST_FAILED', 'AUTHENTICATION_ERROR').
+     * @param {string} [openaiErrorCode] - OpenAI-specific error code from the API response.
+     * @param {string} [openaiErrorType] - OpenAI error type classification.
+     * @param {number} [httpStatus] - HTTP status code from the API response.
+     * @param {unknown} [details] - Optional underlying error object or additional context.
+     */
+    constructor(message: string, code: string, openaiErrorCode?: string, openaiErrorType?: string, httpStatus?: number, details?: unknown);
+}
+//# sourceMappingURL=OpenAIProviderError.d.ts.map

package/dist/core/llm/providers/errors/OpenAIProviderError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenAIProviderError.d.ts","sourceRoot":"","sources":["../../../../../src/core/llm/providers/errors/OpenAIProviderError.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,SAAQ,aAAa;IACpD,yGAAyG;IACzG,SAAgB,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzC,qFAAqF;IACrF,SAAgB,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzC,yEAAyE;IACzE,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpC;;;;;;;;OAQG;gBAED,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,MAAM,EACxB,eAAe,CAAC,EAAE,MAAM,EACxB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,OAAO;CAUpB"}

package/dist/core/llm/providers/errors/OpenAIProviderError.js

@@ -0,0 +1,44 @@
+// File: backend/agentos/core/llm/providers/errors/OpenAIProviderError.ts
+/**
+ * @fileoverview Defines a custom error class for OpenAI-specific provider errors.
+ * This extends the base {@link ProviderError} to include details specific to OpenAI API interactions.
+ * @module backend/agentos/core/llm/providers/errors/OpenAIProviderError
+ * @see {@link ./ProviderError.ts}
+ */
+import { ProviderError } from './ProviderError.js';
+/**
+ * Represents an error specific to the OpenAI provider.
+ * It includes additional context like OpenAI-specific error codes, types, and HTTP status.
+ *
+ * @example
+ * try {
+ * // OpenAI API call
+ * } catch (error) {
+ * if (error instanceof OpenAIProviderError) {
+ * console.error(`OpenAI Error (${error.openaiErrorCode || 'N/A'}): ${error.message}`);
+ * // Handle OpenAI-specific error properties
+ * } else {
+ * // Handle other errors
+ * }
+ * }
+ */
+export class OpenAIProviderError extends ProviderError {
+    /**
+     * Creates an instance of OpenAIProviderError.
+     * @param {string} message - A human-readable description of the error.
+     * @param {string} code - A unique AgentOS internal code identifying the type of error (e.g., 'API_REQUEST_FAILED', 'AUTHENTICATION_ERROR').
+     * @param {string} [openaiErrorCode] - OpenAI-specific error code from the API response.
+     * @param {string} [openaiErrorType] - OpenAI error type classification.
+     * @param {number} [httpStatus] - HTTP status code from the API response.
+     * @param {unknown} [details] - Optional underlying error object or additional context.
+     */
+    constructor(message, code, openaiErrorCode, openaiErrorType, httpStatus, details) {
+        super(message, code, 'openai', details); // ProviderId is 'openai'
+        this.name = 'OpenAIProviderError';
+        this.openaiErrorCode = openaiErrorCode;
+        this.openaiErrorType = openaiErrorType;
+        this.httpStatus = httpStatus;
+        Object.setPrototypeOf(this, OpenAIProviderError.prototype);
+    }
+}
+//# sourceMappingURL=OpenAIProviderError.js.map

package/dist/core/llm/providers/errors/OpenAIProviderError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenAIProviderError.js","sourceRoot":"","sources":["../../../../../src/core/llm/providers/errors/OpenAIProviderError.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IAUpD;;;;;;;;OAQG;IACH,YACE,OAAe,EACf,IAAY,EACZ,eAAwB,EACxB,eAAwB,EACxB,UAAmB,EACnB,OAAiB;QAEjB,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,yBAAyB;QAClE,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAE7B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC7D,CAAC;CACF"}

package/dist/core/llm/providers/errors/OpenRouterProviderError.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Defines a custom error class for OpenRouter-specific provider errors.
+ * This extends the base {@link ProviderError} to include details specific to OpenRouter API interactions.
+ * @module backend/agentos/core/llm/providers/errors/OpenRouterProviderError
+ * @see {@link ./ProviderError.ts}
+ */
+import { ProviderError } from './ProviderError';
+/**
+ * Represents an error specific to the OpenRouter provider.
+ * It can include additional context like HTTP status codes or specific OpenRouter error messages.
+ *
+ * @example
+ * try {
+ * // OpenRouter API call
+ * } catch (error) {
+ * if (error instanceof OpenRouterProviderError) {
+ * console.error(`OpenRouter Error (Status: ${error.httpStatus || 'N/A'}, Type: ${error.openRouterErrorType || 'N/A'}): ${error.message}`);
+ * // Handle OpenRouter-specific error properties
+ * } else {
+ * // Handle other errors
+ * }
+ * }
+ */
+export declare class OpenRouterProviderError extends ProviderError {
+    /** HTTP status code from the API response (e.g., 400, 401, 429, 500). */
+    readonly httpStatus?: number;
+    /** OpenRouter specific error type, if available from the response. */
+    readonly openRouterErrorType?: string;
+    /**
+     * Creates an instance of OpenRouterProviderError.
+     * @param {string} message - A human-readable description of the error.
+     * @param {string} code - A unique AgentOS internal code identifying the type of error (e.g., 'API_REQUEST_FAILED', 'INVALID_ROUTE').
+     * @param {number} [httpStatus] - HTTP status code from the API response.
+     * @param {string} [openRouterErrorType] - OpenRouter specific error type.
+     * @param {unknown} [details] - Optional underlying error object or additional context from OpenRouter.
+     */
+    constructor(message: string, code: string, httpStatus?: number, openRouterErrorType?: string, details?: unknown);
+}
+//# sourceMappingURL=OpenRouterProviderError.d.ts.map

package/dist/core/llm/providers/errors/OpenRouterProviderError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenRouterProviderError.d.ts","sourceRoot":"","sources":["../../../../../src/core/llm/providers/errors/OpenRouterProviderError.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,uBAAwB,SAAQ,aAAa;IACxD,yEAAyE;IACzE,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpC,sEAAsE;IACtE,SAAgB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7C;;;;;;;OAOG;gBAED,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,MAAM,EACnB,mBAAmB,CAAC,EAAE,MAAM,EAC5B,OAAO,CAAC,EAAE,OAAO;CASpB"}

package/dist/core/llm/providers/errors/OpenRouterProviderError.js

@@ -0,0 +1,42 @@
+// File: backend/agentos/core/llm/providers/errors/OpenRouterProviderError.ts
+/**
+ * @fileoverview Defines a custom error class for OpenRouter-specific provider errors.
+ * This extends the base {@link ProviderError} to include details specific to OpenRouter API interactions.
+ * @module backend/agentos/core/llm/providers/errors/OpenRouterProviderError
+ * @see {@link ./ProviderError.ts}
+ */
+import { ProviderError } from './ProviderError.js';
+/**
+ * Represents an error specific to the OpenRouter provider.
+ * It can include additional context like HTTP status codes or specific OpenRouter error messages.
+ *
+ * @example
+ * try {
+ * // OpenRouter API call
+ * } catch (error) {
+ * if (error instanceof OpenRouterProviderError) {
+ * console.error(`OpenRouter Error (Status: ${error.httpStatus || 'N/A'}, Type: ${error.openRouterErrorType || 'N/A'}): ${error.message}`);
+ * // Handle OpenRouter-specific error properties
+ * } else {
+ * // Handle other errors
+ * }
+ * }
+ */
+export class OpenRouterProviderError extends ProviderError {
+    /**
+     * Creates an instance of OpenRouterProviderError.
+     * @param {string} message - A human-readable description of the error.
+     * @param {string} code - A unique AgentOS internal code identifying the type of error (e.g., 'API_REQUEST_FAILED', 'INVALID_ROUTE').
+     * @param {number} [httpStatus] - HTTP status code from the API response.
+     * @param {string} [openRouterErrorType] - OpenRouter specific error type.
+     * @param {unknown} [details] - Optional underlying error object or additional context from OpenRouter.
+     */
+    constructor(message, code, httpStatus, openRouterErrorType, details) {
+        super(message, code, 'openrouter', details); // ProviderId is 'openrouter'
+        this.name = 'OpenRouterProviderError';
+        this.httpStatus = httpStatus;
+        this.openRouterErrorType = openRouterErrorType;
+        Object.setPrototypeOf(this, OpenRouterProviderError.prototype);
+    }
+}
+//# sourceMappingURL=OpenRouterProviderError.js.map