@orxataguy/tyr 1.0.28 → 1.0.30

package/package.json

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

package/src/core/Container.ts

@@ -10,6 +10,10 @@ import { WebManager } from '../lib/WebManager.js';
 import { WorkspaceManager } from '../lib/WorkspaceManager.js';
 import { JiraManager } from '../lib/JiraManager.js';
 import { SetupManager } from '../lib/SetupManager.js';
+import { AIVendorManager } from '../lib/AIVendorManager.js';
+import { AIContextManager } from '../lib/AIContextManager.js';
+import { PromptTemplateManager } from '../lib/PromptTemplateManager.js';
+import { TokenManager } from '../lib/TokenManager.js';
 import { Logger, createLogger } from './Logger.js';
 
 import path from 'path';
@@ -31,6 +35,10 @@ export interface ServiceContainer {
     workspace: WorkspaceManager;
     jira: JiraManager;
     setup: SetupManager;
+    aiVendor: AIVendorManager;
+    aiContext: AIContextManager;
+    prompts: PromptTemplateManager;
+    tokens: TokenManager;
 }
 
 export class Container {
@@ -47,6 +55,8 @@ export class Container {
         const mongo = new MongoManager();
         const web = new WebManager(logger);
         const fs = new FileSystemManager(logger);
+        const aiVendor = new AIVendorManager(logger);
+        const aiContext = new AIContextManager(fs, aiVendor, logger);
 
         this.services = {
             logger,
@@ -63,6 +73,10 @@ export class Container {
             workspace: new WorkspaceManager(shell, fs, logger),
             jira: new JiraManager(web, shell, logger),
             setup: new SetupManager(shell, fs, logger),
+            aiVendor,
+            aiContext,
+            prompts: new PromptTemplateManager(aiContext, logger),
+            tokens: new TokenManager(logger),
         };
     }
 

package/src/core/sys/config.ts

@@ -1,4 +1,5 @@
 import path from 'path';
+import { getEnvString } from '../util/getenv.js';
 import { homedir, platform } from 'os';
 import { existsSync, cpSync, rmSync, mkdirSync, readdirSync } from 'fs';
 import { execSync } from 'child_process';
@@ -48,7 +49,7 @@ function backupUserRoot(userRoot: string, backupPath: string): void {
 }
 
 function detectShellRcFile(homeDir: string): string | null {
-    const shell = process.env.SHELL || '';
+    const shell = getEnvString('SHELL', '');
     if (shell.includes('zsh'))  return path.join(homeDir, '.zshrc');
     if (shell.includes('fish')) return path.join(homeDir, '.config', 'fish', 'config.fish');
     if (shell.includes('bash')) {
@@ -60,7 +61,7 @@ function detectShellRcFile(homeDir: string): string | null {
 }
 
 function getWindowsProfilePaths(): string[] {
-    const userProfile = process.env.USERPROFILE;
+    const userProfile = getEnvString('USERPROFILE');
     if (!userProfile) return [];
     return [
         path.join(userProfile, 'Documents', 'WindowsPowerShell', 'Microsoft.PowerShell_profile.ps1'),
@@ -76,13 +77,13 @@ async function checkWindowsExecutionPolicy(shell: any, logger: any): Promise<voi
         const policy = String(output).trim();
 
         if (policy === 'Restricted' || policy === 'AllSigned' || policy === 'Undefined') {
-            logger.warn(`\nExecution Policy actual: ${policy || 'Undefined'}`);
-            logger.warn('Con esta política, PowerShell puede bloquear la carga de tu perfil (y por tanto las funciones/alias de Tyr).');
-            logger.info('Para permitirlo, ejecuta en una consola de PowerShell:');
+            logger.warn(`\nCurrent Execution Policy: ${policy || 'Undefined'}`);
+            logger.warn('With this policy, PowerShell may block loading your profile (and therefore Tyr functions/aliases).');
+            logger.info('To allow it, run in a PowerShell console:');
             logger.info('  Set-ExecutionPolicy RemoteSigned -Scope CurrentUser');
         }
     } catch {
-        logger.warn('No se pudo comprobar la Execution Policy de PowerShell. Verifícala manualmente si los comandos no cargan.');
+        logger.warn('Could not check PowerShell Execution Policy. Verify it manually if commands do not load.');
     }
 }
 
@@ -123,6 +124,14 @@ MSSQL_DATABASE=
 # MongoDB database
 MONGO_URI=
 MONGO_DATABASE=
+# AI vendor (anthropic | openai | gemini)
+AI_VENDOR=anthropic
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+GEMINI_API_KEY=
+AI_MODEL=
+AI_TEMPERATURE=
+AI_MAX_TOKENS=
 `;
 
 const SH_ALIASES_TEMPLATE = `# Add your custom aliases here.
@@ -176,15 +185,15 @@ async function configureUnixShell(tyrFs: any, logger: any, homeDir: string, alia
     }
     await tyrFs.ensureLine(rcFile, `source "${aliasesPath}"`);
     await tyrFs.ensureLine(rcFile, `source "${pluginsPath}"`);
-    logger.success(`Shell configurado: ${rcFile}`);
-    logger.info(`Ejecuta: source ${rcFile}  (o abre una nueva terminal)`);
+    logger.success(`Shell configured: ${rcFile}`);
+    logger.info(`Run: source ${rcFile}  (or open a new terminal)`);
 }
 
 async function configureWindowsShell(tyrFs: any, logger: any, shell: any, aliasesPath: string, pluginsPath: string): Promise<void> {
     const profiles = getWindowsProfilePaths();
 
     if (profiles.length === 0) {
-        logger.warn('Could not detect PowerShell profile (USERPROFILE no está definido).');
+        logger.warn('Could not detect PowerShell profile (USERPROFILE is not defined).');
         logger.info(`Add manually:\n  . "${aliasesPath}"\n  . "${pluginsPath}"`);
         return;
     }
@@ -197,7 +206,7 @@ async function configureWindowsShell(tyrFs: any, logger: any, shell: any, aliase
         logger.success(`PowerShell profile configured: ${psProfile}`);
     }
 
-    logger.info('Restart PowerShell (o abre una nueva consola) para aplicar los cambios.');
+    logger.info('Restart PowerShell (or open a new console) to apply the changes.');
 
     await checkWindowsExecutionPolicy(shell, logger);
 }
@@ -322,21 +331,19 @@ export default function config({ logger, fs: tyrFs, frameworkRoot, shell }: TyrC
             }
         }
 
-        // Garantizar package.json + tsconfig.json + npm install siempre,
-        // tanto en init fresh como al clonar un repo existente.
         const packageJsonPath = path.join(userRoot, 'package.json');
         const tsconfigPath    = path.join(userRoot, 'tsconfig.json');
         let needsInstall = false;
 
         if (!tyrFs.exists(packageJsonPath)) {
             await tyrFs.write(packageJsonPath, PACKAGE_JSON_TEMPLATE);
-            logger.success(`Archivo creado: ${packageJsonPath}`);
+            logger.success(`File created: ${packageJsonPath}`);
             needsInstall = true;
         }
 
         if (!tyrFs.exists(tsconfigPath)) {
             await tyrFs.write(tsconfigPath, TSCONFIG_TEMPLATE);
-            logger.success(`Archivo creado: ${tsconfigPath}`);
+            logger.success(`File created: ${tsconfigPath}`);
             needsInstall = true;
         }
 
@@ -355,7 +362,7 @@ export default function config({ logger, fs: tyrFs, frameworkRoot, shell }: TyrC
         const pluginsPath = path.join(userRoot, `plugins${ext}`);
 
         if (tyrFs.exists(aliasesPath) || tyrFs.exists(pluginsPath)) {
-            logger.info('\nConfigurando shell...');
+            logger.info('\nConfiguring shell...');
             if (isWindows) {
                 await configureWindowsShell(tyrFs, logger, shell, aliasesPath, pluginsPath);
             } else {

package/src/core/util/getenv.ts

@@ -0,0 +1,57 @@
+
+export function getEnvString(name: string, fallback: string): string;
+export function getEnvString(name: string, fallback?: string): string | undefined;
+export function getEnvString(name: string, fallback?: string): string | undefined {
+    const value = process.env[name];
+    return value === undefined || value === '' ? fallback : value;
+}
+
+
+export function getEnvInt(name: string, fallback: number): number;
+export function getEnvInt(name: string, fallback?: number): number | undefined;
+export function getEnvInt(name: string, fallback?: number): number | undefined {
+    const raw = getEnvString(name);
+    if (raw === undefined) return fallback;
+    const value = Number.parseInt(raw, 10);
+    return Number.isNaN(value) ? fallback : value;
+}
+
+
+export function getEnvDouble(name: string, fallback: number): number;
+export function getEnvDouble(name: string, fallback?: number): number | undefined;
+export function getEnvDouble(name: string, fallback?: number): number | undefined {
+    const raw = getEnvString(name);
+    if (raw === undefined) return fallback;
+    const value = Number.parseFloat(raw);
+    return Number.isNaN(value) ? fallback : value;
+}
+
+const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const FALSE_VALUES = new Set(['0', 'false', 'no', 'off']);
+
+
+export function getEnvBool(name: string, fallback: boolean): boolean;
+export function getEnvBool(name: string, fallback?: boolean): boolean | undefined;
+export function getEnvBool(name: string, fallback?: boolean): boolean | undefined {
+    const raw = getEnvString(name);
+    if (raw === undefined) return fallback;
+
+    const normalized = raw.trim().toLowerCase();
+    if (TRUE_VALUES.has(normalized)) return true;
+    if (FALSE_VALUES.has(normalized)) return false;
+    return fallback;
+}
+
+export function getEnvArray(name: string, fallback: string[], separator?: string): string[];
+export function getEnvArray(name: string, fallback?: string[], separator?: string): string[] | undefined;
+export function getEnvArray(name: string, fallback?: string[], separator: string = ','): string[] | undefined {
+    const raw = getEnvString(name);
+    if (raw === undefined) return fallback;
+
+    const values = raw
+        .split(separator)
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+
+    return values.length > 0 ? values : fallback;
+}

package/src/lib/AIContextManager.ts

@@ -0,0 +1,302 @@
+import path from 'path';
+
+import { FileSystemManager } from './FileSystemManager.js';
+import { AIVendorManager, AIMessage } from './AIVendorManager.js';
+import { Logger } from '../core/Logger.js';
+import { TyrError } from '../core/TyrError.js';
+
+import { getEnvInt } from '../core/util/getenv.js';
+
+
+const CONTEXT_FILENAMES = [
+    'CLAUDE.md',
+    'AGENTS.md',
+    'CONTEXT.md',
+    '.cursorrules',
+    path.join('.github', 'copilot-instructions.md'),
+];
+
+const GENERATED_FILENAME = 'CLAUDE.md';
+
+const SNAPSHOT_TREE_MAX_DEPTH =  getEnvInt('SNAPSHOT_TREE_MAX_DEPTH', 5);
+const SNAPSHOT_TREE_MAX_ENTRIES_PER_DIR = getEnvInt('SNAPSHOT_TREE_MAX_ENTRIES_PER_DIR', 250);
+const SNAPSHOT_SECTION_MAX_CHARS = getEnvInt('SNAPSHOT_SECTION_MAX_CHARS', 40000);
+
+const DEFAULT_IGNORED_DIRS = new Set<string>([
+    'node_modules', '.git', '.hg', '.svn',
+    '.turbo', '.next', '.nuxt', '.cache', '.parcel-cache',
+    '.vscode', '.idea',
+    'dist', 'build', 'out', 'coverage', '.nyc_output',
+    'target', 'vendor',
+]);
+
+const PACKAGE_JSON_FIELDS = ['name', 'version', 'type', 'dependencies', 'devDependencies', 'scripts'] as const;
+
+const GUIDELINES_SYSTEM_PROMPT =
+    'You are a senior software architect. Given a snapshot of a project (package manifest, README ' +
+    'and file structure), produce a concise, well-structured Markdown file of coding guidelines and ' +
+    'project conventions (stack, architecture, naming, testing, error handling) meant to be read by ' +
+    'an AI coding assistant before making changes. Be specific to this project and avoid generic ' +
+    'advice. Output only the Markdown content, with no surrounding commentary.';
+
+interface GuidelinesBlock {
+    fileName: string;
+    content: string;
+}
+
+/**
+ * @class AIContextManager
+ * @description Encuentra, valida y lee los archivos de directrices del proyecto (CLAUDE.md,
+ * AGENTS.md, etc.). Si no existen, escanea el proyecto (100% Node.js nativo, sin subprocesos de
+ * shell) y le pide al vendor de IA configurado que genere un archivo de directrices óptimo.
+ * Expone tanto el texto plano de las directrices (para sesiones de chat que gestionan su propia
+ * ventana de contexto) como un mensaje de sistema listo para usar (para completions puntuales).
+ */
+export class AIContextManager {
+    private fs: FileSystemManager;
+    private ai: AIVendorManager;
+    private logger: Logger;
+
+    constructor(fs: FileSystemManager, ai: AIVendorManager, logger: Logger) {
+        this.fs = fs;
+        this.ai = ai;
+        this.logger = logger;
+    }
+
+    /**
+     * @method findContextFiles
+     * @description Busca los archivos de directrices conocidos directamente dentro del directorio
+     * del proyecto.
+     * @param {string} dir - Ruta absoluta a la raíz del proyecto.
+     * @returns {string[]} Rutas absolutas de los archivos de directrices que existen.
+     */
+    public findContextFiles(dir: string): string[] {
+        return CONTEXT_FILENAMES
+            .map(name => path.join(dir, name))
+            .filter(fullPath => this.fs.exists(fullPath));
+    }
+
+    private async readAndValidate(filePath: string): Promise<string | null> {
+        const content = await this.fs.read(filePath);
+        if (!content || !content.trim()) return null;
+        return content.trim();
+    }
+
+    /**
+     * @method buildPackageJsonSummary
+     * @description Parsea package.json de forma segura (try/catch) y vuelve a serializar
+     * únicamente los campos relevantes para el contexto arquitectónico. A diferencia de un
+     * `.slice()` a ciegas, nunca entrega al vendor de IA un JSON truncado y sintácticamente roto.
+     * @param {string} dir - Ruta absoluta a la raíz del proyecto.
+     * @returns {Promise<string | null>} Sección Markdown lista para el snapshot, o null si no
+     * hay package.json legible o válido.
+     */
+    private async buildPackageJsonSummary(dir: string): Promise<string | null> {
+        const pkgPath = path.join(dir, 'package.json');
+        if (!this.fs.exists(pkgPath)) return null;
+
+        const raw = await this.fs.read(pkgPath);
+        if (!raw) return null;
+
+        try {
+            const parsed = JSON.parse(raw) as Record<string, unknown>;
+            const summary: Record<string, unknown> = {};
+            for (const field of PACKAGE_JSON_FIELDS) {
+                if (parsed[field] !== undefined) summary[field] = parsed[field];
+            }
+            return `# package.json (summary)\n\`\`\`json\n${JSON.stringify(summary, null, 2)}\n\`\`\``;
+        } catch {
+            this.logger.info(`package.json en ${pkgPath} no es JSON válido, se omite del snapshot.`);
+            return null;
+        }
+    }
+
+    /**
+     * @method scanDirectoryTree
+     * @description Escaneo recursivo de directorios agnóstico al SO usando la API nativa de
+     * Node.js (sin subprocesos de shell, por lo que funciona igual en Windows, macOS y Linux).
+     * Genera un árbol de texto indentado, ignora directorios de ruido y limita las entradas por
+     * carpeta para que directorios con cientos de archivos generados no colapsen el snapshot.
+     * @param {string} rootDir - Ruta absoluta desde la que empezar a escanear.
+     * @param {number} maxDepth - Profundidad máxima de recursión.
+     * @param {number} maxEntriesPerDir - Máximo de entradas listadas por carpeta antes de truncar.
+     * @param {Set<string>} ignoredDirs - Nombres de directorios a omitir por completo.
+     * @returns {Promise<string>} Representación en texto indentado del árbol.
+     */
+    private async scanDirectoryTree(
+        rootDir: string,
+        maxDepth: number = SNAPSHOT_TREE_MAX_DEPTH,
+        maxEntriesPerDir: number = SNAPSHOT_TREE_MAX_ENTRIES_PER_DIR,
+        ignoredDirs: Set<string> = DEFAULT_IGNORED_DIRS
+    ): Promise<string> {
+        const lines: string[] = [path.basename(rootDir) || rootDir];
+
+        const walk = async (currentDir: string, depth: number, prefix: string): Promise<void> => {
+            if (depth > maxDepth) return;
+
+            let entries;
+            try {
+                entries = await this.fs.readdir(currentDir, { withFileTypes: true });
+            } catch {
+                // Errores de permisos o carpetas borradas a mitad de escaneo no deben abortar
+                // todo el snapshot, simplemente se omiten.
+                return;
+            }
+
+            entries = entries
+                .filter(entry => !(entry.isDirectory() && ignoredDirs.has(entry.name)))
+                .sort((a, b) => {
+                    if (a.isDirectory() !== b.isDirectory()) return a.isDirectory() ? -1 : 1;
+                    return a.name.localeCompare(b.name);
+                });
+
+            const visible = entries.slice(0, maxEntriesPerDir);
+            const hiddenCount = entries.length - visible.length;
+
+            for (const entry of visible) {
+                lines.push(`${prefix}${entry.name}${entry.isDirectory() ? '/' : ''}`);
+                if (entry.isDirectory()) {
+                    await walk(path.join(currentDir, entry.name), depth + 1, `${prefix}  `);
+                }
+            }
+
+            if (hiddenCount > 0) {
+                lines.push(`${prefix}… y ${hiddenCount} elemento(s) más`);
+            }
+        };
+
+        await walk(rootDir, 1, '  ');
+        return lines.join('\n');
+    }
+
+    /**
+     * @method buildProjectSnapshot
+     * @description Ensambla el material que necesita el vendor de IA para escribir directrices:
+     * un resumen seguro de package.json, el README y un árbol de directorios nativo. Sin
+     * subprocesos de shell.
+     */
+    private async buildProjectSnapshot(dir: string): Promise<string> {
+        const parts: string[] = [];
+
+        const pkgSummary = await this.buildPackageJsonSummary(dir);
+        if (pkgSummary) parts.push(pkgSummary);
+
+        const readmePath = path.join(dir, 'README.md');
+        if (this.fs.exists(readmePath)) {
+            const readme = await this.fs.read(readmePath);
+            // El README es texto libre, no estructurado: aquí el truncado por longitud sí es seguro.
+            if (readme) parts.push(`# README.md\n${readme.slice(0, SNAPSHOT_SECTION_MAX_CHARS)}`);
+        }
+
+        const tree = await this.scanDirectoryTree(dir).catch(() => '');
+        if (tree) parts.push(`# Project structure\n${tree.slice(0, SNAPSHOT_SECTION_MAX_CHARS)}`);
+
+        return parts.join('\n\n');
+    }
+
+    /**
+     * @method generateContextFile
+     * @description Escanea el proyecto y le pide al vendor de IA configurado que sintetice un
+     * archivo de directrices, luego lo escribe como CLAUDE.md en la raíz del proyecto.
+     * @param {string} dir - Ruta absoluta a la raíz del proyecto.
+     * @returns {Promise<string>} Ruta absoluta del archivo generado.
+     */
+    public async generateContextFile(dir: string): Promise<string> {
+        this.logger.info('No se encontró archivo de contexto. Analizando el proyecto para generar uno...');
+
+        const snapshot = await this.buildProjectSnapshot(dir);
+        const messages: AIMessage[] = [
+            { role: 'system', content: GUIDELINES_SYSTEM_PROMPT },
+            { role: 'user', content: snapshot || 'The project has no readable package.json, README or file tree.' },
+        ];
+
+        let result;
+        try {
+            result = await this.ai.complete(messages, { temperature: 0.2 });
+        } catch (err) {
+            throw new TyrError(
+                `No se pudo generar el archivo de contexto para ${dir}`,
+                err,
+                'Revisa la configuración de tu vendor de IA y la conectividad de red, luego reintenta.'
+            );
+        }
+
+        const targetPath = path.join(dir, GENERATED_FILENAME);
+        await this.fs.write(targetPath, result.content.trim() + '\n');
+
+        this.logger.success(`Archivo de contexto generado en: ${targetPath}`);
+        return targetPath;
+    }
+
+    /**
+     * @method readGuidelines
+     * @description Encuentra los archivos de directrices existentes (generando uno vía IA si no
+     * hay ninguno), los lee y valida, y los devuelve como bloques discretos etiquetados — sin
+     * colapsarlos en un único string de mensaje de sistema. Esta es la pieza clave para sesiones
+     * de chat de larga duración: quien necesite gestionar una ventana de contexto continua (p. ej.
+     * un AIChatSessionManager) puede inspeccionar, cachear o descartar bloques individuales en
+     * lugar de releer disco y reinyectar un system prompt duplicado en cada turno.
+     * @param {string} dir - Ruta absoluta a la raíz del proyecto.
+     * @returns {Promise<GuidelinesBlock[]>}
+     */
+    public async readGuidelines(dir: string): Promise<GuidelinesBlock[]> {
+        let files = this.findContextFiles(dir);
+
+        if (files.length === 0) {
+            const generated = await this.generateContextFile(dir);
+            files = [generated];
+        }
+
+        const blocks: GuidelinesBlock[] = [];
+        for (const file of files) {
+            const content = await this.readAndValidate(file);
+            if (content) blocks.push({ fileName: path.basename(file), content });
+        }
+
+        if (blocks.length === 0) {
+            throw new TyrError(
+                `Se encontraron archivos de contexto pero están vacíos o son ilegibles en: ${dir}`,
+                null,
+                'Revisa el contenido de tu archivo CLAUDE.md/AGENTS.md.'
+            );
+        }
+
+        return blocks;
+    }
+
+    /**
+     * @method getGuidelinesText
+     * @description Envoltorio de conveniencia sobre readGuidelines() que devuelve el texto plano
+     * combinado de las directrices, sin envolver en roles/mensajes. Pensado para un
+     * AIChatSessionManager: se obtiene una vez por sesión, se cachea, y se gestiona dentro de la
+     * ventana de contexto de la conversación en lugar de llamar a getContext() (con su relectura
+     * de disco y reenvío de un system message completo) en cada turno.
+     * @param {string} dir - Ruta absoluta a la raíz del proyecto.
+     * @returns {Promise<string>}
+     */
+    public async getGuidelinesText(dir: string): Promise<string> {
+        const blocks = await this.readGuidelines(dir);
+        return blocks.map(b => `<!-- ${b.fileName} -->\n${b.content}`).join('\n\n');
+    }
+
+    /**
+     * @method getContext
+     * @description Punto de entrada para uso puntual: encuentra/genera archivos de directrices y
+     * los empaqueta como un único mensaje 'system' listo para prepender a un prompt. Para sesiones
+     * de chat continuas, usa getGuidelinesText() junto con tu propia gestión de ventana de contexto
+     * en lugar de llamar a este método en cada turno.
+     * @param {string} dir - Ruta absoluta a la raíz del proyecto.
+     * @returns {Promise<AIMessage[]>}
+     * @example
+     * const contextMessages = await context.getContext(process.cwd());
+     * const result = await ai.complete([...contextMessages, { role: 'user', content: 'Fix this bug...' }]);
+     */
+    public async getContext(dir: string): Promise<AIMessage[]> {
+        const text = await this.getGuidelinesText(dir);
+        return [{ role: 'system', content: text }];
+    }
+}
+
+export const AIContextManagerTests = {
+    findContextFiles: { dir: '~/Projects/TyrFramework' },
+};

package/src/lib/AIVendorManager.ts

@@ -0,0 +1,388 @@
+import axios from 'axios';
+
+import { Logger } from '../core/Logger.js';
+import { TyrError } from '../core/TyrError.js';
+
+import {getEnvString, getEnvInt, getEnvDouble} from '../core/util/getenv.js';
+
+export type AIVendor = 'anthropic' | 'openai' | 'gemini';
+export type AIRole = 'system' | 'user' | 'assistant';
+
+export interface AIMessage {
+    role: AIRole;
+    content: string;
+}
+
+export interface AICompletionOptions {
+    vendor?: AIVendor;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    maxRetries?: number;
+}
+
+export interface AICompletionResult {
+    content: string;
+    vendor: AIVendor;
+    model: string;
+    promptTokens?: number;
+    completionTokens?: number;
+}
+
+interface VendorConfig {
+    vendor: AIVendor;
+    apiKey: string;
+    model: string;
+    temperature: number;
+    maxTokens: number;
+    maxRetries: number;
+}
+
+interface VendorRequest {
+    url: string;
+    headers: Record<string, string>;
+    body: any;
+}
+
+const DEFAULT_MODELS: Record<AIVendor, string> = {
+    anthropic: 'claude-sonnet-5',
+    openai: 'gpt-4o-mini',
+    gemini: 'gemini-2.5-flash',
+};
+
+const API_KEY_ENV: Record<AIVendor, string> = {
+    anthropic: 'ANTHROPIC_API_KEY',
+    openai: 'OPENAI_API_KEY',
+    gemini: 'GEMINI_API_KEY',
+};
+
+const DEFAULT_TEMPERATURE = 0.3;
+const DEFAULT_MAX_TOKENS = 4096;
+const DEFAULT_MAX_RETRIES = 3;
+const RETRY_BASE_DELAY_MS = 500;
+
+/**
+ * @class AIVendorManager
+ * @description Unified client for AI chat-completion APIs (Anthropic, OpenAI, Gemini).
+ * Resolves the API key and technical defaults (model, temperature, max tokens) from
+ * environment variables / Tyr configuration, retries transient failures with exponential
+ * backoff, and supports both blocking and streaming responses.
+ *
+ * Environment variables:
+ *   AI_VENDOR          – 'anthropic' | 'openai' | 'gemini' (default: 'anthropic')
+ *   ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY – API key for the selected vendor
+ *   AI_MODEL           – overrides the vendor's default model
+ *   AI_TEMPERATURE     – overrides the default temperature (0.3)
+ *   AI_MAX_TOKENS      – overrides the default max output tokens (4096)
+ *   AI_MAX_RETRIES     – overrides the default retry count (3)
+ */
+export class AIVendorManager {
+    private logger: Logger;
+
+    constructor(logger: Logger) {
+        this.logger = logger;
+    }
+
+    private resolveConfig(options?: AICompletionOptions): VendorConfig {
+        const vendor = (options?.vendor ?? (getEnvString('AI_VENDOR') as AIVendor | undefined) ?? 'anthropic')
+            .toString()
+            .toLowerCase() as AIVendor;
+
+        if (!DEFAULT_MODELS[vendor]) {
+            throw new TyrError(
+                `Unsupported AI vendor: '${vendor}'`,
+                null,
+                `Set AI_VENDOR to one of: ${Object.keys(DEFAULT_MODELS).join(', ')}`
+            );
+        }
+
+        const apiKey = getEnvString(API_KEY_ENV[vendor]);
+        if (!apiKey) {
+            throw new TyrError(
+                `Missing API key for vendor '${vendor}'`,
+                null,
+                `Set ${API_KEY_ENV[vendor]} in ~/.tyr/.env`
+            );
+        }
+
+        return {
+            vendor,
+            apiKey,
+            model: options?.model ?? getEnvString('AI_MODEL') ?? DEFAULT_MODELS[vendor],
+            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),
+        };
+    }
+
+    private splitSystem(messages: AIMessage[]): { system: string; turns: AIMessage[] } {
+        const system = messages.filter(m => m.role === 'system').map(m => m.content).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);
+
+        switch (config.vendor) {
+            case 'anthropic':
+                return {
+                    url: 'https://api.anthropic.com/v1/messages',
+                    headers: {
+                        'x-api-key': config.apiKey,
+                        'anthropic-version': '2023-06-01',
+                        'content-type': 'application/json',
+                    },
+                    body: {
+                        model: config.model,
+                        system,
+                        messages: turns.map(m => ({ role: m.role, content: m.content })),
+                        temperature: config.temperature,
+                        max_tokens: config.maxTokens,
+                        stream,
+                    },
+                };
+
+            case 'openai':
+                return {
+                    url: 'https://api.openai.com/v1/chat/completions',
+                    headers: {
+                        Authorization: `Bearer ${config.apiKey}`,
+                        'content-type': 'application/json',
+                    },
+                    body: {
+                        model: config.model,
+                        messages: [
+                            ...(system ? [{ role: 'system', content: system }] : []),
+                            ...turns.map(m => ({ role: m.role, content: m.content })),
+                        ],
+                        temperature: config.temperature,
+                        max_tokens: config.maxTokens,
+                        stream,
+                        ...(stream ? { stream_options: { include_usage: true } } : {}),
+                    },
+                };
+
+            case 'gemini': {
+                const action = stream ? 'streamGenerateContent?alt=sse&' : 'generateContent?';
+                return {
+                    url: `https://generativelanguage.googleapis.com/v1beta/models/${config.model}:${action}key=${config.apiKey}`,
+                    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 }],
+                        })),
+                        generationConfig: {
+                            temperature: config.temperature,
+                            maxOutputTokens: config.maxTokens,
+                        },
+                    },
+                };
+            }
+
+            default:
+                throw new TyrError(`Unsupported AI vendor: '${config.vendor}'`);
+        }
+    }
+
+    private sleep(ms: number): Promise<void> {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+
+    private isRetryable(status: number | undefined): boolean {
+        return status === 429 || (status !== undefined && status >= 500);
+    }
+
+    private async withRetries<T>(fn: () => Promise<T>, maxRetries: number): Promise<T> {
+        let lastError: unknown;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await fn();
+            } catch (e: any) {
+                lastError = e;
+                const status = e?.response?.status;
+                if (attempt === maxRetries || !this.isRetryable(status)) throw e;
+                const delay = RETRY_BASE_DELAY_MS * 2 ** attempt;
+                this.logger.warn(`AI request failed (status ${status ?? 'unknown'}). Retrying in ${delay}ms...`);
+                await this.sleep(delay);
+            }
+        }
+        throw lastError;
+    }
+
+    private parseCompletion(config: VendorConfig, data: any): AICompletionResult {
+        switch (config.vendor) {
+            case 'anthropic':
+                return {
+                    content: (data.content ?? []).map((b: any) => b.text ?? '').join(''),
+                    vendor: config.vendor,
+                    model: config.model,
+                    promptTokens: data.usage?.input_tokens,
+                    completionTokens: data.usage?.output_tokens,
+                };
+            case 'openai':
+                return {
+                    content: data.choices?.[0]?.message?.content ?? '',
+                    vendor: config.vendor,
+                    model: config.model,
+                    promptTokens: data.usage?.prompt_tokens,
+                    completionTokens: data.usage?.completion_tokens,
+                };
+            case 'gemini':
+                return {
+                    content: (data.candidates?.[0]?.content?.parts ?? []).map((p: any) => p.text ?? '').join(''),
+                    vendor: config.vendor,
+                    model: config.model,
+                    promptTokens: data.usageMetadata?.promptTokenCount,
+                    completionTokens: data.usageMetadata?.candidatesTokenCount,
+                };
+        }
+    }
+
+    /**
+     * @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).
+     * @param {AIMessage[]} messages - Conversation messages ('system', 'user', 'assistant').
+     * @param {AICompletionOptions} options - Optional overrides (vendor, model, temperature, maxTokens).
+     * @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);
+     */
+    public async complete(messages: AIMessage[], options?: AICompletionOptions): Promise<AICompletionResult> {
+        const config = this.resolveConfig(options);
+        const { url, headers, body } = this.buildRequest(config, messages, false);
+
+        try {
+            const response = await this.withRetries(
+                () => axios.post(url, body, { headers }),
+                config.maxRetries
+            );
+            return this.parseCompletion(config, response.data);
+        } catch (e: any) {
+            if (e instanceof TyrError) throw e;
+            const status = e?.response?.status;
+            throw new TyrError(
+                `AI request to '${config.vendor}' failed (${status ?? 'network error'})`,
+                e,
+                'Check your API key, network connection, and the vendor status page.'
+            );
+        }
+    }
+
+    /**
+     * @method stream
+     * @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.
+     * @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).
+     * @returns {Promise<AICompletionResult>} The full accumulated content plus vendor/model/usage metadata.
+     * @example
+     * const result = await ai.stream(messages, (chunk) => process.stdout.write(chunk));
+     */
+    public async stream(
+        messages: AIMessage[],
+        onChunk: (chunk: string) => void,
+        options?: AICompletionOptions
+    ): Promise<AICompletionResult> {
+        const config = this.resolveConfig(options);
+        const { url, headers, body } = this.buildRequest(config, messages, true);
+
+        let content = '';
+        let promptTokens: number | undefined;
+        let completionTokens: number | undefined;
+        let hasStreamedAny = false;
+
+        const attemptStream = async (): Promise<void> => {
+            const response = await axios.post(url, body, { headers, responseType: 'stream' });
+            let buffer = '';
+
+            for await (const chunk of response.data) {
+                hasStreamedAny = true;
+                buffer += chunk.toString('utf-8');
+
+                let boundary: number;
+                while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+                    const rawEvent = buffer.slice(0, boundary);
+                    buffer = buffer.slice(boundary + 2);
+
+                    for (const line of rawEvent.split('\n')) {
+                        const trimmed = line.trim();
+                        if (!trimmed.startsWith('data:')) continue;
+
+                        const payload = trimmed.slice(5).trim();
+                        if (payload === '[DONE]') continue;
+
+                        let event: any;
+                        try {
+                            event = JSON.parse(payload);
+                        } catch {
+                            continue;
+                        }
+
+                        if (config.vendor === 'anthropic') {
+                            if (event.type === 'content_block_delta' && event.delta?.text) {
+                                content += event.delta.text;
+                                onChunk(event.delta.text);
+                            } else if (event.type === 'message_start') {
+                                promptTokens = event.message?.usage?.input_tokens;
+                            } else if (event.type === 'message_delta') {
+                                completionTokens = event.usage?.output_tokens;
+                            }
+                        } else if (config.vendor === 'openai') {
+                            const delta = event.choices?.[0]?.delta?.content;
+                            if (delta) {
+                                content += delta;
+                                onChunk(delta);
+                            }
+                            if (event.usage) {
+                                promptTokens = event.usage.prompt_tokens;
+                                completionTokens = event.usage.completion_tokens;
+                            }
+                        } else if (config.vendor === 'gemini') {
+                            const text = event.candidates?.[0]?.content?.parts?.[0]?.text;
+                            if (text) {
+                                content += text;
+                                onChunk(text);
+                            }
+                            if (event.usageMetadata) {
+                                promptTokens = event.usageMetadata.promptTokenCount;
+                                completionTokens = event.usageMetadata.candidatesTokenCount;
+                            }
+                        }
+                    }
+                }
+            }
+        };
+
+        let attempt = 0;
+        for (;;) {
+            try {
+                await attemptStream();
+                break;
+            } catch (e: any) {
+                const status = e?.response?.status;
+                if (hasStreamedAny || attempt >= config.maxRetries || !this.isRetryable(status)) {
+                    throw new TyrError(
+                        `AI streaming request to '${config.vendor}' failed (${status ?? 'network error'})`,
+                        e,
+                        'Check your API key, network connection, and the vendor status page.'
+                    );
+                }
+                attempt++;
+                const delay = RETRY_BASE_DELAY_MS * 2 ** attempt;
+                this.logger.warn(`AI stream request failed (status ${status ?? 'unknown'}). Retrying in ${delay}ms...`);
+                await this.sleep(delay);
+            }
+        }
+
+        return { content, vendor: config.vendor, model: config.model, promptTokens, completionTokens };
+    }
+}
+
+export const AIVendorManagerTests = {};

