deadbyte-mcp 0.15.14 → 0.15.16

package/src/commander-compat-runtime.mjs

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { COMMANDER_COMPAT_TOOLS, DEADBYTE_NATIVE_TOOLS } from './commander-compat-contracts.mjs';
+
+export const COMMANDER_COMPAT_RUNTIME_SCHEMA = 'deadbyte.commander-compat-runtime.v2';
+const sha256 = value => createHash('sha256').update(JSON.stringify(value), 'utf8').digest('hex');
+const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+
+const CONTRACTS = Object.freeze({
+  contained_transform:{native:'contained.transform',required:['operation','input'],mutation:false},
+  create_directory:{native:'machine_fs.mkdir',required:['root_id','path'],mutation:true},
+  edit_block:{native:'native_diff',required:['root_id','path','expected_sha256'],mutation:true},
+  evidence_verify:{native:'evidence.verify',required:['receipt'],mutation:false},
+  file_preview:{native:'commander.file_preview',required:['root_id','path'],mutation:false},
+  file_read:{native:'machine_fs.read',required:['root_id','path'],mutation:false},
+  force_terminate:{native:'process.terminate',required:['session_id'],mutation:true},
+  get_config:{native:'commander.config.get',required:[],mutation:false},
+  get_file_info:{native:'machine_fs.stat',required:['root_id','path'],mutation:false},
+  get_more_search_results:{native:'machine_search.page',required:['search_id'],mutation:false},
+  get_prompts:{native:'commander.prompts',required:[],mutation:false},
+  get_recent_tool_calls:{native:'operation_history.recent',required:[],mutation:false},
+  get_usage_stats:{native:'operation_history.stats',required:[],mutation:false},
+  give_feedback_to_desktop_commander:{native:'commander.feedback',required:['message'],mutation:true},
+  host_exec:{native:'host.exec',required:['command_id','root_id','script_path','script_sha256'],mutation:true},
+  host_file_read:{native:'host.file_read',required:['path'],mutation:false},
+  host_file_write:{native:'host.file_write',required:['path','content','expected_sha256'],mutation:true},
+  interact_with_process:{native:'process.input',required:['session_id','input'],mutation:true},
+  kill_process:{native:'process.terminate',required:['session_id'],mutation:true},
+  list_directory:{native:'machine_fs.list',required:['root_id','path'],mutation:false},
+  list_processes:{native:'process.sessions',required:[],mutation:false},
+  list_searches:{native:'machine_search.list',required:[],mutation:false},
+  list_sessions:{native:'process.sessions',required:[],mutation:false},
+  markdown_editor:{native:'native_diff',required:['root_id','path','expected_sha256'],mutation:true},
+  move_file:{native:'machine_fs.move',required:['root_id','source_path','destination_path','expected_source_identity'],mutation:true},
+  proof_execute:{native:'proof.execute',required:['operation'],mutation:false},
+  read_file:{native:'machine_fs.read',required:['root_id','path'],mutation:false},
+  read_multiple_files:{native:'machine_fs.read_many',required:['root_id','paths'],mutation:false},
+  read_process_output:{native:'process.output',required:['session_id'],mutation:false},
+  remote_device:{native:'remote_device',required:['device_id'],mutation:false},
+  remote_mcp:{native:'remote_mcp',required:['request_id'],mutation:false},
+  resources:{native:'commander.resources',required:[],mutation:false},
+  set_config_value:{native:'commander.config.set',required:['key','value','expected_sha256'],mutation:true},
+  skill_catalog:{native:'skill.catalog',required:[],mutation:false},
+  start_process:{native:'process.start',required:['profile_id','root_id'],mutation:true},
+  start_search:{native:'machine_search.start',required:['root_id','path','pattern'],mutation:false},
+  stop_search:{native:'machine_search.cancel',required:['search_id'],mutation:false},
+  workspace_open:{native:'workspace.open',required:['root_id'],mutation:false},
+  write_file:{native:'machine_fs.write',required:['root_id','path','content','expected_sha256'],mutation:true},
+  write_pdf:{native:'document.write_pdf',required:['root_id','path','content','expected_sha256'],mutation:true}
+});
+
+export function commanderCompatibilityContract(name) {
+  if (!COMMANDER_COMPAT_TOOLS.includes(name)) throw new Error(`unsupported Commander capability: ${name}`);
+  return CONTRACTS[name] ?? {native:DEADBYTE_NATIVE_TOOLS[name] ?? null,required:[],mutation:false};
+}
+
+export function validateCommanderRequest(name,args={}) {
+  const c=commanderCompatibilityContract(name);
+  if (!args || typeof args!=='object' || Array.isArray(args)) throw new Error('request arguments must be an object');
+  const missing=c.required.filter(k=>!own(args,k)||args[k]===undefined||args[k]===null||args[k]==='');
+  if(missing.length) throw new Error(`missing required fields: ${missing.join(', ')}`);
+  if(c.mutation && !['create_directory','start_process','force_terminate','kill_process','interact_with_process','host_exec'].includes(name) && !('expected_sha256' in args) && !('expected_source_identity' in args)) throw new Error('mutation requires an explicit precondition');
+  if((name==='host_exec') && typeof args.script_sha256!=='string') throw new Error('host_exec requires hash-pinned script');
+  return Object.freeze({commander_tool:name,native_tool:c.native,mutation:c.mutation,args});
+}
+
+export function createCommanderCompatibilityRuntime({invoke,snapshot}) {
+  if(typeof invoke!=='function') throw new Error('invoke function required');
+  return Object.freeze({
+    schema:COMMANDER_COMPAT_RUNTIME_SCHEMA,
+    async call(name,args={}) {
+      const request=validateCommanderRequest(name,args);
+      const before=typeof snapshot==='function'?await snapshot(request):null;
+      const result=await invoke(request.native_tool,request.args);
+      const after=typeof snapshot==='function'?await snapshot(request):null;
+      const resultHash=sha256(result);
+      const receipt={schema:COMMANDER_COMPAT_RUNTIME_SCHEMA,commander_tool:name,native_tool:request.native_tool,request_sha256:sha256(request),before_sha256:sha256(before),result_sha256:resultHash,after_sha256:sha256(after),verified:true};
+      return {status:'ok',result,receipt};
+    }
+  });
+}
+
+export function assertNoCommanderDependency(sourceText) {
+  if(typeof sourceText!=='string') throw new Error('source text must be a string');
+  if(/@wonderwhy-er\/desktop-commander|desktop-commander\/dist/.test(sourceText)) throw new Error('native DEADBYTE source must not depend on Commander package');
+  return true;
+}
+
+export function commanderCompatibilityCoverage() {
+  const covered=COMMANDER_COMPAT_TOOLS.filter(name=>CONTRACTS[name]?.native);
+  return Object.freeze({schema:COMMANDER_COMPAT_RUNTIME_SCHEMA,covered:covered.length,total:COMMANDER_COMPAT_TOOLS.length,missing:COMMANDER_COMPAT_TOOLS.filter(name=>!CONTRACTS[name]?.native),coverage_sha256:sha256(covered.map(name=>[name,CONTRACTS[name].native]))});
+}

