@compilr-dev/agents 0.3.21 → 0.3.23

package/dist/providers/claude.d.ts

@@ -45,6 +45,19 @@ export interface ClaudeProviderConfig {
      * @default true
      */
     enablePromptCaching?: boolean;
+    /**
+     * Enable token-efficient tool use (Anthropic beta).
+     * Sends compact tool representation, reducing input tokens.
+     * No-op for Claude 4+ (already default).
+     * @default true
+     */
+    enableTokenEfficientTools?: boolean;
+    /**
+     * Optional token estimator function (e.g., tiktoken).
+     * When provided, debug payload reports token counts instead of char-based estimates.
+     * Fallback: Math.ceil(text.length / 4)
+     */
+    estimateTokens?: (text: string) => number;
 }
 /**
  * ClaudeProvider implements LLMProvider for Anthropic's Claude API
@@ -55,6 +68,8 @@ export declare class ClaudeProvider implements LLMProvider {
     private readonly defaultModel;
     private readonly defaultMaxTokens;
     private readonly enablePromptCaching;
+    private readonly enableTokenEfficientTools;
+    private readonly estimateTokensFn;
     constructor(config: ClaudeProviderConfig);
     /**
      * Send messages and stream the response
@@ -64,6 +79,11 @@ export declare class ClaudeProvider implements LLMProvider {
      * Count tokens in messages using tiktoken (cl100k_base encoding)
      */
     countTokens(messages: Message[]): Promise<number>;
+    /**
+     * Build request options with optional abort signal and beta header.
+     * The token-efficient tools beta reduces schema tokenization for older models.
+     */
+    private buildRequestOptions;
     /**
      * Convert our Message format to Anthropic's format
      */

package/dist/providers/claude.js

