@compilr-dev/agents 0.3.22 → 0.3.24

package/dist/agent.js

@@ -1700,15 +1700,23 @@ export class Agent {
                     const filterSet = new Set(options.toolFilter);
                     tools = tools.filter((tool) => filterSet.has(tool.name));
                 }
-                // Run beforeLLM hooks (can modify messages and tools)
+                // Run beforeLLM hooks (can modify messages, tools, and system prompt)
                 if (this.hooksManager) {
                     const llmHookResult = await this.hooksManager.runBeforeLLM({
                         ...hookContext,
                         messages,
                         tools,
+                        systemPrompt: systemContent,
                     });
                     messages = llmHookResult.messages;
                     tools = llmHookResult.tools;
+                    // If a hook modified the system prompt, update messages[0]
+                    if (llmHookResult.systemPrompt !== systemContent) {
+                        systemContent = llmHookResult.systemPrompt;
+                        if (messages.length > 0 && messages[0].role === 'system') {
+                            messages[0] = { role: 'system', content: systemContent };
+                        }
+                    }
                 }
                 // Call LLM
                 emit({ type: 'llm_start' });
@@ -1772,6 +1780,7 @@ export class Agent {
                         ...hookContext,
                         messages,
                         tools,
+                        systemPrompt: systemContent,
                         text,
                         toolUses,
                         usage: usage

package/dist/hooks/manager.d.ts

@@ -102,6 +102,7 @@ export declare class HooksManager {
     runBeforeLLM(context: LLMHookContext): Promise<{
         messages: Message[];
         tools: ToolDefinition[];
+        systemPrompt: string;
     }>;
     /**
      * Run after:llm hooks

package/dist/hooks/manager.js

@@ -330,6 +330,7 @@ export class HooksManager {
     async runBeforeLLM(context) {
         let messages = context.messages;
         let tools = context.tools;
+        let systemPrompt = context.systemPrompt;
         for (const registered of this.beforeLLMHooks) {
             const start = Date.now();
             try {
@@ -339,7 +340,7 @@ export class HooksManager {
                     hookId: registered.id,
                     hookName: registered.name,
                 });
-                const result = await registered.hook({ ...context, messages, tools });
+                const result = await registered.hook({ ...context, messages, tools, systemPrompt });
                 this.emitEvent({
                     type: 'hook:completed',
                     hookType: 'beforeLLM',
@@ -353,6 +354,8 @@ export class HooksManager {
                         messages = hookResult.messages;
                     if (hookResult.tools)
                         tools = hookResult.tools;
+                    if (hookResult.systemPrompt !== undefined)
+                        systemPrompt = hookResult.systemPrompt;
                 }
             }
             catch (error) {
@@ -365,7 +368,7 @@ export class HooksManager {
                 });
             }
         }
-        return { messages, tools };
+        return { messages, tools, systemPrompt };
     }
     /**
      * Run after:llm hooks

package/dist/hooks/types.d.ts

@@ -94,6 +94,11 @@ export interface LLMHookContext extends HookContext {
      * Tool definitions available to LLM
      */
     tools: ToolDefinition[];
+    /**
+     * Current system prompt (fully assembled, including anchors).
+     * Hooks can read this and return a modified version in BeforeLLMHookResult.
+     */
+    systemPrompt: string;
 }
 /**
  * Result from before:llm hook that modifies messages or tools
@@ -107,6 +112,11 @@ export interface BeforeLLMHookResult {
      * Modified tools (optional, original used if not provided)
      */
     tools?: ToolDefinition[];
+    /**
+     * Modified system prompt (optional, original used if not provided).
+     * When returned, messages[0] (system message) is updated automatically.
+     */
+    systemPrompt?: string;
 }
 /**
  * Hook called before LLM call.

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

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 = {

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.22",
+  "version": "0.3.24",
   "description": "Lightweight multi-LLM agent library for building CLI AI assistants",
   "type": "module",
   "main": "dist/index.js",