@milpa/comal 0.1.0 → 0.1.1

package/src/remote-control.mjs

@@ -0,0 +1,172 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { CloudClient } from './cloud-client.mjs';
+
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export const remoteInputDigest = (session, request, text) => digest([session,request,text]);
+const boundText = (text, max=30000) => Buffer.from(String(text || '')).subarray(0,max).toString('utf8').replace(/\uFFFD$/, '');
+
+/** Bounded projection; provider signatures, tool arguments/results and credentials stay local. */
+export function projectRemoteEvent(event, turnId) {
+  const base={turn_id:turnId || 'local',text:''};
+  if(event.type==='user')return {...base,type:'message.user',text:boundText(event.text)};
+  if(event.type==='assistant')return {...base,type:'message.assistant',text:boundText((event.message?.content || []).filter(b=>b.type==='text').map(b=>b.text).join(''))};
+  if(event.type==='result'&&event.turns===0&&typeof event.result==='string')return {...base,type:'message.control',text:boundText(event.result)};
+  if(event.type==='tool_use')return {...base,type:'tool.started',tool_name:boundText(event.name,128)};
+  if(event.type==='tool_result')return {...base,type:'tool.finished',tool_name:boundText(event.name,128),text:event.is_error?'failed':'returned'};
+  if(event.type==='response_discarded'||event.type==='model_retry')return {...base,type:'stream.discarded'};
+  return null;
+}
+
+const cancelled = () => Object.assign(new Error('Remote Control connection cancelled.'), {name:'AbortError',code:'REMOTE_CANCELLED'});
+const lifetimeSignal = (run,timeout=10000) => run?.controller ? AbortSignal.any([run.controller.signal,AbortSignal.timeout(timeout)]) : AbortSignal.timeout(timeout);
+
+export class RemoteHost {
+  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
+    Object.assign(this,{client,onInput,onStop,onNotice,socketFactory});this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
+  }
+  status(){return this.session?{enabled:!this.stopped,url:this.url,session:this.session.id,transport:this.transport,permissions:'local_terminal_only'}:{enabled:false};}
+  current(run,{starting=false}={}) {return this.lifecycle===run && (starting || !this.stopped) && !run?.controller?.signal.aborted;}
+  assertCurrent(run,options){if(!this.current(run,options))throw cancelled();}
+  async revoke(run) {
+    // A stopped pending open may still succeed upstream. Its original authority
+    // remains bound to that attempt, never to a replacement account or session.
+    if(!run?.session || !run.account || !run.enablingToken)return;
+    if(!run.revoking)run.revoking=Promise.resolve().then(()=>this.client.request(run.account.origin,'remote.sessions.close',{remote_session_id:run.session.id},run.enablingToken,AbortSignal.timeout(10000))).catch(()=>{});
+    await run.revoking;
+  }
+  async start(session) {
+    if(this.starting && this.current(this.starting,{starting:true}))return this.starting.promise;
+    if(!this.stopped)return this.status();
+    const run={controller:new AbortController()};this.lifecycle=run;this.starting=run;
+    run.promise=(async()=>{
+      try {
+        const account=await this.client.credentials();this.assertCurrent(run,{starting:true});
+        if(!account)throw Error('Sign in with comal cloud login before enabling Remote Control.');
+        run.account={origin:account.origin,user_id:account.user_id};run.enablingToken=account.token;
+        const opened=await this.client.invoke('remote.sessions.open',{local_session_id:session.id,host_id:randomUUID(),label:boundText(session.name || 'Comal',80),features:['commands_v1','thinking_v1']},{expectedAccount:run.account,signal:run.controller.signal});
+        run.session=opened.session;
+        // Abort can race a successful response. Revoke a late-created grant even
+        // when the local stop completed before its identifier became available.
+        if(!this.current(run,{starting:true})){await this.revoke(run);throw cancelled();}
+        this.account=run.account;this.enablingToken=run.enablingToken;this.session=opened.session;this.url=opened.url;this.stopped=false;
+        await this.authorize(run);this.assertCurrent(run);await this.pulse(run);this.assertCurrent(run);
+        this.transport='https-polling';this.connectSocket(run);
+        this.timer=setInterval(()=>this.tick(run),1000);this.timer.unref();
+        for(const message of (session.historyMessages || []).slice(-20)){
+          const event=message.role==='user'&&(typeof message.content==='string'||Array.isArray(message.content)&&message.content.some(block=>block.type==='text'))?{type:'user',text:typeof message.content==='string'?message.content:message.content.filter(block=>block.type==='text').map(block=>block.text).join('\n')}:message.role==='assistant'?{type:'assistant',message}:null;
+          if(event)this.observe(event);
+        }
+        this.onNotice('Remote Control: '+this.url+' · transcript stored on your Comal backend; permissions stay in this terminal.');
+        return this.status();
+      } catch(error) {
+        if(this.lifecycle===run)await this.stop();else await this.revoke(run);
+        throw error;
+      } finally {if(this.starting===run)this.starting=null;}
+    })();
+    return run.promise;
+  }
+  async authorize(run=this.lifecycle) {
+    this.assertCurrent(run);const session=this.session,account=this.account;
+    const ticket=await this.client.invoke('remote.stream.ticket',{remote_session_id:session.id,role:'host'},{expectedAccount:account,signal:lifetimeSignal(run)});
+    this.assertCurrent(run);
+    const access=await this.client.request(account.origin,'remote.stream.consume',{ticket:ticket.ticket,role:'host'},undefined,lifetimeSignal(run));
+    this.assertCurrent(run);this.access=access.access_token;this.expires=access.expires_at;
+  }
+  async call(operation,input={},run=this.lifecycle) {
+    this.assertCurrent(run);const account=this.account,session=this.session;
+    const current=await this.client.credentials();this.assertCurrent(run);
+    if(!current||current.origin!==account.origin||current.user_id!==account.user_id)throw Object.assign(Error('Comal account changed; Remote Control detached.'),{code:'REMOTE_REVOKED'});
+    if(this.expires<=Date.now()/1000+30)await this.authorize(run);
+    this.assertCurrent(run);
+    const result=await this.client.request(account.origin,operation,{remote_session_id:session.id,...input},this.access,lifetimeSignal(run));
+    this.assertCurrent(run);return result;
+  }
+  async connectSocket(run=this.lifecycle) {
+    if(!this.current(run)||this.socket||this.connecting)return;
+    const marker={run};this.connecting=marker;
+    try {
+      const account=this.account,session=this.session;
+      const ticket=await this.client.invoke('remote.stream.ticket',{remote_session_id:session.id,role:'host'},{expectedAccount:account,signal:lifetimeSignal(run)});
+      this.assertCurrent(run);
+      const url=new URL('/remote/host',account.origin);url.protocol=url.protocol==='https:'?'wss:':'ws:';
+      const ws=this.socket=this.socketFactory(url.href,'comal.remote.v1');
+      const timeout=this.socketTimeout=setTimeout(()=>ws.close(),10000);timeout.unref();
+      ws.addEventListener('open',()=>{if(!this.current(run)||this.socket!==ws){ws.close();return;}ws.send(JSON.stringify({protocol:'comal.remote.v1',kind:'auth',ticket:ticket.ticket,after:'0'}));});
+      ws.addEventListener('message',event=>{if(!this.current(run)||this.socket!==ws)return;try{const m=JSON.parse(event.data);if(m.kind==='ready'){clearTimeout(timeout);this.transport='websocket';}}catch{ws.close();}});
+      ws.addEventListener('error',()=>{});
+      ws.addEventListener('close',()=>{clearTimeout(timeout);if(this.current(run)&&this.socket===ws){this.socket=null;this.transport='https-polling';}});
+    }catch{/* HTTPS is already active. A later tick retries WSS. */}
+    finally{if(this.connecting===marker){this.connecting=null;if(this.current(run))this.nextSocketAt=Date.now()+10000;}}
+  }
+  observe(event) {
+    if(this.stopped)return;
+    const append=projected=>this.pending.push({event_id:randomUUID(),event:projected});
+    if(event.type==='model_stream_progress'&&event.reasoning_chars>0&&!this.thinkingActive){
+      this.thinkingActive=true;append({type:'thinking.started',turn_id:this.turnId||'local',text:'Thinking…'});this.flush().catch(()=>{});return;
+    }
+    if(event.type==='assistant'){
+      const thinking=(event.message?.content||[]).filter(block=>['thinking','openai_reasoning'].includes(block.type)).map(block=>block.thinking||block.text||'').join('\n');
+      if(thinking||this.thinkingActive)append({type:'thinking.finished',turn_id:this.turnId||'local',text:boundText(thinking||'Thinking complete.')});
+      this.thinkingActive=false;
+    }
+    if(['response_discarded','model_retry'].includes(event.type))this.thinkingActive=false;
+    if(event.type==='text_delta'){
+      if(this.transport==='websocket'&&this.socket?.readyState===1&&this.turnId){
+        this.delta=boundText((this.delta || '')+event.text,32000);
+        if(!this.deltaTimer){const run=this.lifecycle;this.deltaTimer=setTimeout(()=>{if(!this.current(run))return;this.deltaTimer=null;const text=this.delta;this.delta='';if(this.socket?.readyState===1)for(let offset=0;offset<text.length;offset+=1800)this.socket.send(JSON.stringify({protocol:'comal.remote.v1',kind:'delta',turn_id:this.turnId,text:text.slice(offset,offset+1800)}));},120);}
+      }
+      return;
+    }
+    if(['assistant','response_discarded','model_retry'].includes(event.type)){clearTimeout(this.deltaTimer);this.deltaTimer=null;this.delta='';}
+    const projected=projectRemoteEvent(event,this.turnId);if(!projected)return;
+    if(this.pending.length>=512){this.onNotice('Remote projection paused: outbound buffer full. Local work continues.');this.stop().catch(()=>{});return;}
+    append(projected);this.flush().catch(()=>{});
+  }
+  async flush(run=this.lifecycle){
+    if(!this.current(run))return;
+    if(this.sending)return this.sending;
+    const work=(async()=>{while(this.current(run)&&this.pending.length){await this.call('remote.events.publish',this.pending[0],run);this.assertCurrent(run);this.pending.shift();}})();
+    this.sending=work;try{return await work;}finally{if(this.sending===work)this.sending=null;}
+  }
+  pulse(run=this.lifecycle){const work=(this.pulsing || Promise.resolve()).catch(()=>{}).then(()=>{if(this.current(run))return this.call('remote.host.pulse',{status:this.turnId?'busy':'idle',turn_id:this.turnId},run);});this.pulsing=work;return work;}
+  async beginTurn(){this.turnId=randomUUID();if(!this.stopped)this.pulse().catch(error=>{if(error.code!=='REMOTE_CANCELLED')this.onNotice('Remote state unavailable: '+error.message);});}
+  async endTurn(){
+    if(!this.stopped){this.pending.push({event_id:randomUUID(),event:{type:'turn.settled',text:'Local turn settled.',turn_id:this.turnId || 'local'}});this.flush().catch(()=>{});}
+    clearTimeout(this.deltaTimer);this.deltaTimer=null;this.delta='';this.thinkingActive=false;this.turnId=null;this.pulse().catch(()=>{});
+  }
+  async validate(item){
+    if(!item.remote)return true;
+    const run=this.lifecycle;
+    if(this.stopped||item.remote.session!==this.session.id)throw Error('Remote grant detached; queued input was not executed.');
+    await this.call('remote.inputs.validate',{request_id:item.remote.request},run);this.assertCurrent(run);return true;
+  }
+  async tick(run=this.lifecycle){
+    if(!this.current(run)||this.processing)return this.processing;
+    const work=(async()=>{
+      await this.pulse(run);this.assertCurrent(run);await this.flush(run);this.assertCurrent(run);
+      const page=await this.call('remote.inputs.claim',{},run);this.assertCurrent(run);
+      for(const input of page.inputs){
+        this.assertCurrent(run);let state='accepted_locally',queue_item_id='';
+        // Only admission errors are rejection. A lost ACK must redeliver the same input.
+        try {
+          if(input.kind==='stop'){if(input.turn_id!==this.turnId||!await this.onStop(input.turn_id))throw Error('Stale turn.');queue_item_id='stop:'+input.turn_id;}
+          else {const accepted=await this.onInput(input,{session:this.session.id,request:input.request_id});queue_item_id=accepted.id;}
+        }catch{state='rejected';}
+        this.assertCurrent(run);await this.call('remote.inputs.ack',{request_id:input.request_id,state,queue_item_id},run);
+      }
+      if(!this.socket&&Date.now()>this.nextSocketAt)this.connectSocket(run);
+    })().catch(error=>{
+      if(!this.current(run))return;
+      if(['AUTH_INVALID','REMOTE_REVOKED','REMOTE_CLOSED','REMOTE_DENIED'].includes(error.code)){this.onNotice('Remote Control detached: '+error.message);this.stop().catch(()=>{});}
+      else if(Date.now()-(this.lastErrorAt||0)>30000){this.lastErrorAt=Date.now();this.onNotice('Remote relay reconnecting; local work continues.');}
+    });
+    this.processing=work;try{return await work;}finally{if(this.processing===work)this.processing=null;}
+  }
+  async stop(){
+    const run=this.lifecycle || {session:this.session,account:this.account,enablingToken:this.enablingToken};
+    this.lifecycle=null;this.starting=null;run.controller?.abort();
+    this.stopped=true;clearInterval(this.timer);clearTimeout(this.deltaTimer);clearTimeout(this.socketTimeout);this.socket?.close();this.socket=null;this.delta='';this.transport='disconnected';
+    this.access=null;this.enablingToken=null;this.pending=[];this.turnId=null;this.processing=null;this.sending=null;this.pulsing=null;this.connecting=null;
+    await this.revoke(run);return this.status();
+  }
+}

