deadbyte-mcp 0.15.18 → 0.15.20

package/src/commander-observability.mjs

@@ -1,32 +1,82 @@
-import { canonicalJson } from './canonical-json.mjs';
-
 const MAX_LIMIT=1000;
-const SCHEMA='deadbyte.commander-observability.v1';
+const SCHEMA='deadbyte.commander-observability.v2';
 
-function boundLimit(limit){if(!Number.isInteger(limit)||limit<1||limit>MAX_LIMIT)throw new Error('observability limit out of range');return limit;}
+function boundLimit(limit){
+  if(!Number.isInteger(limit)||limit<1||limit>MAX_LIMIT)throw new Error('observability limit out of range');
+  return limit;
+}
+function parseSince(value){
+  if(value===undefined||value===null)return null;
+  if(typeof value!=='string')throw new Error('since must be an ISO timestamp string');
+  const ms=Date.parse(value);
+  if(!Number.isFinite(ms))throw new Error('since must be a valid ISO timestamp');
+  return ms;
+}
+function retainedPage(history){
+  if(typeof history.snapshot==='function')return history.snapshot();
+  return history.read({afterSequence:0,limit:MAX_LIMIT});
+}
+function visibleToolEvent(event){
+  return event?.event_type==='tool.call'||event?.event_type==='tool.result'||event?.event_type==='tool.error';
+}
 
 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};
+  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=null,limit=null,maxResults=null,toolName=null,since=null}={}){
+    const referenceMode=maxResults!==null||toolName!==null||since!==null;
+    if(referenceMode){
+      const requested=maxResults??50;
+      if(!Number.isFinite(requested)||requested<1||requested>MAX_LIMIT) throw new Error('observability limit out of range');
+      // Reference Array.slice(-limit) truncates fractional counts toward zero.
+      const bounded=Math.trunc(requested);
+      if(toolName!==null&&typeof toolName!=='string')throw new Error('toolName invalid');
+      const sinceMs=parseSince(since);
+      const page=retainedPage(history);
+      let events=page.events.filter(visibleToolEvent);
+      if(toolName!==null)events=events.filter(event=>event.payload?.tool===toolName);
+      if(sinceMs!==null)events=events.filter(event=>Number(event.at_ms)>=sinceMs);
+      if(events.length>bounded)events=events.slice(events.length-bounded);
+      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
+      };
+    }
+    const cursor=afterSequence??0;
+    const bounded=boundLimit(limit??100);
+    const page=history.read({afterSequence:cursor,limit:bounded});
+    const events=page.events.filter(visibleToolEvent);
+    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 page=retainedPage(history);
     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++;
+      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;
+      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 {
+      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});
 }
 

package/src/commander-office-reader-r48.mjs

