@compilr-dev/agents 0.0.1

package/dist/providers/claude.js

@@ -0,0 +1,348 @@
+/**
+ * ClaudeProvider - Anthropic Claude API implementation
+ *
+ * @example
+ * ```typescript
+ * const provider = new ClaudeProvider({
+ *   apiKey: process.env.ANTHROPIC_API_KEY,
+ * });
+ *
+ * const agent = new Agent({ provider });
+ * ```
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import { ProviderError } from '../errors.js';
+/**
+ * Default model for Claude API
+ */
+const DEFAULT_MODEL = 'claude-sonnet-4-20250514';
+/**
+ * Default max tokens
+ */
+const DEFAULT_MAX_TOKENS = 4096;
+/**
+ * ClaudeProvider implements LLMProvider for Anthropic's Claude API
+ */
+export class ClaudeProvider {
+    name = 'claude';
+    client;
+    defaultModel;
+    defaultMaxTokens;
+    constructor(config) {
+        this.client = new Anthropic({
+            apiKey: config.apiKey,
+            baseURL: config.baseURL,
+        });
+        this.defaultModel = config.model ?? DEFAULT_MODEL;
+        this.defaultMaxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
+    }
+    /**
+     * Send messages and stream the response
+     */
+    async *chat(messages, options) {
+        const { systemPrompt, anthropicMessages } = this.convertMessages(messages);
+        const tools = this.convertTools(options?.tools);
+        const thinking = this.convertThinking(options?.thinking);
+        try {
+            // Build request parameters
+            const params = {
+                model: options?.model ?? this.defaultModel,
+                max_tokens: options?.maxTokens ?? this.defaultMaxTokens,
+                system: systemPrompt,
+                messages: anthropicMessages,
+                tools: tools.length > 0 ? tools : undefined,
+                temperature: options?.temperature,
+                stop_sequences: options?.stopSequences,
+            };
+            // Add thinking if enabled (Claude-specific)
+            // Note: Extended thinking types not yet in SDK, using Object.assign
+            if (thinking) {
+                Object.assign(params, { thinking });
+            }
+            const stream = this.client.messages.stream(params);
+            const model = options?.model ?? this.defaultModel;
+            let currentToolId = '';
+            let currentToolName = '';
+            let inThinkingBlock = false;
+            for await (const event of stream) {
+                const chunks = this.processEvent(event, currentToolId, currentToolName, inThinkingBlock);
+                for (const chunk of chunks) {
+                    // Track current tool for delta events
+                    if (chunk.type === 'tool_use_start' && chunk.toolUse) {
+                        currentToolId = chunk.toolUse.id;
+                        currentToolName = chunk.toolUse.name;
+                    }
+                    else if (chunk.type === 'tool_use_end') {
+                        currentToolId = '';
+                        currentToolName = '';
+                    }
+                    else if (chunk.type === 'thinking_start') {
+                        inThinkingBlock = true;
+                    }
+                    else if (chunk.type === 'thinking_end') {
+                        inThinkingBlock = false;
+                    }
+                    yield chunk;
+                }
+            }
+            // Get final message to extract usage
+            const finalMessage = await stream.finalMessage();
+            const usage = finalMessage.usage;
+            // Access optional cache token fields via type coercion
+            // These fields are present in newer SDK versions but not in the type definitions
+            const usageWithCache = usage;
+            yield {
+                type: 'done',
+                model,
+                usage: {
+                    inputTokens: usage.input_tokens,
+                    outputTokens: usage.output_tokens,
+                    cacheReadTokens: usageWithCache.cache_read_input_tokens,
+                    cacheCreationTokens: usageWithCache.cache_creation_input_tokens,
+                },
+            };
+        }
+        catch (error) {
+            throw this.mapError(error);
+        }
+    }
+    /**
+     * Count tokens in messages (not yet available in SDK v0.30)
+     *
+     * Note: Token counting API is available via Anthropic's beta endpoints
+     * but not yet exposed in the stable SDK. For now, this provides an
+     * approximation based on character count.
+     */
+    countTokens(messages) {
+        // Approximation: ~4 characters per token (rough estimate)
+        let charCount = 0;
+        for (const msg of messages) {
+            if (typeof msg.content === 'string') {
+                charCount += msg.content.length;
+            }
+            else {
+                for (const block of msg.content) {
+                    switch (block.type) {
+                        case 'text':
+                            charCount += block.text.length;
+                            break;
+                        case 'tool_use':
+                            charCount += JSON.stringify(block.input).length;
+                            break;
+                        case 'tool_result':
+                            charCount += block.content.length;
+                            break;
+                    }
+                }
+            }
+        }
+        return Promise.resolve(Math.ceil(charCount / 4));
+    }
+    /**
+     * Convert our Message format to Anthropic's format
+     */
+    convertMessages(messages) {
+        let systemPrompt = '';
+        const anthropicMessages = [];
+        for (const msg of messages) {
+            if (msg.role === 'system') {
+                // Anthropic uses a separate system parameter
+                systemPrompt = typeof msg.content === 'string' ? msg.content : '';
+            }
+            else {
+                // user or assistant role
+                anthropicMessages.push({
+                    role: msg.role,
+                    content: this.convertContent(msg.content),
+                });
+            }
+        }
+        return { systemPrompt, anthropicMessages };
+    }
+    /**
+     * Convert content to Anthropic's content block format
+     */
+    convertContent(content) {
+        if (typeof content === 'string') {
+            return 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.toolUseId,
+                        content: block.content,
+                        is_error: block.isError,
+                    };
+                case 'thinking':
+                    // Thinking blocks are passed through as text for now
+                    // The API expects thinking in a specific format during beta
+                    return { type: 'text', text: `<thinking>${block.thinking}</thinking>` };
+                default: {
+                    // Exhaustive check - this should never happen
+                    const _exhaustive = block;
+                    throw new Error(`Unknown content block type: ${_exhaustive.type}`);
+                }
+            }
+        });
+    }
+    /**
+     * Convert our ToolDefinition to Anthropic's Tool format
+     */
+    convertTools(tools) {
+        if (!tools || tools.length === 0) {
+            return [];
+        }
+        return tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            input_schema: {
+                type: 'object',
+                properties: tool.inputSchema.properties,
+                required: tool.inputSchema.required,
+            },
+        }));
+    }
+    /**
+     * Convert thinking config to Anthropic API format
+     */
+    convertThinking(thinking) {
+        if (!thinking || thinking.type === 'disabled') {
+            return undefined;
+        }
+        // Validate budget_tokens minimum (1024)
+        if (thinking.budgetTokens < 1024) {
+            throw new ProviderError(`Extended thinking budget_tokens must be at least 1024, got ${String(thinking.budgetTokens)}`, 'claude');
+        }
+        return {
+            type: thinking.type,
+            budget_tokens: thinking.budgetTokens,
+        };
+    }
+    /**
+     * Process a stream event into StreamChunks
+     */
+    processEvent(event, currentToolId, _currentToolName, inThinkingBlock) {
+        const chunks = [];
+        switch (event.type) {
+            case 'content_block_start': {
+                // Extended thinking support: cast content_block to check for 'thinking' type
+                const contentBlock = event.content_block;
+                if (event.content_block.type === 'tool_use') {
+                    chunks.push({
+                        type: 'tool_use_start',
+                        toolUse: {
+                            id: event.content_block.id,
+                            name: event.content_block.name,
+                        },
+                    });
+                }
+                else if (contentBlock.type === 'thinking') {
+                    // Extended thinking block started
+                    chunks.push({ type: 'thinking_start' });
+                }
+                break;
+            }
+            case 'content_block_delta':
+                chunks.push(...this.processDelta(event, inThinkingBlock));
+                break;
+            case 'content_block_stop':
+                // Check if we were in a tool use block
+                if (currentToolId) {
+                    chunks.push({ type: 'tool_use_end' });
+                }
+                else if (inThinkingBlock) {
+                    chunks.push({ type: 'thinking_end' });
+                }
+                break;
+            case 'message_stop':
+                // Message complete - done chunk will be yielded after the loop
+                break;
+        }
+        return chunks;
+    }
+    /**
+     * Process a content block delta event
+     */
+    processDelta(event, inThinkingBlock) {
+        const chunks = [];
+        // Cast delta to our extended type that includes thinking deltas
+        const delta = event.delta;
+        switch (delta.type) {
+            case 'text_delta':
+                chunks.push({
+                    type: 'text',
+                    text: delta.text,
+                });
+                break;
+            case 'input_json_delta':
+                chunks.push({
+                    type: 'tool_use_delta',
+                    text: delta.partial_json,
+                });
+                break;
+            case 'thinking_delta':
+                // Extended thinking content delta
+                chunks.push({
+                    type: 'thinking_delta',
+                    text: delta.thinking,
+                    thinking: { thinking: delta.thinking },
+                });
+                break;
+            case 'signature_delta':
+                // Signature for thinking block verification (sent just before content_block_stop)
+                if (inThinkingBlock) {
+                    chunks.push({
+                        type: 'thinking_delta',
+                        thinking: { signature: delta.signature },
+                    });
+                }
+                break;
+        }
+        return chunks;
+    }
+    /**
+     * Map Anthropic SDK errors to ProviderError
+     */
+    mapError(error) {
+        if (error instanceof Anthropic.APIError) {
+            return new ProviderError(error.message, 'claude', error.status, error);
+        }
+        if (error instanceof Anthropic.APIConnectionError) {
+            return new ProviderError(`Connection error: ${error.message}`, 'claude', undefined, error);
+        }
+        if (error instanceof Anthropic.RateLimitError) {
+            return new ProviderError('Rate limit exceeded', 'claude', 429, error);
+        }
+        if (error instanceof Anthropic.AuthenticationError) {
+            return new ProviderError('Authentication failed: Invalid API key', 'claude', 401, error);
+        }
+        if (error instanceof Error) {
+            return new ProviderError(error.message, 'claude', undefined, error);
+        }
+        return new ProviderError(String(error), 'claude');
+    }
+}
+/**
+ * Create a ClaudeProvider with API key from environment
+ */
+export function createClaudeProvider(config) {
+    const apiKey = config?.apiKey ?? process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        throw new ProviderError('Anthropic API key not found. Set ANTHROPIC_API_KEY environment variable or pass apiKey in config.', 'claude');
+    }
+    return new ClaudeProvider({
+        ...config,
+        apiKey,
+    });
+}

