deadbyte-mcp 0.11.3 → 0.12.0

package/src/deadbyte-cli.mjs

@@ -11,6 +11,7 @@ import { verifyAuditChain } from './audit-verify.mjs';
 import { openRemoteResultJournal, parseRemoteResultCursor } from './remote-result-journal.mjs';
 import { DEADBYTE_VERSION } from './version.mjs';
 import { createLiveTimelineTracker, formatCompactAuditEvent, formatRemoteLifecycle, formatRemoteToolCall, formatRuntimeDiagnosticLine } from './remote-live-log.mjs';
+import { prepareRemoteConsole, remoteDisplayText } from './remote-console.mjs';
 
 const REMOTE_COMMANDS=new Set([
   'menu','start','resume','park','stop','restart','status','url','test','fulltest','toggle','clean','machinetest',
@@ -95,30 +96,38 @@ async function listLogFiles(root){
   }
   return files;
 }
-function formatLogLine(file,line,{activityTracker=null}={}){
+function formatLogLine(file,line,{activityTracker=null,sequence=null,verbose=false,displayMode='unicode'}={}){
   if(!line) return null;
   if(/^segment-\d{8}\.jsonl$/.test(path.basename(file))){
     try{
       const event=JSON.parse(line);
-      return activityTracker?activityTracker.observe(event):formatCompactAuditEvent(event);
+      return activityTracker?activityTracker.observe(event,{sequence}):formatCompactAuditEvent(event);
     }catch{return null;}
   }
-  return formatRuntimeDiagnosticLine(file,line);
+  return formatRuntimeDiagnosticLine(file,line,{verbose,displayMode});
 }
 function remoteResultJournalPath(root,sessionId){return path.join(root,'runtime','remote-results',`${sessionId}.json`);}
 function auditTimelineRecord(file,line){
   if(!/^segment-\d{8}\.jsonl$/.test(path.basename(file))||!line) return null;
   let event;try{event=JSON.parse(line);}catch{return null;}
   if(typeof event?.request_id!=='string'||!event.request_id||typeof event.tool!=='string'||!event.tool) return null;
-  const observed=Number.isFinite(Date.parse(event.created_at_utc))?new Date(Date.parse(event.created_at_utc)).toISOString():new Date().toISOString();
+  const stamp=[event.ts,event.created_at_utc,event.observed_at_utc].find(value=>typeof value==='string'&&Number.isFinite(Date.parse(value)));
+  const observed=stamp?new Date(Date.parse(stamp)).toISOString():new Date().toISOString();
   const payload_sha256=createHash('sha256').update(Buffer.from(line,'utf8')).digest('hex');
   if(event.event_type==='tool.request') return {event_type:'tool.call',request_id:event.request_id,tool:event.tool,
     observed_at_utc:observed,arguments:event.args??{},payload_sha256};
-  if(event.event_type==='tool.result') return {event_type:'tool.result',request_id:event.request_id,tool:event.tool,
-    status:event.outcome?.is_error===true?'error':'ok',observed_at_utc:observed,payload_sha256};
+  if(event.event_type==='tool.result'){
+    const unknown=event.outcome?.side_effect_state==='unknown';
+    const recoveryReason=unknown&&typeof event.outcome?.recovery?.reason==='string'?event.outcome.recovery.reason:null;
+    return {event_type:'tool.result',request_id:event.request_id,tool:event.tool,
+      status:event.outcome?.is_error===true?'error':'ok',observed_at_utc:observed,payload_sha256,
+      ...(Number.isFinite(Number(event.outcome?.duration_ms))?{duration_ms:Number(event.outcome.duration_ms)}:{}),
+      ...(unknown?{side_effect_state:'unknown'}:{}),
+      ...(typeof event.outcome?.reason==='string'&&event.outcome.reason?{reason:event.outcome.reason}:(recoveryReason?{reason:recoveryReason}:{}))};
+  }
   return null;
 }
-async function replayRemoteResults(root,cursor){
+async function replayRemoteResults(root,cursor,{displayMode='unicode'}={}){
   const parsed=parseRemoteResultCursor(cursor);
   const file=remoteResultJournalPath(root,parsed.session_id);
   await requireRegular(file,'remote result journal');
@@ -129,12 +138,15 @@ async function replayRemoteResults(root,cursor){
     for(const event of page.events){
       if(event.event_type==='tool.call'){
         const line=formatRemoteToolCall({event_type:'tool.request',tool:event.tool,request_id:event.request_id,
-          observed_at_utc:event.observed_at_utc,args:event.arguments});
-        process.stdout.write(`${line} | REPLAY cursor r1:${event.session_id}:${event.seq}\n`);
+          observed_at_utc:event.observed_at_utc,args:event.arguments},{displayMode});
+        process.stdout.write(remoteDisplayText(`${line} | REPLAY #${event.seq}\n`,displayMode));
         continue;
       }
-      const marker=event.status==='error'?'[ERR]':'[OK]';
-      process.stdout.write(`[REPLAY] ${marker} ${event.tool} [cursor r1:${event.session_id}:${event.seq}]\n`);
+      const unknown=event.side_effect_state==='unknown';
+      const marker=unknown?'OUTCOME_UNKNOWN':event.status==='error'?(displayMode==='ascii'?'ERR':'✗'):(displayMode==='ascii'?'OK':'✓');
+      const duration=Number.isFinite(Number(event.duration_ms))?` ${event.duration_ms<1000?Math.round(event.duration_ms)+'ms':(event.duration_ms/1000).toFixed(2)+'s'}`:'';
+      const reason=(event.status==='error'||unknown)&&typeof event.reason==='string'&&event.reason?` — ${event.reason}`:'';
+      process.stdout.write(remoteDisplayText(`[REPLAY] #${event.seq} ${event.tool}${duration} ${marker}${reason}\n`,displayMode));
     }
     next=page.next_cursor;
     if(!page.has_more) return next;
@@ -158,8 +170,10 @@ async function snapshotRemoteLogOffsets(root){
   }
   return offsets;
 }
-async function tailRemoteLogs(root,signal,{journal=null,offsets=null,activityTracker=null}={}){
-  process.stdout.write('[LOG] Unified live timeline. Ctrl+C disconnects and revokes authority.\n');
+async function tailRemoteLogs(root,signal,{journal=null,offsets=null,activityTracker=null,verbose=false,displayMode='unicode'}={}){
+  process.stdout.write(verbose
+    ? '[LOG] Verbose live timeline. Full sanitized request detail enabled; Ctrl+C disconnects and revokes authority.\n'
+    : '[LOG] Human live timeline. Transport IN/OUT hidden; full replay/audit detail remains on disk. Ctrl+C disconnects and revokes authority.\n');
   const activeOffsets=offsets??await snapshotRemoteLogOffsets(root);
   while(!signal.aborted){
     for(const file of await listLogFiles(root)){
@@ -173,22 +187,28 @@ async function tailRemoteLogs(root,signal,{journal=null,offsets=null,activityTra
           ? await journal.recordCall(timeline)
           : await journal.recordTerminal(timeline);
         if(recorded?.duplicate) continue;
-        const formatted=formatLogLine(file,line,{activityTracker});
+        const formatted=formatLogLine(file,line,{activityTracker,sequence:recorded?.event?.seq??null,verbose,displayMode});
         if(!formatted) continue;
-        if(recorded) process.stdout.write(`${formatted} [cursor ${recorded.cursor}]\n`);
-        else process.stdout.write(`${formatted}\n`);
+        const output=Array.isArray(formatted)?formatted:[formatted];
+        for(const item of output) if(item) process.stdout.write(`${item}\n`);
       }
     }
     try{await sleep(250,null,{signal});}catch(error){if(error?.name!=='AbortError') throw error;}
   }
 }
-async function cleanupRemoteSession(ctx){
+function remoteTag(kind,displayMode){
+  const unicode={warn:'⚠️ [WARN]',recovery:'♻️ [RECOVERY]',auth:'🔐 [AUTH]'};
+  const ascii={warn:'[WARN]',recovery:'[RECOVERY]',auth:'[AUTH]'};
+  return (displayMode==='ascii'?ascii:unicode)[kind];
+}
+function writeRemote(stream,text,displayMode){stream.write(remoteDisplayText(text,displayMode));}
+async function cleanupRemoteSession(ctx,{displayMode='unicode'}={}){
   for(const command of SESSION_CLEANUP){
     try{
       const result=invokeController(ctx,command,{allowFailure:true,capture:true,echoCaptured:false});
-      if(result.status!==0) process.stderr.write(`⚠️ [WARN] cleanup ${command} exit=${result.status}\n`);
+      if(result.status!==0) writeRemote(process.stderr,`${remoteTag('warn',displayMode)} cleanup ${command} exit=${result.status}\n`,displayMode);
     }
-    catch(error){process.stderr.write(`⚠️ [WARN] cleanup ${command}: ${String(error?.message||error)}\n`);}
+    catch(error){writeRemote(process.stderr,`${remoteTag('warn',displayMode)} cleanup ${command}: ${String(error?.message||error)}\n`,displayMode);}
   }
 }
 const GUARDIAN_SCRIPT=fileURLToPath(new URL('./remote-session-guardian.mjs',import.meta.url));
@@ -215,7 +235,7 @@ async function readRemoteSessionMarker(root){
   }
   throw new Error('remote session marker schema invalid');
 }
-async function recoverRemoteSession(ctx){
+async function recoverRemoteSession(ctx,{displayMode='unicode'}={}){
   let prior=await readRemoteSessionMarker(ctx.root);
   if(!prior) return;
   const ownerPid=remoteOwnerPid(prior);
@@ -230,8 +250,8 @@ async function recoverRemoteSession(ctx){
     }
     throw new Error(`remote session guardian cleanup still active pid=${prior.guardian_pid}`);
   }
-  process.stdout.write(`♻️ [RECOVERY] Stale remote session pid=${ownerPid}; revoking authority before restart.\n`);
-  await cleanupRemoteSession(ctx);
+  writeRemote(process.stdout,`${remoteTag('recovery',displayMode)} Stale remote session pid=${ownerPid}; revoking authority before restart.\n`,displayMode);
+  await cleanupRemoteSession(ctx,{displayMode});
   await rm(remoteSessionMarker(ctx.root),{force:true});
 }
 async function claimRemoteSession(ctx){
@@ -259,20 +279,23 @@ async function claimRemoteSession(ctx){
     throw error;
   }
 }
-async function releaseRemoteSession(ctx,marker){
-  let current=null;try{current=await readRemoteSessionMarker(ctx.root);}catch(error){process.stderr.write(`⚠️ [WARN] remote session marker cleanup: ${String(error?.message||error)}\n`);return;}
+async function releaseRemoteSession(ctx,marker,{displayMode='unicode'}={}){
+  let current=null;try{current=await readRemoteSessionMarker(ctx.root);}catch(error){writeRemote(process.stderr,`${remoteTag('warn',displayMode)} remote session marker cleanup: ${String(error?.message||error)}\n`,displayMode);return;}
   const same=current?.schema==='deadbyte.remote-session.v2'&&current.owner_pid===marker.owner_pid&&current.session_nonce===marker.session_nonce;
   if(same) await rm(remoteSessionMarker(ctx.root),{force:true});
 }
-async function runRemoteSession({resumeCursor=null}={}){
+async function runRemoteSession({resumeCursor=null,verbose=false}={}){
+  const display=prepareRemoteConsole();
+  const displayMode=display.mode;
   const ctx=await remoteContext();
-  if(resumeCursor!==null) await replayRemoteResults(ctx.root,resumeCursor);
-  await recoverRemoteSession(ctx);
+  if(displayMode==='ascii') writeRemote(process.stdout,`[DISPLAY] ASCII fallback: ${display.reason}\n`,displayMode);
+  if(resumeCursor!==null) await replayRemoteResults(ctx.root,resumeCursor,{displayMode});
+  await recoverRemoteSession(ctx,{displayMode});
   const marker=await claimRemoteSession(ctx);
   const resultJournal=await openRemoteResultJournal({
     filePath:remoteResultJournalPath(ctx.root,marker.result_session_id),sessionId:marker.result_session_id,maxEntries:2048
   });
-  const activityTracker=createLiveTimelineTracker();
+  const activityTracker=createLiveTimelineTracker({verbose,displayMode});
   const aborter=new AbortController();
   const abort=()=>aborter.abort();
   const watchStdin=!process.stdin.isTTY;
@@ -282,10 +305,10 @@ async function runRemoteSession({resumeCursor=null}={}){
   let logTask=null;
   try{
     process.stdout.write('DEADBYTE MCP\n');
-    process.stdout.write(`${formatRemoteLifecycle('device_start')}\n`);
-    process.stdout.write(`${formatRemoteLifecycle(resumeCursor!==null?'session_restored':'session_new')}\n`);
+    process.stdout.write(`${formatRemoteLifecycle('device_start',{displayMode})}\n`);
+    process.stdout.write(`${formatRemoteLifecycle(resumeCursor!==null?'session_restored':'session_new',{displayMode})}\n`);
     const logOffsets=await snapshotRemoteLogOffsets(ctx.root);
-    logTask=tailRemoteLogs(ctx.root,aborter.signal,{journal:resultJournal,offsets:logOffsets,activityTracker});
+    logTask=tailRemoteLogs(ctx.root,aborter.signal,{journal:resultJournal,offsets:logOffsets,activityTracker,verbose,displayMode});
     process.stdout.write('[BOOT] Starting local + remote runtime...\n');
     const preflight=invokeController(ctx,'status',{capture:true,allowFailure:true,echoCaptured:false,timeoutMs:REMOTE_STATUS_TIMEOUT_MS});
     let startText=preflight.stdout||'';
@@ -298,42 +321,47 @@ async function runRemoteSession({resumeCursor=null}={}){
       if(started.status!==0||!controllerRuntimeReady(started.stdout)) throw new Error('remote controller start returned without a verified ONLINE runtime');
       startText=started.stdout||'';
     }
-    process.stdout.write(`${formatRemoteLifecycle('bridge_connected')}\n`);
-    process.stdout.write(`${formatRemoteLifecycle('cloud_connected')}\n`);
+    process.stdout.write(`${formatRemoteLifecycle('bridge_connected',{displayMode})}\n`);
+    process.stdout.write(`${formatRemoteLifecycle('cloud_connected',{displayMode})}\n`);
     for(const command of SESSION_ARM){
-      process.stdout.write(`🔐 [AUTH] Arming ${command.slice(3)}...\n`);
+      writeRemote(process.stdout,`${remoteTag('auth',displayMode)} Arming ${command.slice(3)}...\n`,displayMode);
       invokeController(ctx,command,{capture:true,echoCaptured:false,timeoutMs:REMOTE_STATUS_TIMEOUT_MS});
     }
     const url=startText.match(/^URL\s*:\s*(\S+)/m)?.[1]||'';
     process.stdout.write('[OK] ONLINE\n');
-    process.stdout.write(`${formatRemoteLifecycle('ready')}\n`);
-    if(url) process.stdout.write(`URL: ${url}\n`);
-    process.stdout.write('🔐 [AUTH] Verifying process, coding, autonomous; host must stay DISARMED...\n');
+    process.stdout.write(`${formatRemoteLifecycle('ready',{displayMode})}\n`);
+    if(url) writeRemote(process.stdout,`URL: ${url}\n`,displayMode);
+    writeRemote(process.stdout,`${remoteTag('auth',displayMode)} Verifying process, coding, autonomous; host must stay DISARMED...\n`,displayMode);
     for(const [command,pattern] of SESSION_STATUS){
       const result=invokeController(ctx,command,{capture:true,echoCaptured:false});
       if(!pattern.test(result.stdout)) throw new Error(`remote session authority verification failed: ${command} state mismatch`);
     }
     ready=true;
-    process.stdout.write('🔐 [AUTH] ARMED: process, coding, autonomous | host DISARMED\n');
+    writeRemote(process.stdout,`${remoteTag('auth',displayMode)} ARMED: process, coding, autonomous | host DISARMED\n`,displayMode);
     await logTask;
   }finally{
     const wasAborted=aborter.signal.aborted;
     aborter.abort();
     if(logTask) await logTask.catch(()=>{});
     for(const line of activityTracker.reconcileInterrupted('session_end')) process.stdout.write(`${line}\n`);
+    process.stdout.write(`${activityTracker.summary()}\n`);
     process.removeListener('SIGINT',abort);process.removeListener('SIGTERM',abort);
     if(watchStdin){process.stdin.removeListener('end',abort);process.stdin.removeListener('close',abort);process.stdin.pause();}
-    process.stdout.write(`${formatRemoteLifecycle('cleanup')}\n`);
+    process.stdout.write(`${formatRemoteLifecycle('cleanup',{displayMode})}\n`);
     if(ready||!wasAborted) process.stdout.write('[INFO] Disconnecting; revoking authority...\n');
-    await cleanupRemoteSession(ctx);
-    await releaseRemoteSession(ctx,marker);
+    await cleanupRemoteSession(ctx,{displayMode});
+    await releaseRemoteSession(ctx,marker,{displayMode});
   }
 }
 async function runRemote(args){
   if(args.length===0){await runRemoteSession();return;}
-  if(args.length===2&&args[0]==='--resume'){await runRemoteSession({resumeCursor:args[1]});return;}
-  if(args.length>1) throw new Error('remote accepts one controller command or --resume <cursor>');
-  const command=args[0];if(!REMOTE_COMMANDS.has(command)) throw new Error(`unsupported remote command '${command}'`);
+  const verbose=args.includes('--verbose')||args.includes('-v');
+  const filtered=args.filter(arg=>arg!=='--verbose'&&arg!=='-v');
+  if(filtered.length===0){await runRemoteSession({verbose});return;}
+  if(filtered.length===2&&filtered[0]==='--resume'){await runRemoteSession({resumeCursor:filtered[1],verbose});return;}
+  if(verbose) throw new Error('remote --verbose/-v is valid only for foreground session or --resume <cursor>');
+  if(filtered.length>1) throw new Error('remote accepts one controller command or --resume <cursor>');
+  const command=filtered[0];if(!REMOTE_COMMANDS.has(command)) throw new Error(`unsupported remote command '${command}'`);
   const ctx=await remoteContext();
   const result=invokeController(ctx,command,{allowFailure:true});
   process.exitCode=result.status;

package/src/desktop-contract.mjs

@@ -0,0 +1,263 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.mjs';
+
+export const DESKTOP_FRAME_SCHEMA='deadbyte.desktop-frame.v1';
+export const DESKTOP_TARGET_SCHEMA='deadbyte.desktop-target.v1';
+export const DESKTOP_ACTION_SCHEMA='deadbyte.desktop-action.v1';
+export const DESKTOP_GUARD_SCHEMA='deadbyte.desktop-action-guard.v1';
+export const DESKTOP_POST_OBSERVATION_SCHEMA='deadbyte.desktop-post-observation.v1';
+export const DESKTOP_ACTION_CHAIN_SCHEMA='deadbyte.desktop-action-chain.v1';
+
+const HEX64=/^[0-9a-f]{64}$/;
+const INTENT=/^[0-9a-f]{64}$/;
+const HWND=/^0x[0-9a-f]{1,16}$/;
+const ACTION_KINDS=new Set([
+  'pointer_move','click_primary','click_secondary','double_click_primary',
+  'scroll','key_chord','text_input'
+]);
+const TARGET_SOURCES=new Set(['visual','uia','accessibility','geometry']);
+const KEY=/^(?:[A-Z0-9]|F(?:[1-9]|1[0-2])|ENTER|ESC|TAB|SPACE|BACKSPACE|DELETE|INSERT|HOME|END|PAGEUP|PAGEDOWN|LEFT|RIGHT|UP|DOWN|CTRL|ALT|SHIFT|WIN)$/;
+
+const sha256Bytes=bytes=>createHash('sha256').update(bytes).digest('hex');
+const sha256Object=value=>sha256Bytes(Buffer.from(canonicalJson(value),'utf8'));
+const isObject=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
+
+function insist(condition,message){ if(!condition) throw new Error(message); }
+function hash(value,label){ insist(typeof value==='string'&&HEX64.test(value),`${label} must be sha256`); return value; }
+function parseUtc(value,label){
+  insist(typeof value==='string'&&value.length>=20&&value.length<=40,`${label} invalid`);
+  const ms=Date.parse(value); insist(Number.isFinite(ms),`${label} invalid`);
+  return ms;
+}
+function int(value,label,{min=Number.MIN_SAFE_INTEGER,max=Number.MAX_SAFE_INTEGER}={}){
+  insist(Number.isSafeInteger(value)&&value>=min&&value<=max,`${label} invalid`);
+  return value;
+}
+function number(value,label,{min=-Infinity,max=Infinity}={}){
+  insist(Number.isFinite(value)&&value>=min&&value<=max,`${label} invalid`);
+  return value;
+}
+function bounds(value,label='desktop bounds'){
+  insist(isObject(value),`${label} invalid`);
+  const left=int(value.left,`${label}.left`,{min:-131072,max:131072});
+  const top=int(value.top,`${label}.top`,{min:-131072,max:131072});
+  const width=int(value.width,`${label}.width`,{min:1,max:131072});
+  const height=int(value.height,`${label}.height`,{min:1,max:131072});
+  insist(left+width<=262144&&top+height<=262144,`${label} extent invalid`);
+  return Object.freeze({left,top,width,height});
+}
+function rect(value,label='target rect'){
+  insist(isObject(value),`${label} invalid`);
+  return Object.freeze({
+    left:int(value.left,`${label}.left`,{min:-131072,max:131072}),
+    top:int(value.top,`${label}.top`,{min:-131072,max:131072}),
+    width:int(value.width,`${label}.width`,{min:1,max:131072}),
+    height:int(value.height,`${label}.height`,{min:1,max:131072})
+  });
+}
+function point(value,label='point'){
+  insist(isObject(value),`${label} invalid`);
+  return Object.freeze({
+    x:int(value.x,`${label}.x`,{min:-131072,max:131072}),
+    y:int(value.y,`${label}.y`,{min:-131072,max:131072})
+  });
+}
+function insidePoint(b,p){ return p.x>=b.left&&p.y>=b.top&&p.x<b.left+b.width&&p.y<b.top+b.height; }
+function insideRect(b,r){
+  return r.left>=b.left&&r.top>=b.top&&
+    r.left+r.width<=b.left+b.width&&r.top+r.height<=b.top+b.height;
+}
+function windowIdentity(value,{optional=false}={}){
+  if(value===null||value===undefined){
+    insist(optional,'window identity required'); return null;
+  }
+  insist(isObject(value),'window identity invalid');
+  const hwnd=String(value.hwnd??'').toLowerCase();
+  insist(HWND.test(hwnd),'window hwnd invalid');
+  const pid=int(value.pid,'window pid',{min:1,max:0x7fffffff});
+  const result={hwnd,pid};
+  if(value.process_image_sha256!==undefined&&value.process_image_sha256!==null) result.process_image_sha256=hash(value.process_image_sha256,'window process_image_sha256');
+  if(value.title_sha256!==undefined&&value.title_sha256!==null) result.title_sha256=hash(value.title_sha256,'window title_sha256');
+  return Object.freeze(result);
+}
+function sameWindow(expected,actual){
+  if(expected===null) return true;
+  if(actual===null) return false;
+  if(expected.hwnd!==actual.hwnd||expected.pid!==actual.pid) return false;
+  if(expected.process_image_sha256&&expected.process_image_sha256!==actual.process_image_sha256) return false;
+  if(expected.title_sha256&&expected.title_sha256!==actual.title_sha256) return false;
+  return true;
+}
+function normalizeKeyChord(value){
+  insist(Array.isArray(value)&&value.length>=1&&value.length<=5,'key_chord invalid');
+  const keys=value.map(item=>String(item).toUpperCase());
+  insist(keys.every(item=>KEY.test(item)),'key_chord contains unsupported key');
+  insist(new Set(keys).size===keys.length,'key_chord contains duplicate key');
+  return Object.freeze(keys);
+}
+function validateFrameObject(frame){
+  insist(isObject(frame),'desktop frame invalid');
+  insist(frame.schema===DESKTOP_FRAME_SCHEMA,'desktop frame schema mismatch');
+  hash(frame.desktop_epoch,'desktop_epoch');
+  hash(frame.topology_sha256,'topology_sha256');
+  hash(frame.image_sha256,'image_sha256');
+  hash(frame.frame_id,'frame_id');
+  parseUtc(frame.observed_at_utc,'observed_at_utc');
+  const b=bounds(frame.bounds);
+  const active=frame.active_window===null?null:windowIdentity(frame.active_window);
+  const body={
+    schema:DESKTOP_FRAME_SCHEMA,
+    desktop_epoch:frame.desktop_epoch,
+    topology_sha256:frame.topology_sha256,
+    observed_at_utc:frame.observed_at_utc,
+    bounds:b,
+    active_window:active,
+    image_sha256:frame.image_sha256
+  };
+  insist(sha256Object(body)===frame.frame_id,'desktop frame hash mismatch');
+  return Object.freeze({...body,frame_id:frame.frame_id});
+}
+
+export function createDesktopFrame({desktopEpoch,topologySha256,observedAtUtc,bounds:inputBounds,activeWindow=null,imageSha256}={}){
+  hash(desktopEpoch,'desktopEpoch'); hash(topologySha256,'topologySha256'); hash(imageSha256,'imageSha256');
+  parseUtc(observedAtUtc,'observedAtUtc');
+  const body={
+    schema:DESKTOP_FRAME_SCHEMA,
+    desktop_epoch:desktopEpoch,
+    topology_sha256:topologySha256,
+    observed_at_utc:observedAtUtc,
+    bounds:bounds(inputBounds),
+    active_window:activeWindow===null?null:windowIdentity(activeWindow),
+    image_sha256:imageSha256
+  };
+  return Object.freeze({...body,frame_id:sha256Object(body)});
+}
+
+export function verifyDesktopFrame(frame){
+  try { const normalized=validateFrameObject(frame); return {ok:true,frame:normalized}; }
+  catch(error){ return {ok:false,reason:String(error?.message??error)}; }
+}
+
+export function createDesktopTarget({frame,rect:inputRect,source,confidence,semanticLabelSha256=null,windowBinding=undefined}={}){
+  const f=validateFrameObject(frame);
+  insist(TARGET_SOURCES.has(source),'target source invalid');
+  number(confidence,'target confidence',{min:0,max:1});
+  const r=rect(inputRect);
+  insist(insideRect(f.bounds,r),'target rect outside desktop bounds');
+  const binding=windowBinding===undefined?f.active_window:windowIdentity(windowBinding,{optional:true});
+  if(binding!==null) insist(sameWindow(binding,f.active_window),'target window binding does not match frame');
+  if(semanticLabelSha256!==null) hash(semanticLabelSha256,'semantic_label_sha256');
+  const body={
+    schema:DESKTOP_TARGET_SCHEMA,frame_id:f.frame_id,desktop_epoch:f.desktop_epoch,
+    topology_sha256:f.topology_sha256,rect:r,source,confidence,
+    window_binding:binding,semantic_label_sha256:semanticLabelSha256
+  };
+  return Object.freeze({...body,target_id:sha256Object(body)});
+}
+
+export function createDesktopAction({
+  intentId,kind,frameId,desktopEpoch,topologySha256,expectedWindow=null,
+  point:inputPoint=null,scrollDelta=null,keyChord=null,text=null,targetId=null
+}={}){
+  insist(typeof intentId==='string'&&INTENT.test(intentId),'intentId invalid');
+  insist(ACTION_KINDS.has(kind),'desktop action kind invalid');
+  hash(frameId,'frameId'); hash(desktopEpoch,'desktopEpoch'); hash(topologySha256,'topologySha256');
+  if(targetId!==null) hash(targetId,'targetId');
+  const expected=windowIdentity(expectedWindow,{optional:true});
+  let p=null,delta=null,keys=null,textValue=null,textSha256=null;
+  if(['pointer_move','click_primary','click_secondary','double_click_primary','scroll'].includes(kind)){
+    p=point(inputPoint,'action point');
+  } else insist(inputPoint===null,'non-pointer action cannot carry point');
+  if(kind==='scroll'){
+    delta=int(scrollDelta,'scrollDelta',{min:-12000,max:12000});
+    insist(delta!==0,'scrollDelta cannot be zero');
+  } else insist(scrollDelta===null,'non-scroll action cannot carry scrollDelta');
+  if(kind==='key_chord') keys=normalizeKeyChord(keyChord);
+  else insist(keyChord===null,'non-key action cannot carry keyChord');
+  if(kind==='text_input'){
+    insist(typeof text==='string'&&text.length>=1&&text.length<=4096&&!text.includes('\u0000'),'text input invalid');
+    textValue=text; textSha256=sha256Bytes(Buffer.from(text,'utf8'));
+  } else insist(text===null,'non-text action cannot carry text');
+  const body={
+    schema:DESKTOP_ACTION_SCHEMA,intent_id:intentId,kind,frame_id:frameId,
+    desktop_epoch:desktopEpoch,topology_sha256:topologySha256,
+    expected_window:expected,target_id:targetId,point:p,scroll_delta:delta,key_chord:keys,
+    text:textValue,text_sha256:textSha256
+  };
+  return Object.freeze({...body,action_sha256:sha256Object(body)});
+}
+
+export function guardDesktopAction({frame,action,nowUtc,maxFrameAgeMs=2000,maxFutureSkewMs=250}={}){
+  const f=validateFrameObject(frame);
+  insist(isObject(action)&&action.schema===DESKTOP_ACTION_SCHEMA,'desktop action invalid');
+  hash(action.action_sha256,'action_sha256');
+  const actionBody={...action}; delete actionBody.action_sha256;
+  insist(sha256Object(actionBody)===action.action_sha256,'desktop action hash mismatch');
+  insist(action.frame_id===f.frame_id,'desktop action stale frame id');
+  insist(action.desktop_epoch===f.desktop_epoch,'desktop action desktop epoch mismatch');
+  insist(action.topology_sha256===f.topology_sha256,'desktop action topology mismatch');
+  insist(sameWindow(action.expected_window,f.active_window),'desktop action foreground window mismatch');
+  int(maxFrameAgeMs,'maxFrameAgeMs',{min:1,max:60000});
+  int(maxFutureSkewMs,'maxFutureSkewMs',{min:0,max:5000});
+  const now=parseUtc(nowUtc,'nowUtc'), observed=parseUtc(f.observed_at_utc,'frame observed_at_utc');
+  const age=now-observed;
+  insist(age>=-maxFutureSkewMs,'desktop frame is from the future');
+  insist(age<=maxFrameAgeMs,'desktop frame is stale');
+  if(action.point!==null) insist(insidePoint(f.bounds,action.point),'desktop action point outside frame bounds');
+  const guardedAt=new Date(now).toISOString();
+  const body={
+    schema:DESKTOP_GUARD_SCHEMA,frame_id:f.frame_id,action_sha256:action.action_sha256,
+    intent_id:action.intent_id,desktop_epoch:f.desktop_epoch,topology_sha256:f.topology_sha256,
+    active_window:f.active_window,frame_age_ms:Math.max(0,age),guarded_at_utc:guardedAt
+  };
+  return Object.freeze({...body,guard_sha256:sha256Object(body)});
+}
+
+export function bindDesktopPostObservation({guard,beforeFrame,action,afterFrame}={}){
+  insist(isObject(guard)&&guard.schema===DESKTOP_GUARD_SCHEMA,'desktop guard invalid');
+  hash(guard.guard_sha256,'guard_sha256');
+  const guardBody={...guard}; delete guardBody.guard_sha256;
+  insist(sha256Object(guardBody)===guard.guard_sha256,'desktop guard hash mismatch');
+  const before=validateFrameObject(beforeFrame),after=validateFrameObject(afterFrame);
+  insist(before.frame_id===guard.frame_id,'post-observation before frame mismatch');
+  insist(isObject(action)&&action.action_sha256===guard.action_sha256,'post-observation action mismatch');
+  parseUtc(guard.guarded_at_utc,'guarded_at_utc');
+  insist(parseUtc(after.observed_at_utc,'after observed_at_utc')>=parseUtc(guard.guarded_at_utc,'guarded_at_utc'),'post-observation predates guarded action');
+  const windowChanged=!sameWindow(before.active_window,after.active_window)||!sameWindow(after.active_window,before.active_window);
+  const result={
+    schema:DESKTOP_POST_OBSERVATION_SCHEMA,
+    guard_sha256:guard.guard_sha256,
+    action_sha256:action.action_sha256,
+    before_frame_id:before.frame_id,
+    after_frame_id:after.frame_id,
+    change_observed:before.image_sha256!==after.image_sha256,
+    window_changed:windowChanged,
+    foreground_transition:Object.freeze({
+      before:before.active_window,
+      after:after.active_window,
+      changed:windowChanged
+    }),
+    topology_changed:before.topology_sha256!==after.topology_sha256,
+    desktop_epoch_changed:before.desktop_epoch!==after.desktop_epoch,
+    observed_at_utc:after.observed_at_utc,
+    success:null
+  };
+  return Object.freeze({...result,post_observation_sha256:sha256Object(result)});
+}
+
+export function bindDesktopActionChain({
+  beforeFrameId,actionSha256,afterFrameId,guardSha256,postObservationSha256,
+  postReceiptSha256,effectId,effectFingerprint
+}={}){
+  hash(beforeFrameId,'beforeFrameId'); hash(actionSha256,'actionSha256'); hash(afterFrameId,'afterFrameId');
+  hash(guardSha256,'guardSha256'); hash(postObservationSha256,'postObservationSha256');
+  hash(postReceiptSha256,'postReceiptSha256'); hash(effectId,'effectId'); hash(effectFingerprint,'effectFingerprint');
+  const body={
+    schema:DESKTOP_ACTION_CHAIN_SCHEMA,before_frame_id:beforeFrameId,action_sha256:actionSha256,
+    after_frame_id:afterFrameId,guard_sha256:guardSha256,post_observation_sha256:postObservationSha256,
+    post_receipt_sha256:postReceiptSha256,effect_id:effectId,effect_fingerprint:effectFingerprint
+  };
+  return Object.freeze({...body,chain_sha256:sha256Object(body)});
+}
+
+export function desktopActionKinds(){ return Object.freeze([...ACTION_KINDS]); }