@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/services/llm/providers/openrouter.provider.d.ts

@@ -0,0 +1,187 @@
+import type { ChatCompletion, ChatCompletionChunk } from 'openai/resources/chat/completions';
+import type { Stream } from 'openai/streaming';
+import type { config as ConfigType } from '../../../config/index.js';
+import type { ILlmProvider, OpenRouterChatParams } from '../../../services/llm/core/ILlmProvider.js';
+import type { logger as LoggerType } from '../../../utils/internal/logger.js';
+import { type RequestContext } from '../../../utils/internal/requestContext.js';
+import type { RateLimiter } from '../../../utils/security/rateLimiter.js';
+/**
+ * Construction options for the underlying `OpenAI` client pointed at OpenRouter.
+ * Passed internally by `initClient()` — not exposed as a public constructor parameter,
+ * but exported so callers can reference the shape if needed.
+ */
+export interface OpenRouterClientOptions {
+    /** OpenRouter API key (value of `OPENROUTER_API_KEY`). */
+    apiKey: string;
+    /**
+     * Base URL for the OpenRouter API. Defaults to `https://openrouter.ai/api/v1`
+     * when not provided.
+     */
+    baseURL?: string;
+    /**
+     * Human-readable name of the calling application, sent as the `X-Title` request
+     * header for OpenRouter analytics and attribution.
+     */
+    siteName?: string;
+    /**
+     * URL of the calling application, sent as the `HTTP-Referer` request header for
+     * OpenRouter analytics and attribution.
+     */
+    siteUrl?: string;
+}
+/**
+ * LLM provider implementation backed by the OpenRouter API.
+ *
+ * Implements `ILlmProvider` so it can be used anywhere the framework expects a
+ * generic LLM provider. The `openai` SDK is loaded lazily on first use; the
+ * resulting `OpenAI` client is cached for the lifetime of the instance.
+ *
+ * Default generation parameters (`model`, `temperature`, `top_p`, `max_tokens`,
+ * `top_k`, `min_p`) are read from the application config at construction time and
+ * applied to every request unless the caller explicitly overrides them. Passing
+ * `null` for an OpenAI-typed field (e.g. `temperature: null`) clears that default.
+ *
+ * @example
+ * ```ts
+ * const provider = new OpenRouterProvider(rateLimiter, config, logger);
+ * const completion = await provider.chatCompletion(
+ *   { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'Hello' }] },
+ *   ctx,
+ * );
+ * ```
+ */
+export declare class OpenRouterProvider implements ILlmProvider {
+    private rateLimiter;
+    private config;
+    private logger;
+    /** Cached `OpenAI` client instance. Undefined until the first request. */
+    private client;
+    /**
+     * In-flight initialization promise. Guards against concurrent calls racing to
+     * create the client simultaneously. Reset to `undefined` if `initClient` throws,
+     * so the next call can retry.
+     */
+    private clientInitPromise;
+    /** Default generation parameters sourced from app config at construction time. */
+    private readonly defaultParams;
+    /**
+     * Creates a new `OpenRouterProvider` instance.
+     *
+     * @param rateLimiter - Rate limiter used to throttle outbound API calls per
+     *   client/tenant key.
+     * @param config - Application config object; must have `openrouterApiKey` set,
+     *   and may have `llmDefault*` fields for generation defaults.
+     * @param logger - Application logger for lifecycle and interaction logging.
+     * @throws {McpError} `ConfigurationError` if `openrouterApiKey` is absent in config.
+     */
+    constructor(rateLimiter: RateLimiter, config: typeof ConfigType, logger: typeof LoggerType);
+    /**
+     * Returns the initialized `OpenAI` client, initializing it on first call.
+     * Concurrent callers share a single initialization promise to avoid duplicate
+     * client construction.
+     *
+     * @returns The ready-to-use `OpenAI` client.
+     * @throws {McpError} `ConfigurationError` if client initialization fails.
+     */
+    private ensureClient;
+    /**
+     * Performs the one-time initialization of the `OpenAI` client configured for
+     * the OpenRouter base URL. Lazily imports the `openai` package, constructs the
+     * client with API key and optional site metadata headers, and stores the result
+     * in `this.client`.
+     *
+     * If initialization fails, `clientInitPromise` is reset so the next call to
+     * `ensureClient()` can attempt again.
+     *
+     * @returns The newly constructed `OpenAI` client.
+     * @throws {McpError} `ConfigurationError` if the `openai` package is missing or
+     *   client construction throws.
+     */
+    private initClient;
+    /**
+     * Merges caller-supplied parameters with instance-level defaults. OpenAI-typed
+     * fields (`model`, `temperature`, `top_p`, `max_tokens`) fall back to the
+     * corresponding `defaultParams` value when omitted. Passing `null` explicitly
+     * clears the default (mapped to `undefined` in the result object so the field is
+     * omitted from the API request).
+     *
+     * OpenRouter-specific fields not present in the OpenAI type definitions
+     * (`top_k`, `min_p`) are applied from defaults only when not already present in
+     * the incoming params.
+     *
+     * @param params - Raw parameters from the caller before defaults are applied.
+     * @returns A new parameter object with defaults merged in, ready to send to the
+     *   OpenRouter API.
+     */
+    private _prepareApiParameters;
+    /**
+     * Dispatches a single chat completion call to the OpenRouter API via the
+     * provided `OpenAI` client. Logs the outbound request via `logInteraction`.
+     * For non-streaming calls, awaits the response and logs it before returning.
+     * For streaming calls, returns the `Stream` immediately; the caller is
+     * responsible for consuming and logging the stream (see `chatCompletionStream`).
+     *
+     * @param client - Initialized `OpenAI` client to use for the request.
+     * @param params - Fully-prepared API parameters (defaults already merged).
+     * @param context - Request context for correlated log entries.
+     * @returns `ChatCompletion` for non-streaming; `Stream<ChatCompletionChunk>` for streaming.
+     * @throws Propagates any error thrown by the OpenAI SDK.
+     */
+    private _openRouterChatCompletionLogic;
+    /**
+     * Sends a chat completion request to OpenRouter. Enforces rate limiting keyed
+     * on `context.auth?.clientId`, `context.tenantId`, or the global fallback key
+     * `'openrouter_global'`. Applies generation defaults via `_prepareApiParameters`
+     * before dispatching.
+     *
+     * Wraps execution in `ErrorHandler.tryCatch` for consistent error formatting and
+     * structured logging. Input params are sanitized before logging.
+     *
+     * @param params - Chat completion parameters (streaming or non-streaming).
+     * @param context - Request context for rate-limit keying, logging, and tracing.
+     * @returns `ChatCompletion` when `params.stream` is falsy; `Stream<ChatCompletionChunk>`
+     *   when `params.stream` is `true`.
+     * @throws {McpError} `RateLimited` if the rate limit is exceeded.
+     * @throws {McpError} `ConfigurationError` if the OpenAI client cannot be initialized.
+     * @throws {McpError} `ServiceUnavailable` if the OpenRouter API call fails.
+     *
+     * @example
+     * ```ts
+     * const result = await provider.chatCompletion(
+     *   { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'Hello' }] },
+     *   ctx,
+     * ) as ChatCompletion;
+     * console.log(result.choices[0].message.content);
+     * ```
+     */
+    chatCompletion(params: OpenRouterChatParams, context: RequestContext): Promise<ChatCompletion | Stream<ChatCompletionChunk>>;
+    /**
+     * Sends a streaming chat completion request to OpenRouter and returns an async
+     * generator that yields `ChatCompletionChunk` objects as they arrive.
+     *
+     * Internally delegates to `chatCompletion` with `stream: true` forced, then
+     * wraps the resulting `Stream` in a generator that collects all chunks and logs
+     * the full response (via `logInteraction`) in the generator's `finally` block
+     * once the stream is exhausted or the consumer breaks out early.
+     *
+     * @param params - Chat completion parameters. `stream` is overridden to `true`.
+     * @param context - Request context for rate-limit keying, logging, and tracing.
+     * @returns An async iterable that yields `ChatCompletionChunk` objects.
+     * @throws {McpError} `RateLimited` if the rate limit is exceeded.
+     * @throws {McpError} `ConfigurationError` if the OpenAI client cannot be initialized.
+     * @throws {McpError} `ServiceUnavailable` if the OpenRouter API call fails.
+     *
+     * @example
+     * ```ts
+     * const stream = await provider.chatCompletionStream(
+     *   { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'Hello' }] },
+     *   ctx,
+     * );
+     * for await (const chunk of stream) {
+     *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+     * }
+     * ```
+     */
+    chatCompletionStream(params: OpenRouterChatParams, context: RequestContext): Promise<AsyncIterable<ChatCompletionChunk>>;
+}
+//# sourceMappingURL=openrouter.provider.d.ts.map

