@rho-workspace/rho 0.5.6 → 0.5.7

package/docs/FRONTEND.md

@@ -1,6 +1,6 @@
 # Browser application
 
-Updated 2026-11-01. The frontend was reset at the user's request. Previous frontend
+Updated 2026-11-07. The frontend was reset at the user's request. Previous frontend
 plans, visual specifications, Paper references and appearance rulers have been
 removed from the working repository. Git retains their history; they do not govern
 this implementation. This document describes the current application, not another
@@ -10,6 +10,19 @@ prescriptive design system. How it changes next is decided by reviewing real run
 screens do not yet show. Avoid unnecessary secondary labels and descriptions: let the
 layout do the explaining.
 
+## The Agent's view of the sending tab
+
+Each message sent from the Agent panel carries that tab's page and, in Studio,
+its workspace ID, observed layout version and replay position. The service freezes
+a bounded view summary with the message; a retry keeps that original context.
+Under a Studio message, the workspace name records where it was sent from.
+An empty workspace has no views, even when the project contains files. An Agent can
+delete that empty layout through `composition.delete` and restore it through
+`composition.undo`. Deletion removes the sidebar entry and moves an observing tab
+to another workspace, or Overview if none remains. Project files and sessions are
+separate. The [Studio context episode](STUDIO-CONTEXT-EPISODE.md) records the original
+misunderstanding, the real OpenCode run and the limits of this summary.
+
 ## Starting from the work
 
 A person needs to find a project, work on its contents, ask an Agent for help and
