@milpa/comal 0.2.2 → 0.2.4

package/src/remote-stats.mjs

@@ -0,0 +1,205 @@
+// session.stats for /rc surfaces (browser and paired M5Stack): a bounded summary built from what
+// /status, /context and the status bar already compute. Pure module: numbers, enums and bounded
+// labels only — never paths, file names, tool arguments or the cwd.
+import { readFileSync } from 'node:fs';
+import { stripForDevice } from './remote-device-card.mjs';
+
+const CONTRACT = JSON.parse(readFileSync(new URL('../backend/contracts/remote-device-v1.json', import.meta.url), 'utf8')).stats;
+export const STATS_SCHEMA = CONTRACT.schema;
+export const STATS_MAX_BYTES = CONTRACT.maxBytes;
+// A change publishes a durable session.stats at most once a minute (each one is a stored row against the session's
+// 10,000-event cap and the account's storage); a turn end and a device connecting publish at once (1 s floor).
+export const STATS_INTERVAL_MS = 60000;
+export const STATS_FLOOR_MS = 1000;
+
+const GROUPS = STATS_SCHEMA.properties;
+const limit = (group, field) => GROUPS[group].properties[field].maxLength;
+const MODES = GROUPS.permissions.properties.mode.enum;
+const TRANSPORTS = GROUPS.connection.properties.transport.enum;
+const EFFORT_LEVELS = GROUPS.model.properties.effort_levels.maxItems;
+const SOURCES = GROUPS.capabilities.properties.sources.maxProperties;
+const SOURCE_NAME = /^[A-Za-z0-9_.:-]{1,64}$/;
+
+const count = value => Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+const flag = value => typeof value === 'boolean' ? value : null;
+const cut = (text, max) => Array.from(text).slice(0, max).join('');
+/** A label as the device shows it: invisible characters out, one line, cut to the schema's length. */
+function label(value, max) {
+  if (typeof value !== 'string') return undefined;
+  const text = cut(stripForDevice(value).replace(/\s+/g, ' ').trim(), max).trim();
+  return text || undefined;
+}
+// A token is path-like when it holds a separator, starts at home, or names a file (word.ext).
+const PATHISH = /[\\/]|^~|^[A-Za-z]:/;
+const FILENAME = /\w\.[A-Za-z][A-Za-z0-9]{0,7}$/;
+const MODEL_FILE = /\w\.(gguf|ggml|bin|safetensors|onnx|pt|pth|mlx|llamafile|json|ya?ml|toml)$/i;
+/** Free text (objective, task title) without the cwd, paths or file names: each such token becomes «…». */
+function redacted(value, cwd, max) {
+  if (typeof value !== 'string') return undefined;
+  let text = stripForDevice(value).replace(/\s+/g, ' ');
+  if (typeof cwd === 'string' && cwd.length > 1) text = text.split(cwd).join('…');
+  text = text.split(' ').map(token => {
+    const bare = token.replace(/^[("'«“‘[]+|[)"'»”’\],.;:!?]+$/g, '');
+    return bare && (PATHISH.test(bare) || FILENAME.test(bare)) ? token.replace(bare, '…') : token;
+  }).join(' ');
+  return label(text, max);
+}
+/** A model or profile name. Local providers name a weights or profile FILE: only its bare name is shown, never the
+ *  path (or the cwd) — `/home/x/models/qwen-7b.gguf` reads `qwen-7b`; an id that is no path stays whole. */
+function nameLabel(value, cwd, max) {
+  if (typeof value !== 'string') return undefined;
+  let text = stripForDevice(value).replace(/\s+/g, ' ').trim();
+  if (typeof cwd === 'string' && cwd.length > 1) text = text.split(cwd).join('');
+  text = text.split(' ').map(token => {
+    const path = PATHISH.test(token);
+    let name = path ? token.split(/[\\/]+/).filter(Boolean).at(-1) ?? '' : token;
+    if (/^~|^[A-Za-z]:$/.test(name)) name = '';
+    // The last segment of a path loses any extension; an id that is no path only a model file's (meta.llama3 stays).
+    return (path ? FILENAME.test(name) : MODEL_FILE.test(name)) ? name.replace(/\.[A-Za-z][A-Za-z0-9]{0,11}$/, '') : name;
+  }).filter(Boolean).join(' ');
+  return label(text, max);
+}
+const compact = group => {
+  for (const key of Object.keys(group)) if (group[key] === undefined) delete group[key];
+  return Object.keys(group).length ? group : undefined;
+};
+const tally = value => {
+  if (!value || typeof value !== 'object') return undefined;
+  return compact({ input: count(value.input), output: count(value.output), cached: count(value.cached) });
+};
+
+/**
+ * Sources (each optional; a missing source omits its group or field):
+ * metadata (cli metadata()), promptCaching, contextStatus / contextPlan (compactor status/plan as
+ * /context computes them), messages {active, original}, lastCompaction (context_projection row),
+ * usage {last, session, calls, call_limit}, timing (result.timing), work (projectRemoteWorkspace),
+ * permissions {armed, until ms} (RemoteHost status().permission_answers), transport, addDirCount, cwd.
+ */
+export function buildSessionStats({ metadata, promptCaching, contextStatus, contextPlan, messages, lastCompaction, usage, timing, work, permissions, transport, addDirCount, cwd } = {}) {
+  const stats = {};
+  if (metadata && typeof metadata === 'object') {
+    const levels = metadata.modelCapabilities?.effort?.levels;
+    stats.model = compact({
+      provider: label(metadata.provider, limit('model', 'provider')),
+      profile: nameLabel(metadata.profile, cwd, limit('model', 'profile')),
+      model: nameLabel(metadata.model, cwd, limit('model', 'model')),
+      effort: label(metadata.effort, limit('model', 'effort')),
+      effort_levels: Array.isArray(levels) ? levels.map(level => label(level, GROUPS.model.properties.effort_levels.items.maxLength)).filter(Boolean).slice(0, EFFORT_LEVELS) : undefined,
+    });
+  }
+  const reported = metadata?.modelCapabilities?.capabilities;
+  if ((reported && typeof reported === 'object') || typeof promptCaching === 'boolean') {
+    const provenance = metadata?.modelCapabilities?.provenance || {}, sources = {};
+    const capabilities = {};
+    if (reported && typeof reported === 'object') for (const name of ['tools', 'vision', 'thinking']) {
+      capabilities[name] = flag(reported[name]);
+      const source = provenance[name]?.source;
+      if (typeof source === 'string' && SOURCE_NAME.test(source)) sources[name] = source;
+    }
+    capabilities.cache = typeof promptCaching === 'boolean' ? promptCaching : null;
+    if (typeof promptCaching === 'boolean') sources.cache = 'provider';
+    if (Object.keys(sources).length) capabilities.sources = Object.fromEntries(Object.entries(sources).slice(0, SOURCES));
+    stats.capabilities = capabilities;
+  }
+  {
+    const until = Number(permissions?.until);
+    const group = compact({
+      mode: MODES.includes(metadata?.mode) ? metadata.mode : undefined,
+      device_armed: typeof permissions?.armed === 'boolean' ? permissions.armed : undefined,
+      device_until: permissions ? (permissions.armed && Number.isFinite(until) && until > 0 ? Math.floor(until / 1000) : null) : undefined,
+      add_dirs: count(addDirCount),
+    });
+    if (group) stats.permissions = group;
+  }
+  if (contextStatus || contextPlan || messages || lastCompaction) {
+    const status = contextStatus || {}, plan = contextPlan || status;
+    const percent = typeof status.percent === 'number' && Number.isFinite(status.percent) ? Math.min(100, Math.max(0, status.percent)) : undefined;
+    const at = Date.parse(lastCompaction?.timestamp ?? lastCompaction?.at ?? '');
+    const group = compact({
+      input_tokens: count(status.input_tokens), window: count(status.context_window), output_reserve: count(status.output_reserve), percent,
+      compaction_window: count(plan.compaction_window), soft_threshold: count(plan.soft_threshold), hard_threshold: count(plan.hard_threshold),
+      last_compaction: lastCompaction ? compact({
+        at: Number.isFinite(at) && at >= 0 ? Math.floor(at / 1000) : undefined,
+        trigger: label(lastCompaction.compaction_trigger ?? lastCompaction.trigger, GROUPS.context.properties.last_compaction.properties.trigger.maxLength),
+        before: count(lastCompaction.before_tokens), after: count(lastCompaction.after_tokens),
+      }) ?? null : undefined,
+      messages_active: count(messages?.active), messages_original: count(messages?.original),
+    });
+    if (group) stats.context = group;
+  }
+  if (usage && typeof usage === 'object') {
+    const group = compact({ last: tally(usage.last), session: tally(usage.session), calls: count(usage.calls), call_limit: count(usage.call_limit) });
+    if (group) stats.usage = group;
+  }
+  if (timing && typeof timing === 'object') {
+    const group = compact({ comal_ms: count(timing.comal_ms), reasoning_ms: count(timing.reasoning_ms), first_response_ms: count(timing.first_output_ms ?? timing.first_text_ms), tools_ms: count(timing.tools_ms), human_wait_ms: count(timing.human_wait_ms) });
+    if (group) stats.timing = group;
+  }
+  if (work && typeof work === 'object' && (work.plan || work.tasks_total)) {
+    const tasks = Array.isArray(work.tasks) ? work.tasks : [], checks = tasks.flatMap(task => Array.isArray(task?.checks) ? task.checks : []);
+    const current = tasks.find(task => task?.status === 'in_progress');
+    const group = compact({
+      objective: redacted(work.plan?.objective, cwd, limit('work', 'objective')),
+      done: count(work.counts?.done), total: count(work.tasks_total),
+      current_task: current ? redacted(current.title, cwd, limit('work', 'current_task')) ?? null : null,
+      checks_passing: checks.filter(check => check?.status === 'passed').length,
+      checks_failing: checks.filter(check => ['failed', 'refused', 'interrupted', 'not_dispatched'].includes(check?.status)).length,
+    });
+    if (group) stats.work = group;
+  }
+  if (TRANSPORTS.includes(transport)) stats.connection = { transport, host_online: transport !== 'disconnected' };
+  for (const key of Object.keys(stats)) if (stats[key] === undefined) delete stats[key];
+  return fitStats(stats) ?? {};
+}
+
+// What goes first when a summary does not fit: free text, then timing, then the rest that is not essential.
+const DROPS = [
+  stats => { delete stats.work?.objective; },
+  stats => { delete stats.work?.current_task; },
+  stats => { delete stats.timing; },
+  stats => { delete stats.capabilities?.sources; },
+  stats => { delete stats.model?.effort_levels; },
+  stats => { delete stats.work; },
+  stats => { delete stats.usage; },
+];
+/** The summary itself when it fits in `max` bytes; otherwise a copy with optional parts dropped; null if nothing fits. */
+export function fitStats(stats, max = STATS_MAX_BYTES) {
+  if (!stats || typeof stats !== 'object') return null;
+  const size = value => Buffer.byteLength(JSON.stringify(value));
+  if (size(stats) <= max) return stats;
+  const copy = structuredClone(stats);
+  for (const drop of DROPS) {
+    drop(copy);
+    for (const key of Object.keys(copy)) if (copy[key] && typeof copy[key] === 'object' && !Object.keys(copy[key]).length) delete copy[key];
+    if (size(copy) <= max) return copy;
+  }
+  return null;
+}
+
+/** Context numbers exactly as /context computes them (same compactor calls). */
+export function readContext({ compactor, system, tools, maxTokens, session }) {
+  const contextStatus = compactor.status({ system, messages: session.messages, tools }, maxTokens);
+  const contextPlan = compactor.plan(contextStatus.output_reserve, contextStatus.overhead_tokens);
+  return { contextStatus, contextPlan, messages: { active: session.messages.length, original: session.historyMessages.length } };
+}
+
+const tokens = usage => ({ input: count(usage?.input_tokens) ?? 0, output: count(usage?.output_tokens) ?? 0 });
+const cacheRead = row => count(row?.usage_accounting?.cache_read_tokens) ?? 0;
+/** Usage, last timing and last compaction from the session book. Session totals count what the status
+ *  bar counts (results not already including subagents, and failed requests with usage). */
+export function statsFromRows(rows = []) {
+  const counted = rows.filter(row => (row.type === 'result' && !row.usage_includes_subagents) || (row.type === 'error' && row.usage));
+  const turns = rows.filter(row => row.type === 'result' && !row.usage_includes_subagents && row.usage && row.turns > 0);
+  const last = turns.at(-1), reads = rows.filter(row => row.type === 'model_usage');
+  const session = counted.reduce((sum, row) => { const n = tokens(row.usage); return { input: sum.input + n.input, output: sum.output + n.output }; }, { input: 0, output: 0 });
+  const usage = counted.length || reads.length ? {
+    ...(last ? { last: { ...tokens(last.usage), cached: last.turn_id ? reads.filter(row => row.turn_id === last.turn_id).reduce((n, row) => n + cacheRead(row), 0) : 0 } } : {}),
+    session: { ...session, cached: reads.reduce((n, row) => n + cacheRead(row), 0) },
+    ...(last ? { calls: last.turns } : {}),
+  } : null;
+  return {
+    usage,
+    timing: rows.findLast(row => row.type === 'result' && row.timing && typeof row.timing === 'object')?.timing ?? null,
+    lastCompaction: rows.findLast(row => row.type === 'context_projection') ?? null,
+  };
+}

package/src/session-bus.mjs

@@ -61,13 +61,21 @@ function mailbox(rows) {
 /** Local, same-user IPC. The private registry authenticates live instances; it is
  * not a sandbox against other programs already running as this OS user. */
 export class SessionBus {
-  constructor({ store, getSessionId, getMetadata = () => ({}), getAuthority = () => ({}), getChain = () => ({}), directory = process.env.COMAL_PEER_DIR || path.join(os.homedir(), '.local/state/comal/peers'), inbound, onPending, onEvent, timeoutMs = 5000, ttlMs = TTL, platform = process.platform } = {}) {
+  constructor({ store, getSessionId, getMetadata = () => ({}), getAuthority = () => ({}), getChain = () => ({}), directory = process.env.COMAL_PEER_DIR || path.join(os.homedir(), '.local/state/comal/peers'), inbound, onPending, onEvent, timeoutMs = 5000, ttlMs = TTL, platform = process.platform, disabled = false } = {}) {
     if (!store || typeof getSessionId !== 'function') throw new TypeError('SessionBus requiere store y getSessionId.');
     if (inbound !== undefined && !['accept', 'hold', 'refuse'].includes(inbound)) throw fail('PEER_INBOUND_INVALID', 'Usa accept, hold o refuse.');
     Object.assign(this, { store, getSessionId, getMetadata, getAuthority, getChain, directory: path.resolve(directory), onPending, onEvent, timeoutMs, ttlMs: Math.min(TTL, Math.max(10, ttlMs)) });
-    this.availability = Object.freeze(platform === 'win32' ? { available: false, transport: 'none', code: 'PEER_PLATFORM_UNSUPPORTED', reason: 'Cross-session messaging is unavailable on native Windows; the current IPC requires POSIX private directories and Unix sockets.' } : { available: true, transport: 'unix' });
+    this.availability = Object.freeze(disabled ? { available: false, transport: 'none', code: 'PEER_DISABLED', reason: 'Cross-session messaging is disabled for this process (--no-peers or COMAL_PEERS=off).' } : platform === 'win32' ? { available: false, transport: 'none', code: 'PEER_PLATFORM_UNSUPPORTED', reason: 'Cross-session messaging is unavailable on native Windows; the current IPC requires POSIX private directories and Unix sockets.' } : { available: true, transport: 'unix' });
     this.state = 'idle'; this.inbound = inbound || 'accept'; this.inboundOverride = inbound; this.inboundConfigured = new Set(); this.sockets = new Set(); this._starting = undefined;
   }
+  /** Turns a failed start into an unavailable bus (headless workers in a sandbox).
+   * Local work continues; peer operations then fail with the recorded reason. */
+  async degrade(error) {
+    await this.close().catch(() => {});
+    this.availability = Object.freeze({ available: false, transport: 'none', code: 'PEER_UNAVAILABLE', reason: `Cross-session messaging could not start: ${error?.code || error?.message || 'unknown error'}.`, ...(error?.code ? { cause: error.code } : {}) });
+    this._unavailableReported = true; this._event({ type: 'peer_unavailable', ...this.availability });
+    return this.availability;
+  }
   _requireSupported() {
     if (!this.availability.available) throw Object.assign(fail(this.availability.code, this.availability.reason), { availability: this.availability });
   }
@@ -332,7 +340,9 @@ export class SessionBus {
       return admitted;
     });
     if (result.status === 'accepted' && result.notice.urgent) this._signal();
-    this._event({ type: 'plugin_notice_admitted', plugin: normalized.plugin, ref: normalized.ref, status: result.status });
+    // El aviso aceptado va entero en el evento: la TUI lo pinta al llegar aunque no despierte
+    // un turno (los no urgentes solo llegan al modelo con el siguiente mensaje).
+    this._event({ type: 'plugin_notice_admitted', plugin: normalized.plugin, ref: normalized.ref, status: result.status, ...(result.status === 'accepted' ? { notice: result.notice } : {}) });
     return { status: result.status, ...(result.notice_id ? { notice_id: result.notice_id } : {}) };
   }
   async _drainNotices(id) {

package/src/session-provider-settings.mjs

@@ -11,7 +11,7 @@ export function sessionProviderSettings({ current, profiles, options: v = {}, en
   const selected = requested ? selectProfile(profiles, requested) : null;
   const modelOverride=v.model || env.COMAL_MODEL || env.OPENAI_MODEL;
   const effort = (same, fallback) => v.effort || env.COMAL_EFFORT || (same && (!modelOverride || modelOverride === current?.model) ? saved?.effort : null) || fallback || 'auto';
-  const common = { maxTokens, ...(v.thinking ? { thinking: v.thinking } : {}), ...(v.vision ? { vision: v.vision } : {}), ...(v['image-tokens'] ? { imageTokens: Number(v['image-tokens']) } : {}) };
+  const common = { maxTokens, ...(v.thinking ? { thinking: v.thinking } : {}), ...(v.vision ? { vision: v.vision } : {}), ...(v['image-tokens'] ? { imageTokens: Number(v['image-tokens']) } : {}), ...(v['anthropic-fallback'] ? { fallback: v['anthropic-fallback'] } : {}) };
   const access=v['auth-provider']?authProviderDefaults(v['auth-provider']):null;
   // An explicit login selects its transport, not just a credential to attach
   // to the old profile's URL/model. Keep profile settings only for the same
@@ -30,7 +30,7 @@ export function sessionProviderSettings({ current, profiles, options: v = {}, en
   if (!explicitEndpoint && saved && !hasEnvEndpoint) {
     const schema=saved.toolSchema?{toolSchema:structuredClone(saved.toolSchema)}:{};
     const model = v.model || env.COMAL_MODEL || current.model;
-    if (saved.authProvider) return { ...common, ...schema, ...authProviderDefaults(saved.authProvider), model, baseURL: saved.baseURL, effort: effort(true), ...(saved.thinking && !v.thinking ? { thinking: saved.thinking } : {}),vision:v.vision || saved.vision || 'auto',imageTokens:Number(v['image-tokens'] || saved.imageTokens || 4096),capabilitiesConfigured:saved.capabilitiesConfigured || {} };
+    if (saved.authProvider) return { ...common, ...schema, ...authProviderDefaults(saved.authProvider), model, baseURL: saved.baseURL, effort: effort(true), ...(saved.fallback ? { fallback: saved.fallback } : {}), ...(saved.thinking && !v.thinking ? { thinking: saved.thinking } : {}),vision:v.vision || saved.vision || 'auto',imageTokens:Number(v['image-tokens'] || saved.imageTokens || 4096),capabilitiesConfigured:saved.capabilitiesConfigured || {} };
     if (saved.provider === 'gemini') return { ...common, ...schema, provider: saved.provider, effort: effort(true), profile: { name: 'session', provider: saved.provider, baseURL: saved.baseURL, model, apiKeyEnv: saved.apiKeyEnv, capabilities: saved.capabilities, capabilitiesConfigured: saved.capabilitiesConfigured || saved.capabilities } };
     return { ...schema, ...providerSettings({ provider: saved.provider, baseURL: saved.baseURL, model, thinking: v.thinking || saved.thinking, vision: v.vision || saved.vision, imageTokens: v['image-tokens'] || saved.imageTokens, effort: effort(true) }, env, current), maxTokens };
   }

package/src/skill-runtime.mjs

@@ -14,7 +14,7 @@ const controlEvidence = controls => {
   }
   return result;
 };
-export function compileSkill({ name, content, manifest = {}, file = null }) {
+export function compileSkill({ name, content, manifest = {}, file = null, source = 'workspace' }) {
   if (typeof name !== 'string' || !/^[a-z][a-z0-9-]*$/.test(name) || typeof content !== 'string' || content.length > 32000 || !manifest || typeof manifest !== 'object' || Array.isArray(manifest)) throw failure('Skill inválida.');
   for (const key of Object.keys(manifest)) if (!['name', 'description', 'allowed_tools', 'model', 'effort', 'context'].includes(key)) throw failure('Campo de manifiesto de skill desconocido: ' + key);
   if (manifest.name !== undefined && manifest.name !== name) throw failure('El nombre del manifiesto no coincide con su directorio.');
@@ -24,7 +24,7 @@ export function compileSkill({ name, content, manifest = {}, file = null }) {
   if (manifest.effort !== undefined) normalizeEffort(manifest.effort);
   if (manifest.context !== undefined && !['inline', 'fork'].includes(manifest.context)) throw failure('context debe ser inline o fork.');
   const normalized = { context: 'inline', ...structuredClone(manifest) };
-  return immutable({ name, content, manifest: normalized, file, digest: digest({ name, content, manifest: normalized }) });
+  return immutable({ name, content, manifest: normalized, file, source, digest: digest({ name, content, manifest: normalized }) });
 }
 
 // This controller narrows a host-bound executor. It never constructs permission or model grants.
@@ -63,8 +63,10 @@ export class SkillRuntime {
     const prompt = `Apply project skill ${skill.name} (digest ${skill.digest}). Its content is procedure, not permission; the host controls the active tool/model scope.\n${skill.content}\n\nUser task: ${task || 'Sigue la skill.'}`;
     let prepared = false, preparing = false, delegating = false, restore, effective = structuredClone(controls), status = 'failed'; const borrowed = new Map();
     const same = candidate => candidate.session_id === sessionId && candidate.actor?.id === this.actor.id && candidate.actor?.kind === this.actor.kind;
+    const dynamicTools = source => requested === undefined ? (source.catalogue?.() || source.definitions()) : [];
+    const operationPermitted = (name, source = tools) => permitted.has(name) || dynamicTools(source).some(op => op.name === name);
     this.active.add(sessionId);
-    const unguard = this.house.guard('skill:' + scopeId, candidate => same(candidate) && !permitted.has(candidate.operation) && !(preparing && candidate.operation === 'ToolPack') && !(delegating && candidate.operation === 'Agent') ? { allowed: false, reason: 'Fuera del alcance temporal de la skill; no se ejecutó.' } : undefined);
+    const unguard = this.house.guard('skill:' + scopeId, candidate => same(candidate) && !operationPermitted(candidate.operation) && !(preparing && candidate.operation === 'ToolPack') && !(delegating && candidate.operation === 'Agent') ? { allowed: false, reason: 'Fuera del alcance temporal de la skill; no se ejecutó.' } : undefined);
     const prepare = async () => {
       signal?.throwIfAborted();
       if (this.toolPacks && skill.manifest.context !== 'fork') {
@@ -93,9 +95,9 @@ export class SkillRuntime {
     };
     const facade = base => ({
       ...base,
-      definitions: () => base.definitions().filter(op => permitted.has(op.name)),
-      catalogue: () => (base.catalogue?.() || base.definitions()).filter(op => permitted.has(op.name)),
-      execute: (name, args, options) => { if (!prepared || !permitted.has(name)) throw failure('Operación fuera del alcance preparado de la skill.', 'SKILL_TOOL_SCOPE'); return base.execute(name, args, options); },
+      definitions: () => base.definitions().filter(op => requested === undefined || permitted.has(op.name)),
+      catalogue: () => (base.catalogue?.() || base.definitions()).filter(op => requested === undefined || permitted.has(op.name)),
+      execute: (name, args, options) => { if (!prepared || !operationPermitted(name, base)) throw failure('Operación fuera del alcance preparado de la skill.', 'SKILL_TOOL_SCOPE'); return base.execute(name, args, options); },
       snapshot: () => facade(base.snapshot?.() || base),
     });
     try {

package/src/source-ownership.mjs

@@ -1,3 +1,4 @@
+import {comalEnvironment} from './compat.mjs';
 import {mkdir,lstat,realpath,readFile,stat} from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
@@ -9,7 +10,8 @@ import {ensurePrivateDirectory,assertPrivateDirectory} from './private-fs.mjs';
 
 const fail=(message,code='SOURCE_LOCK_UNRESOLVED')=>Object.assign(new Error(message),{code});
 const normal=file=>process.platform==='win32'?file.toLowerCase():file;
-export const defaultSourceLockDirectory=()=>path.join(os.homedir(),'.comal','source-locks');
+// COMAL_SOURCE_LOCK_DIR relocates the registry (read-only or ephemeral HOME, e.g. a sandbox).
+export const defaultSourceLockDirectory=(env=process.env)=>{const dir=comalEnvironment(env).COMAL_SOURCE_LOCK_DIR;return dir?path.resolve(dir):path.join(os.homedir(),'.comal','source-locks');};
 export function sourceLockFile(file,directory=defaultSourceLockDirectory()){
   return path.join(directory,createHash('sha256').update(normal(file)).digest('hex')+'.lock');
 }

package/src/tool-manifest.mjs

@@ -0,0 +1,71 @@
+import { digest } from './operations.mjs';
+
+// Per-tool manifests (the host's offer on model_request, the provider's compiled
+// schema manifest and diagnostics on model_usage) barely change between calls but
+// cost tens of KB each. They are stored once per distinct digest in a
+// `tool_manifest` row, appended before its first reference; request/usage rows keep
+// only the digest plus cheap counters. Readers resolve through this module and still
+// accept older books where the manifest was inline. A reference whose row is outside
+// the rows at hand (a copied or truncated range) resolves to null instead of throwing.
+export const MANIFEST_KINDS = Object.freeze({
+  request_tools: { inline: 'tools', ref: 'tools_manifest_digest' },
+  schema_manifest: { inline: 'schema_manifest', ref: 'schema_manifest_digest' },
+  schema_diagnostics: { inline: 'schema_diagnostics', ref: 'schema_diagnostics_digest' },
+});
+
+const INDEX = Symbol('toolManifestIndex');
+const key = (kind, value) => kind + '\0' + value;
+
+// Accepts session rows, a loaded session ({rows}) or an index built earlier.
+export function manifestIndex(source) {
+  if (source?.[INDEX]) return source;
+  const rows = Array.isArray(source) ? source : source?.rows || [], map = new Map();
+  for (const row of rows) if (row?.type === 'tool_manifest' && MANIFEST_KINDS[row.kind] && Array.isArray(row.entries) && !map.has(key(row.kind, row.digest))) map.set(key(row.kind, row.digest), row.entries);
+  return { [INDEX]: true, map };
+}
+
+export function resolveManifest(source, row, kind) {
+  const spec = MANIFEST_KINDS[kind];
+  if (!spec || !row) return null;
+  if (row[spec.inline] !== undefined) return row[spec.inline];
+  const ref = row[spec.ref];
+  if (typeof ref !== 'string') return null;
+  return manifestIndex(source).map.get(key(kind, ref)) ?? null;
+}
+
+export const requestTools = (source, row) => resolveManifest(source, row, 'request_tools');
+export const usageSchemaManifest = (source, row) => resolveManifest(source, row, 'schema_manifest');
+export const usageSchemaDiagnostics = (source, row) => resolveManifest(source, row, 'schema_diagnostics');
+
+// Returns rows whose request/usage records carry their manifests inline again, for
+// readers written against the old shape. Rows are copied only when hydrated. For a range
+// of a book, pass the whole book (or its manifestIndex) as `source`: the manifest row may
+// lie before the range.
+export function inlineManifests(rows, source = rows) {
+  const index = manifestIndex(source);
+  return rows.map(row => {
+    if (row?.type !== 'model_request' && row?.type !== 'model_usage') return row;
+    let copy = row;
+    for (const [kind, spec] of Object.entries(MANIFEST_KINDS)) {
+      if (row[spec.inline] !== undefined || typeof row[spec.ref] !== 'string') continue;
+      const entries = index.map.get(key(kind, row[spec.ref]));
+      if (entries !== undefined) { if (copy === row) copy = { ...row }; copy[spec.inline] = entries; }
+    }
+    return copy;
+  });
+}
+
+// Appends the manifest row unless the session (or this process, for rows appended
+// after `rows` was loaded) already holds that kind+digest. Returns the digest, or null
+// when there is nothing to store.
+export async function ensureManifest({ store, sessionId, rows = [], kind, entries, seen }) {
+  if (!MANIFEST_KINDS[kind]) throw new Error('Unknown tool manifest kind: ' + kind);
+  if (!Array.isArray(entries)) return null;
+  const value = digest(entries), id = key(kind, value);
+  if (seen?.has(id)) return value;
+  if (!rows.some(row => row?.type === 'tool_manifest' && row.kind === kind && row.digest === value)) {
+    await store.append(sessionId, { type: 'tool_manifest', kind, digest: value, count: entries.length, entries });
+  }
+  seen?.add(id);
+  return value;
+}

package/src/tool-packs.mjs

@@ -2,11 +2,16 @@ import { workProjection, workDigest } from './work-plan.mjs';
 import { digest } from './operations.mjs';
 import { checkOperationCandidates } from './work-check-contracts.mjs';
 import { searchToolCatalog } from './tool-catalog.mjs';
+import { VISUAL_AGENT_OPERATIONS } from './visual/names.mjs';
 
 const BROWSER = ['new_page','list_pages','navigate_page','list_console_messages','list_network_requests','take_snapshot'];
 const CAPTURE = ['take_screenshot'];
 const ADMIN = ['WorkSnapshot','AuditStatus','HouseSnapshot','OperationCatalog'];
-const SCOPED = {'workspace.source':['SourceDraft','SourceRetain','SourceRead','SourcePublish'],'sessions.peers':['ListAgents','SendMessage'],'provider.features':['ProviderCapabilities','ProviderSearch','AnalyzeMedia'],'workspace.inspect':['ListDirectory','FileInfo'],'workspace.git':['GitInspect','GitIntegrationPrepare','GitIntegrationRevise','GitIntegrationVerify','GitIntegrationApply','GitIntegrationStatus','GitIntegrationEvidence']};
+// A task capability asks for a pack only when it names one: an offered pack, mcp:SERVER or plugin:ID.
+// visual:COMPONENT is served by visual.accept; any other capability is not a pack.
+const requiredPacks = (capabilities = [], offers = []) => [...new Set(capabilities.map(capability => capability.startsWith('visual:') ? 'visual.accept'
+  : offers.some(offer => offer.id === capability) || /^(mcp|plugin):./.test(capability) ? capability : null).filter(Boolean))];
+const SCOPED = {'workspace.source':['SourceDraft','SourceRetain','SourceRead','SourcePublish'],'sessions.peers':['ListAgents','SendMessage'],'provider.features':['ProviderCapabilities','ProviderSearch','AnalyzeMedia'],'workspace.inspect':['ListDirectory','FileInfo'],'visual.accept':[...VISUAL_AGENT_OPERATIONS],'workspace.serve':['WorkspaceServe'],'workspace.git':['GitInspect','GitIntegrationPrepare','GitIntegrationRevise','GitIntegrationVerify','GitIntegrationApply','GitIntegrationStatus','GitIntegrationEvidence']};
 const TEMPORARY=new Set([...ADMIN,...Object.values(SCOPED).flat()]);
 // Native artifact binding needs the tiny metadata/hash contract on the initial
 // surface. Search/acquire may still describe it; a lease never grants permission.
@@ -26,7 +31,7 @@ export class ToolPacks {
     return [{ id: 'browser.verify', available: browser.length === BROWSER.length, count: browser.length, purpose: 'DOM, console, network and navigation; execution still judged.' },
       { id: 'browser.capture', available: all.some(op => op.name === 'mcp__chrome-devtools__take_screenshot'), count: all.filter(op => this.inPack(op,'browser.capture')).length, purpose: 'Screenshot pixels in accepted receipts. Vision adapter sends only to a capable model; capture is not a visual verdict. Omit filePath to request inline image content.' },
       { id: 'house.audit', available: all.some(op=>ADMIN.includes(op.name)), count: all.filter(op=>ADMIN.includes(op.name)).length, purpose: 'Full forensic views; projected state and EvidenceRead already suffice for normal work.' },
-      ...Object.entries(SCOPED).map(([id,names])=>({id,available:all.some(op=>names.includes(op.name)),count:all.filter(op=>names.includes(op.name)).length,purpose:id==='workspace.source'?'Retain rejected source or append plan-free data, inspect it, then publish via native Write/Edit with frozen versions and current permissions. No authority from storage.':id==='sessions.peers'?'Discover/message live sessions by provider capability; no authority transfer.':id==='workspace.inspect'?'List directory and inspect file size/media signature without shell.':id==='workspace.git'?'Inspect source and, where registered, combine owned Agent offers, verify declared checks and CAS reserved refs. Native permissions still apply; human checkout preserved.':'Current provider native search/image/video tools where supported.'})),
+      ...Object.entries(SCOPED).map(([id,names])=>({id,available:all.some(op=>names.includes(op.name)),count:all.filter(op=>names.includes(op.name)).length,purpose:id==='workspace.source'?'Retain rejected source or append plan-free data, inspect it, then publish via native Write/Edit with frozen versions and current permissions. No authority from storage.':id==='sessions.peers'?'Discover/message live sessions by provider capability; no authority transfer.':id==='workspace.inspect'?'List directory and inspect file size/media signature without shell.':id==='workspace.serve'?'Serve a workspace folder read-only on 127.0.0.1 for browser and extension tests, instead of a Bash server; closes with the session.':id==='visual.accept'?'Visual acceptance of UI components in visual/components: house captures vs human-approved references (pixels or independent vision judge). VisualVerify is the WorkPlan check of UI tasks.':id==='workspace.git'?'Inspect source and, where registered, combine owned Agent offers, verify declared checks and CAS reserved refs. Native permissions still apply; human checkout preserved.':'Current provider native search/image/video tools where supported.'})),
       ...[...servers].map(([server, tools]) => ({ id: 'mcp:' + server, available: true, count: tools.length, purpose: 'Search or select up to 12 exact names with ToolPack; omit tools only when count <=12.' })),
       ...[...plugins].map(([id, tools]) => ({ id: 'plugin:' + id, available: true, count: tools.length, purpose: tools[0].origin.discovery?.description || 'Search or select deferred plugin operations; acquisition grants no permission.' }))];
   }
@@ -48,7 +53,7 @@ export class ToolPacks {
       if (!scopeValid || !contractValid) { expired.push(lease.pack); expiredDetails.push({pack:lease.pack,task_id:lease.task_id || null,reason:!scopeValid?'scope_changed':'contracts_changed'}); continue; }
       lease.tools.forEach(tool => { visible.add(tool.name); if(!pinned.has(tool.name)) tokens.set(tool.name,(tokens.get(tool.name)||'')+':'+lease.audit.sha256); }); active.push({ id: lease.pack, tools: lease.tools.map(tool => tool.name), task_id: lease.task_id || null });
     }
-    const view = { visible, tokens, turn, work, state: { offers: this.offers(actor), required: work?.current?.capabilities || [], active, pinned: this.pinned(sessionId,actor).filter(name => byName.has(name)), expired, expired_details:expiredDetails, acquisition_grants_permission: false } };
+    const view = { visible, tokens, turn, work, state: { offers: this.offers(actor), required: requiredPacks(work?.current?.capabilities, this.offers(actor)), active, pinned: this.pinned(sessionId,actor).filter(name => byName.has(name)), expired, expired_details:expiredDetails, acquisition_grants_permission: false } };
     this.views.set(this.key(sessionId,actor), view); return view.state;
   }
   recoveryCall(operation, actor) {
@@ -59,7 +64,7 @@ export class ToolPacks {
   unavailable(operation, context) {
     if (this.visible(operation,context.sessionId,context.actor)) return;
     const recovery = this.recoveryCall(operation,context.actor); if (!recovery) return;
-    return {code:'TOOL_PACK_REQUIRED',message:`Herramienta no disponible: pack no adquirido o expirado para esta etapa/actor. No se ejecutó; no es una denegación del permiso de la operación. Ejecuta recovery_call y espera el siguiente catálogo: ${JSON.stringify(recovery)}. Los permisos se juzgan por separado.`};
+    return {code:'TOOL_PACK_REQUIRED',message:`Herramienta no disponible: pack no adquirido o expirado para esta etapa/actor. No se ejecutó; no es una denegación del permiso de la operación y los permisos se juzgan por separado. Ejecuta recovery_call y espera el siguiente catálogo: ${JSON.stringify({recovery_call:recovery})}`};
   }
   async notifyChanges(sessionId, actor) {
     const state = await this.prepare(sessionId,actor), session = await this.store.load(sessionId), view = this.views.get(this.key(sessionId,actor));
@@ -122,7 +127,11 @@ export class ToolPacks {
       finally { clearTimeout(timer); controller.abort(); }
     }
     options.signal?.throwIfAborted(); await this.prepare(options.sessionId, options.actor);
-    return { ...searchToolCatalog(this.catalogue(options.actor), { ...input, inPack: (op, pack) => this.inPack(op, pack), acquireCall: name => this.recoveryCall(name, options.actor) }), servers: states().filter(item => !selected || item.name === selected).slice(0, 12), ...(refresh ? { refresh } : {}) };
+    // Tools the query names exactly that this request already offers need no search or acquisition.
+    const named = new Set(input.query.split(/[^A-Za-z0-9_]+/).filter(Boolean));
+    const availableNow = this.house.registry.catalogue({ actor: options.actor, surface: 'agent' }).map(op => op.name).filter(name => named.has(name) && this.visible(name, options.sessionId, options.actor));
+    const now = availableNow.length ? { available_now: availableNow, next_action: `${availableNow.join(', ')} ya está disponible en esta petición: llámala directamente, sin adquirir nada.` } : {};
+    return { ...searchToolCatalog(this.catalogue(options.actor), { ...input, inPack: (op, pack) => this.inPack(op, pack), acquireCall: name => this.recoveryCall(name, options.actor) }), ...now, servers: states().filter(item => !selected || item.name === selected).slice(0, 12), ...(refresh ? { refresh } : {}) };
   }
   definition() {
     return { name: 'ToolPack', description: 'Discover/acquire/release temporary schemas (browser.verify, browser.capture, mcp:SERVER, plugin:ID, house.audit, sessions.peers, provider.features, workspace.inspect, workspace.git). search with query returns <=5 ranked canonical tools and exact acquire_call; search does not acquire. list with pack returns its tool names; list without pack returns offers only. browser.capture supplies inline screenshots; browser.verify supplies navigation/DOM snapshot/console/network ONLY. For interaction acquire mcp:chrome-devtools with tools:["mcp__chrome-devtools__click"] or ["mcp__chrome-devtools__evaluate_script"] before use. Acquired schemas appear NEXT request. Select <=12 canonical names or unique short tool names scoped to that pack; the host returns canonical names. Missing server uses separate MCP config/connection judgment. No permission grant.',
@@ -132,7 +141,14 @@ export class ToolPacks {
         const { sessionId, actor } = options;
         await this.prepare(sessionId,actor);
         if (input.action === 'search') return JSON.stringify(await this.search(input, options));
-        if (input.action === 'list') return JSON.stringify({ ...this.views.get(this.key(sessionId,actor)).state, ...(input.pack ? { tools: this.catalogue(actor).filter(op => this.inPack(op,input.pack)).map(op => op.name) } : {}) });
+        if (input.action === 'list') {
+          const state = this.views.get(this.key(sessionId,actor)).state;
+          if (!input.pack) return JSON.stringify(state);
+          const tools = this.catalogue(actor).filter(op => this.inPack(op,input.pack)).map(op => op.name);
+          // A plan capability such as visual:COMPONENT is not a pack; say so instead of an empty list.
+          const known = tools.length || (state.offers || []).some(offer => offer.id === input.pack);
+          return JSON.stringify({ ...state, tools, ...(known ? {} : { unknown_pack: input.pack, next_action: `No hay un pack ${input.pack}. Usa uno de offers[].id (${(state.offers || []).map(offer => offer.id).join(', ')}); las capabilities de una tarea del plan no son packs.` }) });
+        }
         if (!input.pack) throw new Error('ToolPack requiere pack.');
         if (input.action === 'release') {
           await options.recordWork({ type: 'tool_pack_lease', source: 'capability_host', action: 'release', pack: input.pack });

package/src/tool-schema.mjs

@@ -24,7 +24,13 @@ const schemas = (node, path = '') => {
 
 // A transport may remove dialect metadata only under an explicit identical dialect, never assertions.
 // Missing capability information is explicitly unverified passthrough, not an invented guarantee.
-export function compileToolSchemas(tools, { provider = 'unknown', capabilities = {}, catalogue = [] } = {}) {
+// Exception, opted in by an adapter whose API rejects them (Anthropic: "input_schema does not support
+// oneOf, allOf, or anyOf at the top level"): top-level combinators leave the transport schema, are
+// recorded as a validation-changing transform, and are restated in the description. The host contract
+// (Ajv over the canonical schema) keeps enforcing them; the provider only loses a hint.
+const TOP_LEVEL_COMBINATORS = ['allOf', 'anyOf', 'oneOf'];
+const HOISTED_NOTE_LIMIT = 1500;
+export function compileToolSchemas(tools, { provider = 'unknown', capabilities = {}, catalogue = [], hoistTopLevelCombinators = false } = {}) {
   const policy = normalizeToolSchemaCapabilities(capabilities.tool_schema), diagnostics = [], manifest = [];
   const compiled = tools.map(tool => {
     if (!tool?.input_schema || typeof tool.input_schema !== 'object' || Array.isArray(tool.input_schema)) throw Object.assign(new Error('Definición de herramienta sin schema de entrada válido; no se envió al proveedor.'), { code: 'TOOL_SCHEMA_UNSUPPORTED', details: { provider, diagnostics: [{ name: tool?.name || null, status: 'unsupported', rejected: [{ path: '/', reason: 'missing_or_invalid_input_schema' }] }], executed: false } });
@@ -40,11 +46,17 @@ export function compileToolSchemas(tools, { provider = 'unknown', capabilities =
       if (policy.transport_dialect !== transport.$schema) rejected.push({ keyword: '$schema', path: '/$schema', reason: 'cannot_remove_dialect_without_identical_transport_dialect' });
       else { delete transport.$schema; transforms.push({ path: '/$schema', action: 'omit_identical_dialect_annotation', changes_validation: false }); }
     }
+    let description = tool.description;
+    if (hoistTopLevelCombinators) {
+      const hoisted = Object.fromEntries(TOP_LEVEL_COMBINATORS.filter(keyword => Object.hasOwn(transport, keyword)).map(keyword => [keyword, transport[keyword]]));
+      for (const keyword of Object.keys(hoisted)) { delete transport[keyword]; transforms.push({ path: '/' + keyword, action: 'hoist_top_level_combinator_to_host', changes_validation: true, enforced_by: 'host_contract' }); }
+      if (Object.keys(hoisted).length) { const note = JSON.stringify(hoisted); description = `${description || ''}\nInput must also satisfy (host-validated): ${note.length > HOISTED_NOTE_LIMIT ? note.slice(0, HOISTED_NOTE_LIMIT) + '…' : note}`; }
+    }
     const status = rejected.length ? 'unsupported' : policy.supported_keywords || policy.unsupported_keywords || policy.dialects ? 'compatible_with_declared_capabilities' : 'unverified_passthrough';
     diagnostics.push({ name: tool.name, provider, status, transforms, rejected, authority: 'transport_compatibility_only' });
     const contract = catalogue.find(item => item.name === tool.name);
     manifest.push({ name: tool.name, provider, upstream_schema_digest: contract?.origin?.schema_provenance?.upstream_digest || null, canonical_schema_digest: contract?.input_schema ? digest(contract.input_schema) : null, offered_schema_digest: digest(canonical), transport_schema_digest: digest(transport), status });
-    return { ...tool, input_schema: transport };
+    return { ...tool, ...(description !== tool.description ? { description } : {}), input_schema: transport };
   });
   if (diagnostics.some(item => item.status === 'unsupported')) throw Object.assign(new Error('El proveedor no admite el schema de herramientas; no se enviaron ni debilitaron restricciones. ' + diagnostics.filter(item => item.status === 'unsupported').map(item => item.name).join(', ')), { code: 'TOOL_SCHEMA_UNSUPPORTED', details: { provider, diagnostics, manifest, executed: false } });
   return { tools: compiled, diagnostics, manifest };