@remcp/runtime 0.2.19 → 0.2.21

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.20
+
+- `set_config_value`: a model may change this runtime’s own preferences (telemetry opt-out, read
+  and buffer line limits, result size) while it is running; the change applies immediately and is
+  saved to runtime.json. Access roots, blocked commands, the command guardrail, the shell and the
+  write limit stay with the person at this computer and are refused by the tool.
+
 ## 0.2.16
 
 - Mark cursor-consuming `read_process_output` as non-idempotent so clients do not assume retries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "description": "First-party ReMCP local device runtime: file, search, terminal and process tools over MCP for computers paired with ReMCP.",
   "type": "module",
   "license": "MIT",

package/src/catalog.mjs

@@ -3,6 +3,7 @@ import { searchToolHandlers } from './tools/search.mjs';
 import { terminalToolHandlers } from './tools/terminal.mjs';
 import { systemToolHandlers } from './tools/system.mjs';
 import { statsToolHandlers } from './tools/stats.mjs';
+import { configToolHandlers } from './tools/config.mjs';
 
 // Every tool answers with a text result (image tools add an image part as well), so the
 // declared output schema is the same shape everywhere and clients can rely on it.
@@ -25,7 +26,7 @@ export const toolDefinitions = [
   {
     name: 'read_file',
     title: 'Read file',
-    description: 'Read a text file on this computer. Use offset and length to page through large files; a negative offset reads from the end of the file.',
+    description: 'Read a file on this computer: text as text, and .docx or .pdf as their extracted document text (a scanned or font-obfuscated PDF says so instead of returning noise). Use offset and length to page through large files; a negative offset reads from the end of the file.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -737,6 +738,23 @@ export const toolDefinitions = [
     annotations: readOnly,
     handler: statsToolHandlers.get_runtime_stats,
   },
+  {
+    name: 'set_config_value',
+    title: 'Change runtime setting',
+    description: 'Change one of this runtime’s own preferences on this computer: telemetryEnabled, maxReadLines, maxBufferedLines or maxOutputBytes. The change applies immediately and is saved to runtime.json. Access roots, blocked commands, the command guardrail, the shell and the write limit cannot be set through MCP — they stay with the person at this computer.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        key: { type: 'string', description: 'telemetryEnabled (true/false), maxReadLines, maxBufferedLines or maxOutputBytes.' },
+        value: { description: 'New value: a boolean for telemetryEnabled, a number for the limits.' },
+      },
+      required: ['key', 'value'],
+      additionalProperties: false,
+    },
+    // Preference only, and the same call twice leaves the same state.
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    handler: configToolHandlers.set_config_value,
+  },
 ];
 
 export function advertisedTools() {

package/src/config.mjs

@@ -1,6 +1,6 @@
 import os from 'node:os';
 import path from 'node:path';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { expandHome } from './util.mjs';
 
 const configDir = process.env.REMCP_RUNTIME_CONFIG_DIR || path.join(os.homedir(), '.config', 'remcp');
@@ -97,6 +97,61 @@ export const runtimeConfig = Object.freeze({
   telemetryEnabled,
 });
 
+// --- settings a model may change, and nothing else ------------------------------------------------
+//
+// Desktop Commander lets a model rewrite any of its own configuration, including the directories it
+// may touch and the commands it must refuse. On ReMCP those two decide what the computer exposes, so
+// they stay with the person at the computer: `allowedRoots`, `blockedCommands`, `dangerousCommands`
+// (the command guardrail), `defaultShell`, `maxWriteBytes` and `name` are not settable from a tool.
+//
+// What is settable is a preference and two context limits — telemetry opt-out, the read and buffer
+// line limits, and the result size — all of which the person can also change in runtime.json. The
+// values apply immediately (the tool handlers read them through liveConfig) and are written back to
+// runtime.json so they survive a restart.
+const SETTABLE = Object.freeze({
+  telemetryEnabled: { type: 'boolean' },
+  maxReadLines: { type: 'integer', min: 1, max: 100_000 },
+  maxBufferedLines: { type: 'integer', min: 1, max: 1_000_000 },
+  maxOutputBytes: { type: 'integer', min: 1024, max: HARD_OUTPUT_CEILING_BYTES },
+});
+export const settableKeys = Object.freeze(Object.keys(SETTABLE));
+
+const live = new Map();
+
+// Every read of a settable value goes through here, so a change applies to the next call.
+export function liveConfig(key) {
+  return live.has(key) ? live.get(key) : runtimeConfig[key];
+}
+
+export function validateConfigValue(key, raw) {
+  const rule = SETTABLE[key];
+  if (!rule) {
+    throw new Error(`Unsupported setting: ${key || '(empty)'}. Settable here: ${settableKeys.join(', ')}. Access roots, blocked commands, the command guardrail, the shell and write limits are changed by the person at this computer.`);
+  }
+  if (rule.type === 'boolean') {
+    if (typeof raw === 'boolean') return raw;
+    if (typeof raw === 'string') return booleanValue(raw, null) ?? (() => { throw new Error(`${key} must be true or false`); })();
+    throw new Error(`${key} must be true or false`);
+  }
+  const value = Math.trunc(Number(raw));
+  if (!Number.isFinite(value)) throw new Error(`${key} must be a number`);
+  if (value < rule.min || value > rule.max) throw new Error(`${key} must be between ${rule.min} and ${rule.max}`);
+  return value;
+}
+
+export function applyLiveConfig(key, value) {
+  live.set(key, value);
+}
+
+// Writes only the changed key back, with the file mode the rest of the runtime expects.
+export function persistConfigValue(key, value) {
+  const file = readConfigFile();
+  const next = { ...file, [key]: value };
+  mkdirSync(runtimeConfigDir, { recursive: true, mode: 0o700 });
+  writeFileSync(runtimeConfigPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  return runtimeConfigPath;
+}
+
 // A configuration the user cannot read is not a configuration we should quietly ignore:
 // it is how allowedRoots and an opt-out silently disappear.
 export function configurationError() {

package/src/documents.mjs

@@ -0,0 +1,130 @@
+import { inflateRawSync, inflateSync } from 'node:zlib';
+
+// Reading PDF and DOCX without pulling a document stack into the device runtime.
+//
+// Desktop Commander installs libraries for this. ReMCP keeps its one-dependency promise and reads the
+// two formats that are actually documents with text in them:
+//
+//   DOCX - a ZIP whose word/document.xml holds the text in <w:t> elements. Inflating a stored or
+//          deflated entry is all that is needed.
+//   PDF  - objects with content streams. Text drawn with the standard encodings (Tj/TJ/'/") is
+//          extracted; a PDF that uses embedded subset fonts with custom CMaps cannot be read this
+//          way, and says so instead of returning mojibake.
+//
+// Nothing here writes, and nothing leaves the computer.
+
+const MAX_INFLATE_BYTES = 32 * 1024 * 1024;
+
+function inflate(buffer, raw = false) {
+  try {
+    const out = raw ? inflateRawSync(buffer, { maxOutputLength: MAX_INFLATE_BYTES }) : inflateSync(buffer, { maxOutputLength: MAX_INFLATE_BYTES });
+    return out;
+  } catch {
+    return null;
+  }
+}
+
+function unzipEntry(buffer, wanted) {
+  // Walk the central directory once: enough to find one entry without implementing the whole format.
+  const end = buffer.lastIndexOf(Buffer.from([0x50, 0x4b, 0x05, 0x06]));
+  if (end < 0) return null;
+  const count = buffer.readUInt16LE(end + 10);
+  let offset = buffer.readUInt32LE(end + 16);
+  for (let index = 0; index < count && offset + 46 <= buffer.length; index += 1) {
+    if (buffer.readUInt32LE(offset) !== 0x02014b50) return null;
+    const method = buffer.readUInt16LE(offset + 10);
+    const compressedSize = buffer.readUInt32LE(offset + 20);
+    const nameLength = buffer.readUInt16LE(offset + 28);
+    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);
+    if (name === wanted) {
+      const localNameLength = buffer.readUInt16LE(localOffset + 26);
+      const localExtraLength = buffer.readUInt16LE(localOffset + 28);
+      const start = localOffset + 30 + localNameLength + localExtraLength;
+      const raw = buffer.subarray(start, start + compressedSize);
+      if (method === 0) return raw;
+      if (method === 8) return inflate(raw, true);
+      return null;
+    }
+    offset += 46 + nameLength + extraLength + commentLength;
+  }
+  return null;
+}
+
+const DOCX_ENTITIES = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'" };
+
+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');
+  // Paragraph and line breaks become newlines, tabs become tabs, everything else is text.
+  const withBreaks = xml
+    .replace(/<w:(?:br|cr)\b[^>]*\/?>/g, '\n')
+    .replace(/<\/w:p>/g, '\n')
+    .replace(/<w:tab\b[^>]*\/?>/g, '\t');
+  const text = withBreaks.replace(/<[^>]+>/g, '');
+  return text
+    .replace(/&(amp|lt|gt|quot|apos);/g, match => DOCX_ENTITIES[match])
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function decodePdfString(raw) {
+  // Literal strings arrive with backslash escapes; hex strings are pairs of hex digits.
+  return raw
+    .replace(/\\([nrtbf()\\])/g, (_match, character) => ({ n: '\n', r: '\r', t: '\t', b: '\b', f: '\f' }[character] ?? character))
+    .replace(/\\([0-7]{1,3})/g, (_match, octal) => String.fromCharCode(Number.parseInt(octal, 8)));
+}
+
+export function readPdfText(buffer) {
+  const raw = buffer.toString('latin1');
+  const chunks = [];
+  let index = 0;
+  while (index < raw.length) {
+    const streamStart = raw.indexOf('stream', index);
+    if (streamStart < 0) break;
+    let start = streamStart + 'stream'.length;
+    if (raw[start] === '\r') start += 1;
+    if (raw[start] === '\n') start += 1;
+    const end = raw.indexOf('endstream', start);
+    if (end < 0) break;
+    const body = Buffer.from(raw.slice(start, end), 'latin1');
+    const decoded = body.subarray(0, 5).toString('latin1') === '<?xml' ? body : (inflate(body) ?? inflate(body, true) ?? body);
+    chunks.push(decoded.toString('latin1'));
+    index = end + 'endstream'.length;
+  }
+  const content = chunks.join('\n');
+
+  const pieces = [];
+  const showText = /(?:\((?:\\.|[^\\()])*\)|<[0-9A-Fa-f\s]+>)\s*Tj|\[((?:[^\][]|\\.)*)\]\s*TJ|\((?:\\.|[^\\()])*\)\s*['"]|T\*|Td|TD|ET/g;
+  for (const match of content.matchAll(showText)) {
+    const token = match[0];
+    if (/^T\*|Td|TD|ET$/.test(token)) { pieces.push('\n'); continue; }
+    if (token.includes('TJ')) {
+      const array = match[1] ?? '';
+      for (const part of array.matchAll(/\((?:\\.|[^\\()])*\)|<[0-9A-Fa-f\s]+>/g)) {
+        const value = part[0];
+        if (value.startsWith('(')) pieces.push(decodePdfString(value.slice(1, -1)));
+        else pieces.push(Buffer.from(value.slice(1, -1).replace(/\s+/g, ''), 'hex').toString('latin1').replace(/\0/g, ''));
+      }
+      continue;
+    }
+    if (token.startsWith('(')) pieces.push(decodePdfString(token.slice(1, token.lastIndexOf(')'))));
+    else if (token.startsWith('<')) pieces.push(Buffer.from(token.slice(1, token.indexOf('>')).replace(/\s+/g, ''), 'hex').toString('latin1').replace(/\0/g, ''));
+  }
+  const text = pieces.join('').replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
+  const printable = text.replace(/[^\p{L}\p{N}\p{P}\p{Zs}\n\t]/gu, '');
+  if (text.length < 8 || printable.length / Math.max(1, text.length) < 0.7) {
+    throw new Error('This PDF has no extractable text — it is a scan, or it uses embedded fonts the built-in reader cannot decode. Run a text extraction tool on that computer (for example pdftotext) and read the result instead.');
+  }
+  return text;
+}
+
+export function documentKind(filePath) {
+  const lower = String(filePath).toLowerCase();
+  if (lower.endsWith('.docx')) return 'docx';
+  if (lower.endsWith('.pdf')) return 'pdf';
+  return '';
+}

package/src/sessions.mjs

@@ -1,5 +1,5 @@
 import process from 'node:process';
-import { runtimeConfig } from './config.mjs';
+import { liveConfig, runtimeConfig } from './config.mjs';
 
 const processSessions = new Map();
 const searchSessions = new Map();
@@ -13,7 +13,7 @@ const MAX_PARTIAL_BYTES = 64 * 1024;
 const MAX_BUFFERED_CHARS = 8 * 1024 * 1024;
 
 function trimBuffer(session) {
-  const overflow = session.lines.length - runtimeConfig.maxBufferedLines;
+  const overflow = session.lines.length - liveConfig('maxBufferedLines');
   if (overflow > 0) {
     const removed = session.lines.splice(0, overflow);
     for (const line of removed) session.bufferedChars -= line.length;

package/src/telemetry.mjs

@@ -1,5 +1,5 @@
 import process from 'node:process';
-import { runtimeConfig } from './config.mjs';
+import { liveConfig, runtimeConfig } from './config.mjs';
 import { VERSION } from './version.mjs';
 
 // Event fields are whitelisted: an event can never carry a file path, a command
@@ -20,7 +20,7 @@ const FLUSH_INTERVAL_MS = 15_000;
 const FLUSH_THRESHOLD = 20;
 
 const state = {
-  enabled: runtimeConfig.telemetryEnabled,
+  enabled: liveConfig('telemetryEnabled'),
   buffer: [],
   sink: null,
   timer: null,
@@ -39,8 +39,10 @@ const state = {
   toolCounts: new Map(),
 };
 
+// Live: a runtime setting changed through set_config_value applies to the next call, not the next
+// restart.
 export function telemetryEnabled() {
-  return state.enabled;
+  return liveConfig('telemetryEnabled');
 }
 
 export function telemetryStatus() {
@@ -97,7 +99,7 @@ export function recordEvent(event, detail = {}) {
   if (name === 'policy_block') state.counters.policyBlocks += 1;
   if (name === 'session_started') state.counters.sessionsStarted += 1;
   if (name === 'write_denied') state.counters.writeDenials += 1;
-  if (!state.enabled) return;
+  if (!telemetryEnabled()) return;
   if (state.buffer.length >= BUFFER_LIMIT) {
     state.dropped += 1;
     return;

package/src/tools/config.mjs

@@ -0,0 +1,31 @@
+import { applyLiveConfig, liveConfig, persistConfigValue, runtimeConfig, settableKeys, validateConfigValue } from '../config.mjs';
+import { text } from '../util.mjs';
+
+// The one write into this runtime's own configuration, and a deliberately narrow one.
+//
+// Desktop Commander exposes its whole config object to the model, including the directories it may
+// touch and the commands it must refuse. Those two decide what this computer exposes, so they stay
+// with the person at the computer: only the telemetry opt-out and the read/buffer/output limits can be
+// changed here, and the change is written back to runtime.json so it survives a restart.
+export async function setConfigValueTool(args = {}) {
+  const key = String(args.key || '').trim();
+  const value = validateConfigValue(key, args.value);
+  applyLiveConfig(key, value);
+  const file = persistConfigValue(key, value);
+  return text(JSON.stringify({
+    ok: true,
+    key,
+    value,
+    applied: 'immediately',
+    savedTo: file,
+    note: `Effective now and after a restart. Settable through MCP: ${settableKeys.join(', ')}. Access roots, blocked commands, the command guardrail, the shell and the write limit stay with the person at this computer.`,
+    effective: Object.fromEntries(settableKeys.map(name => [name, liveConfig(name)])),
+  }, null, 2));
+}
+
+export const configToolHandlers = {
+  set_config_value: args => setConfigValueTool(args),
+};
+
+// Kept so a future tool can report the settable surface without duplicating the list.
+export const configSurface = Object.freeze({ settableKeys, roots: runtimeConfig.allowedRoots });

package/src/tools/files.mjs

@@ -5,7 +5,8 @@ import { createHash } from 'node:crypto';
 import { constants, createReadStream } from 'node:fs';
 import { access, chmod, chown, copyFile, cp, lstat, mkdir, open, readFile, readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
 import { pipeline } from 'node:stream/promises';
-import { runtimeConfig } from '../config.mjs';
+import { liveConfig, runtimeConfig } from '../config.mjs';
+import { documentKind, readDocxText, readPdfText } from '../documents.mjs';
 import { diffStats, unifiedDiff } from '../diff.mjs';
 import { applyHunks, parseUnifiedDiff } from '../patch.mjs';
 import { countEvent, recordEvent } from '../telemetry.mjs';
@@ -94,10 +95,29 @@ async function readTextFile(absolute) {
 
 export async function readFileTool(args) {
   const absolute = await resolveSafePath(args.path);
+  // Documents first: a .docx or .pdf is not text, and the binary guard below would refuse it.
+  const kind = documentKind(absolute);
+  if (kind) {
+    const info = await stat(absolute);
+    assertRegularFile(info, absolute);
+    if (info.size > MAX_INLINE_FILE_BYTES) fail(`File is too large to read inline (${info.size} bytes)`);
+    const buffer = await readFile(absolute);
+    const extracted = kind === 'docx' ? readDocxText(buffer) : readPdfText(buffer);
+    const documentLines = splitLines(extracted);
+    const offset = Number.isFinite(Number(args.offset)) ? Math.trunc(Number(args.offset)) : 0;
+    const length = clampInteger(args.length, liveConfig('maxReadLines'), 1, 10000);
+    const page = pageLines(documentLines, offset, length);
+    const label = kind === 'docx' ? 'Word document' : 'PDF text';
+    const header = documentLines.length
+      ? `${displayPath(absolute)} (${label}, lines ${page.start + 1}-${page.end} of ${documentLines.length})`
+      : `${displayPath(absolute)} (${label}, no text)`;
+    return text(`${header}
+${page.slice.join('\n')}`);
+  }
   const { content, encoding, eol } = await readTextFile(absolute);
   const lines = splitLines(content);
   const offset = Number.isFinite(Number(args.offset)) ? Math.trunc(Number(args.offset)) : 0;
-  const length = clampInteger(args.length, runtimeConfig.maxReadLines, 1, 10000);
+  const length = clampInteger(args.length, liveConfig('maxReadLines'), 1, 10000);
   const { start, end, slice } = pageLines(lines, offset, length);
   const notes = `${encoding === 'utf8' ? '' : ` ${encoding}`}${eol === '\r\n' ? ' CRLF' : ''}`;
   const header = lines.length
@@ -121,7 +141,7 @@ export async function readMultipleFilesTool(args) {
     try {
       const { content } = await readTextFile(absolute);
       const lines = splitLines(content);
-      const limit = runtimeConfig.maxReadLines;
+      const limit = liveConfig('maxReadLines');
       const slice = lines.slice(0, limit);
       const suffix = lines.length > limit ? `\n… ${lines.length - limit} more lines truncated` : '';
       sections.push(`${displayPath(absolute)}:\n${slice.join('\n')}${suffix}`);
@@ -506,7 +526,7 @@ export async function readFilesTool(args) {
   const root = await resolveSafePath(args.path || '.');
   const pattern = typeof args.pattern === 'string' && args.pattern.trim() ? args.pattern.trim() : '**/*';
   const maxFiles = clampInteger(args.max_files, 100, 1, 500);
-  const maxLinesPerFile = clampInteger(args.max_lines_per_file, runtimeConfig.maxReadLines, 1, 20000);
+  const maxLinesPerFile = clampInteger(args.max_lines_per_file, liveConfig('maxReadLines'), 1, 20000);
   const includeIgnored = args.include_ignored === true;
   const matcher = globToRegExp(pattern);
   const rootInfo = await stat(root).catch(() => null);

package/src/tools/stats.mjs

@@ -1,5 +1,5 @@
 import process from 'node:process';
-import { describeConfig, runtimeConfig } from '../config.mjs';
+import { describeConfig, liveConfig, runtimeConfig } from '../config.mjs';
 import { dangerousPatternIds } from '../policy.mjs';
 import { listProcessSessions, listSearchSessions } from '../sessions.mjs';
 import { telemetryStatus } from '../telemetry.mjs';
@@ -29,9 +29,9 @@ export async function getRuntimeInfoTool() {
       remoteFeatureFlags: telemetry.remoteFeatureFlags,
     },
     limits: {
-      maxOutputBytes: runtimeConfig.maxOutputBytes,
-      maxReadLines: runtimeConfig.maxReadLines,
-      maxBufferedLines: runtimeConfig.maxBufferedLines,
+      maxOutputBytes: liveConfig('maxOutputBytes'),
+      maxReadLines: liveConfig('maxReadLines'),
+      maxBufferedLines: liveConfig('maxBufferedLines'),
       maxWriteBytes: runtimeConfig.maxWriteBytes,
       maxConcurrentConnections: 1,
     },

package/src/util.mjs

@@ -1,7 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { realpath } from 'node:fs/promises';
-import { runtimeConfig } from './config.mjs';
+import { liveConfig, runtimeConfig } from './config.mjs';
 
 export class ToolError extends Error {}
 
@@ -111,7 +111,7 @@ function frameBytes(text) {
 }
 
 export function truncate(text, maxBytes) {
-  const limit = maxBytes || runtimeConfig.maxOutputBytes;
+  const limit = maxBytes || liveConfig('maxOutputBytes');
   const value = String(text);
   if (Buffer.byteLength(value, 'utf8') <= limit && frameBytes(value) <= limit) return value;
   // Shrink until the escaped frame fits, so the escaped size is what the caller gets is bounded.
@@ -191,7 +191,7 @@ export function pageLines(lines, offset, length) {
     return { start: total - count, end: total, slice: lines.slice(total - count) };
   }
   const start = Math.min(requested, total);
-  const end = Math.min(start + Math.max(1, Math.trunc(length || runtimeConfig.maxReadLines)), total);
+  const end = Math.min(start + Math.max(1, Math.trunc(length || liveConfig('maxReadLines'))), total);
   return { start, end, slice: lines.slice(start, end) };
 }