@milpa/comal 0.2.4 → 0.2.5

package/README.md

@@ -28,7 +28,7 @@ comal --help
 
 Keep the PATH line in your shell startup file if you use that prefix. If your Node manager already provides a user prefix, you can omit `--prefix "$HOME/.local"`. The package registers the `comal` executable; you do not need to create a shell alias.
 
-You can pin a version with `npx @milpa/comal@0.2.4` or `npm install --global @milpa/comal@0.2.4`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
+You can pin a version with `npx @milpa/comal@0.2.5` or `npm install --global @milpa/comal@0.2.5`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
 
 ## Test without account or model
 

package/backend/contracts/remote-device-v1.json

@@ -1,6 +1,6 @@
 {
   "protocol": "comal.remote.device.v1",
-  "description": "Contract between a Comal Remote Control (/rc) session and an M5Stack device: pairing, the two inputs a device may send, the ephemeral permission card, the session.stats projection and the reasons a device is refused. The device is a pre-check surface only: the local Comal host revalidates every answer (arm, expiry, card digest, session, device) before mutating. Owned by the Comal Node repository; the backend keeps a byte-identical copy.",
+  "description": "Contract between a Comal Remote Control (/rc) session and an M5Stack device: pairing, the two inputs a device may send, the ephemeral permission card, the session.stats projection, the ephemeral speech chunks (8-bit unsigned mono PCM the host sends the paired device through the relay; never stored) and the reasons a device is refused. The device is a pre-check surface only: the local Comal host revalidates every answer (arm, expiry, card digest, session, device) before mutating. Owned by the Comal Node repository; the backend keeps a byte-identical copy.",
   "pairing": {
     "code_alphabet": "0123456789ABCDEFGHJKMNPQRSTVWXYZ",
     "code_length": 8,
@@ -406,6 +406,53 @@
       ]
     }
   },
+  "speech": {
+    "maxBytes": 6144,
+    "format": {
+      "encoding": "pcm_u8",
+      "channels": 1,
+      "sample_rate": 11025,
+      "chunk_max_bytes": 4096,
+      "phrase_max_seconds": 6
+    },
+    "schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{16}$"
+        },
+        "seq": {
+          "type": "string",
+          "pattern": "^(0|[1-9][0-9]?)$"
+        },
+        "last": {
+          "type": "boolean"
+        },
+        "about": {
+          "type": "string",
+          "enum": [
+            "permission",
+            "failure",
+            "turn"
+          ]
+        },
+        "audio": {
+          "type": "string",
+          "maxLength": 5464,
+          "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})$"
+        }
+      },
+      "required": [
+        "id",
+        "seq",
+        "last",
+        "about",
+        "audio"
+      ]
+    }
+  },
   "arm": {
     "default_seconds": 1800,
     "max_seconds": 28800

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milpa/comal",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Comal: governed operations, execution receipts, and programming assistance in any language",
   "type": "module",
   "private": false,

package/src/cli.mjs

@@ -7,6 +7,7 @@ import { t, registerMessages, configureLanguage, languageArguments } from './i18
 import cliSpanish from './i18n/cli-es.mjs';
 registerMessages(cliSpanish);
 import { RemoteHost } from './remote-control.mjs';
+import { speechFromEnv, permissionSpeech } from './remote-speech.mjs';
 import { PermissionDesk, confirmWithDevice } from './remote-permissions.mjs';
 import { remoteCommandHelp, isRemoteCommand } from './remote-commands.mjs';
 import { codeRunDefinition } from './code-run.mjs';
@@ -375,6 +376,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
   const interactive = !print;
   const color = (code, text) => stdout.isTTY && !process.env.NO_COLOR ? `\x1b[${code}m${text}\x1b[0m` : text;
   let remoteHost;
+  const remoteSpeech = speechFromEnv(process.env);
   // One desk per process: a permission card answered from the paired M5Stack races the terminal card.
   const permissionDesk = new PermissionDesk({ sendCard: card => remoteHost?.sendCard(card), closeCard: id => remoteHost?.closeCard(id), record: row => store.append(session.id, { ...row, source: 'remote_device', at: new Date().toISOString() }) });
   let controller, authController, modelController, scanController, runtime, peerBus, listenTimer, listenFinish, swarmFeed, relayFollower, textOpen = false, lastGoalDisplay = '';
@@ -389,6 +391,8 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
       const signals = [options.signal, controller?.signal || startupSignal].filter(Boolean), signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
       const card = options.summary === undefined ? await house.confirmSummary(name, input, { signal }) : null;
       const summary = options.summary ?? card?.summary, terminal = shown => ui.confirm(name, input, shown, { summary, edit: card?.edit, remember: options.remember });
+      // Granito speaks the question whether or not the device is armed to answer it; synchronous, never awaited.
+      try { remoteHost?.sendSpeech(permissionSpeech({ name, input, armed: remoteHost?.permissionsArmed() === true, plan: policy.mode === 'plan', confirmAlways: policy.confirmAlways(name) === true }), 'permission'); } catch {}
       return confirmWithDevice({ armed: remoteHost?.permissionsArmed() === true, desk: permissionDesk, questionId: options.questionId, name, input, summary, signal, terminal, resolveWrite: (file, how) => tools.resolve(file, how), confirmAlways: () => policy.confirmAlways(name), mode: () => policy.mode, notice: text => ui.notice(text) });
     } : undefined });
   // /add-dir rows are the human's decisions in this session's book (under .comal, which the model cannot write);
