@milpa/comal 0.1.0 → 0.1.2

package/src/image-attachments.mjs

@@ -0,0 +1,263 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { createHash, randomUUID } from 'node:crypto';
+import { auditJournal } from './audit.mjs';
+
+export const HUMAN_IMAGE_LIMIT = 2 * 1024 * 1024;
+export const HUMAN_IMAGE_COUNT = 2;
+const staged = new WeakMap();
+const fail = (message, code = 'IMAGE_ATTACHMENT_INVALID') => Object.assign(new Error(message), { code });
+const isHuman = actor => actor?.kind === 'human' && actor.id === 'local-user';
+const imageExtension = /\.(?:png|jpe?g|webp|gif|bmp|tiff?|svg|avif|heic)$/iu;
+
+// The terminal supplies path text, not native OS drag events. Parse a small literal
+// token grammar only: no shell, interpolation, globbing, command or environment eval.
+export function findImageCandidates(text, { cwd = process.cwd(), home = os.homedir() } = {}) {
+  if (typeof text !== 'string') return [];
+  const result = [];
+  for (let i = 0; i < text.length;) {
+    if (/\s/u.test(text[i])) { i++; continue; }
+    const start = i, windowsLiteral = /^["']?[A-Za-z]:[\\/]/u.test(text.slice(i)); let token = '', quote = null, invalid = false;
+    while (i < text.length && (quote || !/\s/u.test(text[i]))) {
+      const char = text[i++];
+      if (char === "'" && quote !== '"') { quote = quote === "'" ? null : "'"; continue; }
+      if (char === '"' && quote !== "'") { quote = quote === '"' ? null : '"'; continue; }
+      if (char === '\\' && windowsLiteral) { token += char; continue; }
+      if (char === '\\' && quote !== "'") {
+        if (i === text.length) { invalid = true; break; }
+        // Standard terminal-escaped spaces and quote characters. Dollar signs
+        // remain literal and can never cause command substitution.
+        token += text[i++]; continue;
+      }
+      token += char;
+    }
+    if (quote || invalid || !token || token.includes('\0')) continue;
+    if (/^[A-Za-z]:[\\/]/u.test(token) && process.platform !== 'win32') continue;
+    let candidatePath = token;
+    try {
+      if (/^file:/i.test(candidatePath)) {
+        const url = new URL(candidatePath);
+        if (url.protocol !== 'file:' || url.host && url.host !== 'localhost' || url.search || url.hash) continue;
+        candidatePath = fileURLToPath(url);
+      } else if (candidatePath.startsWith('~/')) candidatePath = path.join(home, candidatePath.slice(2));
+      if (!imageExtension.test(candidatePath)) continue;
+      result.push({ start, end: i, raw: text.slice(start, i), candidate: token, path: path.resolve(cwd, candidatePath) });
+    } catch { /* Invalid URIs are never treated as filesystem authorization. */ }
+  }
+  return result;
+}
+
+export const HUMAN_IMAGE_MAX_DIMENSION = 16384;
+export const HUMAN_IMAGE_MAX_PIXELS = 40_000_000;
+const dimensionsAllowed = (width, height) => width > 0 && height > 0 && width <= HUMAN_IMAGE_MAX_DIMENSION && height <= HUMAN_IMAGE_MAX_DIMENSION && width * height <= HUMAN_IMAGE_MAX_PIXELS;
+const crcTable = Array.from({ length: 256 }, (_, index) => {
+  let value = index; for (let bit = 0; bit < 8; bit++) value = value & 1 ? (value >>> 1) ^ 0xedb88320 : value >>> 1; return value >>> 0;
+});
+const crc32 = bytes => { let value = 0xffffffff; for (const byte of bytes) value = (value >>> 8) ^ crcTable[(value ^ byte) & 255]; return (value ^ 0xffffffff) >>> 0; };
+
+function pngStructure(bytes) {
+  let offset = 8, header = false, data = false, endedData = false, palette = false, color, depth, dataLength = 0, zlibHeader = [];
+  while (offset + 12 <= bytes.length) {
+    const length = bytes.readUInt32BE(offset), end = offset + 12 + length;
+    if (end > bytes.length) return false;
+    const kind = bytes.toString('latin1', offset + 4, offset + 8), value = bytes.subarray(offset + 8, end - 4);
+    if (!/^[A-Za-z]{4}$/u.test(kind) || crc32(bytes.subarray(offset + 4, end - 4)) !== bytes.readUInt32BE(end - 4)) return false;
+    if (!header && kind !== 'IHDR') return false;
+    if (kind === 'IHDR') {
+      if (header || length !== 13 || !dimensionsAllowed(value.readUInt32BE(0), value.readUInt32BE(4))) return false;
+      depth = value[8]; color = value[9];
+      const allowedDepths = { 0: [1,2,4,8,16], 2: [8,16], 3: [1,2,4,8], 4: [8,16], 6: [8,16] };
+      if (!allowedDepths[color]?.includes(depth) || value[10] || value[11] || value[12] > 1) return false;
+      header = true;
+    } else if (kind === 'PLTE') {
+      if (data || palette || !length || length % 3 || length > 768 || color === 3 && length / 3 > 2 ** depth) return false;
+      palette = true;
+    } else if (kind === 'IDAT') {
+      if (endedData || color === 3 && !palette) return false;
+      data = true; dataLength += length;
+      for (let index = 0; index < value.length && zlibHeader.length < 2; index++) zlibHeader.push(value[index]);
+    } else if (kind === 'IEND') {
+      return length === 0 && end === bytes.length && dataLength >= 6 && (zlibHeader[0] & 15) === 8 && (zlibHeader[0] >>> 4) <= 7 && !(zlibHeader[1] & 32) && ((zlibHeader[0] << 8) + zlibHeader[1]) % 31 === 0;
+    } else {
+      if (data) endedData = true;
+      if (kind[0] === kind[0].toUpperCase()) return false; // Unknown critical chunk.
+    }
+    offset = end;
+  }
+  return false;
+}
+
+function jpegStructure(bytes) {
+  let offset = 2, frame = false, quantization = false, entropy = false, scans = 0;
+  while (offset < bytes.length) {
+    if (bytes[offset++] !== 255) return false;
+    while (bytes[offset] === 255) offset++;
+    const marker = bytes[offset++];
+    if (marker === 0xd9) return frame && quantization && entropy && scans > 0 && offset === bytes.length;
+    if (marker === undefined || marker === 0 || marker === 0xd8 || marker >= 0xd0 && marker <= 0xd7) return false;
+    if (marker === 0x01) continue;
+    if (offset + 2 > bytes.length) return false;
+    const length = bytes.readUInt16BE(offset), end = offset + length;
+    if (length < 2 || end > bytes.length) return false;
+    if ([0xc0,0xc1,0xc2].includes(marker)) {
+      if (frame || length < 8) return false;
+      const components = bytes[offset + 7];
+      if (!components || components > 4 || length !== 8 + components * 3 || ![8,12].includes(bytes[offset + 2]) || !dimensionsAllowed(bytes.readUInt16BE(offset + 5), bytes.readUInt16BE(offset + 3))) return false;
+      frame = true;
+    }
+    if (marker === 0xdb) { if (length < 67) return false; quantization = true; }
+    offset = end;
+    if (marker === 0xda) {
+      const components = bytes[end - length + 2];
+      if (!frame || !quantization || !components || components > 4 || length !== 6 + 2 * components) return false;
+      scans++;
+      // Scan bytes may contain FF00 escapes and restart markers, not segments.
+      while (offset < bytes.length) {
+        if (bytes[offset] !== 255) { entropy = true; offset++; continue; }
+        const next = bytes[offset + 1];
+        if (next === 0 || next >= 0xd0 && next <= 0xd7) { entropy = true; offset += 2; continue; }
+        if (next === 255) { offset++; continue; }
+        break;
+      }
+    }
+  }
+  return false;
+}
+
+function webpFrame(kind, value) {
+  if (kind === 'VP8 ') {
+    if (value.length < 11 || value[0] & 1 || !(value[0] & 16) || !value.subarray(3,6).equals(Buffer.from([0x9d,1,0x2a]))) return null;
+    const partition = value.readUIntLE(0,3) >>> 5;
+    const width = value.readUInt16LE(6) & 0x3fff, height = value.readUInt16LE(8) & 0x3fff;
+    return partition > 0 && partition <= value.length - 10 && dimensionsAllowed(width,height) ? { width,height } : null;
+  }
+  if (kind === 'VP8L') {
+    if (value.length < 6 || value[0] !== 0x2f || value[4] >>> 5) return null;
+    const bits = value.readUInt32LE(1), width = (bits & 0x3fff) + 1, height = ((bits >>> 14) & 0x3fff) + 1;
+    return dimensionsAllowed(width,height) ? { width,height } : null;
+  }
+  return null;
+}
+function webpStructure(bytes) {
+  if (bytes.length < 26 || bytes.readUInt32LE(4) + 8 !== bytes.length) return false;
+  let offset = 12, canvas = null, frame = null;
+  while (offset + 8 <= bytes.length) {
+    const kind = bytes.toString('latin1',offset,offset + 4), length = bytes.readUInt32LE(offset + 4), end = offset + 8 + length, next = end + (length & 1);
+    if (next > bytes.length || length & 1 && bytes[end] !== 0) return false;
+    const value = bytes.subarray(offset + 8,end);
+    if (kind === 'VP8X') {
+      if (offset !== 12 || length !== 10 || value[0] & 0xc1 || value[1] || value[2] || value[3] || value[0] & 2) return false; // Static images only.
+      canvas = {width:value.readUIntLE(4,3) + 1,height:value.readUIntLE(7,3) + 1};
+      if (!dimensionsAllowed(canvas.width,canvas.height)) return false;
+    } else if (kind === 'VP8 ' || kind === 'VP8L') {
+      if (frame || !(frame = webpFrame(kind,value))) return false;
+    } else if (!canvas || kind === 'ANIM' || kind === 'ANMF') return false;
+    offset = next;
+  }
+  return offset === bytes.length && frame !== null && (!canvas || canvas.width === frame.width && canvas.height === frame.height);
+}
+
+// Bounded container/header validation, not full pixel decoding. Format contracts:
+// https://www.w3.org/TR/png-3/ ; https://www.w3.org/Graphics/JPEG/itu-t81.pdf
+// https://developers.google.com/speed/webp/docs/riff_container
+export function imageSignature(bytes) {
+  if (!Buffer.isBuffer(bytes) || bytes.length > HUMAN_IMAGE_LIMIT) return null;
+  if (bytes.length >= 8 && bytes.subarray(0,8).equals(Buffer.from('89504e470d0a1a0a','hex'))) return pngStructure(bytes) ? 'image/png' : null;
+  if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return jpegStructure(bytes) ? 'image/jpeg' : null;
+  if (bytes.length >= 12 && bytes.subarray(0,4).toString() === 'RIFF' && bytes.subarray(8,12).toString() === 'WEBP') return webpStructure(bytes) ? 'image/webp' : null;
+  return null;
+}
+
+export async function stageImage(candidate, options = {}) {
+  let filename;
+  if (typeof candidate === 'object' && candidate && typeof candidate.path === 'string') filename = path.resolve(options.cwd || process.cwd(), candidate.path);
+  else {
+    const matches = findImageCandidates(String(candidate), options);
+    if (matches.length !== 1 || matches[0].start !== 0 || matches[0].end !== String(candidate).length) throw fail('Select one literal PNG, JPEG or WebP image path.');
+    filename = matches[0].path;
+  }
+  let file;
+  try {
+    // O_NONBLOCK avoids waiting on FIFOs; O_NOFOLLOW refuses a final symlink.
+    // fstat validates the opened descriptor, closing the lstat/open race.
+    file = await open(filename, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+    const before = await file.stat();
+    if (!before.isFile()) throw fail('The selected image must be a regular file.');
+    if (!before.size || before.size > HUMAN_IMAGE_LIMIT) throw fail('Images must be nonempty and at most 2 MiB.', 'IMAGE_ATTACHMENT_SIZE');
+    const buffer = Buffer.alloc(HUMAN_IMAGE_LIMIT + 1); let offset = 0;
+    while (offset < buffer.length) {
+      const { bytesRead } = await file.read(buffer, offset, buffer.length - offset, offset);
+      if (!bytesRead) break;
+      offset += bytesRead;
+    }
+    const after = await file.stat();
+    if (offset > HUMAN_IMAGE_LIMIT) throw fail('Images must be at most 2 MiB.', 'IMAGE_ATTACHMENT_SIZE');
+    if (before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || offset !== before.size) throw fail('The image changed during capture. Select it again.', 'IMAGE_ATTACHMENT_CHANGED');
+    const bytes = buffer.subarray(0, offset), media_type = imageSignature(bytes);
+    if (!media_type) throw fail('Invalid or unsupported image. Select a complete PNG, JPEG or static WebP image, at most 16384 pixels per side and 40 megapixels.', 'IMAGE_ATTACHMENT_FORMAT');
+    const id = randomUUID(), descriptor = Object.freeze({ id, label: '[Image]', name: path.basename(filename), path: filename, sha256: createHash('sha256').update(bytes).digest('hex'), bytes: bytes.length, media_type });
+    const stage = Object.freeze({ descriptor });
+    staged.set(stage, { data: bytes.toString('base64'), descriptor });
+    return stage;
+  } catch (error) {
+    if (error.code?.startsWith('IMAGE_ATTACHMENT')) throw error;
+    if (error.code === 'ELOOP') throw fail('Symbolic links cannot be attached. Select the image file itself.');
+    throw fail(`Cannot attach the selected image: ${error.code || error.message}.`);
+  } finally { await file?.close(); }
+}
+
+export function descriptorForStage(stage) {
+  const snapshot = staged.get(stage);
+  if (!snapshot) throw fail('The image snapshot was not captured by the composer.');
+  return snapshot.descriptor;
+}
+
+// The selected external file is read exactly once. Only the sealed host record
+// holds encoded bytes; drafts, queues and model messages carry small references.
+export async function persistHumanImage(store, sessionId, stage) {
+  const snapshot = staged.get(stage);
+  if (!snapshot) throw fail('The image snapshot was not captured by the composer.');
+  const row = await store.append(sessionId, { type: 'human_image', source: 'image_attachment_host', actor: { kind: 'human', id: 'local-user' }, session_id: sessionId,
+    attachment: snapshot.descriptor, data: snapshot.data });
+  return Object.freeze({ kind: 'human_attachment', attachment_id: snapshot.descriptor.id,
+    evidence: Object.freeze({ session_id: sessionId, row: row.audit.sequence }), name: snapshot.descriptor.name,
+    media_type: snapshot.descriptor.media_type, bytes: snapshot.descriptor.bytes, sha256: snapshot.descriptor.sha256 });
+}
+
+export function resolveHumanImage(session, reference) {
+  if (!auditJournal(session.rows || []).verified) throw fail('Image attachment journal integrity could not be verified.', 'AUDIT_INVALID');
+  return decodeRecordedImage(session, reference);
+}
+
+function decodeRecordedImage(session, reference) {
+  if (reference?.kind !== 'human_attachment' || reference.evidence?.session_id !== session.id || !Number.isSafeInteger(reference.evidence.row)) throw fail('The image reference is outside this session.');
+  const row = session.rows[reference.evidence.row], attachment = row?.attachment;
+  if (row?.type !== 'human_image' || row.source !== 'image_attachment_host' || !isHuman(row.actor) || row.session_id !== session.id
+    || reference.attachment_id !== attachment?.id || reference.sha256 !== attachment.sha256 || reference.bytes !== attachment.bytes || reference.media_type !== attachment.media_type
+    || !/^[a-f0-9]{64}$/.test(attachment.sha256) || !Number.isSafeInteger(attachment.bytes) || attachment.bytes < 1 || attachment.bytes > HUMAN_IMAGE_LIMIT
+    || typeof row.data !== 'string' || row.data.length > Math.ceil(HUMAN_IMAGE_LIMIT / 3) * 4) throw fail('The image reference does not match a human-selected snapshot.');
+  const bytes = Buffer.from(row.data, 'base64');
+  if (bytes.toString('base64') !== row.data || bytes.length !== attachment.bytes || createHash('sha256').update(bytes).digest('hex') !== attachment.sha256 || imageSignature(bytes) !== attachment.media_type) throw fail('The image snapshot does not match its recorded digest.');
+  return { ...attachment, data: row.data };
+}
+
+// Only an explicit human composer message activates a captured draft. A staged
+// image alone, tool text, assistant reference or projected row grants no pixels.
+export function humanImageReferences(session) {
+  const rows = session.rows || [], reset = rows.findLastIndex(row => row.type === 'reset');
+  const messages = rows.slice(reset + 1).filter(row => row.type === 'message' && row.source === 'human_composer' && isHuman(row.actor) && row.message?.role === 'user' && Array.isArray(row.message.content));
+  const latest = messages.findLast(row => row.message.content.some(block => block.type === 'image_reference' && block.reference?.kind === 'human_attachment'));
+  if (!latest) return [];
+  if (!auditJournal(rows).verified) throw fail('Image attachment journal integrity could not be verified.', 'AUDIT_INVALID');
+  const references = latest.message.content.filter(block => block.type === 'image_reference').map(block => block.reference);
+  if (references.length > HUMAN_IMAGE_COUNT) throw fail('Attach at most two images per message.', 'IMAGE_ATTACHMENT_COUNT');
+  for (const reference of references) {
+    if (reference.evidence?.row <= reset) throw fail('The image attachment was cleared by the session reset.');
+    if (reference.evidence.row >= rows.indexOf(latest)) throw fail('The image snapshot must precede its human message.');
+    decodeRecordedImage(session, reference);
+  }
+  return references;
+}

package/src/model-controls.mjs

@@ -7,7 +7,7 @@ const bool = value => typeof value === 'boolean' ? value : typeof value?.support
 const validLevel = value => EFFORT_LEVELS.includes(value);
 const fail = message => Object.assign(new Error(message), { code: 'MODEL_EFFORT_UNAVAILABLE' });
 export function normalizeEffort(value = 'auto') {
-  if (typeof value !== 'string' || !validLevel(value)) throw fail(`Effort inválido. Usa ${EFFORT_LEVELS.join(', ')}.`);
+  if (typeof value !== 'string' || !validLevel(value)) throw fail(`Invalid effort. Use ${EFFORT_LEVELS.join(', ')}.`);
   return value;
 }
 function protocol(provider) { return provider.protocol || (provider.url ? 'anthropic' : provider.baseURL?.includes('generativelanguage') ? 'gemini' : 'openai'); }
@@ -24,7 +24,7 @@ async function json(provider, url, { signal, ...options } = {}) {
   if (!reader) return null;
   let text = '', size = 0; const decoder = new TextDecoder();
   try {
-    for (;;) { const { value, done } = await reader.read(); if (done) break; size += value.byteLength; if (size > 1024 * 1024) throw new Error('Metadatos del modelo exceden 1 MiB.'); text += decoder.decode(value, { stream: true }); }
+    for (;;) { const { value, done } = await reader.read(); if (done) break; size += value.byteLength; if (size > 1024 * 1024) throw new Error('Model metadata exceeds 1 MiB.'); text += decoder.decode(value, { stream: true }); }
     return JSON.parse(text + decoder.decode());
   } finally { await reader.cancel(); }
 }
@@ -44,7 +44,7 @@ export async function listProviderModels(provider, { signal } = {}) {
     const url = new URL(base(provider));
     if (next) url.searchParams.set(protocol(provider) === 'gemini' ? 'pageToken' : 'after_id', next);
     const data = await json(provider, url.href, { signal });
-    if (!data) throw Object.assign(new Error('El servidor no permitió listar modelos.'), { code: 'MODEL_DISCOVERY_UNAVAILABLE' });
+    if (!data) throw Object.assign(new Error('The server did not allow listing models.'), { code: 'MODEL_DISCOVERY_UNAVAILABLE' });
     for (const item of Array.isArray(data.data) ? data.data : Array.isArray(data.models) ? data.models : []) { const safe = safeModel(item); if (safe && !models.some(model => model.id === safe.id)) models.push(safe); }
     next = protocol(provider) === 'gemini' ? data.nextPageToken : data.has_more ? data.last_id : '';
   } while (next && ++pages < 8 && models.length < 1024);
@@ -156,7 +156,7 @@ export async function setProviderEffort(provider, value, { signal } = {}) {
   value = normalizeEffort(value);
   if (value !== 'auto') {
     const state = await discoverModelCapabilities(provider, { signal });
-    if (!state.effort.levels.includes(value)) throw fail(`El modelo ${provider.model || '(sin modelo)'} no anuncia effort ${value}. Disponibles: ${state.effort.levels.join(', ')}.`);
+    if (!state.effort.levels.includes(value)) throw fail(`Model ${provider.model || '(no model)'} does not advertise effort ${value}. Available: ${state.effort.levels.join(', ')}.`);
   }
   provider.effort = value;
   if (Object.hasOwn(provider, 'thinking')) provider.thinking = 'auto';

package/src/onboarding.mjs

@@ -0,0 +1,91 @@
+import { readFile, mkdir, writeFile, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { t } from './i18n/index.mjs';
+
+const selectors = ['provider', 'base-url', 'model', 'profile', 'providers-config', 'auth-provider'];
+export function hasProviderSelection(options = {}, profiles = {}, env = process.env) {
+  return Boolean(options.demo || options.resume || options.continue || selectors.some(key => options[key]) || profiles.defaultProfile || Object.entries(env).some(([key, value]) => value && /^(?:(?:COMAL|HARNESS)_(?:PROVIDER|BASE_URL|MODEL|PROVIDERS_CONFIG|PROFILE)|(?:OPENAI|ANTHROPIC|GEMINI)_(?:BASE_URL|MODEL|API_KEY))$/.test(key)));
+}
+const preferenceFile = env => path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'comal', 'connection.json');
+function normalizeConnection(value) {
+  if (!value || Array.isArray(value) || typeof value !== 'object' || Object.keys(value).some(key => !['provider', 'base-url', 'model', 'auth-provider'].includes(key))) throw Error('Invalid saved Comal connection.');
+  if (value['auth-provider']) {
+    if (Object.keys(value).some(key => !['auth-provider', 'model'].includes(key)) || !['codex','kimi','minimax','grok'].includes(value['auth-provider'])) throw Error('Invalid saved login provider.');
+  } else {
+    if (value.provider !== 'openai') throw Error('Invalid saved connection protocol.');
+    const url = new URL(value['base-url']);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw Error('Use an HTTP(S) endpoint without embedded credentials or query parameters.');
+  }
+  if (value.model !== undefined && (typeof value.model !== 'string' || !value.model.trim() || value.model.length > 256 || /[\x00-\x1f\x7f]/.test(value.model))) throw Error('Invalid saved model.');
+  return { ...value };
+}
+export async function loadConnection({ env = process.env } = {}) {
+  try { const text = await readFile(preferenceFile(env), 'utf8'); if (Buffer.byteLength(text) > 4096) throw Error('Saved Comal connection exceeds 4 KiB.'); return normalizeConnection(JSON.parse(text)); }
+  catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+export async function saveConnection(value, { env = process.env } = {}) {
+  const data = normalizeConnection(value), file = preferenceFile(env), temporary = file + '.' + randomUUID();
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  try { await writeFile(temporary, JSON.stringify(data) + '\n', { flag: 'wx', mode: 0o600 }); await rename(temporary, file); }
+  finally { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
+}
+
+// The terminal stays owned by the caller. Only a successfully validated connection
+// is remembered; credentials live in AuthManager/environment, never in this file.
+export async function onboard({ ui, profiles, authManager, connect, signal, env = process.env }) {
+  while (!signal?.aborted && !ui.closed) {
+    const choice = await ui.setupChoice({ title: t('Your first turn'), description: t('Choose how to start. Stay here while Comal connects.'), signal, items: [
+      { id: 'demo', label: t('Try the offline demo'), description: t('No account or model. A scripted tool cycle; no inference.') },
+      ...profiles.profiles.map(profile => ({ id: 'profile:' + profile.name, label: profile.name, description: `${profile.provider} · ${profile.model || t('discover model')}` })),
+      { id: 'codex', label: t('Connect Codex'), description: t('Sign in with your existing subscription in the browser.') },
+      { id: 'server', label: t('Connect a model server'), description: t('OpenAI-compatible endpoint. API keys stay in your environment.') },
+    ] });
+    if (!choice || signal?.aborted || ui.closed) return null;
+    if (choice === 'demo') { ui.clearSetup(); return { options: { demo: true } }; }
+    let options;
+    try {
+      if (choice.startsWith('profile:')) options = { profile: choice.slice(8) };
+      else if (choice === 'codex') {
+        ui.setupStatus({ title: t('Connecting Codex'), description: t('Waiting for browser authorization. Esc cancels this connection.') });
+        const operation = new AbortController();
+        ui.callbacks.onSetupCancel = () => operation.abort();
+        try {
+          const status = await authManager.status('codex');
+          operation.signal.throwIfAborted(); signal?.throwIfAborted();
+          if (status.status !== 'authenticated') await authManager.login('codex', { signal: signal ? AbortSignal.any([signal, operation.signal]) : operation.signal, onEvent: event => {
+            if (operation.signal.aborted || signal?.aborted || ui.closed) return;
+            if (event.type === 'device_code') ui.setupStatus({ title: t('Authorize Codex'), description: `${event.verification_uri}\n\n${t('Code')}: ${event.user_code}\n\n${t('Approve only if you started this connection. Esc cancels.')}` });
+          } });
+          operation.signal.throwIfAborted(); signal?.throwIfAborted();
+        } finally { delete ui.callbacks.onSetupCancel; }
+        options = { 'auth-provider': 'codex' };
+      } else {
+        const endpoint = await ui.setupInput({ title: t('Model server'), description: t('Endpoint URL. No API key or password in the URL.'), value: 'http://127.0.0.1:8080/v1', signal, validate: text => { try { normalizeConnection({ provider: 'openai', 'base-url': text }); return true; } catch (error) { return error.message; } } });
+        if (!endpoint) continue;
+        const model = await ui.setupInput({ title: t('Model'), description: t('Leave empty to discover the model from /models. OPENAI_API_KEY is used when set.'), signal });
+        if (model === null) continue;
+        options = { provider: 'openai', 'base-url': endpoint, ...(model.trim() ? { model: model.trim() } : {}) };
+      }
+      ui.setupStatus({ title: t('Checking connection'), description: t('Discovering the model and its capabilities. No task is sent.') });
+      const connection = await connect(options);
+      signal?.throwIfAborted(); if (ui.closed) return null;
+      if (!options.profile) {
+        try { await saveConnection({ ...options, ...(connection.provider?.model ? { model: connection.provider.model } : {}) }, { env }); }
+        catch (error) { ui.notice(t('Connected, but settings could not be saved: ') + error.message, true); }
+      }
+      ui.clearSetup(); return { options, connection };
+    } catch (error) {
+      if (signal?.aborted || ui.closed) return null;
+      if (error.name === 'AbortError' || error.code === 'ABORT_ERR') continue;
+      const action = await ui.setupChoice({ title: t('Connection not ready'), description: String(error.message).slice(0, 600), signal, items: [
+        { id: 'back', label: t('Choose another connection'), description: t('Your terminal stays open.') },
+        { id: 'demo', label: t('Try the offline demo'), description: t('Continue without an account or model.') },
+      ] });
+      if (!action) return null;
+      if (action === 'demo') { ui.clearSetup(); return { options: { demo: true } }; }
+    }
+  }
+  return null;
+}

package/src/openai-provider.mjs

@@ -13,7 +13,7 @@ export const DEFAULT_LOCAL_URL = 'http://llama.local:11438/';
 // Accept both server roots and conventional OpenAI base URLs ending in /v1.
 export function openaiBaseURL(baseURL) {
   const url = new URL(baseURL);
-  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error('URL OpenAI inválida; usa una base HTTP(S) sin credenciales ni query.');
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error('Invalid OpenAI URL; use an HTTP(S) base without credentials or a query.');
   let pathname = url.pathname.replace(/\/+$/, '');
   if (pathname.endsWith('/chat/completions')) pathname = pathname.slice(0, -'/chat/completions'.length);
   if (!pathname.endsWith('/v1')) pathname += '/v1';
@@ -23,12 +23,12 @@ export function openaiBaseURL(baseURL) {
 
 function textContent(content) {
   if (typeof content === 'string') return content;
-  if (!Array.isArray(content)) throw new Error('Contenido de mensaje inválido.');
+  if (!Array.isArray(content)) throw new Error('Invalid message content.');
   return content.filter(block => block.type === 'text').map(block => block.text).join('\n');
 }
 
 export function toOpenAIMessages(system, messages, { reasoningField = 'reasoning_content' } = {}) {
-  if (!['reasoning_content', 'reasoning'].includes(reasoningField)) throw new Error('Campo de razonamiento OpenAI inválido.');
+  if (!['reasoning_content', 'reasoning'].includes(reasoningField)) throw new Error('Invalid OpenAI reasoning field.');
   const result = system ? [{ role: 'system', content: system }] : [];
   for (const message of messages) {
     const blocks = Array.isArray(message.content) ? message.content : [];
@@ -50,8 +50,8 @@ export function toOpenAIMessages(system, messages, { reasoningField = 'reasoning
         for (const block of blocks) {
           if (block.type === 'text') pending.push({ type: 'text', text: block.text });
           else if (block.type === 'image' && block.source?.type === 'base64') pending.push({ type: 'image_url', image_url: { url: `data:${block.source.media_type};base64,${block.source.data}` } });
-          else if (block.type === 'image_reference') throw new Error('Referencia visual sin resolver; no se envió al proveedor.');
-          else if (block.type === 'video' || block.type === 'media') throw Object.assign(new Error('El adaptador OpenAI Chat Completions no admite video; usa un perfil con transporte multimedia.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
+          else if (block.type === 'image_reference') throw new Error('Unresolved image reference; it was not sent to the provider.');
+          else if (block.type === 'video' || block.type === 'media') throw Object.assign(new Error('The OpenAI Chat Completions adapter does not support video; use a profile with media transport.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
         }
       }
       flush();
@@ -61,20 +61,20 @@ export function toOpenAIMessages(system, messages, { reasoningField = 'reasoning
 }
 
 function normalizedMessage({ text = '', reasoning = '', calls = [], finish, usage = {} }) {
-  if (typeof text !== 'string' || typeof reasoning !== 'string' || !Array.isArray(calls)) throw new Error('Contenido OpenAI inválido.');
-  if (!finish) throw new Error('Streaming OpenAI interrumpido; no se ejecutaron herramientas de esta respuesta.');
+  if (typeof text !== 'string' || typeof reasoning !== 'string' || !Array.isArray(calls)) throw new Error('Invalid OpenAI content.');
+  if (!finish) throw new Error('OpenAI streaming was interrupted; no tools from this response were executed.');
   if (finish === 'length') {
-    const error = new Error('Respuesta OpenAI truncada (length): se agotó el presupuesto de generación o el espacio del servidor; no se ejecutaron herramientas. Usa /compact y --max-tokens, o divide el script en llamadas más pequeñas.');
+    const error = new Error('OpenAI response truncated (length): generation budget or server capacity exhausted; no tools were executed. Use /compact and --max-tokens, or split the script into smaller calls.');
     error.code = 'OUTPUT_LENGTH'; error.usage_accounting = normalizeUsage('openai',usage); error.usage = { input_tokens: usage.prompt_tokens || 0, output_tokens: usage.completion_tokens || 0 }; throw error;
   }
-  if (finish === 'content_filter') throw new Error('Respuesta OpenAI incompleta (content_filter); no se ejecutaron herramientas.');
+  if (finish === 'content_filter') throw new Error('Incomplete OpenAI response (content_filter); no tools were executed.');
   if (finish !== 'stop' && finish !== 'tool_calls') throw new Error(`finish_reason OpenAI no soportado: ${finish}`);
-  if (finish === 'tool_calls' && !calls.length) throw new Error('Respuesta tool_calls sin llamadas.');
+  if (finish === 'tool_calls' && !calls.length) throw new Error('tool_calls response contains no calls.');
   const content = [], ids = new Set();
   if (reasoning) content.push({ type: 'openai_reasoning', text: reasoning });
   if (text) content.push({ type: 'text', text });
   for (const call of calls) {
-    if (typeof call.id !== 'string' || !call.id || ids.has(call.id) || call.type !== 'function' || !call.function?.name) throw new Error('Llamada de herramienta OpenAI inválida.');
+    if (typeof call.id !== 'string' || !call.id || ids.has(call.id) || call.type !== 'function' || !call.function?.name) throw new Error('Invalid OpenAI tool call.');
     let input;
     try {
       if (call.function.arguments !== undefined && typeof call.function.arguments !== 'string') throw new Error('Non-string arguments');
@@ -82,14 +82,14 @@ function normalizedMessage({ text = '', reasoning = '', calls = [], finish, usag
       if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Non-object arguments');
     } catch {
       const raw = typeof call.function.arguments === 'string' ? call.function.arguments : JSON.stringify(call.function.arguments ?? '');
-      throw Object.assign(new Error('JSON de argumentos OpenAI inválido; no se ejecutaron herramientas.'), { code: 'TOOL_ARGUMENTS_INVALID', usage_accounting: normalizeUsage('openai',usage),
+      throw Object.assign(new Error('Invalid OpenAI argument JSON; no tools were executed.'), { code: 'TOOL_ARGUMENTS_INVALID', usage_accounting: normalizeUsage('openai',usage),
         usage: { input_tokens: usage.prompt_tokens || 0, output_tokens: usage.completion_tokens || 0 },
         details: { call_id: call.id, tool: call.function.name, arguments_bytes: Buffer.byteLength(raw), arguments_digest: digest(raw) } });
     }
     ids.add(call.id);
     content.push({ type: 'tool_use', id: call.id, name: call.function.name, input });
   }
-  if (!text && !calls.length) throw Object.assign(new Error('El modelo no devolvió texto ni herramientas.'), { code: 'MODEL_EMPTY', usage_accounting: normalizeUsage('openai',usage), usage: { input_tokens: usage.prompt_tokens || 0, output_tokens: usage.completion_tokens || 0 } });
+  if (!text && !calls.length) throw Object.assign(new Error('The model returned neither text nor tools.'), { code: 'MODEL_EMPTY', usage_accounting: normalizeUsage('openai',usage), usage: { input_tokens: usage.prompt_tokens || 0, output_tokens: usage.completion_tokens || 0 } });
   return { role: 'assistant', content, stop_reason: calls.length ? 'tool_use' : 'end_turn', usage_accounting: normalizeUsage('openai',usage), usage: { input_tokens: usage.prompt_tokens || 0, output_tokens: usage.completion_tokens || 0 } };
 }
 
@@ -100,7 +100,7 @@ export class OpenAIProvider {
     this.reasoningField = new URL(this.baseURL).hostname === 'ollama.com' ? 'reasoning' : 'reasoning_content';
     Object.assign(this, modelTimingSettings({ timeoutMs, idleTimeoutMs }, {}));
     this.maxTokens = maxTokens; this.fetch = fetchImpl;
-    if (!['auto', 'on', 'off', 'low', 'medium', 'high'].includes(thinking)) throw new Error('--thinking / COMAL_THINKING debe ser auto, on, off, low, medium o high.');
+    if (!['auto', 'on', 'off', 'low', 'medium', 'high'].includes(thinking)) throw new Error('--thinking / COMAL_THINKING must be auto, on, off, low, medium or high.');
     this.thinking = thinking;
     Object.assign(this, visionSettings({ vision, imageTokens }, {}));
     this.visionCache = new Map();
@@ -123,7 +123,7 @@ export class OpenAIProvider {
         ...(ollamaCloud ? { method: 'POST', body: JSON.stringify({ model: this.model }) } : {}) });
       if (response.ok) {
         let text = ''; const reader = response.body.getReader(), decoder = new TextDecoder();
-        try { for (;;) { const { value, done } = await reader.read(); if (done) { text += decoder.decode(); break; } text += decoder.decode(value, { stream: true }); if (Buffer.byteLength(text) > 65536) throw new Error('Props demasiado grande.'); } }
+        try { for (;;) { const { value, done } = await reader.read(); if (done) { text += decoder.decode(); break; } text += decoder.decode(value, { stream: true }); if (Buffer.byteLength(text) > 65536) throw new Error('Props response is too large.'); } }
         finally { await reader.cancel(); }
         const props = JSON.parse(text);
         if (ollamaCloud && Array.isArray(props.capabilities)) capability = { ...base, supported: props.capabilities.includes('vision'), source: 'ollama_show' };
@@ -150,9 +150,9 @@ export class OpenAIProvider {
       details = JSON.parse(text).error;
     } catch {}
     if ([400, 413, 422].includes(response.status) && (details?.code === 'context_length_exceeded' || /(?:context|prompt).*(?:exceed|too (?:long|large)|overflow)|exceed.*context/i.test(String(details?.message || '')))) {
-      const error = new Error('El servidor rechazó la petición porque excede su ventana de contexto. Usa /compact o reduce COMAL_CONTEXT_WINDOW.'); error.code = 'CONTEXT_LENGTH'; throw error;
+      const error = new Error('The server rejected the request because it exceeds its context window. Use /compact or reduce COMAL_CONTEXT_WINDOW.'); error.code = 'CONTEXT_LENGTH'; throw error;
     }
-    throw new Error(`OpenAI HTTP ${response.status}. Revisa el endpoint, modelo y OPENAI_API_KEY si el servidor requiere autenticación.`);
+    throw new Error(`OpenAI HTTP ${response.status}. Check the endpoint, model and OPENAI_API_KEY if the server requires authentication.`);
   }
   async discoverModel({ signal } = {}) {
     if (this.model) return this.model;
@@ -165,7 +165,7 @@ export class OpenAIProvider {
       const models = Array.isArray(body.data) ? body.data : Array.isArray(body.models) ? body.models : [];
       this.discoveredModels = models;
       const model = models.map(item => item.id || item.name || item.model).find(id => typeof id === 'string' && id.trim());
-      if (!model) throw new Error('El servidor no anuncia modelos; especifica COMAL_MODEL, OPENAI_MODEL o --model.');
+      if (!model) throw new Error('The server does not advertise models; specify COMAL_MODEL, OPENAI_MODEL or --model.');
       this.model = model; return model;
     } catch (error) { throw deadline.error(error); } finally { deadline.close(); }
   }
@@ -174,7 +174,7 @@ export class OpenAIProvider {
     const accountingRequest={system,messages,tools,maxTokens}, identity={...accountingIdentity(this),projection_epoch:contextIdentity?.projection_epoch ?? null};
     const schemaFrame=compileToolSchemas(tools,{provider:this.protocol,capabilities:{...(this.getCapabilities?.() || {}),...(this.toolSchemaCapabilities?{tool_schema:this.toolSchemaCapabilities}:{})},catalogue:schemaCatalog}); tools=schemaFrame.tools;
     if (messages.some(message => Array.isArray(message.content) && message.content.some(block => block.type === 'image'))) {
-      if (!(await this.getVisionCapability({ signal })).supported) throw new Error('El proveedor no anuncia visión; no se enviaron píxeles. Configura un modelo multimodal o --vision on sólo si tu endpoint lo soporta.');
+      if (!(await this.getVisionCapability({ signal })).supported) throw new Error('The provider does not advertise vision; no pixels were sent. Configure a multimodal model, or --vision on only if your endpoint supports it.');
     }
     const effortWire = await providerEffortWire(this, { signal });
     const body = JSON.stringify({ model: this.model, messages: toOpenAIMessages(system, messages, { reasoningField: this.reasoningField }), max_tokens: maxTokens, stream: true, stream_options: { include_usage: true },
@@ -182,20 +182,20 @@ export class OpenAIProvider {
       ...effortWire,
       ...(tools.length ? { tools: tools.map(tool => ({ type: 'function', function: { name: tool.name, description: tool.description, parameters: tool.input_schema } })), tool_choice: 'auto' } : {}) });
     const account=result=>{result.usage_accounting=bindUsageAccounting(result.usage_accounting,accountingRequest,identity,body); result.schema_diagnostics=schemaFrame.diagnostics;result.schema_manifest=schemaFrame.manifest;return result;};
-    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.');
     const deadline = modelDeadline({ signal, timeoutMs: this.timeoutMs, idleTimeoutMs: this.idleTimeoutMs, purpose });
     const progress = { reasoning_chars: 0, text_chars: 0, tool_argument_chars: 0 }; let lastProgress = 0;
     const report = (force = false) => { if (force || Date.now() - lastProgress >= 750) { lastProgress = Date.now(); onProgress({ ...progress, elapsed_ms: deadline.elapsedMs(), purpose }); } };
     try {
       let response;
       try { response = await this.fetch(`${this.baseURL}/chat/completions`, { method: 'POST', headers: this.headers(), body, signal: deadline.signal }); }
-      catch (error) { if (error.name === 'TypeError') throw new Error(`No se pudo conectar con ${this.baseURL}: ${error.cause?.code || error.message}`); throw error; }
+      catch (error) { if (error.name === 'TypeError') throw new Error(`Could not connect to ${this.baseURL}: ${error.cause?.code || error.message}`); throw error; }
       await this.checkResponse(response);
       deadline.signal.throwIfAborted();
       if (!response.headers.get('content-type')?.includes('text/event-stream')) {
         const data = await response.json();
         deadline.signal.throwIfAborted();
-        if (data.error) throw new Error('El servidor OpenAI devolvió un error.');
+        if (data.error) throw new Error('The OpenAI server returned an error.');
         const choice = data.choices?.find(choice => choice.index === 0) || data.choices?.[0];
         const message = normalizedMessage({ text: choice?.message?.content || '', reasoning: this.reasoningOf(choice?.message), calls: choice?.message?.tool_calls || [], finish: choice?.finish_reason, usage: data.usage });
         for (const block of message.content) if (block.type === 'text') onText(block.text);
@@ -204,7 +204,7 @@ export class OpenAIProvider {
       let text = '', reasoning = '', finish, usage = {}; const calls = new ToolCallStream();
       for await (const event of sseEvents(response.body)) {
         if (event.type === 'stream_done') break;
-        if (event.error) throw new Error('El servidor OpenAI devolvió un error de streaming.');
+        if (event.error) throw new Error('The OpenAI server returned a streaming error.');
         if (event.usage) usage = event.usage;
         const choice = event.choices?.find(choice => choice.index === 0);
         if (!choice) continue;
@@ -236,7 +236,7 @@ export class OpenAIProvider {
 export function providerSettings(options = {}, env = process.env, session) {
   env = comalEnvironment(env);
   const provider = options.provider || env.COMAL_PROVIDER || 'openai';
-  if (!['openai', 'anthropic'].includes(provider)) throw new Error('Proveedor inválido; usa openai o anthropic.');
+  if (!['openai', 'anthropic'].includes(provider)) throw new Error('Invalid provider; use openai or anthropic.');
   const sameProvider = session && (session.provider || 'anthropic') === provider;
   return { provider,
     ...visionSettings(options, env),

package/src/peer-tools.mjs

@@ -65,10 +65,11 @@ export class PeerTurnGuard {
 
 export function providerFeatureDefinitions(provider) {
   const caps=provider.getCapabilities?.() || {};
+  const mediaTypes=[...(caps.vision?['image/png','image/jpeg','image/webp']:[]),...(caps.video?['video/mp4','video/webm','video/quicktime']:[])];
   return [
     {name:'ProviderCapabilities',description:'Read the current provider capability contract. Configured support does not prove task success.',input_schema:object({})},
     ...(caps.web_search && typeof provider.nativeSearch==='function'?[{name:'ProviderSearch',description:'Search using this provider’s native web grounding. Returns its answer and source URLs as untrusted evidence; records provider usage. Requires actual native support.',input_schema:{...object({query:{type:'string',minLength:1,maxLength:4000}}),required:['query']}}]:[]),
-    ...((caps.video || caps.vision) && typeof provider.analyzeMedia==='function'?[{name:'AnalyzeMedia',description:'Read and analyze a workspace image/video DIRECTLY with this provider. No Bash or text Read prerequisite; Read rejecting binary is not an AnalyzeMedia permission denial. Each media call still requires house permission. Bytes stay out of conversation; records hash and advisory answer, not an objective verdict. Video requires video capability.',input_schema:{...object({prompt:{type:'string',minLength:1,maxLength:4000},file_path:{type:'string',minLength:1,maxLength:4096},mime_type:{type:'string',enum:['image/png','image/jpeg','image/webp','video/mp4','video/webm','video/quicktime']}}),required:['prompt','file_path','mime_type']}}]:[]),
+    ...((caps.video || caps.vision) && typeof provider.analyzeMedia==='function'?[{name:'AnalyzeMedia',description:'Analyze workspace media DIRECTLY. Supported MIME types for this provider: '+mediaTypes.join(', ')+'. '+(!caps.video?'Native video is unavailable: extract frames with an authorized local tool, then analyze the images. ':'')+'No text Read prerequisite. Bytes stay out of conversation; results are advisory provider reports, not independent verification.',input_schema:{...object({prompt:{type:'string',minLength:1,maxLength:4000},file_path:{type:'string',minLength:1,maxLength:4096},mime_type:{type:'string',enum:mediaTypes}}),required:['prompt','file_path','mime_type']}}]:[]),
   ];
 }
 
@@ -139,7 +140,7 @@ export async function completePeerReplies(final,{source,baseline=0,requests,stor
   }
 }
 
-export async function executeProviderFeature(name,input,{provider,workspace,record,signal,invoke=async(request,run)=>run(request)}) {
+export async function executeProviderFeature(name,input,{provider,workspace,record,signal,observe=()=>{},invoke=async(request,run)=>run(request)}) {
   const caps=provider.getCapabilities?.() || {text:true,tools:true,vision:false,video:false,web_search:false};
   if(name==='ProviderCapabilities')return JSON.stringify({model:provider.model,capabilities:caps,authority:'capability_contract_not_execution'});
   let result, media;
@@ -148,7 +149,7 @@ export async function executeProviderFeature(name,input,{provider,workspace,reco
     if(name==='ProviderSearch' && caps.web_search && provider.nativeSearch)result=await invoke({messages:[{role:'user',content:input.query}],tools:[],signal,maxTokens:provider.maxTokens},options=>provider.nativeSearch({query:input.query,signal,maxTokens:options.maxTokens}));
     else if(name==='AnalyzeMedia' && provider.analyzeMedia) {
       const video=input.mime_type.startsWith('video/');
-      if(!(video?caps.video:caps.vision))throw new Error('Este perfil no ofrece la capacidad de medios solicitada.');
+      if(!(video?caps.video:caps.vision)){observe({kind:'provider_media_preflight_rejected',reason:'unsupported_modality',mime_type:input.mime_type,target_dispatched:false});throw Object.assign(new Error('The current provider does not support this media type. Use a supported MIME from the live schema; extract video frames for an image-only provider.'),{code:'PROVIDER_MEDIA_UNSUPPORTED'});}
       const file=await workspace.resolve(input.file_path),info=await stat(file);
       if(!info.isFile() || info.size>16*1024*1024)throw new Error('El medio debe ser un archivo del workspace de hasta 16 MiB.');
       const bytes=await readFile(file);if(bytes.length>16*1024*1024)throw new Error('El medio excede 16 MiB.');