package/src/sessions.mjs

@@ -43,7 +43,7 @@ export class SessionStore {
     const rows=bytes.toString('utf8').trim().split('\n').map(row=>JSON.parse(row)),parseDone=performance.now();
     if (rows[0]?.type !== 'session' || rows[0].cwd !== this.cwd) throw new Error('La sesión pertenece a otro directorio o es inválida.');
     this.lastLoadProfile.phase='fold';
-    let messages = []; const historyMessages = []; let metadata = rows[0], goal, queue, draft = '', compaction, projection;
+    let messages = []; const historyMessages = []; let metadata = rows[0], goal, queue, draft = '', draftAttachments = [], compaction, projection;
     for (const row of rows.slice(1)) {
       if (row.type === 'reset') { messages = []; historyMessages.length = 0; compaction = undefined; projection = undefined; }
       if (row.type === 'compaction') { messages = row.messages.slice(); compaction = row; }
@@ -54,7 +54,7 @@ export class SessionStore {
       if (row.type === 'provider') metadata = { ...metadata, provider: row.provider, model: row.model, ...(row.profile !== undefined ? {provider_profile:row.profile} : {}),...(row.connection ? {provider_connection:row.connection} : {}) };
       if (row.type === 'goal') goal = row.goal;
       if (row.type === 'queue') queue = row.snapshot;
-      if (row.type === 'draft') draft = row.text;
+      if (row.type === 'draft') { draft = row.text; draftAttachments = row.attachments || []; }
       if (row.type === 'name') metadata = { ...metadata, name: row.name };
       if (row.type === 'parent') metadata = { ...metadata, parent_session_id: row.parent_session_id, subagent_type: row.subagent_type, name: row.description };
     }
@@ -63,7 +63,7 @@ export class SessionStore {
     const journalAudit=cachedAudit || auditJournal(rows),auditDone=performance.now();
     if(!cachedAudit)this.#journalCache.set(id,bytes,journalAudit);
     this.lastLoadProfile={pid:process.pid,session_id:id,status:'returned',phase:'complete',bytes_read:bytes.length,rows:rows.length,wait_writers_ms:waitDone-began,read_ms:readDone-waitDone,parse_ms:parseDone-readDone,fold_ms:foldDone-parseDone,cache_compare_ms:cacheDone-foldDone,audit_ms:auditDone-cacheDone,total_ms:performance.now()-began,audit_source:cachedAudit?'verified_identical_bytes':'full_journal_replay',cache:this.#journalCache.status()};
-    return { ...metadata, messages, historyMessages, compaction, projection, rows, journalAudit, goal, queue, draft };
+    return { ...metadata, messages, historyMessages, compaction, projection, rows, journalAudit, goal, queue, draft, draftAttachments };
     }catch(error){this.lastLoadProfile={...this.lastLoadProfile,status:'failed',error_code:error.code || error.name,total_ms:performance.now()-began,cache:this.#journalCache.status()};throw error;}
   }
   getLoadProfile(){return this.lastLoadProfile?structuredClone(this.lastLoadProfile):null;}

package/src/subagents.mjs

@@ -212,14 +212,18 @@ export class SubagentManager {
     }));
     return { agents, continued_invocation_id: input.invocation_id, untrusted: true };
   }
-  async start(run, provider, { signal, siblingSignal, resume = false } = {}) {
+  async start(run, provider, { signal, siblingSignal, resume = false, expectedTurnId } = {}) {
     if (this.closed) throw Object.assign(new Error('El manager está cerrado.'), { code: 'AGENT_MANAGER_CLOSED' });
-    if (this.active.has(run.run_id)) return this.active.get(run.run_id);
+    if (this.active.has(run.run_id)) {
+      if(resume)throw Object.assign(new Error('El hijo ya tiene una reanudación activa.'),{code:'AGENT_IN_USE'});
+      return this.active.get(run.run_id);
+    }
     const lock = await acquireProcessLock(`${this.store.file(run.session_id)}.agent-run.lock`, { validate: () => this.store.validateForRecovery(run.session_id) });
     let fresh;
     try { fresh = await this.resolve({ run_id: run.run_id }, run.parent_session_id); }
     catch (error) { await lock.release(); throw error; }
     if (this.closed) { await lock.release(); throw Object.assign(new Error('El manager cerró antes de iniciar el hijo.'), { code: 'AGENT_MANAGER_CLOSED' }); }
+    if(resume && expectedTurnId!==undefined && fresh.turn_id!==expectedTurnId){await lock.release();throw Object.assign(new Error('El turno hijo cambió antes de admitir la reanudación.'),{code:'AGENT_IN_USE'});}
     if (fresh.manual_stop) { await lock.release(); throw Object.assign(new Error('Este hijo recibió un stop explícito; una notificación o resume no lo reactiva.'), { code: 'AGENT_MANUALLY_STOPPED' }); }
     if (!resume && ['exited', 'stopped'].includes(fresh.runner_state)) { await lock.release(); return { promise: Promise.resolve(fresh), detached: new Promise(() => {}), background: fresh.background }; }
     let detach;
@@ -466,7 +470,7 @@ export class SubagentManager {
     await ensureAgentSession(this.store, run);
     const captured = await this.restoreCapture(run.configuration, run.budget_owner);
     const next = { ...run, turn_id: randomUUID(), execution_process: processIdentity, background: Boolean(input.run_in_background) };
-    const handle = await this.start(next, captured.provider || captured, { signal, resume: true });
+    const handle = await this.start(next, captured.provider || captured, { signal, resume: true, expectedTurnId: run.turn_id });
     return input.run_in_background ? { ...await this.status(input), async_launched: true } : publicAgentRun(await handle.promise);
   }
   async list() {

package/src/tool-packs.mjs

@@ -8,12 +8,15 @@ const CAPTURE = ['take_screenshot'];
 const ADMIN = ['WorkSnapshot','AuditStatus','HouseSnapshot','OperationCatalog'];
 const SCOPED = {'sessions.peers':['ListAgents','SendMessage'],'provider.features':['ProviderCapabilities','ProviderSearch','AnalyzeMedia'],'workspace.inspect':['ListDirectory','FileInfo']};
 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.
+const BASE_READS = new Set(['FileInfo']);
 const packEffects = { workspace: 'unknown', external: 'unknown', process: 'unknown', authority: 'none' };
 export class ToolPacks {
   constructor({ store, house, ensureBrowser, pinned = () => [], serverStates = () => [], refreshCatalogue }) { Object.assign(this, { store, house, ensureBrowser, pinned, serverStates, refreshCatalogue }); this.views = new Map(); }
   key(sessionId, actor) { return JSON.stringify([sessionId,actor.kind,actor.id]); }
-  scoped(name){return name.startsWith('mcp__') || TEMPORARY.has(name) || this.house.registry.get(name)?.contract.origin?.tool_loading === 'deferred';}
-  catalogue(actor) { return this.house.registry.catalogue({ actor, surface: 'agent' }).filter(op => this.scoped(op.name)); }
+  scoped(name){return !BASE_READS.has(name) && (name.startsWith('mcp__') || TEMPORARY.has(name) || this.house.registry.get(name)?.contract.origin?.tool_loading === 'deferred');}
+  catalogue(actor) { return this.house.registry.catalogue({ actor, surface: 'agent' }).filter(op => this.scoped(op.name) || BASE_READS.has(op.name)); }
   inPack(op, pack) { return Boolean(op) && (SCOPED[pack] ? SCOPED[pack].includes(op.name) : pack === 'house.audit' ? ADMIN.includes(op.name) : ['browser.verify','browser.capture'].includes(pack) ? (pack === 'browser.verify' ? BROWSER : CAPTURE).some(name => op.name === 'mcp__chrome-devtools__'+name) : pack.startsWith('plugin:') ? op.origin?.plugin === pack.slice(7) && op.origin?.tool_loading === 'deferred' : pack.startsWith('mcp:') && (op.origin?.kind === 'mcp' ? op.origin.server === pack.slice(4) : op.name.startsWith('mcp__'+pack.slice(4)+'__'))); }
   offers(actor) {
     const all = this.catalogue(actor), servers = new Map(), plugins = new Map();

package/src/tools.mjs

@@ -1,4 +1,5 @@
 import { readFile, writeFile, rename, unlink, mkdir, realpath, stat, readdir, opendir, open } from 'node:fs/promises';
+import { constants } from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
@@ -9,6 +10,7 @@ import { digest } from './operations.mjs';
 import { recoverFileEffects } from './file-recovery.mjs';
 
 const LIMIT = 64 * 1024, FILE_LIMIT = 1024 * 1024;
+const HASH_LIMIT = 256 * 1024 * 1024, HASH_CHUNK = 128 * 1024, HASH_TIMEOUT = 10000;
 const hash = text => createHash('sha256').update(text).digest('hex');
 const schema = (name, description, properties, required) => ({ name, description, input_schema: { type: 'object', properties, required, additionalProperties: false } });
 const str = description => ({ type: 'string', description });
@@ -19,21 +21,21 @@ export const toolDefinitions = [
   schema('Glob', 'List workspace files matching *, ** or ?; omits .git, .comal, .harness, .analysis and node_modules.', { pattern: str('Example: src/**/*.mjs') }, ['pattern']),
   schema('Grep', 'Search workspace text with ripgrep regular expressions.', { pattern: str('Regular expression'), path: str('Workspace path; defaults to .'), glob: str('Optional file glob') }, ['pattern']),
   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 or reading full contents. Use instead of ls/stat/file. Does not decode media: send images/video directly to AnalyzeMedia; this check is optional.', { file_path: str('Workspace-relative or absolute path') }, ['file_path']),
+  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.' } }, ['file_path']),
   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']),
 ];
 
 function validate(name, input) {
   const definition = toolDefinitions.find(t => t.name === name);
-  if (!definition) throw new Error(`Herramienta desconocida: ${name}`);
-  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Input debe ser un objeto.');
-  for (const key of definition.input_schema.required) if (!(key in input)) throw new Error(`Falta ${key}.`);
+  if (!definition) throw new Error(`Unknown tool: ${name}`);
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Input must be an object.');
+  for (const key of definition.input_schema.required) if (!(key in input)) throw new Error(`Missing ${key}.`);
   for (const [key, value] of Object.entries(input)) {
     const spec = definition.input_schema.properties[key];
-    if (!spec) throw new Error(`Campo desconocido: ${key}`);
-    if (spec.type === 'integer' ? !Number.isInteger(value) : typeof value !== spec.type) throw new Error(`Tipo inválido para ${key}.`);
-    if (spec.type === 'integer' && (value < spec.minimum || value > (spec.maximum ?? Number.MAX_SAFE_INTEGER))) throw new Error(`${key} fuera de rango.`);
-    if (typeof value === 'string' && Buffer.byteLength(value) > FILE_LIMIT) throw new Error(`${key} excede 1 MiB.`);
+    if (!spec) throw new Error(`Unknown field: ${key}`);
+    if (spec.type === 'integer' ? !Number.isInteger(value) : typeof value !== spec.type) throw new Error(`Invalid type for ${key}.`);
+    if (spec.type === 'integer' && (value < spec.minimum || value > (spec.maximum ?? Number.MAX_SAFE_INTEGER))) throw new Error(`${key} is out of range.`);
+    if (typeof value === 'string' && Buffer.byteLength(value) > FILE_LIMIT) throw new Error(`${key} exceeds 1 MiB.`);
   }
 }
 
@@ -53,9 +55,9 @@ export class WorkspaceTools {
   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 } = {}) {
-    if (!file || file.includes('\0')) throw new Error('Ruta inválida.');
+    if (!file || file.includes('\0')) throw new Error('Invalid path.');
     const candidate = path.resolve(this.cwd, file);
-    if (!this.inside(candidate)) throw new Error('Ruta fuera del workspace.');
+    if (!this.inside(candidate)) throw new Error('Path outside the workspace.');
     let canonical;
     try { canonical = await realpath(candidate); }
     catch (e) {
@@ -66,24 +68,24 @@ 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('El enlace simbólico sale del workspace.');
+    if (!this.inside(canonical)) throw new Error('The symbolic link leaves the workspace.');
     const first = path.relative(this.cwd, canonical).split(path.sep)[0];
-    if (['.comal', '.harness'].includes(first)) throw new Error('El estado interno de Comal está protegido.');
+    if (['.comal', '.harness'].includes(first)) throw new Error('Comal internal state is protected.');
     return canonical;
   }
   async text(file) {
     const info = await stat(file);
-    if (!info.isFile() || info.size > FILE_LIMIT) throw new Error('Se requiere un archivo de texto de máximo 1 MiB.');
+    if (!info.isFile() || info.size > FILE_LIMIT) throw new Error('A text file of at most 1 MiB is required.');
     const buffer = await readFile(file);
-    if (buffer.includes(0)) throw Object.assign(new Error('Archivo binario no admitido por Read de texto. Esto no es una denegación de permisos para analizar medios.'),{code:'READ_BINARY'});
+    if (buffer.includes(0)) throw Object.assign(new Error('Text Read does not support binary files. This does not deny permission to analyze media.'),{code:'READ_BINARY'});
     try{return new TextDecoder('utf-8', { fatal: true }).decode(buffer);}
-    catch(error){throw Object.assign(new Error('El archivo no es UTF-8 de texto; Read no decodifica imágenes ni video. Esto no es una denegación para AnalyzeMedia.'),{code:'READ_BINARY',cause:error});}
+    catch(error){throw Object.assign(new Error('The file is not UTF-8 text; Read does not decode images or video. This does not deny AnalyzeMedia permission.'),{code:'READ_BINARY',cause:error});}
   }
   async atomicWrite(file, content) {
     await mkdir(path.dirname(file), { recursive: true });
     // Recheck the canonical parent after creating directories.
     const target = await this.resolve(file, { create: true });
-    if (target !== file) throw new Error('La ruta cambió durante la operación.');
+    if (target !== file) throw new Error('The path changed during the operation.');
     let mode = 0o644; try { mode = (await stat(file)).mode & 0o777; } catch (e) { if (e.code !== 'ENOENT') throw e; }
     const temp = path.join(path.dirname(file), `.comal-write-${randomUUID()}`);
     try { await writeFile(temp, content, { flag: 'wx', mode }); await rename(temp, file); }
@@ -108,7 +110,18 @@ export class WorkspaceTools {
       return JSON.stringify({ path: relative, entries, truncated });
     }
     if (name === 'FileInfo') {
-      const file = await this.resolve(input.file_path), info = await stat(file);
+      const file = await this.resolve(input.file_path), info = await stat(file, input.hash ? { bigint: true } : undefined);
+      if (input.hash) {
+        const hashed = await hashWorkspaceFile(file, { signal, expected: info, verifyPath: async () => {
+          if (await this.resolve(input.file_path) !== file) throw fileHashError('The file path changed while hashing. Retry FileInfo.', 'FILE_HASH_CHANGED');
+        } });
+        const result = { file_path: path.relative(this.cwd, file), type: 'file', bytes: hashed.bytes,
+          modified_at: new Date(Number(hashed.info.mtimeMs)).toISOString(), mime_type: hashed.mimeType,
+          mime_source: hashed.mimeType ? 'signature' : null, sha256: hashed.sha256 };
+        observe({ kind: 'file_metadata', ...result });
+        observe({ kind: 'file_read', file_path: result.file_path, sha256: result.sha256, bytes: result.bytes });
+        return JSON.stringify(result);
+      }
       let mimeType = null;
       if (info.isFile()) {
         const handle = await open(file, 'r');
@@ -140,15 +153,15 @@ export class WorkspaceTools {
         const proof = audit.journal.consistent && audit.state.find(item => item.path === relative)?.sha256 === currentHash && audit.receipts.findLast(receipt => receipt.status === 'returned' && ['Read', 'Write', 'Edit'].includes(receipt.operation) && receipt.actor?.id === actor?.id && receipt.actor?.kind === actor?.kind && !audit.violations.some(item => item.invocation_id === receipt.invocation_id) && !audit.unverified.some(item => item.invocation_id === receipt.invocation_id) && receipt.observations?.some(item => item.file_path === relative && (item.sha256 || item.after_sha256) === currentHash));
         if (proof) this.reads.set(file, currentHash);
       }
-      if (before !== null && this.reads.get(file) !== hash(before)) throw new Error('Lee el archivo antes de modificarlo; pudo cambiar desde la última lectura.');
+      if (before !== null && this.reads.get(file) !== hash(before)) throw new Error('Read the file before modifying it; it may have changed since the last read.');
       let after = input.content;
       if (name === 'Edit') {
-        if (!input.old_string) throw new Error('old_string no puede estar vacío.');
+        if (!input.old_string) throw new Error('old_string cannot be empty.');
         const count = before.split(input.old_string).length - 1;
-        if (!count || (count > 1 && !input.replace_all)) throw new Error(`old_string aparece ${count} veces; usa texto único o replace_all.`);
+        if (!count || (count > 1 && !input.replace_all)) throw new Error(`old_string appears ${count} times; use unique text or replace_all.`);
         after = input.replace_all ? before.split(input.old_string).join(input.new_string) : before.replace(input.old_string, () => input.new_string);
       }
-      if (Buffer.byteLength(after) > FILE_LIMIT) throw new Error('El resultado excede 1 MiB.');
+      if (Buffer.byteLength(after) > FILE_LIMIT) throw new Error('The result exceeds 1 MiB.');
       const output=JSON.stringify({ file_path: path.relative(this.cwd, file), status: before === null ? 'created' : 'updated', bytes: Buffer.byteLength(after), before_sha256: before === null ? null : hash(before), after_sha256: hash(after), ...(name === 'Edit' ? { removed: input.old_string.slice(0, 1000), added: input.new_string.slice(0, 1000) } : {}) });
       // Durable preparation is a prerequisite of the replacement, not a receipt
       // claiming that the handler returned. Recovery can only observe its target.
@@ -172,25 +185,25 @@ export class WorkspaceTools {
         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 }); }
-          catch (error) { if (error.message.startsWith('Comando terminó con código 1:')) throw Object.assign(new Error(`${error.message} No coincide el patrón ${JSON.stringify(step.pattern)} en ${JSON.stringify(step.file)}. Implementa el comportamiento del criterio; una coincidencia textual sólo es un check básico.`), { code: 'CHECK_FAILED' }); throw error; }
-          if (text !== '(sin salida)') output += text;
+          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;
         }
       }
-      for (const { file, before } of files.values()) { const after = hash(await this.text(file)); if (after !== before) throw new Error('El archivo cambió durante la comprobación; vuelve a verificar.'); observe({ kind: 'file_read', file_path: path.relative(this.cwd, file), sha256: after }); }
-      return output || '(sin salida)';
+      for (const { file, before } of files.values()) { const after = hash(await this.text(file)); if (after !== before) throw new Error('The file changed during the check; verify again.'); observe({ kind: 'file_read', file_path: path.relative(this.cwd, file), sha256: after }); }
+      return output || '(no output)';
     }
     if (name === 'Grep') {
       const target = await this.resolve(input.path || '.');
       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 debe ser relativo al workspace.');
+      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;
       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 excedió 20000 entradas; usa Grep o un workspace menor.');
+          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);
@@ -198,11 +211,48 @@ export class WorkspaceTools {
         }
       };
       await walk(this.cwd);
-      return files.sort().slice(0, 1000).join('\n') || '(sin coincidencias)';
+      return files.sort().slice(0, 1000).join('\n') || '(no matches)';
     }
   }
 }
 