@@ -620,7 +624,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
   house.registry.add({name:'CloudAccountLogout',description:'Human detaches Remote Control and removes the local Comal account credential.',input_schema:emptyInput,audience:'human',surfaces:['tui'],permission:null,effects:{workspace:'none',external:'write',process:'none',authority:'credential_control'},run:async()=>{await remoteHost?.stop();return cloudClient.logout();}});
   const openRemoteControl=async()=>{
     if(!runtime)throw Error('Remote Control requires an interactive local session.');
-    if(!remoteHost || remoteHost.stopped)remoteHost=new RemoteHost({client:new CloudClient({origin:v['cloud-url']}),onInput:(input,binding)=>runtime.admitRemote(input,binding),onStop:id=>runtime.stopRemote(id),onNotice:text=>ui.notice(text),getWorkspace:async snapshot=>projectRemoteWorkspace(snapshot || await store.load(session.id),house.stateContext()),relay:relayRemote,onRelay:interactive?(input,binding)=>relayAnswers.handle(input,binding):null,onPermission:interactive?(input,binding)=>permissionDesk.handle(input,binding):null,onPermissionsDisarmed:reason=>{store.append(session.id,{type:'remote_control',action:'permissions.arm',armed:false,until:null,reason,source:'host',at:new Date().toISOString()}).catch(()=>{});},getStats:sessionStats});
+    if(!remoteHost || remoteHost.stopped)remoteHost=new RemoteHost({client:new CloudClient({origin:v['cloud-url']}),speech:remoteSpeech,onInput:(input,binding)=>runtime.admitRemote(input,binding),onStop:id=>runtime.stopRemote(id),onNotice:text=>ui.notice(text),getWorkspace:async snapshot=>projectRemoteWorkspace(snapshot || await store.load(session.id),house.stateContext()),relay:relayRemote,onRelay:interactive?(input,binding)=>relayAnswers.handle(input,binding):null,onPermission:interactive?(input,binding)=>permissionDesk.handle(input,binding):null,onPermissionsDisarmed:reason=>{store.append(session.id,{type:'remote_control',action:'permissions.arm',armed:false,until:null,reason,source:'host',at:new Date().toISOString()}).catch(()=>{});},getStats:sessionStats});
     const connection = new AbortController(); authController = connection;
     const cancel = () => remoteHost.stop().catch(() => {});
     connection.signal.addEventListener('abort', cancel, { once: true });

package/src/remote-control.mjs

@@ -1,8 +1,9 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { CloudClient } from './cloud-client.mjs';
 import { readFileSync } from 'node:fs';
 import { PERMISSION_ACK_STATES, PERMISSION_OUTCOMES } from './remote-permissions.mjs';
 import { fitStats, STATS_FLOOR_MS, STATS_INTERVAL_MS, STATS_MAX_BYTES } from './remote-stats.mjs';
+import { failurePhrase, speechFrames, SpeechPacer, SPEECH_MAX_BYTES, SPEECH_MAX_BUFFERED, SPEECH_QUIET_AFTER_DELTA_MS, SPEECH_WINDOW_CEILING, SPEECH_WINDOW_MS, turnPhrase } from './remote-speech.mjs';
 
 const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
 export const remoteInputDigest = (session, request, text) => digest([session,request,text]);
@@ -63,6 +64,8 @@ export const CARD_RESEND_MS = 10000;
 // After an arm, a kept card goes once the pulse landed and again this long after: past the relay's 2 s arm cache.
 export const CARD_ARM_RECHECK_MS = 2500;
 const CARD_CLOSES_KEPT = 32;
+// What a phrase may be about (the contract's speech.schema.properties.about.enum).
+const SPEECH_ABOUT = new Set(['permission','failure','turn']);
 
 // Código de emparejamiento del M5Stack: Crockford en mayúsculas, XXXX-XXXX. O→0, I/L→1.
 const DEVICE_CODE=/^[0-9A-HJKMNP-TV-Z]{8}$/;
@@ -79,10 +82,13 @@ let quickReplyList=null;
 /** The three fixed replies come from the device contract, read once. */
 function quickReplies(){return quickReplyList??=JSON.parse(readFileSync(new URL('../backend/contracts/remote-device-v1.json',import.meta.url),'utf8')).inputs.quick_reply.properties.text.enum;}
 export class RemoteHost {
-  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},getWorkspace=null,relay=null,onRelay=null,onDeviceConnected=null,onPermissionsDisarmed=null,onPermission=null,getStats=null,now=Date.now,socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
-    Object.assign(this,{client,onInput,onStop,onNotice,getWorkspace,relay,onRelay,onDeviceConnected,onPermissionsDisarmed,onPermission,getStats,now,socketFactory});this.cards=new Map();this.cardCloses=[];this.cardsSentAt=0;this.cardsShown=false;this.answersUntil=0;this.permissionUntil=0;this.permissionDevice=null;this.deviceInfo=null;this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
+  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},getWorkspace=null,relay=null,onRelay=null,onDeviceConnected=null,onPermissionsDisarmed=null,onPermission=null,getStats=null,speech=null,now=Date.now,socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
+    Object.assign(this,{client,onInput,onStop,onNotice,getWorkspace,relay,onRelay,onDeviceConnected,onPermissionsDisarmed,onPermission,getStats,speech,now,socketFactory});this.cards=new Map();this.cardCloses=[];this.cardsSentAt=0;this.cardsShown=false;this.answersUntil=0;this.permissionUntil=0;this.permissionDevice=null;this.deviceInfo=null;this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
+    // Granito's voice: frames sent over the host socket in the last SPEECH_WINDOW_MS, the last delta, the render in course.
+    this.sentFrames=[];this.lastDeltaAt=-Infinity;this.speechRender=null;
+    this.speechPacer=new SpeechPacer({send:frame=>this.speechAvailable()&&this.cardFrame(frame),room:()=>this.speechRoom(),now:this.now});
   }