package/src/lib/FileSystemManager.ts

@@ -1,5 +1,5 @@
 import fs from 'fs/promises';
-import { existsSync } from 'fs';
+import { existsSync, Dirent } from 'fs';
 import { homedir } from 'os';
 import path from 'path';
 
@@ -29,7 +29,7 @@ export class FileSystemManager {
      * @param {string} filePath - The path to expand.
      * @returns {string} The expanded absolute path.
      * @example
-     * const dir = fs.expandPath(process.env.INTEGRATIONS_DIR!);
+     * const dir = fs.expandPath(getEnvString('INTEGRATIONS_DIR'));
      * // "~/dev/datosBroker" → "/Users/mandreu/dev/datosBroker"
      */
     public expandPath(filePath: string): string {
@@ -76,6 +76,26 @@ export class FileSystemManager {
         }
     }
 
+     /**
+     * @method readdir
+     * @description Reads the content of a directory. Returns null if the directory does not exist.
+     * @param {string} dirPath - Path to the directory.
+     * @returns {Promise<string[]|null>} List of entries or null if it does not exist.
+     * @example
+     * const entries = await fs.readdir('./src');
+     */
+    public async readdir(dirPath: string, options: { withFileTypes: true } & Record<string, any>): Promise<Dirent[]>;
+    public async readdir(dirPath: string, options?: ({ withFileTypes?: false } & Record<string, any>) | undefined): Promise<string[]>;
+    public async readdir(dirPath: string, options?: any): Promise<string[] | Dirent[]> {
+        const resolvedPath = this.resolvePath(dirPath);
+        try {
+            return await fs.readdir(resolvedPath, options);
+        } catch (e) {
+            if ((e as NodeJS.ErrnoException).code === 'ENOENT') return [];
+            throw new TyrError(`Could not read directory: ${dirPath}`, e, 'Check that the directory exists and has read permissions.');
+        }
+    }
+
     /**
      * @method delete
      * @description Deletes a file if it exists.

package/src/lib/JiraManager.ts

@@ -2,6 +2,9 @@ import { WebManager } from './WebManager.js';
 import { ShellManager } from './ShellManager.js';
 import { Logger } from '../core/Logger.js';
 
+import {getEnvString} from '../core/util/getenv.js';
+
+
 interface JiraIssue {
     key: string;
     summary: string;
@@ -29,11 +32,11 @@ export class JiraManager {
     }
 
     private get jiraUrl(): string | undefined {
-        return process.env.JIRA_URL;
+        return getEnvString('JIRA_URL');
     }
 
     private get jiraToken(): string | undefined {
-        return process.env.JIRA_TOKEN;
+        return getEnvString('JIRA_TOKEN');
     }
 
     private async fetchMyIssues(): Promise<JiraIssue[]> {

package/src/lib/MongoManager.ts

@@ -1,4 +1,5 @@
 import { MongoClient, Db, Document, Filter, UpdateFilter, InsertOneResult, InsertManyResult, UpdateResult, DeleteResult, WithId, OptionalUnlessRequiredId, FindOptions } from 'mongodb';
+import { getEnvString } from '../core/util/getenv.js';
 
 /**
  * @class MongoManager
@@ -13,8 +14,8 @@ export class MongoManager {
 
   private async init(): Promise<void> {
     if (!this.connected) {
-      const uri = process.env.MONGO_URI || 'mongodb://localhost:27017';
-      const dbName = process.env.MONGO_DATABASE || '';
+      const uri = getEnvString('MONGO_URI') || 'mongodb://localhost:27017';
+      const dbName = getEnvString('MONGO_DATABASE') || '';
 
       this.client = new MongoClient(uri);
       await this.client.connect();

package/src/lib/PromptTemplateManager.ts

@@ -0,0 +1,135 @@
+import { AIContextManager } from './AIContextManager.js';
+import { AIMessage } from './AIVendorManager.js';
+import { Logger } from '../core/Logger.js';
+import { TyrError } from '../core/TyrError.js';
+
+export interface PromptTemplate {
+    system: string;
+    user: string;
+}
+
+const DEFAULT_TEMPLATES: Record<string, PromptTemplate> = {
+    'analyze-bug': {
+        system:
+            'You are a senior software engineer specialised in debugging. Analyse the given code and ' +
+            'describe the root cause of the bug, then propose a minimal, correct fix. Be precise and ' +
+            'reference exact lines when possible.',
+        user: 'Bug description:\n{{description}}\n\nRelevant code:\n```\n{{code}}\n```',
+    },
+    'generate-command': {
+        system:
+            'You are a senior TypeScript engineer generating a Tyr Framework command. Follow the ' +
+            'existing conventions exactly: dependency injection via TyrContext, TyrError for failures, ' +
+            'JSDoc comments on public methods. Output only the TypeScript 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 ' +
+            'concisely, for a developer unfamiliar with it.',
+        user: 'Code:\n```\n{{code}}\n```',
+    },
+    'refactor-code': {
+        system:
+            'You are a senior software engineer. Refactor the given code for clarity and ' +
+            'maintainability without changing its behaviour. Explain the key changes briefly, then ' +
+            'provide the full refactored code.',
+        user: 'Code:\n```\n{{code}}\n```\n\nGoal:\n{{goal}}',
+    },
+};
+
+/**
+ * @class PromptTemplateManager
+ * @description Manages the system's prompt templates. Exposes a base template for common tasks
+ * (analysing a bug, generating a command, explaining or refactoring code) and fills in the
+ * placeholders with the user's code and the project context, so the AI always receives its role
+ * instructions in a uniform way.
+ */
+export class PromptTemplateManager {
+    private context: AIContextManager;
+    private logger: Logger;
+    private templates: Record<string, PromptTemplate>;
+
+    constructor(context: AIContextManager, logger: Logger) {
+        this.context = context;
+        this.logger = logger;
+        this.templates = { ...DEFAULT_TEMPLATES };
+    }
+
+    /**
+     * @method listTemplates
+     * @description Lists the names of all registered prompt templates.
+     * @returns {string[]} Template names.
+     * @example
+     * const names = prompts.listTemplates();
+     * // ['analyze-bug', 'generate-command', 'explain-code', 'refactor-code']
+     */
+    public listTemplates(): string[] {
+        return Object.keys(this.templates);
+    }
+
+    /**
+     * @method registerTemplate
+     * @description Registers a new prompt template, or overrides an existing one.
+     * @param {string} name - Unique template name.
+     * @param {PromptTemplate} template - The system role instructions and the user template string.
+     * @example
+     * prompts.registerTemplate('write-tests', {
+     *   system: 'You are a senior QA engineer...',
+     *   user: 'Code:\n```\n{{code}}\n```',
+     * });
+     */
+    public registerTemplate(name: string, template: PromptTemplate): void {
+        this.templates[name] = template;
+    }
+
+    private fill(template: string, vars: Record<string, string>): string {
+        return template.replace(/{{\s*(\w+)\s*}}/g, (_match, key: string) => {
+            if (!(key in vars)) {
+                throw new TyrError(
+                    `Missing placeholder value: '${key}'`,
+                    null,
+                    `Provide a value for '${key}' when building this prompt.`
+                );
+            }
+            return vars[key];
+        });
+    }
+
+    /**
+     * @method build
+     * @description Fills a named template with the given variables and prepends the project's
+     * context (see AIContextManager), producing the full list of messages ready to send to
+     * AIVendorManager.
+     * @param {string} templateName - Name of a registered template (see listTemplates()).
+     * @param {Record<string,string>} vars - Values for the template's {{placeholders}}.
+     * @param {string} projectDir - Absolute path to the project root, used to load its context.
+     * @returns {Promise<AIMessage[]>} Ordered messages: [system, ...context, user].
+     * @example
+     * const messages = await prompts.build('analyze-bug', {
+     *   description: 'Login fails with a 500 error',
+     *   code: fileContent,
+     * }, process.cwd());
+     * const result = await ai.complete(messages);
+     */
+    public async build(templateName: string, vars: Record<string, string>, projectDir: string): Promise<AIMessage[]> {
+        const template = this.templates[templateName];
+        if (!template) {
+            throw new TyrError(
+                `Unknown prompt template: '${templateName}'`,
+                null,
+                `Available templates: ${this.listTemplates().join(', ')}`
+            );
+        }
+
+        const systemMessage: AIMessage = { role: 'system', content: template.system };
+        const userMessage: AIMessage = { role: 'user', content: this.fill(template.user, vars) };
+        const contextMessages = await this.context.getContext(projectDir);
+
+        return [systemMessage, ...contextMessages, userMessage];
+    }
+}
+
+export const PromptTemplateManagerTests = {
+    listTemplates: {},
+};

package/src/lib/SQLManager.ts

@@ -1,5 +1,6 @@
 import path from 'path';
 import sql, { config as SQLConfig } from 'mssql';
+import { getEnvString } from '../core/util/getenv.js';
 
 /**
  * @class SQLManager
@@ -16,10 +17,10 @@ export class SQLManager {
     if (!this.connected) {
 
       const db_config: SQLConfig = {
-        user: process.env.MSSQL_USER,
-        password: process.env.MSSQL_PASSWORD,
-        server: process.env.MSSQL_SERVER || '',
-        database: process.env.MSSQL_DATABASE,
+        user: getEnvString('MSSQL_USER'),
+        password: getEnvString('MSSQL_PASSWORD'),
+        server: getEnvString('MSSQL_SERVER') || '',
+        database: getEnvString('MSSQL_DATABASE'),
         options: {
           encrypt: false,
           trustServerCertificate: true

package/src/lib/TokenManager.ts

@@ -0,0 +1,169 @@
+import fs from 'fs';
+import path from 'path';
+import { homedir } from 'os';
+
+import { AIMessage } from './AIVendorManager.js';
+import { Logger } from '../core/Logger.js';
+import { TyrError } from '../core/TyrError.js';
+import { getEnvInt } from '../core/util/getenv.js';
+
+const DEFAULT_MAX_INPUT_TOKENS = getEnvInt('DEFAULT_MAX_INPUT_TOKENS', 100000);
+const CHARS_PER_TOKEN = 4;
+const PER_MESSAGE_OVERHEAD_TOKENS = 4;
+
+interface UsageEntry {
+    timestamp: string;
+    vendor: string;
+    model: string;
+    promptTokens: number;
+    completionTokens: number;
+}
+
+export interface UsageStats {
+    totalCalls: number;
+    totalPromptTokens: number;
+    totalCompletionTokens: number;
+    byModel: Record<string, { calls: number; promptTokens: number; completionTokens: number }>;
+}
+
+/**
+ * @class TokenManager
+ * @description Controls AI token consumption and limits. Estimates the token cost of a prompt
+ * before it is sent (to avoid oversized requests or runaway costs), records real usage once a
+ * request completes, and reports aggregated statistics. The estimate is a fast heuristic
+ * (~4 characters per token), not an exact vendor tokenizer, so it should be treated as an
+ * upper-bound guard rather than a billing-accurate figure.
+ */
+export class TokenManager {
+    private logger: Logger;
+    private usageFile: string;
+
+    constructor(logger: Logger) {
+        this.logger = logger;
+        this.usageFile = path.join(homedir(), '.tyr', 'logs', 'ai-usage.jsonl');
+    }
+
+    /**
+     * @method estimateTokens
+     * @description Estimates the number of tokens a piece of text will consume.
+     * @param {string} text - The text to estimate.
+     * @returns {number} Estimated token count.
+     * @example
+     * const tokens = tokens_.estimateTokens(fileContent);
+     */
+    public estimateTokens(text: string): number {
+        if (!text) return 0;
+        return Math.ceil(text.length / CHARS_PER_TOKEN);
+    }
+
+    /**
+     * @method estimateMessagesTokens
+     * @description Estimates the total token cost of a full list of prompt messages.
+     * @param {AIMessage[]} messages - Messages that would be sent to AIVendorManager.
+     * @returns {number} Estimated total token count, including a small per-message overhead.
+     * @example
+     * const total = tokens_.estimateMessagesTokens(messages);
+     */
+    public estimateMessagesTokens(messages: AIMessage[]): number {
+        return messages.reduce(
+            (total, m) => total + this.estimateTokens(m.content) + PER_MESSAGE_OVERHEAD_TOKENS,
+            0
+        );
+    }
+
+    /**
+     * @method assertWithinLimit
+     * @description Stops execution with an error if the estimated prompt size exceeds the given
+     * limit (or the default of 100,000 tokens). Call this before sending a prompt to AIVendorManager.
+     * @param {AIMessage[]} messages - Messages that would be sent to AIVendorManager.
+     * @param {number} limit - Maximum allowed estimated tokens (default: 100000).
+     * @example
+     * tokens_.assertWithinLimit(messages);
+     * const result = await ai.complete(messages);
+     */
+    public assertWithinLimit(messages: AIMessage[], limit: number = DEFAULT_MAX_INPUT_TOKENS): void {
+        const estimated = this.estimateMessagesTokens(messages);
+        if (estimated > limit) {
+            throw new TyrError(
+                `Estimated prompt size (${estimated} tokens) exceeds the limit (${limit} tokens).`,
+                null,
+                'Provide a smaller context (fewer or shorter files) or split the task into smaller steps.'
+            );
+        }
+    }
+
+    /**
+     * @method recordUsage
+     * @description Appends a usage record for a completed AI request, for later reporting.
+     * @param {string} vendor - Vendor name used (e.g. 'anthropic').
+     * @param {string} model - Model name used.
+     * @param {number} promptTokens - Prompt tokens consumed (from the vendor's response, if available).
+     * @param {number} completionTokens - Completion tokens consumed (from the vendor's response, if available).
+     * @example
+     * const result = await ai.complete(messages);
+     * tokens_.recordUsage(result.vendor, result.model, result.promptTokens ?? 0, result.completionTokens ?? 0);
+     */
+    public recordUsage(vendor: string, model: string, promptTokens: number, completionTokens: number): void {
+        const entry: UsageEntry = {
+            timestamp: new Date().toISOString(),
+            vendor,
+            model,
+            promptTokens,
+            completionTokens,
+        };
+        try {
+            fs.mkdirSync(path.dirname(this.usageFile), { recursive: true });
+            fs.appendFileSync(this.usageFile, JSON.stringify(entry) + '\n', 'utf-8');
+        } catch (e) {
+            this.logger.warn(`Could not record AI token usage: ${(e as Error).message}`);
+        }
+    }
+
+    /**
+     * @method getUsageStats
+     * @description Reads the recorded usage log and returns aggregated statistics, overall and
+     * broken down by vendor/model.
+     * @returns {Promise<UsageStats>} Aggregated usage statistics.
+     * @example
+     * const stats = await tokens_.getUsageStats();
+     * logger.info(`Total tokens used: ${stats.totalPromptTokens + stats.totalCompletionTokens}`);
+     */
+    public async getUsageStats(): Promise<UsageStats> {
+        const stats: UsageStats = {
+            totalCalls: 0,
+            totalPromptTokens: 0,
+            totalCompletionTokens: 0,
+            byModel: {},
+        };
+
+        if (!fs.existsSync(this.usageFile)) return stats;
+
+        const lines = fs.readFileSync(this.usageFile, 'utf-8').split('\n').filter(Boolean);
+        for (const line of lines) {
+            try {
+                const entry: UsageEntry = JSON.parse(line);
+                stats.totalCalls += 1;
+                stats.totalPromptTokens += entry.promptTokens;
+                stats.totalCompletionTokens += entry.completionTokens;
+
+                const key = `${entry.vendor}/${entry.model}`;
+                if (!stats.byModel[key]) {
+                    stats.byModel[key] = { calls: 0, promptTokens: 0, completionTokens: 0 };
+                }
+                stats.byModel[key].calls += 1;
+                stats.byModel[key].promptTokens += entry.promptTokens;
+                stats.byModel[key].completionTokens += entry.completionTokens;
+            } catch {
+                // Skip malformed lines rather than failing the whole report.
+            }
+        }
+
+        return stats;
+    }
+}
+
+export const TokenManagerTests = {
+    estimateTokens: { text: 'Hello world, this is a test string for token estimation.' },
+    estimateMessagesTokens: { messages: [{ role: 'user', content: 'Hello world' }] },
+    assertWithinLimit: { messages: [{ role: 'user', content: 'Hello world' }] },
+};