@@ -111,6 +124,20 @@ inspect what happened. The application gives those actions direct places:
   the reader is there, also when it is shown again or resized. Only the reader's own
   wheel, touch, keys or scroll bar take it off the end
   ([episode](SIMULATED-PROJECT-EPISODE.md#the-notebook)).
+- **Figures.** An R plot built with ggplot2 (directly or by a package on it) is drawn in the
+  cell and in the Plots view from its figure record. Pointing at a mark shows its row;
+  click, Shift/⌘-click or drag selects, Esc clears, and the rows behind the selection are
+  listed by layer. **Ask the Agent** keeps the selection and opens the Agent panel with it
+  attached to the next message; the chip's × detaches it. Marks the Agent pointed at appear
+  as an amber chip above the plot with its note, shown on the plot when the person has
+  nothing selected. A plot nothing described stays a picture; one that failed says why
+  under it ([episode](FIGURES-EPISODE.md)). A ggplot a cell saved with `ggsave` is drawn the
+  same way wherever its file is shown with the bytes the cell saved: on the answer board, in
+  the Results & figures file view and Studio's media view, and under the cell, which names
+  the file ([episode](SAVED-FIGURES-EPISODE.md)). Layers that draw the same rows count the
+  selection once. Pages drawn with base graphics and ComplexHeatmaps are drawn and selected
+  the same way; heatmap cells keep their colour while others are selected, and a selection
+  outlines them ([episode](DRAWN-FIGURES-EPISODE.md)).
 - **Two forms.** Notebook | Console switches how the same sessions read: as a notebook (above)
   or as a console, one transcript as R or Python print it at a terminal. Each cell is its code
   after the prompt (`>`/`+` in R, `>>>`/`...` in Python, a new statement at the prompt) and what
@@ -255,22 +282,33 @@ inspect what happened. The application gives those actions direct places:
   conversations. Each row names where the session started (Terminal, VS Code, Codex
   app, Script…) and whether another window has it open now, and offers Continue,
   the terminal resume command, Markdown export and the trash
-  ([session continuity](SESSION-CONTINUITY-EPISODE.md)). Agents lists the Agents
-  this service can start, with the one new conversations use, its model and folded
-  settings; an Agent not found on this computer is greyed out. Below it, one setup
-  prompt is for the person's own local MCP client. The prompt names
-  the running installation and exact existing project; the Agent configures its
-  own client. Reading or copying grants no access. Connections are listed by their
-  actual session labels, with access waiting for a call, a verified last call,
-  refusal or ended access. Copy failure leaves selectable text; request failure
+  ([session continuity](SESSION-CONTINUITY-EPISODE.md)). Agents is one list of
+  the project's Agents in one row design, whatever way each works here: the Agents
+  this service can start (a radio for new conversations, the model and folded
+  settings; one not found on this computer is greyed out), and the Agents connected
+  from their own windows. A window sits under the Agent it belongs to, named by its
+  MCP client's own name (`clientInfo`) or else by the session name the Agent chose;
+  each window shows its name, a waiting, verified, refused or ended state, what its
+  grant allows and its last call. Marks and Agent names come from the Agent icons
+  plugin, by the words of the name an Agent gave; a name it does not know shows
+  its initial. Below the list, one setup prompt is for the person's own local
+  MCP client. The prompt names the project and gives one `rho connect` command,
+  whose reply tells the Agent how to configure its own client. Reading or copying grants no
+  access. Copy failure leaves selectable text; request failure
   offers retry. ACP observations and Host activity remain under a disclosure
   ([connection episode](AGENT-CONNECT-EPISODE.md)). Conversation rows retain title,
   model, effort, messages, state, usage, cost and their files, commands and answers;
   the trash restores or deletes. Runs follow when present
   ([Agents and conversations](AGENT-PAGE-EPISODE.md)).
 - **Project settings** manages source folders and explicitly checks available tools.
+- **Work from other windows** feeds the same Graph, Console, answer board
+  and session Studio through `agent.sessions.read`. File links in a native answer are
+  reported results; current bytes are not labelled historical. A continued native session
+  is listed once. Notebook cells join its timeline by exact cell IDs in their receipts,
+  not by assuming every call on one connection belongs to that conversation. The
+  [external work episode](EXTERNAL-WORK-EPISODE.md) records the actual Harness check.
 - **Studio** shows how a conversation's work was done. The sidebar lists under Studio
-  each session started in Rho, newest first (eight, then All sessions), and then the
+  each recorded Agent session, newest first (eight, then All sessions), and then the
   person's own workspaces; the Studio bar names the one shown. A session is titled by its
   section of the project notes, else by the Agent's title, else by its first message.
   The **project notes** (`project-notes.md` at the project root) are one Markdown file
@@ -571,7 +609,11 @@ four messages through `web/agent-work.tsx`, the same step model as the panel.
 `web/agent-settings.tsx` keeps one copy of `conversation.settings.read` per tab for
 the Agents tab and the panel's settings menu (`web/settings-menu.tsx`);
 asking an Agent what it offers (`conversation.settings.check`) is always the
-person's click.
+person's click. The Agents tab adds an ACP Agent (`conversation.agents.add`) when the
+person clicks Add on one found installed, types its command, or clicks Use in Rho on an
+Agent connected from its own window whose command Rho knows; an added Agent's settings
+show its command and Remove from Rho. An Agent that offers no settings says so in the
+message box rather than offering to ask.
 Shared notes opens `project-notes.md` in the existing Documents owner. A failed work read keeps the previous
 view and offers Refresh. The cursor invalidates the read model; individual sources
 and resources retain their own versions. See the [observed loop](ACP-EPISODE.md#shared-workspace-loop).

package/docs/HEADLESS.md

@@ -40,7 +40,7 @@ The selected baseline is macOS arm64, Node 22.22.3 (engine range
 `>=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.
+there `rho.cmd` starts Rho, and Ctrl+Break on its console or `rho --stop` stops it in order.
 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
@@ -89,6 +89,17 @@ the state that named the old address is rewritten to the new one, keeping its to
 port named, never replaced. A second start on a state that is already running is
 refused with the running service's address.
 
+`rho --stop [--state-dir DIR]` (`~/Rho/state` without the flag) stops the service that
+holds that state as Ctrl+C does, from any program. On Windows no signal reaches a
+console program from another process, so an Agent that started Rho in the background
+had no orderly way to stop it ([episode](WINDOWS-SETUP-EPISODE.md)). The command leaves
+`service.stop` in the state folder, which the running launcher takes within half a
+second, then waits until the state's writer lock is free and the process that served
+it, named in `connection.json`, has ended. It prints `{"stopped":{"state":…}}`, and the
+service's own output ends with its `{"shutdown":…}` line. It exits 1 when nothing holds
+that state, or when the service there is an earlier version that never takes the
+request (after 10 s, removing it). A start removes a request no service took.
+
 `--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.
@@ -135,15 +146,52 @@ service and reports confirmation separately. Existing Hosts keep their owner.
 ### Connect your own Agent
 
 The project's **Agent → Agents** tab offers one prompt for any Agent
-that can configure and run a local stdio MCP server. `session.instructions` is a
-read-only operation for the local browser or operator: it returns the current
-Node/launcher paths and existing project ID, without credential contents. Reading
-or copying starts no Agent, grants no access and edits no client configuration.
-The Agent uses its own supported configuration mechanism; Rho needs no additional
-brand-specific form. The [connection episode](AGENT-CONNECT-EPISODE.md) records the
-actual clients checked and the limits.
+that can configure and run a local stdio MCP server. The prompt names the project
+and gives one command:
+
+```sh
+rho connect "/absolute/project folder" --as NAME
+```
+
+The Agent puts a short, stable name for itself in place of `NAME`.
+
+Each Rho started from the command line writes a note in `~/Rho/running/`: its state
+folder, address and process ID, with no credential. It removes the note when it
+stops, and a note whose process is gone is ignored. `RHO_RUNNING_DIR` moves that
+folder.
+
+Without `--state-dir`, `rho connect` asks each running Rho with a note, and the Rho
+on `~/Rho/state`, which of them holds the folder. It refuses when more than one does.
+The prompt adds `--state-dir` only for a Rho that has no note and does not use
+`~/Rho/state`, such as one started by a program rather than the CLI.
+
+When the first `rho` on the service's PATH is not this installation, or cannot run,
+the prompt starts the command with this Node and `cli.js` instead. The build marks
+`dist/cli.js` executable, so a source checkout linked onto PATH keeps working.
+
+`rho connect` finds the innermost project holding the folder, grants it to the named
+Agent and tells the Agent the rest in its reply:
 
-The running service's operator connection grants one project to a named Agent:
+- the MCP server to add, and the ready entries below;
+- to keep the entry private and out of version control;
+- to call `rho_index` and check the project ID.
+
+`--json` prints the `--grant` reply instead. The command refuses, without a grant:
+
+- a missing or placeholder name (exit 2);
+- a folder that is not a project, or a state folder no Rho has used (exit 1);
+- a folder that more than one running Rho holds (exit 1);
+- no running Rho, naming the last address it knows (exit 1).
+
+`session.instructions` is a read-only operation for the local browser or operator.
+It returns the prompt and the command, without credential contents. Reading or
+copying starts no Agent, grants no access and edits no client configuration. The
+Agent uses its own supported configuration mechanism and writes its own entry; the
+ready entries only spare it the search. The [connection episode](AGENT-CONNECT-EPISODE.md)
+records the actual clients checked and the limits.
+
+The running service's operator connection also grants one project to a named Agent
+directly, which setup prompts gave before `rho connect`:
 
 ```sh
 rho --grant /absolute/service-state/connection.json \
@@ -159,8 +207,13 @@ legacy default is `claude-code`.
 The JSON reply supplies `mcp.name`, `mcp.command` and `mcp.args` for the Agent to
 register in its own client. `rho --mcp FILE` serves that project grant on stdio with
 `rho_index`, `rho_resolve`, `rho_call` and `rho_read`. Connection files are credentials;
-keep their contents out of prompts and projects. The reply also retains the older
-`claude` command for compatibility.
+keep their contents out of prompts and projects. The reply also holds ready entries
+for the clients whose own mechanism has been used with Rho: `claude` and `codex`
+(their `mcp add` commands), `opencode` (the project's `.opencode/opencode.json` and
+the entry to merge) and `dsh` (the DeepSeek Harness profile patch and the entry to
+append). The bridge sends its MCP client's `clientInfo` name and version as
+`x-rho-client`; Rho keeps it with the grant and shows it as `client` in the
+snapshot's `agents`, ignoring anything that is not short printable text.
 
 Repeating the same grant keeps a valid credential with the same project, methods
 and profile; changing scope, expired access or stale connection data requires a
@@ -213,6 +266,26 @@ settings name one; a model without Auto runs in Accept edits with the adapter's
 Codex's adapter already opens in its own auto-review mode. ACP cancellation confirms the
 turn, not every native job.
 
+Any other Agent that speaks ACP v1 runs through the generic driver, with no adapter of its
+own. `conversation.agents.add` adds one for new conversations in every project, given its
+program (on `PATH` or a path) and arguments, such as `["hermes", "acp"]`. Rho starts it
+once in the project, as `conversation.settings.check` does: a session is opened, what the
+Agent offers is read and the session is removed; no message is sent. The Agent is kept as
+`acp:<name>` only when it answered; otherwise the reply is the Agent's error, or the last
+line it printed when it exited first. `conversation.settings.read` lists the added Agents
+(`added`) and, from `PATH`, the Agents with a known ACP command that are installed and not
+added (`installed`; Agent's `knownAcpAgents`). `conversation.agents.remove` takes one out
+of new conversations. Each conversation records the command it started with, so it
+continues with the same Agent. `--acp-command '<argv JSON>'` / `RHO_ACP_COMMAND` still
+names one ACP Agent at start (`acp`); without it, `dsh acp` is used when Harness's `acp`
+profile is installed. A Harness session in the folder continues only through Harness's own
+ACP command, named at start or added. See the [episode](AGENTS-IN-RHO-EPISODE.md).
+
+| Protected resource | Configuration and default | Exhaustion |
+| --- | --- | --- |
+| Added Agents, kept in the service's Agent settings | `conversations.maxAddedAgents` 16 | Adding another is refused until one is removed. |
+| Starting an Agent to add it | `conversations.connectTimeoutMs` 60 s; one start per command at a time | The start ends; nothing is added and the reason is returned. |
+
 For an external ACP client, select this command as that client's Agent executable:
 
 ```sh
@@ -435,6 +508,7 @@ RHO_CORE_BINARY=/absolute/rho-core npm run recovery
 RHO_CORE_BINARY=/absolute/rho-core npm run agent
 npm run pack:local -- --core darwin-arm64=/absolute/mac/rho-core \
   --core linux-x64=/absolute/linux-x64/rho-core --core linux-arm64=/absolute/linux-arm64/rho-core \
+  --core win32-x64=/absolute/win32-x64/rho-core.exe \
   --core-source /absolute/Rho-core --plugins /absolute/Rho-plugins
 node scripts/install-acceptance.mjs /absolute/rho-workspace-rho-0.5.2.tgz \
   /absolute/ordinary-project /absolute/paired-project
@@ -470,6 +544,25 @@ records source commits/trees, build-input and lock hashes, binary/package digest
 and platform, plus each selected plugin tarball identity. It does not build Core, sign or publish to a registry. Direct
 packing of the development source-linked root is rejected.
 
+Each Core is built as CI's `core` job in [`ci.yml`](../.github/workflows/ci.yml) builds it.
+Check out the Core commit that `components.json` selects with LF line endings
+(`git config --global core.autocrlf false` before cloning). Core compiles
+`docs/ACTIVITY.md` and `docs/MANAGED-RUN.md` in byte for byte, and under Git for
+Windows' default a fresh clone gave a Core whose contract text ended its lines in CRLF
+where CI's has LF. Core keeps those two files LF itself from `8ef933a`, and the packer
+records them among Core's build inputs. Then run
+`CARGO_PROFILE_DEV_DEBUG=0 cargo build --locked --target TARGET`: on Windows, TARGET is
+`x86_64-pc-windows-msvc` (MSVC Build Tools) and the binary is
+`target/x86_64-pc-windows-msvc/debug/rho-core.exe`. A Core built on another machine is
+not CI's: it names that machine's Cargo registry folder, under the builder's user
+folder, 78 times. To carry the accepted Cores instead, take CI's `core-PLATFORM`
+artifacts or the published package's `vendor/core/PLATFORM/` binaries, and add
+`--core-composition` with the composition that records them (the package's
+`vendor/composition.json`); the packer refuses a binary whose digest it does not record. On Windows, `npm ci` in Rho-plugins also
+unpacks the Agent adapters' optional platform clients (Codex 462 MiB, the Claude Agent
+SDK 284 MiB), which the package leaves out. In one run that took 14.5 of its 15
+minutes ([#112](https://github.com/YuLab-SMU/Rho/issues/112)).
+
 
 ## Native artifact intake (phase 1)
 

package/docs/THIRD-PARTY-PLUGINS.md

@@ -7,9 +7,10 @@ or becoming a base dependency. The first consumer is the optional
 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.
+Runtime package installation is included in Rho 0.5.5. User-configured remote
+markets are source functionality after 0.5.6. Build the current checkout with
+`npm run build` and use `node dist/cli.js` in place of `rho` for that new path
+until a distribution containing it is installed.
 
 ## Install and manage
 
@@ -55,6 +56,69 @@ 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.
 
+## Remote plugin markets
+
+In **Plugins → Third-party plugins → Plugin markets**, add an HTTPS JSON index.
+The plugin search above includes its titles, descriptions, package ids and
+keywords. Rho retains the index locally; opening the page, searching and listing
+do not fetch it again or install its packages. **Refresh** explicitly reads the
+source again. A failed refresh displays its error and keeps the last successful
+index available. **Remove** removes the source, keeping installed plugins and
+their recorded market keywords searchable.
+
+The [YuLab Rho index](https://raw.githubusercontent.com/YuLab-SMU/Rho/main/site/market/rho.json)
+includes Semantic figures, discoverable by `ggtree`, `clusterProfiler`, `dotplot`
+and `cnetplot`. It is an optional source; add it explicitly:
+
+```sh
+rho plugin market add https://raw.githubusercontent.com/YuLab-SMU/Rho/main/site/market/rho.json
+rho plugin market list
+rho plugin market install MARKET_ID yulab.semantic-figures
+rho plugin market refresh MARKET_ID
+rho plugin market remove MARKET_ID
+```
+
+Use the id returned by `add` or `list` for `MARKET_ID`. The ordinary
+`--connection FILE` option selects a running service. The browser and CLI use
+the same saved sources. Agents can read cached indexes with `extension.list`;
+adding, refreshing, removing sources and installing packages remain local-person
+operations through `extension.market.change` and `extension.install`.
+
+Publishers can host a static file matching the [actual index](../site/market/rho.json):
+
+```json
+{
+  "apiVersion": 1,
+  "title": "My lab's Rho plugins",
+  "plugins": [{
+    "id": "lab.my-plugin",
+    "title": "My plugin",
+    "version": "0.1.0",
+    "description": "What this plugin does",
+    "source": "@my-lab/rho-plugin@0.1.0",
+    "repository": "https://github.com/my-lab/rho-plugin",
+    "needs": "Required tools or data",
+    "keywords": ["analysis", "visualization"]
+  }]
+}
+```
+
+Each index selects one version per plugin id. `keywords` is optional; the other
+fields shown are required. Package sources use an exact npm version matching
+`version`, or `git+https://…#FULL_40_CHARACTER_COMMIT:package/path`. The package's
+actual plugin id and version must match before installation selects it. Install
+binds the source to the index digest the person selected; a changed or removed
+index refuses a stale install. The installed package records its market URL,
+title, index digest and keywords alongside its own source and runtime-tree digest.
+
+Index URLs use HTTPS without credentials, queries or fragments. Explicit loopback
+HTTP supports local development. Redirects, authenticated indexes, automatic
+refresh/update and tarball entries in markets are not supported in this pass;
+direct package installation still accepts tarballs. An index is publisher metadata,
+not a signature or proof of package validity. This Rho `apiVersion: 1` index is
+separate from the [Harness index](../site/market/index.json); the formats are not
+interchangeable. See the [observed market episode](PLUGIN-MARKETS-EPISODE.md).
+
 ## Create a package
 
 ```sh
@@ -141,6 +205,10 @@ output.textContent = receipt.state === 'completed'
   ? receipt.value.greeting : receipt.error;
 ```
 
+The frame follows the page's own height from 200 to 900 px, so let the page flow
+rather than fill the viewport; a taller page scrolls inside the frame. The page
+`create` generates shows a labelled form, a result and a failure state to start from.
+
 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
@@ -174,6 +242,8 @@ and obtained receipts, or records an unknown result after an interrupted call.
 
 | Protected resource | Default configuration |
 | --- | --- |
+| Configured market sources / entries in each index | `maxMarkets: 16`, `maxMarketEntries: 128` |
+| Each downloaded index / request duration | `maxMarketBytes: 262144`, `marketTimeoutMs: 10000` |
 | Installed selections / retained revisions | `maxPlugins: 32`, `maxVersions: 128` |
 | Admitted runtime tree | `maxFiles: 20000`, `maxPackageBytes: 134217728` |
 | Skill/view bytes | `maxContentBytes: 524288` |
@@ -181,6 +251,8 @@ and obtained receipts, or records an unknown result after an interrupted call.
 | Concurrent calls / delegated calls per invocation | `maxRunning: 4`, `maxDelegations: 32` |
 | Worker / each install subprocess | `timeoutMs: 30000`, `installTimeoutMs: 180000` |
 
+Market limits refuse an initial add or retain the previous index after a failed
+refresh. The byte limit also checks streamed responses without a Content-Length.
 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;

package/node_modules/@rho-workspace/plugin-agent/README.md

@@ -347,6 +347,11 @@ observation of the original identity, never replacement work. A refused connecti
 transport failure whose outcome is known: nothing reached the service, so the call
 returns `unavailable` naming the address and saying nothing ran (`delivered: false`).
 
+Since 0.4.31 each call also carries `x-rho-client`: the name and version the MCP
+client gave in its own `initialize` (`clientInfo`), each URL-encoded and at most 128
+characters, joined by `/`. A client that gives no name sends no header. The
+application uses it to say which Agent a connection belongs to; it grants nothing.
+
 The pure `./layered-contract` entry defines the four tool inputs and Agent note
 props. `./layered` provides the bounded complete-object cache and caller checks;
 it owns no second registry, native loop or task scheduler. Before execution it

package/node_modules/@rho-workspace/plugin-agent/dist/acp-command.d.ts

@@ -8,6 +8,37 @@ export declare function acpCommand(agent: AcpAgent): {
  * executable, else the one already named in the environment, else the client on PATH. */
 export declare function acpEnvironment(agent: AcpAgent, env: NodeJS.ProcessEnv, executable?: string): NodeJS.ProcessEnv;
 export declare function withoutSessionMarkers(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** The file a shell runs for `program`: the program itself when it names a path, else the first
+ * runnable match on PATH. On Windows a copied environment keeps the variable's own case (Path),
+ * and a program is a file with an extension PATHEXT names (claude.exe, an npm codex.cmd). */
+export declare function locate(program: string, env: NodeJS.ProcessEnv): string | null;
 /** Why the adapter could not start the person's client, or null when its executable is
  * there. The adapters report a missing client only as a closed connection. */
 export declare function missingClient(agent: AcpAgent, env: NodeJS.ProcessEnv): string | null;
+/** Agents that serve ACP through a command of their own: the program a person installs and the
+ * arguments that make it an ACP Agent, as the ACP registry (github.com/agentclientprotocol/registry,
+ * read 2026-11-07) gives them or as Rho has run them. Rho starts any of these as it starts a
+ * command the person names; the list only lets it find them. */
+export interface KnownAcpAgent {
+    id: string;
+    name: string;
+    program: string;
+    args: string[];
+}
+export declare const knownAcpAgents: KnownAcpAgent[];
+/** The known Agents installed on this computer, each with the file its command starts. Finding
+ * them reads PATH (and Harness's profile folder) and starts nothing: whether one answers as an
+ * ACP Agent is known only once it is started. */
+export declare function installedAcpAgents(env?: NodeJS.ProcessEnv): {
+    id: string;
+    name: string;
+    command: {
+        file: string;
+        args: string[];
+    };
+}[];
+/** The known Agent a command starts, when it starts one with its ACP arguments. */
+export declare function knownAcpAgent(command: {
+    file: string;
+    args: string[];
+}): KnownAcpAgent | null;

package/node_modules/@rho-workspace/plugin-agent/dist/acp-command.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 export function acpCommand(agent) {
@@ -24,17 +25,15 @@ const sessionMarkers = /^(CLAUDECODE|CLAUDE_CODE_(CHILD_SESSION|ENTRYPOINT|SESSI
 export function withoutSessionMarkers(env) {
     return Object.fromEntries(Object.entries(env).filter(([key]) => !sessionMarkers.test(key)));
 }
-/** Why the adapter could not start the person's client, or null when its executable is
- * there. The adapters report a missing client only as a closed connection. */
-export function missingClient(agent, env) {
-    const executable = env[executableVariable[agent]] || agent;
-    // On Windows a copied environment keeps the variable's own case (Path), and a client is a
-    // file with an extension PATHEXT names (claude.exe, an npm codex.cmd), as the shell finds it.
+/** The file a shell runs for `program`: the program itself when it names a path, else the first
+ * runnable match on PATH. On Windows a copied environment keeps the variable's own case (Path),
+ * and a program is a file with an extension PATHEXT names (claude.exe, an npm codex.cmd). */
+export function locate(program, env) {
     const windows = process.platform === 'win32';
     const variable = (name) => windows ? Object.entries(env).find(([key]) => key.toUpperCase() === name)?.[1] : env[name];
-    const named = executable.includes('/') || (windows && executable.includes('\\'));
-    const extensions = windows && !path.extname(executable) ? (variable('PATHEXT') ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean) : [''];
-    const candidates = (named ? [executable] : (variable('PATH') ?? '').split(path.delimiter).filter(Boolean).map(directory => path.join(directory, executable))).flatMap(file => extensions.map(extension => file + extension));
+    const named = program.includes('/') || (windows && program.includes('\\'));
+    const extensions = windows && !path.extname(program) ? (variable('PATHEXT') ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean) : [''];
+    const candidates = (named ? [program] : (variable('PATH') ?? '').split(path.delimiter).filter(Boolean).map(directory => path.join(directory, program))).flatMap(file => extensions.map(extension => file + extension));
     const runnable = (file) => { try {
         fs.accessSync(file, fs.constants.X_OK);
         return fs.statSync(file).isFile();
@@ -42,7 +41,43 @@ export function missingClient(agent, env) {
     catch {
         return false;
     } };
-    if (candidates.some(runnable))
+    return candidates.find(runnable) ?? null;
+}
+/** Why the adapter could not start the person's client, or null when its executable is
+ * there. The adapters report a missing client only as a closed connection. */
+export function missingClient(agent, env) {
+    const executable = env[executableVariable[agent]] || agent;
+    if (locate(executable, env))
         return null;
+    const named = executable.includes('/') || (process.platform === 'win32' && executable.includes('\\'));
     return `${clientName[agent]} was not found ${named ? 'at ' + executable : 'on PATH (' + executable + ')'}. Install it, or select its executable.`;
 }
+export const knownAcpAgents = [
+    // DeepSeek Harness serves ACP from its `acp` profile, installed apart from the launcher.
+    { id: 'dsh', name: 'DeepSeek Harness', program: 'dsh', args: ['acp'] },
+    { id: 'hermes', name: 'Hermes Agent', program: 'hermes', args: ['acp'] },
+    { id: 'kimi', name: 'Kimi Code', program: 'kimi', args: ['acp'] },
+    { id: 'opencode', name: 'OpenCode', program: 'opencode', args: ['acp'] },
+    { id: 'gemini', name: 'Gemini CLI', program: 'gemini', args: ['--acp'] },
+    { id: 'qwen', name: 'Qwen Code', program: 'qwen', args: ['--acp'] },
+    { id: 'goose', name: 'goose', program: 'goose', args: ['acp'] },
+    { id: 'cursor', name: 'Cursor Agent', program: 'cursor-agent', args: ['acp'] },
+    { id: 'auggie', name: 'Auggie CLI', program: 'auggie', args: ['--acp'] },
+    { id: 'codebuddy', name: 'CodeBuddy Code', program: 'codebuddy', args: ['--acp'] },
+    { id: 'droid', name: 'Factory Droid', program: 'droid', args: ['exec', '--output-format', 'acp-daemon'] },
+];
+const harnessProfile = (env) => fs.existsSync(path.join(env.DSH_HOME || path.join(os.homedir(), '.dsh'), 'profiles', 'acp', 'package.json'));
+/** The known Agents installed on this computer, each with the file its command starts. Finding
+ * them reads PATH (and Harness's profile folder) and starts nothing: whether one answers as an
+ * ACP Agent is known only once it is started. */
+export function installedAcpAgents(env = process.env) {
+    return knownAcpAgents.flatMap(agent => {
+        const file = locate(agent.program, env);
+        return file && (agent.id !== 'dsh' || harnessProfile(env)) ? [{ id: agent.id, name: agent.name, command: { file, args: agent.args } }] : [];
+    });
+}
+/** The known Agent a command starts, when it starts one with its ACP arguments. */
+export function knownAcpAgent(command) {
+    const program = path.basename(command.file).replace(/\.(exe|cmd|bat)$/i, '').toLowerCase();
+    return knownAcpAgents.find(agent => agent.program === program && agent.args.length === command.args.length && agent.args.every((arg, i) => arg === command.args[i])) ?? null;
+}

package/node_modules/@rho-workspace/plugin-agent/dist/acp-conversation.js

@@ -148,9 +148,16 @@ export class AcpConversation {
             } });
         bounded.on('error', () => { });
         child.stdout.pipe(bounded);
-        // Drain diagnostics without storing credentials, URLs or native reasoning.
-        child.stderr.on('data', (chunk) => { this.outputBytes += chunk.length; if (this.outputBytes > o.limits.maxOutputBytes)
-            overflow('output-limit'); });
+        // Drain diagnostics without storing credentials, URLs or native reasoning. Its last few
+        // kilobytes stay in memory only, to say why an Agent that exits before it answers did not
+        // start (an unknown argument, a missing sign-in); only its last line is shown, redacted.
+        let printed = '';
+        child.stderr.on('data', (chunk) => {
+            this.outputBytes += chunk.length;
+            if (this.outputBytes > o.limits.maxOutputBytes)
+                overflow('output-limit');
+            printed = (printed + chunk.toString('utf8')).slice(-4096);
+        });
         this.connection = acp.client({ name: 'rho-agent' })
             .onNotification(acp.methods.client.session.update, ({ params }) => {
             try {
@@ -239,6 +246,15 @@ export class AcpConversation {
                 ...(initialized.agentInfo ? { adapter: { name: initialized.agentInfo.name, version: initialized.agentInfo.version } } : {}), ...(model ? { model } : {}) };
             this.observationOrigin = 'live';
         }
+        catch (error) {
+            await Promise.race([this.childEnded, new Promise(resolve => setTimeout(resolve, 300))]);
+            const last = printed.replace(/\x1b\[[0-9;]*[A-Za-z]/g, '').split(/\r?\n/).map(line => line.trim()).filter(Boolean).at(-1);
+            // The process may have ended while this waited, which the type of exit does not follow.
+            const exit = this.exit;
+            if (exit && last && !this.fault)
+                throw new Error(`The Agent exited before it answered${exit.code !== null ? ' (exit ' + exit.code + ')' : ''}. It printed: ${last.slice(0, 300)}`);
+            throw error;
+        }
         finally {
             clearTimeout(timer);
         }

package/node_modules/@rho-workspace/plugin-agent/dist/external-session-contract.js

@@ -10,9 +10,10 @@ export const externalToolSchema = obj({ id: text, at: text, name: text, detail:
 export const externalTurnSchema = obj({ id: text, at: text, endedAt: text, state, prompt: text, reply: text, messages: array(obj({ at: text, text }), 200), tools: array(externalToolSchema, externalSessionLimits.maxTools), results: array(externalResultSchema, 64), omittedTools: count, omittedChars: count, where: text }, ['id', 'at', 'state', 'prompt', 'reply', 'messages', 'tools', 'results', 'omittedTools', 'omittedChars']);
 export const externalSessionSummarySchema = obj({ id: { type: 'string', pattern: '^x-[a-f0-9]{64}$' }, producer: text, sessionId: text, title: text, lastAt: text, observedAt: text, state, turns: count, sourceCursor: count, omittedTurns: count, problem: text, inputOwner: { const: 'external' },
     // Native sessions: where it was started, a live process holding it, the command that continues it in a terminal
-    // and its size. The application adds the Agent it continues with in Rho and the Rho conversation that continued it.
+    // and its size. The application adds the Agent it continues with in Rho (acp:… is an ACP Agent the person
+    // added there) and the Rho conversation that continued it.
     where: text, open: { anyOf: [{ type: 'null' }, obj({ where: text, since: text, pid: count }, ['where'])] }, resume: text, bytes: count,
-    continueWith: { enum: ['claude-acp', 'codex-acp', 'acp', null] }, conversationId: text }, ['id', 'producer', 'sessionId', 'title', 'lastAt', 'observedAt', 'state', 'turns', 'sourceCursor', 'omittedTurns']);
+    continueWith: { anyOf: [{ enum: ['claude-acp', 'codex-acp', 'acp', null] }, { type: 'string', pattern: '^acp:[a-z0-9][a-z0-9-]{0,39}$' }] }, conversationId: text }, ['id', 'producer', 'sessionId', 'title', 'lastAt', 'observedAt', 'state', 'turns', 'sourceCursor', 'omittedTurns']);
 export const externalSessionSchemas = { summary: externalSessionSummarySchema, turn: externalTurnSchema };
 export const externalSessionOperations = {
     'agent.sessions.list': { inputSchema: obj({}), outputSchema: obj({ sessions: array(externalSessionSummarySchema, 128), omitted: count }), requires: [], effect: 'read' },

package/node_modules/@rho-workspace/plugin-agent/dist/external-session.d.ts

@@ -54,7 +54,7 @@ export interface ExternalSessionSummary {
     } | null;
     resume?: string;
     bytes?: number;
-    continueWith?: 'claude-acp' | 'codex-acp' | 'acp' | null;
+    continueWith?: 'claude-acp' | 'codex-acp' | 'acp' | `acp:${string}` | null;
     conversationId?: string;
 }
 export interface ExternalSessionRecord {

package/node_modules/@rho-workspace/plugin-agent/dist/index.d.ts

@@ -1971,6 +1971,14 @@ export declare const plugin: {
         modelLoop: string;
         contextDelivery: string;
         proactivePush: string;
+        mcp: {
+            entry: string;
+            transport: string;
+            tools: {
+                name: string;
+                description: string;
+            }[];
+        };
     };
 };
 export { listExternalSessions, readExternalSession } from './external-session.js';

package/node_modules/@rho-workspace/plugin-agent/dist/index.js

@@ -1,4 +1,5 @@
 import { layeredSchemas } from './layered-contract.js';
+import { mcpEntry } from './mcp-entry.js';
 import { skillPresentation, presentation, operationPresentation } from './presentation.js';
 import { operationContracts } from './operations.js';
 import * as fs from 'node:fs/promises';
@@ -302,9 +303,9 @@ const presentationSkill = {
     ],
     verify: { command: 'npm run test:presenter', description: 'Presentation enhances display within its witness and role, and refuses business feedback or document access.' }
 };
-export const plugin = { entryVersion: '1.0', id: 'agent', package: '@rho-workspace/plugin-agent', version: '0.4.19', requires: [], capabilities: ['agent-context'], presentation,
+export const plugin = { entryVersion: '1.0', id: 'agent', package: '@rho-workspace/plugin-agent', version: '0.4.33', requires: [], capabilities: ['agent-context'], presentation,
     operations: Object.entries(operationContracts).map(([method, contract]) => ({ method, presentation: operationPresentation[method], version: '2.0', ...structuredClone(contract), requires: [...contract.requires] })),
     components: [{ id: 'rho.agent-note', version: '0.2.0', owner: 'rho-plugins.agent', bindings: {}, propsSchema: layeredSchemas.AgentNoteProps, ui: './ui', presentation: { displayName: 'Agent note', description: 'A plain presentation explanation with authenticated author and binding basis.', readOnly: true, runsCode: false } }],
     skills: [{ ...agentSkill, presentation: skillPresentation }, { ...feedbackSkill, presentation: { displayName: 'Business feedback', description: 'Reads original feedback, preserves current human edits and links an explicit reply.' } }, { ...presentationSkill, presentation: { displayName: 'Presentation', description: 'Enhances the assigned visible layout without business feedback or document access.' } }],
-    agent: { id: 'claude-code-mcp', transport: 'stdio', modelLoop: 'external-client', contextDelivery: 'pull-tool-result', proactivePush: 'unsupported' } };
+    agent: { id: 'claude-code-mcp', transport: 'stdio', modelLoop: 'external-client', contextDelivery: 'pull-tool-result', proactivePush: 'unsupported', mcp: mcpEntry } };
 export { listExternalSessions, readExternalSession } from './external-session.js';

package/node_modules/@rho-workspace/plugin-agent/dist/mcp-entry.d.ts

@@ -0,0 +1,13 @@
+export declare const mcpTools: {
+    name: string;
+    description: string;
+    inputSchema: any;
+}[];
+export declare const mcpEntry: {
+    entry: string;
+    transport: string;
+    tools: {
+        name: string;
+        description: string;
+    }[];
+};