+const fileHashError = (message, code) => Object.assign(new Error(message), { code });
+const sameFileVersion = (left, right) => ['dev', 'ino', 'size', 'mtimeNs', 'ctimeNs'].every(key => left[key] === right[key]);
+async function hashWorkspaceFile(file, { signal, expected, verifyPath }) {
+  const deadline = AbortSignal.timeout(HASH_TIMEOUT), combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
+  const check = () => {
+    signal?.throwIfAborted();
+    if (deadline.aborted) throw fileHashError('File hashing exceeded 10 seconds. Try a smaller artifact.', 'FILE_HASH_TIMEOUT');
+  };
+  let handle, stream;
+  try {
+    check();
+    handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile()) throw fileHashError('Hashing requires a regular file.', 'FILE_HASH_TYPE');
+    if (before.size > BigInt(HASH_LIMIT)) throw fileHashError('File hashing supports at most 256 MiB.', 'FILE_HASH_LIMIT');
+    if (before.dev !== BigInt(expected.dev) || before.ino !== BigInt(expected.ino)) throw fileHashError('The file changed before hashing. Retry FileInfo.', 'FILE_HASH_CHANGED');
+    await verifyPath();
+    if (!sameFileVersion(before, await stat(file, { bigint: true }))) throw fileHashError('The file changed before hashing. Retry FileInfo.', 'FILE_HASH_CHANGED');
+    const digest = createHash('sha256'); let bytes = 0, signature = Buffer.alloc(0);
+    stream = handle.createReadStream({ highWaterMark: HASH_CHUNK, autoClose: false, signal: combined });
+    for await (const chunk of stream) {
+      check(); bytes += chunk.length;
+      if (bytes > HASH_LIMIT) throw fileHashError('File hashing supports at most 256 MiB.', 'FILE_HASH_LIMIT');
+      if (signature.length < 32) signature = Buffer.concat([signature, chunk.subarray(0, 32 - signature.length)]);
+      digest.update(chunk);
+    }
+    check();
+    const after = await handle.stat({ bigint: true }); await verifyPath();
+    if (!sameFileVersion(before, after) || !sameFileVersion(before, await stat(file, { bigint: true })) || BigInt(bytes) !== before.size) throw fileHashError('The file changed while hashing. Retry FileInfo.', 'FILE_HASH_CHANGED');
+    check(); return { bytes, sha256: digest.digest('hex'), mimeType: mediaSignature(signature), info: after };
+  } catch (error) {
+    check();
+    if (error.code === 'ELOOP') throw fileHashError('The file changed to a symbolic link before hashing.', 'FILE_HASH_CHANGED');
+    throw error;
+  } finally { stream?.destroy(); await handle?.close(); }
+}
+
 function mediaSignature(bytes) {
   if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg';
   if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return 'image/png';
@@ -244,7 +294,7 @@ export function runProcess(command, args, { cwd, timeout = 30000, signal, allowN
       if (chunk.length > available) truncated = true;
     };
     child.stdout.on('data', receive); child.stderr.on('data', receive);
-    const timer = setTimeout(() => terminate(new Error(`Comando excedió ${timeout} ms.`)), timeout);
+    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); };
@@ -253,8 +303,8 @@ export function runProcess(command, args, { cwd, timeout = 30000, signal, allowN
       cleanup();
       // Leave the short kill timer alive after timeout to stop remaining descendants.
       if (failure) reject(failure);
-      else if (code !== 0 && !(allowNoMatch && code === 1)) reject(new Error(`Comando terminó con código ${code}: ${output}`));
-      else resolve(output + (truncated ? '\n[Salida limitada a 64 KiB]' : '') || '(sin salida)');
+      else if (code !== 0 && !(allowNoMatch && code === 1)) reject(new Error(`Command exited with code ${code}: ${output}`));
+      else resolve(output + (truncated ? '\n[Output limited to 64 KiB]' : '') || '(no output)');
     });
   });
 }