package/dist/services/llm/providers/openrouter.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openrouter.provider.d.ts","sourceRoot":"","sources":["../../../../src/services/llm/providers/openrouter.provider.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAC7F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAG9F,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,oCAAoC,CAAC;AAChG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AA2BnE;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IA8BnD,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,MAAM;IA/BhB,0EAA0E;IAC1E,OAAO,CAAC,MAAM,CAAqB;IACnC;;;;OAIG;IACH,OAAO,CAAC,iBAAiB,CAA8B;IACvD,kFAAkF;IAClF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAO5B;IAEF;;;;;;;;;OASG;gBAEO,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,OAAO,UAAU,EACzB,MAAM,EAAE,OAAO,UAAU;IA8BnC;;;;;;;OAOG;YACW,YAAY;IAM1B;;;;;;;;;;;;OAYG;YACW,UAAU;IAsCxB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,qBAAqB;IAyB7B;;;;;;;;;;;;OAYG;YACW,8BAA8B;IAwB5C;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,cAAc,CACzB,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAgBxD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,oBAAoB,CAC/B,MAAM,EAAE,oBAAoB,EAC5B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,mBAAmB,CAAC,CAAC;CA2B/C"}

package/dist/services/llm/providers/openrouter.provider.js

@@ -0,0 +1,302 @@
+import { JsonRpcErrorCode, McpError } from '../../../types-global/errors.js';
+import { ErrorHandler } from '../../../utils/internal/error-handler/errorHandler.js';
+import { requestContextService } from '../../../utils/internal/requestContext.js';
+import { sanitization } from '../../../utils/security/sanitization.js';
+/**
+ * Module-level cache for the lazily-imported `openai` package. Undefined until the
+ * first call to `getOpenAI()`. Retained across calls to avoid repeated dynamic imports.
+ */
+let _openai;
+/**
+ * Lazily imports and returns the `OpenAI` default export from the `openai` package.
+ * The import is deferred so that `openai` remains an optional peer dependency —
+ * servers that never call an LLM method pay no startup cost.
+ *
+ * @returns The `OpenAI` constructor (default export of the `openai` package).
+ * @throws {McpError} `ConfigurationError` if the `openai` package is not installed.
+ */
+async function getOpenAI() {
+    _openai ??= await import('openai').catch(() => {
+        throw new McpError(JsonRpcErrorCode.ConfigurationError, 'Install "openai" to use the OpenRouter LLM provider: bun add openai');
+    });
+    return _openai.default;
+}
+/**
+ * LLM provider implementation backed by the OpenRouter API.
+ *
+ * Implements `ILlmProvider` so it can be used anywhere the framework expects a
+ * generic LLM provider. The `openai` SDK is loaded lazily on first use; the
+ * resulting `OpenAI` client is cached for the lifetime of the instance.
+ *
+ * Default generation parameters (`model`, `temperature`, `top_p`, `max_tokens`,
+ * `top_k`, `min_p`) are read from the application config at construction time and
+ * applied to every request unless the caller explicitly overrides them. Passing
+ * `null` for an OpenAI-typed field (e.g. `temperature: null`) clears that default.
+ *
+ * @example
+ * ```ts
+ * const provider = new OpenRouterProvider(rateLimiter, config, logger);
+ * const completion = await provider.chatCompletion(
+ *   { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'Hello' }] },
+ *   ctx,
+ * );
+ * ```
+ */
+export class OpenRouterProvider {
+    rateLimiter;
+    config;
+    logger;
+    /** Cached `OpenAI` client instance. Undefined until the first request. */
+    client;
+    /**
+     * In-flight initialization promise. Guards against concurrent calls racing to
+     * create the client simultaneously. Reset to `undefined` if `initClient` throws,
+     * so the next call can retry.
+     */
+    clientInitPromise;
+    /** Default generation parameters sourced from app config at construction time. */
+    defaultParams;
+    /**
+     * Creates a new `OpenRouterProvider` instance.
+     *
+     * @param rateLimiter - Rate limiter used to throttle outbound API calls per
+     *   client/tenant key.
+     * @param config - Application config object; must have `openrouterApiKey` set,
+     *   and may have `llmDefault*` fields for generation defaults.
+     * @param logger - Application logger for lifecycle and interaction logging.
+     * @throws {McpError} `ConfigurationError` if `openrouterApiKey` is absent in config.
+     */
+    constructor(rateLimiter, config, logger) {
+        this.rateLimiter = rateLimiter;
+        this.config = config;
+        this.logger = logger;
+        const context = requestContextService.createRequestContext({
+            operation: 'OpenRouterProvider.constructor',
+        });
+        if (!this.config.openrouterApiKey) {
+            this.logger.fatal('OpenRouter API key is not configured. Please set OPENROUTER_API_KEY.', context);
+            throw new McpError(JsonRpcErrorCode.ConfigurationError, 'OpenRouter API key is not configured.', context);
+        }
+        this.defaultParams = {
+            model: this.config.llmDefaultModel,
+            temperature: this.config.llmDefaultTemperature,
+            topP: this.config.llmDefaultTopP,
+            maxTokens: this.config.llmDefaultMaxTokens,
+            topK: this.config.llmDefaultTopK,
+            minP: this.config.llmDefaultMinP,
+        };
+        this.logger.info('OpenRouter provider instance created and ready.', context);
+    }
+    /**
+     * Returns the initialized `OpenAI` client, initializing it on first call.
+     * Concurrent callers share a single initialization promise to avoid duplicate
+     * client construction.
+     *
+     * @returns The ready-to-use `OpenAI` client.
+     * @throws {McpError} `ConfigurationError` if client initialization fails.
+     */
+    async ensureClient() {
+        if (this.client)
+            return this.client;
+        this.clientInitPromise ??= this.initClient();
+        return await this.clientInitPromise;
+    }
+    /**
+     * Performs the one-time initialization of the `OpenAI` client configured for
+     * the OpenRouter base URL. Lazily imports the `openai` package, constructs the
+     * client with API key and optional site metadata headers, and stores the result
+     * in `this.client`.
+     *
+     * If initialization fails, `clientInitPromise` is reset so the next call to
+     * `ensureClient()` can attempt again.
+     *
+     * @returns The newly constructed `OpenAI` client.
+     * @throws {McpError} `ConfigurationError` if the `openai` package is missing or
+     *   client construction throws.
+     */
+    async initClient() {
+        const context = requestContextService.createRequestContext({
+            operation: 'OpenRouterProvider.initClient',
+        });
+        try {
+            const OpenAIClass = await getOpenAI();
+            const options = {
+                apiKey: this.config.openrouterApiKey,
+                siteUrl: this.config.openrouterAppUrl,
+                siteName: this.config.openrouterAppName,
+            };
+            this.client = new OpenAIClass({
+                baseURL: options.baseURL ?? 'https://openrouter.ai/api/v1',
+                apiKey: options.apiKey,
+                defaultHeaders: {
+                    'HTTP-Referer': options.siteUrl,
+                    'X-Title': options.siteName,
+                },
+                maxRetries: 0,
+            });
+            return this.client;
+        }
+        catch (e) {
+            this.clientInitPromise = undefined;
+            const error = e instanceof Error ? e : new Error(String(e));
+            this.logger.error('Failed to construct OpenRouter client', {
+                ...context,
+                error: error.message,
+            });
+            throw new McpError(JsonRpcErrorCode.ConfigurationError, 'Failed to construct OpenRouter client. Please check the configuration.', { cause: error });
+        }
+    }
+    // --- PRIVATE METHODS ---
+    /**
+     * Merges caller-supplied parameters with instance-level defaults. OpenAI-typed
+     * fields (`model`, `temperature`, `top_p`, `max_tokens`) fall back to the
+     * corresponding `defaultParams` value when omitted. Passing `null` explicitly
+     * clears the default (mapped to `undefined` in the result object so the field is
+     * omitted from the API request).
+     *
+     * OpenRouter-specific fields not present in the OpenAI type definitions
+     * (`top_k`, `min_p`) are applied from defaults only when not already present in
+     * the incoming params.
+     *
+     * @param params - Raw parameters from the caller before defaults are applied.
+     * @returns A new parameter object with defaults merged in, ready to send to the
+     *   OpenRouter API.
+     */
+    _prepareApiParameters(params) {
+        const { model, temperature, top_p: topP, max_tokens: maxTokens, stream, ...rest } = params;
+        const result = {
+            ...rest,
+            model: model ?? this.defaultParams.model,
+            temperature: temperature === null ? undefined : (temperature ?? this.defaultParams.temperature),
+            top_p: topP === null ? undefined : (topP ?? this.defaultParams.topP),
+            max_tokens: maxTokens === null ? undefined : (maxTokens ?? this.defaultParams.maxTokens),
+            ...(typeof stream === 'boolean' && { stream }),
+        };
+        // OpenRouter-specific params not in OpenAI types — apply defaults
+        const extra = rest;
+        if (extra.top_k === undefined && this.defaultParams.topK !== undefined) {
+            result.top_k = this.defaultParams.topK;
+        }
+        if (extra.min_p === undefined && this.defaultParams.minP !== undefined) {
+            result.min_p = this.defaultParams.minP;
+        }
+        return result;
+    }
+    /**
+     * Dispatches a single chat completion call to the OpenRouter API via the
+     * provided `OpenAI` client. Logs the outbound request via `logInteraction`.
+     * For non-streaming calls, awaits the response and logs it before returning.
+     * For streaming calls, returns the `Stream` immediately; the caller is
+     * responsible for consuming and logging the stream (see `chatCompletionStream`).
+     *
+     * @param client - Initialized `OpenAI` client to use for the request.
+     * @param params - Fully-prepared API parameters (defaults already merged).
+     * @param context - Request context for correlated log entries.
+     * @returns `ChatCompletion` for non-streaming; `Stream<ChatCompletionChunk>` for streaming.
+     * @throws Propagates any error thrown by the OpenAI SDK.
+     */
+    async _openRouterChatCompletionLogic(client, params, context) {
+        this.logger.logInteraction('OpenRouterRequest', {
+            context,
+            request: params,
+        });
+        if (params.stream) {
+            return client.chat.completions.create(params);
+        }
+        else {
+            const response = await client.chat.completions.create(params);
+            this.logger.logInteraction('OpenRouterResponse', {
+                context,
+                response,
+            });
+            return response;
+        }
+    }
+    // --- PUBLIC METHODS (from ILlmProvider interface) ---
+    /**
+     * Sends a chat completion request to OpenRouter. Enforces rate limiting keyed
+     * on `context.auth?.clientId`, `context.tenantId`, or the global fallback key
+     * `'openrouter_global'`. Applies generation defaults via `_prepareApiParameters`
+     * before dispatching.
+     *
+     * Wraps execution in `ErrorHandler.tryCatch` for consistent error formatting and
+     * structured logging. Input params are sanitized before logging.
+     *
+     * @param params - Chat completion parameters (streaming or non-streaming).
+     * @param context - Request context for rate-limit keying, logging, and tracing.
+     * @returns `ChatCompletion` when `params.stream` is falsy; `Stream<ChatCompletionChunk>`
+     *   when `params.stream` is `true`.
+     * @throws {McpError} `RateLimited` if the rate limit is exceeded.
+     * @throws {McpError} `ConfigurationError` if the OpenAI client cannot be initialized.
+     * @throws {McpError} `ServiceUnavailable` if the OpenRouter API call fails.
+     *
+     * @example
+     * ```ts
+     * const result = await provider.chatCompletion(
+     *   { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'Hello' }] },
+     *   ctx,
+     * ) as ChatCompletion;
+     * console.log(result.choices[0].message.content);
+     * ```
+     */
+    async chatCompletion(params, context) {
+        const operation = 'OpenRouterProvider.chatCompletion';
+        const sanitizedParams = sanitization.sanitizeForLogging(params);
+        return await ErrorHandler.tryCatch(async () => {
+            const rateLimitKey = context.auth?.clientId ?? context.tenantId ?? 'openrouter_global';
+            this.rateLimiter.check(rateLimitKey, context);
+            const finalApiParams = this._prepareApiParameters(params);
+            const client = await this.ensureClient();
+            return await this._openRouterChatCompletionLogic(client, finalApiParams, context);
+        }, { operation, context, input: sanitizedParams });
+    }
+    /**
+     * Sends a streaming chat completion request to OpenRouter and returns an async
+     * generator that yields `ChatCompletionChunk` objects as they arrive.
+     *
+     * Internally delegates to `chatCompletion` with `stream: true` forced, then
+     * wraps the resulting `Stream` in a generator that collects all chunks and logs
+     * the full response (via `logInteraction`) in the generator's `finally` block
+     * once the stream is exhausted or the consumer breaks out early.
+     *
+     * @param params - Chat completion parameters. `stream` is overridden to `true`.
+     * @param context - Request context for rate-limit keying, logging, and tracing.
+     * @returns An async iterable that yields `ChatCompletionChunk` objects.
+     * @throws {McpError} `RateLimited` if the rate limit is exceeded.
+     * @throws {McpError} `ConfigurationError` if the OpenAI client cannot be initialized.
+     * @throws {McpError} `ServiceUnavailable` if the OpenRouter API call fails.
+     *
+     * @example
+     * ```ts
+     * const stream = await provider.chatCompletionStream(
+     *   { model: 'openai/gpt-4o', messages: [{ role: 'user', content: 'Hello' }] },
+     *   ctx,
+     * );
+     * for await (const chunk of stream) {
+     *   process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+     * }
+     * ```
+     */
+    async chatCompletionStream(params, context) {
+        const streamParams = { ...params, stream: true };
+        const responseStream = (await this.chatCompletion(streamParams, context));
+        const loggingStream = async function* () {
+            const chunks = [];
+            try {
+                for await (const chunk of responseStream) {
+                    chunks.push(chunk);
+                    yield chunk;
+                }
+            }
+            finally {
+                this.logger.logInteraction('OpenRouterResponse', {
+                    context,
+                    response: chunks,
+                    streaming: true,
+                });
+            }
+        }.bind(this)();
+        return loggingStream;
+    }
+}
+//# sourceMappingURL=openrouter.provider.js.map