package/src/commander-core-bridge.mjs

@@ -0,0 +1,30 @@
+import * as z from 'zod/v4';
+const anyArgs=z.record(z.string(),z.unknown());
+const sessions=new Map(); let sessionCounter=0;
+function denied(tool,reason='required native runtime is disabled'){return {status:'denied',tool,error:reason};}
+function register(server,name,schema,handler){server.registerTool(name,{description:'Native Commander-compatible adapter; execution remains inside DEADBYTE policy and evidence boundaries.',inputSchema:schema},handler);}
+function fsOr(runtime,name,fn){return runtime?fn(runtime):denied(name);}
+function processOr(runtime,name,fn){return runtime?fn(runtime):denied(name);}
+function mapResult(item,type){return type==='files'?{file:item.path,type:'file'}:{file:item.path,line:item.line,match:item.preview,type:'content'};}
+function queryArgs(a){return {rootId:a.root_id??'core',path:a.path,pattern:a.pattern,target:a.searchType==='content'?'content':'path',mode:a.literalSearch===true?'literal':'regex',caseSensitive:a.ignoreCase===false,maxResults:Number.isInteger(a.maxResults)?Math.min(Math.max(a.maxResults,1),1000):200,maxFileBytes:262144,maxScanBytes:64*1024*1024,pageSize:500,cursor:null};}
+export function registerCommanderCoreBridge(server,{machineFsRuntime=null,processRuntime=null,searchRuntime=null,remoteDevicePlane=null}={}){
+  register(server,'read_file',z.strictObject({root_id:z.string().min(1).max(64),path:z.string().min(1).max(2048),offset:z.number().int().min(0).default(0),max_bytes:z.number().int().min(1).max(4194304).default(65536),hash_file:z.boolean().default(false),timeout_ms:z.number().int().min(100).max(180000).default(30000)}),a=>fsOr(machineFsRuntime,'read_file',r=>r.read({rootId:a.root_id,relativePath:a.path,offset:a.offset,maxBytes:a.max_bytes,hashFile:a.hash_file,timeoutMs:a.timeout_ms})));
+  register(server,'read_multiple_files',z.strictObject({root_id:z.string().min(1).max(64),paths:z.array(z.string().min(1).max(2048)).min(1).max(64),max_bytes:z.number().int().min(1).max(4194304).default(65536),timeout_ms:z.number().int().min(100).max(180000).default(30000)}),a=>fsOr(machineFsRuntime,'read_multiple_files',r=>r.readMany({rootId:a.root_id,relativePaths:a.paths,maxBytes:a.max_bytes,timeoutMs:a.timeout_ms})));
+  register(server,'write_file',z.strictObject({root_id:z.string().min(1).max(64),path:z.string().min(1).max(2048),content:z.string().max(12582912),encoding:z.enum(['utf8','base64']).default('utf8'),expected_sha256:z.string().regex(/^(?:absent|[0-9a-f]{64})$/)}),a=>fsOr(machineFsRuntime,'write_file',r=>r.write({rootId:a.root_id,relativePath:a.path,content:a.content,encoding:a.encoding,expectedSha256:a.expected_sha256})));
+  register(server,'create_directory',z.strictObject({root_id:z.string().min(1).max(64),path:z.string().min(1).max(2048)}),a=>fsOr(machineFsRuntime,'create_directory',r=>r.mkdir({rootId:a.root_id,relativePath:a.path})));
+  register(server,'list_directory',z.strictObject({root_id:z.string().min(1).max(64),path:z.string().min(1).max(2048).default('.'),cursor:z.string().max(4096).nullable().default(null),limit:z.number().int().min(1).max(1000).default(100),hash_files:z.boolean().default(false)}),a=>fsOr(machineFsRuntime,'list_directory',r=>r.list({rootId:a.root_id,relativePath:a.path,cursor:a.cursor,limit:a.limit,hashFiles:a.hash_files})));
+  register(server,'move_file',z.strictObject({root_id:z.string().min(1).max(64),source_path:z.string().min(1).max(2048),destination_path:z.string().min(1).max(2048),expected_source_identity:z.string().regex(/^[0-9a-f]{64}$/)}),a=>fsOr(machineFsRuntime,'move_file',r=>r.move({rootId:a.root_id,sourcePath:a.source_path,destinationPath:a.destination_path,expectedSourceIdentity:a.expected_source_identity})));
+  register(server,'get_file_info',z.strictObject({root_id:z.string().min(1).max(64),path:z.string().min(1).max(2048),hash:z.boolean().default(false)}),a=>fsOr(machineFsRuntime,'get_file_info',r=>r.stat({rootId:a.root_id,relativePath:a.path,hash:a.hash})));
+  register(server,'edit_block',z.strictObject({root_id:z.string().min(1).max(64),path:z.string().min(1).max(2048),expected_sha256:z.string().regex(/^[0-9a-f]{64}$/),old_string:z.string().min(1).max(262144),new_string:z.string().max(524288),expected_replacements:z.number().int().min(1).max(64).default(1)}),a=>fsOr(machineFsRuntime,'edit_block',r=>r.editExact({rootId:a.root_id,relativePath:a.path,expectedSha256:a.expected_sha256,oldString:a.old_string,newString:a.new_string,expectedReplacements:a.expected_replacements})));
+  register(server,'start_process',anyArgs,a=>processOr(processRuntime,'start_process',r=>r.start(a)));
+  register(server,'read_process_output',anyArgs,a=>processOr(processRuntime,'read_process_output',r=>r.read(a)));
+  register(server,'interact_with_process',anyArgs,a=>processOr(processRuntime,'interact_with_process',r=>r.action(a)));
+  register(server,'force_terminate',anyArgs,a=>processOr(processRuntime,'force_terminate',r=>r.terminate(a)));
+  register(server,'list_sessions',z.strictObject({}),()=>processOr(processRuntime,'list_sessions',r=>r.list()));
+  register(server,'list_processes',z.strictObject({}),()=>processOr(processRuntime,'list_processes',r=>r.list()));
+  register(server,'kill_process',anyArgs,a=>processOr(processRuntime,'kill_process',r=>r.cancel(a)));
+  register(server,'start_search',z.strictObject({path:z.string().min(1),pattern:z.string().min(1).max(256),searchType:z.enum(['files','content']).default('files'),filePattern:z.string().optional(),ignoreCase:z.boolean().default(true),maxResults:z.number().int().min(1).max(1000).optional(),includeHidden:z.boolean().default(false),contextLines:z.number().int().min(0).max(50).default(5),timeout_ms:z.number().int().min(100).max(120000).optional(),earlyTermination:z.boolean().optional(),literalSearch:z.boolean().default(false),origin:z.enum(['ui','llm']).optional()}),async a=>{if(!searchRuntime)return denied('start_search','dedicated search runtime is disabled');const id='search-'+(++sessionCounter)+'-'+Date.now().toString(36);const s={id,searchType:a.searchType,pattern:a.pattern,startTime:Date.now(),isComplete:false,isError:false,results:[],totalMatches:0,wasIncomplete:false};sessions.set(id,s);s.promise=(async()=>{try{const r=await searchRuntime(queryArgs(a));s.results=r.matches.map(x=>mapResult(x,a.searchType)).slice(0,a.maxResults??200);s.totalMatches=r.matches.length;s.wasIncomplete=r.truncated===true;s.isComplete=true;}catch(e){s.isError=true;s.error=String(e?.message??e).slice(0,512);s.isComplete=true;}})();return {sessionId:id,isComplete:false,isError:false,results:[],totalResults:0,runtime:0};});
+  register(server,'get_more_search_results',z.strictObject({sessionId:z.string().min(1).max(128),offset:z.number().int().default(0),length:z.number().int().min(1).max(1000).default(100)}),async({sessionId,offset,length})=>{const s=sessions.get(sessionId);if(!s)return {status:'error',error:'search session not found'};if(!s.isComplete)return {results:[],returnedCount:0,totalResults:s.results.length,totalMatches:s.totalMatches,isComplete:false,isError:false,hasMoreResults:true,runtime:Date.now()-s.startTime};const start=offset<0?Math.max(0,s.results.length+offset):offset;const end=offset<0?s.results.length:Math.min(s.results.length,start+length);const results=s.results.slice(start,end);return {results,returnedCount:results.length,totalResults:s.results.length,totalMatches:s.totalMatches,isComplete:true,isError:s.isError,error:s.error,hasMoreResults:end<s.results.length,runtime:Date.now()-s.startTime,wasIncomplete:s.wasIncomplete};});
+  register(server,'stop_search',z.strictObject({sessionId:z.string().min(1).max(128)}),async({sessionId})=>{const s=sessions.get(sessionId);if(!s)return false;s.cancelled=true;return true;});
+  register(server,'list_searches',z.strictObject({}),async()=>[...sessions.values()].map(s=>({id:s.id,searchType:s.searchType,pattern:s.pattern,isComplete:s.isComplete,isError:s.isError,runtime:Date.now()-s.startTime,totalResults:s.results.length})));
+}

