@rho-workspace/rho 0.5.3 → 0.5.5

package/README.md

@@ -39,8 +39,9 @@ contract. Electron is reserved for a later desktop client that reuses the WebUI
 and component boundaries. Functional views use CodeMirror 6, AG Grid Community
 and ECharts.
 
-Install the packed tarball, start `rho`, and connect an external Agent with
-`rho --grant` ([Install and start](docs/HEADLESS.md#install-and-start)). Projects,
+Install it with `npm install -g @rho-workspace/rho` on Node 22.22 or later, below 27, start
+`rho`, and connect an external Agent with `rho --grant`
+([Install and start](docs/HEADLESS.md#install-and-start)). Projects,
 files, execution records and workspaces are available through the local WebUI.
 The Agent uses the same scoped capabilities; a browser request copied to an external
 Agent is explicitly a handoff.
@@ -50,8 +51,25 @@ plans and visual rules. See [Frontend](docs/FRONTEND.md) for the current interfa
 [Status](docs/STATUS.md) for executed checks and limits, and the
 [documentation index](docs/README.md) for backend and release information.
 
+## Set up with an Agent
+
+A person can ask Claude Code or Codex, in any language:
+
+> Read https://yulab-smu.top/Rho/doc/setup.md and follow its steps to install and configure Rho for me.
+
+or: 请阅读 https://yulab-smu.top/Rho/doc/setup.md 文档，按照步骤为我安装并配置 Rho。
+
+That page is [SETUP.md](SETUP.md). The Agent checks the machine, installs the npm package and
+starts Rho on `~/Rho/projects` and `~/Rho/state`. It then installs the Agent Skill in
+[skills/rho](skills/rho/SKILL.md) into its own skills folder, connects itself to the example
+project and says what is missing. The Skill teaches an Agent to install and connect Rho, call
+its tools without guessing, and run an analysis a person can follow. It is published beside the
+page at <https://yulab-smu.top/Rho/skills/rho/SKILL.md>.
+
 ## Documentation
 
+<https://yulab-smu.top/Rho/> runs the real interface on the shipped example project,
+replaying a recorded session without a backend, and gives the sentence above for an Agent.
 The documentation is published at <https://yulab-smu.top/Rho/docs/>. The site is
 generated from this repository's `docs/` directory, which stays the only source of
 truth: every page names the file it came from and links to it.
@@ -60,12 +78,13 @@ truth: every page names the file it came from and links to it.
 npm run docs:dev      # assemble and serve locally
 npm run docs:build    # assemble, then build the static site into site/.vitepress/dist
 npm run docs:check    # fail if a document in docs/ is neither published nor withheld
+npm run pages:build   # front page, demo and documentation into site/.pages (add -- --home for the front page alone)
+npm run pages:check   # walk the demo and the front page in a browser
+npm run pages:capture # record the demo again from this checkout's service (after npm run build)
 ```
 
 `@rho-workspace/rho` is published to npm. The registry entry for 0.5.2 carries no
-README, so its package page shows no description; from 0.5.3 the packer ships this README. Desktop installers on the
-[downloads page](https://yulab-smu.top/Rho/) are the earlier 0.4.0 line; this npm line
-is the current delivery.
+README, so its package page shows no description; from 0.5.3 the packer ships this README.
 
 For a new component view, start with [Plugin authoring](docs/PLUGIN-AUTHORING.md):
 generate a typed package, preview it independently and select its compiled entry

package/dist/browser-access.js

@@ -1,3 +1,4 @@
+import { extensionMethods } from './extension-contract.js';
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { randomBytes } from 'node:crypto';
@@ -36,7 +37,7 @@ export const browserMethods = ['protocol.describe', 'protocol.validate', 'projec
 // Only the person at this machine talks to a conversation Rho starts: it runs their own Claude
 // Code with their model credentials. Only they add Rho to their own Agent's configuration. A
 // narrower, expiring link never receives these.
-export const conversationMethods = ['session.connect', 'conversation.start', 'conversation.send', 'conversation.stop', 'conversation.decide', 'conversation.read', 'conversation.list', 'conversation.trash', 'conversation.restore', 'conversation.delete', 'conversation.permission', 'conversation.configure', 'conversation.settings.read', 'conversation.settings.update', 'conversation.settings.check', 'project.work.read', 'evidence.preview', 'evidence.export'];
+export const conversationMethods = ['agent.sessions.list', 'agent.sessions.read', 'session.connect', 'conversation.start', 'conversation.send', 'conversation.stop', 'conversation.decide', 'conversation.read', 'conversation.list', 'conversation.trash', 'conversation.restore', 'conversation.delete', 'conversation.permission', 'conversation.configure', 'conversation.settings.read', 'conversation.settings.update', 'conversation.settings.check', 'project.work.read', 'evidence.preview', 'evidence.export'];
 // The person at this machine. A tab this service served is authorized by the request itself:
 // same origin, loopback only, no link, no code and no expiry. `--pair` stays an explicit,
 // narrower grant for a shared or subfolder-scoped tab.
@@ -49,7 +50,7 @@ export const skillsMethods = ['skills.list', 'skills.read', 'skills.change', 'sk
 export function localBrowserPrincipal(root) {
     // The empty token hash can never match a request digest, so no header impersonates this
     // identity: it is chosen because the request carried no credential at all.
-    return { id: localBrowserId, kind: 'browser', tokenHash: '', projectRoot: root, methods: [...browserMethods, ...conversationMethods, ...consoleMethods, ...kernelMethods, ...skillsMethods] };
+    return { id: localBrowserId, kind: 'browser', tokenHash: '', projectRoot: root, methods: [...extensionMethods, ...browserMethods, ...conversationMethods, ...consoleMethods, ...kernelMethods, ...skillsMethods] };
 }
 export class BrowserAccess {
     state;

package/dist/capabilities.d.ts

@@ -64,6 +64,33 @@ export declare const personFilesSkill: {
         description: string;
     };
 };
+export declare const analysisRunSkillDeclaration: {
+    id: string;
+    version: string;
+    content: string;
+    digest: string;
+    intent: string;
+    requires: string[];
+    example: {
+        method: string;
+        input: {
+            language: string;
+            code: string;
+            purpose: string;
+            changeId: string;
+            waitMs: number;
+        };
+    };
+    failureRecipes: {
+        kind: string;
+        message: string;
+        next: string;
+    }[];
+    verify: {
+        command: string;
+        description: string;
+    };
+};
 export declare const taskMapSkill: {
     id: string;
     version: string;
@@ -130,7 +157,7 @@ export declare class Capabilities {
         enabled: string[];
     }, author: string): Promise<{
         version: number;
-        enabled: ("media" | "r" | "agent" | "files" | "documents" | "requirements" | "tables" | "charts" | "annotations" | "console" | "kernel" | "skills")[];
+        enabled: ("media" | "r" | "agent" | "files" | "skills" | "documents" | "requirements" | "tables" | "charts" | "annotations" | "console" | "kernel")[];
         receipt: CapabilityReceipt;
     }>;
     private pluginStatus;
@@ -165,7 +192,7 @@ export declare class Capabilities {
         }[];
         configuration: {
             version: number;
-            enabled: ("media" | "r" | "agent" | "files" | "documents" | "requirements" | "tables" | "charts" | "annotations" | "console" | "kernel" | "skills")[];
+            enabled: ("media" | "r" | "agent" | "files" | "skills" | "documents" | "requirements" | "tables" | "charts" | "annotations" | "console" | "kernel")[];
             retainedReceipts: number;
             retainedFromVersion: number;
             maxReceipts: number;

package/dist/capabilities.js

@@ -1,6 +1,7 @@
 import * as path from 'node:path';
 import { atomicJson, canonical, digest, now, readJson, requireThat, stateDirectory } from '@rho-workspace/plugin-contracts';
 import { operations } from './protocol.js';
+import { screenCheckSkill } from './screen-check-skill.js';
 export const capabilityLimits = { maxReceipts: 256 };
 // The umbrella Skill: what this application is, the order to work in, and the rules
 // that used to be discovered by failing. It names where the detail lives instead of
@@ -9,6 +10,11 @@ const applicationContent = [
     'Start with rho_index: select an owner or search, then rho_resolve only the operations',
     'needed now. Use rho_call with the complete contractRef. The private connection supplies',
     'the project; discovery never grants additional authority or starts a runtime.',
+    'Independent third-party plugins: extension.list shows installed packages, extension.describe',
+    'gives their digest, operations and Skill entries. Read extension.content (kind skill)',
+    'before extension.call. Keep expectedDigest and the original changeId for a native call;',
+    'extension.read observes pending or unknown outcomes without rerunning. Installation and',
+    'management belong to the local person; plugin code never expands this connection grant.',
     'Large replies carry a result reference. Use rho_read to inspect its fields and fetch',
     'only selected text ranges or array pages. Retain useful references; release finished',
     'results explicitly. Never repeat an action just to retrieve a large reply.',
@@ -29,7 +35,7 @@ const applicationContent = [
     'run or export it as files; a stopped run is not resubmitted under its own operationId.'
 ].join('\n');
 const applicationSkill = {
-    id: 'rho.workspace', version: '1.5', content: applicationContent,
+    id: 'rho.workspace', version: '1.6', content: applicationContent,
     intent: 'Work in this project through versioned operations, in a safe order.',
     requires: ['capability.list', 'observation.snapshot', 'action.submit', 'composition.apply', 'context.read'],
     example: { method: 'observation.snapshot', input: { projectId: 'the-open-project' } },
@@ -85,6 +91,77 @@ const personFiles = {
 };
 export const rhoWorkspaceSkill = { ...applicationSkill, digest: skillDigest };
 export const personFilesSkill = personFiles;
+// Written after five real analyses (bulk RNA-seq, snRNA-seq, GeoMx DSP, bulk plus a
+// metabolome, and a multi-omics cohort) ran through this application. None of them
+// finished unattended at the time: turns ended on a call limit or on a wait nothing
+// wakes, calls went into looking for what may be done rather than doing it, and results
+// were not always written before the turn ended. Several of those stops have since been
+// fixed in this application, so what follows is written as the practice that survived
+// them rather than as a workaround for one build's limits.
+const analysisRunContent = [
+    'A whole analysis has to survive interruption. Rho keeps no step cap and no wall time',
+    'by default, and a long analysis may still be stopped by the person or by the Agent',
+    'client, so write results as you go instead of holding them until the end.',
+    '',
+    '1. Spend calls on the analysis, not on discovery. Resolve the operations you will use',
+    '   once each (kernel.run, kernel.read, kernel.interrupt, resource.list) and reuse the',
+    '   contractRef you were given. In the runs behind this Skill one Agent spent 36',
+    '   capability.index calls in a single analysis and ended with only its quality-control',
+    '   table written.',
+    '2. Do not guess what a result reference contains. A refused read means the shape is',
+    '   wrong, not that the result is missing: resolve the operation that produced it and',
+    '   read the page or range it names instead of trying sibling paths.',
+    '3. Nothing wakes you later. No monitor, timer or event resumes your turn: a cell still',
+    '   running when you stop is left running for nobody, and ending your reply is not',
+    '   proof the analysis finished. Pass a waitMs long enough for the slowest step (a',
+    '   normalisation over 90,000 nuclei can take many minutes), or read the cell with',
+    '   kernel.read in your own next call.',
+    '4. Load once, build on it. A session keeps what a cell defines, so read the data in one',
+    '   cell and derive in the next. A service restart does not keep those objects: the code',
+    '   and its outputs stay, the values in memory do not, so keep a script that rebuilds',
+    '   what matters.',
+    '5. Prefer a few large cells to many small ones, and keep each short enough to finish. A',
+    '   cell that hangs costs time: interrupt it with kernel.interrupt and continue with the',
+    '   part that is cheap to redo.',
+    '6. Draw to an explicit device. In these runs a ggsave call in the shared session hung',
+    '   and the figure had to be redrawn with png() and dev.off(): open the device, plot,',
+    '   close it, and let the figure land in a file you name.',
+    '7. Write each file once, complete, and save it to disk before you rely on it. One script',
+    '   written in full and then run costs less than the same script edited piece by piece,',
+    '   and a file on disk is the only version that outlives a stop.',
+    '8. Check packages in one call, and do not install into a temporary library. Name what is',
+    '   missing, and when you substitute a gene-set source or an annotation build, say so',
+    '   beside the result, because that choice changes the numbers.',
+    '9. Say what did not reproduce, and why. When a published count cannot be matched, name',
+    '   the undefined choice (a threshold, a direction, a model) and compute the cheap',
+    '   alternatives beside your main one instead of tuning until it fits.',
+    '10. Report the state you actually reached. Say which outputs exist on disk, which cell',
+    '   was still running, and what a stopped turn left behind; the person continues from',
+    '   that record rather than from a claim that the work is done.',
+].join('\n');
+const analysisRunSkill = {
+    id: 'rho.analysis-run', version: '1.1', content: analysisRunContent,
+    digest: digest(analysisRunContent),
+    intent: 'Run a whole analysis through the live sessions so a stop never loses the work.',
+    requires: ['kernel.run', 'kernel.read', 'kernel.interrupt', 'resource.list'],
+    example: {
+        method: 'kernel.run',
+        input: {
+            language: 'r',
+            code: 'counts <- read.csv("data/counts.csv", row.names = 1); dim(counts)',
+            purpose: 'Load the count matrix once and keep it for later cells',
+            changeId: 'load-counts',
+            waitMs: 120000
+        }
+    },
+    failureRecipes: [
+        { kind: 'not_found', message: 'Skill is not available in this project and session.', next: 'Read skill.list for the Skills this project and session expose; a Skill owned by a disabled plugin is not listed.' },
+        { kind: 'stale', message: 'Skill content digest changed.', next: 'Read the Skill again and apply the current text; do not act on a cached copy.' },
+        { kind: 'limit', message: 'Too many cells are waiting.', next: 'Wait for the running cell or interrupt it, then continue in a new cell with a new changeId.' }
+    ],
+    verify: { command: 'npm run test:notebook', description: 'Runs R and Python cells, keeps their output, plots and variables, interrupts and stops sessions, and keeps identity across a restart.' }
+};
+export const analysisRunSkillDeclaration = analysisRunSkill;
 const taskMapContent = [
     'Describe the whole task yourself: Rho fixes no closed list of kinds or states.',
     '',
@@ -240,7 +317,7 @@ export class Capabilities {
     }
     async skills(principal) {
         const state = await this.state();
-        const result = [rhoWorkspaceSkill, personFilesSkill, taskMapSkill];
+        const result = [rhoWorkspaceSkill, personFilesSkill, taskMapSkill, analysisRunSkill, screenCheckSkill];
         for (const descriptor of this.plugins.descriptors()) {
             const status = this.pluginStatus(descriptor.id, state);
             for (const skill of descriptor.skills ?? []) {