package/dist/services/llm/providers/openrouter.provider.js.map

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

package/dist/services/llm/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Public type surface for the LLM service layer.
+ * Re-exports shared types from provider interfaces so consumers can import
+ * from a single stable path (`@/services/llm/types`) without coupling to
+ * internal provider modules.
+ * @module src/services/llm/types
+ */
+/**
+ * Parameters accepted by the OpenRouter chat completion endpoint.
+ * Union of streaming and non-streaming variants from the OpenAI SDK
+ * (OpenRouter exposes an OpenAI-compatible API).
+ *
+ * Re-exported from `ILlmProvider` so callers import from one stable location.
+ */
+export type { OpenRouterChatParams } from './core/ILlmProvider.js';
+//# sourceMappingURL=types.d.ts.map

package/dist/services/llm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/llm/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,YAAY,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/services/llm/types.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Public type surface for the LLM service layer.
+ * Re-exports shared types from provider interfaces so consumers can import
+ * from a single stable path (`@/services/llm/types`) without coupling to
+ * internal provider modules.
+ * @module src/services/llm/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/llm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/llm/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/services/speech/core/ISpeechProvider.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Core interface definition for speech service providers.
+ * Provides the contract for Text-to-Speech (TTS) and Speech-to-Text (STT) operations.
+ * @module src/services/speech/core/ISpeechProvider
+ */
+import type { SpeechToTextOptions, SpeechToTextResult, TextToSpeechOptions, TextToSpeechResult, Voice } from '../types.js';
+/**
+ * Main interface for speech service providers.
+ * Providers may implement TTS, STT, or both. Check `supportsTTS` / `supportsSTT`
+ * before calling the corresponding method.
+ */
+export interface ISpeechProvider {
+    /**
+     * Retrieve the list of voices available from this provider.
+     * Only meaningful for TTS providers; STT-only providers should throw.
+     *
+     * @returns Resolved array of available {@link Voice} objects.
+     * @throws {McpError} With `MethodNotFound` if the provider does not support TTS,
+     *   or with `InternalError` / `ServiceUnavailable` if the API call fails.
+     */
+    getVoices(): Promise<Voice[]>;
+    /**
+     * Verify that the provider is reachable and properly configured.
+     * Implementations should perform a lightweight API call (e.g., listing models
+     * or voices) rather than a full synthesis/transcription round-trip.
+     *
+     * @returns `true` if the provider responded successfully, `false` otherwise.
+     *   Never rejects — errors are caught and logged internally.
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * Unique identifier for this provider implementation (e.g. `'elevenlabs'`, `'openai-whisper'`).
+     */
+    readonly name: string;
+    /**
+     * Transcribe audio data to text using this provider.
+     *
+     * @param options - Transcription options including audio data, format, language hint,
+     *   model, temperature, and optional timestamp request.
+     * @returns Resolved {@link SpeechToTextResult} containing the transcript, detected language,
+     *   duration, and optional word-level timestamps.
+     * @throws {McpError} With `MethodNotFound` if the provider does not support STT,
+     *   `InvalidParams` for invalid or oversized audio, or `InternalError` on API failure.
+     */
+    speechToText(options: SpeechToTextOptions): Promise<SpeechToTextResult>;
+    /**
+     * `true` if this provider supports speech-to-text transcription.
+     * Check before calling {@link speechToText}.
+     */
+    readonly supportsSTT: boolean;
+    /**
+     * `true` if this provider supports text-to-speech synthesis.
+     * Check before calling {@link textToSpeech}.
+     */
+    readonly supportsTTS: boolean;
+    /**
+     * Synthesize speech audio from text using this provider.
+     *
+     * @param options - Synthesis options including the text, voice settings, output format,
+     *   language, and model ID.
+     * @returns Resolved {@link TextToSpeechResult} containing audio data as a Buffer,
+     *   character count, format, and provider metadata.
+     * @throws {McpError} With `MethodNotFound` if the provider does not support TTS,
+     *   `InvalidParams` for empty or oversized text, or `InternalError` on API failure.
+     */
+    textToSpeech(options: TextToSpeechOptions): Promise<TextToSpeechResult>;
+}
+/**
+ * Type guard — returns `true` if the provider supports text-to-speech synthesis.
+ *
+ * @param provider - Any `ISpeechProvider` instance.
+ * @returns `true` when `provider.supportsTTS` is set, narrowing the type for callers.
+ *
+ * @example
+ * if (supportsTTS(provider)) {
+ *   const result = await provider.textToSpeech({ text: 'Hello' });
+ * }
+ */
+export declare function supportsTTS(provider: ISpeechProvider): provider is ISpeechProvider;
+/**
+ * Type guard — returns `true` if the provider supports speech-to-text transcription.
+ *
+ * @param provider - Any `ISpeechProvider` instance.
+ * @returns `true` when `provider.supportsSTT` is set, narrowing the type for callers.
+ *
+ * @example
+ * if (supportsSTT(provider)) {
+ *   const result = await provider.speechToText({ audio: buffer });
+ * }
+ */
+export declare function supportsSTT(provider: ISpeechProvider): provider is ISpeechProvider;
+//# sourceMappingURL=ISpeechProvider.d.ts.map

package/dist/services/speech/core/ISpeechProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISpeechProvider.d.ts","sourceRoot":"","sources":["../../../../src/services/speech/core/ISpeechProvider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,EACN,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,SAAS,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IAE9B;;;;;;;OAOG;IACH,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;OASG;IACH,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAExE;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B;;;;;;;;;OASG;IACH,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,QAAQ,IAAI,eAAe,CAElF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,QAAQ,IAAI,eAAe,CAElF"}