@compilr-dev/agents 0.3.2 → 0.3.4

package/dist/agent.d.ts

@@ -2,7 +2,7 @@
  * Agent - The main class for running AI agents with tool use
  */
 import type { LLMProvider, Message, ChatOptions, StreamChunk } from './providers/types.js';
-import type { Tool, ToolDefinition, ToolRegistry, ToolExecutionResult } from './tools/types.js';
+import type { Tool, ToolDefinition, ToolRegistry, ToolExecutionResult, ToolExecutionContext } from './tools/types.js';
 import type { ContextStats, VerbosityLevel, SmartCompactionResult } from './context/types.js';
 import type { AgentState, Checkpointer, SessionMetadata } from './state/types.js';
 import type { Anchor, AnchorInput, AnchorQueryOptions, AnchorClearOptions, AnchorManagerOptions } from './anchors/types.js';
@@ -589,6 +589,29 @@ export interface RunOptions {
      * ```
      */
     toolFilter?: string[];
+    /**
+     * Callback to provide additional tool execution context.
+     * Called before each tool execution, allowing the caller to inject
+     * abort signals or other context-specific options.
+     *
+     * @example
+     * ```typescript
+     * // Provide abort signal for bash commands (for Ctrl+B backgrounding)
+     * const bashAbortController = new AbortController();
+     * await agent.stream(message, {
+     *   getToolContext: (toolName, toolUseId) => {
+     *     if (toolName === 'bash') {
+     *       return {
+     *         abortSignal: bashAbortController.signal,
+     *         onBackground: (shellId, output) => { ... },
+     *       };
+     *     }
+     *     return {};
+     *   },
+     * });
+     * ```
+     */
+    getToolContext?: (toolName: string, toolUseId: string) => Partial<Omit<ToolExecutionContext, 'toolUseId' | 'onOutput'>>;
 }
 /**
  * Agent run result
@@ -1505,6 +1528,10 @@ export declare class Agent {
      * Get all registered tool definitions
      */
     getToolDefinitions(): ToolDefinition[];
+    /**
+     * Check if a tool is marked as silent (no spinner or result output)
+     */
+    isToolSilent(name: string): boolean;
     /**
      * Run the agent with a user message
      */

package/dist/agent.js

@@ -1422,6 +1422,13 @@ export class Agent {
     getToolDefinitions() {
         return this.toolRegistry.getDefinitions();
     }
+    /**
+     * Check if a tool is marked as silent (no spinner or result output)
+     */
+    isToolSilent(name) {
+        const tool = this.toolRegistry.get(name);
+        return tool?.silent === true;
+    }
     /**
      * Run the agent with a user message
      */
@@ -1429,6 +1436,7 @@ export class Agent {
         let maxIterations = options?.maxIterations ?? this.maxIterations;
         const chatOptions = { ...this.chatOptions, ...options?.chatOptions };
         const signal = options?.signal;
+        const getToolContext = options?.getToolContext;
         // Combined event emitter
         const emit = (event) => {
             this.onEvent?.(event);
@@ -1817,6 +1825,8 @@ export class Agent {
                 }
                 const toolStartTime = Date.now();
                 try {
+                    // Get additional context from caller (e.g., for bash backgrounding)
+                    const additionalContext = getToolContext?.(toolUse.name, toolUse.id) ?? {};
                     const toolContext = {
                         toolUseId: toolUse.id,
                         onOutput: (output, stream) => {
@@ -1828,6 +1838,8 @@ export class Agent {
                                 stream,
                             });
                         },
+                        // Merge in additional context (abortSignal, onBackground, etc.)
+                        ...additionalContext,
                     };
                     result = await this.toolRegistry.execute(toolUse.name, toolInput, toolContext);
                 }

package/dist/index.d.ts

@@ -21,6 +21,16 @@ export { GeminiLegacyProvider, createGeminiLegacyProvider } from './providers/in
 export type { GeminiLegacyProviderConfig } from './providers/index.js';
 export { OpenAICompatibleProvider } from './providers/index.js';
 export type { OpenAICompatibleConfig } from './providers/index.js';
+export { TogetherProvider, createTogetherProvider } from './providers/index.js';
+export type { TogetherProviderConfig } from './providers/index.js';
+export { GroqProvider, createGroqProvider } from './providers/index.js';
+export type { GroqProviderConfig } from './providers/index.js';
+export { FireworksProvider, createFireworksProvider } from './providers/index.js';
+export type { FireworksProviderConfig } from './providers/index.js';
+export { PerplexityProvider, createPerplexityProvider } from './providers/index.js';
+export type { PerplexityProviderConfig } from './providers/index.js';
+export { OpenRouterProvider, createOpenRouterProvider } from './providers/index.js';
+export type { OpenRouterProviderConfig } from './providers/index.js';
 export type { Tool, ToolHandler, ToolRegistry, ToolInputSchema, ToolExecutionResult, ToolRegistryOptions, DefineToolOptions, ReadFileInput, WriteFileInput, BashInput, BashResult, FifoDetectionResult, GrepInput, GlobInput, EditInput, TodoWriteInput, TodoReadInput, TodoItem, TodoStatus, TodoContextCleanupOptions, TaskInput, TaskResult, AgentTypeConfig, TaskToolOptions, ContextMode, ThoroughnessLevel, SubAgentEventInfo, SuggestInput, SuggestToolOptions, } from './tools/index.js';
 export { defineTool, createSuccessResult, createErrorResult, wrapToolExecute, DefaultToolRegistry, createToolRegistry, } from './tools/index.js';
 export { readFileTool, createReadFileTool, writeFileTool, createWriteFileTool, bashTool, createBashTool, execStream, detectFifoUsage, bashOutputTool, createBashOutputTool, killShellTool, createKillShellTool, ShellManager, getDefaultShellManager, setDefaultShellManager, grepTool, createGrepTool, globTool, createGlobTool, editTool, createEditTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, resetDefaultTodoStore, getDefaultTodoStore, createIsolatedTodoStore, cleanupTodoContextMessages, getTodoContextStats, webFetchTool, createWebFetchTool, createTaskTool, defaultAgentTypes, suggestTool, createSuggestTool, builtinTools, allBuiltinTools, TOOL_NAMES, TOOL_SETS, } from './tools/index.js';

package/dist/index.js

@@ -16,6 +16,12 @@ export { GeminiNativeProvider, createGeminiNativeProvider } from './providers/in
 // Legacy Gemini provider (OpenAI-compatible endpoint)
 export { GeminiLegacyProvider, createGeminiLegacyProvider } from './providers/index.js';
 export { OpenAICompatibleProvider } from './providers/index.js';
+// "Others" providers - OpenAI-compatible cloud APIs
+export { TogetherProvider, createTogetherProvider } from './providers/index.js';
+export { GroqProvider, createGroqProvider } from './providers/index.js';
+export { FireworksProvider, createFireworksProvider } from './providers/index.js';
+export { PerplexityProvider, createPerplexityProvider } from './providers/index.js';
+export { OpenRouterProvider, createOpenRouterProvider } from './providers/index.js';
 // Tool utilities
 export { defineTool, createSuccessResult, createErrorResult, wrapToolExecute, DefaultToolRegistry, createToolRegistry, } from './tools/index.js';
 // Built-in tools

package/dist/providers/claude.js

@@ -43,6 +43,12 @@ export class ClaudeProvider {
         const { systemPrompt, anthropicMessages } = this.convertMessages(messages);
         const tools = this.convertTools(options?.tools);
         const thinking = this.convertThinking(options?.thinking);
+        // Calculate payload sizes for debugging (same as gemini-native.ts)
+        const debugPayload = {
+            systemChars: systemPrompt.length,
+            contentsChars: JSON.stringify(anthropicMessages).length,
+            toolsChars: JSON.stringify(tools).length,
+        };
         try {
             // Build request parameters
             const params = {
@@ -99,6 +105,7 @@ export class ClaudeProvider {
                     outputTokens: usage.output_tokens,
                     cacheReadTokens: usageWithCache.cache_read_input_tokens,
                     cacheCreationTokens: usageWithCache.cache_creation_input_tokens,
+                    debugPayload,
                 },
             };
         }

package/dist/providers/fireworks.d.ts

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

package/dist/providers/fireworks.js

@@ -0,0 +1,123 @@
+/**
+ * Fireworks AI LLM Provider
+ *
+ * Implements LLMProvider interface for Fireworks AI models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createFireworksProvider({
+ *   model: 'accounts/fireworks/models/llama-v3p1-70b-instruct',
+ *   apiKey: process.env.FIREWORKS_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Fireworks AI API key
+ * - Default model is accounts/fireworks/models/llama-v3p1-8b-instruct
+ * - Supports Llama, Mixtral, and fine-tuned models
+ */
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+// Default configuration
+const DEFAULT_MODEL = 'accounts/fireworks/models/llama-v3p1-8b-instruct';
+const DEFAULT_BASE_URL = 'https://api.fireworks.ai/inference';
+/**
+ * Fireworks AI LLM Provider
+ *
+ * Provides streaming chat completion using Fireworks AI.
+ * Supports Llama, Mixtral, and custom fine-tuned models.
+ */
+export class FireworksProvider extends OpenAICompatibleProvider {
+    name = 'fireworks';
+    apiKey;
+    constructor(config = {}) {
+        const apiKey = config.apiKey ?? process.env.FIREWORKS_API_KEY;
+        if (!apiKey) {
+            throw new ProviderError('Fireworks AI API key not found. Set FIREWORKS_API_KEY environment variable or pass apiKey in config.', 'fireworks');
+        }
+        const baseConfig = {
+            baseUrl: config.baseUrl ?? DEFAULT_BASE_URL,
+            model: config.model ?? DEFAULT_MODEL,
+            maxTokens: config.maxTokens,
+            timeout: config.timeout,
+        };
+        super(baseConfig);
+        this.apiKey = apiKey;
+    }
+    /**
+     * Fireworks AI authentication with Bearer token
+     */
+    getAuthHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+    }
+    /**
+     * Fireworks AI chat completions endpoint (OpenAI-compatible)
+     */
+    getEndpointPath() {
+        return '/v1/chat/completions';
+    }
+    /**
+     * Fireworks AI uses standard OpenAI body format
+     */
+    buildProviderSpecificBody(_options) {
+        return {};
+    }
+    /**
+     * Map HTTP errors with Fireworks AI-specific messages
+     */
+    mapHttpError(status, body, _model) {
+        let message = `Fireworks 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 Fireworks AI API key. Check your FIREWORKS_API_KEY.', 'fireworks', 401);
+            case 403:
+                return new ProviderError('Access denied. Check your Fireworks AI API key permissions.', 'fireworks', 403);
+            case 429:
+                return new ProviderError('Fireworks AI rate limit exceeded. Please wait and try again.', 'fireworks', 429);
+            case 500:
+            case 502:
+            case 503:
+                return new ProviderError('Fireworks AI service temporarily unavailable. Please try again later.', 'fireworks', status);
+            default:
+                return new ProviderError(message, 'fireworks', status);
+        }
+    }
+    /**
+     * Map connection errors with Fireworks AI-specific messages
+     */
+    mapConnectionError(_error) {
+        return new ProviderError('Failed to connect to Fireworks AI API. Check your internet connection.', 'fireworks');
+    }
+}
+/**
+ * Create a Fireworks AI provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (FIREWORKS_API_KEY)
+ * const provider = createFireworksProvider();
+ *
+ * // With explicit API key
+ * const provider = createFireworksProvider({ apiKey: 'fw_...' });
+ *
+ * // With custom model
+ * const provider = createFireworksProvider({
+ *   model: 'accounts/fireworks/models/llama-v3p1-70b-instruct'
+ * });
+ * ```
+ */
+export function createFireworksProvider(config = {}) {
+    return new FireworksProvider(config);
+}