@@ -30,6 +30,8 @@ export class ClaudeProvider {
     defaultModel;
     defaultMaxTokens;
     enablePromptCaching;
+    enableTokenEfficientTools;
+    estimateTokensFn;
     constructor(config) {
         this.client = new Anthropic({
             apiKey: config.apiKey,
@@ -38,6 +40,9 @@ export class ClaudeProvider {
         this.defaultModel = config.model ?? DEFAULT_MODEL;
         this.defaultMaxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
         this.enablePromptCaching = config.enablePromptCaching ?? true;
+        this.enableTokenEfficientTools = config.enableTokenEfficientTools ?? true;
+        this.estimateTokensFn =
+            config.estimateTokens ?? ((s) => Math.ceil(s.length / 4));
     }
     /**
      * Send messages and stream the response
@@ -46,11 +51,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)
+        // Calculate payload sizes for debugging (token estimates)
+        const estimate = this.estimateTokensFn;
         const debugPayload = {
-            systemChars: systemPrompt.length,
-            contentsChars: JSON.stringify(anthropicMessages).length,
-            toolsChars: JSON.stringify(tools).length,
+            systemTokens: estimate(systemPrompt),
+            contentsTokens: estimate(JSON.stringify(anthropicMessages)),
+            toolsTokens: estimate(JSON.stringify(tools)),
         };
         try {
             // Determine if prompt caching is enabled
@@ -74,8 +80,8 @@ export class ClaudeProvider {
             if (thinking) {
                 Object.assign(params, { thinking });
             }
-            // Pass abort signal to SDK for immediate cancellation
-            const requestOptions = options?.signal ? { signal: options.signal } : undefined;
+            // Pass abort signal and optional beta header to SDK
+            const requestOptions = this.buildRequestOptions(options?.signal, tools.length > 0);
             const stream = this.client.messages.stream(params, requestOptions);
             const model = options?.model ?? this.defaultModel;
             let currentToolId = '';
@@ -130,6 +136,19 @@ export class ClaudeProvider {
     countTokens(messages) {
         return Promise.resolve(countMessageTokens(messages));
     }
+    /**
+     * Build request options with optional abort signal and beta header.
+     * The token-efficient tools beta reduces schema tokenization for older models.
+     */
+    buildRequestOptions(signal, hasTools) {
+        const needsBeta = this.enableTokenEfficientTools && hasTools;
+        if (!signal && !needsBeta)
+            return undefined;
+        return {
+            ...(signal ? { signal } : {}),
+            ...(needsBeta ? { headers: { 'anthropic-beta': 'token-efficient-tools-2025-02-19' } } : {}),
+        };
+    }
     /**
      * Convert our Message format to Anthropic's format
      */

package/dist/providers/fireworks.d.ts

@@ -34,6 +34,8 @@ export interface FireworksProviderConfig {
     maxTokens?: number;
     /** Request timeout in milliseconds (default: 120000) */
     timeout?: number;
+    /** Optional token estimator (e.g., tiktoken) for debug payload */
+    estimateTokens?: (text: string) => number;
 }
 /**
  * Fireworks AI LLM Provider

package/dist/providers/fireworks.js

@@ -41,6 +41,7 @@ export class FireworksProvider extends OpenAICompatibleProvider {
             model: config.model ?? DEFAULT_MODEL,
             maxTokens: config.maxTokens,
             timeout: config.timeout,
+            estimateTokens: config.estimateTokens,
         };
         super(baseConfig);
         this.apiKey = apiKey;

package/dist/providers/gemini-native.d.ts

@@ -32,6 +32,12 @@ export interface GeminiNativeProviderConfig {
      * @default 4096
      */
     maxTokens?: number;
+    /**
+     * Optional token estimator function (e.g., tiktoken).
+     * When provided, debug payload reports token counts instead of char-based estimates.
+     * Fallback: Math.ceil(text.length / 4)
+     */
+    estimateTokens?: (text: string) => number;
 }
 /**
  * GeminiNativeProvider implements LLMProvider using the native Google Gen AI SDK
@@ -46,6 +52,7 @@ export declare class GeminiNativeProvider implements LLMProvider {
     private readonly client;
     private readonly defaultModel;
     private readonly defaultMaxTokens;
+    private readonly estimateTokensFn;
     constructor(config: GeminiNativeProviderConfig);
     /**
      * Send messages and stream the response

package/dist/providers/gemini-native.js

@@ -37,10 +37,13 @@ export class GeminiNativeProvider {
     client;
     defaultModel;
     defaultMaxTokens;
+    estimateTokensFn;
     constructor(config) {
         this.client = new GoogleGenAI({ apiKey: config.apiKey });
         this.defaultModel = config.model ?? DEFAULT_MODEL;
         this.defaultMaxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
+        this.estimateTokensFn =
+            config.estimateTokens ?? ((s) => Math.ceil(s.length / 4));
     }
     /**
      * Send messages and stream the response
@@ -49,11 +52,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
+        // Calculate payload sizes for debugging (token estimates)
+        const estimate = this.estimateTokensFn;
         const debugPayload = {
-            systemChars: systemInstruction?.length ?? 0,
-            contentsChars: JSON.stringify(contents).length,
-            toolsChars: JSON.stringify(tools).length,
+            systemTokens: estimate(systemInstruction ?? ''),
+            contentsTokens: estimate(JSON.stringify(contents)),
+            toolsTokens: estimate(JSON.stringify(tools)),
         };
         try {
             // Build config

package/dist/providers/groq.d.ts

@@ -34,6 +34,8 @@ export interface GroqProviderConfig {
     maxTokens?: number;
     /** Request timeout in milliseconds (default: 120000) */
     timeout?: number;
+    /** Optional token estimator (e.g., tiktoken) for debug payload */
+    estimateTokens?: (text: string) => number;
 }
 /**
  * Groq LLM Provider

package/dist/providers/groq.js

@@ -41,6 +41,7 @@ export class GroqProvider extends OpenAICompatibleProvider {
             model: config.model ?? DEFAULT_MODEL,
             maxTokens: config.maxTokens,
             timeout: config.timeout,
+            estimateTokens: config.estimateTokens,
         };
         super(baseConfig);
         this.apiKey = apiKey;

package/dist/providers/ollama.d.ts

@@ -34,6 +34,8 @@ export interface OllamaProviderConfig {
     timeout?: number;
     /** Keep alive duration for model in memory (default: '5m') */
     keepAlive?: string;
+    /** Optional token estimator (e.g., tiktoken) for debug payload */
+    estimateTokens?: (text: string) => number;
 }
 /**
  * Ollama LLM Provider

package/dist/providers/ollama.js

@@ -37,6 +37,7 @@ export class OllamaProvider extends OpenAICompatibleProvider {
             model: config.model ?? DEFAULT_MODEL,
             maxTokens: config.maxTokens,
             timeout: config.timeout,
+            estimateTokens: config.estimateTokens,
         };
         super(baseConfig);
         this.keepAlive = config.keepAlive ?? '5m';

package/dist/providers/openai-compatible.d.ts

@@ -102,6 +102,12 @@ export interface OpenAICompatibleConfig {
     maxTokens?: number;
     /** Request timeout in milliseconds (default: 120000) */
     timeout?: number;
+    /**
+     * Optional token estimator function (e.g., tiktoken).
+     * When provided, debug payload reports token counts instead of char-based estimates.
+     * Fallback: Math.ceil(text.length / 4)
+     */
+    estimateTokens?: (text: string) => number;
 }
 /**
  * Abstract base class for OpenAI-compatible LLM providers
@@ -118,6 +124,7 @@ export declare abstract class OpenAICompatibleProvider implements LLMProvider {
     protected readonly defaultModel: string;
     protected readonly defaultMaxTokens: number;
     protected readonly timeout: number;
+    protected readonly estimateTokensFn: (text: string) => number;
     constructor(config: OpenAICompatibleConfig);
     /**
      * Get authentication headers for API requests
@@ -169,6 +176,16 @@ export declare abstract class OpenAICompatibleProvider implements LLMProvider {
      * Convert library messages to OpenAI format
      */
     protected convertMessages(messages: Message[]): OpenAIMessage[];
