@milpa/comal 0.2.1 → 0.2.3

package/src/swarm-view.mjs

@@ -0,0 +1,53 @@
+// Fase 4 de open-relay: el host lleva al panel /swarm de la TUI la foto que el plugin
+// publica con ctx.provide('open-relay.swarm-view'). Sin turnos del modelo ni herramientas:
+// el plugin avisa (su vigilancia de events.wait vio un cambio), el host copia la foto como
+// datos planos y la pantalla la vuelve a limpiar al pintarla. Sólo se acepta el servicio si
+// su dueño es el plugin open-relay. Si el plugin no está, está apagado o falló, la vista lo
+// dice para que el panel explique por qué y cómo configurarlo.
+import { SWARM_VIEW_SERVICE } from './plugins/open-relay/panel.mjs';
+export { SWARM_VIEW_SERVICE };
+export const SWARM_VIEW_PLUGIN = 'open-relay';
+const MAX_BYTES = 512 * 1024;
+
+function plain(view) {
+  if (!view || typeof view !== 'object' || Array.isArray(view)) return null;
+  let text; try { text = JSON.stringify(view); } catch { return null; }
+  if (typeof text !== 'string' || Buffer.byteLength(text) > MAX_BYTES) return null;
+  return JSON.parse(text);
+}
+
+/** Por qué no hay foto, según el estado del plugin en el runtime. */
+export function swarmViewUnavailable(status, plugin = SWARM_VIEW_PLUGIN) {
+  const item = status?.plugins?.find(entry => entry.id === plugin);
+  if (!item) return { available: false, reason: 'not_configured' };
+  const reason = { disabled: 'disabled', pending_trust: 'pending_trust', failed: 'failed', loading: 'loading', registered: 'disabled', active: 'no_service' }[item.state] || 'disabled';
+  return { available: false, reason, ...(item.error ? { error: String(item.error).slice(0, 600) } : {}) };
+}
+
+/**
+ * Conecta el servicio con onView(view). Devuelve { refresh, close }. onView recibe
+ * { available:true, ...foto } o { available:false, reason, error? }.
+ */
+export function connectSwarmView({ plugins, onView, plugin = SWARM_VIEW_PLUGIN }) {
+  let bound, unsubscribe = null, closed = false, last = null;
+  const emit = view => { if (closed) return; const key = JSON.stringify(view); if (key === last) return; last = key; try { onView(view); } catch {} };
+  const bind = () => {
+    if (closed) return;
+    const service = plugins.service(SWARM_VIEW_SERVICE), value = service?.owner === plugin ? service.value : null;
+    if (value && value === bound) return;
+    try { unsubscribe?.(); } catch {}
+    unsubscribe = null; bound = value;
+    if (!value || typeof value.subscribe !== 'function' || typeof value.snapshot !== 'function') { emit(swarmViewUnavailable(plugins.status(), plugin)); return; }
+    const deliver = view => { if (closed || bound !== value) return; const copy = plain(view); emit(copy ? { ...copy, available: true } : { available: false, reason: 'invalid' }); };
+    try { unsubscribe = value.subscribe(deliver); deliver(value.snapshot()); }
+    catch (error) { emit({ available: false, reason: 'failed', error: String(error?.message || error).slice(0, 600) }); }
+  };
+  const stop = plugins.watchServices(bind);
+  bind();
+  return {
+    refresh: bind,
+    /** La foto actual, sin esperar al próximo aviso (p. ej. /swarm fuera de la TUI). */
+    current() { const service = plugins.service(SWARM_VIEW_SERVICE); if (service?.owner !== plugin) return swarmViewUnavailable(plugins.status(), plugin); try { const copy = plain(service.value.snapshot()); return copy ? { ...copy, available: true } : { available: false, reason: 'invalid' }; } catch (error) { return { available: false, reason: 'failed', error: String(error?.message || error).slice(0, 600) }; } },
+    close() { closed = true; stop(); try { unsubscribe?.(); } catch {} unsubscribe = null; },
+  };
+}

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 };

package/src/tools.mjs

@@ -1,14 +1,18 @@
+import { childEnvironment } from './child-env.mjs';
 import { readFile, writeFile, rename, link, unlink, mkdir, realpath, stat, lstat, readdir, opendir, open } from 'node:fs/promises';
 import { constants } from 'node:fs';
+import { holdsComalState } from './permissions.mjs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { House } from './house.mjs';
 import { readOnlyBashCheck } from './read-only-check.mjs';
