@remcp/runtime 0.2.122 → 0.2.124

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.124 — 2026-10-01
+
+- P3 document capability discovery is cross-platform: Windows uses the native .NET OOXML archive backend, while macOS/Linux require both `zip` and `unzip` before advertising the XLSX/DOCX editor tools.
+- `read_document` and `pdf_action` remain discoverable on supported desktop platforms even without an OOXML archive backend; DOCX/XLSX read attempts still fail closed at execution time when extraction is unavailable. `edit_spreadsheet` and `edit_document` explicitly require `ooxml`.
+- Windows and macOS release CI run real candidate XLSX/DOCX create/read round trips before publication. The 83-tool names and schemas are unchanged.
+
+## 0.2.123 — 2026-10-01
+
+- The compact local MCP facade now tracks live capability changes after startup. It advertises `tools.listChanged`, refreshes grouped input/output schemas, and adds or removes domains such as `control_browser` when loopback CDP becomes available or unavailable.
+- Compact and granular capability polling now serializes discovery passes so a slow probe cannot overlap the next interval and apply a stale capability result out of order.
+- The underlying 83 granular runtime tool names, input/output schemas, annotations, and handlers remain unchanged from 0.2.122.
+
 ## 0.2.122 — 2026-09-30
 
 - No runtime tool names, schemas, or device-side implementations change in this release. The runtime package version remains in lockstep with the Windows bootstrap release, which pins the private Windows Node execution engine for reproducible installs.

package/README.md