package/dist/providers/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Provider exports
+ */
+export * from './types.js';
+export { MockProvider, createMockProvider } from './mock.js';
+export type { MockProviderConfig, MockResponse, MockToolCall } from './mock.js';
+export { ClaudeProvider, createClaudeProvider } from './claude.js';
+export type { ClaudeProviderConfig } from './claude.js';

package/dist/providers/index.js

@@ -0,0 +1,11 @@
+/**
+ * Provider exports
+ */
+export * from './types.js';
+// Mock provider for testing
+export { MockProvider, createMockProvider } from './mock.js';
+// Provider implementations
+export { ClaudeProvider, createClaudeProvider } from './claude.js';
+// Future providers
+// export { OpenAIProvider } from './openai.js';
+// export { GeminiProvider } from './gemini.js';

package/dist/providers/mock.d.ts

@@ -0,0 +1,133 @@
+/**
+ * MockProvider - A test-friendly LLM provider for unit testing
+ *
+ * This provider allows you to define responses in advance, making it
+ * perfect for testing agent behavior without making API calls.
+ *
+ * @example
+ * ```typescript
+ * const mock = new MockProvider();
+ *
+ * // Simple text response
+ * mock.addResponse('Hello, world!');
+ *
+ * // Response with tool call
+ * mock.addResponse({
+ *   text: 'Let me read that file.',
+ *   toolCalls: [{
+ *     id: 'call_1',
+ *     name: 'read_file',
+ *     input: { path: '/test.txt' },
+ *   }],
+ * });
+ *
+ * const agent = new Agent({ provider: mock });
+ * ```
+ */
+import type { LLMProvider, Message, ChatOptions, StreamChunk } from './types.js';
+/**
+ * A tool call in a mock response
+ */
+export interface MockToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/**
+ * A mock thinking block for extended thinking simulation
+ */
+export interface MockThinking {
+    /** The thinking content */
+    thinking: string;
+    /** Optional signature (for verification simulation) */
+    signature?: string;
+}
+/**
+ * A mock response definition
+ */
+export interface MockResponse {
+    /** Text content of the response */
+    text?: string;
+    /** Tool calls to include in the response */
+    toolCalls?: MockToolCall[];
+    /** Extended thinking content (Claude-specific) */
+    thinking?: MockThinking;
+    /** If set, throw this error instead of responding */
+    error?: Error;
+    /** Delay in ms before responding (simulates network latency) */
+    delay?: number;
+}
+/**
+ * Configuration for MockProvider
+ */
+export interface MockProviderConfig {
+    /** Default delay for all responses (ms) */
+    defaultDelay?: number;
+    /** Throw if no responses are queued */
+    throwOnEmpty?: boolean;
+}
+/**
+ * MockProvider for testing agents without API calls.
+ *
+ * Responses are consumed in order (FIFO queue).
+ */
+export declare class MockProvider implements LLMProvider {
+    readonly name = "mock";
+    private readonly responses;
+    private readonly defaultDelay;
+    private readonly throwOnEmpty;
+    private callCount;
+    private readonly callHistory;
+    constructor(config?: MockProviderConfig);
+    /**
+     * Add a response (text string or structured response with tool calls)
+     */
+    addResponse(response: string | MockResponse): this;
+    /**
+     * Add multiple responses at once
+     */
+    addResponses(responses: Array<string | MockResponse>): this;
+    /**
+     * Queue an error to be thrown on the next call
+     */
+    addError(error: Error): this;
+    /**
+     * Get number of times chat() was called
+     */
+    getCallCount(): number;
+    /**
+     * Get the history of all calls made
+     */
+    getCallHistory(): ReadonlyArray<{
+        messages: Message[];
+        options?: ChatOptions;
+    }>;
+    /**
+     * Get the last call made
+     */
+    getLastCall(): {
+        messages: Message[];
+        options?: ChatOptions;
+    } | undefined;
+    /**
+     * Clear all queued responses and call history
+     */
+    reset(): this;
+    /**
+     * Check if there are any queued responses
+     */
+    hasResponses(): boolean;
+    /**
+     * Stream chat response
+     */
+    chat(messages: Message[], options?: ChatOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Count tokens (mock implementation)
+     */
+    countTokens(messages: Message[]): Promise<number>;
+    private sleep;
+}
+/**
+ * Create a MockProvider with initial responses
+ */
+export declare function createMockProvider(responses?: Array<string | MockResponse>, config?: MockProviderConfig): MockProvider;

package/dist/providers/mock.js

@@ -0,0 +1,204 @@
+/**
+ * MockProvider - A test-friendly LLM provider for unit testing
+ *
+ * This provider allows you to define responses in advance, making it
+ * perfect for testing agent behavior without making API calls.
+ *
+ * @example
+ * ```typescript
+ * const mock = new MockProvider();
+ *
+ * // Simple text response
+ * mock.addResponse('Hello, world!');
+ *
+ * // Response with tool call
+ * mock.addResponse({
+ *   text: 'Let me read that file.',
+ *   toolCalls: [{
+ *     id: 'call_1',
+ *     name: 'read_file',
+ *     input: { path: '/test.txt' },
+ *   }],
+ * });
+ *
+ * const agent = new Agent({ provider: mock });
+ * ```
+ */
+import { ProviderError } from '../errors.js';
+/**
+ * MockProvider for testing agents without API calls.
+ *
+ * Responses are consumed in order (FIFO queue).
+ */
+export class MockProvider {
+    name = 'mock';
+    responses = [];
+    defaultDelay;
+    throwOnEmpty;
+    callCount = 0;
+    callHistory = [];
+    constructor(config = {}) {
+        this.defaultDelay = config.defaultDelay ?? 0;
+        this.throwOnEmpty = config.throwOnEmpty ?? true;
+    }
+    /**
+     * Add a response (text string or structured response with tool calls)
+     */
+    addResponse(response) {
+        if (typeof response === 'string') {
+            this.responses.push({ text: response });
+        }
+        else {
+            this.responses.push(response);
+        }
+        return this;
+    }
+    /**
+     * Add multiple responses at once
+     */
+    addResponses(responses) {
+        for (const response of responses) {
+            this.addResponse(response);
+        }
+        return this;
+    }
+    /**
+     * Queue an error to be thrown on the next call
+     */
+    addError(error) {
+        this.responses.push({ error });
+        return this;
+    }
+    /**
+     * Get number of times chat() was called
+     */
+    getCallCount() {
+        return this.callCount;
+    }
+    /**
+     * Get the history of all calls made
+     */
+    getCallHistory() {
+        return this.callHistory;
+    }
+    /**
+     * Get the last call made
+     */
+    getLastCall() {
+        return this.callHistory[this.callHistory.length - 1];
+    }
+    /**
+     * Clear all queued responses and call history
+     */
+    reset() {
+        this.responses.length = 0;
+        this.callHistory.length = 0;
+        this.callCount = 0;
+        return this;
+    }
+    /**
+     * Check if there are any queued responses
+     */
+    hasResponses() {
+        return this.responses.length > 0;
+    }
+    /**
+     * Stream chat response
+     */
+    async *chat(messages, options) {
+        this.callCount++;
+        this.callHistory.push({ messages, options });
+        // Get next response from queue
+        const response = this.responses.shift();
+        if (!response) {
+            if (this.throwOnEmpty) {
+                throw new ProviderError('MockProvider: No responses queued', 'mock');
+            }
+            // Return empty response
+            yield { type: 'done' };
+            return;
+        }
+        // Handle delay
+        const delay = response.delay ?? this.defaultDelay;
+        if (delay > 0) {
+            await this.sleep(delay);
+        }
+        // Handle error
+        if (response.error) {
+            throw response.error;
+        }
+        // Emit thinking blocks (extended thinking simulation)
+        if (response.thinking) {
+            yield { type: 'thinking_start' };
+            yield {
+                type: 'thinking_delta',
+                text: response.thinking.thinking,
+                thinking: {
+                    thinking: response.thinking.thinking,
+                },
+            };
+            if (response.thinking.signature) {
+                yield {
+                    type: 'thinking_delta',
+                    thinking: { signature: response.thinking.signature },
+                };
+            }
+            yield { type: 'thinking_end' };
+        }
+        // Emit text content
+        if (response.text) {
+            yield { type: 'text', text: response.text };
+        }
+        // Emit tool calls
+        if (response.toolCalls && response.toolCalls.length > 0) {
+            for (const toolCall of response.toolCalls) {
+                yield {
+                    type: 'tool_use_start',
+                    toolUse: {
+                        id: toolCall.id,
+                        name: toolCall.name,
+                    },
+                };
+                // Stream the input as JSON
+                const inputJson = JSON.stringify(toolCall.input);
+                yield {
+                    type: 'tool_use_delta',
+                    text: inputJson,
+                };
+                yield { type: 'tool_use_end' };
+            }
+        }
+        yield { type: 'done' };
+    }
+    /**
+     * Count tokens (mock implementation)
+     */
+    countTokens(messages) {
+        // Simple approximation: ~4 chars per token
+        let charCount = 0;
+        for (const msg of messages) {
+            if (typeof msg.content === 'string') {
+                charCount += msg.content.length;
+            }
+            else {
+                for (const block of msg.content) {
+                    if (block.type === 'text') {
+                        charCount += block.text.length;
+                    }
+                }
+            }
+        }
+        return Promise.resolve(Math.ceil(charCount / 4));
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+/**
+ * Create a MockProvider with initial responses
+ */
+export function createMockProvider(responses = [], config) {
+    const provider = new MockProvider(config);
+    provider.addResponses(responses);
+    return provider;
+}