@milpa/comal 0.1.0 → 0.1.2

package/src/permissions.mjs

@@ -5,53 +5,89 @@ import { inspectAutoAction, intentCoversAction } from './auto-guard.mjs';
 import { randomUUID } from 'node:crypto';
 import { readOnlyBashCheck, chromeLabObservation } from './read-only-check.mjs';
 READ_TOOLS.add('ToolPack');
-for (const name of ['ArtifactAccount','ArtifactList','ArtifactInspect']) READ_TOOLS.add(name);
+for (const name of ['ArtifactAccount','ArtifactCapabilities','ArtifactList','ArtifactInspect']) READ_TOOLS.add(name);
 for (const name of ['ListDirectory', 'FileInfo']) READ_TOOLS.add(name);
 for (const name of ['ListAgents','SendMessage','ProviderCapabilities','ProviderSearch','AnalyzeMedia']) READ_TOOLS.add(name);
 
 export const PERMISSION_MODES = ['default', 'acceptEdits', 'plan', 'auto'];
 export function nextPermissionMode(mode) { return PERMISSION_MODES[(PERMISSION_MODES.indexOf(mode) + 1) % PERMISSION_MODES.length]; }
 
+// A UI callback may be shared by resident and subagent policies. One visible
+// question at a time prevents another invocation from replacing its authority.
+const confirmationQueues = new WeakMap();
+function waitWithAbort(promise, signal) {
+  const pending=Promise.resolve(promise);
+  if (!signal) return pending;
+  if(signal.aborted){pending.catch(()=>{});return Promise.reject(signal.reason);}
+  return new Promise((resolve, reject) => {
+    let settled=false;
+    const finish = (callback, value) => { if(settled)return;settled=true;signal.removeEventListener('abort', abort); callback(value); };
+    const abort = () => finish(reject, signal.reason);
+    signal.addEventListener('abort', abort, {once:true});
+    pending.then(value => finish(resolve,value), error => finish(reject,error));
+  });
+}
+function permissionStamp(policy) {
+  return JSON.stringify([policy.mode,[...policy.allowed].sort(),[...policy.denied].sort(),policy.context?.intentions]);
+}
+
 export class PermissionPolicy {
   constructor({ mode = 'default', allowed = [], denied = [], confirm, classifier, cwd, onDecision = () => {} } = {}) {
-    if (!PERMISSION_MODES.includes(mode)) throw new Error('Modo de permisos inválido. Usa default, plan, acceptEdits o auto.');
+    if (!PERMISSION_MODES.includes(mode)) throw new Error('Invalid permission mode. Use default, plan, acceptEdits or auto.');
     this.mode = mode; this.allowed = new Set(allowed); this.denied = new Set(denied); this.confirm = confirm;
     this.classifier = classifier; this.cwd = cwd; this.onDecision = onDecision; this.context = { intentions: [], actions: [] };
   }
   setContext(context) { this.context = context; }
   async authorize(name, input, { signal, onWaiting } = {}) {
     signal?.throwIfAborted();
-    if (this.denied.has(name)) return { allowed: false, reason: 'Regla de denegación explícita' };
+    if (this.denied.has(name)) return { allowed: false, reason: 'Explicit denial rule' };
     const knownRead = READ_TOOLS.has(name) || this.allowed.has(name) && chromeLabObservation(name);
-    if (name === 'Agent' || name === 'AgentBatch') return { allowed: true, reason: 'Delegación: cada acción del hijo conserva los permisos de la sesión' };
-    if (this.mode === 'plan' && !knownRead) return { allowed: false, reason: 'Modo plan: sólo lectura' };
-    if (name === 'Bash' && readOnlyBashCheck(input.command)) return { allowed: true, reason: 'Comprobación de lectura nativa con argv fijo; no requiere clasificador.' };
+    if (name === 'Agent' || name === 'AgentBatch') return { allowed: true, reason: 'Delegation: every child action retains the session permissions' };
+    if (this.mode === 'plan' && !knownRead) return { allowed: false, reason: 'Plan mode: read-only' };
+    if (name === 'Bash' && readOnlyBashCheck(input.command)) return { allowed: true, reason: 'Native read-only check with fixed argv; no classifier required.' };
     if (this.mode === 'auto' && !knownRead) return this.authorizeAuto(name, input, signal, onWaiting);
-    if (knownRead || this.allowed.has(name) || (this.mode === 'acceptEdits' && EDIT_TOOLS.has(name))) return { allowed: true, reason: 'Política de sesión' };
+    if (knownRead || this.allowed.has(name) || (this.mode === 'acceptEdits' && EDIT_TOOLS.has(name))) return { allowed: true, reason: 'Session policy' };
     const allowed = await this.ask(name, input, signal, onWaiting);
-    return { allowed, reason: allowed ? 'Confirmación del usuario' : 'Sin autorización para esta herramienta' };
+    return { allowed, reason: allowed ? 'User confirmation' : 'No authorization for this tool' };
   }
   async ask(name, input, signal, onWaiting) {
     if (!this.confirm) return false;
-    const questionId = randomUUID(); let allowed = false;
-    await onWaiting?.({ type: 'house_waiting', question_id: questionId });
-    try { signal?.throwIfAborted(); allowed = Boolean(await this.confirm(name, input)); return allowed; }
-    finally { await onWaiting?.({ type: 'house_answered', question_id: questionId, allowed }); }
+    const confirm=this.confirm, stamp=permissionStamp(this), previous=confirmationQueues.get(confirm) || Promise.resolve();
+    let release;
+    const slot=new Promise(resolve => {release=resolve;});
+    const tail=previous.catch(() => {}).then(() => slot);
+    confirmationQueues.set(confirm,tail);
+    const questionId=randomUUID();let allowed=false,displayed=false;
+    try {
+      await waitWithAbort(previous,signal);
+      signal?.throwIfAborted();
+      // Do not show a stale question. House observes the changed authority and
+      // calls authorize again, so newly denied/plan actions cannot reach a UI.
+      if(this.confirm!==confirm || stamp!==permissionStamp(this))return false;
+      await onWaiting?.({type:'house_waiting',question_id:questionId});
+      displayed=true;signal?.throwIfAborted();
+      allowed=Boolean(await waitWithAbort(confirm(name,input,{signal,questionId}),signal));
+      signal?.throwIfAborted();
+      return stamp===permissionStamp(this) && this.confirm===confirm ? allowed : false;
+    } finally {
+      try { if(displayed)await onWaiting?.({type:'house_answered',question_id:questionId,allowed:allowed && !signal?.aborted && stamp===permissionStamp(this)}); }
+      finally {release();if(confirmationQueues.get(confirm)===tail)tail.then(()=>{if(confirmationQueues.get(confirm)===tail)confirmationQueues.delete(confirm);});}
+    }
   }
   async authorizeAuto(name, input, signal, onWaiting) {
     const inspection = inspectAutoAction(name, input, this.cwd || process.cwd());
     const data = { workspace: this.cwd, human_requests: this.context.intentions, previous_tool_calls: this.context.actions, proposed_action: { name, input } };
     let verdict;
     if (inspection.hard) verdict = { decision: 'deny', risk: 'destructive', reason: inspection.hard, intent_quote: '', source: 'guard' };
-    else if (!this.classifier || !data.human_requests.length || Buffer.byteLength(JSON.stringify(data)) > 64000) verdict = { decision: 'ask', risk: 'unknown', reason: 'No hay clasificador o contexto de intención suficiente para aprobar automáticamente.', intent_quote: '', source: 'guard' };
+    else if (!this.classifier || !data.human_requests.length || Buffer.byteLength(JSON.stringify(data)) > 64000) verdict = { decision: 'ask', risk: 'unknown', reason: 'No classifier or insufficient intent context for automatic approval.', intent_quote: '', source: 'guard' };
     else try {
       verdict = { ...await this.classifier.classify(data, signal), source: 'classifier' };
-      if (verdict.decision === 'allow' && (inspection.opaque || verdict.risk === 'unknown')) verdict = { ...verdict, decision: 'ask', reason: 'La acción contiene expansión, ejecución opaca o efectos desconocidos; requiere revisión.' };
-      if (verdict.decision === 'allow' && (inspection.destructive || verdict.risk === 'destructive') && !intentCoversAction(verdict, data.proposed_action, inspection, data.human_requests)) verdict = { ...verdict, decision: 'deny', reason: 'La intención más reciente no autoriza explícitamente la acción destructiva y su destino.' };
-      if (verdict.decision === 'allow' && verdict.risk === 'external' && (!verdict.intent_quote || !data.human_requests.at(-1)?.includes(verdict.intent_quote))) verdict = { ...verdict, decision: 'ask', reason: 'Falta autorización explícita para el efecto externo.' };
+      if (verdict.decision === 'allow' && (inspection.opaque || verdict.risk === 'unknown')) verdict = { ...verdict, decision: 'ask', reason: 'The action contains expansion, opaque execution or unknown effects; review is required.' };
+      if (verdict.decision === 'allow' && (inspection.destructive || verdict.risk === 'destructive') && !intentCoversAction(verdict, data.proposed_action, inspection, data.human_requests)) verdict = { ...verdict, decision: 'deny', reason: 'The latest intent does not explicitly authorize the destructive action and its target.' };
+      if (verdict.decision === 'allow' && verdict.risk === 'external' && (!verdict.intent_quote || !data.human_requests.at(-1)?.includes(verdict.intent_quote))) verdict = { ...verdict, decision: 'ask', reason: 'Explicit authorization for the external effect is missing.' };
     } catch (error) {
       if (signal?.aborted || error.code === 'GOAL_BUDGET') throw error;
-      verdict = { decision: 'ask', risk: 'unknown', reason: `Verificador auto no disponible: ${error.message}`, intent_quote: '', source: 'classifier-error' };
+      verdict = { decision: 'ask', risk: 'unknown', reason: `Auto verifier unavailable: ${error.message}`, intent_quote: '', source: 'classifier-error' };
     }
     signal?.throwIfAborted();
     if (this.mode !== 'auto') return this.authorize(name, input, { signal, onWaiting });

package/src/provider-auth.mjs

@@ -16,7 +16,7 @@ const failure = (message, code = 'PROVIDER_AUTH_FAILED') => Object.assign(new Er
 function definition(name) {
   const id = String(name || '').toLowerCase();
   const found = AUTH_PROVIDERS.find(item => item.id === ({ grokia: 'grok', xai: 'grok', chatgpt: 'codex', 'kimi-code': 'kimi' }[id] || id));
-  if (!found) throw failure('Proveedor de login desconocido: codex, kimi, minimax o grok.', 'PROVIDER_AUTH_UNKNOWN');
+  if (!found) throw failure('Unknown login provider: codex, kimi, minimax or grok.', 'PROVIDER_AUTH_UNKNOWN');
   return found;
 }
 export function authProviderDefaults(name) {
@@ -28,7 +28,7 @@ function tokenClaims(token) {
 }
 function secret(value) { return typeof value === 'string' && value.length > 0 && value.length <= 32768 && !/[\x00-\x20\x7f]/.test(value); }
 function tokenRecord(provider, payload, now, previous = {}) {
-  if (!secret(payload?.access_token)) throw failure('El servidor no entregó un access_token válido.');
+  if (!secret(payload?.access_token)) throw failure('The server did not return a valid access_token.');
   const claims = tokenClaims(payload.access_token), identity = tokenClaims(payload.id_token || previous.idToken);
   const auth = claims['https://api.openai.com/auth'] || identity['https://api.openai.com/auth'] || {};
   const ttl = Number(payload.expires_in);
@@ -49,7 +49,7 @@ export class AuthManager {
   async _directory() {
     await mkdir(this.directory, { recursive: true, mode: 0o700 });
     const info = await lstat(this.directory);
-    if (!info.isDirectory() || info.isSymbolicLink() || typeof process.getuid === 'function' && info.uid !== process.getuid()) throw failure('Directorio de credenciales inseguro.');
+    if (!info.isDirectory() || info.isSymbolicLink() || typeof process.getuid === 'function' && info.uid !== process.getuid()) throw failure('Insecure credential directory.');
     await chmod(this.directory, 0o700);
   }
   async _read(provider) {
@@ -57,14 +57,14 @@ export class AuthManager {
     let handle;
     try {
       const dir = await lstat(this.directory);
-      if (!dir.isDirectory() || dir.isSymbolicLink() || dir.mode & 0o077 || typeof process.getuid === 'function' && dir.uid !== process.getuid()) throw failure('Directorio de credenciales inseguro.');
+      if (!dir.isDirectory() || dir.isSymbolicLink() || dir.mode & 0o077 || typeof process.getuid === 'function' && dir.uid !== process.getuid()) throw failure('Insecure credential directory.');
       handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
       const info = await handle.stat();
-      if (!info.isFile() || info.size > 65536 || info.mode & 0o077 || typeof process.getuid === 'function' && info.uid !== process.getuid()) throw failure('Archivo de credenciales inseguro.');
+      if (!info.isFile() || info.size > 65536 || info.mode & 0o077 || typeof process.getuid === 'function' && info.uid !== process.getuid()) throw failure('Insecure credential file.');
       const record = JSON.parse(await handle.readFile('utf8'));
-      if (record.version !== 1 || record.provider !== provider || !secret(record.accessToken)) throw failure('Credenciales guardadas inválidas.');
+      if (record.version !== 1 || record.provider !== provider || !secret(record.accessToken)) throw failure('Invalid stored credentials.');
       return record;
-    } catch (error) { if (error.code === 'ENOENT') return null; throw failure('No se pudieron leer credenciales privadas.', 'PROVIDER_AUTH_STORE'); }
+    } catch (error) { if (error.code === 'ENOENT') return null; throw failure('Could not read private credentials.', 'PROVIDER_AUTH_STORE'); }
     finally { await handle?.close(); }
   }
   async _write(record) {
@@ -84,11 +84,11 @@ export class AuthManager {
       signal?.throwIfAborted();
       try { await mkdir(lock, { mode: 0o700 }); break; }
       catch (error) {
-        if (error.code !== 'EEXIST') throw failure('No se pudo bloquear el almacén de login.');
+        if (error.code !== 'EEXIST') throw failure('Could not lock the login store.');
         let info; try { info = await lstat(lock); } catch (e) { if (e.code === 'ENOENT') continue; throw e; }
-        if (!info.isDirectory() || info.isSymbolicLink()) throw failure('Bloqueo de credenciales inseguro.');
+        if (!info.isDirectory() || info.isSymbolicLink()) throw failure('Insecure credential lock.');
         if (Date.now() - info.mtimeMs > 120000) { await rmdir(lock).catch(() => {}); continue; }
-        if (Date.now() >= until) throw failure('Otro proceso está actualizando login; reintenta.', 'PROVIDER_AUTH_BUSY');
+        if (Date.now() >= until) throw failure('Another process is updating login; retry.', 'PROVIDER_AUTH_BUSY');
         await delay(50, undefined, { signal });
       }
     }
@@ -101,8 +101,8 @@ export class AuthManager {
       status: !record ? 'logged_out' : record.expiresAt && record.expiresAt <= this.now() ? 'expired' : record.method === 'device_code' ? 'authenticated' : 'configured',
       ...(record?.expiresAt ? { expiresAt: record.expiresAt } : {}),
       ...(p.apiKeyEnv ? { apiKeyEnv: p.apiKeyEnv } : {}), documentation: p.documentation,
-      ...(p.experimental ? { experimental: true, note: 'OAuth compatible con el código público Kimi CLI; la vía documentada para clientes externos es una clave Kimi Code (--api-key-env KIMI_CODE_API_KEY).' } : {}),
-      ...(p.id === 'grok' ? { note: 'La API usa facturación API; no se encontró login público de suscripción Grok para Comal.' } : {}) };
+      ...(p.experimental ? { experimental: true, note: 'OAuth compatible with the public Kimi CLI code; the documented route for external clients is a Kimi Code key (--api-key-env KIMI_CODE_API_KEY).' } : {}),
+      ...(p.id === 'grok' ? { note: 'This API uses API billing; no public Grok subscription login was found for Comal.' } : {}) };
   }
   async _request(url, { signal, values, json = false, headers = {} } = {}) {
     const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(30000)]) : AbortSignal.timeout(30000);
@@ -110,7 +110,7 @@ export class AuthManager {
     try { response = await this.fetch(url, { method: 'POST', redirect: 'error', signal: requestSignal,
       headers: { 'content-type': json ? 'application/json' : 'application/x-www-form-urlencoded', 'User-Agent': 'Comal/0.1.0', ...headers },
       body: json ? JSON.stringify(values) : new URLSearchParams(values).toString() }); }
-    catch (error) { if (signal?.aborted) throw signal.reason; throw failure('No se pudo conectar con el servidor de autenticación.'); }
+    catch (error) { if (signal?.aborted) throw signal.reason; throw failure('Could not connect to the authentication server.'); }
     let data;
     try {
       const reader = response.body?.getReader();
@@ -121,18 +121,18 @@ export class AuthManager {
         data = JSON.parse(body + decoder.decode());
       } finally { await reader.cancel(); }
     }
-    catch { throw failure(`Respuesta de autenticación inválida (HTTP ${response.status}).`); }
+    catch { throw failure(`Invalid authentication response (HTTP ${response.status}).`); }
     return { response, data };
   }
   async login(name, { signal, onEvent = () => {}, apiKeyEnv, secret: suppliedSecret } = {}) {
     const p = definition(name);
-    if (apiKeyEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(apiKeyEnv)) throw failure('Variable de credencial inválida.');
+    if (apiKeyEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(apiKeyEnv)) throw failure('Invalid credential environment variable.');
     if (p.method !== 'device_code' || apiKeyEnv || suppliedSecret) {
-      if (p.id === 'codex') throw failure('Codex subscription requiere device login; usa otro perfil para claves API.');
+      if (p.id === 'codex') throw failure('Codex subscription requires device login; use another profile for API keys.');
       const variable = apiKeyEnv || p.apiKeyEnv, value = suppliedSecret || this.env[variable];
       if (!value) return { ...await this.status(p.id), status: 'requires_secret', apiKeyEnv: variable,
-        instructions: `Configura ${variable} con ${p.subscription ? 'la clave de tu suscripción' : 'tu clave API (facturación API)'} y ejecuta login de nuevo.` };
-      if (!secret(value)) throw failure('Credencial inválida.');
+        instructions: `Set ${variable} to ${p.subscription ? 'your subscription key' : 'your API key (API billing)'} and run login again.` };
+      if (!secret(value)) throw failure('Invalid credential.');
       await this._locked(p.id, signal, () => this._write({ version: 1, provider: p.id, method: p.subscription ? 'subscription_key' : 'api_key', accessToken: value, updatedAt: this.now() }));
       // A key has been stored, not checked by making a billable inference request.
       return this.status(p.id);
@@ -141,13 +141,13 @@ export class AuthManager {
     const codex = p.id === 'codex', host = codex ? 'https://auth.openai.com' : 'https://auth.kimi.com';
     const initial = await this._request(host + (codex ? '/api/accounts/deviceauth/usercode' : '/api/oauth/device_authorization'),
       { signal, json: codex, values: { client_id: codex ? C : K } });
-    if (!initial.response.ok) throw failure(`No se pudo iniciar login ${p.id} (HTTP ${initial.response.status}).`);
+    if (!initial.response.ok) throw failure(`Could not start ${p.id} login (HTTP ${initial.response.status}).`);
     const d = initial.data, code = d.user_code || d.usercode;
-    if (!secret(code) || !secret(codex ? d.device_auth_id : d.device_code)) throw failure('Código de dispositivo inválido.');
+    if (!secret(code) || !secret(codex ? d.device_auth_id : d.device_code)) throw failure('Invalid device code.');
     const verification = codex ? host + '/codex/device' : d.verification_uri_complete || d.verification_uri;
     let verificationURL;
-    try { verificationURL = new URL(verification); } catch { throw failure('URL de verificación inválida.'); }
-    if (verificationURL.protocol !== 'https:' || verificationURL.username || verificationURL.password || !codex && !/^(?:[a-z0-9-]+\.)*kimi\.(?:com|ai)$/.test(verificationURL.hostname)) throw failure('Host de verificación inválido.');
+    try { verificationURL = new URL(verification); } catch { throw failure('Invalid verification URL.'); }
+    if (verificationURL.protocol !== 'https:' || verificationURL.username || verificationURL.password || !codex && !/^(?:[a-z0-9-]+\.)*kimi\.(?:com|ai)$/.test(verificationURL.hostname)) throw failure('Invalid verification host.');
     const expiresIn = Math.min(900, Math.max(1, Number(d.expires_in) || 900)), end = this.now() + expiresIn * 1000;
     let interval = Math.min(60, Math.max(1, Number(d.interval) || 5)) * 1000;
     await onEvent({ type: 'device_code', provider: p.id, verification_uri: verificationURL.href, user_code: code, expires_in: expiresIn });
@@ -159,26 +159,26 @@ export class AuthManager {
       if (polled.response.ok) {
         if (codex) {
           const q = polled.data;
-          if (!secret(q.authorization_code) || !secret(q.code_verifier)) throw failure('Autorización Codex incompleta.');
+          if (!secret(q.authorization_code) || !secret(q.code_verifier)) throw failure('Incomplete Codex authorization.');
           const exchanged = await this._request(host + '/oauth/token', { signal, values: { client_id: C, grant_type: 'authorization_code', code: q.authorization_code, code_verifier: q.code_verifier, redirect_uri: host + '/deviceauth/callback' } });
-          if (!exchanged.response.ok) throw failure(`Exchange Codex rechazado (HTTP ${exchanged.response.status}).`);
+          if (!exchanged.response.ok) throw failure(`Codex token exchange rejected (HTTP ${exchanged.response.status}).`);
           payload = exchanged.data;
         } else payload = polled.data;
         break;
       }
       const pending = codex ? [403, 404].includes(polled.response.status) : ['authorization_pending', 'slow_down'].includes(polled.data.error);
-      if (!pending) throw failure(`Login ${p.id} rechazado o expirado (HTTP ${polled.response.status}).`);
+      if (!pending) throw failure(`${p.id} login rejected or expired (HTTP ${polled.response.status}).`);
       if (polled.data.error === 'slow_down') interval = Math.min(60000, interval + 5000);
       await this.sleep(Math.min(interval, Math.max(0, end - this.now())), signal);
     }
-    if (!payload) throw failure('El código de dispositivo expiró.', 'PROVIDER_AUTH_EXPIRED');
+    if (!payload) throw failure('The device code expired.', 'PROVIDER_AUTH_EXPIRED');
     await this._locked(p.id, signal, () => this._write(tokenRecord(p.id, payload, this.now())));
     await onEvent({ type: 'authenticated', provider: p.id });
     return this.status(p.id);
   }
   async logout(name) {
     const p = definition(name);
-    await this._locked(p.id, undefined, () => unlink(path.join(this.directory, `${p.id}.json`)).catch(error => { if (error.code !== 'ENOENT') throw failure('No se pudieron eliminar credenciales privadas.'); }));
+    await this._locked(p.id, undefined, () => unlink(path.join(this.directory, `${p.id}.json`)).catch(error => { if (error.code !== 'ENOENT') throw failure('Could not delete private credentials.'); }));
     return { provider: p.id, status: 'logged_out', remoteRevoked: false };
   }
   async resolve(name, { signal, forceRefresh = false } = {}) {
@@ -188,14 +188,14 @@ export class AuthManager {
   async _resolve(p, { signal, forceRefresh }) {
     if (this.pendingRefresh.has(p.id)) await this.pendingRefresh.get(p.id);
     let record = await this._read(p.id);
-    if (!record) throw failure(`Primero ejecuta /login ${p.id}.`, 'PROVIDER_AUTH_REQUIRED');
+    if (!record) throw failure(`Run /login ${p.id} first.`, 'PROVIDER_AUTH_REQUIRED');
     if (record.method === 'device_code' && (forceRefresh || record.expiresAt <= this.now() + 60000)) {
-      if (!record.refreshToken) throw failure('La sesión de login expiró; inicia sesión de nuevo.', 'PROVIDER_AUTH_EXPIRED');
+      if (!record.refreshToken) throw failure('The login session expired; log in again.', 'PROVIDER_AUTH_EXPIRED');
       const refresh = (async () => {
         const codex = p.id === 'codex';
         const { response, data } = await this._request(codex ? 'https://auth.openai.com/oauth/token' : 'https://auth.kimi.com/api/oauth/token', { signal,
           values: { client_id: codex ? C : K, grant_type: 'refresh_token', refresh_token: record.refreshToken } });
-        if (!response.ok) throw failure(`No se pudo renovar login (HTTP ${response.status}); inicia sesión de nuevo.`, 'PROVIDER_AUTH_EXPIRED');
+        if (!response.ok) throw failure(`Could not refresh login (HTTP ${response.status}); log in again.`, 'PROVIDER_AUTH_EXPIRED');
         record = tokenRecord(p.id, data, this.now(), record); await this._write(record);
       })();
       this.pendingRefresh.set(p.id, refresh);

package/src/provider-profiles.mjs

@@ -13,40 +13,40 @@ const KEYS = new Set(['name', 'provider', 'protocol', 'model', 'baseURL', 'apiKe
 const error = message => Object.assign(new Error(message), { code: 'PROVIDER_PROFILE_INVALID' });
 
 export function normalizeCapabilities(value = {}, { protocol = 'openai' } = {}) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) throw error('capabilities debe ser un objeto de booleanos.');
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw error('capabilities must be an object of booleans.');
   const capabilities = { text: true, tools: true, vision: false, video: false, web_search: false };
   for (const [key, enabled] of Object.entries(value)) {
-    if (!PROVIDER_CAPABILITIES.includes(key) || typeof enabled !== 'boolean') throw error(`Capacidad inválida: ${key}.`);
+    if (!PROVIDER_CAPABILITIES.includes(key) || typeof enabled !== 'boolean') throw error(`Invalid capability: ${key}.`);
     capabilities[key] = enabled;
   }
-  if (!capabilities.text) throw error('Los perfiles de sesión requieren text:true.');
-  if (protocol !== 'gemini' && (capabilities.video || capabilities.web_search)) throw error(`${protocol} no tiene adaptador nativo video/web_search en Comal; usa gemini o herramientas MCP.`);
+  if (!capabilities.text) throw error('Session profiles require text:true.');
+  if (protocol !== 'gemini' && (capabilities.video || capabilities.web_search)) throw error(`${protocol} has no native video/web_search adapter in Comal; use gemini or MCP tools.`);
   return Object.freeze(capabilities);
 }
 
 export function normalizeProviderProfile(input, name = input?.name) {
-  if (!input || typeof input !== 'object' || Array.isArray(input)) throw error('Perfil inválido.');
-  for (const key of Object.keys(input)) if (!KEYS.has(key)) throw error(`Campo no permitido en perfil: ${key}. Guarda sólo apiKeyEnv, nunca claves API.`);
-  if (typeof name !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name)) throw error('Nombre de perfil inválido.');
-  if (input.name && input.name !== name) throw error('Nombre de perfil contradictorio.');
-  if (input.authProvider !== undefined && !['codex', 'kimi', 'minimax', 'grok'].includes(input.authProvider)) throw error('authProvider inválido.');
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw error('Invalid profile.');
+  for (const key of Object.keys(input)) if (!KEYS.has(key)) throw error(`Field not allowed in profile: ${key}. Store only apiKeyEnv, never API keys.`);
+  if (typeof name !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name)) throw error('Invalid profile name.');
+  if (input.name && input.name !== name) throw error('Conflicting profile name.');
+  if (input.authProvider !== undefined && !['codex', 'kimi', 'minimax', 'grok'].includes(input.authProvider)) throw error('Invalid authProvider.');
   if (input.effort !== undefined) normalizeEffort(input.effort);
   const toolSchema=input.toolSchema===undefined?undefined:normalizeToolSchemaCapabilities(input.toolSchema);
   const access=input.authProvider?authProviderDefaults(input.authProvider):null;
   const configuredCapabilities = input.capabilitiesConfigured || input.capabilities || {};
   normalizeCapabilities(configuredCapabilities, { protocol: input.protocol || input.provider || access?.protocol || 'openai' });
   const protocol = input.protocol || input.provider || access?.protocol || 'openai';
-  if(access && protocol!==access.protocol)throw error('El protocolo del perfil no coincide con su login.');
-  if (!PROTOCOLS.includes(protocol) || (input.protocol && input.provider && input.protocol !== input.provider)) throw error('Protocolo de proveedor inválido.');
-  if (input.model !== undefined && (typeof input.model !== 'string' || !input.model.trim() || input.model.length > 256)) throw error('Modelo de perfil inválido.');
-  if (protocol !== 'openai' && !input.model && !access?.model) throw error(`${protocol} requiere model en su perfil.`);
+  if(access && protocol!==access.protocol)throw error('The profile protocol does not match its login.');
+  if (!PROTOCOLS.includes(protocol) || (input.protocol && input.provider && input.protocol !== input.provider)) throw error('Invalid provider protocol.');
+  if (input.model !== undefined && (typeof input.model !== 'string' || !input.model.trim() || input.model.length > 256)) throw error('Invalid profile model.');
+  if (protocol !== 'openai' && !input.model && !access?.model) throw error(`${protocol} requires model in its profile.`);
   if (input.baseURL !== undefined) {
-    if (typeof input.baseURL !== 'string') throw error('baseURL inválida.');
+    if (typeof input.baseURL !== 'string') throw error('Invalid baseURL.');
     const url = new URL(input.baseURL);
-    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw error('baseURL requiere HTTP(S), sin credenciales ni query.');
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw error('baseURL requires HTTP(S), without credentials or a query.');
   }
-  if (input.apiKeyEnv !== undefined && (typeof input.apiKeyEnv !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(input.apiKeyEnv))) throw error('apiKeyEnv debe nombrar una variable de entorno.');
-  if (input.description !== undefined && (typeof input.description !== 'string' || input.description.length > 1024)) throw error('description inválida.');
+  if (input.apiKeyEnv !== undefined && (typeof input.apiKeyEnv !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(input.apiKeyEnv))) throw error('apiKeyEnv must name an environment variable.');
+  if (input.description !== undefined && (typeof input.description !== 'string' || input.description.length > 1024)) throw error('Invalid description.');
   return Object.freeze({ name, provider: protocol, protocol, ...((input.model || access?.model) ? { model: input.model || access.model } : {}),
     baseURL: input.baseURL || access?.baseURL || ({ openai: DEFAULT_LOCAL_URL, anthropic: 'https://api.anthropic.com', gemini: 'https://generativelanguage.googleapis.com/v1beta' })[protocol],
     apiKeyEnv: input.apiKeyEnv || ({ openai: 'OPENAI_API_KEY', anthropic: 'ANTHROPIC_API_KEY', gemini: 'GEMINI_API_KEY' })[protocol],
@@ -64,21 +64,21 @@ export async function loadProviderProfiles({ cwd = process.cwd(), configPath, en
     if (failure.code === 'ENOENT' && !configPath && !env.COMAL_PROVIDERS_CONFIG) return { profiles: [], defaultProfile: null, configPath: file };
     throw failure;
   }
-  if (Buffer.byteLength(text) > 65536) throw error('La configuración de proveedores excede 64 KiB.');
+  if (Buffer.byteLength(text) > 65536) throw error('Provider configuration exceeds 64 KiB.');
   const config = JSON.parse(text);
-  if (!config || typeof config !== 'object' || Array.isArray(config) || Object.keys(config).some(key => !['profiles', 'defaultProfile', 'default', 'version'].includes(key))) throw error('Formato de proveedores inválido.');
-  if (config.version !== undefined && config.version !== 1) throw error('Versión de proveedores no soportada.');
+  if (!config || typeof config !== 'object' || Array.isArray(config) || Object.keys(config).some(key => !['profiles', 'defaultProfile', 'default', 'version'].includes(key))) throw error('Invalid provider configuration format.');
+  if (config.version !== undefined && config.version !== 1) throw error('Unsupported provider configuration version.');
   const raw = config.profiles;
-  if (!raw || typeof raw !== 'object') throw error('Configura profiles como objeto o lista.');
+  if (!raw || typeof raw !== 'object') throw error('Configure profiles as an object or list.');
   const entries = Array.isArray(raw) ? raw.map(input => [input?.name, input]) : Object.entries(raw);
-  if (entries.length > 32) throw error('Máximo 32 perfiles de proveedor.');
+  if (entries.length > 32) throw error('At most 32 provider profiles are allowed.');
   const names = new Set(), profiles = entries.map(([name, input]) => {
     const profile = normalizeProviderProfile(input, name);
-    if (names.has(profile.name)) throw error('Nombre de perfil duplicado.');
+    if (names.has(profile.name)) throw error('Duplicate profile name.');
     names.add(profile.name); return profile;
   });
   const defaultProfile = config.defaultProfile ?? config.default ?? null;
-  if (defaultProfile !== null && (typeof defaultProfile !== 'string' || !names.has(defaultProfile))) throw error('El perfil predeterminado no existe.');
+  if (defaultProfile !== null && (typeof defaultProfile !== 'string' || !names.has(defaultProfile))) throw error('The default profile does not exist.');
   return { profiles, defaultProfile, configPath: file };
 }
 
@@ -86,7 +86,7 @@ export function selectProfile(registry, name) {
   const requested = name || registry.defaultProfile;
   if (!requested) return null;
   const profile = registry.profiles.find(item => item.name === requested);
-  if (!profile) throw Object.assign(new Error(`No existe el perfil ${requested}.`), { code: 'PROVIDER_PROFILE_NOT_FOUND' });
+  if (!profile) throw Object.assign(new Error(`Profile ${requested} does not exist.`), { code: 'PROVIDER_PROFILE_NOT_FOUND' });
   return profile;
 }
 
@@ -97,11 +97,11 @@ export function createProfileProvider(profile, { env = process.env, ...overrides
   else if (overrides.vision === 'off') capabilities.vision = false;
   const options = { ...overrides, apiKey: overrides.apiKey ?? env[profile.apiKeyEnv], model: overrides.model || profile.model, baseURL: overrides.baseURL || profile.baseURL,
     capabilities, capabilitiesConfigured: profile.capabilitiesConfigured, effort: overrides.effort ?? profile.effort ?? 'auto', vision: overrides.vision || (Object.hasOwn(profile.capabilitiesConfigured, 'vision') ? capabilities.vision ? 'on' : 'off' : 'auto') };
-  if (profile.protocol !== 'openai' && !options.apiKey) throw new Error(`Define la variable apiKeyEnv ${profile.apiKeyEnv} del perfil.`);
+  if (profile.protocol !== 'openai' && !options.apiKey) throw new Error(`Set the profile apiKeyEnv variable ${profile.apiKeyEnv}.`);
   const provider = profile.protocol === 'gemini' ? new GeminiProvider(options) : profile.protocol === 'anthropic' ? new AnthropicProvider(options) : new OpenAIProvider(options);
   const complete = provider.complete.bind(provider);
   provider.complete = request => {
-    if (!capabilities.tools && request.tools?.length) throw Object.assign(new Error('El perfil no habilita tools.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
+    if (!capabilities.tools && request.tools?.length) throw Object.assign(new Error('The profile does not enable tools.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
     return complete(request);
   };
   provider.profileName = profile.name;

package/src/provider.mjs

@@ -25,7 +25,7 @@ export async function* sseEvents(body) {
   };
   for await (const chunk of body) {
     total += chunk.byteLength;
-    if (total > 8 * 1024 * 1024) throw new Error('La respuesta del modelo excedió 8 MiB.');
+    if (total > 8 * 1024 * 1024) throw new Error('The model response exceeded 8 MiB.');
     buffer += decoder.decode(chunk, { stream: true });
     // Keep a trailing CR until the next chunk so split CRLF is normalized correctly.
     buffer = buffer.replace(/\r\n/g, '\n');
@@ -40,27 +40,27 @@ export async function* sseEvents(body) {
 }
 
 export async function analyzeImages(provider, { prompt, media, signal, maxTokens } = {}) {
-  if (typeof prompt !== 'string' || !prompt.trim() || prompt.length > 12000 || !Array.isArray(media) || !media.length || media.length > 4) throw new Error('Solicitud multimedia inválida.');
+  if (typeof prompt !== 'string' || !prompt.trim() || prompt.length > 12000 || !Array.isArray(media) || !media.length || media.length > 4) throw new Error('Invalid media request.');
   const images = media.map(source => {
     const mimeType = source.mimeType || source.media_type;
-    if (typeof mimeType !== 'string' || !/^image\/(?:png|jpeg|webp|gif)$/.test(mimeType)) throw Object.assign(new Error('Este adaptador admite imágenes; video requiere un perfil Gemini habilitado.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
-    if (source.uri || source.file_uri || typeof source.data !== 'string' || !source.data || source.data.length % 4 || !/^[a-zA-Z0-9+/]*={0,2}$/.test(source.data)) throw new Error('La imagen requiere datos base64 válidos; no se admiten URI remotas en este adaptador.');
-    if (source.data.length > 4 * 1024 * 1024) throw new Error('La imagen excede el límite de 4 MiB codificados.');
+    if (typeof mimeType !== 'string' || !/^image\/(?:png|jpeg|webp|gif)$/.test(mimeType)) throw Object.assign(new Error('This adapter supports images; video requires an enabled Gemini profile.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
+    if (source.uri || source.file_uri || typeof source.data !== 'string' || !source.data || source.data.length % 4 || !/^[a-zA-Z0-9+/]*={0,2}$/.test(source.data)) throw new Error('The image requires valid base64 data; this adapter does not accept remote URIs.');
+    if (source.data.length > 4 * 1024 * 1024) throw new Error('The image exceeds the 4 MiB encoded limit.');
     return { type: 'image', source: { type: 'base64', media_type: mimeType, data: source.data } };
   });
-  if (!(await provider.getVisionCapability({ signal })).supported) throw Object.assign(new Error('El proveedor no habilita visión.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
+  if (!(await provider.getVisionCapability({ signal })).supported) throw Object.assign(new Error('The provider does not enable vision.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
   const result = await provider.complete({ messages: [{ role: 'user', content: [{ type: 'text', text: prompt }, ...images] }], tools: [], signal, maxTokens });
   return { answer: result.content.filter(block => block.type === 'text').map(block => block.text).join(''), usage: result.usage, model: provider.model };
 }
 
 function validateMessage(message) {
-  if (!message || !Array.isArray(message.content) || !message.stop_reason) throw new Error('Respuesta incompleta del modelo.');
-  if(message.stop_reason==='max_tokens')throw Object.assign(new Error('Respuesta Anthropic truncada; no se ejecutaron herramientas.'),{code:'OUTPUT_LENGTH',usage:message.usage,usage_accounting:normalizeUsage('anthropic',message.usage)});
+  if (!message || !Array.isArray(message.content) || !message.stop_reason) throw new Error('Incomplete model response.');
+  if(message.stop_reason==='max_tokens')throw Object.assign(new Error('Anthropic response truncated; no tools were executed.'),{code:'OUTPUT_LENGTH',usage:message.usage,usage_accounting:normalizeUsage('anthropic',message.usage)});
   const ids = new Set();
   for (const block of message.content) {
-    if (!block || typeof block.type !== 'string') throw new Error('Bloque de contenido inválido.');
+    if (!block || typeof block.type !== 'string') throw new Error('Invalid content block.');
     if (block.type === 'tool_use') {
-      if (typeof block.id !== 'string' || !block.id || ids.has(block.id) || typeof block.name !== 'string' || !block.input || typeof block.input !== 'object' || Array.isArray(block.input)) throw new Error('Llamada de herramienta inválida.');
+      if (typeof block.id !== 'string' || !block.id || ids.has(block.id) || typeof block.name !== 'string' || !block.input || typeof block.input !== 'object' || Array.isArray(block.input)) throw new Error('Invalid tool call.');
       ids.add(block.id);
     }
   }
@@ -69,10 +69,10 @@ function validateMessage(message) {
 
 export class AnthropicProvider {
   constructor({ apiKey = process.env.ANTHROPIC_API_KEY, baseURL = process.env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com', model = process.env.COMAL_MODEL || process.env.HARNESS_MODEL || 'claude-sonnet-4-6', maxTokens = 4096, effort = 'auto', capabilitiesConfigured = {}, vision = 'auto', imageTokens = 4096, timeoutMs = 90000, fetchImpl = fetch } = {}) {
-    if (!apiKey) throw new Error('Define ANTHROPIC_API_KEY o usa --demo para probar sin credenciales.');
+    if (!apiKey) throw new Error('Set ANTHROPIC_API_KEY or use --demo to try without credentials.');
     const url = new URL(baseURL.replace(/\/$/, '') + '/v1/messages');
-    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) throw new Error('El proveedor requiere HTTPS; HTTP sólo se permite en localhost.');
-    if (url.username || url.password || url.search || url.hash) throw new Error('URL del proveedor inválida.');
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) throw new Error('The provider requires HTTPS; HTTP is allowed only on localhost.');
+    if (url.username || url.password || url.search || url.hash) throw new Error('Invalid provider URL.');
     this.protocol = 'anthropic'; this.effort = normalizeEffort(effort); this.capabilitiesConfigured = { ...capabilitiesConfigured }; this.configuredCapabilities = this.capabilitiesConfigured;
     this.apiKey = apiKey; this.url = url; this.model = model; this.maxTokens = maxTokens; this.timeoutMs = timeoutMs; this.fetch = fetchImpl;
     Object.assign(this, visionSettings({ vision, imageTokens }, {}));
@@ -88,10 +88,10 @@ export class AnthropicProvider {
       // but omit another provider's private reasoning from the Anthropic wire.
       if (original.type === 'openai_reasoning' || original.type === 'thinking' && original.gemini_part) return [];
       const { gemini_part: ignoredGeminiPart, ...block } = original;
-      if (block.type === 'video' || block.type === 'media') throw Object.assign(new Error('El adaptador Anthropic no admite video; usa un perfil con transporte multimedia.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
-      if (block.type === 'image_reference') throw new Error('Referencia visual sin resolver; no se envió al proveedor.');
+      if (block.type === 'video' || block.type === 'media') throw Object.assign(new Error('The Anthropic adapter does not support video; use a profile with media transport.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
+      if (block.type === 'image_reference') throw new Error('Unresolved image reference; it was not sent to the provider.');
       if (block.type !== 'image') return block;
-      if (!this.getVisionCapability().supported) throw new Error('Visión no habilitada en el proveedor; no se enviaron píxeles.');
+      if (!this.getVisionCapability().supported) throw new Error('Vision is not enabled for this provider; no pixels were sent.');
       return { type: 'image', source: block.source };
     }) }).filter(message => !Array.isArray(message.content) || message.content.length);
     const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(this.timeoutMs)]) : AbortSignal.timeout(this.timeoutMs);
@@ -99,7 +99,7 @@ export class AnthropicProvider {
     const body = JSON.stringify({ ...effortWire, model: this.model, max_tokens: maxTokens, system, messages: mergeMessages(messages), ...(tools.length ? { tools } : {}), stream: true });
     const account=result=>({...result,usage_accounting:bindUsageAccounting(normalizeUsage('anthropic',result.usage),accountingRequest,identity,body),schema_diagnostics:schemaFrame.diagnostics,schema_manifest:schemaFrame.manifest});
     const finish=result=>{try{return account(validateMessage(result));}catch(error){if(error.usage_accounting)error.usage_accounting=bindUsageAccounting(error.usage_accounting,accountingRequest,identity,body);throw error;}};
-    if (Buffer.byteLength(body) > 8 * 1024 * 1024) throw new Error('El contexto excede 8 MiB; inicia una sesión nueva con /clear.');
+    if (Buffer.byteLength(body) > 8 * 1024 * 1024) throw new Error('The context exceeds 8 MiB; start a new session with /clear.');
     let response;
     for (let attempt = 0; attempt < 3; attempt++) {
       response = await this.fetch(this.url, { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': this.apiKey, 'anthropic-version': '2023-06-01' }, body, signal: requestSignal });
@@ -110,7 +110,7 @@ export class AnthropicProvider {
     }
     if (!response.ok) {
       await response.body?.cancel();
-      throw new Error(`API HTTP ${response.status}. Revisa la clave, el modelo, los límites o el endpoint.`);
+      throw new Error(`API HTTP ${response.status}. Check the key, model, limits or endpoint.`);
     }
     if (!(response.headers.get('content-type') || '').includes('text/event-stream')) {
       const message = finish(await response.json());
@@ -120,29 +120,29 @@ export class AnthropicProvider {
     let message, stopped = false;
     const blocks = new Map(), partial = new Map(), closed = new Set();
     for await (const event of sseEvents(response.body)) {
-      if (event.type === 'error') throw new Error(`Error de streaming: ${event.error?.type || 'unknown'}`);
-      if (event.type === 'message_start') { if (message) throw new Error('message_start duplicado.'); message = structuredClone(event.message); }
+      if (event.type === 'error') throw new Error(`Streaming error: ${event.error?.type || 'unknown'}`);
+      if (event.type === 'message_start') { if (message) throw new Error('Duplicate message_start.'); message = structuredClone(event.message); }
       else if (event.type === 'content_block_start') {
-        if (blocks.has(event.index)) throw new Error('Bloque duplicado.');
+        if (blocks.has(event.index)) throw new Error('Duplicate block.');
         blocks.set(event.index, structuredClone(event.content_block));
       } else if (event.type === 'content_block_delta') {
         const block = blocks.get(event.index);
-        if (!block || closed.has(event.index)) throw new Error('Delta fuera de su bloque.');
+        if (!block || closed.has(event.index)) throw new Error('Delta outside its block.');
         const d = event.delta;
         if (d.type === 'text_delta') { block.text = (block.text || '') + d.text; onText(d.text); }
         else if (d.type === 'input_json_delta') partial.set(event.index, (partial.get(event.index) || '') + d.partial_json);
         else if (d.type === 'thinking_delta') block.thinking = (block.thinking || '') + d.thinking;
         else if (d.type === 'signature_delta') block.signature = (block.signature || '') + d.signature;
       } else if (event.type === 'content_block_stop') {
-        if (!blocks.has(event.index)) throw new Error('Cierre de bloque desconocido.');
+        if (!blocks.has(event.index)) throw new Error('Unknown block closure.');
         if (partial.has(event.index)) blocks.get(event.index).input = JSON.parse(partial.get(event.index));
         closed.add(event.index);
       } else if (event.type === 'message_delta') {
-        if (!message) throw new Error('Delta sin mensaje.');
+        if (!message) throw new Error('Delta without a message.');
         Object.assign(message, event.delta); message.usage = { ...message.usage, ...event.usage };
       } else if (event.type === 'message_stop') stopped = true;
     }
-    if (!stopped || !message || closed.size !== blocks.size) throw new Error('Streaming interrumpido; ninguna herramienta de esta respuesta fue ejecutada.');
+    if (!stopped || !message || closed.size !== blocks.size) throw new Error('Streaming interrupted; no tools from this response were executed.');
     message.content = [...blocks.entries()].sort((a, b) => a[0] - b[0]).map(([, block]) => block);
     return finish(message);
   }
@@ -151,23 +151,23 @@ export class AnthropicProvider {
 export class DemoProvider {
   constructor(sessionId) { this.model = 'demo-scripted'; this.file = `comal-demo-${sessionId.slice(0, 8)}.md`; }
   async complete({ messages, onText = () => {}, signal }) {
-    if (signal?.aborted) throw new Error('Demostración cancelada.');
+    if (signal?.aborted) throw new Error('Demo cancelled.');
     const projection = messages.find(m => typeof m.content === 'string' && m.content.startsWith('Estado de trabajo derivado determinísticamente por Comal'));
     const state = projection ? JSON.parse(projection.content.slice(projection.content.indexOf('\n') + 1)) : null;
     const progress = state?.tool_progress.recent.filter(item => /^demo_\d+$/.test(item.id));
     const calls = progress?.length ? Math.max(...progress.map(item => Number(item.id.slice(5)))) + 1 : messages.flatMap(m => Array.isArray(m.content) ? m.content : []).filter(b => b.type === 'tool_result').length;
     const steps = [
-      ['Write', { file_path: this.file, content: '# Comal\n\nCiclo de herramientas pendiente.\n' }],
+      ['Write', { file_path: this.file, content: '# Comal\n\nTool cycle pending.\n' }],
       ['Read', { file_path: this.file }],
-      ['Edit', { file_path: this.file, old_string: 'pendiente', new_string: 'verificado' }],
-      ['Grep', { pattern: 'verificado', glob: this.file }]
+      ['Edit', { file_path: this.file, old_string: 'pending', new_string: 'verified' }],
+      ['Grep', { pattern: 'verified', glob: this.file }]
     ];
     if (calls < steps.length) {
       const [name, input] = steps[calls];
       return { role: 'assistant', content: [{ type: 'tool_use', id: `demo_${calls}`, name, input }], stop_reason: 'tool_use', usage: { input_tokens: 0, output_tokens: 0 } };
     }
     const failed = progress?.some(item => item.is_error) || messages.flatMap(m => Array.isArray(m.content) ? m.content : []).some(b => b.type === 'tool_result' && b.is_error);
-    const text = failed ? 'La demo terminó con herramientas denegadas o errores. Consulta los eventos; no todos los cambios se completaron.' : `Demo sin modelo real: creé, leí, edité y busqué texto en ${this.file}. El historial puede reanudarse.`;
+    const text = failed ? 'The demo finished with denied tools or errors. Check the events; not all changes completed.' : `Demo without a real model: created, read, edited and searched text in ${this.file}. The history can be resumed.`;
     onText(text);
     return { role: 'assistant', content: [{ type: 'text', text }], stop_reason: 'end_turn', usage: { input_tokens: 0, output_tokens: 0 } };
   }

package/src/remote-commands.mjs

@@ -0,0 +1,11 @@
+import { readFileSync } from 'node:fs';
+
+export const remoteCommandContract = JSON.parse(readFileSync(new URL('../backend/contracts/remote-commands-v1.json', import.meta.url), 'utf8'));
+export function isRemoteCommand(text) {
+  const match = /^\/([a-z-]+)(?:[ \t]+([^\r\n]*))?$/.exec(text.trim());
+  if (!match) return false;
+  const command = remoteCommandContract.commands.find(item => item.name === match[1]);
+  const arg = (match[2] || '').trim();
+  return Boolean(command && (!arg || new RegExp('^(?:' + command.argument_pattern + ')$').test(arg)));
+}
+export const remoteCommandHelp = () => remoteCommandContract.commands.map(item => '/' + item.name + (item.arguments ? ' ' + item.arguments : '') + ' — ' + item.description).join('\n') + '\n\nPermission changes, credentials and session switching remain in the local terminal.';