-  status(){const run=this.lifecycle;return this.session?{enabled:!this.stopped,url:this.url,session:this.session.id,transport:this.transport,permissions:'local_terminal_only',relay:run?.relay?(run.answers?'answers':'read_only'):'off',...(run?.answers?{relay_answers:{armed:this.armed(),until:this.armed()?this.answersUntil:null}}:{}),...(run?.device?{device:this.deviceInfo??null,permission_answers:{armed:this.permissionsArmed(),until:this.permissionsArmed()?this.permissionUntil:null}}:{})}:{enabled:false};}
+  status(){const run=this.lifecycle;return this.session?{enabled:!this.stopped,url:this.url,session:this.session.id,transport:this.transport,permissions:'local_terminal_only',relay:run?.relay?(run.answers?'answers':'read_only'):'off',...(run?.answers?{relay_answers:{armed:this.armed(),until:this.armed()?this.answersUntil:null}}:{}),...(run?.device?{device:this.deviceInfo??null,permission_answers:{armed:this.permissionsArmed(),until:this.permissionsArmed()?this.permissionUntil:null},speech:this.speechStatus()}:{})}:{enabled:false};}
   deviceAvailable(){return Boolean(this.current(this.lifecycle)&&this.lifecycle.device);}
   permissionsArmed(){return this.deviceAvailable()&&this.permissionUntil>this.now()&&Boolean(this.deviceInfo)&&this.deviceInfo.id===this.permissionDevice;}
   /** The arm belongs to the device it was granted for: when that device is gone or another takes its place, it ends and the book hears why. */
