@remcp/runtime 0.2.0 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.2.3
+
+Full surface and review-aligned annotations. (0.2.0 was published from an earlier snapshot that
+carried 23 tools; 0.2.1 is the release that matches this repository.)
+
+- 37 tools: bulk reads and writes (`read_files` by glob, `write_files` for many files at once), binary transfer in both directions (`read_binary`, `write_binary`, base64 chunks),
+  archives (`create_archive`, `extract_archive` for tar, tar.gz, tar.bz2, tar.xz, zip), screenshots
+  (`take_screenshot`), `read_image`, `hash_file`, `diff_files`, `replace_lines`, `replace_in_files`,
+  `move_to_trash`, `get_system_info`, `wait_for_process_output`, runtime introspection, and a glob
+  filter on `list_directory`;
+- no approval step anywhere: writes replace by default, moves and copies replace the destination,
+  `replace_in_files` applies immediately, and `dry_run` is opt-in for callers who want a preview;
+- `dangerousCommands` defaults to `warn`: a catastrophic command runs and the result carries a note,
+  with `allow` for silence and `block` to refuse;
+- annotations say what the tools do: 19 read-only, 14 destructive (including the tools that replace a
+  destination by default), 2 open-world;
+- crash-resistance: a bad shell, a closed stdin, a stream with no newlines, a dead parent, or an
+  unparseable `runtime.json` cannot leave a device silently offline;
+- `read_process_output` offsets are documented and implemented as zero-based line numbers, ranged
+  reads no longer consume the new-output cursor, and reads never sleep over buffered data;
+- the contract commands work with no dependencies installed, so CI can diff the advertised tool
+  surface against the published tarball.
+
 ## 0.2.0
 
 First feature-complete first-party release. ReMCP no longer needs to install an upstream MCP server

package/README.md

