@rho-workspace/rho 0.5.3 → 0.5.5

package/docs/FRONTEND.md

@@ -160,18 +160,31 @@ inspect what happened. The application gives those actions direct places:
   an ended session stay with their cells in the Notebook. With these views on the page, the
   Notebook leaves its own variables and plots out.
 - **Data flow** (`rho.flow`) shows how the values of a live session were made, as a tab beside
-  Variables (else in the right column). Each cell that made something still there is a box, in
-  the order the cells ran: its first line or purpose, the project files and folders it read, and
-  what it made one to a line (values with type and size, its plots, the files it wrote). A line
-  in the left margin runs from a value, or a written file, to each box that read it. A cell
-  that changed a value it read (`m$x <- …`) continues the cell that made it: its box says
-  "Changes what R 6 made", and what that value came from goes with it. A box that read a value
-  or file made again since says so in amber. Pointing at a box keeps its path in view and fades
-  the rest; the newest cell's box is outlined. A value opens as its own view, a file in its
-  viewer; the box's head opens its code (with the code of the cells it continues), its plots,
-  who ran it and Show in the Notebook. It follows the kernel's records (below), not the code:
-  60 values, 8 plots and 24 written files are drawn at most, and older ones are counted
-  ([episode](SIMULATED-PROJECT-EPISODE.md#data-flow-html-pages-and-object-dependent-cases)).
+  Variables (else in the right column). It is a graph of values: the project files and folders
+  the session read at the top, the results at the bottom (the files it wrote and the plots it
+  drew, else the values nothing reads), and the values between in rows. Each node is titled with
+  the meaning its `# means:` comment gives (the Agent writes these above the statement that first
+  makes the value; `# means NAME:` names one of several), with the name beneath, and shows the
+  name alone without one. A bar names the results: choosing one draws what leads to it, and the
+  first is chosen when every result at once would put more than six values in a row. Values that
+  lead to no result are named below the graph, and choosing one draws what leads to it. A chosen
+  value colors what it comes from and what comes of it; its panel gives its meaning, how and where
+  it was made, what it uses and leads to, and which results it reaches. A value can be looked at,
+  a file opened, and the cell that made it shown in the Notebook. A narrow view (under 640 px)
+  puts the chosen value above the graph. Its values come from the kernel's records (below), each
+  meaning from the code of the cell that made the value, and at most 80 values are drawn at once
+  ([episode](VARIABLE-FLOW-EPISODE.md#meaning-in-the-code)).
+- **How variables relate** ([episode](VARIABLE-FLOW-EPISODE.md)). Under each Notebook cell, what it
+  read and from which cell ("Read co from R 3"), and the later cells that read what it made ("ratio
+  read in R 6"); a cell named there goes to that cell and marks it. A cell that makes at least three
+  values offers "How its values came about", the same graph, under it. Variables names the cell that
+  made each value as it is now and the cells that read it. An R or Python script's editor has a Data
+  flow switch in its header, kept with the page: the script's flow, read from the text in the editor
+  as it is typed (nothing runs), shows beside the code, or below it in a view under 640 px. Its
+  nodes are titled by the same comments as the session's, and the flow line says how many values
+  have a meaning written in the code. The code marks the lines that make the chosen value, those it
+  comes from and those it leads to, in the colors of the key above the flow; choosing a value puts
+  the cursor on the line that makes it, and a click on a line that makes a value chooses it.
 - **Servers** (`rho.servers`) shows where the live sessions run: this machine and each place, a
   folder on one of the person's servers, reached through serverctl when serverctl manages it and
   with ssh otherwise. A place shows its server and folder, how it is reached, what its last check saw
@@ -502,8 +515,11 @@ opening a value or a server's file as a view, code waiting for the Notebook's li
 Notebook's form with the page, which views the page has, and a conversation's share of the
 sessions. Highlighting and Markdown come from the shell services (`highlight`, `markdown`).
 The plugin's `./code` finds the statement a script line runs (`statementAt`), writes the code
-that loads a table or runs a script, and makes Data flow's boxes and lanes (`lineage`);
-`web/entries/documents.tsx` sends a line through the page's `runCode` shell service.
+that loads a table or runs a script, what each cell read from which cell (`cellRelations`), and
+Data flow's graph of values from a session (`sessionGraph`) or a script's text (`scriptGraph`);
+`web/entries/documents.tsx` sends a line through the page's `runCode` shell service, draws a
+script's graph with the plugin's `ScriptFlowView`, keeps the chosen value (from the graph or the
+cursor's line, `graphNodeAt`) and marks the lines behind and in front of it (`graphMarks`).
 The HTML page view is `html.reader` from Rho-plugins (HTML 0.1.0); Rho gives it `pageFrame`, the
 service's `/frame.html` (sandboxed, with its own policy and no network; the page's policy adds
 only `frame-src 'self'`), and `fileBytes`, a file snapshot's bytes (`readFile` in `web/previews.ts`).

package/docs/HEADLESS.md

@@ -1,4 +1,4 @@
-# Rho local backend 0.5.1
+# Rho local backend
 
 Rho selects nine independent capability packages: annotations plus documents, files, R,
 requirements, tables, media, charts and Agent. Shared contracts contain generic envelopes/service ports and ordinary-file
@@ -37,23 +37,39 @@ it. Missing browser renderers do not disable the headless protocol.
 ## Install and start
 
 The selected baseline is macOS arm64, Node 22.22.3 (engine range
-`>=22.22.0 <23`), npm 10.9.8, Python 3 with `fcntl`, and Rscript 4.5.2. Windows x64
+`>=22.22.0 <27`; the suite and the installed check also passed on Node 24.22.2 and
+26.13.0), npm 10.9.8, Python 3 with `fcntl`, and Rscript 4.5.2. Windows x64
 was checked with Node 22.23.4 and Rscript 4.5.1; its writer lock needs no Python, and
 there `rho.cmd` starts Rho and Ctrl+Break on its console stops it in order.
-The unsigned local tarball contains Plugins and the selected digest-checked Core
-binary. R and any project-selected packages are external prerequisites, and so are
-the Agent clients: conversations drive the person's installed Claude Code or Codex.
+The unsigned npm package `@rho-workspace/rho` contains Plugins and one digest-checked Core
+binary for each of macOS arm64, Linux x64 and arm64 and Windows x64; CI installs it on each.
+R and any project-selected packages are external prerequisites, and so are the Agent
+clients: conversations drive the person's installed Claude Code or Codex.
 The service, documents, declared files and saved resource readers work without R.
 An unavailable Rscript returns an unknown dependency probe and prevents managed R execution.
-Other platforms and npm registry publication are unverified.
+Other platforms are unverified.
 
 ```sh
-npm install --prefix /absolute/install /absolute/rho-workspace-rho-0.5.2.tgz
-/absolute/install/node_modules/.bin/rho \
-  --root /absolute/projects --state-dir /absolute/service-state
+npm install -g @rho-workspace/rho
+rho --root /absolute/projects --state-dir /absolute/service-state
 ```
 
 Create the allowed projects directory first. Keep service state outside projects.
+
+A person who has no folders to name runs the package with no arguments instead (from
+0.5.4; 0.5.3 prints its usage and exits 2):
+
+```sh
+npx @rho-workspace/rho
+```
+
+That start uses `~/Rho/projects` and `~/Rho/state`, creates both, ships the example
+project on a new state, and prints — after the machine line — the address to open,
+the two folders, and whether the Agent client and R were found, so a missing one is
+read at startup rather than discovered later. It opens the address in a browser when
+stdout is an interactive terminal. Every flagged start keeps the output it had; no
+argument used to print this page and exit 2.
+
 Startup prints the loopback URL and private connection-file location, never the
 credential. Opening that URL in a browser on the same machine is the access: the
 service answers a same-origin request from loopback as the local person, with the
@@ -63,7 +79,17 @@ must expire; that link is a credential and is only as good as its five-minute
 window and single use. A credential that is present must still be valid, so an old
 link never silently widens to local access; a same-origin request that carries no
 credential is the machine's own. Host and Origin are checked on every request, and
-a browser request marked as coming from another site is refused. `--port`, `--rscript`, `--core`, `--plugins` and `--limits` are explicit
+a browser request marked as coming from another site is refused.
+
+A start without `--port` takes the port this state's last start had, so a bookmarked
+address and every Agent connection still reach it after a restart; only when another
+program holds that port does it take a new one, and then each Agent connection file in
+the state that named the old address is rewritten to the new one, keeping its token.
+`--port 0` always takes a new port. A selected port that is in use is refused with the
+port named, never replaced. A second start on a state that is already running is
+refused with the running service's address.
+
+`--port`, `--rscript`, `--core`, `--plugins` and `--limits` are explicit
 operator selections; `RHO_RSCRIPT`, `RHO_CORE_BINARY` and `RHO_PYTHON` select
 equivalent runtimes. A Core override is outside bundled digest verification.
 A source checkout has no bundled Core: packaging supplies one per platform under
@@ -106,17 +132,32 @@ Exact Host and supplied Origin are checked. The bearer credential is project
 scoped for external callers. CLI shutdown stops only Hosts started by this
 service and reports confirmation separately. Existing Hosts keep their owner.
 
-### Connect Claude Code
+### Connect Claude Code or Codex
+
+The running service's operator connection adds Rho to the person's own Claude Code
+or Codex for one project, as the project page's "Add to …" button does:
+
+```sh
+rho --grant /absolute/service-state/connection.json --project PROJECT_FOLDER --agent claude-code|codex
+```
+
+It gives that Agent its own grant to the project (kept when it still reaches the
+service), runs that Agent's `mcp remove` and `mcp add` on this machine — Claude Code's
+with `-s local` in the project folder, Codex's for every folder — and records it, so the
+page shows it under that Agent. The JSON reply names the project, its root, the number
+of granted methods, whether a new grant was made, and what was added (`name`, `scope`,
+`at`). A session that was already open does not have the tools; a new one does.
 
-The running service's operator connection grants one project to one Agent session
-and prints how Claude Code starts that session's MCP server:
+Without `--agent`, the same connection grants one project to one Agent session and
+prints how Claude Code starts that session's MCP server:
 
 ```sh
 rho --grant /absolute/service-state/connection.json --project PROJECT_FOLDER [--session NAME]
 ```
 
 `--project` is the folder relative to `--root`; `--session` defaults to
-`claude-code`. The JSON reply names the project, the private session connection
+`claude-code`, the session `--agent claude-code` uses, and `--session codex` is the one
+`--agent codex` uses. When the service is not running, both forms say so and exit 1. The JSON reply names the project, the private session connection
 file, the number of granted methods (the server default), an `mcp` entry
 (`name`, `command`, `args`) for an MCP configuration file, and the equivalent
 `claude mcp add rho-<folder> -- … --mcp <file>` command. `rho --mcp FILE` serves
@@ -952,6 +993,11 @@ Notebook 0.1.0 (`@rho-workspace/plugin-kernel`) keeps one live R session and one
 live Python session per project, in the project folder, shared by the person and
 their Agent. `kernel.run` queues a cell in its language's session and starts the
 session when none is live; `waitMs` waits up to `maxWaitMs` for it to end.
+Since Notebook 0.5.3 a cell may name `interpreter`, a program in a folder of the project
+such as an environment's `.venv/bin/python`; the project keeps it for that language's later
+sessions, and a session in which only that caller ran cells starts again with it, while one
+where anyone else ran a cell is refused. Each session and each cell records the program
+(relative to the project when it is in it) and the version that ran it.
 `kernel.read` returns the sessions, their variables and the cells, and never starts
 a session. `kernel.inspect` returns one value of a live session as its session
 describes it: its kind (table, model, vector, list, function, value or other), class,

package/docs/PLUGIN-AUTHORING.md

@@ -1,5 +1,9 @@
 # Build a UI extension
 
+For independently installed operations, Skills and live HTML views, use the
+[third-party plugin channel](THIRD-PARTY-PLUGINS.md). This page covers compiled
+React entries over an existing Rho capability.
+
 A UI extension is a React view over an existing Rho capability, such as Documents
 or Tables. The package owns its view; the existing capability owns data, edits and
 operations. Rho supplies tabs, splits, focus and versioned resource bindings.

package/docs/THIRD-PARTY-PLUGINS.md

@@ -0,0 +1,190 @@
+# Develop and install third-party plugins
+
+Rho can install independent npm packages while it is running. A package supplies
+operations, Skills and standalone HTML views; it does not require rebuilding Rho
+or becoming a base dependency. The first consumer is the optional
+[sclet adapter](https://github.com/YuLab-SMU/Rho-plugins/tree/main/examples/sclet-plugin).
+Its scientific implementation remains in sclet and its objects remain in the
+project's shared R session. See the [observed episode](THIRD-PARTY-PLUGINS-EPISODE.md).
+
+This is source functionality after Rho 0.5.4, not a new npm release. Build the
+current checkout with `npm run build` and use `node dist/cli.js` in place of
+`rho` until a distribution containing it is installed.
+
+## Install and manage
+
+Open a project, then **Plugins → Third-party plugins**. Install a directory entry
+or enter a package source. The installed card shows its version, source, enabled
+state and content digest. Open its view, read its guide, update, disable or remove
+it there. An invalid source or failed update leaves the previous selection intact.
+
+Only install packages you trust. Hosts run native code with the Rho process user's
+OS permissions. Disabling npm lifecycle scripts prevents install hooks; it does
+not make plugin execution a sandbox. No approval is added to already authorized
+analysis. Paired browsers and Agent connections cannot install or manage packages.
+
+The equivalent commands use the running service's private connection file:
+
+```sh
+rho plugin add /absolute/path/my-plugin
+rho plugin add /absolute/path/my-plugin-0.1.0.tgz
+rho plugin add @your-org/rho-plugin@0.1.0
+rho plugin add 'git+https://github.com/your-org/repository.git#COMMIT:packages/plugin'
+rho plugin list
+rho plugin update my-plugin
+rho plugin update my-plugin --source @your-org/rho-plugin@0.2.0
+rho plugin disable my-plugin
+rho plugin enable my-plugin
+rho plugin remove my-plugin
+```
+
+Add `--connection /absolute/service-state/connection.json` for a nondefault
+service. The default is `~/Rho/state/connection.json`. These commands do not start
+a service. Never share the connection file. Public HTTPS `.tgz` URLs are also
+accepted. Git sources require Git; package staging requires npm. Git submodules
+and build hooks are not run. Build and include runtime files before distribution.
+
+Installation stages an isolated dependency tree using npm with `--ignore-scripts`
+and `--install-links`, validates the manifest and contained files, hashes the tree,
+then atomically selects it. The source selector, resolved Git commit when present,
+package version and runtime-tree digest remain visible. Listing does not import
+plugin code. Content and calls verify the installed tree before use.
+
+Disable blocks new calls and views. Remove takes the package out of the installed
+selection. Both preserve native tasks, R sessions, project files and receipts.
+Package revisions are retained in the service's `plugins/versions` directory;
+remove is not a disk-purge command. Closing a view only releases its renderer.
+
+## Create a package
+
+```sh
+rho plugin create my-plugin --id lab.my-plugin
+rho plugin check ./my-plugin
+rho plugin dev ./my-plugin
+```
+
+`create` refuses to overwrite a directory. The generated package has a working
+greeting operation, Skill and view. `dev` installs checked snapshots on source
+changes, ignoring `.git` and `node_modules`. Reopen a view to load a new snapshot.
+Invalid edits retain the last working installation. No Rho rebuild is needed.
+
+| File | Responsibility |
+| --- | --- |
+| `package.json` | npm name/version, runtime files and `rhoPlugin: "rho-plugin.json"` |
+| `rho-plugin.json` | API version 1, unique plugin id, title, description and entries |
+| `host.mjs` | `run(operation, input, context)` over the domain's public capabilities |
+| `SKILL.md` | When/how to use the package, prerequisites, failures and result limits |
+| `view.html` | Prebuilt HTML with inline scripts/styles; may bundle a framework |
+
+Each operation declares `id`, `title`, `description`, `effect` (`read` or
+`native`), the Rho `methods` it delegates, and an object `inputSchema`. Each Skill
+or view declares `id`, `title` and a package-relative `file`. The manifest's
+`operations`, `skills` and `views` arrays are required, but may be empty. A host
+is required only when operations exist. The checker validates entry containment,
+API compatibility, identifiers, duplicate entries, schemas and entry sizes.
+
+```js
+export async function run(operation, input, context) {
+  if (operation === 'read-sessions') {
+    const value = await context.call('kernel.read', { limit: 1 });
+    return { sessions: value.sessions };
+  }
+  throw new Error('Unknown operation');
+}
+```
+
+`context.projectRoot` is the selected project, `context.invocationId` identifies
+this call, and `context.changeId(label)` supplies a stable delegated write id.
+`context.call(method, body)` validates the ordinary Rho schema, original caller's
+grant, current project and owner availability. Declare every delegated method.
+A read operation cannot delegate a mutating method. It must also keep its own
+native work read-only; native host code is trusted, not OS-confined.
+
+The host runs in a disposable child process for each call, without the service
+token. Keep long work in its actual native owner and return its handle promptly.
+For example sclet submits `kernel.run` with `waitMs: 0`, then observes the same
+cell with `kernel.read`. Do not create a second scientific state store in Rho.
+
+## Agent and view entries
+
+Agents discover installed packages through `extension.list`, read their schema
+with `extension.describe`, and read a Skill through `extension.content` with
+`kind: "skill"`. These operations are available through the existing layered MCP
+discovery. They then call:
+
+```json
+{
+  "pluginId": "lab.my-plugin",
+  "expectedDigest": "64-character digest from extension.describe",
+  "operation": "greet",
+  "input": { "name": "World" },
+  "changeId": "original-request-1"
+}
+```
+
+This is the body of `extension.call`; direct HTTP clients also supply `projectId`.
+The returned receipt separates plugin completion from the native result in
+`value`. Native invocations retain pending/completed/unknown receipts and delegated
+requests/replies. Repeat the **exact** request to observe the same receipt, even
+after update or removal. `extension.read` reads it by `invocationId` for the same
+caller/project. A restart converts pending receipts to unknown; it never replays
+them. Read-only calls do not accumulate durable receipts. No plugin receipt makes
+native work Core-managed or establishes scientific validity.
+
+A view runs in an iframe with an opaque origin, no service credential or storage
+access, and no network loading. Bundle assets inline or as data URLs. Its bridge
+is restricted to the selected package and digest:
+
+```js
+const receipt = await rho.call('greet', { name: 'World' });
+output.textContent = receipt.state === 'completed'
+  ? receipt.value.greeting : receipt.error;
+```
+
+Pass a third argument to `rho.call` to retain an explicit original changeId.
+The default generates one per deliberate call. A stale digest is refused; reopen
+the view after an update. Several views may be declared and selected in the plugin
+panel. These runtime views currently live on Plugins, not in Studio's resource
+binding/layout contract. Existing compiled React extensions still use
+[UI extension authoring](PLUGIN-AUTHORING.md).
+
+## Contribute and distribute
+
+Keep your repository, license, dependencies and release history independent. Check
+the packed artifact, not just source: `npm pack --ignore-scripts`, then install
+that tarball in a disposable Rho project. Exercise missing prerequisites, an input
+error, recovery, update and removal. Record the Rho/API version, package digest,
+native versions and actual result. Preserve user data and avoid credentials in
+examples or diagnostics. Publish to your own npm namespace or share a public Git
+source/tarball; Rho does not publish packages on your behalf.
+
+No central registration is needed to install a package. To be discoverable in the
+bundled directory, submit a PR editing
+[`src/extension-directory.ts`](../src/extension-directory.ts), linking the public
+source, license, author guide and a reproducible acceptance record. Propose an
+immutable Git commit or exact npm version. Maintainers check the declared scope;
+directory inclusion is not a security audit, release signature or scientific
+endorsement. Future releases of the package can update that entry independently.
+
+## Resource limits and current scope
+
+Use the service's `--limits` JSON file with an `extensions` object to override
+limits. Exceeding a limit refuses new work, retains the previous selected package
+and obtained receipts, or records an unknown result after an interrupted call.
+
+| Protected resource | Default configuration |
+| --- | --- |
+| Installed selections / retained revisions | `maxPlugins: 32`, `maxVersions: 128` |
+| Admitted runtime tree | `maxFiles: 20000`, `maxPackageBytes: 134217728` |
+| Skill/view bytes | `maxContentBytes: 524288` |
+| Durable invocations / receipt and result bytes | `maxReceipts: 2000`, `maxResultBytes: 1048576` |
+| Concurrent calls / delegated calls per invocation | `maxRunning: 4`, `maxDelegations: 32` |
+| Worker / each install subprocess | `timeoutMs: 30000`, `installTimeoutMs: 180000` |
+
+The tree-size check applies after npm staging; it is not a disk quota on npm/Git.
+A timed-out worker does not prove a delegated native task stopped. Observe its
+original identity. Retention limits refuse rather than silently evict identities;
+raise them deliberately when appropriate. Manifests are capped at 64 KiB, with
+32 operations and 16 entries of each content kind. The browser permits four
+pending calls per view. macOS with Node 22 is observed in this episode; Windows,
+Linux and independent developer usability have not been established for this path.