@@ -139,7 +145,43 @@ export class RemoteHost {
   /** One frame over the host WebSocket, only when it is the live transport. Never over remote.events.publish. */
   cardFrame(frame){
     if(this.transport!=='websocket'||this.socket?.readyState!==1)return false;
-    try{this.socket.send(JSON.stringify({protocol:'comal.remote.v1',...frame}));return true;}catch{return false;}
+    try{this.socket.send(JSON.stringify({protocol:'comal.remote.v1',...frame}));}catch{return false;}
+    this.noteFrame(frame.kind);return true;
+  }
+  /** Counts a frame sent over the host socket, for the relay's window; a delta also restarts the quiet speech waits for. */
+  noteFrame(kind){
+    const now=this.now();
+    this.sentFrames=this.sentFrames.filter(at=>now-at<SPEECH_WINDOW_MS);this.sentFrames.push(now);
+    if(kind==='delta')this.lastDeltaAt=now;
+  }
+  /** May a speech chunk go now without pushing the host past the relay's budget? */
+  speechRoom(){
+    if(this.transport!=='websocket'||this.socket?.readyState!==1)return false;
+    const now=this.now();
+    if(now-this.lastDeltaAt<SPEECH_QUIET_AFTER_DELTA_MS)return false;
+    this.sentFrames=this.sentFrames.filter(at=>now-at<SPEECH_WINDOW_MS);
+    if(this.sentFrames.length>=SPEECH_WINDOW_CEILING)return false;
+    return (this.socket.bufferedAmount??0)<SPEECH_MAX_BUFFERED;
+  }
+  /** Speech goes only where it cannot hurt: speech_v1 granted, a relay that said it accepts speech (an older one closes
+   *  the host socket on an unknown frame), the WebSocket transport, a paired device and a Piper voice. */
+  speechAvailable(){const run=this.lifecycle;return Boolean(this.current(run)&&run.speech&&run.speechRelay&&this.transport==='websocket'&&this.deviceInfo&&this.speech?.ready===true);}
+  speechStatus(){const run=this.lifecycle;if(this.speech?.ready!==true)return 'no_piper';if(!(run?.speech&&run?.speechRelay))return 'not_offered';return 'ready';}
+  /** Speaks a phrase on the paired device. Synchronous and fire-and-forget: rendering and sending never hold a turn or
+   *  the permission flow, and every failure is swallowed. A newer phrase replaces the one rendering or playing. */
+  sendSpeech(text,about){
+    try{
+      if(typeof text!=='string'||!text.trim()||!SPEECH_ABOUT.has(about)||!this.speechAvailable())return false;
+      this.speechRender?.abort();
+      const controller=new AbortController(),run=this.lifecycle;this.speechRender=controller;
+      Promise.resolve(this.speech.render(text,{signal:controller.signal})).then(pcm8=>{
+        if(this.speechRender!==controller||controller.signal.aborted||!this.current(run))return;
+        this.speechRender=null;
+        if(!Buffer.isBuffer(pcm8)||!pcm8.length||!this.speechAvailable())return;
+        this.speechPacer.play({frames:speechFrames({id:randomBytes(8).toString('hex'),about,pcm8:pcm8.subarray(0,SPEECH_MAX_BYTES)})});
+      }).catch(()=>{});
+      return true;
+    }catch{return false;}
   }
   /** Permission card for the paired device (Task 10's buildDeviceCard). Nothing is kept or sent while not armed. */
   sendCard(card){
@@ -196,13 +238,14 @@ export class RemoteHost {
         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 workspace=this.getWorkspace?await this.getWorkspace(session):null;this.assertCurrent(run,{starting:true});
-        const features=['commands_v1','thinking_v1',...(this.getWorkspace?['workspace_v1']:[]),...(this.relay?['relay_v1']:[]),...(this.relay&&this.onRelay?['relay_answers_v1']:[]),'device_v1','stats_v1'];
+        const features=['commands_v1','thinking_v1',...(this.getWorkspace?['workspace_v1']:[]),...(this.relay?['relay_v1']:[]),...(this.relay&&this.onRelay?['relay_answers_v1']:[]),'device_v1','stats_v1','speech_v1'];
         const open=list=>this.client.invoke('remote.sessions.open',{local_session_id:session.id,host_id:randomUUID(),label:boundText(session.name || 'Comal',80),features:list},{expectedAccount:run.account,signal:run.controller.signal});
         // Un backend anterior rechaza la capacidad desconocida en el esquema de Milpa (no se crea
         // sesión): se reintenta sin relay_answers_v1 (backend de la fase «ver») y después sin
         // relay_v1 (backend anterior a /relay). /rc se abre igual con lo que el backend admite.
-        const noDevice=features.filter(item=>item!=='device_v1'&&item!=='stats_v1');
-        const attempts=[features,noDevice,noDevice.filter(item=>item!=='relay_answers_v1'),noDevice.filter(item=>!item.startsWith('relay_'))].filter((list,index,all)=>index===0||list.length<all[index-1].length);
+        // speech_v1 goes first (a backend before Granito's voice), then the device features with it.
+        const noDevice=features.filter(item=>item!=='device_v1'&&item!=='stats_v1'&&item!=='speech_v1');
+        const attempts=[features,features.filter(item=>item!=='speech_v1'),noDevice,noDevice.filter(item=>item!=='relay_answers_v1'),noDevice.filter(item=>!item.startsWith('relay_'))].filter((list,index,all)=>index===0||list.length<all[index-1].length);
         let opened,used=attempts[0];
         for(const [index,list] of attempts.entries()){
           try{used=list;opened=await open(list);break;}
@@ -211,7 +254,7 @@ export class RemoteHost {
         run.relayRefused=Boolean(this.relay)&&!used.includes('relay_v1');
         run.session=opened.session;
         const granted=feature=>used.includes(feature)&&(!Array.isArray(opened.session?.features)||opened.session.features.includes(feature));
-        run.relay=Boolean(this.relay)&&granted('relay_v1');run.answers=run.relay&&Boolean(this.onRelay)&&granted('relay_answers_v1');this.answersUntil=0;run.device=granted('device_v1');run.stats=Boolean(this.getStats)&&granted('stats_v1');this.permissionUntil=0;this.permissionDevice=null;this.deviceInfo=null;
+        run.relay=Boolean(this.relay)&&granted('relay_v1');run.answers=run.relay&&Boolean(this.onRelay)&&granted('relay_answers_v1');this.answersUntil=0;run.device=granted('device_v1');run.speech=run.device&&granted('speech_v1');run.speechRelay=false;run.stats=Boolean(this.getStats)&&granted('stats_v1');this.permissionUntil=0;this.permissionDevice=null;this.deviceInfo=null;
         // 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();}
@@ -262,9 +305,9 @@ export class RemoteHost {
       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';this.flushCardCloses();this.sendCards();}else if(m.kind==='state'&&run.device)this.noteSession(m.session);}catch{ws.close();}});
+      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);run.speechRelay=Array.isArray(m.accepts)&&m.accepts.includes('speech');this.transport='websocket';this.flushCardCloses();this.sendCards();}else if(m.kind==='state'&&run.device)this.noteSession(m.session);}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';}});
+      ws.addEventListener('close',()=>{clearTimeout(timeout);if(this.current(run)&&this.socket===ws){this.socket=null;this.transport='https-polling';run.speechRelay=false;this.speechPacer.cancel();}});
     }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;}}
   }