package/dist/providers/gemini-native.js

@@ -48,6 +48,12 @@ export class GeminiNativeProvider {
         const { systemInstruction, contents } = this.convertMessages(messages);
         const tools = this.convertTools(options?.tools);
         const model = options?.model ?? this.defaultModel;
+        // Calculate payload sizes for debugging
+        const debugPayload = {
+            systemChars: systemInstruction?.length ?? 0,
+            contentsChars: JSON.stringify(contents).length,
+            toolsChars: JSON.stringify(tools).length,
+        };
         try {
             // Build config
             const config = {
@@ -71,6 +77,8 @@ export class GeminiNativeProvider {
             let currentToolName = '';
             let toolInputJson = '';
             let inThinkingBlock = false;
+            // Track the last usage metadata (Gemini sends it in EVERY chunk, not just the final one)
+            let lastUsageMetadata;
             // Process stream chunks
             for await (const chunk of streamResponse) {
                 const streamChunks = this.processChunk(chunk, currentToolId, currentToolName, toolInputJson, inThinkingBlock);
@@ -97,18 +105,32 @@ export class GeminiNativeProvider {
                     }
                     yield streamChunk;
                 }
-                // Check for usage in the final chunk
+                // Track usage metadata (update on every chunk, yield only once at end)
                 if (chunk.usageMetadata) {
-                    yield {
-                        type: 'done',
-                        model,
-                        usage: {
-                            inputTokens: chunk.usageMetadata.promptTokenCount ?? 0,
-                            outputTokens: chunk.usageMetadata.candidatesTokenCount ?? 0,
-                        },
-                    };
+                    lastUsageMetadata = chunk.usageMetadata;
                 }
             }
+            // Yield 'done' only ONCE after stream completes with the final usage
+            if (lastUsageMetadata) {
+                yield {
+                    type: 'done',
+                    model,
+                    usage: {
+                        inputTokens: lastUsageMetadata.promptTokenCount ?? 0,
+                        outputTokens: lastUsageMetadata.candidatesTokenCount ?? 0,
+                        // Gemini 2.5+ models report thinking tokens separately
+                        ...(lastUsageMetadata.thoughtsTokenCount
+                            ? { thinkingTokens: lastUsageMetadata.thoughtsTokenCount }
+                            : {}),
+                        // Gemini reports cached content tokens
+                        ...(lastUsageMetadata.cachedContentTokenCount
+                            ? { cacheReadTokens: lastUsageMetadata.cachedContentTokenCount }
+                            : {}),
+                        // Debug payload info
+                        debugPayload,
+                    },
+                };
+            }
         }
         catch (error) {
             throw this.mapError(error);
@@ -169,45 +191,58 @@ export class GeminiNativeProvider {
         if (typeof content === 'string') {
             return [{ text: content }];
         }
-        return content.map((block) => {
+        const parts = [];
+        for (const block of content) {
             switch (block.type) {
                 case 'text':
-                    return { text: block.text };
+                    parts.push({ text: block.text });
+                    break;
                 case 'tool_use':
                     // Convert to functionCall with thought signature if present
                     // Gemini 3 requires thought signatures on function calls
-                    return {
+                    // Note: No 'id' field - Gemini uses 'name' for matching
+                    parts.push({
                         functionCall: {
-                            id: block.id,
                             name: block.name,
                             args: block.input,
                         },
                         // Include thought signature if present (required for Gemini 3)
                         ...(block.signature ? { thoughtSignature: block.signature } : {}),
-                    };
-                case 'tool_result':
+                    });
+                    break;
+                case 'tool_result': {
                     // Convert to functionResponse
-                    return {
+                    // block.content is a JSON string from the agent - parse it for the API
+                    let responseData;
+                    try {
+                        responseData = JSON.parse(block.content);
+                    }
+                    catch {
+                        // If not valid JSON, wrap the string in a result object
+                        responseData = { result: block.content };
+                    }
+                    parts.push({
                         functionResponse: {
-                            id: block.toolUseId,
+                            // Note: No 'id' field - Gemini matches by 'name' only
                             name: this.extractToolName(content, block.toolUseId),
-                            response: { result: block.content },
+                            response: responseData,
                         },
-                    };
+                    });
+                    break;
+                }
                 case 'thinking':
-                    // Pass through thinking with signature if present
-                    return {
-                        text: block.thinking,
-                        thought: true,
-                        thoughtSignature: block.signature,
-                    };
+                    // Thinking blocks should NOT be sent back to Gemini.
+                    // They are internal model reasoning. Only the signature on function calls matters.
+                    // Skip - do not add to parts.
+                    break;
                 default: {
                     // Exhaustive check
                     const _exhaustive = block;
                     throw new Error(`Unknown content block type: ${_exhaustive.type}`);
                 }
             }
-        });
+        }
+        return parts;
     }
     /**
      * Extract tool name from tool_use block that matches the given toolUseId

package/dist/providers/groq.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Groq LLM Provider
+ *
+ * Implements LLMProvider interface for Groq models.
+ * Extends OpenAICompatibleProvider for shared functionality.
+ *
+ * @example
+ * ```typescript
+ * const provider = createGroqProvider({
+ *   model: 'llama-3.2-90b-vision-preview',
+ *   apiKey: process.env.GROQ_API_KEY
+ * });
+ * ```
+ *
+ * @remarks
+ * - Requires valid Groq API key
+ * - Default model is llama-3.2-8b-preview
+ * - Known for extremely fast inference speeds
+ */
+import type { ChatOptions } from './types.js';
+import { ProviderError } from '../errors.js';
+import { OpenAICompatibleProvider } from './openai-compatible.js';
+/**
+ * Configuration for GroqProvider
+ */
+export interface GroqProviderConfig {
+    /** Groq API key (falls back to GROQ_API_KEY env var) */
+    apiKey?: string;
+    /** Base URL for Groq API (default: https://api.groq.com/openai) */
+    baseUrl?: string;
+    /** Default model to use (default: llama-3.2-8b-preview) */
+    model?: string;
+    /** Default max tokens (default: 4096) */
+    maxTokens?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    timeout?: number;
+}
+/**
+ * Groq LLM Provider
+ *
+ * Provides streaming chat completion using Groq's ultra-fast inference.
+ * Supports Llama, Mixtral, and other models optimized for speed.
+ */
+export declare class GroqProvider extends OpenAICompatibleProvider {
+    readonly name = "groq";
+    private readonly apiKey;
+    constructor(config?: GroqProviderConfig);
+    /**
+     * Groq authentication with Bearer token
+     */
+    protected getAuthHeaders(): Record<string, string>;
+    /**
+     * Groq chat completions endpoint (OpenAI-compatible)
+     */
+    protected getEndpointPath(): string;
+    /**
+     * Groq uses standard OpenAI body format
+     */
+    protected buildProviderSpecificBody(_options?: ChatOptions): Record<string, unknown>;
+    /**
+     * Map HTTP errors with Groq-specific messages
+     */
+    protected mapHttpError(status: number, body: string, _model: string): ProviderError;
+    /**
+     * Map connection errors with Groq-specific messages
+     */
+    protected mapConnectionError(_error: Error): ProviderError;
+}
+/**
+ * Create a Groq provider instance
+ *
+ * @example
+ * ```typescript
+ * // Using environment variable (GROQ_API_KEY)
+ * const provider = createGroqProvider();
+ *
+ * // With explicit API key
+ * const provider = createGroqProvider({ apiKey: 'gsk_...' });
+ *
+ * // With custom model
+ * const provider = createGroqProvider({
+ *   model: 'llama-3.2-90b-vision-preview'
+ * });
+ * ```
+ */
+export declare function createGroqProvider(config?: GroqProviderConfig): GroqProvider;