+    /**
+     * Ensure every assistant tool_call has a matching tool response message.
+     *
+     * OpenAI strictly requires that each tool_call_id in an assistant message
+     * is followed by a tool-role response before the next non-tool message.
+     * This can break after ToolLoopError (partial results) or context
+     * compaction (message reordering). We add synthetic error responses
+     * for any orphaned tool_calls.
+     */
+    protected repairOpenAIToolPairing(messages: OpenAIMessage[]): OpenAIMessage[];
     /**
      * Map library role to OpenAI role
      */

package/dist/providers/openai-compatible.js

@@ -37,11 +37,14 @@ export class OpenAICompatibleProvider {
     defaultModel;
     defaultMaxTokens;
     timeout;
+    estimateTokensFn;
     constructor(config) {
         this.baseUrl = config.baseUrl;
         this.defaultModel = config.model;
         this.defaultMaxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
         this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+        this.estimateTokensFn =
+            config.estimateTokens ?? ((s) => Math.ceil(s.length / 4));
     }
     /**
      * Extract cache statistics from response headers.
@@ -67,14 +70,14 @@ export class OpenAICompatibleProvider {
         const openaiMessages = this.convertMessages(messages);
         // Convert tools if provided
         const tools = options?.tools ? this.convertTools(options.tools) : undefined;
-        // Calculate payload sizes for debugging
-        // Note: OpenAI format has system message in messages array, not separate
+        // Calculate payload sizes for debugging (token estimates)
+        const estimate = this.estimateTokensFn;
         const systemMsg = openaiMessages.find((m) => m.role === 'system');
-        const systemChars = systemMsg && typeof systemMsg.content === 'string' ? systemMsg.content.length : 0;
+        const systemTokens = systemMsg && typeof systemMsg.content === 'string' ? estimate(systemMsg.content) : 0;
         const debugPayload = {
-            systemChars,
-            contentsChars: JSON.stringify(openaiMessages).length,
-            toolsChars: tools ? JSON.stringify(tools).length : 0,
+            systemTokens,
+            contentsTokens: estimate(JSON.stringify(openaiMessages)),
+            toolsTokens: tools ? estimate(JSON.stringify(tools)) : 0,
         };
         // Build request body
         const body = {
@@ -271,7 +274,47 @@ export class OpenAICompatibleProvider {
                 }
             }
         }
-        return result;
+        return this.repairOpenAIToolPairing(result);
+    }
+    /**
+     * Ensure every assistant tool_call has a matching tool response message.
+     *
+     * OpenAI strictly requires that each tool_call_id in an assistant message
+     * is followed by a tool-role response before the next non-tool message.
+     * This can break after ToolLoopError (partial results) or context
+     * compaction (message reordering). We add synthetic error responses
+     * for any orphaned tool_calls.
+     */
+    repairOpenAIToolPairing(messages) {
+        const repaired = [];
+        for (let i = 0; i < messages.length; i++) {
+            const msg = messages[i];
+            repaired.push(msg);
+            // Only check assistant messages with tool_calls
+            if (msg.role !== 'assistant' || !msg.tool_calls || msg.tool_calls.length === 0) {
+                continue;
+            }
+            // Collect expected tool_call_ids
+            const expectedIds = new Set(msg.tool_calls.map((tc) => tc.id));
+            // Push all consecutive tool messages first, tracking which IDs are satisfied
+            while (i + 1 < messages.length && messages[i + 1].role === 'tool') {
+                i++;
+                const toolMsg = messages[i];
+                repaired.push(toolMsg);
+                if (toolMsg.tool_call_id) {
+                    expectedIds.delete(toolMsg.tool_call_id);
+                }
+            }
+            // Add synthetic responses for any missing tool_call_ids
+            for (const missingId of expectedIds) {
+                repaired.push({
+                    role: 'tool',
+                    tool_call_id: missingId,
+                    content: '[Error: Tool execution was interrupted]',
+                });
+            }
+        }
+        return repaired;
     }
     /**
      * Map library role to OpenAI role

package/dist/providers/openai.d.ts

@@ -36,6 +36,8 @@ export interface OpenAIProviderConfig {
     timeout?: number;
     /** OpenAI organization ID (optional) */
     organization?: string;
+    /** Optional token estimator (e.g., tiktoken) for debug payload */
+    estimateTokens?: (text: string) => number;
 }
 /**
  * OpenAI LLM Provider

package/dist/providers/openai.js

@@ -42,6 +42,7 @@ export class OpenAIProvider extends OpenAICompatibleProvider {
             model: config.model ?? DEFAULT_MODEL,
             maxTokens: config.maxTokens,
             timeout: config.timeout,
+            estimateTokens: config.estimateTokens,
         };
         super(baseConfig);
         this.apiKey = apiKey;

package/dist/providers/openrouter.d.ts

@@ -39,6 +39,8 @@ export interface OpenRouterProviderConfig {
     siteUrl?: string;
     /** Site name for OpenRouter rankings (optional) */
     siteName?: string;