@@ -1,8 +1,8 @@
 # ReMCP local runtime
 
 `@remcp/runtime` is the local device runtime for [ReMCP](https://remcp.delio24.com). It is an MCP
-server that runs on a computer you paired with ReMCP and executes the file, search, terminal, and
-process tools that the hosted ReMCP MCP endpoint exposes to ChatGPT and Codex.
+server that runs on a computer you paired with ReMCP and executes the file, image, search, terminal,
+and process tools that the hosted ReMCP MCP endpoint exposes to ChatGPT and Codex.
 
 The ReMCP device agent starts this runtime as a child process and talks to it over stdio. The runtime
 never talks to the network on its own: it only answers the paired agent, which holds the device
@@ -27,25 +27,52 @@ npx @remcp/runtime              # MCP server over stdio
 
 ## Tools
 
-23 tools, all implemented in this repository.
+35 tools, all implemented in this repository. Nothing is gated behind an approval step: a tool call
+executes.
 
-| Tool | Behavior |
+| Area | Tools |
 | --- | --- |
-| `read_file`, `read_multiple_files` | Read text files, with line paging and per-file errors in batch reads. |
-| `list_directory`, `get_file_info` | Inspect directory contents and file metadata. |
-| `write_file`, `edit_block` | Create, replace, or append file content; apply an exact-context text edit with a whitespace-tolerant fallback. |
-| `create_directory`, `move_file`, `copy_file` | Create directories; move, rename, or copy without overwriting an existing path unless asked. |
-| `start_search`, `get_more_search_results`, `stop_search`, `list_searches` | Streaming filename and content search with pagination, using `rg` when it is installed. |
-| `start_process`, `read_process_output`, `wait_for_process_output`, `interact_with_process`, `force_terminate`, `list_sessions` | Run and drive terminal sessions, including REPLs, with pattern waits instead of polling. |
-| `list_processes`, `kill_process` | Inspect and terminate operating-system processes. |
-| `get_runtime_info`, `get_runtime_stats` | Read-only introspection of configuration, limits, guardrails, and local counters. |
-
-There is deliberately no `set_config_value`: a model must not be able to rewrite its own device
-limits. Configuration is file- and environment-based, owned by the person at the computer.
+| Read | `read_file`, `read_multiple_files`, `read_image`, `read_binary`, `list_directory` (glob filter), `get_file_info`, `hash_file`, `diff_files` |
+| Write | `write_file`, `write_binary`, `edit_block` (whitespace-tolerant fallback, optional `dry_run`), `replace_lines`, `replace_in_files` |
+| Organise | `create_directory`, `move_file`, `copy_file`, `move_to_trash`, `create_archive`, `extract_archive` |
+| Transfer | `read_binary` / `write_binary` stream any file as base64 chunks in both directions; `create_archive` / `extract_archive` move whole trees |
+| Screen | `take_screenshot` returns the desktop as an image on Linux, macOS, and Windows |
+| Search | `start_search`, `get_more_search_results`, `stop_search`, `list_searches` |
+| Processes | `start_process`, `read_process_output`, `wait_for_process_output`, `interact_with_process`, `force_terminate`, `list_sessions`, `list_processes`, `kill_process` |
+| Introspection | `get_system_info`, `get_runtime_info`, `get_runtime_stats` |
+
+The hosted ReMCP endpoint adds `list_devices` so a model can pick a machine. Everything else the
+agent may need — service management, package installs, git, docker, `sudo` — runs through
+`start_process`, which is an unrestricted shell for the account running the agent.
+
+There is deliberately no `set_config_value` (a model must not rewrite its own device limits; use the
+file) and no `write_pdf`/spreadsheet/DOCX tooling (that is what drags Puppeteer, `sharp`, and
+`exceljs` onto your computer — use `start_process` with whatever tool you already have).
 
 `--print-tools` prints the exact JSON contract (schemas and annotations) the runtime advertises, and
 `src/catalog.mjs` is the single source of truth for it.
 
+## No approval staircase
+
+ReMCP is a remote control for computers you own, with the same trust model as SSH: the tool call runs,
+and the user's request is the authorization. There is no approval prompt, no "are you sure", and no
+dry-run detour unless you ask for one.
+
+- file writes replace by default (`mode: "append"` to add), moves and copies replace the destination
+  (`overwrite: false` refuses instead), `replace_in_files` applies immediately (`dry_run: true`
+  previews), and `move_to_trash` is there when you want an undo;
+- the destructive-command guardrail defaults to `warn`: the command runs and the result carries a note
+  when it matches the catastrophic list (`mkfs`, raw device writes, repartitioning, host power
+  control, fork bombs, recursive root deletion). `allow` removes even the note, `block` refuses
+  before running, and `blockedCommands` adds your own deny list;
+- `allowedRoots` is empty, so the device reaches everything the agent's account can reach. Set it to
+  confine a device to specific directories, enforced against the resolved real path.
+
+The guarantees that remain are about correctness rather than permission: a bad shell, a closed stdin,
+or a 40 MB line cannot take the runtime down; a crashed runtime is restarted by the agent; terminal
+sessions run in their own process group so `force_terminate` stops the whole pipeline; and a
+misconfigured `runtime.json` stops the device loudly instead of silently dropping your settings.
+
 ## Usage metrics
 
 Usage metrics are **opt-out**, matching the ReMCP client. They cover tool names, durations, outcomes,
@@ -72,25 +99,33 @@ export REMCP_RUNTIME_DISABLE_TELEMETRY=1  # environment
 
 in `~/.config/remcp/runtime.json`. `--describe` always reports the current state.
 
-## Safety model
-
-- **No network calls.** The runtime opens no sockets. Every byte it emits goes to the paired agent.
-- **Symlink-aware confinement.** `allowedRoots` is enforced against the resolved real path of the
-  deepest existing ancestor, not against the lexical string, so `<allowed>/link -> /etc` cannot be
-  used to read or write outside the allowed directories.
-- **No silent overwrites.** `move_file` fails when the destination exists; `copy_file` requires
-  `overwrite: true`; `edit_block` fails unless the number of matched blocks equals
-  `expected_replacements`.
-- **Catastrophic-command guardrail.** Commands that format filesystems, write raw block devices,
-  repartition disks, power off the host, fork-bomb, or recursively destroy a root path are refused
-  before they run (`dangerousCommands: block`, the default). `warn` runs them and reports the match;
-  `allow` disables the built-in list. User `blockedCommands` entries are always enforced.
+## Runtime properties
+
+- **No network calls of its own.** The runtime opens no sockets: every byte it emits goes to the
+  paired agent. Shell commands it runs can of course reach the network, exactly as they would from
+  your own terminal.
+- **Optional confinement.** `allowedRoots` is empty by default. When you set it, it is enforced
+  against the resolved real path of the deepest existing ancestor rather than the lexical string, so
+  `<allowed>/link -> /etc` cannot be used to read or write outside the allowed directories.
+  `allowedRoots: ["/"]` means the whole filesystem and works as written.
+- **Command guardrail.** `dangerousCommands` defaults to `warn`: a catastrophic command still runs and
+  the result carries a note. `allow` silences the note, `block` refuses before running. Rules match the
+  *command word* of each shell segment, so `grep -n format README.md` is never affected. User
+  `blockedCommands` entries are always enforced.
+- **A bad configuration is loud.** If `runtime.json` cannot be parsed, the device refuses to start and
+  says why, instead of quietly dropping your `allowedRoots` and re-enabling usage metrics.
 - **Secret masking.** `list_processes` masks command arguments that look like tokens, passwords, or
   API keys before returning them.
-- **Bounded everything.** Tool results are capped (`maxOutputBytes`), writes are capped
-  (`maxWriteBytes`), buffered session output is capped (`maxBufferedLines`), and reads are paged.
+- **Bounded everything.** Tool results are capped (`maxOutputBytes`, also clamped below the MCP
+  transport limit), writes are capped (`maxWriteBytes`), buffered session output is capped by both
+  line count and total characters - a stream with no newlines cannot grow without limit - and reads
+  are paged or chunked.
+- **Crash-resistant sessions.** A bogus shell, a closed stdin, or a dead parent cannot take the
+  runtime down; sessions run in their own process group so `force_terminate` stops a whole pipeline;
+  the agent restarts the runtime if it ever exits, so a device recovers instead of going silently
+  offline.
 - **Protected processes.** `kill_process` refuses pid 1, the runtime itself, and the ReMCP agent that
-  hosts it.
+  hosts it - the three ways a model could otherwise cut its own connection.
 
 These are guardrails, not an operating-system sandbox. A user who can run a shell can reach anything
 their account can reach; use a container, a VM, or a dedicated user account when that matters.
@@ -108,7 +143,7 @@ Optional settings live in `~/.config/remcp/runtime.json` (override the directory
   "name": "workstation",
   "allowedRoots": ["~/projects", "/srv/data"],
   "blockedCommands": ["rm -rf /", "shutdown"],
-  "dangerousCommands": "block",
+  "dangerousCommands": "warn",
   "telemetryEnabled": true,
   "maxOutputBytes": 1048576,
   "maxReadLines": 2000,
@@ -131,7 +166,9 @@ directories.
 ## Session behavior
 
 Terminal sessions and searches live in memory for the lifetime of the runtime process. They end when
-the agent restarts, and exited sessions are dropped 30 minutes after they finish.
+the agent restarts, and exited sessions are dropped 30 minutes after they finish. The agent watches
+this process and restarts it with backoff if it ever exits, so a device recovers instead of staying
+silently offline.
 
 ## Development
 
@@ -141,16 +178,34 @@ npm run check
 npm test
 ```
 
-## Relationship to other MCP servers
+The contract commands (`--help`, `--version`, `--print-tools`, `--describe`) work without
+dependencies installed, so CI can diff the advertised tool surface against the published tarball.
+
+## How it compares with Desktop Commander
 
 This runtime is an independent implementation written for ReMCP. It is not a fork of, and shares no
-code with, Desktop Commander or any other MCP server. Compared with
-[DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP) it keeps the same core
-remote-computer workflow while dropping the parts ReMCP does not want on a user's machine: 34 runtime
-dependencies (Supabase, Puppeteer/md-to-pdf, sharp, exceljs, Tiptap), the install-tracking postinstall
-script, remote feature flags and A/B tests, unredacted local tool logs, URL fetching in `read_file`,
-and `set_config_value`. What it adds is symlink-aware confinement, the catastrophic-command
-guardrail, `copy_file`, pattern waits, whitespace-tolerant edits, and read-only introspection.
+code with, [DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP) or any other
+MCP server.
+
+| | Desktop Commander 0.2.50 | ReMCP runtime 0.2.0 |
+| --- | --- | --- |
+| Tools | 26, including config mutators and document tooling | 35, including binary transfer, archives, screenshots, and diffs |
+| Runtime dependencies | 34 (Supabase, Puppeteer/md-to-pdf, `sharp`, `exceljs`, Tiptap, ripgrep download) | 1 (`@modelcontextprotocol/sdk`) |
+| Install scripts | `postinstall` posts an install payload that ignores the telemetry setting | none |
+| Telemetry | opt-out, 51 event names, remote feature flags, A/B assignment, third-party processor | opt-out, whitelisted event schema, no endpoint, no flags |
+| Install size | 3.78 MB unpacked, 249 files | ~110 kB unpacked, 20 files |
+| `read_file` | also fetches arbitrary URLs (SSRF surface) | local files only; `read_binary` transfers any file as base64 |
+| Command guardrails | always on, 32 substring-blocked commands, advisory; also refuses read-only mentions | `warn` by default (never blocks), `allow`/`block` opt-in, command-word matching |
+| Confinement | always on, checked against the lexical path | opt-in, checked against the resolved real path |
+| Local history | writes tool arguments to disk unredacted | none |
+| Images | file preview UI in a specific client | `read_image` returns the image to any MCP client |
+| Termination | session kill only | whole process group, plus runtime supervision and restart |
+
+What ReMCP deliberately does not implement, and why: document rendering (`write_pdf`) and spreadsheet
+handling would put Puppeteer, `sharp`, and `exceljs` on your computer; `get_config`/`set_config_value`
+would let the model change its own limits; local usage history would write your arguments to disk;
+URL reads in `read_file` would add an SSRF surface. Everything else the upstream server can do has an
+equivalent here, and the tool count is higher.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.0",
+  "version": "0.2.4",
   "description": "First-party ReMCP local device runtime: file, search, terminal and process tools over MCP for computers paired with ReMCP.",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/antonbaider/remcp-runtime.git"
+    "url": "git+https://github.com/antonbaider/remcp.git",
+    "directory": "packages/runtime"
   },
   "bugs": {
     "url": "https://github.com/antonbaider/remcp/issues"