@orxataguy/tyr 1.0.30 → 1.0.32

package/src/lib/AIVendorManager.ts

@@ -8,25 +8,86 @@ import {getEnvString, getEnvInt, getEnvDouble} from '../core/util/getenv.js';
 export type AIVendor = 'anthropic' | 'openai' | 'gemini';
 export type AIRole = 'system' | 'user' | 'assistant';
 
+/**
+ * Representación normalizada (independiente del vendor) del contenido de un mensaje.
+ *
+ *  - 'text': texto plano.
+ *  - 'tool_use': el modelo pide ejecutar una herramienta. `id` es opaco para el llamador: hay
+ *    que devolverlo tal cual en el `tool_result` correspondiente, sin asumir nada sobre su
+ *    formato (en Gemini, por ejemplo, es un id sintético generado por este manager, ya que la
+ *    API de Gemini no da ids reales para las function calls).
+ *  - 'tool_result': resultado de haber ejecutado una herramienta, para devolvérselo al modelo.
+ *  - 'image': imagen adjunta (p.ej. un attachment de chat). `data` es el contenido en base64 SIN
+ *    el prefijo `data:...;base64,`; `mediaType` es el MIME type (p.ej. 'image/png'). Solo válido
+ *    en mensajes de rol 'user' — los vendors no devuelven imágenes en sus respuestas.
+ */
+export type AIContentBlock =
+    | { type: 'text'; text: string }
+    | { type: 'tool_use'; id: string; name: string; input: any }
+    | { type: 'tool_result'; tool_use_id: string; content: string; is_error?: boolean }
+    | { type: 'image'; mediaType: string; data: string };
+
 export interface AIMessage {
     role: AIRole;
-    content: string;
+    /** Texto plano, o una lista de bloques cuando el mensaje incluye tool_use / tool_result. */
+    content: string | AIContentBlock[];
 }
 
