@sashabogi/foundation 0.1.6 → 0.1.7

package/dist/providers/anthropic.js

@@ -0,0 +1,514 @@
+/**
+ * Anthropic Provider Implementation
+ *
+ * Provider adapter for the Anthropic Claude API.
+ * Handles message formatting, streaming, and tool use for Claude models.
+ *
+ * Supports two access modes:
+ * - 'api': Direct HTTP calls to Anthropic API (requires API key)
+ * - 'session': Delegates to the current Claude Code session (zero-cost, in-process)
+ * - 'auto': Automatically selects the best available mode (session > api)
+ */
+import { BaseProvider } from './base.js';
+// ============================================================================
+// Session Detection
+// ============================================================================
+/**
+ * Check if running inside a Claude Code session.
+ * When true, we can use session delegation instead of API calls.
+ *
+ * @returns true if running in a Claude Code MCP context
+ */
+function isRunningInClaudeSession() {
+    return process.env.CLAUDE_CODE_ENTRY === 'mcp' ||
+        process.env.CLAUDE_CODE_SESSION === 'true';
+}
+// ============================================================================
+// Anthropic Provider
+// ============================================================================
+/**
+ * Anthropic Claude API provider adapter.
+ *
+ * Implements the Provider interface for Anthropic's Claude models.
+ * Handles:
+ * - Message format translation (our format -> Anthropic format)
+ * - Streaming SSE event parsing
+ * - Tool use formatting
+ * - Authentication via x-api-key header
+ */
+export class AnthropicProvider extends BaseProvider {
+    name = 'anthropic';
+    /** Default Anthropic API base URL */
+    DEFAULT_BASE_URL = 'https://api.anthropic.com';
+    /** Required API version header value */
+    API_VERSION = '2023-06-01';
+    /** Default max tokens if not specified in request */
+    DEFAULT_MAX_TOKENS = 4096;
+    /**
+     * Build Anthropic-specific HTTP headers.
+     * Uses x-api-key instead of Bearer token for authentication.
+     */
+    buildHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+            'anthropic-version': this.API_VERSION,
+        };
+        // Anthropic uses x-api-key header instead of Bearer token
+        if (this.config.api_key) {
+            headers['x-api-key'] = this.config.api_key;
+        }
+        // Add any custom headers from config
+        if (this.config.headers) {
+            Object.assign(headers, this.config.headers);
+        }
+        return headers;
+    }
+    /**
+     * Execute a completion request and return the full response.
+     *
+     * Supports two modes:
+     * - API mode (access_mode: 'api'): Direct HTTP calls to Anthropic API
+     * - Session mode (access_mode: 'session'): Delegates to current Claude Code session
+     * - Auto mode (access_mode: 'auto'): Selects best available (session > api)
+     *
+     * @param request - The completion request
+     * @returns Promise resolving to the normalized completion response or session delegation
+     */
+    async complete(request) {
+        const accessMode = this.resolveAccessMode();
+        if (accessMode === 'session') {
+            return this.completeViaSession(request);
+        }
+        // Default: API mode with direct HTTP calls
+        const url = `${this.getBaseUrl(this.DEFAULT_BASE_URL)}/v1/messages`;
+        const anthropicRequest = this.translateRequest(request);
+        const response = await this.makeRequest({
+            method: 'POST',
+            url,
+            headers: this.buildHeaders(),
+            body: anthropicRequest,
+            timeoutMs: request.timeout_ms ?? this.defaultTimeoutMs,
+        });
+        return this.translateResponse(response);
+    }
+    /**
+     * Resolve the effective access mode based on config and environment.
+     *
+     * Priority for 'auto' mode:
+     * 1. session - if running inside Claude Code session
+     * 2. api - if API key is configured
+     *
+     * @returns The resolved access mode to use
+     * @throws Error if no valid access mode is available
+     */
+    resolveAccessMode() {
+        const configMode = this.config.access_mode;
+        if (configMode === 'auto') {
+            // Priority: session > api
+            if (isRunningInClaudeSession()) {
+                return 'session';
+            }
+            if (this.config.api_key) {
+                return 'api';
+            }
+            throw new Error('No valid access mode available. Set ANTHROPIC_API_KEY or run inside Claude Code.');
+        }
+        // Handle explicit session mode
+        if (configMode === 'session') {
+            return 'session';
+        }
+        // Default to API mode
+        return configMode || 'api';
+    }
+    /**
+     * Return a session delegation response instead of making an API call.
+     * The current Claude session will handle the request directly.
+     *
+     * This is the most efficient mode when running inside Claude Code:
+     * - Zero additional API costs (uses current session's quota)
+     * - No subprocess spawning overhead
+     * - Direct integration with the calling Claude instance
+     *
+     * @param request - The completion request
+     * @returns SessionDelegationResponse for the caller to handle
+     */
+    completeViaSession(request) {
+        // Extract the task from messages (last user message)
+        const lastUserMessage = [...request.messages].reverse().find(m => m.role === 'user');
+        const task = typeof lastUserMessage?.content === 'string'
+            ? lastUserMessage.content
+            : lastUserMessage?.content?.map(b => b.type === 'text' ? b.text : '').join('') || '';
+        // Get system prompt from config (system messages are not part of Message type,
+        // they're passed through config.system_prompt by the role resolver)
+        const systemPrompt = this.config.system_prompt || '';
+        // Get role name from config
+        const role = this.config.role_name || 'assistant';
+        return {
+            delegation: true,
+            role,
+            system_prompt: systemPrompt,
+            task,
+            model: request.model,
+            instructions: `You are now acting as the '${role}' agent. Apply the following system prompt as your persona and execute the task.\n\n---\nSYSTEM PROMPT:\n${systemPrompt}\n---\n\nTASK:\n${task}`,
+        };
+    }
+    /**
+     * Execute a streaming completion request.
+     * Yields normalized StreamChunk events as they arrive.
+     *
+     * @param request - The completion request
+     * @returns Async iterable of stream chunks
+     */
+    async *completeStream(request) {
+        const url = `${this.getBaseUrl(this.DEFAULT_BASE_URL)}/v1/messages`;
+        const anthropicRequest = this.translateRequest(request);
+        anthropicRequest.stream = true;
+        const response = await this.makeStreamingRequest({
+            method: 'POST',
+            url,
+            headers: this.buildHeaders(),
+            body: anthropicRequest,
+            timeoutMs: request.timeout_ms ?? this.defaultTimeoutMs,
+            stream: true,
+        });
+        if (!response.body) {
+            throw new Error('Response body is null');
+        }
+        // Parse SSE stream
+        yield* this.parseSSEStream(response.body);
+    }
+    /**
+     * Check if the Anthropic API is available and credentials are valid.
+     *
+     * For each access mode:
+     * - session: Checks if running in Claude Code context
+     * - api: Makes a minimal API request to verify credentials
+     *
+     * @throws Error if the health check fails
+     */
+    async healthCheck() {
+        const accessMode = this.resolveAccessMode();
+        // For session mode, verify we're in a Claude Code context
+        if (accessMode === 'session') {
+            if (!isRunningInClaudeSession()) {
+                throw new Error('Session mode requires running inside a Claude Code session');
+            }
+            return; // In session context, assume healthy
+        }
+        // API mode: Make a minimal request to verify credentials
+        const request = {
+            model: 'claude-3-haiku-20240307',
+            messages: [{ role: 'user', content: 'ping' }],
+            max_tokens: 1,
+        };
+        const url = `${this.getBaseUrl(this.DEFAULT_BASE_URL)}/v1/messages`;
+        const anthropicRequest = this.translateRequest(request);
+        await this.makeRequest({
+            method: 'POST',
+            url,
+            headers: this.buildHeaders(),
+            body: anthropicRequest,
+            timeoutMs: request.timeout_ms ?? this.defaultTimeoutMs,
+        });
+    }
+    /**
+     * Translate our normalized request format to Anthropic's format.
+     *
+     * @param request - Normalized completion request
+     * @returns Anthropic API request body
+     */
+    translateRequest(request) {
+        const anthropicRequest = {
+            model: request.model,
+            messages: this.translateMessages(request.messages),
+            max_tokens: request.max_tokens ?? this.DEFAULT_MAX_TOKENS,
+        };
+        // Add optional parameters
+        if (request.temperature !== undefined) {
+            anthropicRequest.temperature = request.temperature;
+        }
+        // Extract system prompt from messages if present
+        const systemPrompt = this.extractSystemPrompt();
+        if (systemPrompt) {
+            anthropicRequest.system = systemPrompt;
+        }
+        // Translate tools if present
+        if (request.tools && request.tools.length > 0) {
+            anthropicRequest.tools = this.translateTools(request.tools);
+        }
+        if (request.stream) {
+            anthropicRequest.stream = true;
+        }
+        return anthropicRequest;
+    }
+    /**
+     * Translate normalized messages to Anthropic format.
+     * Filters out system messages (handled separately).
+     *
+     * @param messages - Normalized messages
+     * @returns Anthropic-formatted messages
+     */
+    translateMessages(messages) {
+        return messages
+            .filter((msg) => msg.role === 'user' || msg.role === 'assistant')
+            .map((msg) => ({
+            role: msg.role,
+            content: this.translateMessageContent(msg.content),
+        }));
+    }
+    /**
+     * Translate message content to Anthropic format.
+     *
+     * @param content - String or content blocks
+     * @returns Anthropic-formatted content
+     */
+    translateMessageContent(content) {
+        if (typeof content === 'string') {
+            return content;
+        }
+        // Translate content blocks
+        return content.map((block) => this.translateContentBlock(block));
+    }
+    /**
+     * Translate a single content block to Anthropic format.
+     *
+     * @param block - Normalized content block
+     * @returns Anthropic content block
+     */
+    translateContentBlock(block) {
+        switch (block.type) {
+            case 'text':
+                return {
+                    type: 'text',
+                    text: block.text ?? '',
+                };
+            case 'tool_use':
+                return {
+                    type: 'tool_use',
+                    id: block.id ?? '',
+                    name: block.name ?? '',
+                    input: block.input ?? {},
+                };
+            case 'tool_result':
+                return {
+                    type: 'tool_result',
+                    tool_use_id: block.tool_use_id ?? '',
+                    content: block.content ?? '',
+                };
+            default:
+                return {
+                    type: 'text',
+                    text: '',
+                };
+        }
+    }
+    /**
+     * Extract system prompt from messages.
+     * Our format may include it in messages; Anthropic uses a separate parameter.
+     *
+     * @returns System prompt string or undefined
+     */
+    extractSystemPrompt() {
+        // The system prompt should be passed via the role config, not in messages
+        return undefined;
+    }
+    /**
+     * Translate tools to Anthropic format.
+     * Our tool format is already compatible with Anthropic's format.
+     *
+     * @param tools - Normalized tools
+     * @returns Anthropic tool definitions
+     */
+    translateTools(tools) {
+        return tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: tool.input_schema,
+        }));
+    }
+    /**
+     * Translate Anthropic response to our normalized format.
+     *
+     * @param response - Anthropic API response
+     * @returns Normalized completion response
+     */
+    translateResponse(response) {
+        return {
+            id: response.id,
+            content: this.translateResponseContent(response.content),
+            model: response.model,
+            stop_reason: response.stop_reason,
+            usage: this.translateUsage(response.usage),
+        };
+    }
+    /**
+     * Translate Anthropic content blocks to our normalized format.
+     *
+     * @param content - Anthropic content blocks
+     * @returns Normalized content blocks
+     */
+    translateResponseContent(content) {
+        return content.map((block) => {
+            switch (block.type) {
+                case 'text':
+                    return {
+                        type: 'text',
+                        text: block.text ?? '',
+                    };
+                case 'tool_use':
+                    return {
+                        type: 'tool_use',
+                        id: block.id ?? '',
+                        name: block.name ?? '',
+                        input: block.input ?? {},
+                    };
+                case 'tool_result':
+                    return {
+                        type: 'tool_result',
+                        tool_use_id: block.tool_use_id ?? '',
+                        content: block.content ?? '',
+                    };
+                default:
+                    return {
+                        type: 'text',
+                        text: '',
+                    };
+            }
+        });
+    }
+    /**
+     * Translate Anthropic usage info to our normalized format.
+     *
+     * @param usage - Anthropic usage info
+     * @returns Normalized usage info
+     */
+    translateUsage(usage) {
+        const result = {
+            input_tokens: usage.input_tokens,
+            output_tokens: usage.output_tokens,
+        };
+        // Only add cache tokens if they are defined
+        if (usage.cache_creation_input_tokens !== undefined) {
+            result.cache_creation_input_tokens = usage.cache_creation_input_tokens;
+        }
+        if (usage.cache_read_input_tokens !== undefined) {
+            result.cache_read_input_tokens = usage.cache_read_input_tokens;
+        }
+        return result;
+    }
+    /**
+     * Parse Anthropic SSE stream and yield normalized stream chunks.
+     *
+     * @param body - ReadableStream from fetch response
+     * @returns Async generator of normalized stream chunks
+     */
+    async *parseSSEStream(body) {
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                buffer += decoder.decode(value, { stream: true });
+                // Process complete events from buffer
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? ''; // Keep incomplete line in buffer
+                for (const line of lines) {
+                    const trimmedLine = line.trim();
+                    // Skip empty lines and comments
+                    if (!trimmedLine || trimmedLine.startsWith(':')) {
+                        continue;
+                    }
+                    // Parse SSE data line
+                    if (trimmedLine.startsWith('data: ')) {
+                        const data = trimmedLine.slice(6);
+                        // Handle stream end marker
+                        if (data === '[DONE]') {
+                            continue;
+                        }
+                        try {
+                            const event = JSON.parse(data);
+                            const chunk = this.translateStreamEvent(event);
+                            if (chunk) {
+                                yield chunk;
+                            }
+                        }
+                        catch {
+                            // Skip malformed JSON
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /**
+     * Translate an Anthropic SSE event to our normalized StreamChunk format.
+     *
+     * @param event - Anthropic stream event
+     * @returns Normalized stream chunk or undefined to skip
+     */
+    translateStreamEvent(event) {
+        switch (event.type) {
+            case 'content_block_start':
+                return {
+                    type: 'content_block_start',
+                    index: event.index,
+                    content_block: this.translateContentBlockFromStream(event.content_block),
+                };
+            case 'content_block_delta': {
+                const delta = {
+                    type: event.delta.type,
+                };
+                if (event.delta.text !== undefined) {
+                    delta.text = event.delta.text;
+                }
+                return {
+                    type: 'content_block_delta',
+                    index: event.index,
+                    delta,
+                };
+            }
+            case 'message_stop':
+                return {
+                    type: 'message_stop',
+                };
+            // Skip other events (message_start, content_block_stop, ping, etc.)
+            default:
+                return undefined;
+        }
+    }
+    /**
+     * Translate a content block from a stream event.
+     *
+     * @param block - Anthropic content block from stream
+     * @returns Normalized content block
+     */
+    translateContentBlockFromStream(block) {
+        switch (block.type) {
+            case 'text':
+                return {
+                    type: 'text',
+                    text: block.text ?? '',
+                };
+            case 'tool_use':
+                return {
+                    type: 'tool_use',
+                    id: block.id ?? '',
+                    name: block.name ?? '',
+                    input: block.input ?? {},
+                };
+            default:
+                return {
+                    type: 'text',
+                    text: '',
+                };
+        }
+    }
+}
+//# sourceMappingURL=anthropic.js.map

package/dist/providers/anthropic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../src/providers/anthropic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAazC,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E;;;;;GAKG;AACH,SAAS,wBAAwB;IAC/B,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,KAAK;QACvC,OAAO,CAAC,GAAG,CAAC,mBAAmB,KAAK,MAAM,CAAC;AACpD,CAAC;AAuJD,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,OAAO,iBAAkB,SAAQ,YAAY;IACjC,IAAI,GAAG,WAAW,CAAC;IAEnC,qCAAqC;IACpB,gBAAgB,GAAG,2BAA2B,CAAC;IAEhE,wCAAwC;IACvB,WAAW,GAAG,YAAY,CAAC;IAE5C,qDAAqD;IACpC,kBAAkB,GAAG,IAAI,CAAC;IAE3C;;;OAGG;IACgB,YAAY;QAC7B,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;YAClC,mBAAmB,EAAE,IAAI,CAAC,WAAW;SACtC,CAAC;QAEF,0DAA0D;QAC1D,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACxB,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;QAC7C,CAAC;QAED,qCAAqC;QACrC,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACxB,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC9C,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;;;;;OAUG;IACI,KAAK,CAAC,QAAQ,CAAC,OAA0B;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAE5C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;QAED,2CAA2C;QAC3C,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,gBAAgB,CAAC,cAAc,CAAC;QACpE,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAExD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,CAAoB;YACzD,MAAM,EAAE,MAAM;YACd,GAAG;YACH,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE;YAC5B,IAAI,EAAE,gBAAgB;YACtB,SAAS,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,gBAAgB;SACvD,CAAC,CAAC;QAEH,OAAO,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;;;OASG;IACK,iBAAiB;QACvB,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;QAE3C,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;YAC1B,0BAA0B;YAC1B,IAAI,wBAAwB,EAAE,EAAE,CAAC;gBAC/B,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACxB,OAAO,KAAK,CAAC;YACf,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAC;QACtG,CAAC;QAED,+BAA+B;QAC/B,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,sBAAsB;QACtB,OAAO,UAAU,IAAI,KAAK,CAAC;IAC7B,CAAC;IAED;;;;;;;;;;;OAWG;IACK,kBAAkB,CAAC,OAA0B;QACnD,qDAAqD;QACrD,MAAM,eAAe,GAAG,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;QACrF,MAAM,IAAI,GAAG,OAAO,eAAe,EAAE,OAAO,KAAK,QAAQ;YACvD,CAAC,CAAC,eAAe,CAAC,OAAO;YACzB,CAAC,CAAC,eAAe,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QAEvF,+EAA+E;QAC/E,oEAAoE;QACpE,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,IAAI,EAAE,CAAC;QAErD,4BAA4B;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,WAAW,CAAC;QAElD,OAAO;YACL,UAAU,EAAE,IAAI;YAChB,IAAI;YACJ,aAAa,EAAE,YAAY;YAC3B,IAAI;YACJ,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,YAAY,EAAE,8BAA8B,IAAI,4GAA4G,YAAY,mBAAmB,IAAI,EAAE;SAClM,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,CAAC,cAAc,CAAC,OAA0B;QACrD,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,gBAAgB,CAAC,cAAc,CAAC;QACpE,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACxD,gBAAgB,CAAC,MAAM,GAAG,IAAI,CAAC;QAE/B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAC;YAC/C,MAAM,EAAE,MAAM;YACd,GAAG;YACH,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE;YAC5B,IAAI,EAAE,gBAAgB;YACtB,SAAS,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,gBAAgB;YACtD,MAAM,EAAE,IAAI;SACb,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QAC3C,CAAC;QAED,mBAAmB;QACnB,KAAK,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,WAAW;QACtB,MAAM,UAAU,GAAG,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAE5C,0DAA0D;QAC1D,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,wBAAwB,EAAE,EAAE,CAAC;gBAChC,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;YAChF,CAAC;YACD,OAAO,CAAC,qCAAqC;QAC/C,CAAC;QAED,yDAAyD;QACzD,MAAM,OAAO,GAAsB;YACjC,KAAK,EAAE,yBAAyB;YAChC,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;YAC7C,UAAU,EAAE,CAAC;SACd,CAAC;QAEF,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,gBAAgB,CAAC,cAAc,CAAC;QACpE,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAExD,MAAM,IAAI,CAAC,WAAW,CAAoB;YACxC,MAAM,EAAE,MAAM;YACd,GAAG;YACH,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE;YAC5B,IAAI,EAAE,gBAAgB;YACtB,SAAS,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,gBAAgB;SACvD,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACK,gBAAgB,CAAC,OAA0B;QACjD,MAAM,gBAAgB,GAAqB;YACzC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,QAAQ,EAAE,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,QAAQ,CAAC;YAClD,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,kBAAkB;SAC1D,CAAC;QAEF,0BAA0B;QAC1B,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACtC,gBAAgB,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACrD,CAAC;QAED,iDAAiD;QACjD,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAChD,IAAI,YAAY,EAAE,CAAC;YACjB,gBAAgB,CAAC,MAAM,GAAG,YAAY,CAAC;QACzC,CAAC;QAED,6BAA6B;QAC7B,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9C,gBAAgB,CAAC,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9D,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,gBAAgB,CAAC,MAAM,GAAG,IAAI,CAAC;QACjC,CAAC;QAED,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACK,iBAAiB,CAAC,QAAmB;QAC3C,OAAO,QAAQ;aACZ,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC;aAChE,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACb,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,OAAO,EAAE,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,OAAO,CAAC;SACnD,CAAC,CAAC,CAAC;IACR,CAAC;IAED;;;;;OAKG;IACK,uBAAuB,CAC7B,OAAgC;QAEhC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,2BAA2B;QAC3B,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC;IACnE,CAAC;IAED;;;;;OAKG;IACK,qBAAqB,CAAC,KAAmB;QAC/C,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,MAAM;gBACT,OAAO;oBACL,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;iBACvB,CAAC;YAEJ,KAAK,UAAU;gBACb,OAAO;oBACL,IAAI,EAAE,UAAU;oBAChB,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE;oBAClB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;oBACtB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE;iBACzB,CAAC;YAEJ,KAAK,aAAa;gBAChB,OAAO;oBACL,IAAI,EAAE,aAAa;oBACnB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE;oBACpC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;iBAC7B,CAAC;YAEJ;gBACE,OAAO;oBACL,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,EAAE;iBACT,CAAC;QACN,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,mBAAmB;QACzB,0EAA0E;QAC1E,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;;OAMG;IACK,cAAc,CAAC,KAAa;QAClC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC1B,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,YAAY,EAAE,IAAI,CAAC,YAAY;SAChC,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACK,iBAAiB,CAAC,QAA2B;QACnD,OAAO;YACL,EAAE,EAAE,QAAQ,CAAC,EAAE;YACf,OAAO,EAAE,IAAI,CAAC,wBAAwB,CAAC,QAAQ,CAAC,OAAO,CAAC;YACxD,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,KAAK,EAAE,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,KAAK,CAAC;SAC3C,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACK,wBAAwB,CAAC,OAAgC;QAC/D,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAgB,EAAE;YACzC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;gBACnB,KAAK,MAAM;oBACT,OAAO;wBACL,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;qBACvB,CAAC;gBAEJ,KAAK,UAAU;oBACb,OAAO;wBACL,IAAI,EAAE,UAAU;wBAChB,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE;wBAClB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;wBACtB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE;qBACzB,CAAC;gBAEJ,KAAK,aAAa;oBAChB,OAAO;wBACL,IAAI,EAAE,aAAa;wBACnB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE;wBACpC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;qBAC7B,CAAC;gBAEJ;oBACE,OAAO;wBACL,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,EAAE;qBACT,CAAC;YACN,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACK,cAAc,CAAC,KAAiC;QACtD,MAAM,MAAM,GAAc;YACxB,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,aAAa,EAAE,KAAK,CAAC,aAAa;SACnC,CAAC;QAEF,4CAA4C;QAC5C,IAAI,KAAK,CAAC,2BAA2B,KAAK,SAAS,EAAE,CAAC;YACpD,MAAM,CAAC,2BAA2B,GAAG,KAAK,CAAC,2BAA2B,CAAC;QACzE,CAAC;QACD,IAAI,KAAK,CAAC,uBAAuB,KAAK,SAAS,EAAE,CAAC;YAChD,MAAM,CAAC,uBAAuB,GAAG,KAAK,CAAC,uBAAuB,CAAC;QACjE,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;OAKG;IACK,KAAK,CAAC,CAAC,cAAc,CAAC,IAAgC;QAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;QAClC,IAAI,MAAM,GAAG,EAAE,CAAC;QAEhB,IAAI,CAAC;YACH,OAAO,IAAI,EAAE,CAAC;gBACZ,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC5C,IAAI,IAAI,EAAE,CAAC;oBAAA,MAAM;gBAAA,CAAC;gBAElB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;gBAElD,sCAAsC;gBACtC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACjC,MAAM,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,iCAAiC;gBAE7D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;oBACzB,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;oBAEhC,gCAAgC;oBAChC,IAAI,CAAC,WAAW,IAAI,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;wBAChD,SAAS;oBACX,CAAC;oBAED,sBAAsB;oBACtB,IAAI,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;wBACrC,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;wBAElC,2BAA2B;wBAC3B,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;4BACtB,SAAS;wBACX,CAAC;wBAED,IAAI,CAAC;4BACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAyB,CAAC;4BACvD,MAAM,KAAK,GAAG,IAAI,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;4BAC/C,IAAI,KAAK,EAAE,CAAC;gCACV,MAAM,KAAK,CAAC;4BACd,CAAC;wBACH,CAAC;wBAAC,MAAM,CAAC;4BACP,sBAAsB;wBACxB,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,MAAM,CAAC,WAAW,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,oBAAoB,CAAC,KAA2B;QACtD,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,qBAAqB;gBACxB,OAAO;oBACL,IAAI,EAAE,qBAAqB;oBAC3B,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,aAAa,EAAE,IAAI,CAAC,+BAA+B,CAAC,KAAK,CAAC,aAAa,CAAC;iBACzE,CAAC;YAEJ,KAAK,qBAAqB,CAAC,CAAC,CAAC;gBAC3B,MAAM,KAAK,GAAyB;oBAClC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI;iBACvB,CAAC;gBACF,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;oBACnC,KAAK,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC;gBAChC,CAAC;gBACD,OAAO;oBACL,IAAI,EAAE,qBAAqB;oBAC3B,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,KAAK;iBACN,CAAC;YACJ,CAAC;YAED,KAAK,cAAc;gBACjB,OAAO;oBACL,IAAI,EAAE,cAAc;iBACrB,CAAC;YAEJ,oEAAoE;YACpE;gBACE,OAAO,SAAS,CAAC;QACrB,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,+BAA+B,CAAC,KAA4B;QAClE,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,MAAM;gBACT,OAAO;oBACL,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;iBACvB,CAAC;YAEJ,KAAK,UAAU;gBACb,OAAO;oBACL,IAAI,EAAE,UAAU;oBAChB,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE;oBAClB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;oBACtB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE;iBACzB,CAAC;YAEJ;gBACE,OAAO;oBACL,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,EAAE;iBACT,CAAC;QACN,CAAC;IACH,CAAC;CACF"}

package/dist/providers/base.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Base Provider Implementation
+ *
+ * Abstract base class that implements common functionality for all LLM providers.
+ * Handles authentication headers, error handling, timeout management, and
+ * provides the interface that concrete providers must implement.
+ */
+import { type Provider, type ProviderConfig, type CompletionRequest, type CompletionResponse, type SessionDelegationResponse, type StreamChunk } from './types.js';
+/**
+ * Options for making HTTP requests to provider APIs.
+ */
+export interface RequestOptions {
+    /** HTTP method */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Request URL */
+    url: string;
+    /** Request headers */
+    headers: Record<string, string>;
+    /** Request body (will be JSON stringified) */
+    body?: unknown;
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+    /** Whether this is a streaming request */
+    stream?: boolean;
+}
+/**
+ * Error response structure from provider APIs.
+ */
+export interface ProviderErrorResponse {
+    error?: {
+        message?: string;
+        type?: string;
+        code?: string;
+    };
+    message?: string;
+}
+/**
+ * Abstract base class for LLM providers.
+ *
+ * Provides common functionality including:
+ * - Authentication header management
+ * - HTTP request helpers with timeout support
+ * - Standardized error handling
+ * - Response parsing utilities
+ *
+ * Concrete providers must implement:
+ * - complete(): Execute a completion request
+ * - completeStream(): Execute a streaming completion request
+ * - healthCheck(): Verify provider connectivity
+ */
+export declare abstract class BaseProvider implements Provider {
+    /** Provider name identifier */
+    abstract readonly name: string;
+    /** Provider configuration */
+    protected readonly config: ProviderConfig;
+    /** Default timeout in milliseconds (3 minutes for complex LLM operations) */
+    protected readonly defaultTimeoutMs: number;
+    /**
+     * Create a new provider instance.
+     *
+     * @param config - Provider-specific configuration (API keys, URLs, etc.)
+     */
+    constructor(config: ProviderConfig);
+    /**
+     * Execute a completion request and return the full response.
+     * Must be implemented by concrete providers.
+     *
+     * For providers that support session delegation (e.g., Anthropic in 'session' mode),
+     * this may return a SessionDelegationResponse instead of making an API call.
+     *
+     * @param request - The completion request
+     * @returns Promise resolving to the completion response or session delegation
+     */
+    abstract complete(request: CompletionRequest): Promise<CompletionResponse | SessionDelegationResponse>;
+    /**
+     * Execute a streaming completion request.
+     * Must be implemented by concrete providers.
+     *
+     * @param request - The completion request
+     * @returns Async iterable of stream chunks
+     */
+    abstract completeStream(request: CompletionRequest): AsyncIterable<StreamChunk>;
+    /**
+     * Check if the provider is available and configured correctly.
+     * Must be implemented by concrete providers.
+     *
+     * @throws ProviderError if the health check fails
+     */
+    abstract healthCheck(): Promise<void>;
+    /**
+     * Build common HTTP headers for provider requests.
+     * Includes authentication and content-type headers.
+     *
+     * @returns Headers object for HTTP requests
+     */
+    protected buildHeaders(): Record<string, string>;
+    /**
+     * Make an HTTP request to the provider API with timeout support.
+     *
+     * @param options - Request options
+     * @returns Promise resolving to the parsed JSON response
+     * @throws ProviderError for API errors
+     * @throws TimeoutError if the request times out
+     */
+    protected makeRequest<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Make a streaming HTTP request to the provider API.
+     *
+     * @param options - Request options
+     * @returns Response object for streaming
+     * @throws ProviderError for API errors
+     * @throws TimeoutError if the connection times out
+     */
+    protected makeStreamingRequest(options: RequestOptions): Promise<Response>;
+    /**
+     * Handle HTTP error responses from provider APIs.
+     * Throws appropriate error types based on status code.
+     *
+     * @param response - The HTTP response object
+     * @throws RateLimitError for 429 responses
+     * @throws AuthenticationError for 401 responses
+     * @throws ProviderError for other error responses
+     */
+    protected handleErrorResponse(response: Response): Promise<never>;
+    /**
+     * Handle request-level errors (network, timeout, etc.).
+     *
+     * @param error - The caught error
+     * @param timeoutMs - The timeout that was configured
+     * @throws TimeoutError for abort errors
+     * @throws ProviderError for other errors
+     */
+    protected handleRequestError(error: unknown, timeoutMs: number): never;
+    /**
+     * Get the base URL for API requests.
+     * Uses configured base_url or returns the default for the provider.
+     *
+     * @param defaultUrl - Default URL if not configured
+     * @returns The base URL to use for requests
+     */
+    protected getBaseUrl(defaultUrl: string): string;
+    /**
+     * Create an AbortController with a timeout.
+     * Useful for streaming requests where we need to track the controller.
+     *
+     * @param timeoutMs - Timeout in milliseconds
+     * @returns Object containing the controller and a cleanup function
+     */
+    protected createTimeoutController(timeoutMs: number): {
+        controller: AbortController;
+        cleanup: () => void;
+    };
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/providers/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/providers/base.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAKL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC9B,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kBAAkB;IAClB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,kBAAkB;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,8CAA8C;IAC9C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,8BAAsB,YAAa,YAAW,QAAQ;IACpD,+BAA+B;IAC/B,kBAAyB,IAAI,EAAE,MAAM,CAAC;IAEtC,6BAA6B;IAC7B,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAE1C,6EAA6E;IAC7E,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAU;IAErD;;;;OAIG;gBACS,MAAM,EAAE,cAAc;IAIlC;;;;;;;;;OASG;aACa,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,GAAG,yBAAyB,CAAC;IAE7G;;;;;;OAMG;aACa,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,CAAC,WAAW,CAAC;IAEtF;;;;;OAKG;aACa,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAE5C;;;;;OAKG;IACH,SAAS,CAAC,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAkBhD;;;;;;;OAOG;cACa,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IAoCnE;;;;;;;OAOG;cACa,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IAmChF;;;;;;;;OAQG;cACa,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC;IAoCvE;;;;;;;OAOG;IACH,SAAS,CAAC,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,KAAK;IAyBtE;;;;;;OAMG;IACH,SAAS,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIhD;;;;;;OAMG;IACH,SAAS,CAAC,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG;QACpD,UAAU,EAAE,eAAe,CAAC;QAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;KACrB;CASF"}