package/src/commander-extended-runtime.mjs

@@ -0,0 +1,74 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile, rename } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalJson } from './canonical-json.mjs';
+
+export const COMMANDER_EXTENDED_SCHEMA='deadbyte.commander-extended.v1';
+const MAX_VALUE=16384,MAX_FEEDBACK=4096,MAX_PREVIEW=65536;
+const sha256=v=>createHash('sha256').update(Buffer.isBuffer(v)?v:Buffer.from(typeof v==='string'?v:canonicalJson(v),'utf8')).digest('hex');
+const keyOk=k=>typeof k==='string'&&/^[A-Za-z0-9._-]{1,128}$/.test(k);
+
+function pdfEscape(s){return String(s).replaceAll('\\\\','\\\\\\\\').replaceAll('(','\\\\(').replaceAll(')','\\\\)');}
+function makePdf(text){
+  const nl=String.fromCharCode(10),lines=String(text).replaceAll(String.fromCharCode(13),'').split(nl).slice(0,200);
+  const stream=['BT','/F1 11 Tf','50 790 14 TL',...lines.map(line=>'('+pdfEscape(line).slice(0,180)+') Tj 0 -14 Td'),'ET'].join(nl);
+  const objs=['<< /Type /Catalog /Pages 2 0 R >>','<< /Type /Pages /Kids [3 0 R] /Count 1 >>','<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 4 0 R >> /Contents 5 0 R >>','<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>','<< /Length '+Buffer.byteLength(stream)+' >>'+nl+'stream'+nl+stream+nl+'endstream'];
+  let out='%PDF-1.4'+nl,offsets=[0];
+  for(let i=0;i<objs.length;i++){offsets.push(Buffer.byteLength(out));out+=(i+1)+' 0 obj'+nl+objs[i]+nl+'endobj'+nl;}
+  const xref=Buffer.byteLength(out);
+  out+='xref'+nl+'0 6'+nl+'0000000000 65535 f '+nl+offsets.slice(1).map(o=>String(o).padStart(10,'0')+' 00000 n ').join(nl)+nl+'trailer'+nl+'<< /Size 6 /Root 1 0 R >>'+nl+'startxref'+nl+xref+nl+'%%EOF'+nl;
+  return Buffer.from(out,'utf8');
+}
+
+export function createCommanderExtendedRuntime({stateRoot,history=null,prompts=[],resources=[]}={}){
+  if(typeof stateRoot!=='string'||!stateRoot)throw new Error('extended runtime stateRoot required');
+  const configPath=path.join(stateRoot,'commander-config.json'),feedbackDir=path.join(stateRoot,'feedback');
+  let configCache=null;
+  async function loadConfig(){
+    if(configCache)return configCache;
+    try{configCache=JSON.parse(await readFile(configPath,'utf8'));}
+    catch(e){if(e?.code!=='ENOENT')throw e;configCache={};}
+    return configCache;
+  }
+  async function getConfig({key=null}={}){
+    const cfg=await loadConfig();
+    if(key!==null&&!keyOk(key))throw new Error('config key invalid');
+    return {schema:COMMANDER_EXTENDED_SCHEMA,status:'ok',config:key===null?structuredClone(cfg):{[key]:cfg[key]},config_sha256:sha256(cfg)};
+  }
+  async function setConfigValue({key,value,expected_sha256}){
+    if(!keyOk(key))throw new Error('config key invalid');
+    if(!['string','number','boolean'].includes(typeof value)&&value!==null)throw new Error('config value must be scalar');
+    if(Buffer.byteLength(typeof value==='string'?value:canonicalJson(value))>MAX_VALUE)throw new Error('config value exceeds byte limit');
+    const cfg=await loadConfig(),beforeSha=sha256(cfg);
+    if(expected_sha256!==beforeSha)throw new Error('config precondition mismatch');
+    const next={...cfg,[key]:value};
+    await mkdir(stateRoot,{recursive:true});
+    const tmp=configPath+'.tmp-'+process.pid+'-'+randomUUID();
+    await writeFile(tmp,canonicalJson(next),{encoding:'utf8',flag:'wx',mode:0o600});
+    await rename(tmp,configPath); configCache=next;
+    return {schema:COMMANDER_EXTENDED_SCHEMA,status:'committed',key,previous_sha256:beforeSha,config_sha256:sha256(next)};
+  }
+  async function feedback({message,category='general'}){
+    if(typeof message!=='string'||!message.trim()||Buffer.byteLength(message)>MAX_FEEDBACK)throw new Error('feedback message invalid');
+    if(!/^[A-Za-z0-9._-]{1,64}$/.test(category))throw new Error('feedback category invalid');
+    await mkdir(feedbackDir,{recursive:true});
+    const id=randomUUID(),record={schema:COMMANDER_EXTENDED_SCHEMA,id,category,message:message.trim(),created_at_utc:new Date().toISOString()};
+    await writeFile(path.join(feedbackDir,id+'.json'),canonicalJson(record),{encoding:'utf8',flag:'wx',mode:0o600});
+    return {status:'committed',feedback_id:id,feedback_sha256:sha256(record)};
+  }
+  function getPrompts(){return {schema:COMMANDER_EXTENDED_SCHEMA,status:'ok',prompts:prompts.map(x=>({...x})).slice(0,128)};}
+  function getResources(){return {schema:COMMANDER_EXTENDED_SCHEMA,status:'ok',resources:resources.map(x=>({...x})).slice(0,128)};}
+  async function filePreview({rootId,path:relativePath,offset=0,maxBytes=MAX_PREVIEW,mimeType='text/plain'}){
+    if(!Number.isInteger(offset)||offset<0||offset>64*1024*1024)throw new Error('preview offset invalid');
+    if(!Number.isInteger(maxBytes)||maxBytes<1||maxBytes>MAX_PREVIEW)throw new Error('preview maxBytes invalid');
+    if(typeof rootId!=='string'||typeof relativePath!=='string'||path.isAbsolute(relativePath))throw new Error('preview target invalid');
+    const data=await readFile(path.resolve(rootId,relativePath)),slice=data.subarray(offset,offset+maxBytes);
+    return {schema:COMMANDER_EXTENDED_SCHEMA,status:'ok',root_id:rootId,path:relativePath,mime_type:mimeType,offset,bytes:slice.length,total_bytes:data.length,truncated:offset+slice.length<data.length,sha256:sha256(slice),text:mimeType.startsWith('text/')?slice.toString('utf8'):null};
+  }
+  function writePdf({text,metadata={}}){
+    if(typeof text!=='string'||Buffer.byteLength(text)>MAX_PREVIEW)throw new Error('PDF text exceeds byte limit');
+    const bytes=makePdf(text);
+    return {schema:COMMANDER_EXTENDED_SCHEMA,status:'ok',mime_type:'application/pdf',bytes_base64:bytes.toString('base64'),bytes_sha256:sha256(bytes),bytes:bytes.length,metadata};
+  }
+  return Object.freeze({getConfig,setConfigValue,feedback,getPrompts,getResources,filePreview,writePdf,history});
+}

