@rho-workspace/rho 0.5.3 → 0.5.4

package/dist/conversations.js

@@ -1,7 +1,7 @@
 import { projectPath, commandFiles, buildWorkGraph } from './work-graph.js';
 import { notesInstructions, projectNotesPath } from './project-notes.js';
 import { addSpend, describeLimits, describable, fileFacts, figureContext, raster } from './file-describer.js';
-import { agentTurnLimit, toolActivity } from './conversation-presentation.js';
+import { agentTurnLimit, displayCommand, toolActivity } from './conversation-presentation.js';
 import { privateEvidencePath } from './evidence-capture.js';
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
@@ -127,7 +127,7 @@ function compare(before, after, limit) {
     changed.sort((a, b) => (a.modifiedAt ?? '\uffff').localeCompare(b.modifiedAt ?? '\uffff') || a.path.localeCompare(b.path));
     return { changed: changed.slice(0, limit), omitted: Math.max(0, changed.length - limit), partial };
 }
-const backends = ['claude-acp', 'codex-acp'];
+const backends = ['claude-acp', 'codex-acp', 'acp'];
 const blankSettings = () => ({ format: 1, version: 0, updatedAt: null, backend: null, choices: {}, offered: {} });
 const acpDriver = (driver) => !!driver && 'configure' in driver;
 const identity = /^c-[a-f0-9]{16}$/;
