@compilr-dev/agents 0.3.1 → 0.3.2

package/dist/messages/index.js

@@ -156,39 +156,77 @@ export function normalizeMessages(messages) {
 /**
  * Repair tool use/result pairing issues in a message array.
  *
- * This function removes orphaned tool_result blocks (those without a matching tool_use)
- * which can cause API errors like "function_response.name: Name cannot be empty" in Gemini.
+ * This function handles BOTH types of orphans with POSITIONAL requirements:
+ * 1. Orphaned tool_result blocks (those without a matching tool_use BEFORE them)
+ *    - Causes: "function_response.name: Name cannot be empty" in Gemini
+ * 2. Orphaned tool_use blocks (those without tool_result in IMMEDIATELY NEXT message)
+ *    - Causes: "tool_use ids were found without tool_result blocks" in Claude
  *
- * This is particularly useful after context compaction/summarization, which may remove
- * tool_use messages while preserving tool_result messages in the "recent" window.
+ * CRITICAL: Claude API requires tool_result to be in the IMMEDIATELY NEXT message
+ * after the assistant message containing tool_use. This function validates that
+ * positional requirement, not just existence anywhere in the array.
+ *
+ * This is particularly useful after context compaction/summarization, which may
+ * remove messages and break tool_use/tool_result pairing.
  *
  * @param messages - Array of messages to repair
- * @returns New array with orphaned tool_results removed
+ * @returns New array with orphaned tool_use and tool_result blocks removed
  */
 export function repairToolPairing(messages) {
-    // First, collect all tool_use IDs
-    const toolUseIds = new Set();
-    for (const message of messages) {
+    // First pass: collect all tool_use IDs that appear BEFORE their tool_result
+    // Also track which tool_use IDs have their result in the IMMEDIATELY NEXT message
+    const validToolUseIds = new Set();
+    const allToolUseIds = new Set();
+    for (let i = 0; i < messages.length; i++) {
+        const message = messages[i];
         if (typeof message.content === 'string')
             continue;
-        for (const block of message.content) {
-            if (block.type === 'tool_use') {
-                toolUseIds.add(block.id);
+        // Check for tool_use blocks in assistant messages
+        if (message.role === 'assistant') {
+            const toolUseIdsInThisMessage = [];
+            for (const block of message.content) {
+                if (block.type === 'tool_use') {
+                    toolUseIdsInThisMessage.push(block.id);
+                    allToolUseIds.add(block.id);
+                }
+            }
+            // Check if the NEXT message contains tool_result for ALL these tool_use IDs
+            if (toolUseIdsInThisMessage.length > 0) {
+                // Next message may not exist if we're at the end of the array
+                const nextMessage = messages[i + 1];
+                if (nextMessage && typeof nextMessage.content !== 'string') {
+                    const toolResultIdsInNext = new Set();
+                    for (const block of nextMessage.content) {
+                        if (block.type === 'tool_result') {
+                            toolResultIdsInNext.add(block.toolUseId);
+                        }
+                    }
+                    // Mark tool_use IDs as valid only if their result is in the next message
+                    for (const id of toolUseIdsInThisMessage) {
+                        if (toolResultIdsInNext.has(id)) {
+                            validToolUseIds.add(id);
+                        }
+                    }
+                }
             }
         }
     }
-    // Now filter out orphaned tool_results
+    // Second pass: filter out orphaned blocks
     const repairedMessages = [];
     for (const message of messages) {
         if (typeof message.content === 'string') {
             repairedMessages.push(message);
             continue;
         }
-        // Filter content blocks to remove orphaned tool_results
+        // Filter content blocks to remove orphaned tool_use and tool_result
         const filteredBlocks = message.content.filter((block) => {
             if (block.type === 'tool_result') {
-                // Only keep if there's a matching tool_use
-                return toolUseIds.has(block.toolUseId);
+                // Only keep if there's a valid matching tool_use (that also has its result properly placed)
+                return validToolUseIds.has(block.toolUseId);
+            }
+            if (block.type === 'tool_use') {
+                // Only keep if this tool_use has its result in the immediately next message
+                return validToolUseIds.has(block.id);
             }
             return true;
         });

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

@@ -0,0 +1,86 @@
+/**
+ * GeminiNativeProvider - Native Google Gen AI SDK implementation
+ *
+ * Uses the native @google/genai SDK instead of OpenAI-compatible endpoint.
+ * This enables proper support for Gemini 3 models with thought signatures.
+ *
+ * @example
+ * ```typescript
+ * const provider = new GeminiNativeProvider({
+ *   apiKey: process.env.GOOGLE_AI_API_KEY,
+ * });
+ *
+ * const agent = new Agent({ provider });
+ * ```
+ */
+import type { LLMProvider, Message, ChatOptions, StreamChunk } from './types.js';
+/**
+ * Configuration for GeminiNativeProvider
+ */
+export interface GeminiNativeProviderConfig {
+    /**
+     * Google AI API key
+     */
+    apiKey: string;
+    /**
+     * Default model to use
+     * @default 'gemini-2.5-flash'
+     */
+    model?: string;
+    /**
+     * Default max tokens
+     * @default 4096
+     */
+    maxTokens?: number;
+}
+/**
+ * GeminiNativeProvider implements LLMProvider using the native Google Gen AI SDK
+ *
+ * Benefits over OpenAI-compatible endpoint:
+ * - Automatic thought signature handling for Gemini 3
+ * - Native streaming support
+ * - Full access to Gemini-specific features
+ */
+export declare class GeminiNativeProvider implements LLMProvider {
+    readonly name = "gemini";
+    private readonly client;
+    private readonly defaultModel;
+    private readonly defaultMaxTokens;
+    constructor(config: GeminiNativeProviderConfig);
+    /**
+     * Send messages and stream the response
+     */
+    chat(messages: Message[], options?: ChatOptions): AsyncIterable<StreamChunk>;
+    /**
+     * Count tokens in messages (approximation)
+     */
+    countTokens(messages: Message[]): Promise<number>;
+    /**
+     * Convert our Message format to Google's format
+     */
+    private convertMessages;
+    /**
+     * Convert content to Google's Part format
+     */
+    private convertContent;
+    /**
+     * Extract tool name from tool_use block that matches the given toolUseId
+     */
+    private extractToolName;
+    /**
+     * Convert our ToolDefinition to Google's FunctionDeclaration format
+     */
+    private convertTools;
+    /**
+     * Process a streaming chunk into StreamChunks
+     */
+    private processChunk;
+    /**
+     * Map errors to ProviderError
+     */
+    private mapError;
+}
+/**
+ * Create a GeminiNativeProvider with API key from environment
+ */
+export declare function createGeminiNativeProvider(config?: Partial<GeminiNativeProviderConfig>): GeminiNativeProvider;

package/dist/providers/gemini-native.js

@@ -0,0 +1,339 @@
+/**
+ * GeminiNativeProvider - Native Google Gen AI SDK implementation
+ *
+ * Uses the native @google/genai SDK instead of OpenAI-compatible endpoint.
+ * This enables proper support for Gemini 3 models with thought signatures.
+ *
+ * @example
+ * ```typescript
+ * const provider = new GeminiNativeProvider({
+ *   apiKey: process.env.GOOGLE_AI_API_KEY,
+ * });
+ *
+ * const agent = new Agent({ provider });
+ * ```
+ */
+import { GoogleGenAI } from '@google/genai';
+import { ProviderError } from '../errors.js';
+/**
+ * Default model for Gemini API
+ */
+const DEFAULT_MODEL = 'gemini-2.5-flash';
+/**
+ * Default max tokens
+ */
+const DEFAULT_MAX_TOKENS = 4096;
+/**
+ * GeminiNativeProvider implements LLMProvider using the native Google Gen AI SDK
+ *
+ * Benefits over OpenAI-compatible endpoint:
+ * - Automatic thought signature handling for Gemini 3
+ * - Native streaming support
+ * - Full access to Gemini-specific features
+ */
+export class GeminiNativeProvider {
+    name = 'gemini';
+    client;
+    defaultModel;
+    defaultMaxTokens;
+    constructor(config) {
+        this.client = new GoogleGenAI({ apiKey: config.apiKey });
+        this.defaultModel = config.model ?? DEFAULT_MODEL;
+        this.defaultMaxTokens = config.maxTokens ?? DEFAULT_MAX_TOKENS;
+    }
+    /**
+     * Send messages and stream the response
+     */
+    async *chat(messages, options) {
+        const { systemInstruction, contents } = this.convertMessages(messages);
+        const tools = this.convertTools(options?.tools);
+        const model = options?.model ?? this.defaultModel;
+        try {
+            // Build config
+            const config = {
+                systemInstruction,
+                maxOutputTokens: options?.maxTokens ?? this.defaultMaxTokens,
+                temperature: options?.temperature,
+                stopSequences: options?.stopSequences,
+            };
+            // Add tools if any
+            if (tools.length > 0) {
+                config.tools = [{ functionDeclarations: tools }];
+            }
+            // Request streaming response
+            const streamResponse = await this.client.models.generateContentStream({
+                model,
+                contents,
+                config,
+            });
+            // Track state for tool calls
+            let currentToolId = '';
+            let currentToolName = '';
+            let toolInputJson = '';
+            let inThinkingBlock = false;
+            // Process stream chunks
+            for await (const chunk of streamResponse) {
+                const streamChunks = this.processChunk(chunk, currentToolId, currentToolName, toolInputJson, inThinkingBlock);
+                for (const streamChunk of streamChunks) {
+                    // Update tracking state
+                    if (streamChunk.type === 'tool_use_start' && streamChunk.toolUse) {
+                        currentToolId = streamChunk.toolUse.id;
+                        currentToolName = streamChunk.toolUse.name;
+                        toolInputJson = '';
+                    }
+                    else if (streamChunk.type === 'tool_use_delta' && streamChunk.text) {
+                        toolInputJson += streamChunk.text;
+                    }
+                    else if (streamChunk.type === 'tool_use_end') {
+                        currentToolId = '';
+                        currentToolName = '';
+                        toolInputJson = '';
+                    }
+                    else if (streamChunk.type === 'thinking_start') {
+                        inThinkingBlock = true;
+                    }
+                    else if (streamChunk.type === 'thinking_end') {
+                        inThinkingBlock = false;
+                    }
+                    yield streamChunk;
+                }
+                // Check for usage in the final chunk
+                if (chunk.usageMetadata) {
+                    yield {
+                        type: 'done',
+                        model,
+                        usage: {
+                            inputTokens: chunk.usageMetadata.promptTokenCount ?? 0,
+                            outputTokens: chunk.usageMetadata.candidatesTokenCount ?? 0,
+                        },
+                    };
+                }
+            }
+        }
+        catch (error) {
+            throw this.mapError(error);
+        }
+    }
+    /**
+     * Count tokens in messages (approximation)
+     */
+    countTokens(messages) {
+        // Approximation: ~4 characters 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) {
+                    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 Google's format
+     */
+    convertMessages(messages) {
+        let systemInstruction;
+        const contents = [];
+        for (const msg of messages) {
+            if (msg.role === 'system') {
+                // Google uses systemInstruction in config, not a message
+                systemInstruction = typeof msg.content === 'string' ? msg.content : '';
+            }
+            else {
+                // user → user, assistant → model
+                const role = msg.role === 'assistant' ? 'model' : 'user';
+                const parts = this.convertContent(msg.content);
+                contents.push({ role, parts });
+            }
+        }
+        return { systemInstruction, contents };
+    }
+    /**
+     * Convert content to Google's Part format
+     */
+    convertContent(content) {
+        if (typeof content === 'string') {
+            return [{ text: content }];
+        }
+        return content.map((block) => {
+            switch (block.type) {
+                case 'text':
+                    return { text: block.text };
+                case 'tool_use':
+                    // Convert to functionCall with thought signature if present
+                    // Gemini 3 requires thought signatures on function calls
+                    return {
+                        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':
+                    // Convert to functionResponse
+                    return {
+                        functionResponse: {
+                            id: block.toolUseId,
+                            name: this.extractToolName(content, block.toolUseId),
+                            response: { result: block.content },
+                        },
+                    };
+                case 'thinking':
+                    // Pass through thinking with signature if present
+                    return {
+                        text: block.thinking,
+                        thought: true,
+                        thoughtSignature: block.signature,
+                    };
+                default: {
+                    // Exhaustive check
+                    const _exhaustive = block;
+                    throw new Error(`Unknown content block type: ${_exhaustive.type}`);
+                }
+            }
+        });
+    }
+    /**
+     * Extract tool name from tool_use block that matches the given toolUseId
+     */
+    extractToolName(content, toolUseId) {
+        for (const block of content) {
+            if (block.type === 'tool_use' && block.id === toolUseId) {
+                return block.name;
+            }
+        }
+        // Fallback if not found in same message - this shouldn't happen normally
+        return 'unknown_function';
+    }
+    /**
+     * Convert our ToolDefinition to Google's FunctionDeclaration format
+     */
+    convertTools(tools) {
+        if (!tools || tools.length === 0) {
+            return [];
+        }
+        return tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            // Use parametersJsonSchema for raw JSON schema (more flexible than typed Schema)
+            parametersJsonSchema: {
+                type: 'object',
+                properties: tool.inputSchema.properties,
+                required: tool.inputSchema.required,
+            },
+        }));
+    }
+    /**
+     * Process a streaming chunk into StreamChunks
+     */
+    processChunk(chunk, _currentToolId, _currentToolName, _toolInputJson, inThinkingBlock) {
+        const chunks = [];
+        // Get the first candidate's content
+        const candidate = chunk.candidates?.[0];
+        if (!candidate?.content?.parts) {
+            return chunks;
+        }
+        for (const part of candidate.content.parts) {
+            // Text content
+            if (part.text !== undefined && !part.thought) {
+                chunks.push({
+                    type: 'text',
+                    text: part.text,
+                });
+            }
+            // Thinking content (Gemini 3)
+            if (part.thought && part.text !== undefined) {
+                if (!inThinkingBlock) {
+                    chunks.push({ type: 'thinking_start' });
+                }
+                chunks.push({
+                    type: 'thinking_delta',
+                    text: part.text,
+                    thinking: {
+                        thinking: part.text,
+                        signature: part.thoughtSignature,
+                    },
+                });
+            }
+            // Function call
+            if (part.functionCall) {
+                const funcCall = part.functionCall;
+                const toolId = funcCall.id ?? `tool_${String(Date.now())}_${Math.random().toString(36).slice(2, 9)}`;
+                // Capture thought signature if present (Gemini 3 attaches it to function calls)
+                // Note: thoughtSignature is not in the SDK types yet but exists on the response
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+                const signature = part.thoughtSignature;
+                chunks.push({
+                    type: 'tool_use_start',
+                    toolUse: {
+                        id: toolId,
+                        name: funcCall.name ?? 'unknown',
+                        signature, // Pass through the thought signature
+                    },
+                });
+                // Emit the arguments as delta
+                if (funcCall.args) {
+                    chunks.push({
+                        type: 'tool_use_delta',
+                        text: JSON.stringify(funcCall.args),
+                    });
+                }
+                chunks.push({ type: 'tool_use_end' });
+            }
+        }
+        // Check for finish reason to end thinking block
+        if (inThinkingBlock && candidate.finishReason) {
+            chunks.push({ type: 'thinking_end' });
+        }
+        return chunks;
+    }
+    /**
+     * Map errors to ProviderError
+     */
+    mapError(error) {
+        if (error instanceof Error) {
+            const message = error.message;
+            // Check for common error patterns
+            if (message.includes('API key')) {
+                return new ProviderError('Invalid Gemini API key. Check your GOOGLE_AI_API_KEY or GEMINI_API_KEY.', 'gemini', 401, error);
+            }
+            if (message.includes('rate limit') || message.includes('429')) {
+                return new ProviderError('Gemini rate limit exceeded. Please wait and try again.', 'gemini', 429, error);
+            }
+            if (message.includes('not found') || message.includes('404')) {
+                return new ProviderError(`Gemini model not found: ${message}`, 'gemini', 404, error);
+            }
+            return new ProviderError(message, 'gemini', undefined, error);
+        }
+        return new ProviderError(String(error), 'gemini');
+    }
+}
+/**
+ * Create a GeminiNativeProvider with API key from environment
+ */
+export function createGeminiNativeProvider(config) {
+    const apiKey = config?.apiKey ?? process.env.GOOGLE_AI_API_KEY ?? process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+        throw new ProviderError('Gemini API key not found. Set GOOGLE_AI_API_KEY or GEMINI_API_KEY environment variable or pass apiKey in config.', 'gemini');
+    }
+    return new GeminiNativeProvider({
+        ...config,
+        apiKey,
+    });
+}

package/dist/providers/index.d.ts

@@ -12,5 +12,10 @@ export { OpenAICompatibleProvider } from './openai-compatible.js';
 export type { OpenAICompatibleConfig, OpenAIMessage, OpenAIToolCall, OpenAITool, OpenAIStreamChunk, } from './openai-compatible.js';
 export { OpenAIProvider, createOpenAIProvider } from './openai.js';
 export type { OpenAIProviderConfig } from './openai.js';
-export { GeminiProvider, createGeminiProvider } from './gemini.js';
-export type { GeminiProviderConfig } from './gemini.js';
+export { GeminiProvider as GeminiLegacyProvider, createGeminiProvider as createGeminiLegacyProvider, } from './gemini.js';
+export type { GeminiProviderConfig as GeminiLegacyProviderConfig } from './gemini.js';
+export { GeminiNativeProvider, createGeminiNativeProvider } from './gemini-native.js';
+export type { GeminiNativeProviderConfig } from './gemini-native.js';
+export { GeminiNativeProvider as GeminiProvider } from './gemini-native.js';
+export { createGeminiNativeProvider as createGeminiProvider } from './gemini-native.js';
+export type { GeminiNativeProviderConfig as GeminiProviderConfig } from './gemini-native.js';

package/dist/providers/index.js

@@ -11,5 +11,10 @@ export { OllamaProvider, createOllamaProvider } from './ollama.js';
 export { OpenAICompatibleProvider } from './openai-compatible.js';
 // OpenAI provider
 export { OpenAIProvider, createOpenAIProvider } from './openai.js';
-// Gemini provider
-export { GeminiProvider, createGeminiProvider } from './gemini.js';
+// Gemini provider (legacy OpenAI-compatible endpoint)
+export { GeminiProvider as GeminiLegacyProvider, createGeminiProvider as createGeminiLegacyProvider, } from './gemini.js';
+// Gemini native provider (recommended - supports Gemini 3 thought signatures)
+export { GeminiNativeProvider, createGeminiNativeProvider } from './gemini-native.js';
+// Re-export native as default Gemini provider
+export { GeminiNativeProvider as GeminiProvider } from './gemini-native.js';
+export { createGeminiNativeProvider as createGeminiProvider } from './gemini-native.js';

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)
@@ -75,6 +81,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;

package/dist/state/agent-state.js

@@ -22,6 +22,7 @@ export function createEmptyState(sessionId, systemPrompt) {
         systemPrompt,
         todos: [],
         currentIteration: 0,
+        turnCount: 0,
         totalTokensUsed: 0,
         createdAt: now,
         updatedAt: now,
@@ -40,6 +41,7 @@ export function createAgentState(options) {
         model: options.model,
         todos: serializeTodos(options.todos),
         currentIteration: options.currentIteration,
+        turnCount: options.turnCount,
         totalTokensUsed: options.totalTokensUsed,
         createdAt: options.createdAt || now,
         updatedAt: now,

package/dist/state/serializer.js

@@ -34,7 +34,11 @@ export class JsonSerializer {
             throw StateError.deserialization('Invalid JSON format', error instanceof Error ? error : undefined);
         }
         this.validateParsed(parsed);
-        return parsed;
+        // Ensure turnCount has a default value for backward compatibility
+        // with saved states from before turnCount was added (pre-v2 states)
+        const partialState = parsed;
+        const turnCount = partialState.turnCount ?? partialState.messages.filter((m) => m.role === 'user').length;
+        return { ...partialState, turnCount };
     }
     /**
      * Validate state before serialization (public interface method).
@@ -77,6 +81,11 @@ export class JsonSerializer {
         if (typeof state.version !== 'number') {
             throw StateError.invalidState('version must be a number');
         }
+        // turnCount is optional for backward compatibility
+        // (old saved states may not have it)
+        if (state.turnCount !== undefined && typeof state.turnCount !== 'number') {
+            throw StateError.invalidState('turnCount must be a number if present');
+        }
         // Version check - safe to cast since we validated it's a number
         const version = state.version;
         if (version > CURRENT_STATE_VERSION) {
@@ -119,7 +128,11 @@ export class CompactJsonSerializer {
             throw StateError.deserialization('Invalid JSON format', error instanceof Error ? error : undefined);
         }
         this.validateParsed(parsed);
-        return parsed;
+        // Ensure turnCount has a default value for backward compatibility
+        // with saved states from before turnCount was added (pre-v2 states)
+        const partialState = parsed;
+        const turnCount = partialState.turnCount ?? partialState.messages.filter((m) => m.role === 'user').length;
+        return { ...partialState, turnCount };
     }
     /**
      * Validate state before serialization (public interface method).
@@ -159,6 +172,11 @@ export class CompactJsonSerializer {
         if (typeof state.version !== 'number') {
             throw StateError.invalidState('version must be a number');
         }
+        // turnCount is optional for backward compatibility
+        // (old saved states may not have it)
+        if (state.turnCount !== undefined && typeof state.turnCount !== 'number') {
+            throw StateError.invalidState('turnCount must be a number if present');
+        }
         // Version check - safe to cast since we validated it's a number
         const version = state.version;
         if (version > CURRENT_STATE_VERSION) {

package/dist/state/types.d.ts

@@ -35,6 +35,11 @@ export interface AgentState {
      * Current iteration count
      */
     currentIteration: number;
+    /**
+     * Number of conversation turns (user + assistant exchanges)
+     * Used by context manager to track recent vs old messages for compaction.
+     */
+    turnCount: number;
     /**
      * Total tokens used in the session
      */