package/src/commander-observability.mjs

@@ -0,0 +1,33 @@
+import { canonicalJson } from './canonical-json.mjs';
+
+const MAX_LIMIT=1000;
+const SCHEMA='deadbyte.commander-observability.v1';
+
+function boundLimit(limit){if(!Number.isInteger(limit)||limit<1||limit>MAX_LIMIT)throw new Error('observability limit out of range');return limit;}
+
+export function createCommanderObservability({history}={}){
+  if(!history||typeof history.read!=='function'||typeof history.verify!=='function'||typeof history.operationId!=='string'||history.operationId.length<1) throw new Error('observability requires operation history');
+  function recentToolCalls({afterSequence=0,limit=100}={}){
+    boundLimit(limit);
+    const page=history.read({afterSequence,limit});
+    const events=page.events.filter(e=>e.event_type==='tool.call'||e.event_type==='tool.result'||e.event_type==='tool.error');
+    return {schema:SCHEMA,operation_id:page.operation_id,events,next_sequence:page.next_sequence,head_event_hash:page.head_event_hash,earliest_sequence:page.earliest_sequence,overflow:page.overflow};
+  }
+  function usageStats(){
+    const page=history.read({afterSequence:0,limit:MAX_LIMIT});
+    const counts={};
+    let toolCalls=0,toolResults=0,toolErrors=0;
+    for(const event of page.events){
+      if(event.event_type==='tool.call') toolCalls++;
+      else if(event.event_type==='tool.result') toolResults++;
+      else if(event.event_type==='tool.error') toolErrors++;
+      else continue;
+      const name=event.payload?.tool;
+      if(typeof name==='string'&&name.length) counts[name]=(counts[name]??0)+1;
+    }
+    return {schema:SCHEMA,operation_id:page.operation_id,events_visible:page.events.length,tool_calls:toolCalls,tool_results:toolResults,tool_errors:toolErrors,tool_counts:Object.fromEntries(Object.entries(counts).sort(([a],[b])=>a.localeCompare(b))),head_event_hash:page.head_event_hash,earliest_sequence:page.earliest_sequence,overflow:page.overflow,integrity:history.verify()};
+  }
+  return Object.freeze({usageStats,recentToolCalls});
+}
+
+export const COMMANDER_OBSERVABILITY_SCHEMA=SCHEMA;

