@remcp/runtime 0.2.123 → 0.2.125

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.125 — 2026-10-01
+
+- Windows `audio` now controls the default render endpoint through the native Core Audio `IAudioEndpointVolume` interface hosted by inbox PowerShell `Add-Type`.
+- `status` returns the actual 0–100 master level and mute state; `set_volume` is absolute; `mute`/`unmute` use idempotent `SetMute(true/false)` instead of a shared toggle key.
+- Windows release CI compiles the interop definition with PowerShell 5.1 on `windows-latest`. No third-party runtime dependency is added and the 83 tool schemas are unchanged.
+
+## 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.

package/README.md

@@ -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`.
 

package/package.json

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

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/diagnostics.mjs

@@ -183,6 +183,117 @@ export async function environmentTool(args) {
   });
 }
 
+const WINDOWS_AUDIO_CORE_CSHARP = String.raw`
+using System;
+using System.Runtime.InteropServices;
+
+namespace ReMCP {
+  enum EDataFlow { eRender = 0, eCapture = 1, eAll = 2 }
+  enum ERole { eConsole = 0, eMultimedia = 1, eCommunications = 2 }
+
+  [ComImport]
+  [Guid("BCDE0395-E52F-467C-8E3D-C4579291692E")]
+  class MMDeviceEnumeratorComObject { }
+
+  [ComImport]
+  [Guid("A95664D2-9614-4F35-A746-DE8DB63617E6")]
+  [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  interface IMMDeviceEnumerator {
+    [PreserveSig] int EnumAudioEndpoints(EDataFlow dataFlow, uint stateMask, out IntPtr devices);
+    [PreserveSig] int GetDefaultAudioEndpoint(EDataFlow dataFlow, ERole role, out IMMDevice endpoint);
+  }
+
+  [ComImport]
+  [Guid("D666063F-1587-4E43-81F1-B948E807363F")]
+  [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  interface IMMDevice {
+    [PreserveSig] int Activate(ref Guid iid, uint clsCtx, IntPtr activationParams, [MarshalAs(UnmanagedType.IUnknown)] out object instance);
+  }
+
+  [ComImport]
+  [Guid("5CDF2C82-841E-4546-9722-0CF74078229A")]
+  [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  interface IAudioEndpointVolume {
+    [PreserveSig] int RegisterControlChangeNotify(IntPtr notify);
+    [PreserveSig] int UnregisterControlChangeNotify(IntPtr notify);
+    [PreserveSig] int GetChannelCount(out uint count);
+    [PreserveSig] int SetMasterVolumeLevel(float levelDb, ref Guid eventContext);
+    [PreserveSig] int SetMasterVolumeLevelScalar(float level, ref Guid eventContext);
+    [PreserveSig] int GetMasterVolumeLevel(out float levelDb);
+    [PreserveSig] int GetMasterVolumeLevelScalar(out float level);
+    [PreserveSig] int SetChannelVolumeLevel(uint channel, float levelDb, ref Guid eventContext);
+    [PreserveSig] int SetChannelVolumeLevelScalar(uint channel, float level, ref Guid eventContext);
+    [PreserveSig] int GetChannelVolumeLevel(uint channel, out float levelDb);
+    [PreserveSig] int GetChannelVolumeLevelScalar(uint channel, out float level);
+    [PreserveSig] int SetMute([MarshalAs(UnmanagedType.Bool)] bool muted, ref Guid eventContext);
+    [PreserveSig] int GetMute([MarshalAs(UnmanagedType.Bool)] out bool muted);
+    [PreserveSig] int GetVolumeStepInfo(out uint step, out uint stepCount);
+    [PreserveSig] int VolumeStepUp(ref Guid eventContext);
+    [PreserveSig] int VolumeStepDown(ref Guid eventContext);
+    [PreserveSig] int QueryHardwareSupport(out uint mask);
+    [PreserveSig] int GetVolumeRange(out float minDb, out float maxDb, out float incrementDb);
+  }
+
+  public static class WindowsAudio {
+    const uint CLSCTX_ALL = 23;
+
+    static IAudioEndpointVolume Endpoint() {
+      IMMDeviceEnumerator enumerator = (IMMDeviceEnumerator)(new MMDeviceEnumeratorComObject());
+      IMMDevice device;
+      Marshal.ThrowExceptionForHR(enumerator.GetDefaultAudioEndpoint(EDataFlow.eRender, ERole.eMultimedia, out device));
+      Guid iid = typeof(IAudioEndpointVolume).GUID;
+      object endpoint;
+      Marshal.ThrowExceptionForHR(device.Activate(ref iid, CLSCTX_ALL, IntPtr.Zero, out endpoint));
+      return (IAudioEndpointVolume)endpoint;
+    }
+
+    public static string GetStateJson() {
+      IAudioEndpointVolume endpoint = Endpoint();
+      float scalar;
+      bool muted;
+      Marshal.ThrowExceptionForHR(endpoint.GetMasterVolumeLevelScalar(out scalar));
+      Marshal.ThrowExceptionForHR(endpoint.GetMute(out muted));
+      int volume = (int)Math.Round(Math.Max(0.0f, Math.Min(1.0f, scalar)) * 100.0f, MidpointRounding.AwayFromZero);
+      return "{\"volume\":" + volume.ToString() + ",\"muted\":" + (muted ? "true" : "false") + "}";
+    }
+
+    public static void SetVolume(int volume) {
+      if (volume < 0 || volume > 100) throw new ArgumentOutOfRangeException("volume");
+      IAudioEndpointVolume endpoint = Endpoint();
+      Guid context = Guid.Empty;
+      Marshal.ThrowExceptionForHR(endpoint.SetMasterVolumeLevelScalar(volume / 100.0f, ref context));
+    }
+
+    public static void SetMuted(bool muted) {
+      IAudioEndpointVolume endpoint = Endpoint();
+      Guid context = Guid.Empty;
+      Marshal.ThrowExceptionForHR(endpoint.SetMute(muted, ref context));
+    }
+  }
+}
+`;
+
+export function windowsAudioPowerShell(action = 'status', volume = 50, { compileOnly = false } = {}) {
+  const selected = requireEnum(action, 'action', ['status','set_volume','mute','unmute']);
+  const normalizedVolume = clamp(volume, 50, 0, 100);
+  const mutation = selected === 'set_volume'
+    ? `[ReMCP.WindowsAudio]::SetVolume(${normalizedVolume})`
+    : selected === 'mute'
+      ? '[ReMCP.WindowsAudio]::SetMuted($true)'
+      : selected === 'unmute'
+        ? '[ReMCP.WindowsAudio]::SetMuted($false)'
+        : '';
+  return [
+    "$ErrorActionPreference='Stop'",
+    "$source=@'",
+    WINDOWS_AUDIO_CORE_CSHARP,
+    "'@",
+    'Add-Type -TypeDefinition $source -Language CSharp -ErrorAction Stop',
+    compileOnly ? "Write-Output 'compiled'" : mutation,
+    compileOnly ? '' : '[Console]::Out.WriteLine([ReMCP.WindowsAudio]::GetStateJson())',
+  ].filter(Boolean).join('\n');
+}
+
 export async function audioTool(args) {
   const action = requireEnum(args.action || 'status', 'action', ['status','set_volume','mute','unmute']);
   const volume = clamp(args.volume, 50, 0, 100);
@@ -196,12 +307,13 @@ export async function audioTool(args) {
   }
   if (process.platform === 'win32') {
     if (!commandExists('powershell.exe') && !process.env.SystemRoot) unavailable('Windows audio control');
-    if (action === 'status') return text('Windows master-volume status requires the CoreAudio adapter; use set_volume/mute/unmute or install a system audio helper.');
-    // Windows has no stable built-in CLI for CoreAudio; use media keys for mute/volume changes.
-    const key = action === 'mute' || action === 'unmute' ? '{VOLUME_MUTE}' : null;
-    if (key) await runPowerShell(`$w=New-Object -ComObject WScript.Shell;$w.SendKeys('${key}')`, { label:'audio control' });
-    else throw new Error('set_volume on Windows requires an installed CoreAudio helper; exact absolute volume is not exposed by a stable built-in command');
-    return text(`Audio action ${action} requested.`);
+    const { stdout } = await runPowerShell(windowsAudioPowerShell(action, volume), { label:'Windows CoreAudio control', timeout:30_000 });
+    const rendered = stdout.trim();
+    try {
+      return jsonResult(JSON.parse(rendered));
+    } catch {
+      throw new Error(`Windows CoreAudio returned an invalid state payload: ${rendered || '(empty)'}`);
+    }
   }
   if (commandExists('wpctl')) {
     if (action === 'status') return text((await runFile('wpctl', ['get-volume','@DEFAULT_AUDIO_SINK@'], { label:'audio status' })).stdout.trim());

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');
 }