package/src/tui/brand.mjs

@@ -1,3 +1,4 @@
+import { t } from '../i18n/index.mjs';
 import { clip, createTones, width } from './text.mjs';
 
 export const BRAND_FRAME_INTERVAL_MS = 240;
@@ -36,7 +37,7 @@ export function brandingWelcome({ columns = 80, frame = 0, active = false, motio
   const heat = ascii ? ['     . . .', '      . .', '     . . .', '    . . .'] : ['     · · ·', '      ˙ ·', '     · ˙ ·', '    ˙ · ˙'];
   const icon = [tones.muted(steam[phase]), ...mark.map(line => '  ' + tones.accent(line)), tones.tierra(plate[0]), tones.tierra(plate[1]), tones.secondary(heat[phase])];
   const label = tones.bold(tones.accent('COMAL'));
-  const caption = ['Operaciones con intención.', 'Cada vuelta deja un recibo.'];
+  const caption = [t("Operations with intent."), t("Every turn leaves a receipt.")];
   const rows = room >= 61 ? icon.map((line, index) => line + ' '.repeat(Math.max(1, 24 - width(line))) + (index === 2 ? label : index === 4 ? tones.muted(caption[0]) : index === 5 ? tones.muted(caption[1]) : '')) : [...icon, '', label, ...caption.map(line => tones.muted(line))];
   return rows.map(line => clip(line, room));
 }

package/src/tui/clipboard.mjs

@@ -1,10 +1,11 @@
+import { t } from '../i18n/index.mjs';
 import { spawn } from 'node:child_process';
 import { safeText } from './text.mjs';
 
 // Write only. Text travels over stdin, never through shell arguments.
 export async function copyText(text, { env = process.env, platform = process.platform, spawnProcess = spawn, timeoutMs = 3000 } = {}) {
   const value = safeText(text, { preserveTabs: true });
-  if (!value.trim()) throw new Error('No hay texto de respuesta para copiar.');
+  if (!value.trim()) throw new Error(t("No response text to copy."));
   const candidates = platform === 'darwin' ? [['pbcopy', []]] : [
     ...(env.WAYLAND_DISPLAY ? [['wl-copy', []]] : []),
     ...(env.DISPLAY ? [['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]] : []),
@@ -15,14 +16,14 @@ export async function copyText(text, { env = process.env, platform = process.pla
         const child = spawnProcess(command, args, { env, stdio: ['pipe', 'ignore', 'ignore'], shell: false });
         let settled = false;
         const finish = error => { if (settled) return; settled = true; clearTimeout(timer); error ? reject(error) : resolve(); };
-        const timer = setTimeout(() => { child.kill(); finish(new Error('Tiempo de espera agotado.')); }, timeoutMs);
+        const timer = setTimeout(() => { child.kill(); finish(new Error(t("Timed out."))); }, timeoutMs);
         child.once('error', finish);
-        child.once('close', code => finish(code === 0 ? null : new Error(`Código ${code}`)));
+        child.once('close', code => finish(code === 0 ? null : new Error(t("Code {v0}", {v0: code}))));
         child.stdin.on('error', error => { child.kill(); finish(error); });
         child.stdin.end(value);
       });
       return command;
     } catch { /* Try the next installed desktop clipboard provider. */ }
   }
-  throw new Error('No se pudo escribir al portapapeles. Usa F5, selecciona con el mouse y copia desde tu terminal. En Linux puedes instalar wl-clipboard (Wayland) o xclip (X11).');
+  throw new Error(t("Could not write to the clipboard. Use F5, select with the mouse and copy from your terminal. On Linux you can install wl-clipboard (Wayland) or xclip (X11)."));
 }