+    /** Optional token estimator (e.g., tiktoken) for debug payload */
+    estimateTokens?: (text: string) => number;
 }
 /**
  * OpenRouter LLM Provider

package/dist/providers/openrouter.js

@@ -44,6 +44,7 @@ export class OpenRouterProvider extends OpenAICompatibleProvider {
             model: config.model ?? DEFAULT_MODEL,
             maxTokens: config.maxTokens,
             timeout: config.timeout,
+            estimateTokens: config.estimateTokens,
         };
         super(baseConfig);
         this.apiKey = apiKey;

package/dist/providers/perplexity.d.ts

@@ -34,6 +34,8 @@ export interface PerplexityProviderConfig {
     maxTokens?: number;
     /** Request timeout in milliseconds (default: 120000) */
     timeout?: number;
+    /** Optional token estimator (e.g., tiktoken) for debug payload */
+    estimateTokens?: (text: string) => number;
 }
 /**
  * Perplexity LLM Provider

package/dist/providers/perplexity.js

@@ -41,6 +41,7 @@ export class PerplexityProvider extends OpenAICompatibleProvider {
             model: config.model ?? DEFAULT_MODEL,
             maxTokens: config.maxTokens,
             timeout: config.timeout,
+            estimateTokens: config.estimateTokens,
         };
         super(baseConfig);
         this.apiKey = apiKey;

package/dist/providers/together.d.ts

@@ -34,6 +34,8 @@ export interface TogetherProviderConfig {
     maxTokens?: number;
     /** Request timeout in milliseconds (default: 120000) */
     timeout?: number;
+    /** Optional token estimator (e.g., tiktoken) for debug payload */
+    estimateTokens?: (text: string) => number;
 }
 /**
  * Together AI LLM Provider

package/dist/providers/together.js

@@ -41,6 +41,7 @@ export class TogetherProvider extends OpenAICompatibleProvider {
             model: config.model ?? DEFAULT_MODEL,
             maxTokens: config.maxTokens,
             timeout: config.timeout,
+            estimateTokens: config.estimateTokens,
         };
         super(baseConfig);
         this.apiKey = apiKey;

package/dist/providers/types.d.ts

@@ -72,11 +72,11 @@ export interface LLMUsage {
     cacheCreationTokens?: number;
     /** Thinking tokens (Gemini 2.5+ models with thinking) */
     thinkingTokens?: number;
-    /** Debug payload info - estimated char counts before sending to provider */
+    /** Debug payload info - estimated token counts before sending to provider */
     debugPayload?: {
-        systemChars: number;
-        contentsChars: number;
-        toolsChars: number;
+        systemTokens: number;
+        contentsTokens: number;
+        toolsTokens: number;
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/agents",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",