@compilr-dev/agents 0.3.1 → 0.3.4

package/dist/providers/openrouter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * OpenRouter LLM Provider
+ *
+ * Implements LLMProvider interface for OpenRouter's unified API.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createOpenRouterProvider({
+ *   model: 'anthropic/claude-3.5-sonnet',
+ *   apiKey: process.env.OPENROUTER_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid OpenRouter API key
+ * - Default model is meta-llama/llama-3.1-8b-instruct
+ * - Provides access to 100+ models from multiple providers
+ * - Includes custom headers for ranking and attribution
+ */
+import type { ChatOptions } from './types.js';
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+/**
+ * Configuration for OpenRouterProvider
+ */
+export interface OpenRouterProviderConfig {
+    /** OpenRouter API key (falls back to OPENROUTER_API_KEY env var) */
+    apiKey?: string;
+    /** Base URL for OpenRouter API (default: https://openrouter.ai/api) */
+    baseUrl?: string;
+    /** Default model to use (default: meta-llama/llama-3.1-8b-instruct) */
+    model?: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+    /** Site URL for OpenRouter rankings (optional) */
+    siteUrl?: string;
+    /** Site name for OpenRouter rankings (optional) */
+    siteName?: string;
+}
+/**
+ * OpenRouter LLM Provider
+ *
+ * Provides streaming chat completion via OpenRouter's unified API.
+ * Access 100+ models from Claude, GPT, Llama, Mistral, and more.
+ */
+export declare class OpenRouterProvider extends OpenAICompatibleProvider {
+    readonly name = "openrouter";
+    private readonly apiKey;
+    private readonly siteUrl?;
+    private readonly siteName?;
+    constructor(config?: OpenRouterProviderConfig);
+    /**
+     * OpenRouter authentication with Bearer token and custom headers
+     */
+    protected getAuthHeaders(): Record<string, string>;
+    /**
+     * OpenRouter chat completions endpoint (OpenAI-compatible)
+     */
+    protected getEndpointPath(): string;
+    /**
+     * OpenRouter uses standard OpenAI body format
+     */
+    protected buildProviderSpecificBody(_options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP errors with OpenRouter-specific messages
+     */
+    protected mapHttpError(status: number, body: string, _model: string): ProviderError;
+    /**
+     * Map connection errors with OpenRouter-specific messages
+     */
+    protected mapConnectionError(_error: Error): ProviderError;
+}
+/**
+ * Create an OpenRouter provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (OPENROUTER_API_KEY)
+ * const provider = createOpenRouterProvider();
+ *
+ * // With explicit API key
+ * const provider = createOpenRouterProvider({ apiKey: 'sk-or-...' });
+ *
+ * // With custom model and site attribution
+ * const provider = createOpenRouterProvider({
+ *   model: 'anthropic/claude-3.5-sonnet',
+ *   siteUrl: 'https://myapp.com',
+ *   siteName: 'My App'
+ * });
+ * ```
+ */
+export declare function createOpenRouterProvider(config?: OpenRouterProviderConfig): OpenRouterProvider;

package/dist/providers/openrouter.js

@@ -0,0 +1,138 @@
+/**
+ * OpenRouter LLM Provider
+ *
+ * Implements LLMProvider interface for OpenRouter's unified API.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createOpenRouterProvider({
+ *   model: 'anthropic/claude-3.5-sonnet',
+ *   apiKey: process.env.OPENROUTER_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid OpenRouter API key
+ * - Default model is meta-llama/llama-3.1-8b-instruct
+ * - Provides access to 100+ models from multiple providers
+ * - Includes custom headers for ranking and attribution
+ */
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+// Default configuration
+const DEFAULT_MODEL = 'meta-llama/llama-3.1-8b-instruct';
+const DEFAULT_BASE_URL = 'https://openrouter.ai/api';
+/**
+ * OpenRouter LLM Provider
+ *
+ * Provides streaming chat completion via OpenRouter's unified API.
+ * Access 100+ models from Claude, GPT, Llama, Mistral, and more.
+ */
+export class OpenRouterProvider extends OpenAICompatibleProvider {
+    name = 'openrouter';
+    apiKey;
+    siteUrl;
+    siteName;
+    constructor(config = {}) {
+        const apiKey = config.apiKey ?? process.env.OPENROUTER_API_KEY;
+        if (!apiKey) {
+            throw new ProviderError('OpenRouter API key not found. Set OPENROUTER_API_KEY environment variable or pass apiKey in config.', 'openrouter');
+        }
+        const baseConfig = {
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            model: config.model ?? DEFAULT_MODEL,
+            maxTokens: config.maxTokens,
+            timeout: config.timeout,
+        };
+        super(baseConfig);
+        this.apiKey = apiKey;
+        this.siteUrl = config.siteUrl;
+        this.siteName = config.siteName;
+    }
+    /**
+     * OpenRouter authentication with Bearer token and custom headers
+     */
+    getAuthHeaders() {
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        // OpenRouter-specific headers for ranking and attribution
+        if (this.siteUrl) {
+            headers['HTTP-Referer'] = this.siteUrl;
+        }
+        if (this.siteName) {
+            headers['X-Title'] = this.siteName;
+        }
+        return headers;
+    }
+    /**
+     * OpenRouter chat completions endpoint (OpenAI-compatible)
+     */
+    getEndpointPath() {
+        return '/v1/chat/completions';
+    }
+    /**
+     * OpenRouter uses standard OpenAI body format
+     */
+    buildProviderSpecificBody(_options) {
+        return {};
+    }
+    /**
+     * Map HTTP errors with OpenRouter-specific messages
+     */
+    mapHttpError(status, body, _model) {
+        let message = `OpenRouter error (${String(status)})`;
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed.error?.message) {
+                message = parsed.error.message;
+            }
+        }
+        catch {
+            message = body || message;
+        }
+        switch (status) {
+            case 401:
+                return new ProviderError('Invalid OpenRouter API key. Check your OPENROUTER_API_KEY.', 'openrouter', 401);
+            case 403:
+                return new ProviderError('Access denied. Check your OpenRouter API key permissions or credits.', 'openrouter', 403);
+            case 429:
+                return new ProviderError('OpenRouter rate limit exceeded. Please wait and try again.', 'openrouter', 429);
+            case 500:
+            case 502:
+            case 503:
+                return new ProviderError('OpenRouter service temporarily unavailable. Please try again later.', 'openrouter', status);
+            default:
+                return new ProviderError(message, 'openrouter', status);
+        }
+    }
+    /**
+     * Map connection errors with OpenRouter-specific messages
+     */
+    mapConnectionError(_error) {
+        return new ProviderError('Failed to connect to OpenRouter API. Check your internet connection.', 'openrouter');
+    }
+}
+/**
+ * Create an OpenRouter provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (OPENROUTER_API_KEY)
+ * const provider = createOpenRouterProvider();
+ *
+ * // With explicit API key
+ * const provider = createOpenRouterProvider({ apiKey: 'sk-or-...' });
+ *
+ * // With custom model and site attribution
+ * const provider = createOpenRouterProvider({
+ *   model: 'anthropic/claude-3.5-sonnet',
+ *   siteUrl: 'https://myapp.com',
+ *   siteName: 'My App'
+ * });
+ * ```
+ */
+export function createOpenRouterProvider(config = {}) {
+    return new OpenRouterProvider(config);
+}

