agent-rev 0.5.10 → 0.5.12

package/dist/commands/repl.js

@@ -683,6 +683,57 @@ async function cmdAuthStatus(fi) {
         }));
     fi.println(renderSectionBox('Auth Status', rows));
 }
+async function cmdUsage(fi) {
+    const { qwenUsage } = await import('../utils/qwen-auth.js');
+    const { PKG_NAME, getConfigDir } = await import('../utils/config.js');
+    const { loadProjectConfig } = await import('../utils/config.js');
+    fi.println(chalk.bold.cyan('\n  Uso / Quota\n'));
+    // Check each role CLI
+    const dir = await resolveProjectDir(process.cwd());
+    let config;
+    try {
+        config = await loadProjectConfig(dir);
+    }
+    catch {
+        config = null;
+    }
+    const checks = [];
+    // Check main PKG_NAME (this CLI's own credentials)
+    const mainResult = await qwenUsage();
+    const mainLabel = `${PKG_NAME} (${mainResult.token ? 'coder-model' : '?'})`;
+    if (mainResult.ok) {
+        const exp = mainResult.token ? new Date(mainResult.token.expiresAt).toLocaleTimeString() : '?';
+        checks.push({ key: mainLabel, value: chalk.green(`✓ quota OK — expires ${exp}`) });
+    }
+    else {
+        checks.push({ key: mainLabel, value: chalk.red(`✗ ${mainResult.error}`) });
+    }
+    // Check each configured role CLI
+    if (config?.roles) {
+        for (const [roleName, roleCfg] of Object.entries(config.roles)) {
+            const r = roleCfg;
+            if (!r?.cli)
+                continue;
+            const homeDir = path.join(os.homedir(), '.' + r.cli);
+            const credsPath = path.join(homeDir, 'oauth_creds.json');
+            if (await fileExists(credsPath)) {
+                const result = await qwenUsage(credsPath);
+                const exp = result.token ? new Date(result.token.expiresAt).toLocaleTimeString() : '?';
+                if (result.ok) {
+                    checks.push({ key: `${r.cli} (${roleName})`, value: chalk.green(`✓ quota OK — expires ${exp}`) });
+                }
+                else {
+                    checks.push({ key: `${r.cli} (${roleName})`, value: chalk.red(`✗ ${result.error}`) });
+                }
+            }
+            else {
+                checks.push({ key: `${r.cli} (${roleName})`, value: chalk.yellow('not logged in') });
+            }
+        }
+    }
+    fi.println(renderSectionBox('Quota Status', checks));
+    fi.println('');
+}
 function cmdHelp(fi) {
     const commands = [
         { key: '/setup', value: 'Full interactive setup wizard' },
@@ -703,6 +754,7 @@ function cmdHelp(fi) {
         { key: '/login', value: 'Login (Qwen OAuth or CLI auth)' },
         { key: '/logout', value: 'Logout and clear credentials' },
         { key: '/auth-status', value: 'Show authentication status' },
+        { key: '/usage', value: 'Check quota status for all role CLIs' },
         { key: '/tasks', value: 'List all tasks' },
         { key: '/clear', value: 'Clear the screen' },
         { key: '/help', value: 'Show this help' },
@@ -994,6 +1046,16 @@ export async function runRepl(resumeSession) {
                 const dir = await resolveProjectDir(process.cwd());
                 const config = await loadProjectConfig(dir);
                 if (args[0] === 'orch' || args[0] === 'orchestrator') {
+                    // Ensure documentation exists before orchestrator runs
+                    const contextDir = path.join(dir, '.agent', 'context');
+                    const archPath = path.join(contextDir, 'architecture.md');
+                    if (!(await fileExists(archPath))) {
+                        fi.println(chalk.yellow('\n  ── Generando documentación del proyecto ──'));
+                        fi.println(chalk.dim('  El orquestador necesita conocer la estructura del proyecto primero.\n'));
+                        const prepEngine = new AgentEngine(config, dir, gCoordinatorCmd, rl, fi, handleCmd);
+                        await prepEngine.runExplorer('Document the complete project structure, services, dependencies, and entry points. Create/update .agent/context/architecture.md');
+                        fi.println(chalk.green('  ✓ Documentación del proyecto generada.\n'));
+                    }
                     const task = args.slice(1).join(' ');
                     const engine = new AgentEngine(config, dir, gCoordinatorCmd, rl, fi, handleCmd);
                     const result = await engine.runOrchestrator(task);
@@ -1057,6 +1119,9 @@ export async function runRepl(resumeSession) {
             case 'auth-status':
                 await cmdAuthStatus(fi);
                 break;
+            case 'usage':
+                await cmdUsage(fi);
+                break;
             case 'tasks':
                 await cmdTasks(fi);
                 break;
@@ -1106,6 +1171,16 @@ export async function runRepl(resumeSession) {
                     fi.println(chalk.red('  No roles configured. Run /config-multi first.'));
                 }
                 else {
+                    // Before running the orchestrator, ensure project documentation exists
+                    const contextDir = path.join(dir, '.agent', 'context');
+                    const archPath = path.join(contextDir, 'architecture.md');
+                    if (!(await fileExists(archPath))) {
+                        fi.println(chalk.yellow('\n  ── Generando documentación del proyecto ──'));
+                        fi.println(chalk.dim('  El orquestador necesita conocer la estructura del proyecto primero.\n'));
+                        const engine = new AgentEngine(config, dir, gCoordinatorCmd, rl, fi, handleCmd);
+                        await engine.runExplorer('Document the complete project structure, services, dependencies, and entry points. Create/update .agent/context/architecture.md');
+                        fi.println(chalk.green('  ✓ Documentación del proyecto generada.\n'));
+                    }
                     const engine = new AgentEngine(config, dir, gCoordinatorCmd, rl, fi, handleCmd);
                     await engine.runFullCycle(trimmed);
                     session.messages.push({ role: 'agent', content: `[task cycle completed for: ${trimmed}]`, ts: new Date().toISOString() });

package/dist/core/engine.js

@@ -545,6 +545,10 @@ INSTRUCCIONES:
                     log.warn(`${cliName} session expired — using fallback`);
                     return null;
                 }
+                if (err.message?.startsWith('QWEN_QUOTA_EXCEEDED')) {
+                    log.warn(`${cliName} quota exhausted — using fallback`);
+                    return null;
+                }
                 log.warn(`${cliName} direct API call failed: ${err.message}`);
                 return null;
             }
@@ -981,40 +985,364 @@ INSTRUCCIONES:
         await fs.mkdir(path.join(agentDir, 'rules'), { recursive: true });
         // Clean up stray files before running
         await this._cleanContextDir(contextDir);
-        // Read existing architecture doc if any
-        const archPath = path.join(contextDir, 'architecture.md');
-        let existingArch = '';
+        // Build a quick filesystem snapshot to give the explorer context
+        let fsSnapshot = '';
         try {
-            existingArch = await readFile(archPath);
+            const { execSync } = await import('child_process');
+            fsSnapshot = execSync(`find "${this.projectDir}" -maxdepth 3 -not -path '*/.agent/*' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/__pycache__/*' -not -path '*/.venv/*' -not -path '*/target/*' -not -path '*/build/*' -not -name '.git' | sort | head -300`, { encoding: 'utf-8', timeout: 10000 });
+        }
+        catch { /* ignore */ }
+        // Read existing main architecture doc
+        const mainArchPath = path.join(contextDir, 'architecture.md');
+        let existingMainArch = '';
+        try {
+            existingMainArch = await readFile(mainArchPath);
         }
-        catch { /* new project */ }
+        catch { /* new */ }
+        // Read existing per-component docs
+        let existingComponentDocs = '';
+        try {
+            const ctxEntries = await fs.readdir(contextDir);
+            for (const entry of ctxEntries.filter(e => e !== 'architecture.md' && e !== 'explorer-last.md' && e !== 'modules')) {
+                const entryPath = path.join(contextDir, entry);
+                const stat = await fs.stat(entryPath);
+                if (stat.isDirectory()) {
+                    const compArch = path.join(entryPath, 'architecture.md');
+                    if (await fileExists(compArch)) {
+                        existingComponentDocs += `\n=== EXISTING: ${entry}/architecture.md ===\n${(await readFile(compArch)).slice(0, 1500)}\n`;
+                    }
+                }
+            }
+        }
+        catch { /* ignore */ }
         const effectiveTask = task || 'Explorar y documentar todas las aplicaciones y servicios del proyecto';
         const prompt = `TAREA DE EXPLORACION: ${effectiveTask}
 DIRECTORIO_TRABAJO: ${this.projectDir}
 PROYECTO: ${this.config.project}
 STACK: ${this.config.stack}
 
-${existingArch ? `DOCUMENTACION EXISTENTE (actualizar si hay cambios):\n${existingArch.slice(0, 3000)}\n` : 'DOCUMENTACION EXISTENTE: ninguna — crear desde cero.\n'}
-INSTRUCCIONES:
-1. Lista el directorio raiz para identificar todos los servicios/aplicaciones.
-2. Para cada servicio/app: lee su package.json / requirements.txt / pyproject.toml para obtener nombre, stack y dependencias clave.
-3. Explora src/ o app/ de cada servicio: identifica entry point, modulos principales, rutas/endpoints expuestos, puerto configurado.
-4. Identifica dependencias ENTRE servicios (llamadas HTTP, variables de entorno compartidas, bases de datos comunes).
-5. Crea o actualiza el archivo ${archPath} con:
-   - Tabla resumen: | Servicio | Stack | Puerto | Proposito | Entry Point |
-   - Por cada servicio: modulos principales, rutas API clave, dependencias externas
-   - Mapa de dependencias entre servicios
-6. Crea o actualiza archivos individuales en ${contextDir}/<servicio>/architecture.md para cada servicio.
-7. Al terminar lista todos los archivos creados/actualizados.
-
-REGLAS:
-- Escribe UNICAMENTE los archivos indicados: ${archPath} y ${contextDir}/<servicio>/architecture.md
-- NO crees archivos adicionales ni con otros nombres
-- NO modifiques archivos de aplicacion
-- NO ejecutes comandos que cambien estado (npm install, migraciones, etc.)
-- Si un directorio esta en node_modules, dist, .git: ignoralo`;
+ESTRUCTURA DE ARCHIVOS (excluye .agent, node_modules, .git, dist, __pycache__, .venv, target, build):
+${fsSnapshot}
+
+${existingMainArch ? `=== DOC EXISTENTE: architecture.md (principal) ===\n${existingMainArch.slice(0, 2000)}\n` : ''}
+${existingComponentDocs ? `=== DOC EXISTENTE por componente ===\n${existingComponentDocs.slice(0, 3000)}\n` : ''}
+
+================================================================
+OBJETIVO
+================================================================
+Generar documentacion ESCALONADA en 3 niveles, util TANTO para personas funcionales (PM, negocio) como tecnicas (devs).
+Detallada pero NO excesiva. Concreta, con datos REALES leidos de los archivos. Cero especulaciones.
+
+================================================================
+REGLA DE ORO — PROHIBIDO INVENTAR
+================================================================
+NO uses jamas: "Inferido", "Probablemente", "Posiblemente", "Asumido", "(supuesto)", "(quizas)", "parece ser".
+Si no podes verificar un dato leyendo un archivo concreto → OMITELO. Es mejor una doc corta y veraz que una larga llena de suposiciones.
+Cada puerto, version, endpoint, env var, schema o ruta que aparezca en la doc DEBE haber sido leido de un archivo real.
+
+================================================================
+WORKFLOW QUE TENES QUE EJECUTAR (usa tus tools de read_file/grep_search/list_directory)
+================================================================
+1. Lista DIRECTORIO_TRABAJO. Identifica los componentes (apps/services/libs). Descarta lo trivial (solo configs/docs/scripts).
+2. Para CADA componente no trivial, LEE COMO MINIMO:
+   a. Manifest del proyecto: package.json | requirements.txt | pyproject.toml | pom.xml | build.gradle | Cargo.toml | go.mod
+      → de ahi sacas: nombre, version, framework, dependencias clave con sus versiones, scripts/tasks, entry point
+   b. Entry point real: src/main.ts | index.js | app.py | Application.java | cmd/main.go (segun stack)
+      → de ahi sacas: puerto, middlewares, modulos cargados, configuracion inicial
+   c. Archivo de variables de entorno: .env | .env.example | application.yml | config.* | settings.py
+      → de ahi sacas: variables reales con su proposito
+   d. Al menos 2-3 controladores/routers/handlers principales
+      → de ahi extraes endpoints REALES (metodo, ruta, parametros)
+   e. Al menos 2-3 modelos/schemas/entities principales
+      → de ahi extraes el shape de datos
+   f. README.md del componente si existe
+3. Mapea RELACIONES REALES entre componentes (no asumas):
+   - Buscando URLs/hosts de otros servicios en .env
+   - Buscando imports cross-component
+   - Buscando cadenas de conexion a BBDD/colas/cache
+4. Recien con esa informacion concreta, genera los archivos de documentacion.
+
+================================================================
+LENGUAJE DUAL (regla critica)
+================================================================
+Cada seccion abre con UNA linea en lenguaje simple (que entienda un PM/negocio), DESPUES viene el detalle tecnico.
+- MAL: "El microservicio orquesta la persistencia mediante un repositorio."
+- BIEN: "Guarda la informacion del usuario en la base. Internamente usa un repositorio que abstrae la conexion a MongoDB."
+
+================================================================
+ESTRUCTURA DE LOS 3 NIVELES
+================================================================
+
+────────────────────────────────────────────────────────────────
+NIVEL 0 — architecture.md (raiz de .agent/context/)
+Indice global. Objetivo: 50-150 lineas. Concreto.
+────────────────────────────────────────────────────────────────
+Secciones obligatorias:
+
+# ${this.config.project} — Arquitectura Global (NIVEL 0)
+
+> Indice de servicios y relaciones. Lectura escalonada:
+>   NIVEL 0: este archivo
+>   NIVEL 1: .agent/context/[componente]/architecture.md
+>   NIVEL 2: .agent/context/[componente]/modules/[modulo].md
+
+## 1. Overview funcional
+2-4 lineas en lenguaje simple: que es el sistema, para quien sirve, que problema resuelve.
+
+## 2. Componentes del proyecto
+| Componente | Tipo | Stack + version | Puerto | Proposito (negocio) | Entry point |
+|------------|------|-----------------|--------|---------------------|-------------|
+(una fila por componente, con datos REALES)
+
+## 3. Relaciones entre componentes
+| Origen | Destino | Tipo (HTTP / Import / DB / Queue / CORS) | Proposito |
+|--------|---------|------------------------------------------|-----------|
+(una fila por cada relacion confirmada)
+
+## 4. Diagrama de arquitectura
+\`\`\`
+[Frontend Web] ──HTTP──> [API Auth :8081]
+       │                        │
+       │                        v
+       └──HTTP──> [API Core :8080] ──> [MongoDB]
+\`\`\`
+
+## 5. Flujos end-to-end principales (3-5)
+Mappings funcional → tecnico, paso a paso. Ejemplo:
+- **"Un usuario crea un pedido"**: WebApp → POST /orders (API Core) → valida JWT contra API Auth → guarda en MongoDB → devuelve 201 con el pedido.
+
+## 6. Prerequisitos para levantar el proyecto
+Versiones REALES leidas de los manifests (no rangos genericos).
+
+## 7. Comandos globales de desarrollo
+| Comando | Descripcion | Directorio |
+
+## 8. Decisiones de arquitectura globales (opcional, solo si hay)
+
+────────────────────────────────────────────────────────────────
+NIVEL 1 — [componente]/architecture.md
+Detalle del componente. Objetivo: 80-200 lineas. Crear UNO POR CADA componente NO trivial.
+────────────────────────────────────────────────────────────────
+Secciones obligatorias:
+
+# [componente] — Arquitectura (NIVEL 1)
+
+## Que hace
+2-3 lineas en lenguaje simple, sin tecnicismos.
+
+## Casos de uso principales
+3-6 bullets en formato negocio:
+- "Permite al usuario X..."
+- "El sistema usa este servicio para Y..."
+
+## Stack tecnico
+| Item | Valor |
+|------|-------|
+| Lenguaje | TypeScript 5.3 |
+| Framework | NestJS 11.0.1 |
+| ORM | Mongoose 9.3.3 |
+| Auth | Passport JWT |
+(datos reales del manifest)
+
+## Puerto y URLs
+- **Puerto:** 8085 (de PORT en .env)
+- **Swagger / docs:** http://localhost:8085/api/docs (si aplica)
+- **Health check:** GET /health (si existe)
+
+## Estructura interna (arbol real)
+\`\`\`
+src/
+├── main.ts            # entry point, configura CORS y swagger
+├── auth/              # autenticacion JWT
+├── leads/             # gestion de leads
+└── ...
+\`\`\`
+
+## Modulos internos
+| Modulo | Proposito (negocio) | Doc tecnica |
+|--------|---------------------|-------------|
+| auth | Login y validacion de tokens | modules/auth.md |
+| leads | Listado y consulta de negocios | modules/leads.md |
+
+## Endpoints principales
+| Metodo | Ruta | Modulo | Que hace (lenguaje simple) |
+|--------|------|--------|----------------------------|
+| GET | /leads | leads | Lista negocios filtrables |
+| GET | /leads/:id | leads | Detalle de un negocio |
+(SOLO endpoints reales extraidos de los controllers)
+
+## Variables de entorno
+| Variable | Default | Proposito |
+|----------|---------|-----------|
+| PORT | 8085 | Puerto del servicio |
+| MONGODB_URI | mongodb://... | Conexion principal |
+
+## Integraciones con otros servicios / sistemas
+| Servicio externo | Tipo (HTTP/DB/Queue) | Proposito |
+
+## Como levantar
+- **Instalar deps:** \`npm install\`
+- **Servicios necesarios:** MongoDB corriendo, security-api accesible
+- **Comando para iniciar:** \`npm run start:dev\`
+
+## Comandos disponibles
+| Comando | Que hace |
+
+## Decisiones tecnicas relevantes
+(solo si hay decisiones notables; si no, omitir esta seccion)
+
+────────────────────────────────────────────────────────────────
+NIVEL 2 — [componente]/modules/[modulo].md
+Detalle de un modulo interno. Objetivo: 40-120 lineas. Crear UNO POR cada modulo significativo.
+────────────────────────────────────────────────────────────────
+Secciones obligatorias:
+
+# Modulo: [nombre] — [componente]
+
+## Funcion (lenguaje simple)
+1-2 lineas: "Permite al usuario gestionar X" / "El sistema usa este modulo para Y".
+
+## Funcion (tecnica)
+1-2 lineas: como esta implementado a alto nivel.
+
+## Flujos / casos de uso (1-3)
+Escenarios paso a paso. Ejemplo:
+- **Crear un pedido:** Cliente → POST /orders → middleware valida JWT → service.create() → guarda en DB → responde 201
+
+## Endpoints / interfaces publicas (si aplica)
+| Metodo | Ruta | Body | Respuesta |
+|--------|------|------|-----------|
+
+## Modelos / schemas relevantes
+\`\`\`typescript
+// shape REAL extraido del archivo de schema/model
+{
+  _id: ObjectId,
+  name: string,
+  createdAt: Date,
+  ...
+}
+\`\`\`
+
+## Reglas de negocio
+- Validaciones: ...
+- Condiciones especiales: ...
+- Excepciones: ...
+
+## Archivos clave
+| Archivo | Rol |
+|---------|-----|
+| src/leads/leads.controller.ts | Endpoints /leads |
+| src/leads/leads.service.ts | Logica de negocio |
+
+## Dependencias
+- **Internas (mismo componente):** auth, common
+- **Externas:** mongoose, class-validator
+- **Cross-component:** llama a security-api via HTTP para validar JWT
+
+================================================================
+CALIBRACION DE DETALLE
+================================================================
+- NIVEL 0: 50-150 lineas (no menos, no mas)
+- NIVEL 1: 80-200 lineas por componente
+- NIVEL 2: 40-120 lineas por modulo
+- Si te queda corto → leiste pocos archivos, lee mas
+- Si te queda largo → estas repitiendo o agregando relleno, recorta
+
+================================================================
+QUE NO HACER
+================================================================
+- NO usar "Inferido", "Probablemente", "(asumido)", "(quizas)", "parece"
+- NO repetir lo mismo entre niveles sin agregar valor (cada nivel zoomea mas)
+- NO dejar tablas vacias ni con placeholders tipo "..."
+- NO mezclar lenguaje tecnico puro: SIEMPRE empezar funcional, despues tecnico
+- NO documentar componentes triviales (scripts, docs, configs sueltas) con su propia carpeta — mencionalos en NIVEL 0 y listo
+- NO inventar endpoints, env vars, puertos o schemas que no leiste
+
+================================================================
+FORMATO DE SALIDA — OBLIGATORIO
+================================================================
+Devolve UNICAMENTE bloques de archivos separados por marcadores ===. Nada de explicaciones extra fuera de los bloques.
+
+=== architecture.md ===
+[contenido completo del NIVEL 0]
+
+=== nombre-componente-1/architecture.md ===
+[contenido completo del NIVEL 1 del componente 1]
+
+=== nombre-componente-1/modules/auth.md ===
+[contenido completo del NIVEL 2 del modulo auth]
+
+=== nombre-componente-1/modules/leads.md ===
+[contenido completo del NIVEL 2 del modulo leads]
+
+=== nombre-componente-2/architecture.md ===
+...
+
+REGLAS DE PATHS:
+- El archivo principal SIEMPRE es: === architecture.md ===
+- Por componente: === [nombre-componente]/architecture.md ===
+- Por modulo interno: === [nombre-componente]/modules/[nombre-modulo].md ===
+- USA SIEMPRE rutas RELATIVAS, jamas absolutas
+- Documenta TODOS los componentes no triviales del DIRECTORIO_TRABAJO
+- Si existe documentacion previa, ACTUALIZALA preservando lo que sigue siendo valido y agregando lo nuevo`;
         const res = await this.runWithFallback('explorer', prompt, 'Exploracion');
         const text = extractCliText(res);
+        // Parse sections separated by === path/file.md === markers
+        const sections = text.split(/===\s+(.+?\.md)\s*===/).slice(1);
+        let filesWritten = 0;
+        for (let i = 0; i < sections.length; i += 2) {
+            const fileName = sections[i].trim();
+            let content = sections[i + 1] ? sections[i + 1].trim() : '';
+            if (!content)
+                continue;
+            // Clean up code fences if present
+            content = content.replace(/^```markdown\s*/i, '').replace(/^```\s*$/gm, '').trim();
+            try {
+                let targetPath;
+                if (fileName === 'architecture.md' || fileName === 'ARCHITECTURE.md') {
+                    // Main architecture doc
+                    targetPath = mainArchPath;
+                }
+                else {
+                    // CRITICAL: Extract only the relative path components, strip any absolute path prefix
+                    // fileName could be: "datamart-data-access-api/architecture.md"
+                    // or "/home/user/project/datamart-data-access-api/architecture.md" (BAD — must ignore prefix)
+                    // We only want the components relative to contextDir
+                    // Remove any leading absolute path by extracting the last meaningful path segments
+                    const cleanName = fileName.replace(/^.*[\/\\]/, ''); // strip any prefix
+                    // Check if it's a component architecture file: "component/architecture.md" or "component/modules/mod.md"
+                    const pathParts = fileName.split(/[\/\\]/).filter(Boolean);
+                    // Keep only the last 2-3 parts (component name + file)
+                    // e.g. ["/home", "user", "proj", "datamart", "architecture.md"] → ["datamart", "architecture.md"]
+                    // e.g. ["datamart-data-access-api", "architecture.md"] → same
+                    // e.g. ["datamart-data-access-api", "modules", "config.md"] → same
+                    let relPath;
+                    if (pathParts.length >= 3 && pathParts[pathParts.length - 2] === 'modules') {
+                        // component/modules/file.md
+                        relPath = path.join(pathParts[pathParts.length - 3], 'modules', pathParts[pathParts.length - 1]);
+                    }
+                    else if (pathParts.length >= 2) {
+                        // component/file.md
+                        relPath = path.join(pathParts[pathParts.length - 2], pathParts[pathParts.length - 1]);
+                    }
+                    else {
+                        // fallback
+                        relPath = path.join('modules', cleanName);
+                    }
+                    targetPath = path.join(contextDir, relPath);
+                }
+                await fs.mkdir(path.dirname(targetPath), { recursive: true });
+                await writeFile(targetPath, content);
+                filesWritten++;
+            }
+            catch (err) {
+                log.warn(`Failed to write ${fileName}: ${err.message}`);
+            }
+        }
+        if (filesWritten > 0) {
+            log.ok(`${filesWritten} documentation file(s) written`);
+        }
         // Overwrite the single last-run report (no timestamp accumulation)
         try {
             await writeFile(path.join(contextDir, 'explorer-last.md'), `# Explorer Report\n\nTask: ${effectiveTask}\nDate: ${new Date().toISOString()}\n\n${text}\n`);
@@ -1048,16 +1376,47 @@ PROYECTO: ${this.config.project}
 ${existingArch ? `DOCUMENTACION EXISTENTE:\n${existingArch.slice(0, 3000)}\n` : 'Sin documentacion previa.\n'}
 CONTEXTO: ${context.slice(0, 2000)}
 
-INSTRUCCIONES:
-1. Lista el directorio raiz e identifica todos los servicios/apps.
-2. Para cada uno: lee package.json/requirements.txt, explora src/, identifica entry point, rutas/endpoints, puerto.
-3. Identifica dependencias entre servicios.
-4. Crea/actualiza ${archPath} con tabla resumen y detalle por servicio.
-5. Crea/actualiza ${contextDir}/<servicio>/architecture.md para cada servicio.
-
-REGLAS:
-- Escribe UNICAMENTE los archivos indicados: ${archPath} y ${contextDir}/<servicio>/architecture.md
-- NO crees archivos adicionales ni con otros nombres en ningun directorio`);
+OBJETIVO
+Generar documentacion ESCALONADA en 3 niveles (global / componente / modulo), util para perfiles funcionales y tecnicos. Detallada pero concreta. Cero suposiciones.
+
+REGLA DE ORO — PROHIBIDO ESPECULAR
+NO uses "Inferido", "Probablemente", "Asumido", "(quizas)", "parece". Si no podes verificar un dato leyendo un archivo, OMITELO. Cada puerto, version, endpoint, env var y schema debe haber sido leido de un archivo real.
+
+WORKFLOW (usa tus tools)
+1. Lista DIRECTORIO_TRABAJO y detecta los componentes no triviales.
+2. Para cada componente, LEE como minimo:
+   - Manifest (package.json | requirements.txt | pom.xml | build.gradle | go.mod | Cargo.toml)
+   - Entry point (main.ts | index.js | app.py | Application.java | cmd/main.go)
+   - .env / .env.example / application.yml / settings.py
+   - 2-3 controladores/routers principales (para endpoints reales)
+   - 2-3 schemas/models principales (para shapes reales)
+3. Mapea relaciones reales (URLs en .env, imports cross-component, conexiones a DB/colas).
+
+LENGUAJE DUAL
+Cada seccion abre con UNA linea simple (que entienda un PM). Despues, el detalle tecnico.
+- MAL: "El microservicio orquesta la persistencia mediante un repositorio."
+- BIEN: "Guarda la informacion del usuario. Internamente usa un repositorio que abstrae MongoDB."
+
+NIVEL 0 — ${archPath} (50-150 lineas)
+Secciones: Overview funcional · Tabla de componentes (con stack+version, puerto, proposito, entry point) · Tabla de relaciones (origen, destino, tipo, proposito) · Diagrama ASCII · 3-5 flujos end-to-end (mapping funcional → tecnico) · Prerequisitos · Comandos globales.
+
+NIVEL 1 — ${contextDir}/<componente>/architecture.md (80-200 lineas, uno por componente)
+Secciones: Que hace (simple) · Casos de uso (3-6 bullets en formato negocio) · Stack tecnico (tabla con versiones reales) · Puerto y URLs · Estructura interna (arbol real) · Tabla de modulos · Tabla de endpoints reales · Tabla de variables de entorno · Integraciones · Como levantar · Comandos.
+
+NIVEL 2 — ${contextDir}/<componente>/modules/<modulo>.md (40-120 lineas, uno por modulo significativo)
+Secciones: Funcion (simple) · Funcion (tecnica) · Flujos / casos de uso paso a paso · Endpoints / interfaces · Schemas reales en codigo · Reglas de negocio · Archivos clave · Dependencias internas/externas/cross-component.
+
+CALIBRACION
+- NIVEL 0: 50-150 lineas. NIVEL 1: 80-200 por componente. NIVEL 2: 40-120 por modulo.
+- Si te queda corto, leiste pocos archivos. Si te queda largo, recorta el relleno.
+- Componentes triviales (solo scripts/docs): mencionalos en NIVEL 0 y NO les crees subcarpeta.
+
+REGLAS DE ESCRITURA
+- Solo podes escribir archivos dentro de ${contextDir}/
+- NO crees archivos sueltos en la raiz de ${contextDir}/ (excepto architecture.md)
+- Por componente usa: ${contextDir}/<componente>/architecture.md
+- Por modulo usa: ${contextDir}/<componente>/modules/<modulo>.md
+- Si existe documentacion previa, ACTUALIZALA preservando lo valido`);
         let result;
         const sp = this._startSpinner(`agent-explorer  ${role.model}`);
         try {

package/dist/index.js

@@ -38,6 +38,7 @@ program
     .option('--model [cli]', 'Alias for --models')
     .option('--reset-coordinator', 'Clear coordinator selection (re-pick on next run)')
     .option('--reset-auth', 'Wipe all auth credentials and start fresh')
+    .option('--usage', 'Check quota status for all role CLIs')
     .addHelpText('after', `
 Setup subcommands:
   agent-mp setup init            Full interactive wizard (login + roles + project)
@@ -131,6 +132,22 @@ if (nativeRole) {
         }
         process.exit(0);
     }
+    // --usage: check quota status with test API call
+    if (args.includes('--usage') || args.includes('usage')) {
+        const { qwenUsage, getTokenPath } = await import('./utils/qwen-auth.js');
+        const result = await qwenUsage();
+        const exp = result.token ? new Date(result.token.expiresAt).toLocaleString() : 'N/A';
+        if (result.ok) {
+            console.log(chalk.green(`  ✓ ${PKG_NAME}: quota OK`));
+            console.log(chalk.dim(`  Token expires: ${exp}`));
+            console.log(chalk.dim(`  Model: ${result.model}`));
+        }
+        else {
+            console.log(chalk.red(`  ✗ ${PKG_NAME}: ${result.error}`));
+            console.log(chalk.dim(`  Token expires: ${exp}`));
+        }
+        process.exit(result.ok ? 0 : 1);
+    }
     // Parse --model flag if provided
     const modelIdx = args.findIndex(a => a === '--model' || a === '-m');
     let model;
@@ -150,6 +167,23 @@ if (nativeRole) {
 }
 // ─────────────────────────────────────────────────────────────────────────────
 program.action(async (task, options) => {
+    // --usage: check quota status
+    if (options.usage) {
+        const { qwenUsage } = await import('./utils/qwen-auth.js');
+        const { PKG_NAME } = await import('./utils/config.js');
+        const result = await qwenUsage();
+        const exp = result.token ? new Date(result.token.expiresAt).toLocaleString() : 'N/A';
+        if (result.ok) {
+            console.log(chalk.green(`  ✓ ${PKG_NAME}: quota OK`));
+            console.log(chalk.dim(`  Token expires: ${exp}`));
+            console.log(chalk.dim(`  Model: ${result.model}`));
+        }
+        else {
+            console.log(chalk.red(`  ✗ ${PKG_NAME}: ${result.error}`));
+            console.log(chalk.dim(`  Token expires: ${exp}`));
+        }
+        process.exit(result.ok ? 0 : 1);
+    }
     if (options.resetCoordinator || options.resetAuth) {
         const authFile = path.join(AGENT_HOME, 'auth.json');
         const qwenCreds = path.join(AGENT_HOME, 'oauth_creds.json');

package/dist/utils/config.d.ts

@@ -1,9 +1,10 @@
 import { AgentConfig } from '../types.js';
 /**
  * Resolve the actual project root starting from a given directory.
- * If .agent/config.json exists in the start dir, scan subdirectories
- * for a deeper project root (indicated by common project files).
- * Returns the deepest valid project root found, or the original dir.
+ * If .agent/config.json exists in the start dir, use it directly
+ * (the user already configured this as the project root).
+ * If not, walk up the directory tree looking for .agent/config.json.
+ * Returns the resolved project root.
  */
 export declare function resolveProjectDir(startDir: string): Promise<string>;
 export declare const PKG_NAME: string;

package/dist/utils/config.js

@@ -3,46 +3,29 @@ import * as fsSync from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 const KNOWN_PKGS = ['agent-mp', 'agent-orch', 'agent-impl', 'agent-rev', 'agent-explorer'];
-// Files/dirs that indicate a directory is the real project root
-const PROJECT_INDICATORS = [
-    'package.json', 'pyproject.toml', 'requirements.txt', 'setup.py', 'setup.cfg',
-    'Cargo.toml', 'go.mod', 'Gemfile', 'pom.xml', 'build.gradle', 'build.gradle.kts',
-    'CMakeLists.txt', 'Makefile', 'composer.json', 'mix.exs', 'pubspec.yaml',
-    'src', 'app', 'lib', 'main.py', 'app.py', 'index.js', 'index.ts',
-    'main.go', 'main.rs', 'lib.rs', 'app.js', 'app.ts',
-];
 /**
  * Resolve the actual project root starting from a given directory.
- * If .agent/config.json exists in the start dir, scan subdirectories
- * for a deeper project root (indicated by common project files).
- * Returns the deepest valid project root found, or the original dir.
+ * If .agent/config.json exists in the start dir, use it directly
+ * (the user already configured this as the project root).
+ * If not, walk up the directory tree looking for .agent/config.json.
+ * Returns the resolved project root.
  */
 export async function resolveProjectDir(startDir) {
-    const hasAgentConfig = await fileExists(path.join(startDir, '.agent', 'config.json'));
-    if (!hasAgentConfig)
+    // If .agent/config.json exists in current dir, use it — user already configured this
+    if (await fileExists(path.join(startDir, '.agent', 'config.json'))) {
         return startDir;
-    // Scan immediate subdirectories for a deeper project root
-    let bestDir = startDir;
-    let bestScore = 0;
-    try {
-        const entries = await fs.readdir(startDir, { withFileTypes: true });
-        for (const entry of entries) {
-            if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules')
-                continue;
-            const subDir = path.join(startDir, entry.name);
-            let score = 0;
-            for (const indicator of PROJECT_INDICATORS) {
-                if (await fileExists(path.join(subDir, indicator)))
-                    score++;
-            }
-            if (score > bestScore) {
-                bestScore = score;
-                bestDir = subDir;
-            }
+    }
+    // Walk up the directory tree looking for .agent/config.json
+    let current = startDir;
+    while (current !== path.dirname(current)) {
+        const parent = path.dirname(current);
+        if (await fileExists(path.join(parent, '.agent', 'config.json'))) {
+            return parent;
         }
+        current = parent;
     }
-    catch { /* ignore */ }
-    return bestDir;
+    // No .agent/config.json found — return original dir (will fail gracefully)
+    return startDir;
 }
 async function fileExists(p) {
     try {

package/dist/utils/qwen-auth.d.ts

@@ -2,6 +2,13 @@
 export declare const QWEN_AGENT_HOME: string;
 /** Dynamic getter (recommended for runtime changes) */
 export declare function getQwenHome(): string;
+interface QwenToken {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    idToken?: string;
+    resourceUrl?: string;
+}
 export declare function getTokenPath(): Promise<string>;
 export declare function qwenLogin(): Promise<boolean>;
 export declare function qwenAuthStatus(): Promise<{
@@ -20,3 +27,11 @@ export declare function callQwenAPI(prompt: string, model?: string, onData?: (ch
  * Calls the Qwen REST API directly — no dependency on any qwen CLI binary.
  */
 export declare function callQwenAPIFromCreds(prompt: string, model: string, credsPath: string, onData?: (chunk: string) => void): Promise<string>;
+/** Check quota status by making a minimal test API call */
+export declare function qwenUsage(credsPath?: string): Promise<{
+    ok: boolean;
+    token: QwenToken | null;
+    error?: string;
+    model?: string;
+}>;
+export {};

package/dist/utils/qwen-auth.js

@@ -286,9 +286,14 @@ async function callQwenAPIWithToken(token, prompt, model, onData) {
     });
     if (!response.ok) {
         const errorText = await response.text();
-        if (response.status === 401 || (response.status === 429 && errorText.includes('insufficient_quota'))) {
+        // 401 = auth error, refresh may help
+        if (response.status === 401) {
             throw new Error(`QWEN_AUTH_EXPIRED: ${errorText}`);
         }
+        // 429 insufficient_quota = daily quota exhausted, refresh won't help
+        if (response.status === 429 && errorText.includes('insufficient_quota')) {
+            throw new Error(`QWEN_QUOTA_EXCEEDED: ${errorText}`);
+        }
         throw new Error(`Qwen API error: ${response.status} - ${errorText}`);
     }
     if (!useStream) {
@@ -342,6 +347,9 @@ export async function callQwenAPI(prompt, model = 'coder-model', onData) {
         return await callQwenAPIWithToken(token, prompt, model, onData);
     }
     catch (err) {
+        // Quota errors: refresh won't help, propagate immediately
+        if (err.message?.startsWith('QWEN_QUOTA_EXCEEDED'))
+            throw err;
         if (!err.message?.startsWith('QWEN_AUTH_EXPIRED'))
             throw err;
         if (token.refreshToken) {
@@ -390,6 +398,9 @@ export async function callQwenAPIFromCreds(prompt, model, credsPath, onData) {
         return await callQwenAPIWithToken(token, prompt, model, onData);
     }
     catch (err) {
+        // Quota errors: refresh won't help, propagate immediately
+        if (err.message?.startsWith('QWEN_QUOTA_EXCEEDED'))
+            throw err;
         if (!err.message?.startsWith('QWEN_AUTH_EXPIRED'))
             throw err;
         if (token.refreshToken) {
@@ -402,3 +413,80 @@ export async function callQwenAPIFromCreds(prompt, model, credsPath, onData) {
         throw new Error(`QWEN_AUTH_EXPIRED: Sesión expirada. Ejecutá: ${cliName} --login`);
     }
 }
+/** Check quota status by making a minimal test API call */
+export async function qwenUsage(credsPath) {
+    let token;
+    if (credsPath) {
+        try {
+            const raw = JSON.parse(await fs.readFile(credsPath, 'utf-8'));
+            token = {
+                accessToken: raw.accessToken || raw.access_token || '',
+                refreshToken: raw.refreshToken || raw.refresh_token || '',
+                expiresAt: raw.expiresAt || raw.expiry_date || 0,
+                idToken: raw.idToken || raw.id_token,
+                resourceUrl: raw.resourceUrl || raw.resource_url,
+            };
+        }
+        catch {
+            return { ok: false, token: null, error: 'No credentials found' };
+        }
+    }
+    else {
+        token = await loadToken();
+    }
+    if (!token || !token.accessToken) {
+        return { ok: false, token, error: 'No access token — run --login' };
+    }
+    if (token.expiresAt < Date.now()) {
+        // Try refresh
+        if (token.refreshToken) {
+            const refreshed = await doRefreshToken(token.refreshToken);
+            if (refreshed) {
+                token = refreshed;
+                if (!credsPath)
+                    await saveToken(refreshed);
+                else
+                    await fs.writeFile(credsPath, JSON.stringify(refreshed, null, 2), 'utf-8');
+            }
+            else {
+                return { ok: false, token, error: 'Token expired and refresh failed' };
+            }
+        }
+        else {
+            return { ok: false, token, error: 'Token expired, no refresh token' };
+        }
+    }
+    // Make a minimal test call to check quota
+    try {
+        const result = await callQwenAPIWithToken(token, 'ping', 'coder-model');
+        return { ok: true, token, model: 'coder-model' };
+    }
+    catch (err) {
+        // If auth failed, try refresh even if expiresAt hasn't passed yet
+        if (err.message?.startsWith('QWEN_AUTH_EXPIRED') && token.refreshToken) {
+            const refreshed = await doRefreshToken(token.refreshToken);
+            if (refreshed) {
+                token = refreshed;
+                if (!credsPath)
+                    await saveToken(refreshed);
+                else
+                    await fs.writeFile(credsPath, JSON.stringify(refreshed, null, 2), 'utf-8');
+                // Retry with new token
+                try {
+                    await callQwenAPIWithToken(refreshed, 'ping', 'coder-model');
+                    return { ok: true, token: refreshed, model: 'coder-model' };
+                }
+                catch (err2) {
+                    if (err2.message?.startsWith('QWEN_QUOTA_EXCEEDED')) {
+                        return { ok: false, token: refreshed, error: 'Daily quota exhausted — wait or --login with different account' };
+                    }
+                    return { ok: false, token: refreshed, error: err2.message };
+                }
+            }
+        }
+        if (err.message?.startsWith('QWEN_QUOTA_EXCEEDED')) {
+            return { ok: false, token, error: 'Daily quota exhausted — wait or --login with different account' };
+        }
+        return { ok: false, token, error: err.message };
+    }
+}

package/package.json

@@ -1 +1 @@
-{"name":"agent-rev","version":"0.5.10","description":"Deterministic multi-agent CLI orchestrator — plan, code, review","type":"module","main":"./dist/index.js","files":["dist/"],"bin":{"agent-rev":"dist/index.js"},"scripts":{"build":"tsc && echo '#!/usr/bin/env node' | cat - dist/index.js > dist/index.tmp && mv dist/index.tmp dist/index.js && chmod +x dist/index.js","dev":"tsx src/index.ts","prepublishOnly":"npm run build"},"keywords":["ai","agent","orchestrator","multi-agent","cli","coding"],"license":"MIT","dependencies":{"@anthropic-ai/sdk":"^0.39.0","@google/generative-ai":"^0.24.0","chalk":"^5.4.1","commander":"^13.1.0","open":"^11.0.0","openai":"^4.91.0"},"devDependencies":{"@types/node":"^22.13.0","@types/open":"^6.1.0","tsx":"^4.19.3","typescript":"^5.7.3"},"engines":{"node":">=18.0.0"}}
+{"name":"agent-rev","version":"0.5.12","description":"Deterministic multi-agent CLI orchestrator — plan, code, review","type":"module","main":"./dist/index.js","files":["dist/"],"bin":{"agent-rev":"dist/index.js"},"scripts":{"build":"tsc && echo '#!/usr/bin/env node' | cat - dist/index.js > dist/index.tmp && mv dist/index.tmp dist/index.js && chmod +x dist/index.js","dev":"tsx src/index.ts","prepublishOnly":"npm run build"},"keywords":["ai","agent","orchestrator","multi-agent","cli","coding"],"license":"MIT","dependencies":{"@anthropic-ai/sdk":"^0.39.0","@google/generative-ai":"^0.24.0","chalk":"^5.4.1","commander":"^13.1.0","open":"^11.0.0","openai":"^4.91.0"},"devDependencies":{"@types/node":"^22.13.0","@types/open":"^6.1.0","tsx":"^4.19.3","typescript":"^5.7.3"},"engines":{"node":">=18.0.0"}}