@remcp/runtime 0.2.48 → 0.2.49

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.2.49 — 2026-09-20
+
+- Terminal process tools now return schema-validated structured session state, output ranges, match results and termination facts alongside their human-readable text.
+- The runtime catalog and hosted tool contract align on bounded structured outputs and accurate read-only/destructive/idempotent/open-world annotations for the expanded computer-use surface.
+- Preview references remain optional presentation metadata rather than replacing the source result used for model reasoning.
+- Lockstep patch release with the ReMCP client at `0.2.49`.
+
 ## 0.2.48 — 2026-09-20
 
 - Migrate the local stdio runtime to the official `@modelcontextprotocol/server` v2 serving entry while preserving legacy 2025-era client compatibility.
@@ -13,6 +20,7 @@
 - Added high-level `computer_snapshot` and `computer_action` primitives so agents can prefer semantic Accessibility/DOM targets and fall back to coordinates/screenshots only when necessary.
 - Chrome DevTools Protocol endpoints are restricted to loopback addresses. New filesystem/document operations continue through the existing resolved-path allowlist, and launch/service/power operations reuse the runtime command policy.
 - Fixed metadata output truncation once the JSON tool contract exceeded the operating-system pipe buffer by waiting for stdout writes to flush before exit.
+- Terminal session tools now expose schema-validated structured `pid`, status, exit information, output ranges/matches, and session lists alongside their human-readable text, so hosted agents can chain process calls without parsing prose.
 - No browser/document rendering stack was added; the runtime remains dependency-light and uses native OS facilities plus existing qpdf/poppler/zip helpers when available.
 
 ## 0.2.47 — 2026-09-19

package/README.md

@@ -49,9 +49,11 @@ support and emits `notifications/tools/list_changed` when that capability set ch
 | Diagnostics | `service`, `event_log`, `network`, `installed_apps`, `environment`, `audio`, `power_action`, `record_screen` |
 | Documents | `read_document`, `edit_spreadsheet`, `edit_document`, `pdf_action` |
 
-The hosted ReMCP endpoint adds eight account/relay tools — `list_devices`, `ping_device`,
+The hosted ReMCP endpoint adds eleven account/presentation tools — `list_devices`, `ping_device`,
 `who_am_i`, `create_pairing_command`, `get_recent_tool_calls`, `get_usage_statistics`,
-`get_configuration`, and `rename_device` — for a 91-tool release contract.
+`get_configuration`, `render_file_preview`, `render_image_preview`, `render_terminal_preview`, and
+`rename_device` — for a 94-tool MCP Apps catalog. Plain MCP clients receive 91 tools because the
+three presentation-only render tools are omitted unless the UI extension is negotiated.
 
 `computer_snapshot` and `computer_action` keep OCR inside the compact high-level surface: when a local `tesseract` binary is available, snapshot can return bounded OCR text/boxes and click targeting can fall back through Accessibility → browser DOM/CDP → OCR → coordinates. OCR is optional and never adds another MCP tool or bundled OCR dependency.
 

package/package.json

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

package/src/catalog.mjs

@@ -16,6 +16,72 @@ export const TEXT_OUTPUT_SCHEMA = {
   additionalProperties: false,
 };
 