package/dist/providers/perplexity.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Perplexity LLM Provider
+ *
+ * Implements LLMProvider interface for Perplexity models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createPerplexityProvider({
+ *   model: 'llama-3.1-sonar-large-128k-online',
+ *   apiKey: process.env.PERPLEXITY_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Perplexity API key
+ * - Default model is llama-3.1-sonar-small-128k-online
+ * - Sonar models have built-in web search capabilities
+ */
+import type { ChatOptions } from './types.js';
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+/**
+ * Configuration for PerplexityProvider
+ */
+export interface PerplexityProviderConfig {
+    /** Perplexity API key (falls back to PERPLEXITY_API_KEY env var) */
+    apiKey?: string;
+    /** Base URL for Perplexity API (default: https://api.perplexity.ai) */
+    baseUrl?: string;
+    /** Default model to use (default: llama-3.1-sonar-small-128k-online) */
+    model?: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+}
+/**
+ * Perplexity LLM Provider
+ *
+ * Provides streaming chat completion using Perplexity's API.
+ * Sonar models include real-time web search capabilities.
+ */
+export declare class PerplexityProvider extends OpenAICompatibleProvider {
+    readonly name = "perplexity";
+    private readonly apiKey;
+    constructor(config?: PerplexityProviderConfig);
+    /**
+     * Perplexity authentication with Bearer token
+     */
+    protected getAuthHeaders(): Record<string, string>;
+    /**
+     * Perplexity chat completions endpoint (OpenAI-compatible)
+     */
+    protected getEndpointPath(): string;
+    /**
+     * Perplexity uses standard OpenAI body format
+     */
+    protected buildProviderSpecificBody(_options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP errors with Perplexity-specific messages
+     */
+    protected mapHttpError(status: number, body: string, _model: string): ProviderError;
+    /**
+     * Map connection errors with Perplexity-specific messages
+     */
+    protected mapConnectionError(_error: Error): ProviderError;
+}
+/**
+ * Create a Perplexity provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (PERPLEXITY_API_KEY)
+ * const provider = createPerplexityProvider();
+ *
+ * // With explicit API key
+ * const provider = createPerplexityProvider({ apiKey: 'pplx-...' });
+ *
+ * // With custom model (sonar models have web search)
+ * const provider = createPerplexityProvider({
+ *   model: 'llama-3.1-sonar-large-128k-online'
+ * });
+ * ```
+ */
+export declare function createPerplexityProvider(config?: PerplexityProviderConfig): PerplexityProvider;

package/dist/providers/perplexity.js

@@ -0,0 +1,123 @@
+/**
+ * Perplexity LLM Provider
+ *
+ * Implements LLMProvider interface for Perplexity models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createPerplexityProvider({
+ *   model: 'llama-3.1-sonar-large-128k-online',
+ *   apiKey: process.env.PERPLEXITY_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Perplexity API key
+ * - Default model is llama-3.1-sonar-small-128k-online
+ * - Sonar models have built-in web search capabilities
+ */
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+// Default configuration
+const DEFAULT_MODEL = 'llama-3.1-sonar-small-128k-online';
+const DEFAULT_BASE_URL = 'https://api.perplexity.ai';
+/**
+ * Perplexity LLM Provider
+ *
+ * Provides streaming chat completion using Perplexity's API.
+ * Sonar models include real-time web search capabilities.
+ */
+export class PerplexityProvider extends OpenAICompatibleProvider {
+    name = 'perplexity';
+    apiKey;
+    constructor(config = {}) {
+        const apiKey = config.apiKey ?? process.env.PERPLEXITY_API_KEY;
+        if (!apiKey) {
+            throw new ProviderError('Perplexity API key not found. Set PERPLEXITY_API_KEY environment variable or pass apiKey in config.', 'perplexity');
+        }
+        const baseConfig = {
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            model: config.model ?? DEFAULT_MODEL,
+            maxTokens: config.maxTokens,
+            timeout: config.timeout,
+        };
+        super(baseConfig);
+        this.apiKey = apiKey;
+    }
+    /**
+     * Perplexity authentication with Bearer token
+     */
+    getAuthHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+    }
+    /**
+     * Perplexity chat completions endpoint (OpenAI-compatible)
+     */
+    getEndpointPath() {
+        return '/chat/completions';
+    }
+    /**
+     * Perplexity uses standard OpenAI body format
+     */
+    buildProviderSpecificBody(_options) {
+        return {};
+    }
+    /**
+     * Map HTTP errors with Perplexity-specific messages
+     */
+    mapHttpError(status, body, _model) {
+        let message = `Perplexity error (${String(status)})`;
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed.error?.message) {
+                message = parsed.error.message;
+            }
+        }
+        catch {
+            message = body || message;
+        }
+        switch (status) {
+            case 401:
+                return new ProviderError('Invalid Perplexity API key. Check your PERPLEXITY_API_KEY.', 'perplexity', 401);
+            case 403:
+                return new ProviderError('Access denied. Check your Perplexity API key permissions.', 'perplexity', 403);
+            case 429:
+                return new ProviderError('Perplexity rate limit exceeded. Please wait and try again.', 'perplexity', 429);
+            case 500:
+            case 502:
+            case 503:
+                return new ProviderError('Perplexity service temporarily unavailable. Please try again later.', 'perplexity', status);
+            default:
+                return new ProviderError(message, 'perplexity', status);
+        }
+    }
+    /**
+     * Map connection errors with Perplexity-specific messages
+     */
+    mapConnectionError(_error) {
+        return new ProviderError('Failed to connect to Perplexity API. Check your internet connection.', 'perplexity');
+    }
+}
+/**
+ * Create a Perplexity provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (PERPLEXITY_API_KEY)
+ * const provider = createPerplexityProvider();
+ *
+ * // With explicit API key
+ * const provider = createPerplexityProvider({ apiKey: 'pplx-...' });
+ *
+ * // With custom model (sonar models have web search)
+ * const provider = createPerplexityProvider({
+ *   model: 'llama-3.1-sonar-large-128k-online'
+ * });
+ * ```
+ */
+export function createPerplexityProvider(config = {}) {
+    return new PerplexityProvider(config);
+}

