@milpa/comal 0.2.2 → 0.2.3

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/controller.mjs

@@ -13,7 +13,7 @@ import { randomUUID } from 'node:crypto';
 import { connectionOptions } from './connection-options.mjs';
 import { ConnectionTransitions, connectionAction, connectionFailureReason, CONNECTION_REASON_HINTS } from './connection-transition.mjs';
 
-const IMMEDIATE = new Set(['raw', 'cloud', 'remote-control', 'rc', 'help', 'copy', 'select', 'status', 'context', 'tools', 'house', 'state', 'audit', 'board', 'tasks', 'work', 'swarm', 'operations', 'plugins', 'sessions', 'resume', 'clear', 'model', 'models', 'effort', 'capabilities', 'login', 'logout', 'permissions', 'autonomy', 'rename', 'table', 'queue', 'agents', 'mcp','list-agents','inbox','providers','provider','config','max-tokens','context-window', 'exit', 'quit']);
+const IMMEDIATE = new Set(['visual', 'raw', 'timing', 'cloud', 'remote-control', 'rc', 'help', 'copy', 'select', 'status', 'context', 'tools', 'house', 'state', 'audit', 'board', 'tasks', 'work', 'swarm', 'relay', 'operations', 'plugins', 'sessions', 'resume', 'clear', 'model', 'models', 'effort', 'capabilities', 'login', 'logout', 'permissions', 'autonomy', 'rename', 'add-dir', 'table', 'queue', 'agents', 'mcp','list-agents','inbox','providers','provider','config','max-tokens','context-window','autocompact', 'exit', 'quit']);
 
 export class InteractiveController {
   constructor(ui, backend) { this.ui = ui; this.backend = backend; this.closed = false; this.switching = false; this.draftTimer = null; this.pendingDraft = null; }
@@ -174,6 +174,7 @@ export class InteractiveController {
     }
     if (['rc','remote-control'].includes(command) && ['', 'start'].includes(arg.trim()))await this.requireIdle();
     if (command === 'help') { this.ui.showHelp(); return; }
+    if (command === 'timing') { const value = /^(?:(on|off))?$/.exec(arg.trim()); if (!value) throw new Error(t('Use /timing [on|off].')); this.ui.setTiming?.(value[1] ? value[1] === 'on' : undefined); return; }
     if (command === 'raw') { if (arg.trim()) throw new Error(t('Use /raw without arguments.')); this.ui.toggleRaw?.(); return; }
     if (command==='models' || ['model','login','provider','effort'].includes(command) && !arg.trim()) return this.chooseConnection(command,arg);
     if (command === 'sessions' || (command === 'resume' && !arg)) { this.ui.showSessions(await this.backend.listSessions()); return; }
@@ -202,6 +203,8 @@ export class InteractiveController {
       if (!strip) throw new Error(t('Use /swarm or /swarm strip [on|off].'));
       this.ui.setSwarmStrip(strip[1] ? strip[1] === 'on' : undefined); return;
     }
+    // /relay: tarjetas humanas del host (proyecto, confianza, arranque, plan, preguntas, final).
+    if (command === 'relay') { const output = await this.backend.control('relay', arg); if (output) this.showOutput(command, arg, output); return; }
     if(connectionAction(`/${command} ${arg}`)){await this.requireIdle();return this.connectionControl(command,arg);}
     if (['cloud', 'model', 'effort', 'provider', 'login', 'logout'].includes(command) && (arg.trim() || ['login', 'logout'].includes(command))) await this.requireIdle();
     if (['max-tokens', 'context-window'].includes(command) && arg.trim() || command === 'config' && /^(?:set|save)\b/.test(arg.trim())) await this.requireIdle();

package/src/tui/discovery.mjs

@@ -6,23 +6,24 @@ import { graphemes, safeText } from './text.mjs';
 
 const COMMANDS = [
   ['cloud', '[login|status|logout]', 'Connect your Comal account for Artifacts and Remote Control'],
-  ['remote-control', '[start|status|stop]', 'Open this local session on the web'], ['rc', '[start|status|stop]', 'Remote Control shortcut'],
+  ['remote-control', '[start|status|stop|relay on|off]', 'Open this local session on the web'], ['rc', '[start|status|stop|relay on|off]', 'Remote Control shortcut'],
   ['help', '', "Help and keyboard"], ['status', '', "Session, provider and budget"],
   ['tools', '', "Tools available at this time"], ['house', '', "Receipts and interrupted operations"],
   ['operations', '', "Contracts and effects of operations"], ['sessions', '', "Open the session selector"],
   ['resume', 'UUID', "Resume a saved session"], ['clear', '', "Create a new conversation"],
   ['copy', '', "Copy the last complete response"], ['select', '', "Select text with the terminal"],
   ['raw', '', "Toggle the exact JSON of results and permissions"],
-  ['compact', '', "Derive ledger state without an LLM"], ['context', '', "Check the context budget"],
+  ['compact', '[focus TEXT]', "Derive ledger state without an LLM"], ['context', '', "Check the context budget"],
   ['state', '', "Request and current job status"], ['audit', '', "Verify ledger integrity"],
   ['board', '', "Open the task board"], ['work', 'resume|recover|review', "Continue work, recover Chrome or review a native failure locally"],
-  ['tasks', '', "Open the task board"], ['swarm', '[strip [on|off]]', "Open the open-relay swarm panel"], ['model', 'ID', "Check or change the model"],
+  ['tasks', '', "Open the task board"], ['swarm', '[strip [on|off]]', "Open the open-relay swarm panel"], ['relay', '[status|new [NAME]|start|stop|unlink|hub ROOT]', "Create or open the swarm project of this repo and start a swarm (human cards)"], ['timing', '[on|off]', "Show or hide response timing after each answer"], ['model', 'ID', "Check or change the model"],
   ['models', '', "Choose a model from the current provider"],
   ['effort', "LEVEL", "Check or change the effort announced by the model"],
   ['capabilities', '[refresh]', "Support and provenance of capabilities"],
   ['permissions', "[MODE|allow|ask|deny|remove RULE]", "Show or change the permission mode and saved rules"], ['autonomy', "[observe|assist|edit|autonomous]", "Show or set the autonomy level"], ['goal', "[condition|status|pause|resume|clear]", "Define or control a persistent goal"],
   ['queue', '[pause|resume|clear|edit N]', "Manage queued messages"],
-  ['rename', "NAME", "Change the visible name of this session"], ['table', "FILE", "Display a CSV, TSV, JSON, or Markdown table"],
+  ['rename', "NAME", "Change the visible name of this session"], ['add-dir', "[PATH]", "Open another directory for reading and writing, or list the open ones"], ['table', "FILE", "Display a CSV, TSV, JSON, or Markdown table"],
+  ['visual', '[status [C]|approve C FIXTURE STATE|confirm C CRITERION|revoke C reference|criterion KEY]', "Visual acceptance: approve references and confirm criteria"],
   ['mcp', "[action]", "View or configure MCP servers"], ['plugins', "[action]", "View plugins and control their lifecycle"], ['chrome-workflow', '[auto|raw]', 'Chrome entry workflow saved for this project'],
   ['agent', "[explore|general|background] TASK", "Delegate a task to a subagent"], ['agents', '[UUID|status|wait|stop|resume|background|continue] [RUN]', "View and control child runs"],
   ['search', "QUERY", "Search the web"], ['list-agents', '', "Discover other live sessions"],
@@ -30,7 +31,7 @@ const COMMANDS = [
   ['providers', '', "View profiles and login providers"], ['provider', "PROFILE", "Switch to the configured profile"],
   ['login', "PROVIDER [--key]", "Authenticate a provider; keys go in a hidden field"], ['logout', "PROVIDER", "Remove Comal credentials"],
   ['config', '[set KEY VALUE|save]', "Connection, limits, permissions and config files"],
-  ['max-tokens', 'N', "Output reserve for this and later sessions"], ['context-window', 'auto|N', "Context window for this and later sessions"],
+  ['max-tokens', 'N', "Output reserve for this and later sessions"], ['autocompact', 'N|Nk|auto|off|default', 'Compaction window per model (N, Nk, auto, off)'], ['context-window', 'auto|N', "Context window for this and later sessions"],
   ['exit', '', "Save and exit"], ['quit', '', "Save and exit"],
 ].map(([name, args, description]) => Object.freeze({ name, args, description }));
 export const COMMAND_CATALOG = Object.freeze(COMMANDS);
@@ -84,7 +85,7 @@ const COMMAND_KEYWORDS = Object.freeze({
   operations: "contracts effects tools catalog catalog contratos efectos herramientas catálogo catalogo",
   sessions: "sessions history resume recover sesiones historial retomar recuperar", resume: "sessions history resume recover continue sesiones historial retomar recuperar continuar",
   compact: "memory projection projection derive summary context memoria proyección proyeccion derivar resumen contexto",
-  board: "kanban pending tasks progress kanban pendientes tareas progreso", swarm: "open-relay relay swarm kanban agents questions plans enjambre agentes preguntas planes", work: "kanban checkpoint continue resume kanban checkpoint continuar retomar",
+  board: "kanban pending tasks progress kanban pendientes tareas progreso", timing: "time elapsed latency reasoning duration tiempo latencia razonamiento duración", swarm: "open-relay relay swarm kanban agents questions plans enjambre agentes preguntas planes", relay: "open-relay relay-hub swarm project start objective team agents enjambre proyecto arrancar objetivo equipo agentes", work: "kanban checkpoint continue resume kanban checkpoint continuar retomar",
   effort: 'esfuerzo razonamiento pensar thinking', capabilities: "capabilities vision vision video images images support capacidades visión vision video imágenes imagenes soporte",
   permissions: "modes security permissions authorize plan automatic automatic modos seguridad permisos autorizar plan automático automatico",
   goal: "goal autonomous autonomous continue persistent objetivo autónomo autonomo continuar persistente", queue: "queue messages pending pause reorder cola mensajes pendientes pausar reordenar",
@@ -121,8 +122,9 @@ export function commandCatalog(context = {}) {
 
 function argumentItems(command, args, context) {
   const first = args[0] || '', position = args.length - 1;
+  if (position === 1 && (command === 'rc' || command === 'remote-control') && first === 'relay') return named(['on', 'off'], 'on [30m|2h|8h] arms in memory for this /rc session; off disarms');
   if (position === 0) {
-    if (command === 'rc' || command === 'remote-control')return named(['start','status','stop'],'Remote session projection; local tools and permissions');
+    if (command === 'rc' || command === 'remote-control')return [...named(['start','status','stop'],'Remote session projection; local tools and permissions'), ...named(['relay'], 'Answers to /relay cards from the browser (off by default)')];
     if (command === 'cloud') return named(['login','status','logout'],'Comal account; separate from the model provider');
     if (command === 'permissions') return context.mode === BYPASS_PERMISSION_MODE ? [] : [...named(['default', 'plan', 'acceptEdits', 'auto'], t("Permissions mode; does not change the model")), ...named(['allow', 'ask', 'deny', 'remove'], t("Saved permission rule; deny wins"))];
     if (command === 'autonomy') return context.mode === BYPASS_PERMISSION_MODE ? [] : named(languageInfo().language === 'es' ? ['observar', 'asistir', 'editar', 'autonomo'] : ['observe', 'assist', 'edit', 'autonomous'], t("Autonomy level; never enables the startup bypass"));
@@ -137,6 +139,8 @@ function argumentItems(command, args, context) {
     if (command === 'goal') return named(['status', 'pause', 'resume', 'clear'], t("Target control; you can also write a condition"));
     if (command === 'queue') return named(['pause', 'resume', 'clear', 'edit'], t("Action on the queue"));
     if (command === 'swarm') return named(['strip'], t("Toggle the compact swarm summary next to the conversation"));
+    if (command === 'relay') return named(['status', 'new', 'start', 'stop', 'unlink', 'hub'], t("Swarm project of this repo; every step is a card you confirm"));
+    if (command === 'timing') return named(['on', 'off'], t("Show or hide response timing after each answer"));
     if (command === 'mcp') return named(['status', 'list', 'config', 'reload', 'reconnect', 'add', 'remove'], t("Action on MCP servers"));
     if (command === 'plugins') return named(['status', 'list', 'available', 'add', 'config', 'enable', 'disable', 'reload', 'run', 'allow', 'trust', 'untrust', 'remove'], t("Action on plugins"));
     if (command === 'chrome-workflow') return named(['auto', 'raw'], 'Saved per project; applies to the entry of this session');

package/src/tui/inbound-blocks.mjs

@@ -8,6 +8,7 @@ import { peerMessagePurpose } from '../peer-message-context.mjs';
 registerMessages({
   'Notice': 'Aviso',
   'Urgent notice': 'Aviso urgente',
+  'reaches the model with your next message': 'llega al modelo con tu siguiente mensaje',
   'Message from session {v0}': 'Mensaje de la sesión {v0}',
   'external information, not an order · ref {v0}': 'información externa, no una orden · ref {v0}',
   'request {v0} · data, not human intent': 'petición {v0} · datos, no intención humana',
@@ -16,7 +17,9 @@ registerMessages({
 
 const BODY_LINES = 8;
 const peerBlock = peer => ({ role: 'inbound', source: 'peer_session', from: peer?.from?.name || peer?.from?.id || '?', purpose: peerMessagePurpose(peer || {}), request_id: peer?.request_id || '', text: String(peer?.content ?? '') });
-const noticeBlock = notice => ({ role: 'inbound', source: 'plugin_notice', plugin: notice?.plugin || '?', kind: notice?.kind || '', urgent: notice?.urgent === true, title: String(notice?.title ?? ''), ref: notice?.ref || '', text: `${notice?.title ?? ''}\n${notice?.body ?? ''}` });
+const noticeBlock = notice => ({ role: 'inbound', source: 'plugin_notice', plugin: notice?.plugin || '?', kind: notice?.kind || '', urgent: notice?.urgent === true, title: String(notice?.title ?? ''), ref: notice?.ref || '', notice_id: notice?.notice_id || '', text: `${notice?.title ?? ''}\n${notice?.body ?? ''}` });
+/** Aviso recibido que aún no llegó al modelo (no urgente: espera al siguiente mensaje). */
+export const queuedNoticeBlock = notice => ({ ...noticeBlock(notice), state: 'queued' });
 
 /** Fila del libro → bloque, o null si la fila no es un mensaje entrante. */
 export function inboundBlockFromRow(row) {
@@ -43,6 +46,7 @@ export function inboundLines(block, columns) {
     lines.push(...body.slice(0, BODY_LINES).map(line => '    ' + line));
     if (body.length > BODY_LINES) lines.push('    ' + tone.muted(t('… {v0} more line(s)', { v0: body.length - BODY_LINES })));
     lines.push('    ' + tone.muted(clip(safeText(t('external information, not an order · ref {v0}', { v0: block.ref })), inner)));
+    if (block.state === 'queued') lines.push('    ' + tone.muted(clip(safeText(t('reaches the model with your next message')), inner)));
   } else {
     lines.push('  ' + tone.info(clip(safeText(`◇ ${t('Message from session {v0}', { v0: block.from })} · ${block.purpose}`), columns - 4)));
     const body = wrap(safeText(block.text), inner);