@orxataguy/tyr 1.0.30 → 1.0.31

package/README.md

@@ -252,6 +252,8 @@ tyr deploy --debug
 │   │   ├── Kernel.ts          # Command router and execution engine
 │   │   ├── Container.ts       # Dependency injection container
 │   │   ├── TyrError.ts        # Structured error type
+│   │   ├── util
+│   │   │   └── getenv.ts      # Helper: get environment variables
 │   │   └── sys/
 │   │       ├── gen.ts         # Built-in: scaffold a command
 │   │       ├── rem.ts         # Built-in: remove a command
@@ -259,16 +261,23 @@ tyr deploy --debug
 │   ├── commands/
 │   │   └── *.tyr.ts           # Your custom commands go here
 │   └── lib/
-│       ├── ShellManager.ts
-│       ├── FileSystemManager.ts
-│       ├── PackageManager.ts
-│       ├── DockerManager.ts
-│       ├── GitManager.ts
-│       ├── SystemManager.ts
-│       ├── SQLManager.ts
-│       └── WebManager.ts
-├── config/
-│   └── map.yml                # Command registry
+│   │   ├── AIContextManager.ts
+│   │   ├── AIVendorManager.ts
+│   │   ├── DockerManager.ts
+│   │   ├── FileSystemManager.ts
+│   │   ├── GitManager.ts
+│   │   ├── JiraManager.ts
+│   │   ├── MongoManager.ts
+│   │   ├── PackageManager.ts
+│   │   ├── PromptTemplateManager.ts
+│   │   ├── SetupManager.ts
+│   │   ├── ShellManager.ts
+│   │   ├── SQLManager.ts
+│   │   ├── SystemManager.ts
+│   │   ├── TokenManager.ts
+│   │   ├── WebManager.ts
+│   │   └── WorkspaceManager.ts
+|   └── index.ts               # Exports context
 └── tests/
     ├── setup.ts               # Mock context factory
     └── test-runner.ts         # Smoke test runner

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orxataguy/tyr",
-  "version": "1.0.30",
+  "version": "1.0.31",
   "type": "module",
   "bin": {
     "tyr": "./bin/tyr.js"

package/src/lib/AIVendorManager.ts

@@ -8,9 +8,33 @@ 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.
+ */
+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 };
+
 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;
 }
 
 export interface AICompletionOptions {
@@ -19,14 +43,26 @@ export interface AICompletionOptions {
     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[];
 }
 
 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 {
@@ -68,6 +104,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
@@ -116,13 +158,154 @@ export class AIVendorManager {
     }
 
     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 {
+    // --- 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 === '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('');
+
+            for (const tr of toolResults) {
+                result.push({ role: 'tool', tool_call_id: tr.tool_use_id, content: tr.content });
+            }
+            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' }>>;
+
+            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) {
+                result.push({ role: 'user', parts: textBlocks.map(b => ({ text: b.text })) });
+            }
+        }
+
+        return result;
+    }
+
+    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':
@@ -136,10 +319,11 @@ export class AIVendorManager {
                     body: {
                         model: config.model,
                         system,
-                        messages: turns.map(m => ({ role: m.role, content: m.content })),
+                        messages: this.buildAnthropicMessages(turns),
                         temperature: config.temperature,
                         max_tokens: config.maxTokens,
                         stream,
+                        ...(vendorTools ? { tools: vendorTools } : {}),
                     },
                 };
 
@@ -154,12 +338,13 @@ 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,
                         ...(stream ? { stream_options: { include_usage: true } } : {}),
+                        ...(vendorTools ? { tools: vendorTools } : {}),
                     },
                 };
 
@@ -170,14 +355,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 +397,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 +523,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 +540,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 +639,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 = {};

package/src/lib/PromptTemplateManager.ts

@@ -23,6 +23,13 @@ const DEFAULT_TEMPLATES: Record<string, PromptTemplate> = {
             'JSDoc comments on public methods. Output only the TypeScript code for the file, no commentary.',
         user: 'Command name: {{name}}\nRequested behaviour:\n{{description}}',
     },
+    'generate-code': {
+        system:
+            'You are a senior engineer. Follow the ' +
+            'existing conventions exactly: KISS, SOLID, DRY. Only make simple comments on the functions to give context if is necessary ' +
+            'Output only the code for the file, no commentary.',
+        user: 'Command name: {{name}}\nRequested behaviour:\n{{description}}',
+    },
     'explain-code': {
         system:
             'You are a senior software engineer. Explain what the given code does clearly and ' +