+/** Definición de herramienta en formato JSON-schema al estilo Anthropic; se traduce internamente
+ *  al formato de cada vendor (function-calling de OpenAI, functionDeclarations de Gemini). */
+export interface AITool {
+    name: string;
+    description: string;
+    input_schema: any;
+}
+
+/**
+ * Nivel de "esfuerzo de razonamiento" (extended thinking) pedido al modelo, independiente del
+ * vendor concreto. Se traduce a `thinking.budget_tokens` en Anthropic y a `reasoning_effort` en
+ * los modelos de OpenAI que lo soportan (serie 'o'); Gemini no tiene un equivalente público en
+ * este momento y el valor se ignora silenciosamente para ese vendor.
+ */
+export type ThinkingEffort = 'none' | 'low' | 'medium' | 'high' | 'max';
+
+/** Prioridad de una tarea, usada por resolvePriority()/completeWithPriority() para elegir modelo
+ *  y esfuerzo de razonamiento sin que el llamador tenga que conocer nombres de modelo concretos. */
+export type TaskPriority =
+    | 'baja-prioridad'
+    | 'baja-media-prioridad'
+    | 'media-prioridad'
+    | 'media-alta-prioridad'
+    | 'alta-prioridad'
+    | 'muy-alta-prioridad';
+
 export interface AICompletionOptions {
     vendor?: AIVendor;
     model?: string;
     temperature?: number;
     maxTokens?: number;
     maxRetries?: number;
+    /** Herramientas disponibles para que el modelo las invoque. Solo soportado en complete(),
+     *  no en stream() — ver el guard al inicio de stream(). */
+    tools?: AITool[];
+    /** Nivel de extended thinking / reasoning effort. Ver ThinkingEffort. 'none' (o ausente)
+     *  desactiva el thinking explícitamente. */
+    thinking?: ThinkingEffort;
 }
 
 export interface AICompletionResult {
+    /** Texto plano concatenado de todos los bloques de tipo 'text' (conveniencia; equivalente al
+     *  comportamiento anterior de esta clase, antes de soportar tools). */
     content: string;
+    /** Contenido completo y normalizado, incluyendo bloques tool_use si el modelo pidió alguno.
+     *  Necesario para reconstruir el mensaje de assistant en el siguiente turno de un bucle
+     *  agente. */
+    blocks: AIContentBlock[];
     vendor: AIVendor;
     model: string;
     promptTokens?: number;
     completionTokens?: number;
+    /** Motivo de parada normalizado tal como lo reporta cada vendor (stop_reason / finish_reason
+     *  / finishReason), sin normalizar entre vendors — úsalo solo informativamente. */
+    stopReason?: string;
 }
 
 interface VendorConfig {
@@ -36,6 +97,7 @@ interface VendorConfig {
     temperature: number;
     maxTokens: number;
     maxRetries: number;
+    thinking: ThinkingEffort;
 }
 
 interface VendorRequest {
@@ -61,6 +123,58 @@ const DEFAULT_MAX_TOKENS = 4096;
 const DEFAULT_MAX_RETRIES = 3;
 const RETRY_BASE_DELAY_MS = 500;
 
+// --- Dynamic Model Routing ----------------------------------------------------------------------
+//
+// Three cost/capability tiers per vendor. Each is overridable via env var (AI_MODEL_CHEAP /
+// AI_MODEL_BALANCED / AI_MODEL_FLAGSHIP) so operators can point a tier at a newer model without
+// touching code. 'balanced' matches DEFAULT_MODELS on purpose — it's the vendor's normal default.
+type ModelTier = 'cheap' | 'balanced' | 'flagship';
+
+const MODEL_TIERS: Record<AIVendor, Record<ModelTier, string>> = {
+    anthropic: { cheap: 'claude-haiku-4-5', balanced: 'claude-sonnet-5', flagship: 'claude-opus-4-1' },
+    openai: { cheap: 'gpt-4o-mini', balanced: 'gpt-4o', flagship: 'gpt-4o' },
+    gemini: { cheap: 'gemini-2.5-flash', balanced: 'gemini-2.5-pro', flagship: 'gemini-2.5-pro' },
+};
+
+const MODEL_TIER_ENV: Record<ModelTier, string> = {
+    cheap: 'AI_MODEL_CHEAP',
+    balanced: 'AI_MODEL_BALANCED',
+    flagship: 'AI_MODEL_FLAGSHIP',
+};
+
+/** budget_tokens sent to Anthropic's `thinking` param per effort level. 'none' disables thinking. */
+const THINKING_BUDGETS: Record<ThinkingEffort, number> = {
+    none: 0,
+    low: 1024,
+    medium: 4096,
+    high: 8192,
+    max: 16384,
+};
+
+/**
+ * Task-priority → (model tier, thinking effort) matrix. This is the routing table requested by
+ * the architecture spec: callers pick a priority by *intent* ("this is a trivial file", "this
+ * previous attempt failed"), not by model name, and AIVendorManager decides what that costs.
+ */
+const PRIORITY_ROUTING: Record<TaskPriority, { tier: ModelTier; thinking: ThinkingEffort }> = {
+    'baja-prioridad': { tier: 'cheap', thinking: 'none' },
+    'baja-media-prioridad': { tier: 'cheap', thinking: 'max' },
+    'media-prioridad': { tier: 'balanced', thinking: 'none' },
+    'media-alta-prioridad': { tier: 'balanced', thinking: 'high' },
+    'alta-prioridad': { tier: 'balanced', thinking: 'max' },
+    'muy-alta-prioridad': { tier: 'flagship', thinking: 'max' },
+};
+
+/** Ordered priority ladder, used by bumpPriority() to escalate one level at a time. */
+const PRIORITY_LADDER: TaskPriority[] = [
+    'baja-prioridad',
+    'baja-media-prioridad',
+    'media-prioridad',
+    'media-alta-prioridad',
+    'alta-prioridad',
+    'muy-alta-prioridad',
+];
+
 /**
  * @class AIVendorManager
  * @description Unified client for AI chat-completion APIs (Anthropic, OpenAI, Gemini).
@@ -68,6 +182,12 @@ const RETRY_BASE_DELAY_MS = 500;
  * environment variables / Tyr configuration, retries transient failures with exponential
  * backoff, and supports both blocking and streaming responses.
  *
+ * Tool use (function calling) is supported in `complete()` for all three vendors, behind a
+ * vendor-agnostic representation (`AITool` / `AIContentBlock`). Each vendor's wire format is
+ * different — this class does the translation both ways (request and response) so callers never
+ * need to know which vendor is active. `stream()` does not support tools yet (see the guard at
+ * the top of that method).
+ *
  * Environment variables:
  *   AI_VENDOR          – 'anthropic' | 'openai' | 'gemini' (default: 'anthropic')
  *   ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY – API key for the selected vendor
@@ -112,20 +232,272 @@ export class AIVendorManager {
             temperature: options?.temperature ?? getEnvDouble('AI_TEMPERATURE', DEFAULT_TEMPERATURE),
             maxTokens: options?.maxTokens ?? getEnvInt('AI_MAX_TOKENS', DEFAULT_MAX_TOKENS),
             maxRetries: options?.maxRetries ?? getEnvInt('AI_MAX_RETRIES', DEFAULT_MAX_RETRIES),
+            thinking: options?.thinking ?? 'none',
         };
     }
 
+    /**
+     * @method resolvePriority
+     * @description Translates a TaskPriority into concrete AICompletionOptions (model + thinking
+     * effort) for the currently configured vendor (or the vendor passed in `overrides`), via the
+     * routing matrix in PRIORITY_ROUTING. This is the single place that maps "how important/hard
+     * is this task" to "which model do we pay for" — Manager code should route through this
+     * instead of hardcoding model names.
+     * @param {TaskPriority} priority - One of the six priority levels (see TaskPriority).
+     * @param {AICompletionOptions} overrides - Optional overrides merged on top (e.g. tools, maxTokens).
+     * @returns {AICompletionOptions} Options ready to pass to complete()/stream().
+     * @example
+     * const options = aiVendor.resolvePriority('media-alta-prioridad', { tools: AGENT_TOOLS });
+     * const result = await aiVendor.complete(messages, options);
+     */
+    public resolvePriority(priority: TaskPriority, overrides: AICompletionOptions = {}): AICompletionOptions {
+        const vendor = (overrides.vendor ?? (getEnvString('AI_VENDOR') as AIVendor | undefined) ?? 'anthropic')
+            .toString()
+            .toLowerCase() as AIVendor;
+
+        const route = PRIORITY_ROUTING[priority];
+        if (!route) {
+            throw new TyrError(`Unknown task priority: '${priority}'`, null, `Use one of: ${PRIORITY_LADDER.join(', ')}`);
+        }
+
+        const tierModel = getEnvString(MODEL_TIER_ENV[route.tier]) ?? MODEL_TIERS[vendor][route.tier];
+
+        return {
+            vendor,
+            model: tierModel,
+            thinking: route.thinking,
+            ...overrides,
+        };
+    }
+
+    /**
+     * @method bumpPriority
+     * @description Escalates a priority one level up the ladder (baja-prioridad → ... →
+     * muy-alta-prioridad), capping at the top. Used for self-healing retries: each consecutive
+     * failure (e.g. a broken compile after an applied patch) buys the model more capability.
+     * @param {TaskPriority} priority - The current priority.
+     * @returns {TaskPriority} The next priority level, or the same value if already at the top.
+     * @example
+     * priority = aiVendor.bumpPriority(priority); // one more level of thinking/model tier
+     */
+    public bumpPriority(priority: TaskPriority): TaskPriority {
+        const index = PRIORITY_LADDER.indexOf(priority);
+        if (index === -1 || index === PRIORITY_LADDER.length - 1) return priority;
+        return PRIORITY_LADDER[index + 1];
+    }
+
+    /**
+     * @method completeWithPriority
+     * @description Convenience wrapper around complete() that resolves model + thinking effort
+     * from a TaskPriority first. Equivalent to `complete(messages, resolvePriority(priority, options))`.
+     * @param {AIMessage[]} messages - Conversation messages.
+     * @param {TaskPriority} priority - Routing priority (see TaskPriority).
+     * @param {AICompletionOptions} options - Optional overrides merged on top of the routed defaults.
+     * @returns {Promise<AICompletionResult>}
+     * @example
+     * const result = await aiVendor.completeWithPriority(messages, 'alta-prioridad', { tools });
+     */
+    public async completeWithPriority(
+        messages: AIMessage[],
+        priority: TaskPriority,
+        options: AICompletionOptions = {}
+    ): Promise<AICompletionResult> {
+        return this.complete(messages, this.resolvePriority(priority, options));
+    }
+
     private splitSystem(messages: AIMessage[]): { system: string; turns: AIMessage[] } {
-        const system = messages.filter(m => m.role === 'system').map(m => m.content).join('\n\n');
+        const system = messages
+            .filter(m => m.role === 'system')
+            .map(m => (typeof m.content === 'string' ? m.content : m.content.map(b => (b.type === 'text' ? b.text : '')).join('')))
+            .join('\n\n');
         const turns = messages.filter(m => m.role !== 'system');
         return { system, turns };
     }
 
-    private buildRequest(config: VendorConfig, messages: AIMessage[], stream: boolean): VendorRequest {
-        const { system, turns } = this.splitSystem(messages);
+    // --- Traducción de herramientas por vendor -------------------------------------------------
+
+    private buildVendorTools(config: VendorConfig, tools?: AITool[]): any {
+        if (!tools || tools.length === 0) return undefined;
 
         switch (config.vendor) {
             case 'anthropic':
+                return tools.map(t => ({ name: t.name, description: t.description, input_schema: t.input_schema }));
+            case 'openai':
+                return tools.map(t => ({
+                    type: 'function',
+                    function: { name: t.name, description: t.description, parameters: t.input_schema },
+                }));
+            case 'gemini':
+                return [{ functionDeclarations: tools.map(t => ({ name: t.name, description: t.description, parameters: t.input_schema })) }];
+        }
+    }
+
+    // --- Traducción de mensajes por vendor ------------------------------------------------------
+
+    private toAnthropicContent(content: string | AIContentBlock[]): any {
+        if (typeof content === 'string') return content;
+        return content.map(block => {
+            if (block.type === 'text') return { type: 'text', text: block.text };
+            if (block.type === 'image') return { type: 'image', source: { type: 'base64', media_type: block.mediaType, data: block.data } };
+            if (block.type === 'tool_use') return { type: 'tool_use', id: block.id, name: block.name, input: block.input };
+            return { type: 'tool_result', tool_use_id: block.tool_use_id, content: block.content, ...(block.is_error ? { is_error: true } : {}) };
+        });
+    }
+
+    private buildAnthropicMessages(turns: AIMessage[]): any[] {
+        return turns.map(m => ({ role: m.role, content: this.toAnthropicContent(m.content) }));
+    }
+
+    /**
+     * OpenAI no tiene un bloque "tool_result" dentro de un mensaje de usuario: cada resultado de
+     * herramienta tiene que ir en su propio mensaje con role: 'tool'. Por eso, a diferencia de
+     * Anthropic, un único AIMessage de entrada puede expandirse a varios mensajes de salida.
+     */
+    private buildOpenAIMessages(turns: AIMessage[]): any[] {
+        const result: any[] = [];
+
+        for (const m of turns) {
+            if (typeof m.content === 'string') {
+                result.push({ role: m.role, content: m.content });
+                continue;
+            }
+
+            if (m.role === 'assistant') {
+                const text = m.content.filter(b => b.type === 'text').map(b => (b as any).text).join('');
+                const toolUses = m.content.filter(b => b.type === 'tool_use') as Array<Extract<AIContentBlock, { type: 'tool_use' }>>;
+
+                const msg: any = { role: 'assistant', content: text || null };
+                if (toolUses.length > 0) {
+                    msg.tool_calls = toolUses.map(t => ({
+                        id: t.id,
+                        type: 'function',
+                        function: { name: t.name, arguments: JSON.stringify(t.input ?? {}) },
+                    }));
+                }
+                result.push(msg);
+                continue;
+            }
+
+            const toolResults = m.content.filter(b => b.type === 'tool_result') as Array<Extract<AIContentBlock, { type: 'tool_result' }>>;
+            const text = m.content.filter(b => b.type === 'text').map(b => (b as any).text).join('');
+            const images = m.content.filter(b => b.type === 'image') as Array<Extract<AIContentBlock, { type: 'image' }>>;
+
+            for (const tr of toolResults) {
+                result.push({ role: 'tool', tool_call_id: tr.tool_use_id, content: tr.content });
+            }
+            if (images.length > 0) {
+                const parts: any[] = [];
+                if (text) parts.push({ type: 'text', text });
+                for (const img of images) {
+                    parts.push({ type: 'image_url', image_url: { url: `data:${img.mediaType};base64,${img.data}` } });
+                }
+                result.push({ role: m.role, content: parts });
+            } else if (text) {
+                result.push({ role: m.role, content: text });
+            }
+        }
+
+        return result;
+    }
+
+    /** Busca hacia atrás en TODO el historial (no solo en el turno actual) el nombre de la
+     *  función asociada a un tool_use_id, porque Gemini necesita el `name` en el functionResponse
+     *  y nosotros solo tenemos el id opaco que generamos al parsear la respuesta anterior. */
+    private findToolUseName(allMessages: AIMessage[], toolUseId: string): string | undefined {
+        for (const m of allMessages) {
+            if (!Array.isArray(m.content)) continue;
+            const match = m.content.find(b => b.type === 'tool_use' && b.id === toolUseId) as
+                | Extract<AIContentBlock, { type: 'tool_use' }>
+                | undefined;
+            if (match) return match.name;
+        }
+        return undefined;
+    }
+
+    /**
+     * NOTA: la API pública de Gemini espera los resultados de función en un content con
+     * role: 'function' (parts: [{ functionResponse: { name, response } }]). Esto puede variar
+     * entre versiones de la API — si Google cambia el contrato, este es el único sitio a tocar.
+     */
+    private buildGeminiContents(turns: AIMessage[], allMessages: AIMessage[]): any[] {
+        const result: any[] = [];
+
+        for (const m of turns) {
+            if (typeof m.content === 'string') {
+                result.push({ role: m.role === 'assistant' ? 'model' : 'user', parts: [{ text: m.content }] });
+                continue;
+            }
+
+            if (m.role === 'assistant') {
+                const parts: any[] = [];
+                for (const b of m.content) {
+                    if (b.type === 'text' && b.text) parts.push({ text: b.text });
+                    if (b.type === 'tool_use') parts.push({ functionCall: { name: b.name, args: b.input ?? {} } });
+                }
+                result.push({ role: 'model', parts });
+                continue;
+            }
+
+            const toolResults = m.content.filter(b => b.type === 'tool_result') as Array<Extract<AIContentBlock, { type: 'tool_result' }>>;
+            const textBlocks = m.content.filter(b => b.type === 'text') as Array<Extract<AIContentBlock, { type: 'text' }>>;
+            const imageBlocks = m.content.filter(b => b.type === 'image') as Array<Extract<AIContentBlock, { type: 'image' }>>;
+
+            if (toolResults.length > 0) {
+                result.push({
+                    role: 'function',
+                    parts: toolResults.map(tr => ({
+                        functionResponse: {
+                            name: this.findToolUseName(allMessages, tr.tool_use_id) ?? 'unknown_function',
+                            response: { content: tr.content },
+                        },
+                    })),
+                });
+            }
+            if (textBlocks.length > 0 || imageBlocks.length > 0) {
+                result.push({
+                    role: 'user',
+                    parts: [
+                        ...textBlocks.map(b => ({ text: b.text })),
+                        ...imageBlocks.map(b => ({ inlineData: { mimeType: b.mediaType, data: b.data } })),
+                    ],
+                });
+            }
+        }
+
+        return result;
+    }
+
+    /** Anthropic's extended thinking requires temperature === 1 and max_tokens strictly greater
+     *  than budget_tokens; both are enforced here so callers never have to remember it. */
+    private anthropicThinkingFields(config: VendorConfig): { thinking?: any; temperature: number; max_tokens: number } {
+        const budget = THINKING_BUDGETS[config.thinking];
+        if (!budget) return { temperature: config.temperature, max_tokens: config.maxTokens };
+
+        return {
+            thinking: { type: 'enabled', budget_tokens: budget },
+            temperature: 1,
+            max_tokens: Math.max(config.maxTokens, budget + 1024),
+        };
+    }
+
+    /** OpenAI's `reasoning_effort` only exists on the 'o' reasoning model family and only accepts
+     *  low/medium/high (no 'none'/'max') — mapped from our vendor-agnostic ThinkingEffort. Those
+     *  models also reject a custom `temperature`, so it's omitted whenever reasoning_effort is set. */
+    private openaiReasoningFields(config: VendorConfig): { reasoning_effort?: string; temperature?: number } {
+        const isReasoningModel = /^o\d/.test(config.model);
+        if (!isReasoningModel || config.thinking === 'none') return { temperature: config.temperature };
+
+        const effortMap: Partial<Record<ThinkingEffort, string>> = { low: 'low', medium: 'medium', high: 'high', max: 'high' };
+        return { reasoning_effort: effortMap[config.thinking] };
+    }
+
+    private buildRequest(config: VendorConfig, messages: AIMessage[], stream: boolean, tools?: AITool[]): VendorRequest {
+        const { system, turns } = this.splitSystem(messages);
+        const vendorTools = this.buildVendorTools(config, tools);
+
+        switch (config.vendor) {
+            case 'anthropic': {
+                const thinkingFields = this.anthropicThinkingFields(config);
                 return {
                     url: 'https://api.anthropic.com/v1/messages',
                     headers: {
@@ -136,14 +508,16 @@ export class AIVendorManager {
                     body: {
                         model: config.model,
                         system,
-                        messages: turns.map(m => ({ role: m.role, content: m.content })),
-                        temperature: config.temperature,
-                        max_tokens: config.maxTokens,
+                        messages: this.buildAnthropicMessages(turns),
                         stream,
+                        ...thinkingFields,
+                        ...(vendorTools ? { tools: vendorTools } : {}),
                     },
                 };
+            }
 
-            case 'openai':
+            case 'openai': {
+                const reasoningFields = this.openaiReasoningFields(config);
                 return {
                     url: 'https://api.openai.com/v1/chat/completions',
                     headers: {
@@ -154,14 +528,16 @@ export class AIVendorManager {
                         model: config.model,
                         messages: [
                             ...(system ? [{ role: 'system', content: system }] : []),
-                            ...turns.map(m => ({ role: m.role, content: m.content })),
+                            ...this.buildOpenAIMessages(turns),
                         ],
-                        temperature: config.temperature,
                         max_tokens: config.maxTokens,
                         stream,
+                        ...reasoningFields,
                         ...(stream ? { stream_options: { include_usage: true } } : {}),
+                        ...(vendorTools ? { tools: vendorTools } : {}),
                     },
                 };
+            }
 
             case 'gemini': {
                 const action = stream ? 'streamGenerateContent?alt=sse&' : 'generateContent?';
@@ -170,14 +546,12 @@ export class AIVendorManager {
                     headers: { 'content-type': 'application/json' },
                     body: {
                         ...(system ? { systemInstruction: { parts: [{ text: system }] } } : {}),
-                        contents: turns.map(m => ({
-                            role: m.role === 'assistant' ? 'model' : 'user',
-                            parts: [{ text: m.content }],
-                        })),
+                        contents: this.buildGeminiContents(turns, messages),
                         generationConfig: {
                             temperature: config.temperature,
                             maxOutputTokens: config.maxTokens,
                         },
+                        ...(vendorTools ? { tools: vendorTools } : {}),
                     },
                 };
             }
@@ -214,47 +588,109 @@ export class AIVendorManager {
 
     private parseCompletion(config: VendorConfig, data: any): AICompletionResult {
         switch (config.vendor) {
-            case 'anthropic':
+            case 'anthropic': {
+                const blocks: AIContentBlock[] = (data.content ?? []).map((b: any) => {
+                    if (b.type === 'tool_use') return { type: 'tool_use', id: b.id, name: b.name, input: b.input };
+                    return { type: 'text', text: b.text ?? '' };
+                });
                 return {
-                    content: (data.content ?? []).map((b: any) => b.text ?? '').join(''),
+                    content: blocks.filter(b => b.type === 'text').map((b: any) => b.text).join(''),
+                    blocks,
                     vendor: config.vendor,
                     model: config.model,
                     promptTokens: data.usage?.input_tokens,
                     completionTokens: data.usage?.output_tokens,
+                    stopReason: data.stop_reason,
                 };
-            case 'openai':
+            }
+
+            case 'openai': {
+                const message = data.choices?.[0]?.message ?? {};
+                const blocks: AIContentBlock[] = [];
+
+                if (message.content) blocks.push({ type: 'text', text: message.content });
+
+                for (const call of message.tool_calls ?? []) {
+                    let input: any = {};
+                    try {
+                        input = JSON.parse(call.function?.arguments || '{}');
+                    } catch {
+                        input = {};
+                    }
+                    blocks.push({ type: 'tool_use', id: call.id, name: call.function?.name, input });
+                }
+
                 return {
-                    content: data.choices?.[0]?.message?.content ?? '',
+                    content: message.content ?? '',
+                    blocks,
                     vendor: config.vendor,
                     model: config.model,
                     promptTokens: data.usage?.prompt_tokens,
                     completionTokens: data.usage?.completion_tokens,
+                    stopReason: data.choices?.[0]?.finish_reason,
                 };
-            case 'gemini':
+            }
+
+            case 'gemini': {
+                const parts = data.candidates?.[0]?.content?.parts ?? [];
+                const blocks: AIContentBlock[] = [];
+                let callIndex = 0;
+
+                for (const p of parts) {
+                    if (p.text) blocks.push({ type: 'text', text: p.text });
+                    if (p.functionCall) {
+                        // Gemini no da ids: generamos uno sintético que solo usamos internamente
+                        // para poder emparejar el tool_result correspondiente más adelante.
+                        blocks.push({
+                            type: 'tool_use',
+                            id: `gemini-call-${callIndex++}-${p.functionCall.name}`,
+                            name: p.functionCall.name,
+                            input: p.functionCall.args ?? {},
+                        });
+                    }
+                }
+
                 return {
-                    content: (data.candidates?.[0]?.content?.parts ?? []).map((p: any) => p.text ?? '').join(''),
+                    content: blocks.filter(b => b.type === 'text').map((b: any) => b.text).join(''),
+                    blocks,
                     vendor: config.vendor,
                     model: config.model,
                     promptTokens: data.usageMetadata?.promptTokenCount,
                     completionTokens: data.usageMetadata?.candidatesTokenCount,
+                    stopReason: data.candidates?.[0]?.finishReason,
                 };
+            }
         }
     }
 
     /**
      * @method complete
      * @description Sends a chat-completion request and returns the full response once ready.
-     * Retries automatically on rate limiting (429) or server errors (5xx).
+     * Retries automatically on rate limiting (429) or server errors (5xx). When `options.tools`
+     * is provided, the model may respond with one or more `tool_use` blocks in `result.blocks`
+     * instead of (or in addition to) text — the caller is responsible for executing those tools
+     * and feeding the results back as a follow-up message with 'tool_result' blocks.
      * @param {AIMessage[]} messages - Conversation messages ('system', 'user', 'assistant').
-     * @param {AICompletionOptions} options - Optional overrides (vendor, model, temperature, maxTokens).
+     * @param {AICompletionOptions} options - Optional overrides (vendor, model, temperature, maxTokens, tools).
      * @returns {Promise<AICompletionResult>} The generated content plus vendor/model/usage metadata.
      * @example
      * const result = await ai.complete([{ role: 'user', content: 'Explain this bug...' }]);
      * console.log(result.content);
+     * @example
+     * // Tool use loop
+     * let result = await ai.complete(messages, { tools });
+     * while (result.blocks.some(b => b.type === 'tool_use')) {
+     *   messages.push({ role: 'assistant', content: result.blocks });
+     *   const toolResults = result.blocks
+     *     .filter(b => b.type === 'tool_use')
+     *     .map(b => ({ type: 'tool_result' as const, tool_use_id: b.id, content: runTool(b) }));
+     *   messages.push({ role: 'user', content: toolResults });
+     *   result = await ai.complete(messages, { tools });
+     * }
      */
     public async complete(messages: AIMessage[], options?: AICompletionOptions): Promise<AICompletionResult> {
         const config = this.resolveConfig(options);
-        const { url, headers, body } = this.buildRequest(config, messages, false);
+        const { url, headers, body } = this.buildRequest(config, messages, false, options?.tools);
 
         try {
             const response = await this.withRetries(
@@ -278,6 +714,11 @@ export class AIVendorManager {
      * @description Sends a chat-completion request and streams the response as it is generated.
      * Retries are only applied before any data has been received; once streaming has started,
      * failures are surfaced immediately to avoid emitting duplicated content.
+     *
+     * Tool use is NOT supported here: streaming tool calls arrive as incremental JSON fragments
+     * (Anthropic's `input_json_delta`, OpenAI's indexed `tool_calls` deltas, Gemini's partial
+     * function-call parts) and this method does not accumulate them. Passing `options.tools`
+     * throws immediately rather than silently dropping tool calls the model might make mid-stream.
      * @param {AIMessage[]} messages - Conversation messages ('system', 'user', 'assistant').
      * @param {(chunk: string) => void} onChunk - Called with each incremental text fragment.
      * @param {AICompletionOptions} options - Optional overrides (vendor, model, temperature, maxTokens).
@@ -290,6 +731,14 @@ export class AIVendorManager {
         onChunk: (chunk: string) => void,
         options?: AICompletionOptions
     ): Promise<AICompletionResult> {
+        if (options?.tools && options.tools.length > 0) {
+            throw new TyrError(
+                'Tool use is not supported in streaming mode yet',
+                null,
+                'Use complete() instead of stream() when passing tools.'
+            );
+        }
+
         const config = this.resolveConfig(options);
         const { url, headers, body } = this.buildRequest(config, messages, true);
 
@@ -381,8 +830,8 @@ export class AIVendorManager {
             }
         }
 
-        return { content, vendor: config.vendor, model: config.model, promptTokens, completionTokens };
+        return { content, blocks: [{ type: 'text', text: content }], vendor: config.vendor, model: config.model, promptTokens, completionTokens };
     }
 }
 
-export const AIVendorManagerTests = {};
+export const AIVendorManagerTests = {};