@milpa/comal 0.2.2 → 0.2.4

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|device CODE|scan|forget|permissions on|off]', 'Open this local session on the web'], ['rc', '[start|status|stop|relay on|off|device CODE|scan|forget|permissions 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,15 @@ export function commandCatalog(context = {}) {
 
 function argumentItems(command, args, context) {
   const first = args[0] || '', position = args.length - 1;
+  if (command === 'rc' || command === 'remote-control') {
+    const durations = () => named(['30m', '2h', '8h'], 'How long the arm lasts (30 min by default, 8 h at most)');
+    if (position === 1 && first === 'relay') return named(['on', 'off'], 'on [30m|2h|8h] arms in memory for this /rc session; off disarms');
+    if (position === 1 && first === 'device') return [...named(['scan'], 'Read the pairing QR with the camera (at most 30 s); you confirm the code'), ...named(['forget'], 'Unpair the M5Stack')];
+    if (position === 1 && first === 'permissions') return named(['on', 'off'], 'on [30m|2h|8h] lets the paired M5Stack allow once or deny; off disarms');
+    if (position === 2 && (first === 'relay' || first === 'permissions') && args[1] === 'on') return durations();
+  }
   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)'), ...named(['device'], 'Pair an M5Stack: type its CODE, or scan its QR'), ...named(['permissions'], 'Let the paired M5Stack answer permission cards (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 +145,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);