+const NULLABLE_NUMBER_SCHEMA = { anyOf:[{ type:'number' }, { type:'null' }] };
+const NULLABLE_STRING_SCHEMA = { anyOf:[{ type:'string' }, { type:'null' }] };
+const TERMINAL_SESSION_PROPERTIES = {
+  pid:{ type:'number', description:'Process/session id used by follow-up terminal tools.' },
+  status:{ type:'string', description:'running or exited, with an exit code/signal when known.' },
+  runtimeMs:{ type:'number' },
+  lines:{ type:'number', description:'Total output lines produced by the session.' },
+  exited:{ type:'boolean' },
+  exitCode:NULLABLE_NUMBER_SCHEMA,
+  signal:NULLABLE_STRING_SCHEMA,
+};
+function terminalOutputSchema(extraProperties = {}, extraRequired = []) {
+  return {
+    type:'object',
+    properties:{ ...TERMINAL_SESSION_PROPERTIES, ...extraProperties },
+    required:['pid','status','runtimeMs','lines','exited','exitCode','signal', ...extraRequired],
+    additionalProperties:false,
+  };
+}
+const START_PROCESS_OUTPUT_SCHEMA = terminalOutputSchema({
+  command:{ type:'string' },
+  output:{ type:'string' },
+  partial:{ type:'string' },
+  warning:{ type:'string' },
+}, ['command','output']);
+const READ_PROCESS_OUTPUT_SCHEMA = terminalOutputSchema({
+  range:{ type:'string' },
+  output:{ type:'string' },
+  explicitOffset:{ type:'boolean' },
+}, ['range','output','explicitOffset']);
+const WAIT_PROCESS_OUTPUT_SCHEMA = terminalOutputSchema({
+  pattern:{ type:'string' },
+  matched:{ type:'boolean' },
+  bufferedMatch:{ type:'boolean' },
+  timeoutMs:{ type:'number' },
+  output:{ type:'string' },
+}, ['pattern','matched','bufferedMatch','timeoutMs','output']);
+const INTERACT_PROCESS_OUTPUT_SCHEMA = terminalOutputSchema({
+  output:{ type:'string' },
+}, ['output']);
+const TERMINATE_PROCESS_OUTPUT_SCHEMA = terminalOutputSchema({
+  terminated:{ type:'boolean' },
+  alreadyExited:{ type:'boolean' },
+  escalated:{ type:'boolean' },
+}, ['terminated','alreadyExited','escalated']);
+const LIST_SESSIONS_OUTPUT_SCHEMA = {
+  type:'object',
+  properties:{
+    sessions:{
+      type:'array',
+      items:{
+        type:'object',
+        properties:{
+          ...TERMINAL_SESSION_PROPERTIES,
+          blocked:{ type:'string' },
+          command:{ type:'string' },
+        },
+        required:['pid','status','runtimeMs','lines','exited','exitCode','signal','blocked','command'],
+        additionalProperties:false,
+      },
+    },
+  },
+  required:['sessions'],
+  additionalProperties:false,
+};
+
 const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 const readOnlyNonIdempotent = { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false };
 const additive = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
@@ -606,6 +672,7 @@ export const toolDefinitions = [
       additionalProperties: false,
     },
     annotations: command,
