@rho-workspace/rho 0.5.4 → 0.5.6

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
@@ -132,38 +132,47 @@ 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 or Codex
+### Connect your own Agent
 
-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:
+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.
 
-```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.
-
-Without `--agent`, the same connection grants one project to one Agent session and
-prints how Claude Code starts that session's MCP server:
+The running service's operator connection grants one project to a named Agent:
 
 ```sh
-rho --grant /absolute/service-state/connection.json --project PROJECT_FOLDER [--session NAME]
+rho --grant /absolute/service-state/connection.json \
+  --project-id EXISTING_PROJECT_ID --session my-agent
 ```
 
-`--project` is the folder relative to `--root`; `--session` defaults to
-`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
-that grant on stdio with the four tools `rho_index`, `rho_resolve`, `rho_call` and
-`rho_read`; nothing else writes to stdout in that mode. Every connection file is a
-credential. `rho --help` prints the usage; an unknown option exits 2 with it.
+`--project-id` selects an already registered project, including one chosen outside
+the service's projects folder. The older `--project PROJECT_FOLDER` form remains
+available for a folder relative to `--root`; select exactly one form. Choose a
+stable session name for each Agent and reuse it on retry. Without `--session`, the
+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.
+
+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
+fresh one. A client may need to reload its tools or open a new session. A saved
+entry alone does not verify a connection: call `rho_index` in that client and check
+its project scope. The page observes grants and actual calls separately and does
+not claim that an old successful call means the Agent is online now.
+
+The existing `--agent claude-code|codex` shortcut and `session.connect` remain
+available. They use those clients' own `mcp add` commands (Claude Code in the project
+folder, Codex in user configuration). They are no longer the page's setup workflow.
+A stopped service is reported with exit 1; an unknown CLI option exits 2 with usage.
 
 Agent 0.4.11 provides persistent Claude and Codex ACP entries and retains each
 tool step's human title, ACP category and one identifying input (command, file path,