package/src/commander-remote-bridge-r47.mjs

@@ -0,0 +1,41 @@
+import * as z from 'zod/v4';
+
+const HEX64=/^[0-9a-f]{64}$/;
+const CAP=/^[A-Za-z0-9._-]{1,128}$/;
+function register(server,name,schema,handler){
+  server.registerTool(name,{description:'Native remote Commander-compatible bridge backed directly by DEADBYTE remote-device-r44. No Commander runtime is invoked.',inputSchema:schema},handler);
+}
+function requirePlane(plane,name){
+  if(!plane) return {status:'unavailable',tool:name,error:'remote-device-r44 plane is not configured'};
+  return null;
+}
+export function registerCommanderRemoteBridge(server,{remoteDevicePlane=null}={}){
+  register(server,'remote_device',z.strictObject({
+    op:z.enum(['pair','status','report_online','probe','dispatch','revoke','rotate_credential','list']),
+    device_id:z.string().regex(HEX64).optional(),epoch:z.number().int().min(1).optional(),
+    public_key_spki_base64:z.string().min(1).max(4096).optional(),display_name:z.string().min(1).max(128).optional(),
+    connection_id:z.string().min(1).max(256).optional(),capability_id:z.string().regex(CAP).optional(),
+    payload:z.record(z.string(),z.unknown()).optional(),request_id:z.string().regex(HEX64).optional(),
+    encrypted_bundle_base64:z.string().min(1).max(1024*1024).optional(),expected_previous_sha256:z.string().regex(HEX64).nullable().optional()
+  }),async a=>{
+    const unavailable=requirePlane(remoteDevicePlane,'remote_device');if(unavailable)return unavailable;
+    switch(a.op){
+      case 'pair': return remoteDevicePlane.pair({publicKeySpkiBase64:a.public_key_spki_base64,displayName:a.display_name});
+      case 'status': return remoteDevicePlane.status({deviceId:a.device_id});
+      case 'report_online': return remoteDevicePlane.reportOnline({deviceId:a.device_id,epoch:a.epoch,connectionId:a.connection_id});
+      case 'probe': return remoteDevicePlane.probe({deviceId:a.device_id,epoch:a.epoch});
+      case 'dispatch': return remoteDevicePlane.dispatch({deviceId:a.device_id,epoch:a.epoch,capabilityId:a.capability_id,payload:a.payload??{},requestId:a.request_id});
+      case 'revoke': return remoteDevicePlane.revoke({deviceId:a.device_id,epoch:a.epoch});
+      case 'rotate_credential': return remoteDevicePlane.rotateCredential({deviceId:a.device_id,epoch:a.epoch,encryptedBundleBase64:a.encrypted_bundle_base64,expectedPreviousSha256:a.expected_previous_sha256??null});
+      case 'list': return remoteDevicePlane.list();
+      default: throw new Error(`unsupported remote_device operation: ${String(a.op)}`);
+    }
+  });
+  register(server,'remote_mcp',z.strictObject({
+    device_id:z.string().regex(HEX64),epoch:z.number().int().min(1),capability_id:z.string().regex(CAP),
+    payload:z.record(z.string(),z.unknown()).default({}),request_id:z.string().regex(HEX64)
+  }),async a=>{
+    const unavailable=requirePlane(remoteDevicePlane,'remote_mcp');if(unavailable)return unavailable;
+    return remoteDevicePlane.dispatch({deviceId:a.device_id,epoch:a.epoch,capabilityId:a.capability_id,payload:a.payload,requestId:a.request_id});
+  });
+}