@@ -27,7 +27,7 @@ npx @remcp/runtime              # granular capability-aware MCP server over stdi
 node ./src/compact.mjs --print-tools  # compact local façade for scanners/local MCP hosts
 ```
 
-`src/compact.mjs` is a second stdio entrypoint over the **same real handlers**. It advertises `read_file` plus up to seven `verb_noun` domain tools (`manage_files`, `run_terminal`, `control_computer`, `view_image`, `control_browser`, `manage_system`, `manage_documents`) and narrows each operation enum to capabilities available on the current host. It exists for directory scanners and local MCP hosts that benefit from a small selection surface; the paired ReMCP agent continues to use the granular capability-aware entrypoint.
+`src/compact.mjs` is a second stdio entrypoint over the **same real handlers**. It advertises `read_file` plus up to seven `verb_noun` domain tools (`manage_files`, `run_terminal`, `control_computer`, `view_image`, `control_browser`, `manage_system`, `manage_documents`) and narrows each operation enum to capabilities available on the current host. It also tracks capability changes while running: grouped schemas are refreshed and `notifications/tools/list_changed` is emitted when a domain appears, disappears, or changes membership. It exists for directory scanners and local MCP hosts that benefit from a small selection surface; the paired ReMCP agent continues to use the granular capability-aware entrypoint.
 
 ## Tools
 
@@ -67,7 +67,8 @@ For frontend QA, use semantic data to operate the page and rendered pixels to ve
 `set_config_value` remains deliberately narrow: it can change only `telemetryEnabled`,
 `maxReadLines`, `maxBufferedLines`, and `maxOutputBytes`. Access roots, blocked commands,
 the command guardrail, shell, write limit, runtime name, and unrestricted mode stay with the person
-at the computer. DOCX/XLSX edits operate directly on OOXML, while structural PDF writes use existing
+at the computer. DOCX/XLSX edits operate directly on OOXML: Windows uses the built-in .NET ZIP backend,
+while macOS/Linux advertise the OOXML editor tools only when both `zip` and `unzip` are available. `read_document` stays discoverable for PDF/plain-text formats when that backend is absent and fails closed only for DOCX/XLSX reads. Structural PDF writes use existing
 system tools such as qpdf/poppler when present. PDF text reading uses the built-in parser first and can fall back to local `pdftotext` for embedded-font PDFs; ReMCP still does not bundle Chromium, Puppeteer,
 `sharp`, or `exceljs`.
 
@@ -81,7 +82,7 @@ example: they are enabled only while the runtime can use a supported loopback br
 The generated hosted reference covers the current **10 hosted production definitions**, all model-visible
 and routing to the 83 granular runtime operations described above; the optional widget-enabled surface is 15.
 The separate compact local stdio entrypoint advertises `read_file` plus up to seven domain tools
-(up to 8 tools total) while the paired agent keeps using the capability-aware granular runtime.
+(up to 8 tools total) and keeps those groups capability-aware at runtime with `tools/list_changed`; the paired agent keeps using the capability-aware granular runtime.
 See https://remcp.site/docs#tools and public `docs/TOOLS.md`.
 
 ## No approval staircase

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.122",
+  "version": "0.2.124",
   "description": "First-party ReMCP local device runtime: filesystem, terminal, computer-use, browser, diagnostics and document tools over MCP.",
   "type": "module",
   "license": "MIT",

package/src/compact-mcp.mjs

@@ -1,6 +1,14 @@
+import process from 'node:process';
 import { compactRuntimeToolDefinitions, resolveCompactRuntimeCall } from './compact-catalog.mjs';
 import { invokeTool } from './invoke.mjs';
 
+const DEFAULT_CAPABILITY_POLL_MS = 3000;
+
+function pollIntervalMs() {
+  const requested = Number(process.env.REMCP_CAPABILITY_POLL_MS);
+  return Math.min(60_000, Math.max(250, Number.isFinite(requested) && requested > 0 ? requested : DEFAULT_CAPABILITY_POLL_MS));
+}
+
 function toolConfig(definition, fromJsonSchema) {
   return {
     title:definition.title,
@@ -11,20 +19,45 @@ function toolConfig(definition, fromJsonSchema) {
   };
 }
 
+function toolUpdate(definition, fromJsonSchema) {
+  return {
+    title:definition.title,
+    description:definition.description,
+    paramsSchema:fromJsonSchema(definition.inputSchema || { type:'object' }),
+    ...(definition.outputSchema ? { outputSchema:fromJsonSchema(definition.outputSchema) } : {}),
+    annotations:definition.annotations,
+    enabled:true,
+  };
+}
+
+function definitionSignature(definition) {
+  if (!definition) return '';
+  return JSON.stringify({
+    title:definition.title,
+    description:definition.description,
+    inputSchema:definition.inputSchema,
+    outputSchema:definition.outputSchema,
+    annotations:definition.annotations,
+  });
+}
+
 export async function startCompactRuntimeMcpServer({ version, instructions, onError = () => {} } = {}) {
   const [{ McpServer, fromJsonSchema }, { serveStdio }] = await Promise.all([
     import('@modelcontextprotocol/server'),
     import('@modelcontextprotocol/server/stdio'),
   ]);
-  const definitions = await compactRuntimeToolDefinitions();
+  let definitions = await compactRuntimeToolDefinitions();
+  const currentDefinitions = new Map(definitions.map(definition => [definition.name, definition]));
   let activeServer = null;
+  let capabilityTimer = null;
+  let capabilityPollRunning = false;
   let closed = false;
 
   const serverHandle = serveStdio(() => {
     const server = new McpServer(
       { name:'remcp-runtime-compact', version },
       {
-        capabilities:{ tools:{} },
+        capabilities:{ tools:{ listChanged:true } },
         instructions,
         cacheHints:{
           'tools/list':{ ttlMs:3000, cacheScope:'private' },
@@ -33,20 +66,78 @@ export async function startCompactRuntimeMcpServer({ version, instructions, onEr
       },
     );
     activeServer = server;
-    for (const definition of definitions) {
-      server.registerTool(
+    const registrations = new Map();
+
+    const registerDefinition = definition => {
+      const registered = server.registerTool(
         definition.name,
         toolConfig(definition, fromJsonSchema),
         async (args, context) => {
           try {
-            const resolved = resolveCompactRuntimeCall(definition.name, args || {}, definitions);
+            const activeDefinitions = [...currentDefinitions.values()];
+            const resolved = resolveCompactRuntimeCall(definition.name, args || {}, activeDefinitions);
             return await invokeTool(resolved.runtimeName, resolved.runtimeArguments, { signal:context?.mcpReq?.signal });
           } catch (error) {
             return { content:[{ type:'text', text:error instanceof Error ? error.message : String(error) }], isError:true };
           }
         },
       );
-    }
+      registrations.set(definition.name, registered);
+      return registered;
+    };
+
+    for (const definition of definitions) registerDefinition(definition);
+
+    capabilityTimer = setInterval(async () => {
+      if (closed || capabilityPollRunning) return;
+      capabilityPollRunning = true;
+      try {
+        const nextDefinitions = await compactRuntimeToolDefinitions();
+        const nextByName = new Map(nextDefinitions.map(definition => [definition.name, definition]));
+        const names = new Set([...registrations.keys(), ...nextByName.keys()]);
+
+        for (const name of names) {
+          const before = currentDefinitions.get(name);
+          const after = nextByName.get(name);
+          const registered = registrations.get(name);
+
+          if (!after) {
+            currentDefinitions.delete(name);
+            if (registered?.enabled) registered.disable();
+            continue;
+          }
+
+          if (!registered) {
+            currentDefinitions.set(name, after);
+            registerDefinition(after);
+            continue;
+          }
+
+          if (definitionSignature(before) === definitionSignature(after) && registered.enabled !== false) {
+            currentDefinitions.set(name, after);
+            continue;
+          }
+
+          const previous = before;
+          currentDefinitions.set(name, after);
+          try {
+            registered.update(toolUpdate(after, fromJsonSchema));
+          } catch (error) {
+            if (previous) currentDefinitions.set(name, previous);
+            else currentDefinitions.delete(name);
+            throw error;
+          }
+        }
+
+        definitions = nextDefinitions;
+      } catch (error) {
+        onError(error instanceof Error ? error : new Error(String(error)));
+      } finally {
+        capabilityPollRunning = false;
+      }
+    }, pollIntervalMs());
+    capabilityTimer.unref?.();
+
     return server;
   }, {
     legacy:'serve',
@@ -54,7 +145,7 @@ export async function startCompactRuntimeMcpServer({ version, instructions, onEr
   });
 
   return {
-    definitions,
+    get definitions() { return definitions; },
     async notification(notification) {
       if (!activeServer) return;
       await activeServer.server.notification(notification);
@@ -62,6 +153,8 @@ export async function startCompactRuntimeMcpServer({ version, instructions, onEr
     async close() {
       if (closed) return;
       closed = true;
+      if (capabilityTimer) clearInterval(capabilityTimer);
+      capabilityTimer = null;
       await serverHandle.close();
       activeServer = null;
     },

package/src/documents.mjs

@@ -40,7 +40,7 @@ function unzipEntry(buffer, wanted) {
     const extraLength = buffer.readUInt16LE(offset + 30);
     const commentLength = buffer.readUInt16LE(offset + 32);
     const localOffset = buffer.readUInt32LE(offset + 42);
-    const name = buffer.toString('utf8', offset + 46, offset + 46 + nameLength);
+    const name = buffer.toString('utf8', offset + 46, offset + 46 + nameLength).replace(/\\/g, '/');
     if (name === wanted) {
       const localNameLength = buffer.readUInt16LE(localOffset + 26);
       const localExtraLength = buffer.readUInt16LE(localOffset + 28);
@@ -116,16 +116,19 @@ function wordXmlText(xml) {
   return output;
 }
 
-export function readDocxText(buffer) {
-  const document = unzipEntry(buffer, 'word/document.xml');
-  if (!document) throw new Error('This file is not a readable .docx (its word/document.xml is missing or compressed in an unsupported way)');
-  const xml = document.toString('utf8');
-  return wordXmlText(xml)
+export function readDocxXmlText(xml) {
+  return wordXmlText(String(xml))
     .replace(/&(amp|lt|gt|quot|apos);/g, match => DOCX_ENTITIES[match])
     .replace(/\n{3,}/g, '\n\n')
     .trim();
 }
 
+export function readDocxText(buffer) {
+  const document = unzipEntry(buffer, 'word/document.xml');
+  if (!document) throw new Error('This file is not a readable .docx (its word/document.xml is missing or compressed in an unsupported way)');
+  return readDocxXmlText(document.toString('utf8'));
+}
+
 function decodePdfString(raw) {
   // Literal strings arrive with backslash escapes; hex strings are pairs of hex digits.
   return raw

package/src/extended/catalog.mjs

@@ -569,8 +569,8 @@ export const extendedToolDefinitions = [
   define('record_screen', 'Record screen', 'Record a short bounded desktop video to a permitted local file for debugging and return its path and size. Uses native/available recording helpers.', o({ duration_seconds:n('1..120 seconds.'), fps:n('1..60.'), destination:s('Permitted output path. If an extension is supplied, use .webm for native GNOME Wayland recording and .mp4 for the other recorder backends.') }), mutating, diagnosticHandlers.record_screen, ['record']),
 
   define('read_document', 'Read document', 'Read PDF, DOCX, XLSX, TXT, Markdown, CSV, JSON, or XML. PDF/DOCX extraction is built in and XLSX is parsed from its OOXML worksheet cells.', o({ path:s('Document path.'), sheet:s('Worksheet name for XLSX.'), max_cells:n() }, ['path']), readOnly, documentHandlers.read_document, ['documents']),
-  define('edit_spreadsheet', 'Edit spreadsheet', 'Create a new XLSX workbook or edit up to 500 expanded XLSX cells directly in OOXML without launching Excel. For creation set create=true and use path as a new destination; existing files are never overwritten by create mode. Each edit may target one cell or a rectangular range, with a scalar fill, a values matrix, or a formula.', o({ path:s('Existing .xlsx path, or the new workbook destination when create=true.'), create:b('Create a new XLSX at path. Fails if path already exists; do not combine with output.'), output:s('Optional output .xlsx when editing an existing workbook; defaults to replacing input.'), sheet:s('Worksheet name. For create=true, defaults to Sheet1 and becomes the new workbook sheet name.'), edits:{ type:'array', maxItems:500, items:o({ cell:s('Single A1 cell reference.'), range:s('Rectangular range such as A1:C3.'), value:{ description:'Scalar value for one cell or to fill a range.' }, values:{ type:'array', items:{ type:'array', items:{} }, description:'2D matrix matching the range dimensions.' }, formula:s('Optional formula; for a range it is written to each expanded cell.') }) } }, ['path','edits']), mutating, documentHandlers.edit_spreadsheet, ['documents']),
-  define('edit_document', 'Edit DOCX document', 'Create a new DOCX document or edit DOCX paragraph structure directly in OOXML: replace text, append/prepend paragraphs, insert before/after matching paragraphs, or delete matching paragraphs. For creation set create=true and use path as a new destination; existing files are never overwritten by create mode.', o({ path:s('Existing .docx path, or the new document destination when create=true.'), create:b('Create a new DOCX at path. Fails if path already exists; do not combine with output.'), output:s('Optional output .docx path when editing an existing document.'), operations:{ type:'array', maxItems:100, items:o({ action:e(['replace','append_paragraph','prepend_paragraph','insert_paragraph_before','insert_paragraph_after','delete_paragraph']), search:s('Paragraph text substring for replace/insert/delete operations.'), replacement:s(), all:b('Apply to all matching paragraphs; default true.'), text:s('Paragraph text to append/prepend/insert.') }, ['action']) } }, ['path','operations']), mutating, documentHandlers.edit_document, ['documents']),
+  define('edit_spreadsheet', 'Edit spreadsheet', 'Create a new XLSX workbook or edit up to 500 expanded XLSX cells directly in OOXML without launching Excel. For creation set create=true and use path as a new destination; existing files are never overwritten by create mode. Each edit may target one cell or a rectangular range, with a scalar fill, a values matrix, or a formula.', o({ path:s('Existing .xlsx path, or the new workbook destination when create=true.'), create:b('Create a new XLSX at path. Fails if path already exists; do not combine with output.'), output:s('Optional output .xlsx when editing an existing workbook; defaults to replacing input.'), sheet:s('Worksheet name. For create=true, defaults to Sheet1 and becomes the new workbook sheet name.'), edits:{ type:'array', maxItems:500, items:o({ cell:s('Single A1 cell reference.'), range:s('Rectangular range such as A1:C3.'), value:{ description:'Scalar value for one cell or to fill a range.' }, values:{ type:'array', items:{ type:'array', items:{} }, description:'2D matrix matching the range dimensions.' }, formula:s('Optional formula; for a range it is written to each expanded cell.') }) } }, ['path','edits']), mutating, documentHandlers.edit_spreadsheet, ['documents','ooxml']),
+  define('edit_document', 'Edit DOCX document', 'Create a new DOCX document or edit DOCX paragraph structure directly in OOXML: replace text, append/prepend paragraphs, insert before/after matching paragraphs, or delete matching paragraphs. For creation set create=true and use path as a new destination; existing files are never overwritten by create mode.', o({ path:s('Existing .docx path, or the new document destination when create=true.'), create:b('Create a new DOCX at path. Fails if path already exists; do not combine with output.'), output:s('Optional output .docx path when editing an existing document.'), operations:{ type:'array', maxItems:100, items:o({ action:e(['replace','append_paragraph','prepend_paragraph','insert_paragraph_before','insert_paragraph_after','delete_paragraph']), search:s('Paragraph text substring for replace/insert/delete operations.'), replacement:s(), all:b('Apply to all matching paragraphs; default true.'), text:s('Paragraph text to append/prepend/insert.') }, ['action']) } }, ['path','operations']), mutating, documentHandlers.edit_document, ['documents','ooxml']),
   define('pdf_action', 'PDF action', 'Inspect PDF annotations or metadata, merge PDFs, split a PDF into pages, or extract selected page ranges. Structural writes use qpdf/poppler/pdftk when installed.', o({ action:e(['merge','split','extract_pages','annotations','info']), path:s(), paths:{type:'array',items:{type:'string'}}, output:s(), output_dir:s(), pattern:s(), pages:s('Page list/ranges such as 1-3,5.') }, ['action']), mutating, documentHandlers.pdf_action, ['documents']),
 ];
 
@@ -598,6 +598,21 @@ async function linuxHasPyAtSpi() {
   return pyAtSpiCache.value;
 }
 
+export function documentCapabilitySnapshot({
+  platform = process.platform,
+  commandExistsFn = commandExists,
+} = {}) {
+  const supportedPlatform = ['win32','darwin','linux'].includes(platform);
+  const nativeOoxml = platform === 'win32';
+  const archiveOoxml = (platform === 'darwin' || platform === 'linux')
+    && commandExistsFn('zip')
+    && commandExistsFn('unzip');
+  return {
+    documents:supportedPlatform,
+    ooxml:supportedPlatform && (nativeOoxml || archiveOoxml),
+  };
+}
+
 export async function capabilitySnapshot() {
   const win = process.platform === 'win32';
   const mac = process.platform === 'darwin';
@@ -608,6 +623,7 @@ export async function capabilitySnapshot() {
   const portalInput = wayland && waylandPortalCandidate();
   const x11Input = linux && !wayland && (commandExists('wdotool') || commandExists('xdotool'));
   const browserCdp = browserRemoteEnabled() && await browserControlAvailable(undefined, 500);
+  const documentCapabilities = documentCapabilitySnapshot();
   return {
     windows: win || mac || commandExists('wdotool') || commandExists('wmctrl') || (wayland && pyAtSpi),
     ui: win || mac || pyAtSpi,
@@ -620,7 +636,6 @@ export async function capabilitySnapshot() {
     notifications: win || mac || commandExists('notify-send'),
     browser_cdp: browserCdp,
     browser_evaluate: browserCdp && (process.env.NODE_ENV !== 'production' || ['1', 'true', 'yes', 'on'].includes(String(process.env.REMCP_BROWSER_ALLOW_EVALUATE || '').toLowerCase())),
-    documents: linux,
     services: win || mac || commandExists('systemctl'),
 
     logs: win || mac || commandExists('journalctl'),
@@ -628,7 +643,7 @@ export async function capabilitySnapshot() {
     audio: win || mac || commandExists('wpctl') || commandExists('pactl') || commandExists('amixer'),
     power: win || mac || commandExists('systemctl') || commandExists('loginctl'),
     record: recordScreenAvailable({ platform:process.platform, wayland, gnomeSupported:gnomeRecord }),
-    ooxml: linux && (commandExists('zip') && commandExists('unzip')),
+    ...documentCapabilities,
   };
 }
 

package/src/extended/documents.mjs

@@ -3,7 +3,7 @@ import process from 'node:process';
 import { randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { copyFile, link, lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
-import { readDocxText, readPdfText } from '../documents.mjs';
+import { readDocxXmlText, readPdfText } from '../documents.mjs';
 import { openDirectoryPath } from '../tools/files.mjs';
 import { resolveSafePath, text } from '../util.mjs';
 import {
@@ -353,6 +353,25 @@ async function readXlsx(filePath, args) {
   }
 }
 
+async function readDocxDocument(filePath) {
+  const dir = await tempDir('remcp-docx-read-');
+  try {
+    await extractZip(filePath, dir);
+    let xml;
+    try {
+      xml = await readFile(path.join(dir, 'word', 'document.xml'), 'utf8');
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        throw new Error('This file is not a readable .docx (word/document.xml is missing)');
+      }
+      throw error;
+    }
+    return readDocxXmlText(xml);
+  } finally {
+    await removeTemp(dir);
+  }
+}
+
 async function readPdfDocument(data) {
   try {
     return readPdfText(data);
@@ -380,10 +399,10 @@ async function readPdfDocument(data) {
 export async function readDocument(args) {
   const filePath = await resolveSafePath(args.path,'path');
   const lower = filePath.toLowerCase();
+  if (lower.endsWith('.docx')) return text(await readDocxDocument(filePath));
+  if (lower.endsWith('.xlsx')) return jsonResult(await readXlsx(filePath,args));
   const data = await readDocumentFile(filePath);
-  if (lower.endsWith('.docx')) return text(readDocxText(data));
   if (lower.endsWith('.pdf')) return text(await readPdfDocument(data));
-  if (lower.endsWith('.xlsx')) return jsonResult(await readXlsx(filePath,args));
   if (/\.(txt|md|csv|json|xml|yaml|yml)$/i.test(lower)) return text(data.toString('utf8'));
   throw new Error('read_document supports PDF, DOCX, XLSX, TXT, Markdown, CSV, JSON, XML, YAML');
 }

package/src/mcp-v2.mjs

@@ -32,6 +32,7 @@ export async function startRuntimeMcpServer({ version, instructions, onError = (
   ]);
   let activeServer = null;
   let capabilityTimer = null;
+  let capabilityPollRunning = false;
   let closed = false;
 
   const serverHandle = serveStdio(() => {
@@ -65,7 +66,8 @@ export async function startRuntimeMcpServer({ version, instructions, onError = (
 
     let lastSupported = initiallySupported;
     capabilityTimer = setInterval(async () => {
-      if (closed) return;
+      if (closed || capabilityPollRunning) return;
+      capabilityPollRunning = true;
       try {
         const next = new Set((await advertisedExtendedTools()).map(tool => tool.name));
         let changed = false;
@@ -87,6 +89,8 @@ export async function startRuntimeMcpServer({ version, instructions, onError = (
         if (changed) server.sendToolListChanged();
       } catch (error) {
         onError(error instanceof Error ? error : new Error(String(error)));
+      } finally {
+        capabilityPollRunning = false;
       }
     }, pollIntervalMs());
     capabilityTimer.unref?.();