@@ -279,7 +288,8 @@ const check = await rho.call('requirements.check', {
 | `context.create/read` | Exact buffer/version/range, declared selected entities, a media rectangle with page and pixels/points, or one run (`run: {operationId}`): its state, exit, stop, the last 8 KiB of retained stderr with its byte offset and Core's truncation flag, the script reference, args and declared files. |
 | `session.grant`, `binding.open/close/list/activity` | Operator-selected method grant, external binding metadata and bounded tool receipts. Agent grants include the read-only `project.entries` and no other `project.*` method. |
 | `session.connect` | The person at this machine only: grants Claude Code or Codex access to one project and runs that Agent's own `mcp add` (`claude mcp add -s local` in the project folder, `codex mcp add`) with the project-scoped connection. A grant that still reaches this service is kept; a new one the Agent refuses is removed. Each CLI call: 20 s and 8 KiB of output, then stopped with what it printed. |
-| `conversation.start/send/stop/read/permission` | Only the browser on this machine. Original message identities, retained text/tool steps and one selected Agent session. New conversations use the selected Claude or Codex ACP connection. Cancel is confirmed by the original prompt response; lost transport keeps an unknown outcome. Reads and reconnect never replay a prompt. Native permission choices are scoped to the original pending request. Limits are in `conversationLimits` and `--limits`. |
+| `conversation.start/send/stop/read/permission` | Only the browser on this machine. Original message identities, retained text/tool steps and one selected Agent session. New conversations use the selected Claude or Codex ACP connection; `continue: {session, copy}` instead loads a session listed by `agent.sessions.list` under its own native ID, or forks it, and is refused while another process holds that session. Cancel is confirmed by the original prompt response; lost transport keeps an unknown outcome. Reads and reconnect never replay a prompt. Native permission choices are scoped to the original pending request. Limits are in `conversationLimits` and `--limits`. |
+| `agent.sessions.list/read` | Only the browser on this machine; excluded from Agent grants. Claude Code and Codex sessions in the project folder read from their own records, and observed Harness conversations, each with where it started, whether another window holds it now and its resume command. Reading starts no Agent and is bounded (`nativeSessionLimits` in the Agent plugin). |
 | `composition.put/read/apply/undo`, `view.close` | Registered entry/version, props and binding checks; `apply`/`undo` are conditional tree transactions with receipts ([Collaboration](COLLABORATION.md#composition-and-selection)). Uninstalled UI is explicitly unavailable. `rho.action` (version `1`, no bindings) is Rho's own form for one proposed action: props `{title, action, actionVersion, operationId, input, repairOf?}`, and the action must be registered at that version. |
 | `workspace.save/export/restore` | Drafts/undo, bytes/provenance, selections and composition intent; native execution is not replayed. |
 | `action.export` | One run as ordinary files in a new project folder (default `exports/<operationId>`): `script/` holds the code that ran, from the run's own record; `outputs/` holds each declared file as the run left it; `provenance.json` and `PROVENANCE.md` give the run, script digest, arguments, inputs, each file's SHA-256 and whether it matches the inventory the run wrote. A declared file that was not written, or no longer matches that inventory, is named and left out, and the export says `partial`. When the script has unsaved changes the call must say `unsaved: "include"` (written as `<name>.unsaved.<ext>`, marked as never run) or `"leave"`. Runs nothing; never writes into an existing folder. |

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.

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

@@ -390,3 +390,71 @@ fetched; an explicit response excludes replies already present in that context.
 ACP retains Codex's native MCP spelling while identifying its operation, and names
 an otherwise unnamed permission from the original tool update. These observations
 do not expand native permission or grant access to arbitrary session history.
+
+## External conversations
+
+Agent 0.4.29 exports `dsh-session` for a Harness adapter to retain a read-only
+observation of a native version-4 session. `observeDshSession(projectRoot, header,
+events)` requires the real native working folder to equal the selected project.
+It preserves session, turn and tool-call identities. Repeated cuts replace the
+same record; a changed prefix or backwards cursor is refused. It never creates
+an Agent, executes a tool, changes a grant or resumes a runtime.
+
+`external-session` supplies bounded `listExternalSessions` and
+`readExternalSession` reads. The operation contracts are `agent.sessions.list`
+and `agent.sessions.read`; an embedding application supplies authorization.
+`ui-external-session` renders prompts, visible replies, operations and results,
+with input explicitly retained by the native client. Reasoning, injected context
+and system messages are excluded; credential-shaped strings are redacted.
+This is an observation of the client's reports, not an independent execution proof.
+
+A successful resource-registration reply carries its exact resource identity and
+version. The application must verify that tuple against its own project resources.
+A native deliverable without a receipt is only a reported path, with no historical
+bytes asserted. Tool return, native exit code and turn completion remain separate.
+An unfinished turn with no observation for 10 seconds has an unknown outcome.
+
+`externalSessionLimits` names the fixed local observation budgets: 64 sessions
+per project, 200 retained turns per session, 256 tools per turn, 32,768 source
+events / 32 MiB per cut, 32,768 characters per prompt/reply and earlier-reply
+collection, 8,192 characters per tool field, and 4 MiB per stored record.
+Text/tools/earlier turns beyond their budgets are omitted with counts. An
+oversized source, conflicting cut, invalid record or busy writer retains the
+previous record and reports failure. Storage is `.rho/agent/external`, contained
+in the project without symlink directories; atomic replacement leaves readers a
+complete record. A positively dead PID lock can be reclaimed; an unknown/live
+lock cannot. Reads create no directories or runtime state. These limits protect
+local storage and observation work; they do not limit the native Agent.
+
+`test/external-session.test.mjs` checks identity, prefix conflicts, omissions,
+missing outcomes, redaction, project containment, retained failure and pagination.
+The Rho application records its separate real Harness/browser acceptance.
+
+### Native Claude Code and Codex sessions
+
+Agent 0.4.30 exports `native-sessions`. `listNativeSessions(root, nativeSources(env))`
+lists the Claude Code and Codex sessions whose recorded working folder is `root`,
+read from the Agents' own records: `CLAUDE_CONFIG_DIR` (or `~/.claude`)
+`/projects/<folder>/<id>.jsonl` and `CODEX_HOME` (or `~/.codex`)
+`/sessions/**/rollout-*.jsonl`. Each summary keeps the native session ID, title,
+times, turn counts, where it started (Claude Code's `entrypoint`, Codex's
+`originator`), whether another process holds it now (Claude Code's live
+`sessions/<pid>.json` with a running PID, Codex's `thread-writer-locks/<id>.lock`)
+and the terminal resume command. `readNativeSession` streams one record into the
+same turn shape as `readExternalSession`, with each turn's tools, results and
+reply. Reading starts no Agent, takes no lock and writes nothing.
+`nativeSessionLimits` names the budgets: 64 sessions per listing, 4,096 files
+scanned per Claude Code folder and across Codex's sessions, 256 KiB read from each end of a file for a summary, at most 256 MiB
+streamed from the end for a read, 200 turns, 256 tools per turn, and the text and
+tool field limits above. Sidechains, injected reminders and local command output
+are excluded. A recorded interruption is stopped. A last turn without an end record
+is running while its file was written in the last minute; after that it is completed
+when it has a reply and no unanswered tool, and unknown otherwise.
+
+To continue such a session, the application passes its ID as `sessionId` (ACP
+`session/load`). `forkFrom` instead asks the Agent for a separate copy through
+`session/fork`; the connection is refused before sending when the Agent does not
+advertise fork, or returns the same ID. `acpEnvironment` drops inherited Claude Code
+session markers (`CLAUDECODE`, `CLAUDE_CODE_CHILD_SESSION` and related variables):
+a Claude Code started under them saves no transcript, so its session could not be
+listed or continued anywhere else.

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

@@ -7,6 +7,7 @@ export declare function acpCommand(agent: AcpAgent): {
  * optional dependencies that an application need not install, so name the selected
  * 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;
 /** 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;

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

@@ -14,7 +14,15 @@ const clientName = { claude: 'Claude Code', codex: 'Codex' };
  * executable, else the one already named in the environment, else the client on PATH. */
 export function acpEnvironment(agent, env, executable) {
     const name = executableVariable[agent];
-    return { ...env, [name]: executable || env[name] || agent };
+    return { ...withoutSessionMarkers(env), [name]: executable || env[name] || agent };
+}
+// When Rho itself was started from inside a Claude Code session (an Agent ran the setup), the
+// environment carries that session's markers. A Claude Code started with them takes itself for
+// its child: it saves no transcript (so its session cannot be continued anywhere) and reports to
+// the parent's socket. Rho's sessions are the person's own, so those markers are not passed on.
+const sessionMarkers = /^(CLAUDECODE|CLAUDE_CODE_(CHILD_SESSION|ENTRYPOINT|SESSION_ID|SESSION_ATTENDED|MESSAGING_SOCKET|MESSAGING_TOKEN|EXECPATH|SSE_PORT)|CLAUDE_PID)$/;
+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. */

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

@@ -8,6 +8,7 @@ export interface AcpConversationOptions {
     mcpServers: AgentMcpServer[];
     limits: AgentProcessLimits;
     sessionId?: string;
+    forkFrom?: string;
     command: {
         file: string;
         args: string[];

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

@@ -211,6 +211,16 @@ export class AcpConversation {
                     throw new Error('This Agent cannot load the original session. Nothing was resent.');
                 }
             }
+            else if (o.forkFrom) {
+                const caps = initialized.agentCapabilities;
+                if (!caps?.sessionCapabilities?.fork)
+                    throw new Error('This Agent cannot continue a copy of a session. Nothing was sent.');
+                const forked = await connection.agent.request('session/fork', { ...params, sessionId: o.forkFrom });
+                if (typeof forked?.sessionId !== 'string' || forked.sessionId === o.forkFrom)
+                    throw new Error('The Agent did not create a separate copy of the session. Nothing was sent.');
+                this.sessionId = forked.sessionId;
+                this.settings = forked.configOptions ?? [];
+            }
             else {
                 const created = await connection.agent.request(acp.methods.agent.session.new, params);
                 this.sessionId = created.sessionId;

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

@@ -10,5 +10,6 @@ export interface CaptureOptions {
     maxEventBytes?: number;
 }
 export declare function canonicalActivity(value: any): string;
+export declare function activityPayload(value: any, options: CaptureOptions): any;
 export declare function normalizeClaude(records: any[], sessionId: string, project: string, options?: CaptureOptions): ObservedEvent[];
 export declare function normalizeDsh(records: any[], options?: CaptureOptions): ObservedEvent[];

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

@@ -9,7 +9,7 @@ export function canonicalActivity(value) {
 const sensitive = /(?:^|[_-])(?:authorization|cookie|password|passwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token|token)$/i;
 const hidden = /^(?:thinking|reasoning|reasoning_content|signature)$/i;
 const txt = (v) => typeof v === 'string' ? v : Array.isArray(v) ? v.filter(b => b?.type === 'text').map(b => b.text).join('\n') : '';
-function payload(value, options) {
+export function activityPayload(value, options) {
     let redacted = false, truncated = false;
     const cap = options.maxFieldBytes ?? 8192;
     const identities = new Set(['native_id', 'call_id', 'root_call_id', 'job_id', 'parent_message_id']);
@@ -76,7 +76,7 @@ function inputSummary(input) {
 function chained(items, options) {
     let prefix = hash(activityNormalizer);
     return items.map(({ kind, data }, sequence) => {
-        const safe = payload(data, options);
+        const safe = activityPayload(data, options);
         prefix = hash(prefix + canonicalActivity({ kind, data: safe }));
         return { sequence, kind, data: { ...safe, prefix_sha256: prefix } };
     });

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

@@ -0,0 +1,6 @@
+import { type ExternalSessionRecord } from './external-session.js';
+export declare function externalProjectPath(root: string, input: unknown): string | null;
+/** Project the native committed log. System prompts, injected context and reasoning
+ * are excluded. Original session, turn and call identities survive every backfill. */
+export declare function projectDshSession(root: string, header: any, events: readonly any[], observedAt?: string): ExternalSessionRecord;
+export declare function observeDshSession(root: string, header: any, events: readonly any[]): import("./external-session.js").ExternalSessionSummary;

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

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { activityPayload, canonicalActivity } from './activity-normalize.js';
+import { externalSessionId, retainedExternalSession, saveExternalSession } from './external-session.js';
+import { externalSessionLimits as limits } from './external-session-contract.js';
+const text = (v) => typeof v === 'string' ? v : Array.isArray(v) ? v.filter(b => b?.type === 'text' && typeof b.text === 'string').map(b => b.text).join('\n') : '';
+const time = (v) => { const n = typeof v === 'number' ? v : Date.parse(v); if (!Number.isFinite(n))
+    throw new Error('Native event has no valid timestamp.'); return new Date(n).toISOString(); };
+const hash = (v) => createHash('sha256').update(canonicalActivity(v)).digest('hex');
+const safe = (value, cap = limits.maxTextChars) => (activityPayload({ text: value.replace(/\b([\w-]*(?:token|cookie|authorization)["']?\s*[=:]\s*)(?:"[^"]*"|'[^']*'|[^\s'";]+)/gi, '$1[redacted]') }, { content: true, maxFieldBytes: cap * 4, maxEventBytes: cap * 8 }).text ?? '').slice(0, cap).replace(/[\uD800-\uDBFF]$/, '');
+export function externalProjectPath(root, input) {
+    if (typeof input !== 'string' || input.length > 1024 || input.includes('\0'))
+        return null;
+    const relative = path.relative(root, path.resolve(root, input)).split(path.sep).join('/');
+    return relative && !relative.startsWith('../') && !path.isAbsolute(relative) && !relative.split('/').some(p => ['..', '.rho', '.git'].includes(p)) ? relative : null;
+}
+function paths(root, args, content) {
+    const candidates = [args?.path, args?.file_path, args?.filename, args?.declaration?.path];
+    // These are explicitly labelled mentions, never inferred file writes or historical snapshots.
+    for (const m of content.matchAll(/(?<![\w/.:\-])\/?(?:[\w.\-\u0080-\uFFFF]+\/)*[\w.\-\u0080-\uFFFF]+\.(?:R|r|py|md|csv|tsv|png|svg|pdf|json|txt|qmd|Rmd)\b/g))
+        candidates.push(m[0]);
+    return [...new Set(candidates.map(p => externalProjectPath(root, p)).filter((p) => !!p))].slice(0, 32);
+}
+/** Project the native committed log. System prompts, injected context and reasoning
+ * are excluded. Original session, turn and call identities survive every backfill. */
+export function projectDshSession(root, header, events, observedAt = new Date().toISOString()) {
+    root = fs.realpathSync(root);
+    if (!header || header.version !== 4 || typeof header.id !== 'string' || !/^[A-Za-z0-9._:@-]{1,128}$/.test(header.id) || typeof header.cwd !== 'string' || fs.realpathSync(header.cwd) !== root)
+        throw new Error('Harness session does not match the selected project.');
+    if (events.length > limits.maxEvents || Buffer.byteLength(JSON.stringify(events)) > limits.maxSourceBytes)
+        throw new Error('Harness observation exceeds source limits; previous observation retained.');
+    const turns = [], byTurn = new Map(), tools = new Map();
+    let current, title = '', lastAt = time(header.createdAt), omittedTurns = 0;
+    const makeTurn = (id, at) => {
+        let t = byTurn.get(id);
+        if (t)
+            return t;
+        t = { id: 'turn:' + id, at, state: 'unknown', prompt: '', reply: '', messages: [], tools: [], results: [], omittedTools: 0, omittedChars: 0 };
+        byTurn.set(id, t);
+        turns.push(t);
+        if (turns.length > limits.maxTurns) {
+            const gone = turns.shift();
+            omittedTurns++;
+            for (const [k, v] of tools)
+                if (v.turn === gone)
+                    tools.delete(k);
+            for (const [k, v] of byTurn)
+                if (v === gone)
+                    byTurn.delete(k);
+        }
+        return t;
+    };
+    const appendText = (t, field, value, replace = false) => {
+        const full = replace ? value : t[field] + (t[field] ? '\n\n' : '') + value;
+        t[field] = safe(full);
+        t.omittedChars += Math.max(0, full.length - t[field].length);
+    };
+    for (let i = 0; i < events.length; i++) {
+        const e = events[i];
+        if (e.seq !== i)
+            throw new Error('Harness source has a missing or reordered native event.');
+        const d = e.data ?? {}, at = time(e.time);
+        lastAt = at;
+        if (e.type === 'session/title' && typeof d.title === 'string')
+            title = safe(d.title, 512);
+        if (e.type === 'turn/start') {
+            current = makeTurn(d.turn, at);
+            current.state = 'running';
+        }
+        if (e.type === 'user/message' && d.source?.kind === 'user') {
+            if (!current)
+                current = makeTurn(e.seq, at);
+            appendText(current, 'prompt', text(d.content));
+        }
+        if (e.type === 'assistant/message') {
+            const t = byTurn.get(d.turn) ?? current;
+            if (!t)
+                continue;
+            const message = text(d.message?.content);
+            if (message) {
+                if (t.reply)
+                    t.messages.push({ at, text: t.reply });
+                while (t.messages.length > 200 || t.messages.reduce((n, m) => n + m.text.length, 0) > limits.maxTextChars)
+                    t.omittedChars += t.messages.shift().text.length;
+                appendText(t, 'reply', message, true);
+            }
+        }
+        if (e.type === 'tool/call') {
+            const t = byTurn.get(d.turn) ?? current;
+            if (!t || typeof d.callId !== 'string' || typeof d.name !== 'string')
+                continue;
+            if (tools.has(d.callId))
+                throw new Error('Harness call identity was reused.');
+            if (t.tools.length >= limits.maxTools) {
+                t.omittedTools++;
+                continue;
+            }
+            let args = d.arguments;
+            if (typeof args === 'string') {
+                try {
+                    args = JSON.parse(args);
+                }
+                catch { }
+            }
+            const name = d.name === 'mcp__rho__rho_call' && typeof args?.operation === 'string' ? args.operation : d.name;
+            const input = args?.input ?? args;
+            const detail = safe(typeof input?.command === 'string' ? input.command : JSON.stringify(input) ?? '', limits.maxDetailChars);
+            const tool = { id: d.callId, at, name, detail, output: '', outcome: 'requested', paths: paths(root, input, detail) };
+            t.tools.push(tool);
+            tools.set(d.callId, { turn: t, tool });
+        }
+        if (e.type === 'tool/result') {
+            const message = d.message, item = tools.get(message?.toolCallId ?? message?.source?.callId);
+            if (!item)
+                continue;
+            const output = text(message?.content);
+            item.tool.output = safe(output, limits.maxDetailChars);
+            item.tool.outcome = message?.isError ? 'failed' : 'returned';
+            item.turn.omittedChars += Math.max(0, output.length - item.tool.output.length);
+            // Only a successful Rho registration/capture reply asserts an exact resource version.
+            if (['resource.register', 'resource.capture', 'agent.activity.capture'].includes(item.tool.name) && !message?.isError) {
+                try {
+                    const response = JSON.parse(output), r = response.value?.resource ?? response.value;
+                    const relative = externalProjectPath(root, r?.path);
+                    if (response.ok === true && relative && /^[a-f0-9]{64}$/.test(r.id) && /^[a-f0-9]{64}$/.test(r.version) && typeof r.projectId === 'string' && item.turn.results.length < 64)
+                        item.turn.results.push({ path: relative, id: r.id, version: r.version, projectId: r.projectId, toolId: item.tool.id });
+                }
+                catch { /* The bounded receipt can be incomplete; never fabricate a resource. */ }
+            }
+        }
+        if (e.type === 'job/settled') {
+            const item = tools.get(d.toolCall?.rootCallId ?? d.toolCall?.callId), exit = typeof d.detail === 'string' ? /^exit code: (-?\d+)$/.exec(d.detail) : null;
+            if (item && exit)
+                item.tool.exitCode = Number(exit[1]);
+        }
+        if (e.type === 'deliverables/presented') {
+            const t = byTurn.get(d.turn) ?? current;
+            if (!t)
+                continue;
+            for (const file of d.files ?? []) {
+                const relative = externalProjectPath(root, file.path);
+                if (relative && !t.results.some(r => r.path === relative) && t.results.length < 64)
+                    t.results.push({ path: relative, toolId: d.callId ?? 'event:' + e.seq });
+            }
+        }
+        if (e.type === 'turn/end') {
+            const t = byTurn.get(d.turn);
+            if (!t)
+                continue;
+            t.state = d.reason?.kind === 'completed' ? 'completed' : d.reason?.kind === 'cancelled' ? 'stopped' : d.reason?.kind === 'error' ? 'failed' : 'unknown';
+            t.endedAt = at;
+            for (const tool of t.tools)
+                if (tool.outcome === 'requested')
+                    tool.outcome = 'unknown';
+        }
+    }
+    const summary = { id: externalSessionId('dsh', header.id), producer: 'dsh', sessionId: header.id, title: title || turns.find(t => t.prompt)?.prompt.slice(0, 160) || 'Harness conversation', lastAt, observedAt,
+        state: turns.at(-1)?.state ?? 'unknown', turns: turns.length + omittedTurns, sourceCursor: events.length, omittedTurns, inputOwner: 'external' };
+    const result = { format: 1, projectRoot: root, summary, turns, sourceDigest: hash(events) };
+    // A suffix is retained at the record budget; gaps are explicit, earlier files stay untouched.
+    while (Buffer.byteLength(JSON.stringify(result)) > limits.maxRecordBytes && result.turns.length > 1) {
+        result.turns.shift();
+        result.summary.omittedTurns++;
+    }
+    if (Buffer.byteLength(JSON.stringify(result)) > limits.maxRecordBytes)
+        throw new Error('Harness turn exceeds maxRecordBytes; previous observation retained.');
+    return result;
+}
+export function observeDshSession(root, header, events) {
+    const old = retainedExternalSession(root, 'dsh', header.id);
+    const value = projectDshSession(root, header, events);
+    return saveExternalSession(root, value, old ? hash(events.slice(0, old.summary.sourceCursor)) : undefined);
+}