@milpa/comal 0.0.0-stage → 0.1.1

package/src/mcp-runtime.mjs

@@ -0,0 +1,219 @@
+import path from 'node:path';
+import { readFile, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { connectMcp, mcpToolDefinition } from './mcp.mjs';
+import { mcpTransport } from './mcp-http.mjs';
+import { validateInput } from './tool-input.mjs';
+
+const string = maxLength => ({ type: 'string', maxLength });
+const stringMap = { type: 'object', additionalProperties: { ...string(16000), minLength: 0 } };
+const object = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
+const serverSchema = object({ type: { type: 'string', enum: ['stdio', 'http', 'streamable-http', 'sse'] }, command: string(2048), args: { type: 'array', maxItems: 100, items: string(16000) }, env: stringMap, url: string(4096), headers: stringMap, headersEnv: stringMap, timeoutMs: { type: 'integer', minimum: 1, maximum: 1800000 }, disabled: { type: 'boolean' } });
+export const mcpManagementTools = [
+  { name: 'McpStatus', description: 'Show MCP config path, configured/connected/pending servers and current tool names. Read-only; never reveals credentials.', input_schema: object({}) },
+  { name: 'McpConfigure', description: 'Persist an MCP server in the active config file. action=upsert requires server (stdio command/args/env or HTTP url/headersEnv); remove deletes its config entry. Existing fields are preserved on update. connect defaults true: then reload after SEPARATE connection permission. connect=false saves only. Prefer environment references for credentials. Newly connected tools appear in the NEXT model request of this same session.', input_schema: object({ action: { type: 'string', enum: ['upsert', 'remove'] }, name: string(32), server: serverSchema, connect: { type: 'boolean' } }, ['action', 'name']) },
+  { name: 'McpReload', description: 'Reload the active MCP JSON config in this session and refresh tool schemas. config_path selects a workspace file. reconnect names one server to restart. Connection/replacement/removal needs permission independently from config writes and MCP tool execution. Failures keep the previous live catalog; tool calls are never replayed.', input_schema: object({ config_path: string(4096), reconnect: string(32) }) },
+];
+const digest = text => createHash('sha256').update(text).digest('hex');
+const canonical = value => value && typeof value === 'object' ? Array.isArray(value) ? value.map(canonical) : Object.keys(value).sort().map(key => [key, canonical(value[key])]) : value;
+const fingerprint = value => digest(JSON.stringify(canonical(value)));
+const validName = name => /^[a-zA-Z0-9_-]{1,32}$/.test(name) && !['__proto__', 'constructor', 'prototype'].includes(name);
+function validateConfig(config) {
+  if (!config || typeof config !== 'object' || !config.mcpServers || typeof config.mcpServers !== 'object' || Array.isArray(config.mcpServers)) throw new Error('Config MCP requiere {mcpServers:{nombre:servidor}}.');
+  if (Object.keys(config.mcpServers).length > 16) throw new Error('Máximo 16 servidores MCP por configuración.');
+  for (const [name, server] of Object.entries(config.mcpServers)) {
+    if (!validName(name) || !server || typeof server !== 'object' || Array.isArray(server)) throw new Error(`Servidor MCP inválido: ${name}`);
+    if (server.disabled) continue;
+    const type = mcpTransport(server);
+    if (type === 'stdio' && (typeof server.command !== 'string' || !server.command || server.args && (!Array.isArray(server.args) || server.args.some(arg => typeof arg !== 'string')))) throw new Error(`Servidor ${name}: falta command/args válidos.`);
+    if (type !== 'stdio') { const url = new URL(server.url); if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash) throw new Error(`URL MCP inválida en ${name}.`); }
+  }
+  return config;
+}
+function publicServer(server) {
+  const result = structuredClone(server);
+  for (const [key, value] of Object.entries(result.env || {})) if (/token|secret|password|key|credential/i.test(key)) result.env[key] = /^\$\{\w+\}$/.test(value) ? value : '[redacted]';
+  for (const key of Object.keys(result.headers || {})) if (!result.headers[key].includes('${')) result.headers[key] = '[redacted]';
+  if (result.url) { const url = new URL(result.url); for (const key of [...url.searchParams.keys()]) url.searchParams.set(key, '[redacted]'); result.url = url.href; }
+  return result;
+}
+
+export class McpRuntime {
+  constructor({ cwd, configPath, workspace, policy, publish, onEvent = () => {}, onPermission = () => {}, getContext, clientOptions = {}, startupAsk, judge }) {
+    Object.assign(this, { cwd, workspace, policy, publish, onEvent, onPermission, getContext, clientOptions, startupAsk, judge });
+    this.file = configPath ? path.resolve(configPath) : path.join(cwd, '.mcp.json'); this.explicitFile = configPath ? this.file : null;
+    this.entries = new Map(); this.desired = { mcpServers: {} }; this.operations = Promise.resolve(); this.retired = new Set(); this.dirty = new Set(); this.lifetime = new AbortController();
+  }
+  exclusive(operation) {
+    const result = this.operations.catch(() => {}).then(() => { if (this.closed) throw new Error('Runtime MCP cerrado.'); return operation(); });
+    this.operations = result; return result;
+  }
+  signal(signal) { return AbortSignal.any([this.lifetime.signal, ...(signal ? [signal] : [])]); }
+  async authorize(name, input, signal) {
+    signal.throwIfAborted(); if (this.getContext) this.policy.setContext(await this.getContext());
+    if (this.judge) return this.judge(name, input, { signal });
+    const decision = await this.policy.authorize(name, input, { signal }); await this.onPermission({ name, input, ...decision });
+    if (!decision.allowed) throw new Error(`Permiso denegado: ${name}: ${decision.reason}`);
+    signal.throwIfAborted(); return decision;
+  }
+  mutable(signal) { signal.throwIfAborted(); if (this.policy.mode === 'plan') throw new Error('Permiso denegado: modo plan no modifica ni conecta MCP.'); }
+  async read(file, { missing = false } = {}) {
+    let resolved;
+    try {
+      resolved = file === this.explicitFile ? file : await this.workspace.resolve(file);
+      const info = await stat(resolved); if (!info.isFile() || info.size > 1024 * 1024) throw new Error('Config MCP debe ser texto de máximo 1 MiB.');
+      if (this.policy.denied.has('Read')) throw new Error('Permiso denegado: Read de configuración MCP.');
+      const text = await readFile(resolved, 'utf8'); return { file, text, hash: digest(text), config: validateConfig(JSON.parse(text)) };
+    } catch (error) { if (missing && error.code === 'ENOENT') return { file, text: null, hash: null, config: { mcpServers: {} } }; throw error; }
+  }
+  tools() { return [...this.entries.values()].flatMap(entry => entry.tools); }
+  status() {
+    const names = new Set([...Object.keys(this.desired.mcpServers), ...this.entries.keys()]);
+    return { config_path: this.file, servers: [...names].map(name => {
+      const entry = this.entries.get(name), config = this.desired.mcpServers[name];
+      return { name, status: config?.disabled ? 'disabled' : entry ? entry.client.dead ? 'disconnected' : 'connected' : 'pending', transport: entry?.client.mode || entry?.client.transport || (config?.disabled ? 'disabled' : mcpTransport(config)), protocol: entry?.client.protocolVersion, tools: entry?.tools.map(tool => tool.name) || [], pending_changes: Boolean(entry && (!config || config.disabled || entry.fingerprint !== fingerprint(config))) || Boolean(!entry && config && !config.disabled) };
+    }), tools: this.tools().map(tool => tool.name), ...(this.lastError ? { last_error: this.lastError } : {}) };
+  }
+  wrap(entry, definitions, revision) {
+    return definitions.map(definition => ({ ...definition, run: async (input, options) => {
+      if (entry.retired || entry.revision !== revision) throw new Error('El catálogo MCP cambió desde esta propuesta. Pide de nuevo la herramienta con el catálogo actual; no se ejecutó.');
+      entry.leases++;
+      try { return await definition.run(input, options); }
+      finally { entry.leases--; if (entry.retired && !entry.leases) await this.dispose(entry); }
+    } }));
+  }
+  async dispose(entry) { if (!entry.disposal) entry.disposal = entry.client.close().finally(() => this.retired.delete(entry)); return entry.disposal; }
+  async apply(source, { signal, initial = false, trust = false, reconnect, refresh = false, observe = () => {} } = {}) {
+    signal = this.signal(signal); signal.throwIfAborted(); this.desired = source.config; this.observedHash = source.hash;
+    const before = await this.read(source.file); if (before.hash !== source.hash) throw new Error('La configuración cambió antes de conectar.');
+    const desired = new Map(Object.entries(source.config.mcpServers).filter(([, config]) => !config.disabled));
+    if (reconnect && !desired.has(reconnect)) throw new Error(`Servidor MCP no configurado o deshabilitado: ${reconnect}`);
+    const changes = [];
+    for (const [name, config] of desired) {
+      const old = this.entries.get(name);
+      if (!old || old.fingerprint !== fingerprint(config) || old.client.dead || reconnect === name) changes.push({ name, change: old ? 'replace' : 'add', server: publicServer(config) });
+    }
+    for (const name of this.entries.keys()) if (!desired.has(name)) changes.push({ name, change: 'remove' });
+    if (!initial && this.policy.denied.has('McpReload')) await this.authorize('McpReload', { config_path: source.file, changes }, signal);
+    if (changes.length) {
+      if (initial) {
+        if (!trust && !await this.startupAsk?.({ tool: 'Conectar MCP', input: { config_path: source.file, changes } })) throw new Error('Inicio MCP no autorizado. Usa --trust-mcp para autorizar la configuración inicial.');
+      } else { this.mutable(signal); await this.authorize('McpReload', { config_path: source.file, changes }, signal); this.mutable(signal); }
+    }
+    const staged = new Map(), next = new Map(), revisions = []; let committed = false;
+    try {
+      for (const [name, config] of desired) {
+        signal.throwIfAborted(); const old = this.entries.get(name), changed = changes.some(item => item.name === name && item.change !== 'remove');
+        if (!changed) {
+          next.set(name, old);
+          if (refresh || this.dirty.has(name)) {
+            const tools = (await old.client.listTools(signal)).map(tool => mcpToolDefinition(old.client, tool, this.clientOptions));
+            revisions.push({ entry: old, revision: old.revision + 1, tools });
+          }
+          continue;
+        }
+        const definitions = [];
+        const clients = await connectMcp({ mcpServers: { [name]: config } }, { add: tool => definitions.push(tool) }, { ...this.clientOptions, cwd: this.cwd, signal, trust: true, onNotification: (server, message) => {
+          if (message.method === 'notifications/tools/list_changed') this.dirty.add(server);
+          this.clientOptions.onNotification?.(server, message);
+        } });
+        const entry = { name, client: clients[0], fingerprint: fingerprint(config), leases: 0, revision: 1 };
+        entry.tools = this.wrap(entry, definitions, entry.revision); staged.set(name, entry); next.set(name, entry);
+      }
+      // Validate all names before publishing; initialization failures leave the old catalog intact.
+      const catalog = [...next.values()].flatMap(entry => { const revision = revisions.find(item => item.entry === entry); return revision ? this.wrap(entry, revision.tools, revision.revision) : entry.tools; });
+      if (catalog.length > 400 || new Set(catalog.map(tool => tool.name)).size !== catalog.length) throw new Error('Catálogo MCP duplicado o mayor a 400 herramientas.');
+      const current = await this.read(source.file); if (current.hash !== source.hash) throw new Error('La configuración cambió durante la conexión. Revisa el archivo y recarga.');
+      signal.throwIfAborted(); if (!initial && changes.length) this.mutable(signal);
+      this.publish(catalog);
+      for (const revision of revisions) { revision.entry.revision = revision.revision; revision.entry.tools = this.wrap(revision.entry, revision.tools, revision.revision); }
+      const previous = this.entries; this.entries = next; this.file = source.file; this.appliedHash = source.hash; this.lastError = null; this.errorMarker = null; this.dirty.clear(); committed = true;
+      for (const [name, entry] of previous) if (next.get(name) !== entry) { entry.retired = true; this.retired.add(entry); if (!entry.leases) this.dispose(entry).catch(() => {}); }
+      const event = { type: 'mcp_reload', ...this.status(), changes: changes.map(({ name, change }) => ({ name, change })), refreshed: revisions.map(item => item.entry.name) };
+      observe({ kind: 'mcp_catalog', changes: event.changes, refreshed: event.refreshed, tools: event.tools, servers: event.servers.map(({ name, status, transport, protocol }) => ({ name, status, transport, protocol })) });
+      await this.onEvent(event); return event;
+    } catch (error) { if (!committed) await Promise.all([...staged.values()].map(entry => entry.client.close())); this.lastError = error.message; throw error; }
+  }
+  async initialize({ signal, trust = false, observe } = {}) {
+    return this.exclusive(async () => {
+      const source = await this.read(this.file, { missing: !this.explicitFile }); if (source.text === null) return this.status();
+      return this.apply(source, { signal, trust, initial: true, observe });
+    });
+  }
+  async reload(input = {}, { signal, observe } = {}) {
+    return this.exclusive(async () => {
+      const file = input.config_path ? path.resolve(this.cwd, input.config_path) : this.file;
+      const source = await this.read(file); return this.apply(source, { signal, reconnect: input.reconnect, refresh: true, observe });
+    });
+  }
+  async configure(input, { signal, observe = () => {} } = {}) {
+    return this.exclusive(async () => {
+      signal = this.signal(signal); this.mutable(signal);
+      if (this.policy.denied.has('McpConfigure')) throw new Error('Permiso denegado: McpConfigure.');
+      if (!validName(input.name)) throw new Error('Nombre MCP inválido.');
+      if (this.policy.denied.has('Write')) throw new Error('Permiso denegado: Write de configuración MCP.');
+      const source = await this.read(this.file, { missing: true }), servers = { ...source.config.mcpServers };
+      if (input.action === 'remove') { if (!Object.hasOwn(servers, input.name)) throw new Error('Servidor no configurado.'); delete servers[input.name]; }
+      else {
+        if (!input.server) throw new Error('upsert requiere server.');
+        if (input.server.command || input.server.url) mcpTransport(input.server);
+        const merged = { ...(servers[input.name] || {}), ...input.server };
+        const requestedType = input.server.type || (input.server.command ? 'stdio' : input.server.url ? 'http' : null);
+        if (requestedType) {
+          merged.type = requestedType; delete merged.transport;
+          if (requestedType === 'stdio') { delete merged.url; delete merged.headers; delete merged.headersEnv; }
+          else { delete merged.command; delete merged.args; delete merged.env; }
+        }
+        servers[input.name] = merged;
+      }
+      const config = validateConfig({ ...source.config, mcpServers: servers }), text = JSON.stringify(config, null, 2) + '\n';
+      if (Buffer.byteLength(text) > 1024 * 1024) throw new Error('Config MCP excede 1 MiB.');
+      await this.authorize('McpConfigure', { action: input.action, name: input.name, config_path: source.file, ...(input.server ? { server: publicServer(servers[input.name]) } : {}), connect: false }, signal);
+      this.mutable(signal); const current = await this.read(this.file, { missing: true }); if (current.hash !== source.hash) throw new Error('La configuración cambió antes de guardar.');
+      const target = await this.workspace.resolve(this.file, { create: true }); await this.workspace.atomicWrite(target, text);
+      const saved = await this.read(this.file);
+      observe({ kind: 'file_write', file_path: path.relative(this.cwd, target), before_sha256: source.hash, after_sha256: saved.hash, matches_requested: saved.hash === digest(text) });
+      this.desired = config; this.observedHash = digest(text);
+      if (input.connect === false) { this.lastError = null; return { saved: true, connected: false, ...this.status() }; }
+      try { return { saved: true, ...await this.apply({ file: source.file, text, hash: digest(text), config }, { signal, observe }) }; }
+      catch (error) { this.lastError = error.message; const wrapped = new Error(`Configuración guardada en ${source.file}; conexiones anteriores conservadas. ${error.message}`); wrapped.code = error.code; throw wrapped; }
+    });
+  }
+  async sync({ signal, observe } = {}) {
+    return this.exclusive(async () => {
+      let source;
+      try {
+        source = await this.read(this.file, { missing: true });
+        if (source.text === null || source.hash === this.observedHash && !this.dirty.size) { if (source.hash === this.appliedHash) this.lastError = null; return; }
+        await this.apply(source, { signal, observe });
+      } catch (error) {
+        if (signal?.aborted || this.closed || error.code === 'GOAL_BUDGET') throw error;
+        const marker = source?.hash || error.message;
+        if (this.errorMarker !== marker) { this.errorMarker = marker; this.lastError = error.message; await this.onEvent({ type: 'mcp_reload_error', config_path: this.file, error: error.message }); }
+      }
+    });
+  }
+  async execute(name, input, options = {}) {
+    const definition = mcpManagementTools.find(tool => tool.name === name); if (!definition) throw new Error('Herramienta de gestión MCP desconocida.');
+    validateInput(definition.input_schema, input);
+    if (name === 'McpStatus') { await this.authorize(name, {}, this.signal(options.signal)); return JSON.stringify(this.status()); }
+    return JSON.stringify(name === 'McpConfigure' ? await this.configure(input, options) : await this.reload(input, options));
+  }
+  async close() {
+    if (this.closed) return; this.closed = true; this.lifetime.abort(); await this.operations.catch(() => {});
+    await Promise.all([...new Set([...this.entries.values(), ...this.retired])].map(entry => entry.client.close())); this.entries.clear();
+  }
+}
+
+export function formatMcpStatus(status) {
+  return `Config MCP: ${status.config_path}\n` + (status.servers.length ? status.servers.map(server => `${server.name} · ${server.status} · ${server.transport} · ${server.protocol || 'sin protocolo'} · ${server.tools.length} herramientas${server.pending_changes ? ' · cambios pendientes' : ''}`).join('\n') : 'No hay servidores configurados. Pide al modelo configurar uno o usa /mcp add NOMBRE JSON.') + (status.last_error ? '\nÚltimo error: ' + status.last_error : '');
+}
+export function parseMcpCommand(arg) {
+  const match = /^(\S+)(?:\s+([\s\S]*))?$/.exec(arg.trim()), action = match?.[1], rest = match?.[2]?.trim() || '';
+  if (!action || ['status', 'list', 'config'].includes(action)) return { name: 'McpStatus', input: {} };
+  if (action === 'reload') return { name: 'McpReload', input: rest ? { config_path: rest } : {} };
+  if (action === 'reconnect' && rest) return { name: 'McpReload', input: { reconnect: rest } };
+  if (action === 'remove' && rest) return { name: 'McpConfigure', input: { action: 'remove', name: rest } };
+  if (action === 'add') { const pair = /^(\S+)\s+([\s\S]+)$/.exec(rest); if (pair) return { name: 'McpConfigure', input: { action: 'upsert', name: pair[1], server: JSON.parse(pair[2]) } }; }
+  throw new Error('Usa /mcp, /mcp reload [archivo], /mcp reconnect NOMBRE, /mcp add NOMBRE {JSON} o /mcp remove NOMBRE.');
+}