package/src/commander-remote-relay-r47.mjs

@@ -0,0 +1,44 @@
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+
+function insist(ok,message){if(!ok)throw new Error(message);}
+function structured(result,label){
+  if(result?.isError) throw new Error(`${label} returned MCP error`);
+  const value=result?.structuredContent;
+  insist(value&&typeof value==='object',`${label} missing structured output`);
+  return value;
+}
+
+export async function createCommanderRemoteRelayR47({endpoint,protocolVersion='2026-07-28',timeoutMs=15000}={}){
+  const url=new URL(String(endpoint??''));
+  insist(url.protocol==='https:','remote relay endpoint must use HTTPS');
+  insist(Number.isInteger(timeoutMs)&&timeoutMs>=100&&timeoutMs<=120000,'remote relay timeout invalid');
+  const client=new Client({name:'deadbyte-r47-remote-relay',version:'0.15.15'},{versionNegotiation:{mode:{pin:protocolVersion}}});
+  const transport=new StreamableHTTPClientTransport(url);
+  let connected=false;
+  let connecting=null;
+  async function ensureConnected(){
+    if(connected)return;
+    if(!connecting){connecting=client.connect(transport).then(()=>{connected=true;}).finally(()=>{connecting=null;});}
+    await connecting;
+  }
+  async function call(name,arguments_,label){await ensureConnected();return structured(await client.callTool({name,arguments:arguments_}),label);}
+  async function probe({device_id,epoch,connection_id,nonce}){
+    const value=await call('remote_device',{op:'probe',device_id,epoch,connection_id,nonce},'remote readiness probe');
+    const result=value.result??value;
+    return {device_id,epoch,nonce,ready:result.ready===true||result.reachable===true};
+  }
+  async function request({device_id,epoch,capability_id,payload,request_id,request_sha256}){
+    insist(typeof request_sha256==='string'&&/^[0-9a-f]{64}$/.test(request_sha256),'remote request hash invalid');
+    const value=await call('remote_mcp',{device_id,epoch,capability_id,payload,request_id,request_sha256},'remote dispatch');
+    const result=value.result??value;
+    if(result?.request_id!==undefined) insist(result.request_id===request_id,'remote request identity mismatch');
+    if(result?.status==='completed'||result?.state==='completed'){
+      insist(typeof result.result_sha256==='string'&&/^[0-9a-f]{64}$/.test(result.result_sha256),'remote terminal result hash invalid');
+      return {ack:'accepted',request_id,terminal:{status:'completed',result_sha256:result.result_sha256}};
+    }
+    if(result?.status==='failed'||result?.state==='failed') return {ack:'accepted',request_id,terminal:{status:'failed',error_code:result.error_code??'remote_failed'}};
+    throw new Error('remote dispatch returned non-terminal state');
+  }
+  async function close(){connected=false;await client.close().catch(()=>{});}
+  return Object.freeze({probe,request,close,endpoint:url.toString()});
+}

package/src/machine-fs.mjs

@@ -33,7 +33,36 @@ async function sha256File(file) {
 }
 
 const machineFsReadWorkerPath = fileURLToPath(new URL('./machine-fs-read-worker.mjs', import.meta.url));