+import { BASH_TIMEOUTS, bashTimeoutSchema, bashDescription } from './bash-timeouts.mjs';
 import { auditExecution } from './audit.mjs';
 import { digest } from './operations.mjs';
 import { recoverFileEffects } from './file-recovery.mjs';
 import { SourceOwnership } from './source-ownership.mjs';
+import { imageSignature, HUMAN_IMAGE_LIMIT } from './image-attachments.mjs';
 import { bindChromeSourceSyntax, chromeSourceSyntaxAdvice } from './chrome-source-syntax.mjs';
 import {SourceProposals,sourceDefinitions} from './source-proposals.mjs';
 import { registerNativeSourceRequests, nativeSourceRequestCapability, consumeNativeSourceRequest, settleNativeSourceRequest } from './source-requests.mjs';
@@ -29,7 +33,7 @@ export const toolDefinitions = [
   schema('ListDirectory', 'List one workspace directory without shell. Returns bounded names/types, not file contents; omits internal state. Use Glob for recursive matches.', { path: str('Workspace directory; defaults to .'), limit: { type: 'integer', minimum: 1, maximum: 1000 } }, []),
   schema('FileInfo', 'Inspect workspace file size/type and media signature without shell. By default reads at most 32 signature bytes. Set hash:true for bounded binary-safe full-file SHA-256 evidence (up to 256 MiB, 10 seconds); emits a file_read observation but grants no text inspection for editing. Does not decode media: send images/video directly to AnalyzeMedia.', { file_path: str('Workspace-relative or absolute path'), hash: { type: 'boolean', description: 'Stream the complete regular file to compute SHA-256 without returning contents.' }, allow_missing:{type:'boolean',description:'Return explicit absent metadata for a missing safe path; never treat a dangling symbolic link as absence.'}, max_bytes:{type:'integer',minimum:1,maximum:268435456,description:'Optional stricter hash byte limit; never increases the 256 MiB bound.'} }, ['file_path']),
   ...sourceDefinitions,
-  schema('Bash', 'Run a shell command from the workspace after permission. This is NOT an OS sandbox.', { command: str('Shell command'), timeout: { type: 'integer', minimum: 1, maximum: 120000 } }, ['command']),
+  schema('Bash', bashDescription(), { command: str('Shell command'), timeout: bashTimeoutSchema() }, ['command']),
 ];
 
 function validate(name, input) {
@@ -47,9 +51,9 @@ function validate(name, input) {
 }
 
 export class WorkspaceTools {
-  constructor({ cwd, policy, store, onPermission = () => {}, house = new House({ cwd }), actor = { id: 'local-agent', kind: 'agent' }, sessionId, record, select, frontier, capture, unavailable, sourceLockDirectory, nativeSourceRequests = false }) {
+  constructor({ cwd, policy, store, onPermission = () => {}, house = new House({ cwd }), actor = { id: 'local-agent', kind: 'agent' }, sessionId, record, select, frontier, capture, unavailable, sourceLockDirectory, nativeSourceRequests = false, imageReads }) {
     this.cwd = cwd; this.policy = policy; this.onPermission = onPermission; this.reads = new Map(); this.house = house;
-    this.store = store;
+    this.store = store; this.imageReads = imageReads;
     this.sourceOwnership = new SourceOwnership({cwd,store,directory:sourceLockDirectory});
     this.sourceProposals=new SourceProposals(this);this.nativeSettlers=new Set();
     for (const definition of toolDefinitions) if (!house.registry.get(definition.name)) nativeOperations.add(house.registry.add({ ...definition, run: (input, options) => sourceDefinitions.some(d=>d.name===definition.name)?(options.workspace||this).sourceProposals.execute(definition.name,input,options):(options.workspace || this).#run(definition.name, input, options) }));
@@ -66,18 +70,28 @@ export class WorkspaceTools {
   }
   setContext(context) { this.executor.setContext(context); }
   getMode() { return this.executor.getMode(); }
+  grantedByHuman(name) { return Boolean(this.executor.grantedByHuman?.(name)); }
   snapshot() { return this.executor.snapshot(); }
   execute(name, input, options) { return this.executor.execute(name, input, options); }
   isNativeOperation(name){return nativeOperations.has(this.house.registry.get(name));}
   nativeSourceRequestCapability(name){return this.executor.nativeSourceRequestCapability(name);}
   registerSettlement(handler){this.nativeSettlers.add(handler);return()=>this.nativeSettlers.delete(handler);}
   async settleOperation(outcome) { const results=await Promise.allSettled([settleNativeSourceRequest(this,outcome),this.sourceOwnership.settle(outcome),this.sourceProposals.settle(outcome),...[...this.nativeSettlers].map(fn=>fn(outcome))]);const failed=results.find(r=>r.status==='rejected');if(failed)throw failed.reason; }
-  recoverInterrupted({signal,session}={}) { return this.store && this.house.hasRecorder ? recoverFileEffects({store:this.store,house:this.house,executor:this.executor,sessionId:typeof this.recoverySessionId==='function'?this.recoverySessionId():this.recoverySessionId,actor:this.recoveryActor,signal,session}) : undefined; }
-  inside(file) { const relative = path.relative(this.cwd, file); return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative)); }
-  async resolve(file, { create = false } = {}) {
+  async recoverInterrupted({signal,session}={}) {
+    if(!this.store||!this.house.hasRecorder)return;
+    if(this.codeRunSessionRecovery){await this.codeRunSessionRecovery.recover({signal});session=undefined;}
+    return recoverFileEffects({store:this.store,house:this.house,executor:this.executor,sessionId:typeof this.recoverySessionId==='function'?this.recoverySessionId():this.recoverySessionId,actor:this.recoveryActor,signal,session});
+  }
+  inside(file, root = this.cwd) { const relative = path.relative(root, file); return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative)); }
+  /** --add-dir: directorio de solo lectura que contiene `file`, o null. */
+  readRootOf(file) { return (this.policy?.readRoots || []).find(root => this.inside(file, root)) || null; }
+  /** /add-dir: read+write directory the human opened that contains `file`, or null. */
+  workRootOf(file) { return (this.policy?.workRoots || []).find(root => this.inside(file, root)) || null; }
+  async resolve(file, { create = false, read = false } = {}) {
     if (!file || file.includes('\0')) throw new Error('Invalid path.');
     const candidate = path.resolve(this.cwd, file);
-    if (!this.inside(candidate)) throw new Error('Path outside the workspace.');
+    const readable = read && !create; // las raíces de --add-dir solo valen para leer
+    if (!this.inside(candidate) && !this.workRootOf(candidate) && !(readable && this.readRootOf(candidate))) throw new Error('Path outside the workspace.');
     let canonical;
     try { canonical = await realpath(candidate); }
     catch (e) {
@@ -88,10 +102,14 @@ export class WorkspaceTools {
         catch (err) { if (err.code !== 'ENOENT') throw err; suffix.unshift(path.basename(ancestor)); ancestor = path.dirname(ancestor); }
       }
     }
-    if (!this.inside(canonical)) throw new Error('The symbolic link leaves the workspace.');
+    const workRoot = this.workRootOf(canonical);
+    if (!this.inside(canonical) && !workRoot && !(readable && this.readRootOf(candidate) && this.inside(canonical, this.readRootOf(candidate)))) throw new Error('The symbolic link leaves the workspace.');
     if (this.sourceOwnership.contains(canonical)) throw new Error('Native source ownership state is protected.');
     const first = path.relative(this.cwd, canonical).split(path.sep)[0];
     if (['.comal', '.harness'].includes(first)) throw new Error('Comal internal state is protected.');
+    // An added directory may be another Comal workspace: its state stays off-limits too.
+    if (workRoot && holdsComalState(workRoot, canonical)) throw new Error('Comal internal state is protected.');
+    if (workRoot && this.policy?.isPrivate?.(canonical)) throw new Error('Path protected: private Comal location or a path an active plugin protects.');
     return canonical;
   }
   async text(file) {
@@ -135,7 +153,7 @@ export class WorkspaceTools {
   async #run(name, input, { signal, actor, sessionId, invocation_id, revalidate, nativeSourceRequest, observe = () => {}, recordWork = async () => {} } = {}) {
     validate(name, input); signal?.throwIfAborted();
     if (name === 'ListDirectory') {
-      const dir = await this.resolve(input.path || '.'), entries = []; let truncated = false, bytes = 0;
+      const dir = await this.resolve(input.path || '.', { read: true }), entries = []; let truncated = false, bytes = 0;
       for await (const entry of await opendir(dir)) {
         signal?.throwIfAborted();
         if (['.git', '.comal', '.harness', '.analysis'].includes(entry.name)) continue;
@@ -150,7 +168,7 @@ export class WorkspaceTools {
       return JSON.stringify({ path: relative, entries, truncated });
     }
     if (name === 'FileInfo') {
-      const file = await this.resolve(input.file_path,{create:Boolean(input.allow_missing)});let info;
+      const file = await this.resolve(input.file_path,{create:Boolean(input.allow_missing),read:true});let info;
       try{info=await stat(file,input.hash?{bigint:true}:undefined);}catch(error){
         if(error.code!=='ENOENT'||!input.allow_missing)throw error;
         // ENOENT through a dangling link is not an absent entry.
@@ -184,7 +202,22 @@ export class WorkspaceTools {
       return JSON.stringify(result);
     }
     if (name === 'Read') {
-      const file = await this.resolve(input.file_path), text = await this.text(file);
+      const file = await this.resolve(input.file_path, { read: true });
+      // With a vision-capable model, Read of a PNG/JPEG/WebP returns the image as an
+      // MCP-style image block. Its text projection keeps only a digest reference, and
+      // the vision pipeline attaches the receipt's pixels to the next request.
+      if (typeof this.imageReads === 'function' && await this.imageReads()) {
+        const info = await stat(file);
+        if (info.isFile() && info.size > 0 && info.size <= HUMAN_IMAGE_LIMIT) {
+          const bytes = await readFile(file), mimeType = imageSignature(bytes);
+          if (mimeType) {
+            const sha256 = createHash('sha256').update(bytes).digest('hex');
+            observe({ kind: 'file_read', file_path: path.relative(this.cwd, file), sha256, media_type: mimeType });
+            return JSON.stringify({ file_path: path.relative(this.cwd, file), media_type: mimeType, bytes: bytes.length, sha256, content: [{ type: 'image', mimeType, data: bytes.toString('base64') }], note: 'Image read natively; the pixels reach the model in the next request as recorded evidence.' });
+          }
+        }
+      }
+      const text = await this.text(file);
       this.reads.set(file, hash(text));
       observe({ kind: 'file_read', file_path: path.relative(this.cwd, file), sha256: hash(text) });
       const offset = input.offset ?? 1, count = input.limit ?? 400;
@@ -243,7 +276,7 @@ export class WorkspaceTools {
     }
     if (name === 'Bash') {
       const check = readOnlyBashCheck(input.command);
-      if (!check) return runProcess('/bin/sh', ['-c', input.command], { cwd: this.cwd, timeout: input.timeout ?? 30000, signal, observe });
+      if (!check) return runProcess('/bin/sh', ['-c', input.command], { cwd: this.cwd, timeout: input.timeout ?? BASH_TIMEOUTS.defaultMs, signal, observe });
       const files = new Map();
       for (const name of check.files) { const file = await this.resolve(name); files.set(name, { file, before: hash(await this.text(file)) }); }
       let output = '';
@@ -251,7 +284,7 @@ export class WorkspaceTools {
         if (step.kind === 'echo') output += step.text + '\n';
         else {
           let text;
-          try { text = await runProcess('/usr/bin/grep', [...step.flags, '--', step.pattern, files.get(step.file).file], { cwd: this.cwd, timeout: input.timeout ?? 30000, signal }); }
+          try { text = await runProcess('/usr/bin/grep', [...step.flags, '--', step.pattern, files.get(step.file).file], { cwd: this.cwd, timeout: input.timeout ?? BASH_TIMEOUTS.defaultMs, signal }); }
           catch (error) { if (error.message.startsWith('Command exited with code 1:')) throw Object.assign(new Error(`${error.message} Pattern ${JSON.stringify(step.pattern)} did not match in ${JSON.stringify(step.file)}. Implement the criterion behavior; a text match is only a basic check.`), { code: 'CHECK_FAILED' }); throw error; }
           if (text !== '(no output)') output += text;
         }
@@ -260,24 +293,46 @@ export class WorkspaceTools {
       return output || '(no output)';
     }
     if (name === 'Grep') {
-      const target = await this.resolve(input.path || '.');
+      const target = await this.resolve(input.path || '.', { read: true });
       return runProcess('rg', ['--line-number', '--no-heading', '--color', 'never', '--max-count', '100', '--glob', '!.comal/**', '--glob', '!.harness/**', '--glob', '!.analysis/**', ...(input.glob ? ['--glob', input.glob] : []), '--', input.pattern, target], { cwd: this.cwd, timeout: 10000, signal, allowNoMatch: true });
     }
     if (name === 'Glob') {
-      if (path.isAbsolute(input.pattern) || input.pattern.split('/').includes('..')) throw new Error('Glob must be relative to the workspace.');
-      const pattern = input.pattern.replace(/^\.\//, ''), matcher = globRegex(pattern), files = []; let visited = 0;
+      // --add-dir: un patrón absoluto bajo un directorio de solo lectura recorre ese directorio y devuelve rutas absolutas.
+      // A relative pattern whose literal prefix (before the first wildcard) resolves under an --add-dir becomes absolute.
+      let requested = input.pattern;
+      if (!path.isAbsolute(requested) && requested.split('/').includes('..')) {
+        const parts = requested.split('/'), wild = parts.findIndex(part => /[*?[{]/.test(part)), literal = wild < 0 ? parts : parts.slice(0, wild), rest = wild < 0 ? [] : parts.slice(wild);
+        if (!rest.includes('..') && rest.length) requested = [path.resolve(this.cwd, ...literal), ...rest].join('/');
+      }
+      const root = path.isAbsolute(requested) ? [...(this.policy?.workRoots || []), ...(this.policy?.readRoots || [])].find(dir => requested.startsWith(dir + '/')) : null;
+      if ((path.isAbsolute(requested) && !root) || requested.split('/').includes('..')) throw new Error('Glob must be relative to the workspace or under an added directory (/add-dir or --add-dir).');
+      const base = root || this.cwd, show = file => root ? file : path.relative(this.cwd, file).split(path.sep).join('/');
+      const pattern = (root ? requested.slice(root.length + 1) : requested).replace(/^\.\//, ''), matcher = globRegex(pattern), files = []; let visited = 0;
+      // Enter only directories that can still lead to a match; `**` matches any depth below it.
+      const segments = pattern.split('/').map(part => part.includes('**') ? null : globRegex(part));
+      const canEnter = parts => { for (let i = 0; i < parts.length; i++) { if (i >= segments.length) return false; if (!segments[i]) return true; if (!segments[i].test(parts[i])) return false; } return parts.length < segments.length; };
       const walk = async (dir, depth = 0) => {
         if (depth > 30) return;
         for (const entry of await readdir(dir, { withFileTypes: true })) {
           signal?.throwIfAborted();
           if (++visited > 20000) throw new Error('Glob exceeded 20000 entries; use Grep or a smaller workspace.');
           if (['.git', '.comal', '.harness', '.analysis', 'node_modules'].includes(entry.name)) continue;
-          const file = path.join(dir, entry.name), relative = path.relative(this.cwd, file).split(path.sep).join('/');
-          if (entry.isDirectory()) await walk(file, depth + 1);
-          else if (entry.isFile() && matcher.test(relative)) files.push(relative);
+          const file = path.join(dir, entry.name), relative = path.relative(base, file).split(path.sep).join('/');
+          if (entry.isDirectory()) { if (canEnter(relative.split('/'))) await walk(file, depth + 1); }
+          else if (entry.isFile() && matcher.test(relative)) files.push(show(file));
         }
       };
-      await walk(this.cwd);
+      try { await walk(base); }
+      catch (error) {
+        if (!/20000 entries/.test(error.message)) throw error;
+        // A pattern that must search the whole tree falls back to ripgrep's file list: it honours
+        // .gitignore (like Grep), so generated trees such as evidence/ or dist/ do not exhaust it.
+        const listed = await runProcess('rg', ['--files', '--hidden', '--no-require-git', '--color', 'never', '--glob', '!.git/**', '--glob', '!.comal/**', '--glob', '!.harness/**', '--glob', '!.analysis/**', '--glob', '!**/node_modules/**', '.'], { cwd: base, signal, allowNoMatch: true, timeout: 30000 })
+          .catch(() => { throw error; });
+        const matched = listed.split('\n').map(line => line.replace(/^\.\//, '')).filter(relative => relative && relative !== '(no output)' && matcher.test(relative)).map(relative => show(path.join(base, relative))).sort();
+        const note = '\n[Searched with ripgrep: paths ignored by .gitignore were skipped' + (matched.length > 1000 ? `; limited to 1000 of ${matched.length} matches` : '') + '.]';
+        return (matched.slice(0, 1000).join('\n') || '(no matches)') + note;
+      }
       return files.sort().slice(0, 1000).join('\n') || '(no matches)';
     }
   }
@@ -348,26 +403,40 @@ function globRegex(pattern) {
 export function runProcess(command, args, { cwd, timeout = 30000, signal, allowNoMatch = false, observe = () => {} }) {
   return new Promise((resolve, reject) => {
     signal?.throwIfAborted();
-    const child = spawn(command, args, { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    const child = spawn(command, args, { cwd, env: childEnvironment(), detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
     observe({kind:'process_started',pid:child.pid,process_group:child.pid});
-    let output = '', truncated = false, failure, killTimer;
+    // Keep the start and the end: test runners and builds print their summary last.
+    let head = '', tail = '', omitted = 0, failure, killTimer;
     const terminate = reason => {
       if (failure) return; failure = reason;
       try { process.kill(-child.pid, 'SIGTERM'); } catch {}
       killTimer = setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch {} }, 200);
     };
     const receive = chunk => {
-      const available = LIMIT - output.length;
-      if (available > 0) output += chunk.toString().slice(0, available);
-      if (chunk.length > available) truncated = true;
+      let text = chunk.toString();
+      if (head.length < LIMIT / 2) { const taken = text.slice(0, LIMIT / 2 - head.length); head += taken; text = text.slice(taken.length); }
+      if (text) { tail += text; if (tail.length > LIMIT / 2) { omitted += tail.length - LIMIT / 2; tail = tail.slice(-LIMIT / 2); } }
     };
+    const collected = () => omitted ? `${head}\n[Output limited to 64 KiB: ${omitted} characters omitted between the start and the end]\n${tail}` : head + tail;
     child.stdout.on('data', receive); child.stderr.on('data', receive);
     const timer = setTimeout(() => terminate(new Error(`Command exceeded ${timeout} ms.`)), timeout);
     const abort = () => terminate(new Error('Comando cancelado.'));
     signal?.addEventListener('abort', abort, { once: true });
     const cleanup = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); };
     child.once('error', err => { cleanup(); clearTimeout(killTimer); reject(err); });
+    // A child that left the process group (setsid, nohup &, daemons) can hold the output pipe after
+    // the shell exits, so 'close' never comes. After the shell exits, give the pipes a short grace,
+    // then stop reading and settle; such a child keeps running and is reported.
+    let settled = false, detached = false;
+    child.once('exit', (code, terminationSignal) => {
+      setTimeout(() => {
+        if (settled) return; detached = true;
+        child.stdout.destroy(); child.stderr.destroy();
+        child.emit('close', code, terminationSignal);
+      }, 500);
+    });
     child.once('close', async (code, terminationSignal) => {
+      if (settled) return; settled = true;
       cleanup();
       if(failure){
         // Wait for the bounded escalation before recording a terminal receipt.
@@ -378,8 +447,8 @@ export function runProcess(command, args, { cwd, timeout = 30000, signal, allowN
       observe({kind:'process_exit',exit_code:code,termination_signal:terminationSignal || null,interrupted:Boolean(failure)});
       // Leave the short kill timer alive after timeout to stop remaining descendants.
       if (failure) reject(failure);
-      else if (code !== 0 && !(allowNoMatch && code === 1)) reject(Object.assign(new Error(`Command exited with code ${code}: ${output}`),{code:'PROCESS_EXIT_NONZERO'}));
-      else resolve(output + (truncated ? '\n[Output limited to 64 KiB]' : '') || '(no output)');
+      else if (code !== 0 && !(allowNoMatch && code === 1)) reject(Object.assign(new Error(`Command exited with code ${code}: ${collected()}`),{code:'PROCESS_EXIT_NONZERO'}));
+      else resolve((collected() || '(no output)') + (detached ? '\n[The shell exited but a process it started left its process group and still holds the output; Comal stopped reading. It keeps running: stop it when done. To serve pages for browser tests use WorkspaceServe instead of a background server.]' : ''));
     });
   });
 }

package/src/tui/connection-transition.mjs

@@ -14,6 +14,16 @@ const MESSAGES = Object.freeze({
   uncertain: 'Connection change could not be confirmed. Check the active connection before trying again.',
 });
 
+// Next step shown with a failed change. Built from the classified reason only,
+// never from the upstream error text.
+export const CONNECTION_REASON_HINTS = Object.freeze({
+  authentication: 'Sign in or check the configured credential environment variable.',
+  timeout: 'The model server timed out.',
+  unavailable: 'The model server could not be reached.',
+  unsupported: 'The active model does not support this setting.',
+  unknown: 'The change could not be verified.',
+});
+
 function label(value) {
   if (typeof value !== 'string') return '';
   // Never render terminal escapes or URL credentials/query strings in a status.