@@ -358,6 +401,8 @@ export class RemoteHost {
   }
   observe(event) {
     if(this.stopped)return;
+    if(event.type==='tool_result'&&event.is_error===true&&!String(event.content??'').includes('HOUSE_REFUSED'))try{this.sendSpeech(failurePhrase(event.name),'failure');}catch{}
+    if(event.type==='result'&&event.turns>0&&typeof event.result==='string')try{const phrase=turnPhrase(event.result);if(phrase)this.sendSpeech(phrase,'turn');}catch{}
     if(['tool_result','house_waiting','house_answered','result'].includes(event.type))this.invalidateWorkspace();
     const append=projected=>this.pending.push({event_id:randomUUID(),event:projected});
     if(['result','context_projection','usage_accounting'].includes(event.type))this.publishStats().catch(()=>{});
@@ -373,7 +418,7 @@ export class RemoteHost {
     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);}
+        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)}));this.noteFrame('delta');}},120);}
       }
       return;
     }
@@ -465,7 +510,7 @@ export class RemoteHost {
   }
   async stop(){
     const run=this.lifecycle || {session:this.session,account:this.account,enablingToken:this.enablingToken};
-    this.lifecycle=null;this.starting=null;run.controller?.abort();clearTimeout(run.workspaceTimer);clearTimeout(run.boardTimer);clearTimeout(run.statsTimer);if(run.relaySink)this.relay?.detach(run.relaySink);
+    this.lifecycle=null;this.starting=null;run.controller?.abort();this.speechRender?.abort();this.speechRender=null;this.speechPacer.cancel();this.sentFrames=[];clearTimeout(run.workspaceTimer);clearTimeout(run.boardTimer);clearTimeout(run.statsTimer);if(run.relaySink)this.relay?.detach(run.relaySink);
     this.stopped=true;this.answersUntil=0;this.permissionUntil=0;this.permissionDevice=null;this.cards.clear();this.cardCloses=[];this.cardsSentAt=0;this.cardsShown=false;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/remote-device.mjs

@@ -10,6 +10,9 @@ registerMessages({
   'The camera read the code {code}. Pair only if it is the code on the M5Stack\'s screen.': 'La cámara leyó el código {code}. Empareja sólo si es el código de la pantalla del M5Stack.',
   'Pair {code}': 'Emparejar {code}',
   'Do not pair': 'No emparejar',
+  'voice: ready': 'voz: lista',
+  'voice: no Piper (COMAL_PIPER_VOICE)': 'voz: sin Piper (COMAL_PIPER_VOICE)',
+  'voice: not available on this connection': 'voz: no disponible en esta conexión',
 });
 
 // Forward the House's permission rows to the Remote Control projection.
@@ -44,7 +47,9 @@ export async function runRcDevice(parsed, host, t, { record } = {}) {
   if (!host || host.stopped || !host.deviceAvailable()) throw Error(t('Open /rc first, with a Comal backend that supports devices.'));
   if (parsed.kind === 'status') {
     const device = host.status().device;
-    return device ? t('Device: {label} ({id}){connected}.', { label: device.label, id: device.id, connected: device.connected_at ? t(', connected {time}', { time: String(device.connected_at) }) : '' }) : t('No device paired.');
+    const line = device ? t('Device: {label} ({id}){connected}.', { label: device.label, id: device.id, connected: device.connected_at ? t(', connected {time}', { time: String(device.connected_at) }) : '' }) : t('No device paired.');
+    const voice = { ready: t('voice: ready'), no_piper: t('voice: no Piper (COMAL_PIPER_VOICE)') }[host.speechStatus()] ?? t('voice: not available on this connection');
+    return line + '\n' + voice;
   }
   if (parsed.kind === 'forget') { const wasArmed = host.permissionsArmed(); await host.forgetDevice(); if (wasArmed) await record?.(ARM_ROW(false, 0)); return t('Device removed; its permission answers are off.'); }
   const paired = await host.pairDevice(parsed.code);

package/src/remote-speech.mjs

@@ -0,0 +1,275 @@
+// Granito's voice, host side: the short phrases a paired device speaks, and their conversion to the
+// device's PCM format. Pure module: the only I/O is the one read of the contract.
+import { readFileSync } from 'node:fs';
+import { spawn as nodeSpawn } from 'node:child_process';
+import { stripForDevice } from './remote-device-card.mjs';
+
+const SPEECH = JSON.parse(readFileSync(new URL('../backend/contracts/remote-device-v1.json', import.meta.url), 'utf8')).speech;
+export const SPEECH_RATE = SPEECH.format.sample_rate;
+export const SPEECH_CHUNK_BYTES = SPEECH.format.chunk_max_bytes;
+export const SPEECH_MAX_BYTES = SPEECH_RATE * SPEECH.format.phrase_max_seconds;
+// About 6 s of the voice (Piper speaks ~14-16 characters a second): a longer sentence would be cut mid-word.
+export const TURN_PHRASE_CHARS = 90;
+const TOOL_NAME_CHARS = 40;
+const BASENAME_CHARS = 60;
+
+const chars = text => Array.from(text);
+const collapse = text => text.replace(/\s+/g, ' ').trim();
+
+/** Cut to `limit` code points, ending on a whole word when one fits. */
+function capWords(text, limit) {
+  const all = chars(text);
+  if (all.length <= limit) return text;
+  if (all[limit] === ' ') return all.slice(0, limit).join('').trimEnd();
+  const space = all.slice(0, limit).lastIndexOf(' ');
+  return all.slice(0, space > 0 ? space : limit).join('').trimEnd();
+}
+
+export function speakableToolName(name) {
+  let text = stripForDevice(name).replace(/^mcp__.+?__/, '');
+  text = collapse(text.replace(/_/g, ' '));
+  return capWords(text, TOOL_NAME_CHARS);
+}
+
+function fileLabel(path) {
+  if (typeof path !== 'string') return '';
+  const base = path.split(/[\\/]/).filter(Boolean).pop() ?? '';
+  return chars(collapse(stripForDevice(base))).slice(0, BASENAME_CHARS).join('').trim();
+}
+
+export function permissionPhrase({ name, input, terminalOnly = false }) {
+  let what;
+  if (name === 'Write' || name === 'Edit') {
+    what = 'escribir ' + ((!terminalOnly && fileLabel(input?.file_path)) || 'un archivo');
+  } else if (name === 'Bash') what = 'correr un comando';
+  else what = 'usar ' + (speakableToolName(name) || 'una herramienta');
+  return `Necesito tu permiso para ${what}.`;
+}
+
+/** The permission phrase as spoken: the file is named only where the device itself may show it (armed, not plan
+ *  mode, not confirm-always); otherwise the name never leaves the terminal. */
+export function permissionSpeech({ name, input, armed = false, plan = false, confirmAlways = false }) {
+  return permissionPhrase({ name, input, terminalOnly: armed !== true || plan === true || confirmAlways === true });
+}
+
+export function failurePhrase(name) {
+  return `Falló ${speakableToolName(name) || 'una herramienta'}.`;
+}
+
+const HTML_ONLY = /^\s*(?:<\/?[A-Za-z][^>]*>\s*)+$/;
+const BOX_DRAWING = /[─-╿]/;
+const URL_RE = /\b(?:https?|ftp):\/\/\S+|\bwww\.\S+/g;
+const WRAP = '()[\\]"\'«»,;:';
+const PATH_TOKEN = new RegExp(`^([${WRAP}]*)(.*?)([${WRAP}]*)$`, 'u');
+
+function withoutFences(text) {
+  const out = [];
+  let fence = null;
+  for (const line of text.split('\n')) {
+    const open = /^\s*(```|~~~)/.exec(line);
+    if (fence) { if (open && open[1] === fence) fence = null; continue; }
+    if (open) { fence = open[1]; continue; }
+    out.push(line);
+  }
+  return out;
+}
+
+function reducePath(token) {
+  const m = PATH_TOKEN.exec(token);
+  const [, pre, core, post] = m;
+  if (!core.includes('/') || /^(?:https?|ftp):/i.test(core) || /^www\./i.test(core)) return token;
+  const segments = core.split('/').filter(Boolean);
+  if (!segments.length) return token;
+  const last = segments[segments.length - 1];
+  const pathLike = /^(?:\/|~\/|\.\/|\.\.\/)/.test(core) || core.split('/').length - 1 >= 2 || last.includes('.');
+  return pathLike ? pre + last + post : token;
+}
+
+export function turnPhrase(text) {
+  let lines = withoutFences(String(text ?? '').replace(/\r\n?/g, '\n'))
+    .filter(l => !/^\s{0,3}#{1,6}\s/.test(l) && !/^\s*\|/.test(l) && !HTML_ONLY.test(l) && !BOX_DRAWING.test(l))
+    .map(l => l.replace(/^\s*(?:(?:[-*+]|\d+[.)]|>)\s+)+/, ''));
+  lines = lines.map(line => line
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/`([^`]*)`/g, (_, code) => (!/\s/.test(code) && chars(code).length <= 60 ? code : ''))
+    .replace(URL_RE, '')
+    .replace(/\*\*|__|~~/g, '')
+    .replace(/(^|[\s(])([*_])(\S[^*_]*?)\2(?=[\s).,;:!?]|$)/g, '$1$3')
+    .replace(/<\/?[A-Za-z][^>]*>/g, '')
+    .replace(/\p{Extended_Pictographic}|️/gu, ''))
+    .map(line => stripForDevice(line).replace(/[ \t]+/g, ' ').split(' ').map(reducePath).join(' '));
+  const first = lines.find(l => l.trim());
+  if (first === undefined) return null;
+  const sentence = /^(.*?[.!?…])(?=\s|$)/.exec(first.trim());
+  let out = collapse(sentence ? sentence[1] : first).replace(/^[:;,\-–— ]+/, '');
+  if (!out) return null;
+  const all = chars(out);
+  if (all.length > TURN_PHRASE_CHARS) {
+    const space = all.lastIndexOf(' ', TURN_PHRASE_CHARS - 1);
+    out = all.slice(0, space > 0 ? space : TURN_PHRASE_CHARS - 1).join('').trimEnd() + '…';
+  }
+  return out;
+}
+
+/** 16-bit little-endian PCM at `rate` Hz to the device's 8-bit unsigned mono at 11025 Hz. */
+export function toDevicePcm(pcm16le, rate) {
+  const samples = Math.floor(pcm16le.length / 2);
+  const ratio = rate / SPEECH_RATE;
+  const outLen = Math.min(Math.floor(samples / ratio), SPEECH_MAX_BYTES);
+  const out = Buffer.alloc(outLen);
+  for (let i = 0; i < outLen; i++) {
+    const start = Math.floor(i * ratio);
+    const end = Math.min(samples, Math.max(start + 1, Math.floor((i + 1) * ratio)));
+    let sum = 0;
+    for (let j = start; j < end; j++) sum += pcm16le.readInt16LE(j * 2);
+    out[i] = Math.min(255, Math.max(0, Math.round(sum / (end - start) / 256) + 128));
+  }
+  return out;
+}
+
+export function speechChunks(pcm8, max = SPEECH_CHUNK_BYTES) {
+  const out = [];
+  for (let at = 0; at < pcm8.length; at += max) out.push(pcm8.subarray(at, at + max));
+  return out;
+}
+
+export function speechFrames({ id, about, pcm8 }) {
+  const chunks = speechChunks(pcm8);
+  return chunks.map((chunk, index) => ({ kind: 'speech', id, seq: String(index), last: index === chunks.length - 1, about, audio: chunk.toString('base64') }));
+}
+
+export const PIPER_TIMEOUT_MS = 8000;
+const DEFAULT_VOICE_RATE = 22050;
+
+/** The sample rate Piper writes for `voice`, from its `.onnx.json`; 22050 when unreadable. */
+export function voiceRate(voice, { readFile = readFileSync } = {}) {
+  try {
+    const rate = JSON.parse(readFile(voice + '.json')).audio.sample_rate;
+    return Number.isInteger(rate) && rate >= 8000 && rate <= 48000 ? rate : DEFAULT_VOICE_RATE;
+  } catch { return DEFAULT_VOICE_RATE; }
+}
+
+/** Renders a phrase with a local Piper process. Never rejects; null means "no voice this time". */
+export class PiperSpeech {
+  #piper; #voice; #spawn; #readFile; #timeoutMs; #rate = null;
+
+  constructor({ piper = 'piper', voice = null, spawn = nodeSpawn, readFile = readFileSync, timeoutMs = PIPER_TIMEOUT_MS } = {}) {
+    this.#piper = piper; this.#voice = voice; this.#spawn = spawn; this.#readFile = readFile; this.#timeoutMs = timeoutMs;
+  }
+
+  get ready() { return typeof this.#voice === 'string' && this.#voice !== ''; }
+
+  async render(text, { signal } = {}) {
+    try {
+      const line = typeof text === 'string' ? collapse(text) : '';
+      if (!this.ready || !line || signal?.aborted) return null;
+      this.#rate ??= voiceRate(this.#voice, { readFile: this.#readFile });
+      return await this.#run(line, this.#rate, signal);
+    } catch { return null; }
+  }
+
+  #run(line, rate, signal) {
+    return new Promise(resolve => {
+      const cap = rate * 2 * 7;
+      const parts = [];
+      let size = 0, capped = false, timer = null, child = null, done = false;
+      const onAbort = () => { kill(); finish(null); };
+      const kill = () => { try { child?.kill('SIGKILL'); } catch { /* already gone */ } };
+      const finish = value => {
+        if (done) return;
+        done = true;
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        child?.stdout?.removeAllListeners('data');
+        child?.removeAllListeners('close');
+        child?.removeAllListeners('error');
+        resolve(value);
+      };
+      const pcm = () => {
+        const out = toDevicePcm(Buffer.concat(parts), rate);
+        return out.length ? out : null;
+      };
+      try {
+        child = this.#spawn(this.#piper, ['--model', this.#voice, '--output-raw'], { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true });
+        child.stdin.on('error', () => {});
+        child.stdout.on('data', chunk => {
+          if (capped) return;
+          const room = cap - size;
+          if (chunk.length >= room) {
+            parts.push(chunk.subarray(0, room)); size = cap; capped = true;
+            kill();
+          } else { parts.push(chunk); size += chunk.length; }
+        });
+        child.on('error', () => finish(null));
+        child.on('close', code => finish(capped || code === 0 ? pcm() : null));
+        signal?.addEventListener('abort', onAbort, { once: true });
+        timer = setTimeout(() => { kill(); finish(null); }, this.#timeoutMs);
+        child.stdin.write(line + '\n');
+        child.stdin.end();
+      } catch { kill(); finish(null); }
+    });
+  }
+}
+
+export function speechFromEnv(env = process.env, deps = {}) {
+  const set = value => (typeof value === 'string' && value.trim() ? value.trim() : null);
+  return new PiperSpeech({ ...deps, piper: set(env.COMAL_PIPER) ?? 'piper', voice: set(env.COMAL_PIPER_VOICE) });
+}
+
+// Pacing of speech frames over the host socket. The relay allows a host socket 100 frames / 10 s and 16 pending, and
+// silently drops a speech frame past 70 frames in its window or 4 pending: one chunk every 300 ms at most, only once
+// deltas have been quiet for a second, below 70 frames in the last 10 s and with little left in the send buffer.
+export const SPEECH_CHUNK_INTERVAL_MS = 300;
+export const SPEECH_QUIET_AFTER_DELTA_MS = 1000;
+export const SPEECH_WINDOW_MS = 10000;
+export const SPEECH_WINDOW_CEILING = 70;
+export const SPEECH_MAX_BUFFERED = 16384;
+export const SPEECH_PHRASE_DEADLINE_MS = 15000;
+
+/** Plays one phrase at a time, a chunk per tick while `room()` says so. A newer phrase replaces the current one; a
+ *  failed send or a phrase older than its deadline is dropped, never retried. Never throws. */
+export class SpeechPacer {
+  #send; #room; #now; #intervalMs; #deadlineMs; #setTimer; #clearTimer;
+  #frames = null; #next = 0; #startedAt = 0; #timer = null;
+
+  constructor({ send, room, now = Date.now, intervalMs = SPEECH_CHUNK_INTERVAL_MS, deadlineMs = SPEECH_PHRASE_DEADLINE_MS, setTimer = setTimeout, clearTimer = clearTimeout }) {
+    this.#send = send; this.#room = room; this.#now = now; this.#intervalMs = intervalMs; this.#deadlineMs = deadlineMs;
+    this.#setTimer = setTimer; this.#clearTimer = clearTimer;
+  }
+
+  get busy() { return this.#frames !== null && this.#now() - this.#startedAt <= this.#deadlineMs; }
+
+  play({ frames }) {
+    this.cancel();
+    if (!Array.isArray(frames) || !frames.length) return;
+    this.#frames = frames; this.#next = 0; this.#startedAt = this.#now();
+    this.#schedule(0);
+  }
+
+  cancel() {
+    if (this.#timer !== null) { try { this.#clearTimer(this.#timer); } catch { /* gone */ } }
+    this.#timer = null; this.#frames = null; this.#next = 0;
+  }
+
+  #schedule(ms) {
+    try {
+      const timer = this.#setTimer(() => this.#tick(), ms);
+      timer?.unref?.();
+      this.#timer = timer;
+    } catch { this.cancel(); }
+  }
+
+  #tick() {
+    this.#timer = null;
+    if (!this.#frames) return;
+    try {
+      if (this.#now() - this.#startedAt > this.#deadlineMs) { this.cancel(); return; }
+      if (this.#room()) {
+        if (this.#send(this.#frames[this.#next]) === false) { this.cancel(); return; }
+        if (++this.#next >= this.#frames.length) { this.cancel(); return; }
+      }
+    } catch { this.cancel(); return; }
+    this.#schedule(this.#intervalMs);
+  }
+}