+async function boundedReadInProcess({ file, offset, length, hashFile, timeoutMs }) {
+  const handle = await open(file, 'r');
+  let timer;
+  let settled = false;
+  const abort = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      settled = true;
+      void handle.close().catch(() => {});
+      reject(new Error(`machine fs read timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    timer.unref?.();
+  });
+  try {
+    const operation = (async () => {
+      const buffer = Buffer.alloc(length);
+      const result = length ? await handle.read(buffer, 0, length, offset) : { bytesRead: 0 };
+      let fileSha256 = null;
+      if (hashFile) fileSha256 = await sha256File(file);
+      return { schema: 'deadbyte.machine-fs-read-worker.v1', bytes_read: result.bytesRead,
+        data_base64: buffer.subarray(0, result.bytesRead).toString('base64'), file_sha256: fileSha256 };
+    })();
+    operation.catch(() => {});
+    return await Promise.race([operation, abort]);
+  } finally {
+    if (!settled) { clearTimeout(timer); await handle.close().catch(() => {}); }
+  }
+}
+
 async function boundedReadWorker({ file, offset, length, hashFile, timeoutMs, workerPath = machineFsReadWorkerPath }) {
+  if (workerPath === machineFsReadWorkerPath) return boundedReadInProcess({ file, offset, length, hashFile, timeoutMs });
   return await new Promise((resolve, reject) => {
     const child = spawn(process.execPath, [workerPath, file, String(offset), String(length), hashFile ? '1' : '0'], {
       windowsHide: true, shell: false, stdio: ['ignore','pipe','pipe']
@@ -103,20 +132,27 @@ function assertNotDenied(root, relativePath) {
 }
 async function assertNoReparse(rootPath, target, allowMissingLeaf = false) {
   const relative = path.relative(rootPath, target);
-  if (relative === '') return;
+  if (relative === '') {
+    const info = await lstat(rootPath);
+    if (info.isSymbolicLink()) throw new Error('machine fs root reparse point denied');
+    return info;
+  }
   if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('machine fs path escapes allowed root');
   const parts = relative.split(path.sep).filter(Boolean);
   let cursor = rootPath;
+  let targetInfo = null;
   for (let i = 0; i < parts.length; i += 1) {
     cursor = path.join(cursor, parts[i]);
     try {
       const info = await lstat(cursor);
       if (info.isSymbolicLink()) throw new Error(`machine fs reparse point denied at '${parts.slice(0, i + 1).join('/')}'`);
+      targetInfo = info;
     } catch (error) {
-      if (allowMissingLeaf && i === parts.length - 1 && error?.code === 'ENOENT') return;
+      if (allowMissingLeaf && i === parts.length - 1 && error?.code === 'ENOENT') return null;
       throw error;
     }
   }
+  return targetInfo;
 }
 
 async function resolveExisting(policy, grant, rootId, relativePath, permission, allowDot = false) {
@@ -126,10 +162,10 @@ async function resolveExisting(policy, grant, rootId, relativePath, permission,
   if (normalized !== '.') assertNotDenied(root, normalized);
   const lexical = normalized === '.' ? root.real_path : path.resolve(root.real_path, normalized);
   if (!isInside(root.real_path, lexical) && lexical !== root.real_path) throw new Error('machine fs path escapes allowed root');
-  await assertNoReparse(root.real_path, lexical, false);
-  const resolved = await realpath(lexical);
+  const targetInfo = await assertNoReparse(root.real_path, lexical, false);
+  const resolved = lexical === root.real_path ? lexical : await realpath(lexical);
   if (!isInside(root.real_path, resolved) && resolved !== root.real_path) throw new Error('machine fs path resolves outside allowed root');
-  return { root, lexical, resolved, relative: normalized };
+  return { root, lexical, resolved, relative: normalized, targetInfo };
 }
 async function resolveTarget(policy, grant, rootId, relativePath, permission) {
   const normalized = normalizeRelative(relativePath, false);
@@ -208,15 +244,41 @@ async function objectIdentity(target, budget = { remaining: MAX_DIRECTORY_IDENTI
   return { ...core, identity_sha256: sha256Object(core) };
 }
 
-function decodeCursor(cursor) {
+const LIST_CURSOR_DOMAIN = Buffer.from('DEADBYTE-MACHINE-FS-LIST-CURSOR-V3\\0', 'utf8');
+async function encodeListCursor({ path: relativePath, snapshot_sha256, after_name, signingKeyPath }) {
+  const signing = await loadPrivateSigningKey(signingKeyPath);
+  const body = { schema: 'deadbyte.machine-fs-list-cursor.v3', path: relativePath, snapshot_sha256, after_name };
+  const payload = Buffer.from(canonicalJson(body), 'utf8');
+  const signature_base64 = cryptoSign(null, Buffer.concat([LIST_CURSOR_DOMAIN, payload]), signing.privateKey).toString('base64');
+  return Buffer.from(canonicalJson({
+    ...body,
+    attestation: { algorithm: 'ed25519', key_id: signing.keyId, signature_base64 }
+  }), 'utf8').toString('base64url');
+}
+async function decodeListCursor(cursor, verifyKeyPath) {
   if (cursor === null || cursor === undefined) return null;
-  if (typeof cursor !== 'string' || cursor.length < 1 || cursor.length > 2048) throw new Error('machine fs cursor invalid');
+  if (typeof cursor !== 'string' || cursor.length < 1 || cursor.length > 4096) throw new Error('machine fs cursor invalid');
   let decoded;
-  try { decoded = Buffer.from(cursor, 'base64url').toString('utf8'); }
+  try { decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')); }
   catch { throw new Error('machine fs cursor invalid'); }
-  if (!decoded || Buffer.from(decoded, 'utf8').toString('base64url') !== cursor) throw new Error('machine fs cursor invalid');
+  if (!decoded || decoded.schema !== 'deadbyte.machine-fs-list-cursor.v3' ||
+      typeof decoded.path !== 'string' || !SHA256_RE.test(decoded.snapshot_sha256 ?? '') ||
+      typeof decoded.after_name !== 'string' || decoded.after_name.length < 1 ||
+      decoded.attestation?.algorithm !== 'ed25519' || typeof decoded.attestation?.key_id !== 'string' ||
+      typeof decoded.attestation?.signature_base64 !== 'string') throw new Error('machine fs cursor invalid');
+  if (Buffer.from(canonicalJson(decoded), 'utf8').toString('base64url') !== cursor) throw new Error('machine fs cursor invalid');
+  const { attestation, ...body } = decoded;
+  const verifyKey = await loadPublicVerifyKey(verifyKeyPath);
+  if (attestation.key_id !== verifyKey.keyId) throw new Error('machine fs cursor key mismatch');
+  const signature = Buffer.from(attestation.signature_base64, 'base64');
+  const valid = signature.length === 64 &&
+    cryptoVerify(null, Buffer.concat([LIST_CURSOR_DOMAIN, Buffer.from(canonicalJson(body), 'utf8')]), verifyKey.publicKey, signature);
+  if (!valid) throw new Error('machine fs cursor signature mismatch');
   return decoded;
 }
+function directoryListingSnapshot(children) {
+  return sha256Object(children.map(child => ({ name: child.name, kind: child.isSymbolicLink() ? 'reparse' : child.isDirectory() ? 'directory' : child.isFile() ? 'file' : 'other' })));
+}
 
 function encodeCursor(name) { return Buffer.from(name, 'utf8').toString('base64url'); }
 
@@ -286,7 +348,14 @@ export function createMachineFsRuntime({ policy, signingKeyPath, verifyKeyPath,
     const info = await lstat(found.resolved);
     const kind = kindOf(info);
     if (kind === 'reparse') throw new Error('machine fs reparse target denied');
-    const identity = await objectIdentity(found.resolved);
+    let identity;
+    if (kind === 'file') {
+      const contentSha256 = await sha256File(found.resolved);
+      const core = { kind: 'file', bytes: info.size, content_sha256: contentSha256 };
+      identity = { ...core, identity_sha256: sha256Object(core) };
+    } else {
+      identity = await objectIdentity(found.resolved);
+    }
     return {
       status: 'ok', root_id: rootId, path: found.relative, kind,
       bytes: kind === 'file' ? info.size : 0,
@@ -300,27 +369,29 @@ export function createMachineFsRuntime({ policy, signingKeyPath, verifyKeyPath,
     if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIST_LIMIT) throw new Error(`machine fs list limit must be in [1, ${MAX_LIST_LIMIT}]`);
     const grant = await assertCodingArmed(policy, rootId);
     const found = await resolveExisting(policy, grant, rootId, relativePath, 'read', true);
-    const info = await lstat(found.resolved);
-    if (!info.isDirectory()) throw new Error('machine fs list path must be a directory');
-    const afterName = decodeCursor(cursor);
+    const info = found.targetInfo;
+    if (!info?.isDirectory()) throw new Error('machine fs list path must be a directory');
+    const decodedCursor = await decodeListCursor(cursor, verifyKeyPath);
+    if (decodedCursor && decodedCursor.path !== found.relative) throw new Error('machine fs cursor path mismatch');
     const children = await readdir(found.resolved, { withFileTypes: true });
     children.sort((a, b) => a.name.localeCompare(b.name));
+    const snapshot_sha256 = directoryListingSnapshot(children);
+    if (decodedCursor && decodedCursor.snapshot_sha256 !== snapshot_sha256) throw new Error('machine fs cursor snapshot changed');
+    const afterName = decodedCursor?.after_name ?? null;
     const filtered = children.filter(child => afterName === null || child.name.localeCompare(afterName) > 0);
     const selected = filtered.slice(0, limit);
-    const entries = [];
-    for (const child of selected) {
+    const entries = await Promise.all(selected.map(async child => {
       const rel = found.relative === '.' ? child.name : `${found.relative}/${child.name}`;
-      if (child.isSymbolicLink()) {
-        entries.push({ path: rel, kind: 'reparse', bytes: 0, mtime_utc: null, sha256: null });
-        continue;
-      }
+      if (child.isSymbolicLink()) return { path: rel, kind: 'reparse', bytes: 0, mtime_utc: null, sha256: null };
       const childPath = path.join(found.resolved, child.name);
       const childInfo = await lstat(childPath);
       const kind = kindOf(childInfo);
       const digest = hashFiles && kind === 'file' ? await sha256File(childPath) : null;
-      entries.push({ path: rel, kind, bytes: kind === 'file' ? childInfo.size : 0, mtime_utc: childInfo.mtime.toISOString(), sha256: digest });
-    }
-    const nextCursor = filtered.length > selected.length && selected.length ? encodeCursor(selected.at(-1).name) : null;
+      return { path: rel, kind, bytes: kind === 'file' ? childInfo.size : 0, mtime_utc: childInfo.mtime.toISOString(), sha256: digest };
+    }));
+    const nextCursor = filtered.length > selected.length && selected.length
+      ? await encodeListCursor({ path: found.relative, snapshot_sha256, after_name: selected.at(-1).name, signingKeyPath })
+      : null;
     return { status: 'ok', root_id: rootId, path: found.relative, entries, next_cursor: nextCursor };
   }
   async function readRange({ rootId, relativePath, offset = 0, maxBytes = 65536, hashFile = false, timeoutMs = 30000 }) {
@@ -348,6 +419,20 @@ export function createMachineFsRuntime({ policy, signingKeyPath, verifyKeyPath,
     };
   }
 
+  async function readMany({ rootId, paths, maxBytes = 65536, timeoutMs = 30000 }) {
+    if (!Array.isArray(paths) || paths.length < 1 || paths.length > 64) throw new Error('machine fs read_many paths must contain 1-64 entries');
+    if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > policy.max_read_bytes) throw new Error(`machine fs read_many max_bytes must be in [1, ${policy.max_read_bytes}]`);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 180000) throw new Error('machine fs read_many timeout_ms must be in [100, 180000]');
+    const unique = new Set();
+    for (const relativePath of paths) {
+      if (typeof relativePath !== 'string' || relativePath.length < 1 || relativePath.length > 512) throw new Error('machine fs read_many path invalid');
+      if (unique.has(relativePath)) throw new Error(`machine fs read_many duplicate path '${relativePath}'`);
+      unique.add(relativePath);
+    }
+    const results = await Promise.all(paths.map(relativePath => readRange({ rootId, relativePath, offset: 0, maxBytes, timeoutMs })));
+    return { status: 'ok', root_id: rootId, count: results.length, results };
+  }
+
   async function writePath({ rootId, relativePath, content, encoding = 'utf8', expectedSha256, receiptId = null }) {
     const grant = await assertCodingArmed(policy, rootId);
     const target = await resolveTarget(policy, grant, rootId, relativePath, 'write');
@@ -551,6 +636,7 @@ export function createMachineFsRuntime({ policy, signingKeyPath, verifyKeyPath,
     stat: statPath,
     list: listPage,
     read: readRange,
+    readMany,
     write: writePath,
     editExact,
     move: movePath,