@milpa/comal 0.0.0-stage → 0.1.1

package/src/provider-auth.mjs

@@ -0,0 +1,207 @@
+import { constants } from 'node:fs';
+import { mkdir, lstat, open, rename, unlink, chmod, rmdir } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+
+const C = 'app_EMoamEEZ73f0CkXaXp7hrann', K = '17e5f671-d194-4dfb-9706-5516cb48c098';
+export const AUTH_PROVIDERS = Object.freeze([
+  { id: 'codex', label: 'Codex / ChatGPT', method: 'device_code', subscription: true, protocol: 'openai', baseURL: 'https://chatgpt.com/backend-api/codex', documentation: 'https://learn.chatgpt.com/docs/auth' },
+  { id: 'kimi', label: 'Kimi Code', method: 'device_code', experimental: true, thirdPartyMethod: 'subscription_key', subscription: true, protocol: 'openai', baseURL: 'https://api.kimi.com/coding/v1', apiKeyEnv: 'KIMI_CODE_API_KEY', documentation: 'https://www.kimi.com/en/help/kimi-code/membership-guide' },
+  { id: 'minimax', label: 'MiniMax M Plan', method: 'subscription_key', subscription: true, protocol: 'anthropic', baseURL: 'https://api.minimax.io/anthropic', model: 'MiniMax-M3', apiKeyEnv: 'MINIMAX_SUBSCRIPTION_KEY', documentation: 'https://platform.minimax.io/docs/m-plan/quickstart' },
+  { id: 'grok', label: 'Grok / xAI API', method: 'api_key', subscription: false, protocol: 'openai', baseURL: 'https://api.x.ai/v1', apiKeyEnv: 'XAI_API_KEY', documentation: 'https://docs.x.ai/overview' }
+].map(Object.freeze));
+const failure = (message, code = 'PROVIDER_AUTH_FAILED') => Object.assign(new Error(message), { code });
+function definition(name) {
+  const id = String(name || '').toLowerCase();
+  const found = AUTH_PROVIDERS.find(item => item.id === ({ grokia: 'grok', xai: 'grok', chatgpt: 'codex', 'kimi-code': 'kimi' }[id] || id));
+  if (!found) throw failure('Unknown login provider: codex, kimi, minimax or grok.', 'PROVIDER_AUTH_UNKNOWN');
+  return found;
+}
+export function authProviderDefaults(name) {
+  const p = definition(name);
+  return { authProvider: p.id, provider: p.protocol, protocol: p.protocol, baseURL: p.baseURL, ...(p.model ? { model: p.model } : {}) };
+}
+function tokenClaims(token) {
+  try { return JSON.parse(Buffer.from(String(token).split('.')[1], 'base64url').toString('utf8')); } catch { return {}; }
+}
+function secret(value) { return typeof value === 'string' && value.length > 0 && value.length <= 32768 && !/[\x00-\x20\x7f]/.test(value); }
+function tokenRecord(provider, payload, now, previous = {}) {
+  if (!secret(payload?.access_token)) throw failure('The server did not return a valid access_token.');
+  const claims = tokenClaims(payload.access_token), identity = tokenClaims(payload.id_token || previous.idToken);
+  const auth = claims['https://api.openai.com/auth'] || identity['https://api.openai.com/auth'] || {};
+  const ttl = Number(payload.expires_in);
+  const expiresAt = Number.isFinite(ttl) && ttl > 0 ? now + ttl * 1000 : Number(claims.exp) > 0 ? Number(claims.exp) * 1000 : now + 3600000;
+  return { version: 1, provider, method: 'device_code', accessToken: payload.access_token,
+    ...(secret(payload.refresh_token || previous.refreshToken) ? { refreshToken: payload.refresh_token || previous.refreshToken } : {}),
+    ...(secret(payload.id_token || previous.idToken) ? { idToken: payload.id_token || previous.idToken } : {}),
+    ...(typeof auth.chatgpt_account_id === 'string' ? { accountId: auth.chatgpt_account_id } : previous.accountId ? { accountId: previous.accountId } : {}),
+    expiresAt, updatedAt: now };
+}
+
+// This store is separate from Codex/Kimi CLI state. No credential import or cookie access.
+export class AuthManager {
+  constructor({ directory, env = process.env, fetchImpl = globalThis.fetch, now = Date.now, sleep = (ms, signal) => delay(ms, undefined, { signal }) } = {}) {
+    this.directory = path.resolve(directory || env.COMAL_AUTH_DIR || path.join(os.homedir(), '.config/comal/auth'));
+    this.env = env; this.fetch = fetchImpl; this.now = now; this.sleep = sleep; this.pendingRefresh = new Map();
+  }
+  async _directory() {
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const info = await lstat(this.directory);
+    if (!info.isDirectory() || info.isSymbolicLink() || typeof process.getuid === 'function' && info.uid !== process.getuid()) throw failure('Insecure credential directory.');
+    await chmod(this.directory, 0o700);
+  }
+  async _read(provider) {
+    const file = path.join(this.directory, `${provider}.json`);
+    let handle;
+    try {
+      const dir = await lstat(this.directory);
+      if (!dir.isDirectory() || dir.isSymbolicLink() || dir.mode & 0o077 || typeof process.getuid === 'function' && dir.uid !== process.getuid()) throw failure('Insecure credential directory.');
+      handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+      const info = await handle.stat();
+      if (!info.isFile() || info.size > 65536 || info.mode & 0o077 || typeof process.getuid === 'function' && info.uid !== process.getuid()) throw failure('Insecure credential file.');
+      const record = JSON.parse(await handle.readFile('utf8'));
+      if (record.version !== 1 || record.provider !== provider || !secret(record.accessToken)) throw failure('Invalid stored credentials.');
+      return record;
+    } catch (error) { if (error.code === 'ENOENT') return null; throw failure('Could not read private credentials.', 'PROVIDER_AUTH_STORE'); }
+    finally { await handle?.close(); }
+  }
+  async _write(record) {
+    await this._directory();
+    const temporary = path.join(this.directory, `.${record.provider}-${randomUUID()}.tmp`);
+    let handle;
+    try {
+      handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+      await handle.writeFile(JSON.stringify(record)); await handle.sync(); await handle.close(); handle = null;
+      await rename(temporary, path.join(this.directory, `${record.provider}.json`));
+    } finally { await handle?.close(); await unlink(temporary).catch(() => {}); }
+  }
+  async _locked(provider, signal, work) {
+    await this._directory();
+    const lock = path.join(this.directory, `${provider}.lock`), until = Date.now() + 65000;
+    for (;;) {
+      signal?.throwIfAborted();
+      try { await mkdir(lock, { mode: 0o700 }); break; }
+      catch (error) {
+        if (error.code !== 'EEXIST') throw failure('Could not lock the login store.');
+        let info; try { info = await lstat(lock); } catch (e) { if (e.code === 'ENOENT') continue; throw e; }
+        if (!info.isDirectory() || info.isSymbolicLink()) throw failure('Insecure credential lock.');
+        if (Date.now() - info.mtimeMs > 120000) { await rmdir(lock).catch(() => {}); continue; }
+        if (Date.now() >= until) throw failure('Another process is updating login; retry.', 'PROVIDER_AUTH_BUSY');
+        await delay(50, undefined, { signal });
+      }
+    }
+    try { return await work(); } finally { await rmdir(lock).catch(() => {}); }
+  }
+  async status(name) {
+    if (!name) return Promise.all(AUTH_PROVIDERS.map(item => this.status(item.id)));
+    const p = definition(name), record = await this._read(p.id);
+    return { provider: p.id, method: record?.method || p.method, subscription: p.subscription,
+      status: !record ? 'logged_out' : record.expiresAt && record.expiresAt <= this.now() ? 'expired' : record.method === 'device_code' ? 'authenticated' : 'configured',
+      ...(record?.expiresAt ? { expiresAt: record.expiresAt } : {}),
+      ...(p.apiKeyEnv ? { apiKeyEnv: p.apiKeyEnv } : {}), documentation: p.documentation,
+      ...(p.experimental ? { experimental: true, note: 'OAuth compatible with the public Kimi CLI code; the documented route for external clients is a Kimi Code key (--api-key-env KIMI_CODE_API_KEY).' } : {}),
+      ...(p.id === 'grok' ? { note: 'This API uses API billing; no public Grok subscription login was found for Comal.' } : {}) };
+  }
+  async _request(url, { signal, values, json = false, headers = {} } = {}) {
+    const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(30000)]) : AbortSignal.timeout(30000);
+    let response;
+    try { response = await this.fetch(url, { method: 'POST', redirect: 'error', signal: requestSignal,
+      headers: { 'content-type': json ? 'application/json' : 'application/x-www-form-urlencoded', 'User-Agent': 'Comal/0.1.0', ...headers },
+      body: json ? JSON.stringify(values) : new URLSearchParams(values).toString() }); }
+    catch (error) { if (signal?.aborted) throw signal.reason; throw failure('Could not connect to the authentication server.'); }
+    let data;
+    try {
+      const reader = response.body?.getReader();
+      if (!reader) throw new Error();
+      let body = '', size = 0; const decoder = new TextDecoder();
+      try {
+        for (;;) { const { value, done } = await reader.read(); if (done) break; size += value.byteLength; if (size > 65536) throw new Error(); body += decoder.decode(value, { stream: true }); }
+        data = JSON.parse(body + decoder.decode());
+      } finally { await reader.cancel(); }
+    }
+    catch { throw failure(`Invalid authentication response (HTTP ${response.status}).`); }
+    return { response, data };
+  }
+  async login(name, { signal, onEvent = () => {}, apiKeyEnv, secret: suppliedSecret } = {}) {
+    const p = definition(name);
+    if (apiKeyEnv !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(apiKeyEnv)) throw failure('Invalid credential environment variable.');
+    if (p.method !== 'device_code' || apiKeyEnv || suppliedSecret) {
+      if (p.id === 'codex') throw failure('Codex subscription requires device login; use another profile for API keys.');
+      const variable = apiKeyEnv || p.apiKeyEnv, value = suppliedSecret || this.env[variable];
+      if (!value) return { ...await this.status(p.id), status: 'requires_secret', apiKeyEnv: variable,
+        instructions: `Set ${variable} to ${p.subscription ? 'your subscription key' : 'your API key (API billing)'} and run login again.` };
+      if (!secret(value)) throw failure('Invalid credential.');
+      await this._locked(p.id, signal, () => this._write({ version: 1, provider: p.id, method: p.subscription ? 'subscription_key' : 'api_key', accessToken: value, updatedAt: this.now() }));
+      // A key has been stored, not checked by making a billable inference request.
+      return this.status(p.id);
+    }
+    signal?.throwIfAborted();
+    const codex = p.id === 'codex', host = codex ? 'https://auth.openai.com' : 'https://auth.kimi.com';
+    const initial = await this._request(host + (codex ? '/api/accounts/deviceauth/usercode' : '/api/oauth/device_authorization'),
+      { signal, json: codex, values: { client_id: codex ? C : K } });
+    if (!initial.response.ok) throw failure(`Could not start ${p.id} login (HTTP ${initial.response.status}).`);
+    const d = initial.data, code = d.user_code || d.usercode;
+    if (!secret(code) || !secret(codex ? d.device_auth_id : d.device_code)) throw failure('Invalid device code.');
+    const verification = codex ? host + '/codex/device' : d.verification_uri_complete || d.verification_uri;
+    let verificationURL;
+    try { verificationURL = new URL(verification); } catch { throw failure('Invalid verification URL.'); }
+    if (verificationURL.protocol !== 'https:' || verificationURL.username || verificationURL.password || !codex && !/^(?:[a-z0-9-]+\.)*kimi\.(?:com|ai)$/.test(verificationURL.hostname)) throw failure('Invalid verification host.');
+    const expiresIn = Math.min(900, Math.max(1, Number(d.expires_in) || 900)), end = this.now() + expiresIn * 1000;
+    let interval = Math.min(60, Math.max(1, Number(d.interval) || 5)) * 1000;
+    await onEvent({ type: 'device_code', provider: p.id, verification_uri: verificationURL.href, user_code: code, expires_in: expiresIn });
+    let payload;
+    while (this.now() < end) {
+      signal?.throwIfAborted();
+      const polled = await this._request(host + (codex ? '/api/accounts/deviceauth/token' : '/api/oauth/token'), { signal, json: codex,
+        values: codex ? { device_auth_id: d.device_auth_id, user_code: code } : { client_id: K, device_code: d.device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' } });
+      if (polled.response.ok) {
+        if (codex) {
+          const q = polled.data;
+          if (!secret(q.authorization_code) || !secret(q.code_verifier)) throw failure('Incomplete Codex authorization.');
+          const exchanged = await this._request(host + '/oauth/token', { signal, values: { client_id: C, grant_type: 'authorization_code', code: q.authorization_code, code_verifier: q.code_verifier, redirect_uri: host + '/deviceauth/callback' } });
+          if (!exchanged.response.ok) throw failure(`Codex token exchange rejected (HTTP ${exchanged.response.status}).`);
+          payload = exchanged.data;
+        } else payload = polled.data;
+        break;
+      }
+      const pending = codex ? [403, 404].includes(polled.response.status) : ['authorization_pending', 'slow_down'].includes(polled.data.error);
+      if (!pending) throw failure(`${p.id} login rejected or expired (HTTP ${polled.response.status}).`);
+      if (polled.data.error === 'slow_down') interval = Math.min(60000, interval + 5000);
+      await this.sleep(Math.min(interval, Math.max(0, end - this.now())), signal);
+    }
+    if (!payload) throw failure('The device code expired.', 'PROVIDER_AUTH_EXPIRED');
+    await this._locked(p.id, signal, () => this._write(tokenRecord(p.id, payload, this.now())));
+    await onEvent({ type: 'authenticated', provider: p.id });
+    return this.status(p.id);
+  }
+  async logout(name) {
+    const p = definition(name);
+    await this._locked(p.id, undefined, () => unlink(path.join(this.directory, `${p.id}.json`)).catch(error => { if (error.code !== 'ENOENT') throw failure('Could not delete private credentials.'); }));
+    return { provider: p.id, status: 'logged_out', remoteRevoked: false };
+  }
+  async resolve(name, { signal, forceRefresh = false } = {}) {
+    const p = definition(name);
+    return this._locked(p.id, signal, () => this._resolve(p, { signal, forceRefresh }));
+  }
+  async _resolve(p, { signal, forceRefresh }) {
+    if (this.pendingRefresh.has(p.id)) await this.pendingRefresh.get(p.id);
+    let record = await this._read(p.id);
+    if (!record) throw failure(`Run /login ${p.id} first.`, 'PROVIDER_AUTH_REQUIRED');
+    if (record.method === 'device_code' && (forceRefresh || record.expiresAt <= this.now() + 60000)) {
+      if (!record.refreshToken) throw failure('The login session expired; log in again.', 'PROVIDER_AUTH_EXPIRED');
+      const refresh = (async () => {
+        const codex = p.id === 'codex';
+        const { response, data } = await this._request(codex ? 'https://auth.openai.com/oauth/token' : 'https://auth.kimi.com/api/oauth/token', { signal,
+          values: { client_id: codex ? C : K, grant_type: 'refresh_token', refresh_token: record.refreshToken } });
+        if (!response.ok) throw failure(`Could not refresh login (HTTP ${response.status}); log in again.`, 'PROVIDER_AUTH_EXPIRED');
+        record = tokenRecord(p.id, data, this.now(), record); await this._write(record);
+      })();
+      this.pendingRefresh.set(p.id, refresh);
+      try { await refresh; } finally { this.pendingRefresh.delete(p.id); }
+    }
+    return { authProvider: p.id, protocol: p.protocol, baseURL: p.baseURL, apiKey: record.accessToken,
+      headers: { 'User-Agent': 'Comal/0.1.0', ...(record.accountId ? { 'ChatGPT-Account-Id': record.accountId } : {}) }, ...(record.expiresAt ? { expiresAt: record.expiresAt } : {}) };
+  }
+}

package/src/provider-profiles.mjs

@@ -0,0 +1,113 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { OpenAIProvider, DEFAULT_LOCAL_URL } from './openai-provider.mjs';
+import { AnthropicProvider } from './provider.mjs';
+import { GeminiProvider } from './gemini-provider.mjs';
+import { authProviderDefaults } from './provider-auth.mjs';
+import { normalizeEffort } from './model-controls.mjs';
+import {normalizeToolSchemaCapabilities} from './tool-schema.mjs';
+
+export const PROVIDER_CAPABILITIES = Object.freeze(['text', 'tools', 'thinking', 'vision', 'video', 'web_search']);
+const PROTOCOLS = ['openai', 'anthropic', 'gemini'];
+const KEYS = new Set(['name', 'provider', 'protocol', 'model', 'baseURL', 'apiKeyEnv', 'capabilities', 'capabilitiesConfigured', 'description', 'effort', 'authProvider','toolSchema']);
+const error = message => Object.assign(new Error(message), { code: 'PROVIDER_PROFILE_INVALID' });
+
+export function normalizeCapabilities(value = {}, { protocol = 'openai' } = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw error('capabilities must be an object of booleans.');
+  const capabilities = { text: true, tools: true, vision: false, video: false, web_search: false };
+  for (const [key, enabled] of Object.entries(value)) {
+    if (!PROVIDER_CAPABILITIES.includes(key) || typeof enabled !== 'boolean') throw error(`Invalid capability: ${key}.`);
+    capabilities[key] = enabled;
+  }
+  if (!capabilities.text) throw error('Session profiles require text:true.');
+  if (protocol !== 'gemini' && (capabilities.video || capabilities.web_search)) throw error(`${protocol} has no native video/web_search adapter in Comal; use gemini or MCP tools.`);
+  return Object.freeze(capabilities);
+}
+
+export function normalizeProviderProfile(input, name = input?.name) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw error('Invalid profile.');
+  for (const key of Object.keys(input)) if (!KEYS.has(key)) throw error(`Field not allowed in profile: ${key}. Store only apiKeyEnv, never API keys.`);
+  if (typeof name !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/.test(name)) throw error('Invalid profile name.');
+  if (input.name && input.name !== name) throw error('Conflicting profile name.');
+  if (input.authProvider !== undefined && !['codex', 'kimi', 'minimax', 'grok'].includes(input.authProvider)) throw error('Invalid authProvider.');
+  if (input.effort !== undefined) normalizeEffort(input.effort);
+  const toolSchema=input.toolSchema===undefined?undefined:normalizeToolSchemaCapabilities(input.toolSchema);
+  const access=input.authProvider?authProviderDefaults(input.authProvider):null;
+  const configuredCapabilities = input.capabilitiesConfigured || input.capabilities || {};
+  normalizeCapabilities(configuredCapabilities, { protocol: input.protocol || input.provider || access?.protocol || 'openai' });
+  const protocol = input.protocol || input.provider || access?.protocol || 'openai';
+  if(access && protocol!==access.protocol)throw error('The profile protocol does not match its login.');
+  if (!PROTOCOLS.includes(protocol) || (input.protocol && input.provider && input.protocol !== input.provider)) throw error('Invalid provider protocol.');
+  if (input.model !== undefined && (typeof input.model !== 'string' || !input.model.trim() || input.model.length > 256)) throw error('Invalid profile model.');
+  if (protocol !== 'openai' && !input.model && !access?.model) throw error(`${protocol} requires model in its profile.`);
+  if (input.baseURL !== undefined) {
+    if (typeof input.baseURL !== 'string') throw error('Invalid baseURL.');
+    const url = new URL(input.baseURL);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw error('baseURL requires HTTP(S), without credentials or a query.');
+  }
+  if (input.apiKeyEnv !== undefined && (typeof input.apiKeyEnv !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(input.apiKeyEnv))) throw error('apiKeyEnv must name an environment variable.');
+  if (input.description !== undefined && (typeof input.description !== 'string' || input.description.length > 1024)) throw error('Invalid description.');
+  return Object.freeze({ name, provider: protocol, protocol, ...((input.model || access?.model) ? { model: input.model || access.model } : {}),
+    baseURL: input.baseURL || access?.baseURL || ({ openai: DEFAULT_LOCAL_URL, anthropic: 'https://api.anthropic.com', gemini: 'https://generativelanguage.googleapis.com/v1beta' })[protocol],
+    apiKeyEnv: input.apiKeyEnv || ({ openai: 'OPENAI_API_KEY', anthropic: 'ANTHROPIC_API_KEY', gemini: 'GEMINI_API_KEY' })[protocol],
+    capabilities: normalizeCapabilities(input.capabilities, { protocol }), capabilitiesConfigured: Object.freeze({ ...configuredCapabilities }),...(toolSchema?{toolSchema:Object.freeze(toolSchema)}:{}),
+    ...(input.effort !== undefined ? { effort: input.effort } : {}), ...(input.authProvider ? { authProvider: input.authProvider } : {}), ...(input.description ? { description: input.description } : {}) });
+}
+
+// Configuration is data only. Secrets are resolved in createProfileProvider and
+// never returned by discovery, saved session metadata or the profile registry.
+export async function loadProviderProfiles({ cwd = process.cwd(), configPath, env = process.env } = {}) {
+  const file = path.resolve(cwd, configPath || env.COMAL_PROVIDERS_CONFIG || '.comal/providers.json');
+  let text;
+  try { text = await readFile(file, 'utf8'); }
+  catch (failure) {
+    if (failure.code === 'ENOENT' && !configPath && !env.COMAL_PROVIDERS_CONFIG) return { profiles: [], defaultProfile: null, configPath: file };
+    throw failure;
+  }
+  if (Buffer.byteLength(text) > 65536) throw error('Provider configuration exceeds 64 KiB.');
+  const config = JSON.parse(text);
+  if (!config || typeof config !== 'object' || Array.isArray(config) || Object.keys(config).some(key => !['profiles', 'defaultProfile', 'default', 'version'].includes(key))) throw error('Invalid provider configuration format.');
+  if (config.version !== undefined && config.version !== 1) throw error('Unsupported provider configuration version.');
+  const raw = config.profiles;
+  if (!raw || typeof raw !== 'object') throw error('Configure profiles as an object or list.');
+  const entries = Array.isArray(raw) ? raw.map(input => [input?.name, input]) : Object.entries(raw);
+  if (entries.length > 32) throw error('At most 32 provider profiles are allowed.');
+  const names = new Set(), profiles = entries.map(([name, input]) => {
+    const profile = normalizeProviderProfile(input, name);
+    if (names.has(profile.name)) throw error('Duplicate profile name.');
+    names.add(profile.name); return profile;
+  });
+  const defaultProfile = config.defaultProfile ?? config.default ?? null;
+  if (defaultProfile !== null && (typeof defaultProfile !== 'string' || !names.has(defaultProfile))) throw error('The default profile does not exist.');
+  return { profiles, defaultProfile, configPath: file };
+}
+
+export function selectProfile(registry, name) {
+  const requested = name || registry.defaultProfile;
+  if (!requested) return null;
+  const profile = registry.profiles.find(item => item.name === requested);
+  if (!profile) throw Object.assign(new Error(`Profile ${requested} does not exist.`), { code: 'PROVIDER_PROFILE_NOT_FOUND' });
+  return profile;
+}
+
+export function createProfileProvider(profile, { env = process.env, ...overrides } = {}) {
+  profile = normalizeProviderProfile(profile);
+  const capabilities = { ...profile.capabilities };
+  if (overrides.vision === 'on') capabilities.vision = true;
+  else if (overrides.vision === 'off') capabilities.vision = false;
+  const options = { ...overrides, apiKey: overrides.apiKey ?? env[profile.apiKeyEnv], model: overrides.model || profile.model, baseURL: overrides.baseURL || profile.baseURL,
+    capabilities, capabilitiesConfigured: profile.capabilitiesConfigured, effort: overrides.effort ?? profile.effort ?? 'auto', vision: overrides.vision || (Object.hasOwn(profile.capabilitiesConfigured, 'vision') ? capabilities.vision ? 'on' : 'off' : 'auto') };
+  if (profile.protocol !== 'openai' && !options.apiKey) throw new Error(`Set the profile apiKeyEnv variable ${profile.apiKeyEnv}.`);
+  const provider = profile.protocol === 'gemini' ? new GeminiProvider(options) : profile.protocol === 'anthropic' ? new AnthropicProvider(options) : new OpenAIProvider(options);
+  const complete = provider.complete.bind(provider);
+  provider.complete = request => {
+    if (!capabilities.tools && request.tools?.length) throw Object.assign(new Error('The profile does not enable tools.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
+    return complete(request);
+  };
+  provider.profileName = profile.name;
+  if(profile.toolSchema)provider.toolSchemaCapabilities=profile.toolSchema;
+  provider.configuredCapabilities = provider.capabilitiesConfigured;
+  const getCapabilities = provider.getCapabilities.bind(provider);
+  provider.getCapabilities = () => ({ ...capabilities, ...getCapabilities() });
+  return provider;
+}

package/src/provider-scheduler.mjs

@@ -0,0 +1,18 @@
+// Slots regulate capacity, never authority. Every callback still enters House.
+export class ProviderScheduler {
+  constructor({ slots = 2, queueLimit = 8 } = {}) { this.slots = slots; this.queueLimit = queueLimit; this.pools = new Map(); }
+  pool(key) { if (!this.pools.has(key)) this.pools.set(key, { active: 0, queue: [] }); return this.pools.get(key); }
+  snapshot(key) { const p = this.pool(key); return { active: p.active, queued: p.queue.length, slots: this.slots, queue_limit: this.queueLimit }; }
+  async run(key, callback, { signal, onQueued, onStart } = {}) {
+    signal?.throwIfAborted(); const pool = this.pool(key);
+    if (pool.active >= this.slots && pool.queue.length >= this.queueLimit) throw Object.assign(new Error('La cola del proveedor está llena.'), { code: 'AGENT_QUEUE_FULL' });
+    await new Promise((resolve, reject) => {
+      const item = { resolve: () => { signal?.removeEventListener('abort', abort); pool.active++; resolve(); }, reject };
+      const abort = () => { const i = pool.queue.indexOf(item); if (i >= 0) { pool.queue.splice(i, 1); reject(signal.reason || new Error('Cancelado')); } };
+      if (pool.active < this.slots) item.resolve();
+      else { pool.queue.push(item); signal?.addEventListener('abort', abort, { once: true }); Promise.resolve(onQueued?.()).catch(error => { const i = pool.queue.indexOf(item); if (i >= 0) { pool.queue.splice(i, 1); signal?.removeEventListener('abort', abort); reject(error); } }); }
+    });
+    try { signal?.throwIfAborted(); await onStart?.(); return await callback(); }
+    finally { pool.active--; pool.queue.shift()?.resolve(); }
+  }
+}

package/src/provider.mjs

@@ -0,0 +1,174 @@
+import { compileToolSchemas } from './tool-schema.mjs';
+import { normalizeUsage, bindUsageAccounting, accountingIdentity } from './usage-accounting.mjs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { visionSettings } from './vision.mjs';
+import { normalizeEffort, providerEffortWire } from './model-controls.mjs';
+
+export function mergeMessages(messages) {
+  const merged = [];
+  for (const msg of messages) {
+    const content = typeof msg.content === 'string' ? [{ type: 'text', text: msg.content }] : msg.content;
+    const last = merged.at(-1);
+    if (last?.role === msg.role) last.content.push(...structuredClone(content));
+    else merged.push({ role: msg.role, content: structuredClone(content) });
+  }
+  return merged;
+}
+
+export async function* sseEvents(body) {
+  const decoder = new TextDecoder();
+  let buffer = '', total = 0;
+  const parse = frame => {
+    const lines = frame.split('\n');
+    const data = lines.filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart()).join('\n');
+    return data === '[DONE]' ? { type: 'stream_done' } : data ? JSON.parse(data) : null;
+  };
+  for await (const chunk of body) {
+    total += chunk.byteLength;
+    if (total > 8 * 1024 * 1024) throw new Error('The model response exceeded 8 MiB.');
+    buffer += decoder.decode(chunk, { stream: true });
+    // Keep a trailing CR until the next chunk so split CRLF is normalized correctly.
+    buffer = buffer.replace(/\r\n/g, '\n');
+    let end;
+    while ((end = buffer.indexOf('\n\n')) !== -1) {
+      const event = parse(buffer.slice(0, end)); buffer = buffer.slice(end + 2);
+      if (event) yield event;
+    }
+  }
+  buffer += decoder.decode();
+  if (buffer.trim()) { const event = parse(buffer.replace(/\r\n/g, '\n')); if (event) yield event; }
+}
+
+export async function analyzeImages(provider, { prompt, media, signal, maxTokens } = {}) {
+  if (typeof prompt !== 'string' || !prompt.trim() || prompt.length > 12000 || !Array.isArray(media) || !media.length || media.length > 4) throw new Error('Invalid media request.');
+  const images = media.map(source => {
+    const mimeType = source.mimeType || source.media_type;
+    if (typeof mimeType !== 'string' || !/^image\/(?:png|jpeg|webp|gif)$/.test(mimeType)) throw Object.assign(new Error('This adapter supports images; video requires an enabled Gemini profile.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
+    if (source.uri || source.file_uri || typeof source.data !== 'string' || !source.data || source.data.length % 4 || !/^[a-zA-Z0-9+/]*={0,2}$/.test(source.data)) throw new Error('The image requires valid base64 data; this adapter does not accept remote URIs.');
+    if (source.data.length > 4 * 1024 * 1024) throw new Error('The image exceeds the 4 MiB encoded limit.');
+    return { type: 'image', source: { type: 'base64', media_type: mimeType, data: source.data } };
+  });
+  if (!(await provider.getVisionCapability({ signal })).supported) throw Object.assign(new Error('The provider does not enable vision.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
+  const result = await provider.complete({ messages: [{ role: 'user', content: [{ type: 'text', text: prompt }, ...images] }], tools: [], signal, maxTokens });
+  return { answer: result.content.filter(block => block.type === 'text').map(block => block.text).join(''), usage: result.usage, model: provider.model };
+}
+
+function validateMessage(message) {
+  if (!message || !Array.isArray(message.content) || !message.stop_reason) throw new Error('Incomplete model response.');
+  if(message.stop_reason==='max_tokens')throw Object.assign(new Error('Anthropic response truncated; no tools were executed.'),{code:'OUTPUT_LENGTH',usage:message.usage,usage_accounting:normalizeUsage('anthropic',message.usage)});
+  const ids = new Set();
+  for (const block of message.content) {
+    if (!block || typeof block.type !== 'string') throw new Error('Invalid content block.');
+    if (block.type === 'tool_use') {
+      if (typeof block.id !== 'string' || !block.id || ids.has(block.id) || typeof block.name !== 'string' || !block.input || typeof block.input !== 'object' || Array.isArray(block.input)) throw new Error('Invalid tool call.');
+      ids.add(block.id);
+    }
+  }
+  return message;
+}
+
+export class AnthropicProvider {
+  constructor({ apiKey = process.env.ANTHROPIC_API_KEY, baseURL = process.env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com', model = process.env.COMAL_MODEL || process.env.HARNESS_MODEL || 'claude-sonnet-4-6', maxTokens = 4096, effort = 'auto', capabilitiesConfigured = {}, vision = 'auto', imageTokens = 4096, timeoutMs = 90000, fetchImpl = fetch } = {}) {
+    if (!apiKey) throw new Error('Set ANTHROPIC_API_KEY or use --demo to try without credentials.');
+    const url = new URL(baseURL.replace(/\/$/, '') + '/v1/messages');
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) throw new Error('The provider requires HTTPS; HTTP is allowed only on localhost.');
+    if (url.username || url.password || url.search || url.hash) throw new Error('Invalid provider URL.');
+    this.protocol = 'anthropic'; this.effort = normalizeEffort(effort); this.capabilitiesConfigured = { ...capabilitiesConfigured }; this.configuredCapabilities = this.capabilitiesConfigured;
+    this.apiKey = apiKey; this.url = url; this.model = model; this.maxTokens = maxTokens; this.timeoutMs = timeoutMs; this.fetch = fetchImpl;
+    Object.assign(this, visionSettings({ vision, imageTokens }, {}));
+  }
+  getVisionCapability() { if (this.vision === 'auto' && this.modelCapabilities && this.modelCapabilities.model === this.model && typeof this.modelCapabilities.capabilities.vision === 'boolean') return { supported: this.modelCapabilities.capabilities.vision, source: this.modelCapabilities.provenance.vision?.source || 'model_discovery', model: this.model, imageTokens: this.imageTokens }; return { supported: this.vision === 'on', source: this.vision === 'on' ? 'explicit_user_configuration' : this.vision === 'off' ? 'disabled' : 'server_capability_unknown', model: this.model, imageTokens: this.imageTokens }; }
+  getCapabilities() { return { text: true, tools: true, vision: this.vision === 'on', video: false, web_search: false, ...this.capabilitiesConfigured, ...(this.modelCapabilities && this.modelCapabilities.model === this.model ? Object.fromEntries(Object.entries(this.modelCapabilities.capabilities).filter(([,value]) => value !== null)) : {}), video: false, web_search: false }; }
+  analyzeMedia(request) { return analyzeImages(this, request); }
+  async complete({ system, messages, tools = [], schemaCatalog = [], contextIdentity, signal, onText = () => {}, maxTokens = this.maxTokens }) {
+    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;
+    messages = messages.map(message => !Array.isArray(message.content) ? message : { ...message, content: message.content.flatMap(original => {
+      // Signatures belong to their issuing protocol. Preserve the durable book,
+      // but omit another provider's private reasoning from the Anthropic wire.
+      if (original.type === 'openai_reasoning' || original.type === 'thinking' && original.gemini_part) return [];
+      const { gemini_part: ignoredGeminiPart, ...block } = original;
+      if (block.type === 'video' || block.type === 'media') throw Object.assign(new Error('The Anthropic adapter does not support video; use a profile with media transport.'), { code: 'PROVIDER_CAPABILITY_UNAVAILABLE' });
+      if (block.type === 'image_reference') throw new Error('Unresolved image reference; it was not sent to the provider.');
+      if (block.type !== 'image') return block;
+      if (!this.getVisionCapability().supported) throw new Error('Vision is not enabled for this provider; no pixels were sent.');
+      return { type: 'image', source: block.source };
+    }) }).filter(message => !Array.isArray(message.content) || message.content.length);
+    const requestSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(this.timeoutMs)]) : AbortSignal.timeout(this.timeoutMs);
+    const effortWire = await providerEffortWire(this, { signal });
+    const body = JSON.stringify({ ...effortWire, model: this.model, max_tokens: maxTokens, system, messages: mergeMessages(messages), ...(tools.length ? { tools } : {}), stream: true });
+    const account=result=>({...result,usage_accounting:bindUsageAccounting(normalizeUsage('anthropic',result.usage),accountingRequest,identity,body),schema_diagnostics:schemaFrame.diagnostics,schema_manifest:schemaFrame.manifest});
+    const finish=result=>{try{return account(validateMessage(result));}catch(error){if(error.usage_accounting)error.usage_accounting=bindUsageAccounting(error.usage_accounting,accountingRequest,identity,body);throw error;}};
+    if (Buffer.byteLength(body) > 8 * 1024 * 1024) throw new Error('The context exceeds 8 MiB; start a new session with /clear.');
+    let response;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      response = await this.fetch(this.url, { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': this.apiKey, 'anthropic-version': '2023-06-01' }, body, signal: requestSignal });
+      if (![429, 529, 503].includes(response.status) || attempt === 2) break;
+      await response.body?.cancel();
+      const retry = Number(response.headers.get('retry-after'));
+      await delay(Number.isFinite(retry) && retry > 0 ? Math.min(retry * 1000, 5000) : 300 * 2 ** attempt, undefined, { signal: requestSignal });
+    }
+    if (!response.ok) {
+      await response.body?.cancel();
+      throw new Error(`API HTTP ${response.status}. Check the key, model, limits or endpoint.`);
+    }
+    if (!(response.headers.get('content-type') || '').includes('text/event-stream')) {
+      const message = finish(await response.json());
+      for (const block of message.content) if (block.type === 'text') onText(block.text);
+      return account(message);
+    }
+    let message, stopped = false;
+    const blocks = new Map(), partial = new Map(), closed = new Set();
+    for await (const event of sseEvents(response.body)) {
+      if (event.type === 'error') throw new Error(`Streaming error: ${event.error?.type || 'unknown'}`);
+      if (event.type === 'message_start') { if (message) throw new Error('Duplicate message_start.'); message = structuredClone(event.message); }
+      else if (event.type === 'content_block_start') {
+        if (blocks.has(event.index)) throw new Error('Duplicate block.');
+        blocks.set(event.index, structuredClone(event.content_block));
+      } else if (event.type === 'content_block_delta') {
+        const block = blocks.get(event.index);
+        if (!block || closed.has(event.index)) throw new Error('Delta outside its block.');
+        const d = event.delta;
+        if (d.type === 'text_delta') { block.text = (block.text || '') + d.text; onText(d.text); }
+        else if (d.type === 'input_json_delta') partial.set(event.index, (partial.get(event.index) || '') + d.partial_json);
+        else if (d.type === 'thinking_delta') block.thinking = (block.thinking || '') + d.thinking;
+        else if (d.type === 'signature_delta') block.signature = (block.signature || '') + d.signature;
+      } else if (event.type === 'content_block_stop') {
+        if (!blocks.has(event.index)) throw new Error('Unknown block closure.');
+        if (partial.has(event.index)) blocks.get(event.index).input = JSON.parse(partial.get(event.index));
+        closed.add(event.index);
+      } else if (event.type === 'message_delta') {
+        if (!message) throw new Error('Delta without a message.');
+        Object.assign(message, event.delta); message.usage = { ...message.usage, ...event.usage };
+      } else if (event.type === 'message_stop') stopped = true;
+    }
+    if (!stopped || !message || closed.size !== blocks.size) throw new Error('Streaming interrupted; no tools from this response were executed.');
+    message.content = [...blocks.entries()].sort((a, b) => a[0] - b[0]).map(([, block]) => block);
+    return finish(message);
+  }
+}
+
+export class DemoProvider {
+  constructor(sessionId) { this.model = 'demo-scripted'; this.file = `comal-demo-${sessionId.slice(0, 8)}.md`; }
+  async complete({ messages, onText = () => {}, signal }) {
+    if (signal?.aborted) throw new Error('Demo cancelled.');
+    const projection = messages.find(m => typeof m.content === 'string' && m.content.startsWith('Estado de trabajo derivado determinísticamente por Comal'));
+    const state = projection ? JSON.parse(projection.content.slice(projection.content.indexOf('\n') + 1)) : null;
+    const progress = state?.tool_progress.recent.filter(item => /^demo_\d+$/.test(item.id));
+    const calls = progress?.length ? Math.max(...progress.map(item => Number(item.id.slice(5)))) + 1 : messages.flatMap(m => Array.isArray(m.content) ? m.content : []).filter(b => b.type === 'tool_result').length;
+    const steps = [
+      ['Write', { file_path: this.file, content: '# Comal\n\nTool cycle pending.\n' }],
+      ['Read', { file_path: this.file }],
+      ['Edit', { file_path: this.file, old_string: 'pending', new_string: 'verified' }],
+      ['Grep', { pattern: 'verified', glob: this.file }]
+    ];
+    if (calls < steps.length) {
+      const [name, input] = steps[calls];
+      return { role: 'assistant', content: [{ type: 'tool_use', id: `demo_${calls}`, name, input }], stop_reason: 'tool_use', usage: { input_tokens: 0, output_tokens: 0 } };
+    }
+    const failed = progress?.some(item => item.is_error) || messages.flatMap(m => Array.isArray(m.content) ? m.content : []).some(b => b.type === 'tool_result' && b.is_error);
+    const text = failed ? 'The demo finished with denied tools or errors. Check the events; not all changes completed.' : `Demo without a real model: created, read, edited and searched text in ${this.file}. The history can be resumed.`;
+    onText(text);
+    return { role: 'assistant', content: [{ type: 'text', text }], stop_reason: 'end_turn', usage: { input_tokens: 0, output_tokens: 0 } };
+  }
+}

package/src/read-only-check.mjs

@@ -0,0 +1,38 @@
+import { shellCommands } from './auto-guard.mjs';
+
+// A deliberately small executable subset, not a claim that arbitrary Bash is safe.
+// The native executor runs these greps with fixed argv and no shell.
+export function readOnlyBashCheck(command) {
+  if (typeof command !== 'string') return null;
+  let quote = '', andCount = 0;
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    if (quote) { if (c === quote) quote = ''; continue; }
+    if (c === "'" || c === '"') quote = c;
+    else if (c === '&' && command[i + 1] === '&') { i++; andCount++; }
+    else if (/[;&|<>\n\r#]/.test(c)) return null;
+  }
+  const commands = shellCommands(command); if (!commands?.length || commands.length !== andCount + 1) return null;
+  const steps = [], files = [];
+  for (const [index, tokens] of commands.entries()) {
+    const [name, ...args] = tokens;
+    if (name === 'echo' && index === commands.length - 1 && steps.length && args.every(arg => !arg.startsWith('-') && !/[\\\r\n]/.test(arg))) { steps.push({ kind: 'echo', text: args.join(' ') }); continue; }
+    if (name !== 'grep' && name !== '/usr/bin/grep') return null;
+    let cursor = 0; const flags = [];
+    while (/^-[qFEinc]+$/.test(args[cursor] || '')) flags.push(args[cursor++]);
+    if (args[cursor] === '--') cursor++;
+    if (args.length - cursor !== 2) return null;
+    const [pattern, file] = args.slice(cursor);
+    if (!file || file.startsWith('-') || /[*?\[\]{}]/.test(file)) return null;
+    steps.push({ kind: 'grep', flags, pattern, file }); files.push(file);
+  }
+  return files.length ? { steps, files: [...new Set(files)] } : null;
+}
+
+// Known shipped observation implementations only, not arbitrary plugin/MCP hints.
+// Rechecking still goes through the live contract, guard and permission judge.
+const CHROME_LAB_READS = new Set(['Status', 'Deployment', 'Targets', 'ReadDOM', 'Assert', 'Contexts', 'Console'].map(name => `plugin__chrome-lab__${name}`));
+export const chromeLabObservation = operation => CHROME_LAB_READS.has(operation);
+export const readOnlyWorkCheck = (operation, args) => ['Read', 'Glob', 'Grep', 'ListDirectory', 'FileInfo', 'ChromeVerify'].includes(operation) || CHROME_LAB_READS.has(operation) || (operation === 'Bash' && Boolean(readOnlyBashCheck(args?.command)));
+export const RUNTIME_CHECK_IDS = Object.freeze(['target_id','pageId','page_id','context_id','contextId']);
+export const runtimeBoundReadCheck = (operation, args) => readOnlyWorkCheck(operation,args) && RUNTIME_CHECK_IDS.some(key => Object.hasOwn(args || {},key));

package/src/remote-commands.mjs

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