@milpa/comal 0.2.2 → 0.2.4

package/src/auto-guard.mjs

@@ -13,6 +13,11 @@ export function protectPath(directory, { reason, names = [] } = {}) {
   protectedPaths.set(key, { directory: path.resolve(directory), reason: reason || 'Ruta protegida por un plugin activo.', names: names.filter(name => typeof name === 'string' && name.length >= 3) });
   return () => protectedPaths.delete(key);
 }
+/** ¿Está `file` (absoluta) bajo una ruta que un plugin activo protege? */
+export function isProtectedPath(file) {
+  for (const { directory } of protectedPaths.values()) { const relative = path.relative(directory, file); if (relative === '' || (relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative))) return true; }
+  return false;
+}
 export function protectedPathMention(command, cwd) {
   if (!protectedPaths.size || typeof command !== 'string') return null;
   const home = os.homedir(), tokens = command.split(/[\s'"`;&|()<>=]+/).filter(Boolean);
@@ -24,13 +29,43 @@ export function protectedPathMention(command, cwd) {
       const expanded = token.startsWith('~/') ? path.join(home, token.slice(2)) : token;
       const resolved = path.resolve(cwd || process.cwd(), expanded.replace(/[*?\[\]{}].*$/, '') || '.');
       if (resolved === directory || resolved.startsWith(directory + path.sep)) return entry.reason;
-      // Un glob o un prefijo que alcanza la ruta protegida también la menciona.
-      if (/[*?\[\]{}]/.test(expanded) && directory.startsWith(resolved)) return entry.reason;
+      // Un glob que puede expandirse a la ruta protegida o a uno de sus padres también la menciona.
+      if (/[*?\[\]{}]/.test(expanded) && globReaches(path.resolve(cwd || process.cwd(), expanded), directory)) return entry.reason;
     }
   }
   return null;
 }
 
+// Whether an absolute glob could expand to `directory` or to one of its parents, compared
+// segment by segment. Like bash, a wildcard does not match a leading dot and an unclosed
+// brace is literal. When unsure (`**`, a brace group spanning a slash), it answers yes.
+function globReaches(pattern, directory) {
+  if (/\{[^{}]*\/[^{}]*\}/.test(pattern)) return true;
+  const wanted = pattern.split(path.sep), target = directory.split(path.sep);
+  for (let i = 0; i < Math.min(wanted.length, target.length); i++) {
+    const segment = wanted[i];
+    if (segment.includes('**')) return true;
+    const braces = /\{[^{}]*,[^{}]*\}/.test(segment);
+    if (!/[*?\[\]{}]/.test(segment)) { if (segment !== target[i]) return false; continue; }
+    let source = '', depth = 0;
+    for (let j = 0; j < segment.length; j++) {
+      const c = segment[j];
+      if (c === '*') source += '[^/]*';
+      else if (c === '?') source += '[^/]';
+      else if (c === '[') { const end = segment.indexOf(']', j + 2); if (end < 0) source += '\\['; else { source += '[^/]'; j = end; } }
+      else if (c === '{' && braces) { source += '(?:'; depth++; }
+      else if (c === ',' && depth) source += '|';
+      else if (c === '}' && depth) { source += ')'; depth--; }
+      else source += c.replace(/[.+^$()|\\\]{}]/g, '\\$&');
+    }
+    if (depth) return true;
+    if (target[i].startsWith('.') && /^[*?\[]/.test(segment)) return false;
+    let matches; try { matches = new RegExp(`^${source}$`).test(target[i]); } catch { return true; }
+    if (!matches) return false;
+  }
+  return true;
+}
+
 // Deliberately limited lexer. Unsupported expansions/wrappers require human review.
 export function shellCommands(command) {
   const commands = []; let tokens = [], token = '', quote = '', started = false;
@@ -96,7 +131,9 @@ export function inspectAutoAction(name, input, cwd) {
     if (executable === 'git' && (args.includes('--hard') || args.includes('clean') || args.some(a => /^--force(?:-with-lease)?$/.test(a) || /^-[^-]*f/.test(a)))) destructive = true;
     if (['dd', 'docker', 'kubectl', 'terraform', 'psql', 'mysql', 'sqlite3'].includes(executable)) { opaque = true; destructive = true; }
     const commandLookup = executable === 'command' && args[0] === '-v' && args.length > 1 && args.slice(1).every(value => !value.startsWith('-'));
-    const testRunner = (executable === 'node' && args[0] === '--test') || (executable.startsWith('python') && args[0] === '-m' && args[1] === 'pytest');
+    // `node --check FILE…` only parses the files; any other flag could load or run code.
+    const syntaxCheck = executable === 'node' && ['--check', '-c'].includes(args[0]) && args.length > 1 && args.slice(1).every(value => !value.startsWith('-'));
+    const testRunner = syntaxCheck || (executable === 'node' && args[0] === '--test') || (executable.startsWith('python') && args[0] === '-m' && args[1] === 'pytest');
     if (/^(?:sh|bash|zsh|fish|node|python\d*|ruby|perl|php|eval|exec|xargs|env|command|timeout|busybox|npx|for|while|until|if|then|do|done|case|esac|function)$/.test(executable) && !testRunner && !commandLookup) opaque = true;
     if (tokens[0].includes('=')) opaque = true;
     if (executable === 'find' && args.some(arg => ['-delete', '-exec', '-execdir'].includes(arg))) { destructive = true; opaque = true; }

package/src/autocompact.mjs

@@ -0,0 +1,233 @@
+// Compaction timing policy. The compaction window is a target for proactive
+// projection, separate from the model's physical context window: large windows
+// stay cheaper and sharper when the conversation is projected long before the
+// physical limit. All thresholds are in "used" tokens = estimated input plus the
+// output reserve. The projection itself stays deterministic (compaction.mjs).
+import { readFile, mkdir, writeFile, rename, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash, randomUUID } from 'node:crypto';
+import { comalEnvironment } from './compat.mjs';
+import { t, registerMessages } from './i18n/index.mjs';
+
+registerMessages({
+  'Use /autocompact N|Nk|auto|off|default (for example 400k).': 'Usa /autocompact N|Nk|auto|off|default (por ejemplo 400k).',
+  'The compaction window must be between 4096 and 2000000 tokens.': 'La ventana de compactación debe estar entre 4096 y 2000000 tokens.',
+  '--autocompact / COMAL_AUTOCOMPACT: {reason}': '--autocompact / COMAL_AUTOCOMPACT: {reason}',
+  'COMAL_CACHE_TTL_MS must be off or an integer between 1000 and 86400000.': 'COMAL_CACHE_TTL_MS debe ser off o un entero entre 1000 y 86400000.',
+  'Saved autocompact settings exceed 16 KiB.': 'La configuración guardada de autocompact excede 16 KiB.',
+  'Invalid saved autocompact settings.': 'Configuración guardada de autocompact inválida.',
+});
+
+export const LARGE_WINDOW = 600000, LARGE_DEFAULT = 400000, SOFT_RATIO = .75;
+export const AUTO_MIN = 300000, AUTO_LARGE_CAP = 600000, AUTO_FACTOR = 1.3, AUTO_MIN_SAMPLES = 3, AUTO_SAMPLES = 50;
+// Provider prompt-cache lifetimes known to the host. Anthropic's default
+// ephemeral cache lives 5 minutes; other providers are opt-in (COMAL_CACHE_TTL_MS).
+export const CACHE_TTL_MS = Object.freeze({ anthropic: 300000 });
+// Relative input-token prices used for the cost estimate: Anthropic 5-minute
+// cache writes cost 1.25x input, cache reads 0.1x. Recorded as an assumption.
+export const CACHE_RATES = Object.freeze({ basis: 'anthropic_ephemeral_5m_relative', uncached: 1, cache_write: 1.25, cache_read: .1 });
+
+/** N | Nk | Nm | auto | off | default → setting. `default` means "no per-model value". */
+export function parseAutocompact(text) {
+  const value = String(text ?? '').trim().toLowerCase();
+  if (['auto', 'off', 'default'].includes(value)) return { mode: value };
+  const match = /^(\d+(?:\.\d+)?)\s*([km])?$/.exec(value);
+  if (!match) throw Object.assign(new Error(t('Use /autocompact N|Nk|auto|off|default (for example 400k).')), { code: 'AUTOCOMPACT_INVALID' });
+  const tokens = Math.round(Number(match[1]) * (match[2] === 'k' ? 1000 : match[2] === 'm' ? 1000000 : 1));
+  if (!Number.isSafeInteger(tokens) || tokens < 4096 || tokens > 2000000) throw Object.assign(new Error(t('The compaction window must be between 4096 and 2000000 tokens.')), { code: 'AUTOCOMPACT_INVALID' });
+  return { mode: 'fixed', tokens };
+}
+const serialize = setting => setting.mode === 'fixed' ? setting.tokens : setting.mode;
+const deserialize = value => typeof value === 'number' ? parseAutocompact(String(value)) : parseAutocompact(value);
+
+export function percentile(values, ratio) {
+  const sorted = values.filter(Number.isFinite).sort((a, b) => a - b);
+  if (!sorted.length) return null;
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.ceil(ratio * sorted.length) - 1))];
+}
+
+/**
+ * Resolves the compaction window and thresholds for one request shape.
+ * setting: {mode:'fixed',tokens}|{mode:'auto'}|{mode:'off'}|null (default).
+ * peaks: recent per-task peaks of this project (used tokens), newest last.
+ */
+export function compactionPlan({ contextWindow, outputReserve = 0, overhead = 0, setting = null, settingSource = 'default', peaks = [], triggerRatio = .9 }) {
+  const physical = Math.floor(contextWindow * triggerRatio);
+  const floor = 2 * outputReserve + Math.max(0, Math.ceil(overhead));
+  const base = contextWindow >= LARGE_WINDOW ? LARGE_DEFAULT : physical;
+  const mode = setting?.mode && setting.mode !== 'default' ? setting.mode : 'default';
+  let window = base, source = 'default', reason = contextWindow >= LARGE_WINDOW ? 'large_window_default' : 'trigger_ratio_of_window', auto;
+  if (mode === 'off') { window = physical; source = 'off'; reason = 'proactive_compaction_disabled'; }
+  else if (mode === 'fixed') { window = setting.tokens; source = 'user'; reason = 'user_setting'; }
+  else if (mode === 'auto') {
+    source = 'auto';
+    const samples = peaks.filter(value => Number.isFinite(value) && value > 0).slice(-AUTO_SAMPLES), cap = contextWindow >= LARGE_WINDOW ? AUTO_LARGE_CAP : physical;
+    const minimum = Math.min(AUTO_MIN, cap), p90 = percentile(samples, .9);
+    auto = { samples: samples.length, p90_peak: p90, factor: AUTO_FACTOR, minimum, cap };
+    if (samples.length < AUTO_MIN_SAMPLES) { window = base; reason = 'auto_insufficient_samples'; }
+    else { window = Math.min(cap, Math.max(minimum, Math.ceil(p90 * AUTO_FACTOR))); reason = 'auto_p90_task_peak'; }
+  }
+  const clamps = [];
+  if (window > physical) { window = physical; clamps.push('physical_window'); }
+  if (window < floor) { window = Math.min(floor, physical); clamps.push('lower_bound'); }
+  return {
+    policy: 'compaction_window_v1', units: 'input_plus_output_reserve', context_window: contextWindow, physical_threshold: physical,
+    compaction_window: window, source, setting_source: mode === 'default' ? 'default' : settingSource, reason, clamps, lower_bound: floor,
+    soft_ratio: mode === 'off' ? null : SOFT_RATIO, soft_threshold: mode === 'off' ? null : Math.floor(window * SOFT_RATIO), hard_threshold: window,
+    ...(auto ? { auto } : {}),
+  };
+}
+
+/** One human line explaining where the compaction window comes from. */
+export function describePlan(plan) {
+  const k = value => value >= 10000 ? `${Math.round(value / 1000)}k` : String(value);
+  const clamps = plan.clamps.length ? ` · ${plan.clamps.map(item => item === 'lower_bound' ? t('raised to the lower bound {v0}', { v0: k(plan.lower_bound) }) : t('capped at {v0}', { v0: k(plan.physical_threshold) })).join(' · ')}` : '';
+  if (plan.source === 'auto') {
+    if (plan.reason === 'auto_insufficient_samples') return t('auto: {v0} task peaks recorded (needs {v1}); using the default', { v0: plan.auto.samples, v1: AUTO_MIN_SAMPLES }) + clamps;
+    return t('auto: p90 task peak {v0} × {v1} over {v2} tasks, bounded {v3}–{v4}', { v0: k(plan.auto.p90_peak), v1: plan.auto.factor, v2: plan.auto.samples, v3: k(plan.auto.minimum), v4: k(plan.auto.cap) }) + clamps;
+  }
+  if (plan.source === 'user') return t('user setting ({v0})', { v0: plan.setting_source }) + clamps;
+  if (plan.source === 'off') return t('off: only the physical limit compacts') + clamps;
+  return (plan.reason === 'large_window_default' ? t('default for windows ≥ {v0}', { v0: k(LARGE_WINDOW) }) : t('default: {v0} of the window', { v0: '0.9' })) + clamps;
+}
+registerMessages({
+  'raised to the lower bound {v0}': 'elevada al mínimo {v0}', 'capped at {v0}': 'limitada a {v0}',
+  'auto: {v0} task peaks recorded (needs {v1}); using the default': 'auto: {v0} picos de tarea registrados (necesita {v1}); usa el valor por omisión',
+  'auto: p90 task peak {v0} × {v1} over {v2} tasks, bounded {v3}–{v4}': 'auto: pico p90 de tarea {v0} × {v1} sobre {v2} tareas, acotado {v3}–{v4}',
+  'user setting ({v0})': 'ajuste del usuario ({v0})', 'off: only the physical limit compacts': 'off: sólo compacta el límite físico',
+  'default for windows ≥ {v0}': 'valor por omisión para ventanas ≥ {v0}', 'default: {v0} of the window': 'por omisión: {v0} de la ventana',
+});
+
+/** Cache TTL for the idle rule: explicit setting, else the provider's known TTL, else none. */
+export function resolveCacheTtl(env = process.env) {
+  const value = comalEnvironment(env).COMAL_CACHE_TTL_MS;
+  if (value === undefined || value === '') return undefined;
+  if (/^(?:off|0|none)$/i.test(String(value).trim())) return null;
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < 1000 || number > 86400000) throw new Error(t('COMAL_CACHE_TTL_MS must be off or an integer between 1000 and 86400000.'));
+  return number;
+}
+
+// ---- Per-model persistence: $XDG_CONFIG_HOME/comal/autocompact.json -------
+export const autocompactFile = (env = process.env) => path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'comal', 'autocompact.json');
+function normalizeSaved(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || value.version !== 1 || !value.models || typeof value.models !== 'object' || Array.isArray(value.models)) throw new Error(t('Invalid saved autocompact settings.'));
+  const models = {};
+  for (const [model, setting] of Object.entries(value.models)) {
+    if (!model || model.length > 256 || /[\x00-\x1f\x7f]/.test(model)) throw new Error(t('Invalid saved autocompact settings.'));
+    const parsed = deserialize(setting); if (parsed.mode === 'default') continue;
+    models[model] = serialize(parsed);
+  }
+  return { version: 1, models };
+}
+export async function loadAutocompactSettings({ env = process.env } = {}) {
+  try {
+    const text = await readFile(autocompactFile(env), 'utf8');
+    if (Buffer.byteLength(text) > 16384) throw new Error(t('Saved autocompact settings exceed 16 KiB.'));
+    return normalizeSaved(JSON.parse(text));
+  } catch (error) { if (error.code === 'ENOENT') return { version: 1, models: {} }; throw error; }
+}
+/** Saves (or with mode 'default' removes) the value for one model. Same atomic, private write as connection.json. */
+export async function saveAutocompactSetting(model, setting, { env = process.env } = {}) {
+  const current = await loadAutocompactSettings({ env }).catch(() => ({ version: 1, models: {} })), models = { ...current.models };
+  if (setting.mode === 'default') delete models[model]; else models[model] = serialize(setting);
+  const data = normalizeSaved({ version: 1, models }), file = autocompactFile(env), temporary = file + '.' + randomUUID(), text = JSON.stringify(data) + '\n';
+  if (Buffer.byteLength(text) > 16384) throw new Error(t('Saved autocompact settings exceed 16 KiB.'));
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  try { await writeFile(temporary, text, { flag: 'wx', mode: 0o600 }); await rename(temporary, file); }
+  finally { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
+  return data;
+}
+/** Precedence: --autocompact > COMAL_AUTOCOMPACT > saved value for the model > default. */
+export function resolveAutocompactSetting({ flag, env = process.env, saved = { models: {} }, model } = {}) {
+  const variable = comalEnvironment(env).COMAL_AUTOCOMPACT;
+  const pick = (value, source) => { try { const setting = parseAutocompact(value); return setting.mode === 'default' ? null : { setting, source }; } catch (error) { throw new Error(t('--autocompact / COMAL_AUTOCOMPACT: {reason}', { reason: error.message })); } };
+  if (flag !== undefined && flag !== null && flag !== '') { const chosen = pick(flag, 'cli'); if (chosen) return chosen; }
+  else if (variable !== undefined && variable !== '') { const chosen = pick(variable, 'environment'); if (chosen) return chosen; }
+  const stored = model ? saved?.models?.[model] : undefined;
+  if (stored !== undefined) return { setting: deserialize(stored), source: 'saved' };
+  return { setting: null, source: 'default' };
+}
+
+// ---- Per-project task peaks: $XDG_STATE_HOME/comal/projects/<hash>/ --------
+// Outside the workspace on purpose: these are host statistics, not project files.
+export const projectStateDir = (cwd, env = process.env) => path.join(comalEnvironment(env).COMAL_CONTEXT_STATS_DIR || path.join(env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state'), 'comal', 'projects'), createHash('sha256').update(cwd).digest('hex').slice(0, 16));
+export class ContextPeakStats {
+  constructor({ cwd, env = process.env, file } = {}) { this.file = file || path.join(projectStateDir(cwd, env), 'context-peaks.json'); this.cache = null; }
+  async load() {
+    try {
+      const text = await readFile(this.file, 'utf8'); if (Buffer.byteLength(text) > 65536) return [];
+      const value = JSON.parse(text); return Array.isArray(value?.peaks) ? value.peaks.filter(item => item && Number.isFinite(item.task_tokens)) : [];
+    } catch { return []; }
+  }
+  /** Task peaks in used tokens (input + output reserve), oldest first. */
+  async taskPeaks() { this.cache = await this.load(); return this.cache.map(item => item.task_tokens); }
+  async record(sample) {
+    const peaks = [...await this.load(), { ...sample, at: new Date().toISOString() }].slice(-100), temporary = this.file + '.' + randomUUID();
+    await mkdir(path.dirname(this.file), { recursive: true, mode: 0o700 });
+    try { await writeFile(temporary, JSON.stringify({ version: 1, peaks }) + '\n', { flag: 'wx', mode: 0o600 }); await rename(temporary, this.file); }
+    finally { await unlink(temporary).catch(() => {}); }
+    this.cache = peaks; return peaks;
+  }
+}
+
+/** Estimated effect on the next requests, in input-token equivalents. Only when the provider reported usage. */
+export function compactionCostEstimate({ rows = [], before, after, trigger, overhead = 0 }) {
+  const last = rows.findLast(row => row.type === 'model_usage' && row.usage_accounting)?.usage_accounting;
+  if (!last || !Number.isSafeInteger(last.context_input_tokens)) return null;
+  const warm = trigger !== 'idle_cache_expired', saved = Math.max(0, before - after);
+  // The system/tools prefix is not touched by a projection: while warm it stays a cache read.
+  const prefix = warm ? Math.max(0, Math.min(overhead, after)) : 0;
+  const without = Math.round(before * (warm ? CACHE_RATES.cache_read : CACHE_RATES.cache_write)), withCompaction = Math.round(prefix * CACHE_RATES.cache_read + (after - prefix) * CACHE_RATES.cache_write), following = Math.round(saved * CACHE_RATES.cache_read);
+  return { unit: 'input_token_equivalents', rates: CACHE_RATES, cache_assumed: warm ? 'warm' : 'expired', next_request_without_compaction: without, next_request_with_compaction: withCompaction,
+    following_request_saving: following, break_even_requests: withCompaction <= without ? 0 : following > 0 ? Math.ceil((withCompaction - without) / following) : null,
+    last_measured: { protocol: last.protocol || null, context_input_tokens: last.context_input_tokens, cache_read_tokens: last.cache_read_tokens ?? null, cache_write_tokens: last.cache_write_tokens ?? null } };
+}
+
+// ---- Presentation (host text only) ------------------------------------------
+export { compactionNotice } from './compaction-notice.mjs';
+const kilo = value => !Number.isFinite(value) ? '?' : value >= 10000 ? `${Math.round(value / 1000)}k` : String(Math.round(value));
+registerMessages({
+  'Compaction window: {v0} · {v1}': 'Ventana de compactación: {v0} · {v1}',
+  'Thresholds: soft {v0} (at turn end or after the prompt cache expires) · hard {v1} (any request) · physical {v2}': 'Umbrales: suave {v0} (al terminar el turno o al expirar la caché) · duro {v1} (cualquier petición) · físico {v2}',
+  'Thresholds: no proactive compaction · physical {v0}': 'Umbrales: sin compactación proactiva · físico {v0}',
+  'Usage: ~{v0} used (input + output reserve) · {v1}% of the compaction window': 'Uso: ~{v0} usados (entrada + reserva de salida) · {v1}% de la ventana de compactación',
+  'Last compaction: {v0} · ~{v1} → ~{v2} tokens · {v3}': 'Última compactación: {v0} · ~{v1} → ~{v2} tokens · {v3}',
+  'Last compaction: none in this session': 'Última compactación: ninguna en esta sesión',
+  'Idle rule: prompt cache {v0} min ({v1})': 'Regla de inactividad: caché de prompt {v0} min ({v1})',
+  'Idle rule: off (no known prompt-cache lifetime; set COMAL_CACHE_TTL_MS)': 'Regla de inactividad: apagada (sin duración de caché conocida; usa COMAL_CACHE_TTL_MS)',
+  'Pinned focus: {v0}': 'Foco fijado: {v0}',
+  'Change: /autocompact N|Nk|auto|off|default · /compact focus TEXT': 'Cambiar: /autocompact N|Nk|auto|off|default · /compact enfócate en TEXTO',
+  'Compaction window for {v0}: {v1} · {v2}\nSoft {v3} · hard {v4} · lower bound {v5}': 'Ventana de compactación para {v0}: {v1} · {v2}\nSuave {v3} · duro {v4} · mínimo {v5}',
+  'Saved for {v0} in {v1}.': 'Guardado para {v0} en {v1}.',
+  'Applied to this session; not saved: {v0}': 'Aplicado a esta sesión; no guardado: {v0}',
+  'The startup flag --autocompact still wins over the saved value.': 'La bandera --autocompact sigue mandando sobre el valor guardado.',
+  'The environment variable COMAL_AUTOCOMPACT still wins over the saved value.': 'La variable COMAL_AUTOCOMPACT sigue mandando sobre el valor guardado.',
+  'Compaction window per model (N, Nk, auto, off)': 'Ventana de compactación por modelo (N, Nk, auto, off)',
+  'Use /compact or /compact focus TEXT (also: /compact enfócate en TEXTO).': 'Usa /compact o /compact focus TEXT (también: /compact enfócate en TEXTO).',
+  'Focus pinned: {v0} · {v1} results/messages kept verbatim (~{v2} tokens, budget {v3}){v4}.': 'Foco fijado: {v0} · {v1} resultados/mensajes conservados completos (~{v2} tokens, presupuesto {v3}){v4}.',
+  ' · {v0} omitted by budget': ' · {v0} omitidos por presupuesto',
+});
+export function formatCompactionStatus({ plan, status, last, cacheTtlMs, protocol, focus }) {
+  const used = status.input_tokens + status.output_reserve;
+  const lines = [t('Compaction window: {v0} · {v1}', { v0: kilo(plan.compaction_window), v1: describePlan(plan) }),
+    plan.soft_threshold === null ? t('Thresholds: no proactive compaction · physical {v0}', { v0: kilo(plan.physical_threshold) })
+      : t('Thresholds: soft {v0} (at turn end or after the prompt cache expires) · hard {v1} (any request) · physical {v2}', { v0: kilo(plan.soft_threshold), v1: kilo(plan.hard_threshold), v2: kilo(plan.physical_threshold) }),
+    t('Usage: ~{v0} used (input + output reserve) · {v1}% of the compaction window', { v0: kilo(used), v1: Math.round(used / plan.compaction_window * 100) }),
+    last ? t('Last compaction: {v0} · ~{v1} → ~{v2} tokens · {v3}', { v0: last.compaction_trigger || last.reason || last.trigger, v1: kilo(last.before_tokens), v2: kilo(last.after_tokens), v3: last.timestamp || '' }) : t('Last compaction: none in this session'),
+    Number.isSafeInteger(cacheTtlMs) && cacheTtlMs > 0 ? t('Idle rule: prompt cache {v0} min ({v1})', { v0: Math.round(cacheTtlMs / 60000 * 10) / 10, v1: protocol || 'configured' }) : t('Idle rule: off (no known prompt-cache lifetime; set COMAL_CACHE_TTL_MS)'),
+    ...(focus ? [t('Pinned focus: {v0}', { v0: focus })] : []),
+    t('Change: /autocompact N|Nk|auto|off|default · /compact focus TEXT')];
+  return lines.join('\n');
+}
+export const formatTokens = kilo;
+/** /compact focus TEXT · /compact foco TEXTO · /compact enfócate en TEXTO. Returns null for plain /compact. */
+export function parseCompactArguments(arg) {
+  const text = String(arg || '').trim(); if (!text) return { focus: null };
+  const match = /^(?:focus(?:\s+on)?|foco|enf[oó]ca(?:te|r)(?:\s+en)?)\s*:?\s+([\s\S]+)$/iu.exec(text);
+  if (!match || !match[1].trim()) throw Object.assign(new Error(t('Use /compact or /compact focus TEXT (also: /compact enfócate en TEXTO).')), { code: 'COMPACT_ARGUMENTS' });
+  if (match[1].length > 2000) throw Object.assign(new Error(t('Use /compact or /compact focus TEXT (also: /compact enfócate en TEXTO).')), { code: 'COMPACT_ARGUMENTS' });
+  return { focus: match[1].trim() };
+}
+registerMessages({ 'Use /model ID first.': 'Usa /model ID primero.' });

package/src/bash-timeouts.mjs

@@ -0,0 +1,29 @@
+import { comalEnvironment } from './compat.mjs';
+
+// Shell commands (Bash and declared Git checks) get a default timeout and a
+// ceiling the model may ask for. Test suites and builds routinely need minutes,
+// so the default ceiling matches the MCP request limit (30 min, mcp-rpc.mjs).
+export const BASH_DEFAULT_TIMEOUT_MS = 30000;
+export const BASH_DEFAULT_MAX_TIMEOUT_MS = 1800000;
+const HARD_LIMIT_MS = 86400000;
+
+export function bashTimeoutSettings(options = {}, env = process.env) {
+  env = comalEnvironment(env);
+  const maxMs = Number(options.maxTimeoutMs ?? env.COMAL_BASH_MAX_TIMEOUT_MS ?? BASH_DEFAULT_MAX_TIMEOUT_MS);
+  if (!Number.isSafeInteger(maxMs) || maxMs < 1000 || maxMs > HARD_LIMIT_MS) throw new Error(`COMAL_BASH_MAX_TIMEOUT_MS must be an integer between 1000 and ${HARD_LIMIT_MS} ms.`);
+  const defaultMs = Number(options.timeoutMs ?? env.COMAL_BASH_TIMEOUT_MS ?? Math.min(BASH_DEFAULT_TIMEOUT_MS, maxMs));
+  if (!Number.isSafeInteger(defaultMs) || defaultMs < 1 || defaultMs > maxMs) throw new Error(`COMAL_BASH_TIMEOUT_MS must be an integer between 1 and the ceiling (${maxMs} ms).`);
+  return { defaultMs, maxMs };
+}
+
+// Read once per process: tool schemas are fixed when the tool catalogue loads.
+export const BASH_TIMEOUTS = Object.freeze(bashTimeoutSettings());
+
+export function bashTimeoutSchema({ maxMs } = BASH_TIMEOUTS) {
+  return { type: 'integer', minimum: 1, maximum: maxMs };
+}
+
+// Kept short: this text is in every request's tool catalogue.
+export function bashDescription({ defaultMs, maxMs } = BASH_TIMEOUTS) {
+  return `Shell command, after permission (NOT an OS sandbox). Use ListDirectory/Glob/Grep/Read to list/find/read files, also in --add-dir dirs (no permission). Timeout ${defaultMs} ms; pass a longer one (max ${maxMs}) for test suites and builds. Serve test pages with WorkspaceServe, not a background server.`;
+}

package/src/child-env.mjs

@@ -0,0 +1,23 @@
+// Environment for processes Comal starts on behalf of the model (Bash, MCP servers, Git).
+// Provider credentials stay in the Comal process: a command the model writes never
+// inherits them, so `env` or a script cannot print or send the key.
+const PROVIDER_SECRET = /^(?:COMAL|HARNESS|OPENAI|ANTHROPIC|GEMINI|GOOGLE|OLLAMA|DEEPSEEK|OPENROUTER|MISTRAL|GROQ|XAI|AZURE_OPENAI)_(?:API_KEY|AUTH_TOKEN|ACCESS_TOKEN)$/;
+const VALID_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const registered = new Set();
+
+// Names declared by a provider profile (apiKeyEnv) or `login --api-key-env` are secrets too.
+export function registerSecretEnv(name) {
+  if (typeof name === 'string' && VALID_NAME.test(name)) registered.add(name);
+}
+
+export function isProviderSecretEnv(name) {
+  return PROVIDER_SECRET.test(name) || registered.has(name);
+}
+
+// A copy of env without provider credentials; `extra` (explicit per-process values, e.g.
+// an MCP server's own env block) is applied afterwards and kept as configured.
+export function childEnvironment(env = process.env, extra = {}) {
+  const out = {};
+  for (const [key, value] of Object.entries(env)) if (value !== undefined && !isProviderSecretEnv(key)) out[key] = value;
+  return { ...out, ...extra };
+}