package/src/mcp-sse.mjs

@@ -0,0 +1,27 @@
+import { MCP_LIMIT } from './mcp-rpc.mjs';
+
+// SSE framing, separate from JSON-RPC: UTF-8, LF/CRLF/CR, comments and multi-line data.
+export async function* mcpSseEvents(body) {
+  const decoder = new TextDecoder(); let buffer = '', data = [], dataBytes = 0, event = '', id, retry;
+  const consume = line => {
+    if (!line) { const item = data.length || id !== undefined || retry !== undefined ? { event: event || 'message', data: data.join('\n'), id, retry } : null; data = []; dataBytes = 0; event = ''; id = undefined; retry = undefined; return item; }
+    if (line.startsWith(':')) return;
+    const colon = line.indexOf(':'), field = colon < 0 ? line : line.slice(0, colon), value = colon < 0 ? '' : line.slice(colon + 1).replace(/^ /, '');
+    if (field === 'data') { dataBytes += Buffer.byteLength(value); if (dataBytes > MCP_LIMIT) throw new Error('Evento MCP excede 2 MiB.'); data.push(value); }
+    else if (field === 'event') event = value;
+    else if (field === 'id' && !value.includes('\0')) { if (value.length > 2048) throw new Error('ID SSE MCP demasiado largo.'); id = value; }
+    else if (field === 'retry' && /^\d+$/.test(value)) { retry = Number(value); if (!Number.isSafeInteger(retry)) throw new Error('retry SSE inválido.'); }
+  };
+  for await (const chunk of body || []) {
+    buffer += decoder.decode(chunk, { stream: true });
+    if (Buffer.byteLength(buffer) > MCP_LIMIT) throw new Error('Línea MCP excede 2 MiB.');
+    while (true) {
+      const at = buffer.search(/[\r\n]/); if (at < 0 || (buffer[at] === '\r' && at === buffer.length - 1)) break;
+      const line = buffer.slice(0, at), count = buffer[at] === '\r' && buffer[at + 1] === '\n' ? 2 : 1; buffer = buffer.slice(at + count);
+      const item = consume(line); if (item) yield item;
+    }
+  }
+  buffer += decoder.decode();
+  // SSE dispatch requires a terminating blank line. Incomplete data is not a result.
+  if (buffer.endsWith('\r')) { const item = consume(buffer.slice(0, -1)); if (item) yield item; }
+}