@@ -0,0 +1,548 @@
+import { inflateRawSync } from 'node:zlib';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+const ZIP_LOCAL=0x04034b50;
+const ZIP_CENTRAL=0x02014b50;
+const ZIP_EOCD=0x06054b50;
+const MAX_ENTRIES=4096;
+const MAX_ENTRY_BYTES=32*1024*1024;
+const MAX_TOTAL_BYTES=64*1024*1024;
+const UTF8=new TextDecoder('utf-8',{fatal:true});
+
+let crcTable=null;
+function getCrcTable(){
+  if(crcTable) return crcTable;
+  crcTable=new Uint32Array(256);
+  for(let i=0;i<256;i++){
+    let c=i;
+    for(let k=0;k<8;k++) c=(c>>>1)^((c&1)?0xedb88320:0);
+    crcTable[i]=c>>>0;
+  }
+  return crcTable;
+}
+function crc32(bytes){
+  const table=getCrcTable(); let c=0xffffffff;
+  for(const b of bytes)c=(c>>>8)^table[(c^b)&0xff];
+  return (c^0xffffffff)>>>0;
+}
+function decodeUtf8(bytes,label){
+  try{return UTF8.decode(bytes);}catch{throw new Error(`${label} is not valid UTF-8`);}
+}
+function safeZipName(name){
+  if(!name||name.includes('\0')||name.includes('\\')||name.startsWith('/')||/^[A-Za-z]:/.test(name)) throw new Error(`unsafe ZIP entry '${name}'`);
+  const parts=name.split('/');
+  if(parts.some(p=>p==='..'||p==='')) {
+    if(name.endsWith('/')&&parts.at(-1)==='') parts.pop();
+    if(parts.some(p=>p==='..'||p==='')) throw new Error(`unsafe ZIP entry '${name}'`);
+  }
+  return parts.join('/')+(name.endsWith('/')?'/':'');
+}
+function findEocd(buf){
+  if(buf.length<22) throw new Error('invalid ZIP: EOCD missing');
+  const floor=Math.max(0,buf.length-22-65535);
+  for(let i=buf.length-22;i>=floor;i--){
+    if(buf.readUInt32LE(i)===ZIP_EOCD){
+      const comment=buf.readUInt16LE(i+20);
+      if(i+22+comment===buf.length) return i;
+    }
+  }
+  throw new Error('invalid ZIP: EOCD missing');
+}
+function unzipOffice(input){
+  const buf=Buffer.isBuffer(input)?input:Buffer.from(input);
+  const eocd=findEocd(buf);
+  const disk=buf.readUInt16LE(eocd+4),centralDisk=buf.readUInt16LE(eocd+6);
+  const diskEntries=buf.readUInt16LE(eocd+8),entries=buf.readUInt16LE(eocd+10);
+  const centralSize=buf.readUInt32LE(eocd+12),centralOffset=buf.readUInt32LE(eocd+16);
+  if(disk!==0||centralDisk!==0||diskEntries!==entries) throw new Error('multi-disk ZIP is not supported');
+  if(entries===0xffff||centralSize===0xffffffff||centralOffset===0xffffffff) throw new Error('ZIP64 office packages are not supported');
+  if(entries>MAX_ENTRIES) throw new Error(`ZIP entry count exceeds ${MAX_ENTRIES}`);
+  if(centralOffset+centralSize>eocd) throw new Error('invalid ZIP central directory bounds');
+  const files=new Map();
+  let p=centralOffset,total=0;
+  for(let index=0;index<entries;index++){
+    if(p+46>centralOffset+centralSize||buf.readUInt32LE(p)!==ZIP_CENTRAL) throw new Error('invalid ZIP central directory entry');
+    const flags=buf.readUInt16LE(p+8),method=buf.readUInt16LE(p+10),expectedCrc=buf.readUInt32LE(p+16);
+    const compressedSize=buf.readUInt32LE(p+20),uncompressedSize=buf.readUInt32LE(p+24);
+    const nameLen=buf.readUInt16LE(p+28),extraLen=buf.readUInt16LE(p+30),commentLen=buf.readUInt16LE(p+32);
+    const diskStart=buf.readUInt16LE(p+34),localOffset=buf.readUInt32LE(p+42);
+    const recordEnd=p+46+nameLen+extraLen+commentLen;
+    if(recordEnd>centralOffset+centralSize) throw new Error('invalid ZIP central entry bounds');
+    if(diskStart!==0) throw new Error('multi-disk ZIP entry is not supported');
+    if(flags&1) throw new Error('encrypted ZIP entries are not supported');
+    if(method!==0&&method!==8) throw new Error(`ZIP compression method ${method} is not supported`);
+    if(uncompressedSize>MAX_ENTRY_BYTES) throw new Error(`ZIP entry exceeds ${MAX_ENTRY_BYTES} byte limit`);
+    total+=uncompressedSize;
+    if(total>MAX_TOTAL_BYTES) throw new Error(`ZIP uncompressed content exceeds ${MAX_TOTAL_BYTES} byte limit`);
+    const name=safeZipName(decodeUtf8(buf.subarray(p+46,p+46+nameLen),'ZIP entry name'));
+    if(files.has(name)) throw new Error(`duplicate ZIP entry '${name}'`);
+    if(localOffset+30>centralOffset||buf.readUInt32LE(localOffset)!==ZIP_LOCAL) throw new Error(`invalid local ZIP header for '${name}'`);
+    const localFlags=buf.readUInt16LE(localOffset+6),localMethod=buf.readUInt16LE(localOffset+8);
+    const localNameLen=buf.readUInt16LE(localOffset+26),localExtraLen=buf.readUInt16LE(localOffset+28);
+    if((localFlags&1)!==0||localMethod!==method) throw new Error(`ZIP local header mismatch for '${name}'`);
+    const localName=decodeUtf8(buf.subarray(localOffset+30,localOffset+30+localNameLen),'ZIP local entry name');
+    if(localName!==name) throw new Error(`ZIP local name mismatch for '${name}'`);
+    const dataStart=localOffset+30+localNameLen+localExtraLen,dataEnd=dataStart+compressedSize;
+    if(dataStart<0||dataEnd>centralOffset||dataEnd>buf.length) throw new Error(`ZIP compressed data bounds invalid for '${name}'`);
+    if(!name.endsWith('/')){
+      const compressed=buf.subarray(dataStart,dataEnd);
+      let data;
+      try{
+        data=method===0?Buffer.from(compressed):inflateRawSync(compressed,{maxOutputLength:MAX_ENTRY_BYTES});
+      }catch(error){throw new Error(`ZIP inflate failed for '${name}': ${error instanceof Error?error.message:String(error)}`);}
+      if(data.length!==uncompressedSize) throw new Error(`ZIP size mismatch for '${name}'`);
+      if(crc32(data)!==expectedCrc) throw new Error(`ZIP CRC32 mismatch for '${name}'`);
+      files.set(name,data);
+    }
+    p=recordEnd;
+  }
+  if(p!==centralOffset+centralSize) throw new Error('ZIP central directory size mismatch');
+  return files;
+}
+
+function xmlDecode(value){
+  return String(value)
+    .replace(/&#x([0-9a-fA-F]+);/g,(_,x)=>String.fromCodePoint(parseInt(x,16)))
+    .replace(/&#([0-9]+);/g,(_,x)=>String.fromCodePoint(parseInt(x,10)))
+    .replace(/&lt;/g,'<').replace(/&gt;/g,'>').replace(/&quot;/g,'"').replace(/&apos;/g,"'").replace(/&amp;/g,'&');
+}
+function xmlAttrs(fragment){
+  const out={};
+  const re=/([A-Za-z_][A-Za-z0-9_.:-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+  for(const m of fragment.matchAll(re)) out[m[1]]=xmlDecode(m[2]??m[3]??'');
+  return out;
+}
+function xmlTextFragments(fragment,tagPattern='(?:w:)?t'){
+  const re=new RegExp(`<${tagPattern}\\b[^>]*>([\\s\\S]*?)<\\/${tagPattern}>`,'g');
+  return [...fragment.matchAll(re)].map(m=>xmlDecode(m[1].replace(/<[^>]+>/g,'')));
+}
+function wordText(fragment){
+  const token=/<w:t\b[^>]*>[\s\S]*?<\/w:t>|<w:tab\b[^>]*\/>|<w:(?:br|cr)\b[^>]*\/>/g;
+  let out='';
+  for(const m of fragment.matchAll(token)){
+    const s=m[0];
+    if(/^<w:t(?:\s|>)/.test(s)) out+=xmlDecode((s.match(/<w:t\b[^>]*>([\s\S]*?)<\/w:t>/)?.[1]??'').replace(/<[^>]+>/g,''));
+    else if(s.startsWith('<w:tab')) out+='\t';
+    else out+='\n';
+  }
+  return out;
+}
+function prettyXml(xml){
+  const pieces=xml.replace(/>\s+</g,'><').split(/(?<=>)(?=<)/);
+  const lines=[]; let depth=0;
+  for(const piece of pieces){
+    const t=piece.trim(); if(!t) continue;
+    const closing=t.startsWith('</'),self=t.endsWith('/>'),pi=t.startsWith('<?'),inline=!closing&&!self&&/^<[^>]+>.*<\//s.test(t);
+    if(closing) depth=Math.max(0,depth-1);
+    lines.push('  '.repeat(depth)+t);
+    if(!closing&&!self&&!pi&&!inline) depth++;
+  }
+  return lines.join('\n');
+}
+function docxOutline(xml){
+  const body=xml.match(/<w:body\b[^>]*>([\s\S]*?)<\/w:body>/)?.[1];
+  if(body===undefined) return '[No w:body found in document.xml]';
+  const elements=[...body.matchAll(/<w:(p|tbl)\b[\s\S]*?<\/w:\1>/g)].map(m=>({kind:m[1],xml:m[0]}));
+  const lines=[];
+  for(let i=0;i<elements.length;i++){
+    const item=elements[i];
+    if(item.kind==='p'){
+      const style=item.xml.match(/<w:pStyle\b[^>]*w:val=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean);
+      let line=`[${i}] w:p`;
+      if(style) line+=` style="${xmlDecode(style)}"`;
+      const value=wordText(item.xml);
+      if(value) line+='\n  '+value;
+      lines.push(line);
+    }else{
+      lines.push(`[${i}] w:tbl`);
+      const rows=[...item.xml.matchAll(/<w:tr\b[\s\S]*?<\/w:tr>/g)].map(m=>m[0]);
+      for(let r=0;r<rows.length;r++){
+        const cells=[...rows[r].matchAll(/<w:tc\b[\s\S]*?<\/w:tc>/g)].map(m=>wordText(m[0]).replace(/\s*\n\s*/g,' ').trim());
+        lines.push(`  Row ${r}: ${cells.join(' | ')}`);
+      }
+    }
+  }
+  return lines.join('\n');
+}
+
+export function readDocxBytes(input,{path:displayPath='document.docx',offset=0,length=1000}={}){
+  const files=unzipOffice(input);
+  const doc=files.get('word/document.xml');
+  if(!doc) throw new Error('Invalid DOCX: missing word/document.xml');
+  const xml=decodeUtf8(doc,'word/document.xml');
+  const pretty=prettyXml(xml),allLines=pretty.split('\n'),totalLines=allLines.length;
+  if(!Number.isInteger(offset)||!Number.isInteger(length)||length<0) throw new Error('DOCX offset/length invalid');
+  if(offset!==0){
+    const start=offset<0?Math.max(0,totalLines+offset):Math.min(offset,totalLines);
+    const count=offset<0?totalLines-start:length;
+    const sliced=allLines.slice(start,start+count),remaining=Math.max(0,totalLines-(start+sliced.length));
+    return {content:`[DOCX XML: lines ${start}-${Math.max(start,start+sliced.length-1)} of ${totalLines} (${remaining} remaining)]\n${sliced.join('\n')}`,
+      mimeType:'application/xml',metadata:{isDocx:true,lineCount:totalLines},outline:false};
+  }
+  const outline=docxOutline(xml);
+  const rawSizeKB=(Buffer.byteLength(xml)/1024).toFixed(1);
+  return {content:`${outline}\n\nRaw XML: ${totalLines} lines, ${rawSizeKB}KB.`,mimeType:'text/plain',metadata:{isDocx:true,lineCount:totalLines},outline:true};
+}
+
+
+export function createDocxBytes(content){
+  if(typeof content!=='string') throw new Error('DOCX content must be string');
+  if(Buffer.byteLength(content,'utf8')>4*1024*1024) throw new Error('DOCX content exceeds bounded native write limit');
+  if(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/u.test(content)) throw new Error('DOCX content contains invalid XML control character');
+  const paragraphs=content.split('\n').map(line=>{
+    const heading=/^(#{1,6})\s+(.+)/.exec(line);
+    if(heading) return `<w:p><w:pPr><w:pStyle w:val="Heading${heading[1].length}"/></w:pPr><w:r><w:t>${xmlEscapeText(heading[2])}</w:t></w:r></w:p>`;
+    if(!line.trim()) return '<w:p/>';
+    return `<w:p><w:r><w:t xml:space="preserve">${xmlEscapeText(line)}</w:t></w:r></w:p>`;
+  }).join('');
+  const files=new Map([
+    ['[Content_Types].xml',Buffer.from('<?xml version="1.0" encoding="UTF-8"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/></Types>')],
+    ['_rels/.rels',Buffer.from('<?xml version="1.0" encoding="UTF-8"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>')],
+    ['word/document.xml',Buffer.from(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body>${paragraphs}<w:sectPr><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"/></w:sectPr></w:body></w:document>`)]
+  ]);
+  const bytes=writeStoredZip(files);
+  unzipOffice(bytes);
+  return {bytes,bytes_sha256:officeSha256(bytes)};
+}
+
+export function editDocxBytes(input,{oldString,newString,expectedReplacements=1}={}){
+  const original=Buffer.isBuffer(input)?Buffer.from(input):Buffer.from(input);
+  if(typeof oldString!=='string'||oldString.length<1) throw new Error('DOCX oldString must be non-empty string');
+  if(typeof newString!=='string') throw new Error('DOCX newString must be string');
+  if(!Number.isInteger(expectedReplacements)||expectedReplacements<0) throw new Error('DOCX expectedReplacements must be non-negative integer');
+  const files=unzipOffice(original);
+  const doc=files.get('word/document.xml');
+  if(!doc) throw new Error('Invalid DOCX: missing word/document.xml');
+  const xml=decodeUtf8(doc,'word/document.xml');
+  const pretty=prettyXml(xml);
+  let count=0,index=0;
+  while((index=pretty.indexOf(oldString,index))>=0){count++;index+=Math.max(1,oldString.length);}
+  if(count!==expectedReplacements) throw new Error(`DOCX expected ${expectedReplacements} replacements, found ${count}`);
+  const editedPretty=pretty.split(oldString).join(newString);
+  const compact=editedPretty.split('\n').map(line=>line.trimStart()).join('');
+  files.set('word/document.xml',Buffer.from(compact,'utf8'));
+  const bytes=writeStoredZip(files);
+  const verify=unzipOffice(bytes);
+  const verifiedDoc=verify.get('word/document.xml');
+  if(!verifiedDoc) throw new Error('DOCX repack verification missing word/document.xml');
+  decodeUtf8(verifiedDoc,'word/document.xml');
+  return {
+    bytes,bytes_base64:bytes.toString('base64'),replacements:count,
+    before_sha256:officeSha256(original),after_sha256:officeSha256(bytes)
+  };
+}
+
+function normalizeRelTarget(target){
+  const clean=String(target).replaceAll('\\','/');
+  const joined=path.posix.normalize(path.posix.join('xl',clean));
+  if(joined==='..'||joined.startsWith('../')||!joined.startsWith('xl/')) throw new Error('unsafe XLSX relationship target');
+  return joined;
+}
+function parseWorkbook(files){
+  const workbookBytes=files.get('xl/workbook.xml');
+  const relBytes=files.get('xl/_rels/workbook.xml.rels');
+  if(!workbookBytes||!relBytes) throw new Error('Invalid XLSX: workbook metadata missing');
+  const workbook=decodeUtf8(workbookBytes,'xl/workbook.xml');
+  const rels=decodeUtf8(relBytes,'xl/_rels/workbook.xml.rels');
+  const relMap=new Map();
+  for(const m of rels.matchAll(/<Relationship\b([^>]*)\/?\s*>/g)){
+    const a=xmlAttrs(m[1]);
+    if(a.Id&&a.Target) relMap.set(a.Id,normalizeRelTarget(a.Target));
+  }
+  const sheets=[];
+  for(const m of workbook.matchAll(/<sheet\b([^>]*)\/?\s*>/g)){
+    const a=xmlAttrs(m[1]),id=a['r:id'];
+    if(!a.name||!id||!relMap.has(id)) continue;
+    sheets.push({name:a.name,path:relMap.get(id)});
+  }
+  if(sheets.length===0) throw new Error('Invalid XLSX: no worksheets');
+  return sheets;
+}
+function sharedStrings(files){
+  const bytes=files.get('xl/sharedStrings.xml'); if(!bytes) return [];
+  const xml=decodeUtf8(bytes,'xl/sharedStrings.xml');
+  return [...xml.matchAll(/<si\b[^>]*>([\s\S]*?)<\/si>/g)].map(m=>xmlTextFragments(m[1],'t').join(''));
+}
+function columnNumber(ref){
+  const letters=ref.match(/^[A-Za-z]+/)?.[0]; if(!letters) return null;
+  let n=0; for(const ch of letters.toUpperCase()) n=n*26+(ch.charCodeAt(0)-64);
+  return n;
+}
+function cellReference(ref){
+  const m=/^([A-Za-z]+)([1-9][0-9]*)$/.exec(ref); if(!m) return null;
+  return {col:columnNumber(m[1]),row:Number(m[2])};
+}
+function parseWorksheet(files,sheet,shared){
+  const bytes=files.get(sheet.path); if(!bytes) throw new Error(`Invalid XLSX: worksheet '${sheet.name}' is missing`);
+  const xml=decodeUtf8(bytes,sheet.path);
+  const cells=new Map(); let maxRow=0,maxCol=0;
+  for(const m of xml.matchAll(/<c\b([^>]*?)(?:\/>|>([\s\S]*?)<\/c>)/g)){
+    const a=xmlAttrs(m[1]),ref=cellReference(a.r??''); if(!ref) continue;
+    const body=m[2]??'',type=a.t??'';
+    const rawV=body.match(/<v\b[^>]*>([\s\S]*?)<\/v>/)?.[1]??null;
+    let value=null;
+    if(type==='s'&&rawV!==null){const index=Number(rawV);value=Number.isInteger(index)&&index>=0&&index<shared.length?shared[index]:null;}
+    else if(type==='inlineStr') value=xmlTextFragments(body,'t').join('');
+    else if(type==='b'&&rawV!==null) value=String(rawV).trim()==='1';
+    else if((type==='str'||type==='d'||type==='e')&&rawV!==null) value=xmlDecode(rawV);
+    else if(rawV!==null){const s=xmlDecode(rawV).trim();const n=Number(s);value=s!==''&&Number.isFinite(n)?n:s;}
+    cells.set(`${ref.row}:${ref.col}`,value);maxRow=Math.max(maxRow,ref.row);maxCol=Math.max(maxCol,ref.col);
+  }
+  return {sheet,cells,maxRow,maxCol};
+}
+function parseA1Range(value){
+  const m=/^([A-Za-z]+[1-9][0-9]*)(?::([A-Za-z]+[1-9][0-9]*))?$/.exec(value??'');
+  if(!m) throw new Error(`invalid XLSX range '${value}'`);
+  const a=cellReference(m[1]),b=cellReference(m[2]??m[1]);
+  if(!a||!b||b.row<a.row||b.col<a.col) throw new Error(`invalid XLSX range '${value}'`);
+  return {startRow:a.row,startCol:a.col,endRow:b.row,endCol:b.col};
+}
+function parseSheetQualifiedRange(value){
+  if(typeof value!=='string'||!value.includes('!')) return {sheet:null,range:value};
+  const bang=value.lastIndexOf('!');
+  let sheet=value.slice(0,bang),range=value.slice(bang+1);
+  if(sheet.startsWith("'")&&sheet.endsWith("'")) sheet=sheet.slice(1,-1).replaceAll("''","'");
+  return {sheet,range};
+}
+function chooseSheet(sheets,sheetRef){
+  if(sheetRef===undefined||sheetRef===null) return sheets[0];
+  if(typeof sheetRef==='number'){
+    if(!Number.isInteger(sheetRef)||sheetRef<0||sheetRef>=sheets.length) throw new Error(`Sheet index ${sheetRef} out of range`);
+    return sheets[sheetRef];
+  }
+  const found=sheets.find(s=>s.name===sheetRef);
+  if(!found) throw new Error(`Sheet "${sheetRef}" not found. Available sheets: ${sheets.map(s=>s.name).join(', ')}`);
+  return found;
+}
+function sheetArray(parsed,{range,offset=0,length=1000}={}){
+  let startRow=1,startCol=1,endRow=Math.max(1,parsed.maxRow),endCol=Math.max(1,parsed.maxCol);
+  if(range){const r=parseA1Range(range);({startRow,startCol,endRow,endCol}=r);}
+  const totalRows=Math.max(0,endRow-startRow+1);
+  if(!Number.isInteger(offset)||!Number.isInteger(length)||length<0) throw new Error('XLSX offset/length invalid');
+  if(offset<0) startRow=Math.max(startRow,endRow-Math.abs(offset)+1);
+  else if(offset>0) startRow+=offset;
+  if(offset>=0&&length>0) endRow=Math.min(endRow,startRow+length-1);
+  if(startRow>endRow) return {data:[],totalRows,returnedRows:0};
+  const data=[];
+  for(let row=startRow;row<=endRow;row++){
+    const out=[];for(let col=startCol;col<=endCol;col++) out.push(parsed.cells.get(`${row}:${col}`)??null);
+    data.push(out);
+  }
+  return {data,totalRows,returnedRows:data.length};
+}
+
+export function readXlsxBytes(input,{path:displayPath='workbook.xlsx',sheet=undefined,range=undefined,offset=0,length=1000}={}){
+  const bytes=Buffer.isBuffer(input)?input:Buffer.from(input);
+  const files=unzipOffice(bytes),sheets=parseWorkbook(files),shared=sharedStrings(files);
+  let rangeOnly=range,sheetRef=sheet;
+  if(range&&range.includes('!')){
+    const parsed=parseSheetQualifiedRange(range); rangeOnly=parsed.range;
+    if(sheetRef===undefined) sheetRef=parsed.sheet;
+  }
+  const selected=chooseSheet(sheets,sheetRef);
+  const parsedSelected=parseWorksheet(files,selected,shared);
+  const rows=sheetArray(parsedSelected,{range:rangeOnly,offset,length});
+  const metadataSheets=sheets.map(s=>{
+    const p=parseWorksheet(files,s,shared);return {name:s.name,rowCount:p.maxRow,colCount:p.maxCol};
+  });
+  const pagination=rows.totalRows>rows.returnedRows?`\n[Showing rows ${(offset>=0?offset:0)+1}-${(offset>=0?offset:0)+rows.returnedRows} of ${rows.totalRows} total. Use offset/length to paginate.]`:'';
+  const example=/\s/.test(selected.name)?selected.name:'Sheet1';
+  const content=`[Sheet: '${selected.name}' from ${displayPath}]${pagination}\n[To MODIFY cells: use edit_block with range param, e.g., edit_block(path, {range: "${example}!E5", content: [[newValue]]}). read_file accepts the same range form, or pass sheet + range separately.]\n\n${JSON.stringify(rows.data)}`;
+  return {content,mimeType:'application/json',metadata:{isExcelFile:true,sheets:metadataSheets,fileSize:bytes.length,isLargeFile:bytes.length>10*1024*1024},
+    sheetName:selected.name,data:rows.data,totalRows:rows.totalRows,returnedRows:rows.returnedRows};
+}
+
+
+function officeSha256(bytes){return createHash('sha256').update(bytes).digest('hex');}
+function xmlEscapeText(value){
+  return String(value).replaceAll('&','&amp;').replaceAll('<','&lt;').replaceAll('>','&gt;');
+}
+function columnLetters(column){
+  if(!Number.isInteger(column)||column<1) throw new Error('XLSX column invalid');
+  let n=column,out='';
+  while(n>0){n--;out=String.fromCharCode(65+(n%26))+out;n=Math.floor(n/26);}
+  return out;
+}
+function xlsxCellXml(ref,value){
+  if(value===null) return `<c r="${ref}"/>`;
+  if(typeof value==='string'){
+    const preserve=/^\s|\s$/.test(value)?' xml:space="preserve"':'';
+    return `<c r="${ref}" t="inlineStr"><is><t${preserve}>${xmlEscapeText(value)}</t></is></c>`;
+  }
+  if(typeof value==='number'){
+    if(!Number.isFinite(value)) throw new Error('unsupported XLSX cell value: non-finite number');
+    return `<c r="${ref}"><v>${String(value)}</v></c>`;
+  }
+  if(typeof value==='boolean') return `<c r="${ref}" t="b"><v>${value?'1':'0'}</v></c>`;
+  throw new Error(`unsupported XLSX cell value type '${typeof value}'`);
+}
+function rowNumberFromXml(fragment){
+  const open=fragment.match(/^<row\b([^>]*)>/)?.[1]??'';
+  const value=xmlAttrs(open).r;
+  const n=Number(value);
+  return Number.isInteger(n)&&n>0?n:null;
+}
+function cellColumnFromXml(fragment){
+  const open=fragment.match(/^<c\b([^>]*?)(?:\/?>)/)?.[1]??'';
+  const ref=xmlAttrs(open).r??'';
+  return cellReference(ref)?.col??null;
+}
+function editWorksheetCell(xml,row,column,value){
+  const ref=`${columnLetters(column)}${row}`,replacement=xlsxCellXml(ref,value);
+  const sheetData=xml.match(/<sheetData\b[^>]*>([\s\S]*?)<\/sheetData>/);
+  if(!sheetData) throw new Error('Invalid XLSX: worksheet sheetData missing');
+  const full=sheetData[0],body=sheetData[1];
+  const bodyOffset=full.indexOf(body);
+  const rows=[...body.matchAll(/<row\b[^>]*>[\s\S]*?<\/row>/g)];
+  const rowMatch=rows.find(m=>rowNumberFromXml(m[0])===row);
+  let nextBody;
+  if(rowMatch){
+    const rowXml=rowMatch[0],openEnd=rowXml.indexOf('>')+1,closeStart=rowXml.lastIndexOf('</row>');
+    const rowOpen=rowXml.slice(0,openEnd),rowInner=rowXml.slice(openEnd,closeStart);
+    const cells=[...rowInner.matchAll(/<c\b[^>]*(?:\/>|>[\s\S]*?<\/c>)/g)];
+    const exact=cells.find(m=>(m[0].match(/^<c\b([^>]*?)(?:\/?>)/)?.[1]&&xmlAttrs(m[0].match(/^<c\b([^>]*?)(?:\/?>)/)[1]).r===ref));
+    let nextInner;
+    if(exact){
+      nextInner=rowInner.slice(0,exact.index)+replacement+rowInner.slice(exact.index+exact[0].length);
+    }else{
+      const later=cells.find(m=>(cellColumnFromXml(m[0])??Number.MAX_SAFE_INTEGER)>column);
+      const at=later?later.index:rowInner.length;
+      nextInner=rowInner.slice(0,at)+replacement+rowInner.slice(at);
+    }
+    const nextRow=rowOpen+nextInner+'</row>';
+    nextBody=body.slice(0,rowMatch.index)+nextRow+body.slice(rowMatch.index+rowXml.length);
+  }else{
+    const newRow=`<row r="${row}">${replacement}</row>`;
+    const later=rows.find(m=>(rowNumberFromXml(m[0])??Number.MAX_SAFE_INTEGER)>row);
+    const at=later?later.index:body.length;
+    nextBody=body.slice(0,at)+newRow+body.slice(at);
+  }
+  return xml.slice(0,sheetData.index+bodyOffset)+nextBody+xml.slice(sheetData.index+bodyOffset+body.length);
+}
+function writeStoredZip(files){
+  const locals=[],centrals=[];let offset=0;
+  const entries=[...files.entries()].filter(([name])=>!name.endsWith('/')).sort((a,b)=>a[0].localeCompare(b[0],'en'));
+  for(const [name,value] of entries){
+    const n=Buffer.from(name,'utf8'),data=Buffer.from(value),crc=crc32(data);
+    const local=Buffer.alloc(30);
+    local.writeUInt32LE(ZIP_LOCAL,0);local.writeUInt16LE(20,4);local.writeUInt16LE(0x800,6);local.writeUInt16LE(0,8);
+    local.writeUInt32LE(crc,14);local.writeUInt32LE(data.length,18);local.writeUInt32LE(data.length,22);local.writeUInt16LE(n.length,26);
+    locals.push(local,n,data);
+    const central=Buffer.alloc(46);
+    central.writeUInt32LE(ZIP_CENTRAL,0);central.writeUInt16LE(20,4);central.writeUInt16LE(20,6);central.writeUInt16LE(0x800,8);central.writeUInt16LE(0,10);
+    central.writeUInt32LE(crc,16);central.writeUInt32LE(data.length,20);central.writeUInt32LE(data.length,24);central.writeUInt16LE(n.length,28);central.writeUInt32LE(offset,42);
+    centrals.push(central,n);offset+=local.length+n.length+data.length;
+  }
+  const localBytes=Buffer.concat(locals),centralBytes=Buffer.concat(centrals),eocd=Buffer.alloc(22);
+  eocd.writeUInt32LE(ZIP_EOCD,0);eocd.writeUInt16LE(entries.length,8);eocd.writeUInt16LE(entries.length,10);
+  eocd.writeUInt32LE(centralBytes.length,12);eocd.writeUInt32LE(localBytes.length,16);
+  return Buffer.concat([localBytes,centralBytes,eocd]);
+}
+
+export function editXlsxBytes(input,{range,content}={}){
+  const original=Buffer.isBuffer(input)?Buffer.from(input):Buffer.from(input);
+  const files=unzipOffice(original),sheets=parseWorkbook(files);
+  const qualified=parseSheetQualifiedRange(range);
+  const selected=chooseSheet(sheets,qualified.sheet);
+  const bounds=parseA1Range(qualified.range);
+  const expectedRows=bounds.endRow-bounds.startRow+1,expectedCols=bounds.endCol-bounds.startCol+1;
+  if(!Array.isArray(content)||content.length!==expectedRows||content.some(row=>!Array.isArray(row)||row.length!==expectedCols)) {
+    throw new Error(`XLSX range/content shape mismatch: expected ${expectedRows}x${expectedCols}`);
+  }
+  const sheetBytes=files.get(selected.path);
+  if(!sheetBytes) throw new Error(`Invalid XLSX: worksheet '${selected.name}' is missing`);
+  let xml=decodeUtf8(sheetBytes,selected.path),updated=0;
+  for(let r=0;r<expectedRows;r++) for(let col=0;col<expectedCols;col++){
+    xml=editWorksheetCell(xml,bounds.startRow+r,bounds.startCol+col,content[r][col]);updated++;
+  }
+  files.set(selected.path,Buffer.from(xml,'utf8'));
+  const bytes=writeStoredZip(files);
+  unzipOffice(bytes);
+  return {bytes,bytes_base64:bytes.toString('base64'),before_sha256:officeSha256(original),after_sha256:officeSha256(bytes),updated_cells:updated,sheet:selected.name,range:qualified.range};
+}
+
+
+function xmlEscapeAttr(value){
+  return xmlEscapeText(value).replaceAll('"','&quot;').replaceAll("'","&apos;");
+}
+function validateSheetName(name){
+  const forbidden=['[',']',':','*','?','/','\\\\'];
+  if(typeof name!=='string'||name.length<1||name.length>31||forbidden.some(ch=>name.includes(ch))) throw new Error(`XLSX sheet name invalid: '${String(name)}'`);
+  return name;
+}
+function validateSheetRows(rows,label){
+  if(!Array.isArray(rows)) throw new Error(`XLSX sheet '${label}' data must be a 2D array`);
+  if(rows.length>1048576) throw new Error(`XLSX sheet '${label}' exceeds row limit`);
+  let width=null,cells=0;
+  for(let r=0;r<rows.length;r++){
+    if(!Array.isArray(rows[r])) throw new Error(`XLSX sheet '${label}' row ${r+1} must be array`);
+    if(width===null) width=rows[r].length;
+    if(rows[r].length!==width) throw new Error(`XLSX sheet '${label}' data must be rectangular`);
+    if(rows[r].length>16384) throw new Error(`XLSX sheet '${label}' exceeds column limit`);
+    cells+=rows[r].length;
+    for(let col=0;col<rows[r].length;col++) xlsxCellXml(`${columnLetters(col+1)}${r+1}`,rows[r][col]);
+  }
+  if(cells>1000000) throw new Error(`XLSX sheet '${label}' exceeds 1000000 cell budget`);
+  return {rows:rows.length,cols:width??0,cells};
+}
+function normalizeWorkbookInput(value){
+  if(Array.isArray(value)) return new Map([['Sheet1',value]]);
+  if(!value||typeof value!=='object') throw new Error('XLSX content must be a 2D array or object of sheet arrays');
+  const out=new Map(),seen=new Set();
+  for(const [rawName,rows] of Object.entries(value)){
+    const name=validateSheetName(rawName),fold=name.toLowerCase();
+    if(seen.has(fold)) throw new Error(`XLSX duplicate sheet name '${name}'`);
+    seen.add(fold);validateSheetRows(rows,name);out.set(name,rows);
+  }
+  if(out.size<1) throw new Error('XLSX workbook must contain at least one sheet');
+  return out;
+}
+function worksheetXml(rows){
+  validateSheetRows(rows,'Sheet1');
+  const body=[];
+  for(let r=0;r<rows.length;r++){
+    const cells=rows[r].map((value,col)=>xlsxCellXml(`${columnLetters(col+1)}${r+1}`,value)).join('');
+    body.push(`<row r="${r+1}">${cells}</row>`);
+  }
+  return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"><sheetData>${body.join('')}</sheetData></worksheet>`;
+}
+export function createXlsxBytes(value){
+  const workbook=normalizeWorkbookInput(value),files=new Map();
+  const sheets=[...workbook.entries()];
+  const contentOverrides=sheets.map((_,i)=>`<Override PartName="/xl/worksheets/sheet${i+1}.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>`).join('');
+  files.set('[Content_Types].xml',Buffer.from(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>${contentOverrides}</Types>`,'utf8'));
+  files.set('_rels/.rels',Buffer.from('<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/></Relationships>','utf8'));
+  files.set('xl/workbook.xml',Buffer.from(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?><workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><sheets>${sheets.map(([name],i)=>`<sheet name="${xmlEscapeAttr(name)}" sheetId="${i+1}" r:id="rId${i+1}"/>`).join('')}</sheets></workbook>`,'utf8'));
+  files.set('xl/_rels/workbook.xml.rels',Buffer.from(`<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">${sheets.map((_,i)=>`<Relationship Id="rId${i+1}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet${i+1}.xml"/>`).join('')}</Relationships>`,'utf8'));
+  sheets.forEach(([name,rows],i)=>files.set(`xl/worksheets/sheet${i+1}.xml`,Buffer.from(worksheetXml(rows),'utf8')));
+  const bytes=writeStoredZip(files);
+  unzipOffice(bytes);
+  return {bytes,bytes_base64:bytes.toString('base64'),bytes_sha256:officeSha256(bytes),sheet_count:sheets.length};
+}
+export function appendXlsxBytes(input,value){
+  const original=Buffer.isBuffer(input)?Buffer.from(input):Buffer.from(input);
+  const files=unzipOffice(original),sheets=parseWorkbook(files),appends=normalizeWorkbookInput(value);
+  let appendedRows=0,updatedCells=0;
+  for(const [sheetName,rows] of appends){
+    validateSheetRows(rows,sheetName);
+    const selected=chooseSheet(sheets,sheetName);
+    const sheetBytes=files.get(selected.path);
+    if(!sheetBytes) throw new Error(`Invalid XLSX: worksheet '${selected.name}' is missing`);
+    let xml=decodeUtf8(sheetBytes,selected.path);
+    let maxRow=0;
+    for(const match of xml.matchAll(/<row\b[^>]*>[\s\S]*?<\/row>/g)){
+      const n=rowNumberFromXml(match[0]);if(n!==null&&n>maxRow) maxRow=n;
+    }
+    for(let r=0;r<rows.length;r++) for(let col=0;col<rows[r].length;col++){
+      xml=editWorksheetCell(xml,maxRow+r+1,col+1,rows[r][col]);updatedCells++;
+    }
+    appendedRows+=rows.length;
+    files.set(selected.path,Buffer.from(xml,'utf8'));
+  }
+  const bytes=writeStoredZip(files);
+  unzipOffice(bytes);
+  return {bytes,bytes_base64:bytes.toString('base64'),before_sha256:officeSha256(original),after_sha256:officeSha256(bytes),appended_rows:appendedRows,updated_cells:updatedCells};
+}
+
+export { unzipOffice as parseOfficeZip };