@rho-workspace/rho 0.5.4 → 0.5.5

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,42 @@ 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.

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);
+}

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

@@ -0,0 +1,82 @@
+export declare const externalSessionLimits: {
+    maxSessions: number;
+    maxTurns: number;
+    maxTools: number;
+    maxRecordBytes: number;
+    maxEvents: number;
+    maxSourceBytes: number;
+    maxTextChars: number;
+    maxDetailChars: number;
+};
+export declare const externalResultSchema: {
+    type: string;
+    properties: Record<string, any>;
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare const externalToolSchema: {
+    type: string;
+    properties: Record<string, any>;
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare const externalTurnSchema: {
+    type: string;
+    properties: Record<string, any>;
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare const externalSessionSummarySchema: {
+    type: string;
+    properties: Record<string, any>;
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare const externalSessionSchemas: {
+    summary: {
+        type: string;
+        properties: Record<string, any>;
+        required: string[];
+        additionalProperties: boolean;
+    };
+    turn: {
+        type: string;
+        properties: Record<string, any>;
+        required: string[];
+        additionalProperties: boolean;
+    };
+};
+export declare const externalSessionOperations: {
+    'agent.sessions.list': {
+        inputSchema: {
+            type: string;
+            properties: Record<string, any>;
+            required: string[];
+            additionalProperties: boolean;
+        };
+        outputSchema: {
+            type: string;
+            properties: Record<string, any>;
+            required: string[];
+            additionalProperties: boolean;
+        };
+        requires: never[];
+        effect: "read";
+    };
+    'agent.sessions.read': {
+        inputSchema: {
+            type: string;
+            properties: Record<string, any>;
+            required: string[];
+            additionalProperties: boolean;
+        };
+        outputSchema: {
+            type: string;
+            properties: Record<string, any>;
+            required: string[];
+            additionalProperties: boolean;
+        };
+        requires: never[];
+        effect: "read";
+    };
+};

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

@@ -0,0 +1,15 @@
+// A retained observation of another client's conversation. It has no input operation.
+const text = { type: 'string' }, count = { type: 'integer', minimum: 0 };
+const obj = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: false });
+const array = (items, maxItems) => ({ type: 'array', items, maxItems });
+export const externalSessionLimits = { maxSessions: 64, maxTurns: 200, maxTools: 256, maxRecordBytes: 4194304, maxEvents: 32768, maxSourceBytes: 33554432, maxTextChars: 32768, maxDetailChars: 8192 };
+const state = { enum: ['running', 'completed', 'failed', 'stopped', 'unknown'] };
+export const externalResultSchema = obj({ path: text, id: text, version: text, projectId: text, toolId: text }, ['path', 'toolId']);
+export const externalToolSchema = obj({ id: text, at: text, name: text, detail: text, output: text, outcome: { enum: ['requested', 'returned', 'failed', 'unknown'] }, exitCode: { type: 'integer' }, paths: array(text, 32) }, ['id', 'at', 'name', 'detail', 'output', 'outcome', 'paths']);
+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 }, ['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' } }, ['id', 'producer', 'sessionId', 'title', 'lastAt', 'observedAt', 'state', 'turns', 'sourceCursor', 'omittedTurns', 'inputOwner']);
+export const externalSessionSchemas = { summary: externalSessionSummarySchema, turn: externalTurnSchema };
+export const externalSessionOperations = {
+    'agent.sessions.list': { inputSchema: obj({}), outputSchema: obj({ sessions: array(externalSessionSummarySchema, 64), omitted: count }), requires: [], effect: 'read' },
+    'agent.sessions.read': { inputSchema: obj({ session: { type: 'string', pattern: '^x-[a-f0-9]{64}$' }, before: count, limit: { type: 'integer', minimum: 1, maximum: 20 } }, ['session']), outputSchema: obj({ session: externalSessionSummarySchema, first: count, turns: array(externalTurnSchema, 20) }), requires: [], effect: 'read' },
+};

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

@@ -0,0 +1,73 @@
+export { externalSessionLimits } from './external-session-contract.js';
+export interface ExternalTool {
+    id: string;
+    at: string;
+    name: string;
+    detail: string;
+    output: string;
+    outcome: 'requested' | 'returned' | 'failed' | 'unknown';
+    exitCode?: number;
+    paths: string[];
+}
+export interface ExternalResult {
+    path: string;
+    toolId: string;
+    id?: string;
+    version?: string;
+    projectId?: string;
+}
+export interface ExternalTurn {
+    id: string;
+    at: string;
+    endedAt?: string;
+    state: 'running' | 'completed' | 'failed' | 'stopped' | 'unknown';
+    prompt: string;
+    reply: string;
+    messages: Array<{
+        at: string;
+        text: string;
+    }>;
+    tools: ExternalTool[];
+    results: ExternalResult[];
+    omittedTools: number;
+    omittedChars: number;
+}
+export interface ExternalSessionSummary {
+    id: string;
+    producer: string;
+    sessionId: string;
+    title: string;
+    lastAt: string;
+    observedAt: string;
+    state: ExternalTurn['state'];
+    turns: number;
+    sourceCursor: number;
+    omittedTurns: number;
+    problem?: string;
+    inputOwner: 'external';
+}
+export interface ExternalSessionRecord {
+    format: 1;
+    projectRoot: string;
+    summary: ExternalSessionSummary;
+    turns: ExternalTurn[];
+    sourceDigest: string;
+}
+export declare const externalSessionId: (producer: string, session: string) => string;
+export declare function listExternalSessions(root: string): {
+    sessions: ExternalSessionSummary[];
+    omitted: number;
+};
+export declare function readExternalSession(root: string, input: {
+    session: string;
+    before?: number;
+    limit?: number;
+}): {
+    session: ExternalSessionSummary;
+    first: number;
+    turns: ExternalTurn[];
+};
+/** Native adapters retain an observation under their existing filesystem authority.
+ * No managed execution, Agent input, grant change or runtime startup is involved. */
+export declare function saveExternalSession(root: string, value: ExternalSessionRecord, previousDigest?: string): ExternalSessionSummary;
+export declare function retainedExternalSession(root: string, producer: string, sessionId: string): ExternalSessionRecord | undefined;