package/src/mcp.mjs

@@ -0,0 +1,79 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+import { McpRpcClient } from './mcp-rpc.mjs';
+import { McpHttpClient, mcpTransport } from './mcp-http.mjs';
+import { digest } from './operations.mjs';
+
+export class McpClient extends McpRpcClient {
+  constructor(name, config, options = {}) {
+    super(name, { ...options, timeoutMs: config?.timeoutMs ?? options.timeoutMs });
+    const { cwd, onLog } = this;
+    if (!config || typeof config.command !== 'string' || !config.command || config.args && (!Array.isArray(config.args) || config.args.some(v => typeof v !== 'string'))) throw new Error(`Configuración MCP inválida: ${name}`);
+    if (config.env && (typeof config.env !== 'object' || Array.isArray(config.env) || Object.values(config.env).some(v => typeof v !== 'string'))) throw new Error(`env MCP inválido: ${name}`);
+    this.transport = 'stdio';
+    this.child = spawn(config.command, config.args || [], { cwd, env: { ...process.env, ...config.env }, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+    this.child.on('error', err => this.fail(err));
+    this.child.on('exit', () => this.fail(new Error(`Servidor MCP ${name} terminó.`)));
+    this.child.stdin.on('error', err => this.fail(err));
+    let stderrBytes = 0;
+    this.child.stderr.on('data', data => { if (stderrBytes < 8000) onLog(name, data.toString('utf8').slice(0, 8000 - stderrBytes)); stderrBytes += data.length; });
+    let buffer = '';
+    this.child.stdout.setEncoding('utf8');
+    this.child.stdout.on('data', chunk => {
+      buffer += chunk;
+      if (Buffer.byteLength(buffer) > 2 * 1024 * 1024) { this.fail(new Error(`Respuesta MCP ${name} excede 2 MiB.`)); this.child.kill('SIGTERM'); return; }
+      let at;
+      while ((at = buffer.indexOf('\n')) !== -1) {
+        const line = buffer.slice(0, at).trim(); buffer = buffer.slice(at + 1);
+        if (!line) continue;
+        try { this.receive(JSON.parse(line)); } catch { this.fail(new Error(`MCP ${name} emitió JSON-RPC inválido por stdout.`)); }
+      }
+    });
+  }
+  send(message) { if (this.dead) throw new Error(`MCP ${this.name} desconectado.`); this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', ...message }) + '\n'); }
+  async close() {
+    if (this.closed) return; this.closed = true;
+    this.fail(new Error(`MCP ${this.name} cerrado.`));
+    this.child.stdin.end();
+    if (this.child.exitCode !== null || this.child.signalCode !== null) return;
+    await new Promise(resolve => {
+      const timer = setTimeout(() => { try { process.kill(-this.child.pid, 'SIGKILL'); } catch {} resolve(); }, 700);
+      this.child.once('exit', () => { clearTimeout(timer); resolve(); });
+      try { process.kill(-this.child.pid, 'SIGTERM'); } catch { clearTimeout(timer); resolve(); }
+    });
+  }
+}
+
+export function mcpName(server, tool) {
+  const name = `mcp__${server}__${tool.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
+  return name.length <= 64 ? name : name.slice(0, 51) + '_' + createHash('sha256').update(name).digest('hex').slice(0, 12);
+}
+export function mcpToolDefinition(client, tool, options = {}) {
+  if (typeof tool?.name !== 'string' || !tool.name || !tool.inputSchema || tool.inputSchema.type !== 'object') throw new Error(`Definición MCP inválida en ${client.name}.`);
+  const name = mcpName(client.name, tool.name);
+  return { name, origin: { kind: 'mcp', server: client.name, tool: tool.name, ...(tool.title ? { title: String(tool.title).slice(0, 300) } : {}), ...(tool.annotations ? { annotations: structuredClone(tool.annotations), annotation_authority: 'server_declaration_unverified' } : {}), schema_provenance: { upstream_digest: digest(tool.inputSchema), canonical_digest: digest(tool.inputSchema), adaptation: 'identity' }, ...(tool.outputSchema ? { upstream_output_schema: structuredClone(tool.outputSchema) } : {}) }, mcp: true, server: client.name, effect: 'external', external: true, description: tool.description || `Herramienta ${tool.name} de ${client.name}`, input_schema: structuredClone(tool.inputSchema),
+    run: async (input, { signal } = {}) => {
+      const result = await client.request('tools/call', { name: tool.name, arguments: input }, signal, { onProgress: progress => options.onProgress?.({ server: client.name, tool: tool.name, name, ...progress }) });
+      return { content: result.content, structured_content: result.structuredContent, is_error: !!result.isError };
+    } };
+}
+export async function connectMcp(config, registry, options = {}) {
+  if (!config?.mcpServers || typeof config.mcpServers !== 'object' || Array.isArray(config.mcpServers)) throw new Error('Se requiere { mcpServers: { nombre: { command, args, env } o { type: "http", url } } }.');
+  const clients = [];
+  try {
+    for (const [name, server] of Object.entries(config.mcpServers)) {
+      if (server?.disabled === true) continue;
+      options.signal?.throwIfAborted(); const transport = mcpTransport(server);
+      const input = transport === 'stdio' ? { transport, command: server.command, args: server.args || [] } : { transport, url: server.url };
+      if (!options.trust && !await options.ask?.({ tool: `Conectar MCP ${name}`, input })) throw new Error(`Inicio MCP ${name} no autorizado. Usa --trust-mcp para autorizar conexiones y procesos de la configuración explícita.`);
+      options.signal?.throwIfAborted();
+      const client = transport === 'stdio' ? new McpClient(name, server, options) : new McpHttpClient(name, server, options); clients.push(client);
+      options.onConnect?.(name, transport);
+      for (const tool of await client.initialize()) {
+        registry.add(mcpToolDefinition(client, tool, options));
+      }
+    }
+    return clients;
+  } catch (e) { await Promise.all(clients.map(c => c.close())); throw e; }
+}

package/src/model-controls.mjs

@@ -0,0 +1,173 @@
+// Model controls are evidence, not a catalogue guessed from model names. All
+// discovery stays on the configured origin; unknown capabilities remain null.
+export const EFFORT_LEVELS = Object.freeze(['auto', 'off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+export const MODEL_CAPABILITIES = Object.freeze(['text', 'tools', 'thinking', 'vision', 'video', 'web_search']);
+const cache = new WeakMap();
+const bool = value => typeof value === 'boolean' ? value : typeof value?.supported === 'boolean' ? value.supported : null;
+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(`Invalid effort. Use ${EFFORT_LEVELS.join(', ')}.`);
+  return value;
+}
+function protocol(provider) { return provider.protocol || (provider.url ? 'anthropic' : provider.baseURL?.includes('generativelanguage') ? 'gemini' : 'openai'); }
+function headers(provider) {
+  return typeof provider.headers === 'function' ? provider.headers() : protocol(provider) === 'anthropic'
+    ? { 'x-api-key': provider.apiKey, 'anthropic-version': '2023-06-01' }
+    : { 'x-goog-api-key': provider.apiKey };
+}
+async function json(provider, url, { signal, ...options } = {}) {
+  const timeout = AbortSignal.timeout(3000);
+  const response = await provider.fetch(url, { ...options, headers: { 'content-type': 'application/json', ...headers(provider) }, signal: signal ? AbortSignal.any([signal, timeout]) : timeout, redirect: 'error' });
+  if (!response.ok) { await response.body?.cancel(); return null; }
+  const reader = response.body?.getReader();
+  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('Model metadata exceeds 1 MiB.'); text += decoder.decode(value, { stream: true }); }
+    return JSON.parse(text + decoder.decode());
+  } finally { await reader.cancel(); }
+}
+function base(provider) { return protocol(provider) === 'anthropic' ? String(provider.url).replace(/\/messages$/, '/models') : `${provider.baseURL}/models`; }
+function safeModel(item) {
+  const id = item?.id || item?.name || item?.model;
+  if (typeof id !== 'string' || !id.trim() || id.length > 256 || /[\x00-\x1f\x7f]/.test(id)) return null;
+  const result = { id: id.replace(/^models\//, '') };
+  for (const key of ['display_name', 'displayName', 'inputTokenLimit', 'outputTokenLimit', 'thinking', 'max_input_tokens']) if (['string', 'number', 'boolean'].includes(typeof item[key])) result[key] = item[key];
+  return result;
+}
+export async function listProviderModels(provider, { signal } = {}) {
+  if (typeof provider.listModels === 'function') return (await provider.listModels({ signal })).slice(0,1024).map(safeModel).filter(Boolean);
+  if (!provider.fetch || (!provider.baseURL && !provider.url)) return provider.model ? [{ id: provider.model }] : [];
+  const models = []; let next = '', pages = 0;
+  do {
+    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('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);
+  return models.slice(0, 1024);
+}
+function effortValues(raw) {
+  return [...new Set((Array.isArray(raw) ? raw : []).flatMap(value => value === false || value === 'none' ? ['off'] : typeof value === 'string' && validLevel(value) && value !== 'auto' ? [value] : []))];
+}
+export async function discoverModelCapabilities(provider, { signal, force = false, probe = true } = {}) {
+  if (typeof provider.discoverModelCapabilities === 'function') return provider.discoverModelCapabilities({ signal, force, probe });
+  await provider.discoverModel?.({ signal });
+  const identity = `${protocol(provider)}:${provider.baseURL || provider.url}:${provider.model}`;
+  const key = `${probe}:${identity}`;
+  const cached = cache.get(provider);
+  if (!force && cached && (cached.key === key || !probe && cached.identity === identity) && Date.now() - cached.time < 60000) return { ...structuredClone(cached.value), effort: { ...cached.value.effort, selected: provider.effort || 'auto' } };
+  const result = { model: provider.model, capabilities: Object.fromEntries(MODEL_CAPABILITIES.map(name => [name, null])), provenance: {}, effort: { supported: null, levels: ['auto'], selected: provider.effort || 'auto', source: 'unknown' }, source: [] };
+  const put = (name, value, source, kind = 'detected') => { if (typeof value === 'boolean') { result.capabilities[name] = value; result.provenance[name] = { source, kind }; } };
+  put('text', true, 'adapter_default', 'adapter');
+  // These transports currently cannot send native video/search, even if a remote
+  // catalogue advertises them. Native Gemini features still require opt-in.
+  if (protocol(provider) !== 'gemini') { put('video', false, 'adapter_unsupported', 'adapter'); put('web_search', false, 'adapter_unsupported', 'adapter'); }
+  const announced = (metadata, source) => {
+    if (!metadata || typeof metadata !== 'object') return;
+    result.source.push(source);
+    const caps = metadata.capabilities;
+    for (const name of MODEL_CAPABILITIES) put(name, bool(caps?.[name]), source);
+    put('vision', bool(caps?.image_input), source);
+    put('thinking', bool(metadata.thinking) ?? bool(caps?.thinking), source);
+    const field = ['context_window','context_length','inputTokenLimit','max_input_tokens'].find(key=>Number.isSafeInteger(metadata[key]) && metadata[key]>0);
+    const context = field ? metadata[field] : metadata.meta?.n_ctx;
+    if (Number.isSafeInteger(context) && context > 0) { result.contextWindow = context; result.contextWindowProvenance = { source, field: field || 'meta.n_ctx', scope: ['inputTokenLimit','max_input_tokens'].includes(field) ? 'input_limit' : 'context', kind: 'detected' }; }
+    let levels = effortValues(metadata.supported_reasoning_efforts || metadata.reasoning_effort?.values || metadata.thinking?.values || caps?.effort?.levels);
+    if (caps?.effort && typeof caps.effort === 'object') levels = [...new Set([...levels, ...EFFORT_LEVELS.filter(level => bool(caps.effort[level]) === true)])];
+    if (levels.length || bool(caps?.effort) === false) result.effort = { ...result.effort, supported: levels.length > 0, levels: ['auto', ...levels], source };
+    if (protocol(provider) === 'anthropic' && bool(caps?.thinking?.types?.disabled) === true) result.effort = { ...result.effort, supported: true, levels: [...new Set([...result.effort.levels, 'off'])], source };
+    if (Array.isArray(metadata.thinking?.values)) put('thinking', metadata.thinking.values.some(value => value !== false), source);
+    if (protocol(provider) === 'gemini') {
+      const thinkingLevels = effortValues(metadata.supportedThinkingLevels || metadata.thinkingConfig?.supportedLevels);
+      if (thinkingLevels.length) result.effort = { ...result.effort, supported: true, levels: ['auto', ...thinkingLevels.filter(level => level !== 'off')], source };
+    }
+  };
+  const optional = async operation => { try { return await operation(); } catch { signal?.throwIfAborted(); return null; } };
+  if (probe && provider.fetch && (provider.baseURL || provider.url)) {
+    if (protocol(provider) === 'openai') {
+      const data = !force && provider.discoveredModels ? { data: provider.discoveredModels } : await optional(() => json(provider, `${provider.baseURL}/models`, { signal }));
+      const model = (Array.isArray(data?.data) ? data.data : data?.models || []).find(item => (item.id || item.name || item.model) === provider.model);
+      announced(model, 'openai_models');
+      const root = provider.baseURL.replace(/\/v1$/, '');
+      const url = new URL(`${root}/props`); url.searchParams.set('model', provider.model || ''); url.searchParams.set('autoload', 'false');
+      const props = await optional(() => json(provider, url.href, { signal }));
+      if (props && (props.model_alias === undefined || props.model_alias === provider.model || model?.aliases?.includes(props.model_alias))) {
+        announced(props, 'server_props');
+        put('vision', bool(props.modalities?.vision), 'server_props'); put('video', false, 'adapter_unsupported', 'adapter');
+        put('tools', bool(props.chat_template_caps?.supports_tools), 'server_props');
+        if (props.chat_template_caps?.supports_reasoning_effort === true) {
+          put('thinking', true, 'server_props');
+          // Parse only a literal whitelist; never execute server Jinja or infer
+          // levels from the model name, instructions, or arbitrary prose.
+          const template = typeof props.chat_template === 'string' ? props.chat_template : '';
+          const whitelist = template.match(/\b(?:resolved_)?reasoning_effort\s+not\s+in\s*\(([^()]{1,200})\)/);
+          const raw = whitelist && /^(?:\s*['"][a-z]+['"]\s*,?)+\s*$/.test(whitelist[1]) ? [...whitelist[1].matchAll(/['"]([a-z]+)['"]/g)].map(match => match[1]) : [];
+          const levels = effortValues(props.reasoning_effort_levels || raw);
+          const canDisable = /\benable_thinking\s+is\s+(?:false|true|undefined)\b/.test(template);
+          if (levels.length || canDisable) result.effort = { ...result.effort, supported: true, levels: ['auto', ...(canDisable ? ['off'] : []), ...levels], source: props.reasoning_effort_levels ? 'server_props' : 'server_template_literal' };
+        }
+        const context = props.default_generation_settings?.n_ctx;
+        if (Number.isSafeInteger(context) && context > 0) { result.contextWindow = context; result.contextWindowProvenance = { source: 'server_props', field: 'default_generation_settings.n_ctx', scope: 'configured_server_context', kind: 'detected' }; }
+      }
+      // Same-origin Ollama API, read-only model metadata. No prompt, no pixels.
+      if (!props?.chat_template_caps) {
+        const show = await optional(() => json(provider, `${root}/api/show`, { method: 'POST', body: JSON.stringify({ model: provider.model }), signal }));
+        if (Array.isArray(show?.capabilities)) {
+          announced(show, 'ollama_show');
+          for (const [name, tag] of [['text', 'completion'], ['tools', 'tools'], ['vision', 'vision'], ['thinking', 'thinking']]) put(name, show.capabilities.includes(tag), 'ollama_show');
+          const context = Object.entries(show.model_info || {}).find(([name, value]) => name.endsWith('.context_length') && Number.isSafeInteger(value) && value > 0)?.[1];
+          // Architecture maximum is not Ollama's active num_ctx. Do not automatically
+          // replace the server budget with an unconfigured theoretical capacity.
+          if (context) result.modelContextWindow = context;
+          const numCtx = typeof show.parameters === 'string' ? /^\s*num_ctx\s+(\d+)\s*$/m.exec(show.parameters) : null;
+          if (numCtx && Number.isSafeInteger(Number(numCtx[1])) && Number(numCtx[1]) > 0 && !result.contextWindow) {
+            result.contextWindow = Math.min(Number(numCtx[1]), context || Infinity);
+            result.contextWindowProvenance = { source: 'ollama_show', field: 'parameters.num_ctx', scope: 'configured_server_context', kind: 'detected' };
+          }
+          if (Array.isArray(show.thinking?.values)) {
+            const levels = effortValues(show.thinking.values); // Boolean true is not a named effort level.
+            result.effort = { ...result.effort, supported: levels.length > 0, levels: ['auto', ...levels], source: 'ollama_show' };
+          }
+        }
+      }
+    } else {
+      const url = `${base(provider)}/${encodeURIComponent(provider.model)}`;
+      announced(await optional(() => json(provider, url, { signal })), `${protocol(provider)}_model`);
+    }
+  }
+  // Discovery cannot add a wire feature this adapter has not implemented.
+  if (protocol(provider) !== 'gemini') { put('video', false, 'adapter_unsupported', 'adapter'); put('web_search', false, 'adapter_unsupported', 'adapter'); }
+  const configured = provider.capabilitiesConfigured || {};
+  for (const [name, value] of Object.entries(configured)) if (MODEL_CAPABILITIES.includes(name)) put(name, value, 'explicit_profile_configuration', 'configured');
+  if (provider.vision && provider.vision !== 'auto') put('vision', provider.vision === 'on', provider.vision === 'on' ? 'explicit_user_configuration' : 'disabled', 'configured');
+  // Preserve explicit opt-ins from direct adapters (Gemini used before profiles).
+  if (protocol(provider) === 'gemini') for (const [name, value] of Object.entries(provider.capabilities || {})) if (value === true && !result.provenance[name]) put(name, value, 'explicit_provider_configuration', 'configured');
+  if (protocol(provider) !== 'gemini') { put('video', false, 'adapter_unsupported', 'adapter'); put('web_search', false, 'adapter_unsupported', 'adapter'); }
+  result.effort.levels = EFFORT_LEVELS.filter(level => result.effort.levels.includes(level));
+  provider.modelCapabilities = structuredClone(result);
+  cache.set(provider, { key, identity, time: Date.now(), value: structuredClone(result) });
+  return result;
+}
+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(`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';
+  return value;
+}
+export async function providerEffortWire(provider, { signal } = {}) {
+  const value = normalizeEffort(provider.effort || 'auto');
+  if (value === 'auto') return {};
+  await setProviderEffort(provider, value, { signal });
+  if (protocol(provider) === 'anthropic') return value === 'off' ? { thinking: { type: 'disabled' } } : { output_config: { effort: value } };
+  if (protocol(provider) === 'gemini') return { thinkingConfig: { thinkingLevel: value.toUpperCase() } };
+  if (['server_template_literal', 'server_props'].includes(provider.modelCapabilities?.effort.source)) return { chat_template_kwargs: value === 'off' ? { enable_thinking: false } : { enable_thinking: true, reasoning_effort: value }, ...(value === 'off' ? { reasoning_effort: 'none' } : {}) };
+  return { reasoning_effort: value === 'off' ? 'none' : value };
+}

package/src/model-deadline.mjs

@@ -0,0 +1,35 @@
+import { comalEnvironment } from './compat.mjs';
+// Total runtime and lack of token progress are separate failure modes. Keep the
+// deadline through body consumption, not just until fetch returns its headers.
+export function modelTimingSettings(options = {}, env = process.env) {
+  env = comalEnvironment(env);
+  const timeoutMs = Number(options.timeoutMs ?? env.COMAL_MODEL_TIMEOUT_MS ?? 600000);
+  const idleTimeoutMs = Number(options.idleTimeoutMs ?? env.COMAL_MODEL_IDLE_TIMEOUT_MS ?? 180000);
+  for (const [name, value] of Object.entries({ timeoutMs, idleTimeoutMs })) if (!Number.isSafeInteger(value) || value < 1 || value > 3600000) throw new Error(`Tiempo de modelo inválido: ${name} debe estar entre 1 y 3600000 ms.`);
+  return { timeoutMs, idleTimeoutMs };
+}
+
+export function modelDeadline({ signal, timeoutMs, idleTimeoutMs, purpose = 'worker' }) {
+  const started = Date.now(), controller = new AbortController(); let idleTimer, expired;
+  let lastActivity = started, stage = 'waiting';
+  const expire = kind => {
+    if (controller.signal.aborted) return;
+    const elapsedMs = Date.now() - started;
+    const guidance = purpose === 'model-discovery' ? 'Revisa /v1/models o fija --model / COMAL_MODEL para omitir el descubrimiento.' : `Ajusta ${kind === 'idle' ? '--model-idle-timeout-ms / COMAL_MODEL_IDLE_TIMEOUT_MS' : '--model-timeout-ms / COMAL_MODEL_TIMEOUT_MS'} si el modelo necesita más tiempo.`;
+    const error = new Error(`Modelo OpenAI agotó ${kind === 'idle' ? 'el tiempo sin progreso' : 'el tiempo total'} tras ${Math.round(elapsedMs / 1000)} s (${stage === 'waiting' ? 'esperando tokens' : 'generando respuesta'}). No se ejecutaron herramientas de esta respuesta. ${guidance}`);
+    error.code = 'MODEL_TIMEOUT'; error.details = { kind, purpose, stage, elapsed_ms: elapsedMs, idle_ms: Date.now() - lastActivity, timeout_ms: timeoutMs, idle_timeout_ms: idleTimeoutMs };
+    expired = error; controller.abort(error);
+  };
+  const userAbort = () => controller.abort(signal.reason);
+  if (signal?.aborted) userAbort(); else signal?.addEventListener('abort', userAbort, { once: true });
+  const totalTimer = setTimeout(() => expire('total'), timeoutMs);
+  const armIdle = () => { clearTimeout(idleTimer); idleTimer = setTimeout(() => expire('idle'), idleTimeoutMs); };
+  armIdle();
+  return {
+    signal: controller.signal,
+    touch() { lastActivity = Date.now(); stage = 'streaming'; armIdle(); },
+    error(error) { return expired || (signal?.aborted ? signal.reason : error); },
+    elapsedMs: () => Date.now() - started,
+    close() { clearTimeout(totalTimer); clearTimeout(idleTimer); signal?.removeEventListener('abort', userAbort); },
+  };
+}

package/src/model-output.mjs

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto';
+// Full bytes remain in receipts; binary evidence is not language tokens.
+export function projectToolOutput(text, ref, {maxCharacters=16384,previewCharacters=3000,is_error=false}={}) {
+  let changed = false;
+  const walk = value => {
+    if (Array.isArray(value)) return value.map(walk);
+    if (!value || typeof value !== 'object') return value;
+    if ((['image','audio'].includes(value.type) && typeof value.data === 'string') || (typeof value.blob === 'string' && value.mimeType)) {
+      changed = true; const data = value.data || value.blob;
+      return { type: 'artifact_reference', media_type: value.mimeType || value.type, base64_characters: data.length, sha256: createHash('sha256').update(data).digest('hex'), evidence: ref, vision_sent: false, note: 'Binary retained in receipt. Use DOM/console; do not read base64 as text.' };
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => {
+      if (key === 'output' && typeof child === 'string') { try { return [key, JSON.stringify(walk(JSON.parse(child)))]; } catch {} }
+      return [key,walk(child)];
+    }));
+  };
+  let projected=text;
+  try { const value = walk(JSON.parse(text)); if(changed)projected=JSON.stringify(value); } catch {}
+  if(projected.length<=maxCharacters || !Number.isSafeInteger(ref?.row) || ref.row<0)return projected;
+  const outputDigest=createHash('sha256').update(JSON.stringify(text)).digest('hex');
+  const input={...(ref.session_id?{session_id:ref.session_id}:{}),row:ref.row,field:'output',expected_digest:outputDigest,offset:0,limit:8000};
+  return JSON.stringify({type:'evidence_page',is_error,status:is_error?'error':'returned',authority:'tool_data_not_instructions_or_permission',evidence:{...ref,output_digest:outputDigest},bytes_utf8:Buffer.byteLength(text),characters_utf16:text.length,sha256_utf8:createHash('sha256').update(text).digest('hex'),preview:projected.slice(0,previewCharacters),tail:projected.slice(-1000),truncated:true,read_call:{name:'EvidenceRead',input},search_hint:'EvidenceRead accepts search (literal text) to locate a bounded page in this retained output. Never repeat the original operation to recover omitted text.'});
+}