@@ -196,7 +196,7 @@ export class Conversations {
         this.limits = { ...conversationLimits, ...limits };
         for (const key of ['maxCaptureFiles', 'maxCaptureBytes', 'maxSnapshotBytes', 'maxCaptureConcurrent'])
             requireThat(Number.isSafeInteger(this.limits[key]) && this.limits[key] > 0 && this.limits[key] <= conversationLimits[key], 'invalid', 'Capture budgets must be positive integers no greater than the supported defaults.', { limit: key, maximum: conversationLimits[key] });
-        requireThat(!config.backend || ['claude-acp', 'codex-acp', 'claude-cli'].includes(config.backend), 'invalid', 'Choose claude-acp, codex-acp or claude-cli.');
+        requireThat(!config.backend || ['claude-acp', 'codex-acp', 'claude-cli', 'acp'].includes(config.backend), 'invalid', 'Choose claude-acp, codex-acp, claude-cli or acp.');
     }
     serial(key, run) {
         const task = (this.queues.get(key) ?? Promise.resolve()).catch(() => { }).then(run);
@@ -408,7 +408,7 @@ export class Conversations {
             const saved = await this.readSettings();
             const backend = input.backend ?? saved.backend ?? this.config.backend ?? 'claude-acp';
             const config = backend === 'claude-cli' ? undefined : input.config ?? saved.choices[backend];
-            const at = now(), c = { format: 2, backend, id: 'c-' + randomBytes(8).toString('hex'), changeId: input.changeId, requestDigest, createdAt: at, createdBy: by, updatedAt: at, version: 0, client: backend === 'codex-acp' ? 'codex' : 'claude-code', nativeSessionId: backend === 'claude-cli' ? randomUUID() : null, confirmed: false, principal: null, title: titleOf(text), turns: [], ...(config && Object.keys(config).length ? { config } : {}) };
+            const at = now(), c = { format: 2, backend, id: 'c-' + randomBytes(8).toString('hex'), changeId: input.changeId, requestDigest, createdAt: at, createdBy: by, updatedAt: at, version: 0, client: backend === 'codex-acp' ? 'codex' : backend === 'acp' ? 'acp' : 'claude-code', nativeSessionId: backend === 'claude-cli' ? randomUUID() : null, confirmed: false, principal: null, title: titleOf(text), turns: [], ...(config && Object.keys(config).length ? { config } : {}) };
             for (const id of input.contexts ?? [])
                 await this.ports.context?.(project, id);
             const turn = this.turn(input.changeId, requestDigest, by, text, 1);
@@ -468,7 +468,7 @@ export class Conversations {
         this.choices({ [input.configId]: input.value });
         return this.serial(project.id, async () => {
             const c = await this.load(project, input.conversationId), last = c.turns.at(-1);
-            requireThat(c.backend === 'claude-acp' || c.backend === 'codex-acp', 'unavailable', 'This conversation\'s Agent has no settings Rho can change.');
+            requireThat(c.backend === 'claude-acp' || c.backend === 'codex-acp' || c.backend === 'acp', 'unavailable', 'This conversation\'s Agent has no settings Rho can change.');
             requireThat(!c.trashedAt, 'conflict', 'This conversation is in the trash. Restore it to change its settings.');
             requireThat(!last || last.state !== 'running' || !this.liveTurn(project, c, last), 'conflict', 'The Agent is answering. Change its settings after this message.');
             const driver = this.drivers.get(project.id + '/' + c.id)?.driver;
@@ -558,9 +558,9 @@ export class Conversations {
         return this.settings();
     }
     async inspect(project, backend) {
-        const { ClaudeAcpConversation, CodexAcpConversation } = await import('@rho-workspace/plugin-agent/conversation');
+        const { ClaudeAcpConversation, CodexAcpConversation, GenericAcpConversation } = await import('@rho-workspace/plugin-agent/conversation');
         const common = { cwd: project.root, mcpServers: [], limits: this.limits };
-        const driver = backend === 'codex-acp' ? new CodexAcpConversation({ ...this.config.codexAcp, ...common, codex: this.config.codex }) : new ClaudeAcpConversation({ preferred: claudePreferred, ...this.config.claudeAcp, ...common, claude: this.binary });
+        const driver = backend === 'codex-acp' ? new CodexAcpConversation({ ...this.config.codexAcp, ...common, codex: this.config.codex }) : backend === 'acp' ? new GenericAcpConversation({ ...common, command: this.config.acpCommand }) : new ClaudeAcpConversation({ preferred: claudePreferred, ...this.config.claudeAcp, ...common, claude: this.binary });
         let found;
         try {
             found = await driver.inspect();
@@ -750,11 +750,11 @@ export class Conversations {
             const grant = await this.ports.grant(project, c);
             c.principal = grant.principal;
             const mcpServers = [{ name: 'rho', command: process.execPath, args: [fileURLToPath(import.meta.resolve('@rho-workspace/plugin-agent/mcp'))], env: [{ name: 'RHO_AGENT_CONNECTION', value: grant.file }] }];
-            const { ClaudeAcpConversation, CodexAcpConversation, ClaudeCliConversation } = await import('@rho-workspace/plugin-agent/conversation');
+            const { ClaudeAcpConversation, CodexAcpConversation, ClaudeCliConversation, GenericAcpConversation } = await import('@rho-workspace/plugin-agent/conversation');
             const observed = { observation: c.observation, observe: (observation) => {
                     requireThat(observation.sessionId === c.acpSessionId, 'conflict', 'The observed Agent session differs from the retained identity.');
                     requireThat(Buffer.byteLength(JSON.stringify(observation)) <= this.limits.maxObservationBytes, 'limit', 'The session projection exceeded maxObservationBytes; prior observations were kept.');
-                    const config = observation.config, learned = config && config.at !== c.observation?.config?.at && config.origin === 'initial' && !c.config && (c.backend === 'claude-acp' || c.backend === 'codex-acp');
+                    const config = observation.config, learned = config && config.at !== c.observation?.config?.at && config.origin === 'initial' && !c.config && (c.backend === 'claude-acp' || c.backend === 'codex-acp' || c.backend === 'acp');
                     c.observation = observation;
                     this.schedule(project, c);
                     for (const live of this.live.values())
@@ -775,7 +775,9 @@ export class Conversations {
                 ? new CodexAcpConversation({ ...this.config.codexAcp, ...common, codex: this.config.codex })
                 : c.backend === 'claude-acp'
                     ? new ClaudeAcpConversation({ preferred: claudePreferred, ...this.config.claudeAcp, ...common, claude: this.binary, plugins: [...this.config.claudeAcp?.plugins ?? [], ...await this.ports.claudePlugins?.(project) ?? []] })
-                    : new ClaudeCliConversation({ cwd: project.root, binary: this.binary, sessionId: c.nativeSessionId, confirmed: c.confirmed, projectName: project.name ?? path.basename(project.root), mcpServers, limits: this.limits, instructions });
+                    : c.backend === 'acp'
+                        ? new GenericAcpConversation({ ...common, command: this.config.acpCommand })
+                        : new ClaudeCliConversation({ cwd: project.root, binary: this.binary, sessionId: c.nativeSessionId, confirmed: c.confirmed, projectName: project.name ?? path.basename(project.root), mcpServers, limits: this.limits, instructions });
             this.drivers.set(key, { driver, project, conversation: c });
             return driver;
         });
@@ -895,8 +897,9 @@ export class Conversations {
                 const action = toolActivity(incoming, null, project.root);
                 if (action.targetKind === 'path' && (action.location || incoming.detail))
                     this.capture(live, action.location ?? incoming.detail, 'step:' + incoming.id + ':' + incoming.outcome);
-                if (action.targetKind === 'command' && action.target)
-                    for (const file of commandFiles(action.target, project))
+                // A command's files are captured however its row reads (an install names its packages).
+                if (action.action === 'execute' && incoming.detail)
+                    for (const file of commandFiles(displayCommand(incoming.detail), project))
                         this.capture(live, file, 'command:' + incoming.id + ':' + incoming.outcome);
             }
             if (!kept)
@@ -1068,7 +1071,8 @@ export class Conversations {
         const given = shown.get(file);
         const reason = !enabled ? 'Descriptions by a model are switched off; the facts are kept.'
             : c.backend === 'codex-acp' ? 'Descriptions are written with Claude Code; this session\'s Agent is Codex.'
-                : !this.ports.describe ? 'No model is set up to describe files.' : null;
+                : c.backend === 'acp' ? 'Descriptions are written with Claude Code; this session\'s Agent is a configured ACP agent.'
+                    : !this.ports.describe ? 'No model is set up to describe files.' : null;
         const keep = (why) => { if (record.reason !== why) {
             record.state = record.sentence ? 'described' : 'facts';
             record.reason = why;

package/dist/installs.d.ts

@@ -0,0 +1,11 @@
+export interface Installed {
+    tool: string;
+    packages: Array<{
+        name: string;
+        version: string | null;
+    }>;
+    more: number;
+    from: string | null;
+}
+export declare function readInstall(command: string, printed?: string | null): Installed | null;
+export declare function installText(installed: Installed): string;

package/dist/installs.js

@@ -0,0 +1,179 @@
+// One command line split into its commands and words, honouring quotes. Pipes, `&&`, `||`, `;`,
+// new lines and a subshell's parentheses separate commands.
+function commands(line) {
+    const out = [];
+    let words = [], word = '', quote = '', has = false;
+    const end = () => { if (has)
+        words.push(word); word = ''; has = false; };
+    const next = () => { end(); if (words.length)
+        out.push(words); words = []; };
+    for (let i = 0; i < line.length; i++) {
+        const c = line[i];
+        if (quote) {
+            if (c === quote)
+                quote = '';
+            else if (c === '\\' && quote === '"' && i + 1 < line.length)
+                word += line[++i];
+            else
+                word += c;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            quote = c;
+            has = true;
+            continue;
+        }
+        // A backslash before a new line continues the command; before anything else it escapes it.
+        if (c === '\\' && line[i + 1] === '\n') {
+            end();
+            i++;
+            continue;
+        }
+        if (c === '\\' && i + 1 < line.length) {
+            word += line[++i];
+            has = true;
+            continue;
+        }
+        if (c === '\n' || c === ';' || c === '|' || c === '&' || c === '(' || c === ')') {
+            next();
+            if ((c === '|' || c === '&') && line[i + 1] === c)
+                i++;
+            continue;
+        }
+        if (c === ' ' || c === '\t') {
+            end();
+            continue;
+        }
+        word += c;
+        has = true;
+    }
+    next();
+    return out;
+}
+const base = (word) => word.split(/[\\/]/).pop().replace(/\.exe$/i, '');
+// Options of these tools that take the next word as their value, so it is not a package.
+const valued = new Set(['-e', '--editable', '-r', '--requirement', '-c', '--constraint', '--channel', '-i', '--index-url', '--extra-index-url', '-f', '--find-links', '-t', '--target', '--prefix', '--root', '-p', '--python', '-n', '--name', '--group', '--optional', '--extra', '--index', '--default-index', '--cache-dir', '--directory', '--project', '--package', '--override', '--build-constraint']);
+// A package as an installer names it (pandas, pandas==2.2.3, pandas[excel]>=2, conda-forge::pandas);
+// a path, a URL or a file is not one.
+const spec = (raw) => {
+    const word = raw.includes('::') ? raw.slice(raw.lastIndexOf('::') + 2) : raw;
+    if (/[\\/]|^\.|:\/\/|\.(txt|toml|in|cfg|whl|gz|zip)$/i.test(word))
+        return null;
+    const name = word.match(/^[A-Za-z0-9][A-Za-z0-9._-]*/)?.[0];
+    if (!name)
+        return null;
+    return { name, version: word.slice(name.length).match(/^(?:\[[^\]]*\])?={1,2}([^,;\s=<>!~*]+)$/)?.[1] ?? null };
+};
+// A Python installer's words after `install` (or uv's `add`): its packages and a requirements file.
+function pythonArgs(words) {
+    const packages = [];
+    let from = null;
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i];
+        if (word === '-r' || word === '--requirement') {
+            from = words[i + 1] ?? null;
+            i++;
+            continue;
+        }
+        if (word.startsWith('--requirement=')) {
+            from = word.slice(14);
+            continue;
+        }
+        if (valued.has(word)) {
+            i++;
+            continue;
+        }
+        if (word.startsWith('-'))
+            continue;
+        const found = spec(word);
+        if (found)
+            packages.push(found);
+    }
+    return { packages, from };
+}
+// R code's install calls: install.packages("a"), install.packages(c("a", "b")), BiocManager::install(...).
+function rInstalls(code) {
+    const found = [];
+    for (const match of code.matchAll(/\b(?:(utils)::)?(install\.packages|(BiocManager|pak|remotes|renv)::(?:install|pkg_install|install_github|install_cran))\s*\(([^()]*(?:\([^()]*\)[^()]*)*)\)/g)) {
+        const names = [...(match[4] ?? '').matchAll(/["']([A-Za-z0-9._/@-]+)["']/g)].map(m => m[1]).filter(name => !/^(https?|cran|repos)/i.test(name));
+        if (names.length)
+            found.push({ tool: match[3] ?? 'R', names });
+    }
+    return found;
+}
+export function readInstall(command, printed) {
+    let tool = null, from = null;
+    const packages = [];
+    for (const raw of commands(command)) {
+        let words = raw.slice();
+        while (words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]) || ['rtk', 'proxy', 'sudo', 'env', 'command', 'exec', 'time', 'nohup', '{', '}', '!', 'then', 'else', 'do'].includes(words[0])))
+            words = words.slice(1);
+        const head = base(words[0] ?? ''), rest = words.slice(1);
+        let args = null, by = null;
+        if (head === 'uv' && rest[0] === 'pip' && rest[1] === 'install') {
+            args = rest.slice(2);
+            by = 'uv';
+        }
+        else if (head === 'uv' && rest[0] === 'add') {
+            args = rest.slice(1);
+            by = 'uv';
+        }
+        else if (/^pip3?(\.\d+)?$/.test(head) && rest[0] === 'install') {
+            args = rest.slice(1);
+            by = 'pip';
+        }
+        else if (/^python(\d(\.\d+)?)?$/.test(head) && rest[0] === '-m' && rest[1] === 'pip' && rest[2] === 'install') {
+            args = rest.slice(3);
+            by = 'pip';
+        }
+        else if (/^(conda|mamba|micromamba)$/.test(head) && rest[0] === 'install') {
+            args = rest.slice(1);
+            by = head;
+        }
+        else if (/^(Rscript|R)$/.test(head)) {
+            const code = rest.filter((_, i) => rest[i - 1] === '-e' || rest[i - 1] === '--expr').join('\n');
+            for (const call of rInstalls(code)) {
+                by ??= call.tool;
+                for (const name of call.names)
+                    packages.push({ name: name.split('/').pop().split('@')[0], version: null });
+            }
+            if (by)
+                tool ??= by;
+            continue;
+        }
+        if (!args || !by)
+            continue;
+        tool ??= by;
+        const read = pythonArgs(args);
+        packages.push(...read.packages);
+        from ??= read.from;
+    }
+    if (!tool || !packages.length && !from)
+        return null;
+    // What was installed, as the tool printed it: pip's "Successfully installed a-1.0 b-2.0" and
+    // uv's " + a==1.0" lines. Names compare as package indexes compare them.
+    const key = (name) => name.toLowerCase().replace(/[-_.]+/g, '-');
+    const versions = new Map();
+    for (const line of (printed ?? '').split('\n')) {
+        const pip = line.match(/Successfully installed (.+)$/);
+        if (pip)
+            for (const item of pip[1].trim().split(/\s+/)) {
+                const at = item.lastIndexOf('-');
+                if (at > 0)
+                    versions.set(key(item.slice(0, at)), item.slice(at + 1));
+            }
+        const uv = line.match(/^\s*\+\s+([A-Za-z0-9][A-Za-z0-9._-]*)==(\S+)/);
+        if (uv)
+            versions.set(key(uv[1]), uv[2]);
+    }
+    const named = new Set(packages.map(p => key(p.name)));
+    const seen = new Set(), listed = packages.filter(p => !seen.has(key(p.name)) && seen.add(key(p.name)))
+        .map(p => ({ name: p.name, version: versions.get(key(p.name)) ?? p.version }));
+    return { tool, packages: listed, more: [...versions.keys()].filter(name => !named.has(name)).length, from };
+}
+// "pandas 2.2.3, statsmodels 0.15.0 and 6 more (uv)", or "packages from requirements.txt (pip)".
+export function installText(installed) {
+    const names = installed.packages.map(p => p.version ? `${p.name} ${p.version}` : p.name);
+    const what = names.length ? names.join(', ') : `packages from ${installed.from}`;
+    return `${what}${installed.more ? ` and ${installed.more} more` : ''} (${installed.tool})`;
+}

package/dist/project-notes.js

@@ -21,6 +21,7 @@ export function notesInstructions(conversationId, options = {}) {
         '- Data & method: one bullet for the data and one for each script, each linked, saying what it is and how it is used.',
         '- Key results: one bullet per finding, each linking the result files it rests on; embed a key figure on its own line as ![what it shows](path/to/figure.png).',
         '- Files: right after you write a result, table, figure or script, and before your next command, add a bullet as - [path](path) — what it holds; correct it when that changes. Do not leave this to the end.',
+        '- Scripts and cells: above each top-level statement that first makes a value you report, or writes a file, add a comment `# means: …` with one short sentence saying what it is, in the language the person writes in, under 200 characters. Where one statement makes or writes several things, name the one the comment is for: `# means NAME: …`, with a value name or a file path. Comments inside a function, and changes to a value after it is made, need none. Rho shows these sentences beside the code, so a reader who does not read R or Python can follow the steps.',
         '- Choices: when the analysis takes a choice that has a reasonable alternative (a test, a threshold, an exclusion, a model), go on with your choice and do not ask the person or wait. Where the alternative is cheap, compute it too. Write one bullet saying what you chose and what it gives, linking its results, with a nested bullet starting "Alternative:" that says what the other option gives, linking its results.',
         '- To do: a task list (- [ ] open, - [x] done).',
         '- Leave a subsection empty until you have something for it; do not write placeholders such as "to be filled".',
@@ -33,6 +34,7 @@ export function notesInstructions(conversationId, options = {}) {
             '- What a cell defines stays for your next cells, so load data once and build on it. kernel.read shows the cells, including any the person ran, and the variables.',
             '- To look at a value without adding a cell, call kernel.inspect with its language and name: it gives a page of a table, a model\'s fit and coefficients, or a list\'s parts, with the code that reaches each part.',
             '- Keep the code your results rest on in script files as well, so they can be run again without the session.',
+            '- Before a multi-step analysis, read the Skill "rho.analysis-run" with skill.list and skill.read: it holds the practice that keeps a long analysis from losing work when a turn stops, written after five real reproductions ran here.',
         ] : []),
     ].join('\n');
 }

package/dist/protocol.js

@@ -20,7 +20,9 @@ const array = (items) => ({ type: 'array', items });
 const response = (properties, required = Object.keys(properties)) => ({ type: 'object', properties, required, additionalProperties: true });
 const changeId = { type: 'string', pattern: '^[A-Za-z0-9._:@-]{1,128}$' };
 const identity = changeId;
-const agentBackend = { enum: ['claude-acp', 'codex-acp'] };
+// 'acp' is a generic ACP agent: the operator names its command (--acp-command), so Rho
+// supports any ACP v1 implementation without a per-agent adapter.
+const agentBackend = { enum: ['claude-acp', 'codex-acp', 'acp'] };
 const outsideAgent = { enum: ['claude-code', 'codex'] };
 const addedTo = response({ agent: outsideAgent, name: text, scope: { enum: ['folder', 'user'] }, at: text });
 const choiceText = { type: 'string', minLength: 1, maxLength: 512 }, choiceValue = { anyOf: [choiceText, { type: 'boolean' }] };
@@ -81,7 +83,7 @@ export const operations = { ...base.operations,
     // The person's Agent and its settings (model, effort, mode…) among those the Agent offers.
     'conversation.configure': obj({ ...project, conversationId: changeId, configId: choiceText, value: choiceValue }),
     'conversation.settings.read': obj(project),
-    'conversation.settings.update': obj({ ...project, expectedVersion: integer, backend: { anyOf: [agentBackend, { type: 'null' }] }, choices: obj({ 'claude-acp': choices, 'codex-acp': choices }, []), describe: obj({ enabled: { type: 'boolean' } }, ['enabled']) }, ['projectId', 'expectedVersion']),
+    'conversation.settings.update': obj({ ...project, expectedVersion: integer, backend: { anyOf: [agentBackend, { type: 'null' }] }, choices: obj({ 'claude-acp': choices, 'codex-acp': choices, 'acp': choices }, []), describe: obj({ enabled: { type: 'boolean' } }, ['enabled']) }, ['projectId', 'expectedVersion']),
     'conversation.settings.check': obj({ ...project, backend: agentBackend }),
     // Claude Code or Codex running outside Rho, given this project and told how to start Rho's MCP server.
     'session.connect': obj({ ...project, agent: outsideAgent })
@@ -201,8 +203,8 @@ const conversationSummary = response({ conversationId: text, title: text, client
 const sessionObservation = ownerSchema('agent-session', 'sessionObservationSchema');
 // What one Agent offered, from a check or a conversation's first session, and the person's choices.
 const offered = response({ at: text, source: { enum: ['check', 'conversation'] }, adapter: { anyOf: [response({ name: text, version: text }, ['name']), { type: 'null' }] }, options: array(ownerSchema('agent-session', 'configOptionSchema')), omitted: integer });
-const agentSettings = response({ version: integer, updatedAt: { anyOf: [text, { type: 'null' }] }, backend: { anyOf: [agentBackend, { type: 'null' }] }, serviceBackend: { enum: ['claude-acp', 'codex-acp', 'claude-cli'] },
-    choices: response({ 'claude-acp': choices, 'codex-acp': choices }, []), offered: response({ 'claude-acp': offered, 'codex-acp': offered }, []), checking: array(agentBackend),
+const agentSettings = response({ version: integer, updatedAt: { anyOf: [text, { type: 'null' }] }, backend: { anyOf: [agentBackend, { type: 'null' }] }, serviceBackend: { enum: ['claude-acp', 'codex-acp', 'claude-cli', 'acp'] },
+    choices: response({ 'claude-acp': choices, 'codex-acp': choices, 'acp': choices }, []), offered: response({ 'claude-acp': offered, 'codex-acp': offered, 'acp': offered }, []), checking: array(agentBackend),
     // Whether a model describes the files a message writes; the facts are read either way.
     describe: response({ enabled: { type: 'boolean' } }) }, ['version', 'updatedAt', 'backend', 'serviceBackend', 'choices', 'offered', 'checking']);
 // A tool step keeps its original identity, the Agent's bounded human title, its ACP
@@ -405,7 +407,7 @@ export const descriptions = {
     'console.events': 'Who ran each Console command and when, newest first, for the timeline: the folder, how it ended and its first line. No output.',
     'console.output': 'One bounded page of what a Console command printed. Output past the kept size is counted in a note, not silently dropped.',
     'console.stop': 'Person at this machine only: ask a running Console command and the processes it started to stop; they are killed after a short grace period.',
-    'kernel.run': 'Run a cell of R or Python in the project\'s live session of that language, which the Agent and the person share: what one cell defines stays for the next. Starts the session when none is live, on this machine or at a place on one of the person\'s servers (place, or where kernel.places says that language runs next). The same changeId from the same caller returns the same cell and never runs it twice. waitMs waits for the cell to end.',
+    'kernel.run': 'Run a cell of R or Python in the project\'s live session of that language, which the Agent and the person share: what one cell defines stays for the next. Starts the session when none is live, on this machine or at a place on one of the person\'s servers (place, or where kernel.places says that language runs next). interpreter names the program a session on this machine starts with, in a folder of the project such as .venv/bin/python; the project keeps it for that language\'s later sessions, and each cell records the program and version that ran it. The same changeId from the same caller returns the same cell and never runs it twice. waitMs waits for the cell to end.',
     'skills.list': 'The project\'s skills: how work is done here (the methods the person chose, the conventions they keep, the traps its work ran into), each a SKILL.md in .claude/skills that every Agent here reads, with what it is for and its newest change. Read before analysing.',
     'skills.read': 'One project skill\'s text and its changes, newest first: who made each, why, from what (cells, conversations, files) and the lines it added and removed, and what changed outside Rho since.',
     'skills.change': 'Record in a project skill when the person corrects a method or says how they work, or a failure\'s cause and fix are found: a new skill, a new text with a one-sentence reason and evidence, or its removal. Record how to work, never results. Made on the version read; the same changeId never writes twice.',

package/dist/screen-check-skill.d.ts

@@ -0,0 +1,2 @@
+import { SkillDeclaration } from '@rho-workspace/plugin-contracts';
+export declare const screenCheckSkill: SkillDeclaration;

package/dist/screen-check-skill.js

@@ -0,0 +1,39 @@
+import { digest } from '@rho-workspace/plugin-contracts';
+// The practice for checking a page's layout in a real browser, served as the Skill rho.screen-check.
+// skills/rho/references/screen-check.md carries this text verbatim, and
+// test/screen-check-skill.test.mjs fails when the two differ, so the text has one source.
+const screenCheckContent = [
+    'Check how a page lays out in a real browser before you say it works.',
+    '',
+    'Run `rho-screen-check <url or page.html>`. It opens the page at each viewport (by default 1440x900, 1024x768, 768x1024 and 390x844), waits for it to settle, writes one screenshot per viewport and prints a JSON report. Options: `--viewport WxH` (repeatable), `--out DIR` (default ./screen-check), `--overlap SELECTOR` (report the visible boxes of that selector that overlap one another), `--full-page`, `--settle MS` (default 800), `--browser auto|chrome|msedge|chromium|PATH` (default auto: Chrome, then Edge, then Playwright\'s Chromium).',
+    '',
+    'Read the exit status first. 0: the check ran, and its findings are in the report. 1: an argument was wrong. 2: the check did not run; `error.kind`, `error.message` and `error.next` say why and what to do. Do what `next` says, then run it again.',
+    '',
+    'For each viewport, read: `horizontalOverflow` with `scrollWidth` against `clientWidth` (the page is wider than the window); `elementsPastEdgeUnclipped` (what crosses the right edge and no box keeps in: read this count first), then `elementsPastEdge` (the first 50, unclipped first; `clippedBy` names the box that scrolls or hides what is beyond its own width); `unnamedButtons`; `overlaps` for your selector; `pageErrors` and `consoleErrors`; `httpErrors` (each response that failed, with its status and address); `requestsOutsideTarget` (what the page loads from elsewhere).',
+    '',
+    'Then open each `screenshot` with the Read tool and say what you see. The report says what the page does, not whether a person can follow it; the screenshot and the flow answer that. Check the states a person reaches as well as the first screen: an empty state, an error, a long name or number, a narrow window, the screen after a step. Run the check again after each change.',
+    '',
+    'Pitfalls seen in real runs:',
+    '- A selector can match hidden elements. The report counts visible boxes only; your own probes must filter by visibility too.',
+    '- The same attribute can appear in two views at once, such as a script editor\'s flow and a session\'s Data flow. Open a workspace that shows only the view you check.',
+    '- At 390 px the sidebar collapses and project labels are hidden. Reach the label through the page\'s own controls before you look for it.',
+    '- Text cut short inside a box of fixed height, such as a label that ends mid-word, is not in the report. Only the screenshot shows it.',
+    '- Restarting Rho ends the live R sessions, and the page then shows "Rho closed. Values defined before this are gone." Say so when a check follows a restart.',
+    '- Check a copy of the project, not the person\'s own project. A check must not change what the person has.',
+].join('\n');
+export const screenCheckSkill = {
+    id: 'rho.screen-check',
+    version: '1.0',
+    content: screenCheckContent,
+    digest: digest(screenCheckContent),
+    intent: 'Check how a Rho screen or a local page lays out at phone and desktop widths, in a real browser, and read the result rather than assume it.',
+    failureRecipes: [
+        { kind: 'browser_missing', message: 'No browser could be started.', next: 'Install Google Chrome or Microsoft Edge, or pass --browser with the path of an installed Chromium-based browser; then run the check again.' },
+        { kind: 'unreachable', message: 'The page did not load.', next: 'Check the address, that the service is running or the file exists, and that the page opens in a browser; then run the check again.' },
+        { kind: 'usage', message: 'An argument was not understood.', next: 'Run rho-screen-check --help and use one of the listed forms.' },
+    ],
+    verify: {
+        command: 'npm run test:screen-check',
+        description: 'Runs the screen-check tests: the findings on fixture pages in a real browser, the JSON report and the exit codes, and this Skill text against the shipped reference.',
+    },
+};

package/dist/server.d.ts

@@ -70,6 +70,7 @@ export interface ServiceConfig extends Partial<typeof serviceLimits>, Partial<ty
     claude?: string;
     agentBackend?: ConversationConfig['backend'];
     claudeAcp?: ConversationConfig['claudeAcp'];
+    acpCommand?: ConversationConfig['acpCommand'];
     codex?: string;
     codexAcp?: ConversationConfig['codexAcp'];
     conversations?: Partial<typeof conversationLimits>;
@@ -160,6 +161,7 @@ export declare class RhoService {
     private catalog;
     private modelFacts;
     start(): Promise<this>;
+    private followAddress;
     agentConnection(projectId: string, externalSessionId: string, file: string, methods?: string[], pluginFilter?: string[], profile?: 'layered-business' | 'layered-presentation', who?: {
         label?: string;
         conversationId?: string;

package/dist/server.js

@@ -385,7 +385,7 @@ export class RhoService {
             // The same project grant `rho --grant` gives, under this conversation's own principal.
             grant: async (project, conversation) => {
                 const session = 'rho:' + conversation.id, file = path.join(this.state.directory, 'agent-' + digest(project.id + ':' + session) + '.json');
-                await this.agentConnection(project.id, session, file, undefined, undefined, 'layered-business', { label: (conversation.client === 'codex' ? 'Codex' : 'Claude Code') + ' in Rho', conversationId: conversation.id });
+                await this.agentConnection(project.id, session, file, undefined, undefined, 'layered-business', { label: (conversation.client === 'codex' ? 'Codex' : conversation.client === 'acp' ? 'ACP agent' : 'Claude Code') + ' in Rho', conversationId: conversation.id });
                 return { file, principal: 'agent:' + digest(project.id + ':' + session).slice(0, 32) };
             },
             directory: project => this.dataDir(project),
@@ -462,7 +462,7 @@ export class RhoService {
                     return { text: said.text, model: said.model, cost: callCost(said, listed ? await this.modelFacts(listed).catch(() => null) : null) };
                 }
             } : {}
-        }, config.claude, config.conversations, { backend: config.agentBackend, claudeAcp: config.claudeAcp, codex: config.codex, codexAcp: config.codexAcp, settingsFile: path.join(this.state.directory, 'agent-settings.json') });
+        }, config.claude, config.conversations, { backend: config.agentBackend, claudeAcp: config.claudeAcp, acpCommand: config.acpCommand, codex: config.codex, codexAcp: config.codexAcp, settingsFile: path.join(this.state.directory, 'agent-settings.json') });
         this.conversations.describing = { ...describeLimits, ...config.describe };
         this.folderPicker = new NativeFolderPicker({ ...nativeFolderLimits, ...config.nativeFolders });
         this.server = http.createServer((req, res) => void this.handle(req, res));
@@ -501,9 +501,33 @@ export class RhoService {
             const chosen = (earlier?.selectedProjects ?? []).filter(id => this.state.projects.some(p => p.id === id && p.nativeSelected));
             this.state.principals = this.state.principals.filter(p => p.id !== localBrowserId);
             await this.state.addPrincipal({ ...localBrowserPrincipal(await fs.realpath(this.config.root)), ...(chosen.length ? { selectedProjects: chosen } : {}) });
-            await new Promise((resolve, reject) => { this.server.once('error', reject); this.server.listen(this.config.port ?? 0, '127.0.0.1', () => resolve()); });
+            // A person's bookmark and every Agent connection name this service's address. A start that
+            // selects no port takes the one this state's last start had, and a new one only when that
+            // port is taken now; a selected port is used or refused, never replaced.
+            const connectionFile = path.join(this.state.directory, 'connection.json');
+            const earlierUrl = await fs.readFile(connectionFile, 'utf8').then(text => String(JSON.parse(text).url), () => '');
+            const earlierPort = /^http:\/\/127\.0\.0\.1:\d+$/.test(earlierUrl) ? Number(new URL(earlierUrl).port) : 0;
+            const listen = (port) => new Promise((resolve, reject) => {
+                this.server.once('error', reject);
+                this.server.listen(port, '127.0.0.1', () => { this.server.off('error', reject); resolve(); });
+            });
+            try {
+                await listen(this.config.port ?? earlierPort);
+            }
+            catch (error) {
+                const taken = error.code === 'EADDRINUSE';
+                requireThat(!taken || this.config.port === undefined, 'conflict', `Port ${this.config.port} on 127.0.0.1 is in use by another program. If that is Rho, open http://127.0.0.1:${this.config.port}; otherwise choose another --port, or leave it out.`, { port: this.config.port });
+                if (!taken)
+                    throw error;
+                await listen(0);
+            }
             this.url = 'http://127.0.0.1:' + this.server.address().port;
-            await atomicJson(path.join(this.state.directory, 'connection.json'), { url: this.url, token: this.adminToken, apiVersion: '2.0' });
+            await atomicJson(connectionFile, { url: this.url, token: this.adminToken, apiVersion: '2.0' });
+            // An Agent's connection holds the address it was given. When the address changed, each one
+            // that named the earlier address follows, so the Agent's next session reaches this service
+            // with the grant it already has. Its token and methods are unchanged.
+            if (earlierUrl && earlierUrl !== this.url)
+                await this.followAddress(earlierUrl);
             return this;
         }
         catch (e) {
@@ -513,6 +537,20 @@ export class RhoService {
             throw e;
         }
     }
+    // Only this state's own connection files, and only those that named the earlier address: a
+    // file that cannot be read or rewritten keeps what it had, and the start goes on.
+    async followAddress(earlierUrl) {
+        const names = await fs.readdir(this.state.directory).catch(() => []);
+        for (const name of names.filter(name => /^agent-[0-9a-f]+\.json$/.test(name))) {
+            const file = path.join(this.state.directory, name);
+            try {
+                const connection = JSON.parse(await fs.readFile(file, 'utf8'));
+                if (connection?.url === earlierUrl && typeof connection.token === 'string')
+                    await atomicJson(file, { ...connection, url: this.url });
+            }
+            catch { /* left as it was */ }
+        }
+    }
     async agentConnection(projectId, externalSessionId, file, methods, pluginFilter, profile = 'layered-business', who = {}) {
         requireThat(profile === undefined || ['layered-business', 'layered-presentation'].includes(profile), 'invalid', 'Choose an explicitly supported layered profile.');
         const project = await this.state.project(projectId, this.state.principals.find(p => p.id === 'operator'));
@@ -952,7 +990,11 @@ export class RhoService {
             add('rscript', rscriptAvailable ? 'ok' : b.intent === 'run-r' ? 'fail' : 'warn', rscriptAvailable ? `R is available at ${this.bridge.rscript}.` : `The optional managed R entry is unavailable at ${this.bridge.rscript}. Native Agent tools remain available.`, rscriptAvailable ? '' : 'For managed R scripts, select an existing Rscript with --rscript or RHO_RSCRIPT.');
             // Conversations drive the person's installed Claude Code or Codex; the package carries none.
             const agentCommand = await import('@rho-workspace/plugin-agent/acp-command').catch(() => null);
-            if (agentCommand) {
+            if (this.config.agentBackend === 'acp') {
+                const cmd = this.config.acpCommand;
+                add('agents', cmd?.file ? 'ok' : 'warn', cmd?.file ? `A generic ACP agent is configured (${cmd.file} ${cmd.args.join(' ')}).` : 'No ACP agent command is configured.', cmd?.file ? '' : 'Start Rho with --agent-backend acp --acp-command <argv> or RHO_ACP_COMMAND.');
+            }
+            else if (agentCommand) {
                 const claude = this.config.claude ?? process.env.RHO_CLAUDE, codex = this.config.codex ?? process.env.RHO_CODEX;
                 const env = { ...process.env, ...(claude ? { CLAUDE_CODE_EXECUTABLE: claude } : {}), ...(codex ? { CODEX_PATH: codex } : {}) };
                 const preferred = this.config.agentBackend === 'codex-acp' ? 'codex' : 'claude', other = preferred === 'codex' ? 'claude' : 'codex';
@@ -1083,8 +1125,9 @@ export class RhoService {
         }
         // The person's own Claude Code or Codex, outside Rho: the same grant the operator gives, kept
         // when it already exists so a connected session keeps its token, then the Agent's own `mcp add`.
+        // The person does it from the page; whoever started the service, with `rho --grant --agent`.
         if (method === 'session.connect') {
-            requireThat(principal.id === localBrowserId, 'unauthorized', 'Only the person at this machine can add Rho to their own Agent.');
+            requireThat(principal.id === localBrowserId || principal.id === 'operator', 'unauthorized', 'Only the person at this machine can add Rho to their own Agent.');
             const agent = b.agent, file = path.join(this.state.directory, 'agent-' + digest(p.id + ':' + agent) + '.json');
             const id = 'agent:' + digest(p.id + ':' + agent).slice(0, 32), existing = this.state.principals.find(x => x.id === id);
             // A grant is kept while its connection still reaches this service with its token; otherwise
@@ -1184,7 +1227,7 @@ export class RhoService {
             await capabilities.assertAvailable(method, principal);
             const host = this.kernelFor(p);
             if (method === 'kernel.run')
-                return host.run({ language: b.language, code: b.code, purpose: b.purpose, changeId: b.changeId, by: principal.id, waitMs: b.waitMs, place: b.place });
+                return host.run({ language: b.language, code: b.code, purpose: b.purpose, changeId: b.changeId, by: principal.id, waitMs: b.waitMs, place: b.place, interpreter: b.interpreter });
             if (method === 'kernel.read')
                 return host.read(b.limit, b.cellId);
             if (method === 'kernel.events')