package/dist/providers/together.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Together AI LLM Provider
+ *
+ * Implements LLMProvider interface for Together AI models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createTogetherProvider({
+ *   model: 'meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo',
+ *   apiKey: process.env.TOGETHER_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Together AI API key
+ * - Default model is meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo
+ * - Supports Llama, Mistral, Qwen, and other open models
+ */
+import type { ChatOptions } from './types.js';
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+/**
+ * Configuration for TogetherProvider
+ */
+export interface TogetherProviderConfig {
+    /** Together AI API key (falls back to TOGETHER_API_KEY env var) */
+    apiKey?: string;
+    /** Base URL for Together API (default: https://api.together.xyz) */
+    baseUrl?: string;
+    /** Default model to use (default: meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo) */
+    model?: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+}
+/**
+ * Together AI LLM Provider
+ *
+ * Provides streaming chat completion using Together AI models.
+ * Supports Llama, Mistral, Qwen, and other open-source models.
+ */
+export declare class TogetherProvider extends OpenAICompatibleProvider {
+    readonly name = "together";
+    private readonly apiKey;
+    constructor(config?: TogetherProviderConfig);
+    /**
+     * Together AI authentication with Bearer token
+     */
+    protected getAuthHeaders(): Record<string, string>;
+    /**
+     * Together AI chat completions endpoint (OpenAI-compatible)
+     */
+    protected getEndpointPath(): string;
+    /**
+     * Together AI uses standard OpenAI body format
+     */
+    protected buildProviderSpecificBody(_options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP errors with Together AI-specific messages
+     */
+    protected mapHttpError(status: number, body: string, _model: string): ProviderError;
+    /**
+     * Map connection errors with Together AI-specific messages
+     */
+    protected mapConnectionError(_error: Error): ProviderError;
+}
+/**
+ * Create a Together AI provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (TOGETHER_API_KEY)
+ * const provider = createTogetherProvider();
+ *
+ * // With explicit API key
+ * const provider = createTogetherProvider({ apiKey: 'xxx-...' });
+ *
+ * // With custom model
+ * const provider = createTogetherProvider({
+ *   model: 'meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo'
+ * });
+ * ```
+ */
+export declare function createTogetherProvider(config?: TogetherProviderConfig): TogetherProvider;

package/dist/providers/together.js

@@ -0,0 +1,123 @@
+/**
+ * Together AI LLM Provider
+ *
+ * Implements LLMProvider interface for Together AI models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createTogetherProvider({
+ *   model: 'meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo',
+ *   apiKey: process.env.TOGETHER_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Together AI API key
+ * - Default model is meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo
+ * - Supports Llama, Mistral, Qwen, and other open models
+ */
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+// Default configuration
+const DEFAULT_MODEL = 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo';
+const DEFAULT_BASE_URL = 'https://api.together.xyz';
+/**
+ * Together AI LLM Provider
+ *
+ * Provides streaming chat completion using Together AI models.
+ * Supports Llama, Mistral, Qwen, and other open-source models.
+ */
+export class TogetherProvider extends OpenAICompatibleProvider {
+    name = 'together';
+    apiKey;
+    constructor(config = {}) {
+        const apiKey = config.apiKey ?? process.env.TOGETHER_API_KEY;
+        if (!apiKey) {
+            throw new ProviderError('Together AI API key not found. Set TOGETHER_API_KEY environment variable or pass apiKey in config.', 'together');
+        }
+        const baseConfig = {
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            model: config.model ?? DEFAULT_MODEL,
+            maxTokens: config.maxTokens,
+            timeout: config.timeout,
+        };
+        super(baseConfig);
+        this.apiKey = apiKey;
+    }
+    /**
+     * Together AI authentication with Bearer token
+     */
+    getAuthHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+    }
+    /**
+     * Together AI chat completions endpoint (OpenAI-compatible)
+     */
+    getEndpointPath() {
+        return '/v1/chat/completions';
+    }
+    /**
+     * Together AI uses standard OpenAI body format
+     */
+    buildProviderSpecificBody(_options) {
+        return {};
+    }
+    /**
+     * Map HTTP errors with Together AI-specific messages
+     */
+    mapHttpError(status, body, _model) {
+        let message = `Together AI error (${String(status)})`;
+        try {
+            const parsed = JSON.parse(body);
+            if (parsed.error?.message) {
+                message = parsed.error.message;
+            }
+        }
+        catch {
+            message = body || message;
+        }
+        switch (status) {
+            case 401:
+                return new ProviderError('Invalid Together AI API key. Check your TOGETHER_API_KEY.', 'together', 401);
+            case 403:
+                return new ProviderError('Access denied. Check your Together AI API key permissions.', 'together', 403);
+            case 429:
+                return new ProviderError('Together AI rate limit exceeded. Please wait and try again.', 'together', 429);
+            case 500:
+            case 502:
+            case 503:
+                return new ProviderError('Together AI service temporarily unavailable. Please try again later.', 'together', status);
+            default:
+                return new ProviderError(message, 'together', status);
+        }
+    }
+    /**
+     * Map connection errors with Together AI-specific messages
+     */
+    mapConnectionError(_error) {
+        return new ProviderError('Failed to connect to Together AI API. Check your internet connection.', 'together');
+    }
+}
+/**
+ * Create a Together AI provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (TOGETHER_API_KEY)
+ * const provider = createTogetherProvider();
+ *
+ * // With explicit API key
+ * const provider = createTogetherProvider({ apiKey: 'xxx-...' });
+ *
+ * // With custom model
+ * const provider = createTogetherProvider({
+ *   model: 'meta-llama/Meta-Llama-3.1-70B-Instruct-Turbo'
+ * });
+ * ```
+ */
+export function createTogetherProvider(config = {}) {
+    return new TogetherProvider(config);
+}

package/dist/providers/types.d.ts

@@ -24,6 +24,12 @@ export interface ToolUseBlock {
     id: string;
     name: string;
     input: Record<string, unknown>;
+    /**
+     * Thought signature for Gemini 3 function calls.
+     * Required for Gemini 3 to maintain reasoning context.
+     * @see https://ai.google.dev/gemini-api/docs/thought-signatures
+     */
+    signature?: string;
 }
 /**
  * Tool result content block (result of a tool call)
@@ -64,6 +70,14 @@ export interface LLMUsage {
     outputTokens: number;
     cacheReadTokens?: number;
     cacheCreationTokens?: number;
+    /** Thinking tokens (Gemini 2.5+ models with thinking) */
+    thinkingTokens?: number;
+    /** Debug payload info - estimated char counts before sending to provider */
+    debugPayload?: {
+        systemChars: number;
+        contentsChars: number;
+        toolsChars: number;
+    };
 }
 /**
  * Streaming chunk types
@@ -75,6 +89,11 @@ export interface StreamChunk {
         id: string;
         name: string;
         input?: Record<string, unknown>;
+        /**
+         * Thought signature for Gemini 3 function calls.
+         * Only present on first function call in each step.
+         */
+        signature?: string;
     };
     /**
      * Thinking block data (for thinking_start/thinking_end)

package/dist/state/agent-state.d.ts

@@ -24,6 +24,7 @@ export declare function createAgentState(options: {
     messages: Message[];
     todos: TodoItem[];
     currentIteration: number;
+    turnCount: number;
     totalTokensUsed: number;
     createdAt?: string;
 }): AgentState;