+    outputSchema: START_PROCESS_OUTPUT_SCHEMA,
     handler: terminalToolHandlers.start_process,
   },
   {
@@ -626,6 +693,7 @@ export const toolDefinitions = [
     // Reading without an explicit offset advances the session cursor, so retries can return
     // different output even after the process exits. It never modifies user files.
     annotations: readOnlyNonIdempotent,
+    outputSchema: READ_PROCESS_OUTPUT_SCHEMA,
     handler: terminalToolHandlers.read_process_output,
   },
   {
@@ -643,6 +711,7 @@ export const toolDefinitions = [
       additionalProperties: false,
     },
     annotations: command,
+    outputSchema: INTERACT_PROCESS_OUTPUT_SCHEMA,
     handler: terminalToolHandlers.interact_with_process,
   },
   {
@@ -660,6 +729,7 @@ export const toolDefinitions = [
       additionalProperties: false,
     },
     annotations: readOnlyNonIdempotent,
+    outputSchema: WAIT_PROCESS_OUTPUT_SCHEMA,
     handler: terminalToolHandlers.wait_for_process_output,
   },
   {
@@ -675,6 +745,7 @@ export const toolDefinitions = [
       additionalProperties: false,
     },
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    outputSchema: TERMINATE_PROCESS_OUTPUT_SCHEMA,
     handler: terminalToolHandlers.force_terminate,
   },
   {
@@ -683,6 +754,7 @@ export const toolDefinitions = [
     description: 'List terminal sessions started during this ReMCP runtime session with their status and how long they have been running.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     annotations: readOnly,
+    outputSchema: LIST_SESSIONS_OUTPUT_SCHEMA,
     handler: terminalToolHandlers.list_sessions,
   },
   {

package/src/tools/terminal.mjs

@@ -17,7 +17,7 @@ import {
   waitForProcessExit,
   waitForProcessActivity,
 } from '../sessions.mjs';
-import { clampInteger, fail, requireInteger, requireString, text } from '../util.mjs';
+import { clampInteger, fail, requireInteger, requireString, structured, text } from '../util.mjs';
 
 function shellCommand() {
   if (runtimeConfig.defaultShell) return runtimeConfig.defaultShell;
@@ -32,7 +32,15 @@ function shellArgs(command) {
 
 function describeSession(session) {
   const status = session.exited ? `exited${session.signal ? ` (${session.signal})` : session.exitCode === null ? '' : ` (code ${session.exitCode})`}` : 'running';
-  return { pid: session.pid, status, runtimeMs: (session.finishedAt || Date.now()) - session.startedAt, lines: totalLines(session) };
+  return {
+    pid: session.pid,
+    status,
+    runtimeMs: (session.finishedAt || Date.now()) - session.startedAt,
+    lines: totalLines(session),
+    exited: Boolean(session.exited),
+    exitCode: session.exitCode ?? null,
+    signal: session.signal ?? null,
+  };
 }
 
 function abortError() {
@@ -90,8 +98,16 @@ export async function startProcessTool(args, extra = {}) {
   const partial = session.partial;
   session.cursor = session.droppedLines + session.lines.length;
   session.lastPartialRead = session.partial || null;
-  const warning = verdict.note ? `${verdict.note}\n` : '';
-  return text(`${warning}${[headline, output, partial].filter(Boolean).join('\n')}`);
+  const warning = verdict.note ? String(verdict.note) : '';
+  const rendered = [warning, headline, output, partial].filter(Boolean).join('\n');
+  const status = describeSession(session);
+  return structured({
+    ...status,
+    command,
+    output,
+    ...(partial ? { partial } : {}),
+    ...(warning ? { warning } : {}),
+  }, rendered);
 }
 
 export async function readProcessOutputTool(args, extra = {}) {
@@ -124,7 +140,13 @@ export async function readProcessOutputTool(args, extra = {}) {
   }
   const status = describeSession(session);
   const header = `pid ${pid} ${status.status} · lines ${range}`;
-  return text(`${header}\n${slice.join('\n')}`);
+  const output = slice.join('\n');
+  return structured({
+    ...status,
+    range,
+    output,
+    explicitOffset:hasOffset,
+  }, `${header}\n${output}`);
 }
 
 function compileWaiter(pattern) {
@@ -164,7 +186,15 @@ export async function waitForProcessOutputTool(args, extra = {}) {
   const headline = matched
     ? `pid ${pid} ${status.status} · pattern matched${bufferedMatch ? ' (already buffered)' : ''}`
     : `pid ${pid} ${status.status} · pattern not matched within ${timeoutMs}ms`;
-  return text([headline, slice.join('\n')].filter(Boolean).join('\n'));
+  const output = slice.join('\n');
+  return structured({
+    ...status,
+    pattern,
+    matched,
+    bufferedMatch,
+    timeoutMs,
+    output,
+  }, [headline, output].filter(Boolean).join('\n'));
 }
 
 export async function interactWithProcessTool(args, extra = {}) {
@@ -195,34 +225,49 @@ export async function interactWithProcessTool(args, extra = {}) {
   }
   const slice = readNewOutput(session);
   const status = describeSession(session);
-  return text([`pid ${pid} ${status.status}`, slice.join('\n')].filter(Boolean).join('\n'));
+  const output = slice.join('\n');
+  return structured({
+    ...status,
+    output,
+  }, [`pid ${pid} ${status.status}`, output].filter(Boolean).join('\n'));
 }
 
 export async function forceTerminateTool(args) {
   const pid = requireInteger(args.pid, 'pid');
   const session = getProcessSession(pid);
   if (!session) fail(`No ReMCP session with pid ${pid}`);
-  if (session.exited) return text(`Process ${pid} already exited.`);
+  if (session.exited) {
+    const status = describeSession(session);
+    return structured({ ...status, terminated:false, alreadyExited:true, escalated:false }, `Process ${pid} already exited.`);
+  }
   killSessionTree(session, 'SIGTERM');
   const deadline = Date.now() + 2000;
   while (!session.exited && Date.now() < deadline) await waitForProcessActivity(session, 100);
+  let escalated = false;
   if (!session.exited) {
+    escalated = true;
     killSessionTree(session, 'SIGKILL');
     await waitForProcessActivity(session, 1000);
   }
   const status = describeSession(session);
-  return text(`Terminated session ${pid}${status.status.startsWith('exited') ? '' : ' (still running)'}. Status: ${status.status}.`);
+  return structured(
+    { ...status, terminated:Boolean(session.exited), alreadyExited:false, escalated },
+    `Terminated session ${pid}${status.status.startsWith('exited') ? '' : ' (still running)'}. Status: ${status.status}.`,
+  );
 }
 
 export async function listSessionsTool() {
   const sessions = listProcessSessions();
-  if (!sessions.length) return text('No active terminal sessions.');
-  const rows = sessions.map(session => {
+  const facts = sessions.map(session => {
     const status = describeSession(session);
     const blocked = session.exited ? '' : session.partial ? 'blocked-possibly' : 'idle-or-running';
-    return `pid ${status.pid} · ${status.status} · ${Math.round(status.runtimeMs / 1000)}s · ${blocked} · ${session.command.slice(0, 120)}`;
+    return { ...status, blocked, command:session.command.slice(0, 120) };
   });
-  return text(rows.join('\n'));
+  if (!facts.length) return structured({ sessions:[] }, 'No active terminal sessions.');
+  const rows = facts.map(session =>
+    `pid ${session.pid} · ${session.status} · ${Math.round(session.runtimeMs / 1000)}s · ${session.blocked} · ${session.command}`
+  );
+  return structured({ sessions:facts }, rows.join('\n'));
 }
 
 export const terminalToolHandlers = {