@rho-workspace/rho 0.5.6 → 0.5.7

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

@@ -1,6 +1,6 @@
 # Notebook
 
-`@rho-workspace/plugin-kernel` 0.5.4 keeps a live R session and a live Python
+`@rho-workspace/plugin-kernel` 0.5.7 keeps a live R session and a live Python
 session for a project, which an Agent and the person share, on this machine or on a
 server: one the person manages with serverctl, reached through it, or one reached with
 ssh.
@@ -17,7 +17,27 @@ device that stays open for the session, as the console's does: a later cell can
 over an earlier cell's plot (a line over its points) and reports the plot it changed,
 and each page is recorded before a new one starts, so a sourced script that draws two
 plots keeps both. Calls that only set graphics state (`par`, `palette`, `layout`) do not
-make a page new. Python closes its figures after each cell. After each cell the
+make a page new. A host constructed with `extensions.r` and `extensions.python` hands those
+files to each local R or Python session it starts (`RHO_KERNEL_EXTENSIONS`); the Figures
+plugin's describers are such files,
+and a plot it described names its `figure` (layers, marks, how many are bound) or why it
+was not described (`figureProblem`), and `figureRecord` returns the record beside the
+PNG. A page the code saves to a project file on a device of its own (`ggsave`) is found by
+the extension's `saved_page()` and described when the cell ends, at the size it was saved
+at; the cell's `saved` names each such file with its bytes and SHA-256 and the figure's
+summary or `figureProblem`, and `savedFigure(sha256)` returns the record of the newest cell
+that saved those bytes. A file written again since has other bytes and no record. A device
+the code opens on a file (`png()`, `jpeg()`, `tiff()`, `bmp()`, `svg()`, `pdf()`, `cairo_pdf()`)
+is noted with its file: the runner traces those functions and `dev.off()` in grDevices, so
+`png` prints as a traced function. Its pages are recorded as they are drawn, and when
+`dev.off()` closes it the last page (each page, for a name numbered with `%d`) is offered to
+the extension like a ggsave page; a PDF of several pages is named with a `figureProblem`. A
+device the code left open stays the current device in the next cell. A device opened through a
+copy a package imported before the session started is not seen.
+In Python, `Figure.savefig` (and so `plt.savefig`) is watched once `matplotlib.figure` is
+imported: a figure saved to a file in the project is described as savefig wrote it and named
+in `saved` when the cell ends, also when the cell closed the figure. Python closes its
+figures after each cell. After each cell the
 session lists its variables with their type, size and a one-line summary.
 Each cell also names the values it made or changed (`defined`) and, when neither list
 was cut, those it removed (`removed`). It names the values it read (`used`): the names
@@ -187,7 +207,11 @@ The page supplies the scoped client and the project's facts (`UiSnapshot`: the p
 the page's cursor and the conversations, so a cell names the Agent that ran it), and
 callbacks to open a value, a server's file or a conversation as it places them. Inside a
 conversation's record it passes a `SessionScope`: the cells that conversation's Agent and
-the person ran since it began, up to the moment shown. `KernelShell` takes the page's code
+the person ran since it began, up to the moment shown. Native clients sharing a connection
+can supply `cellIds` from their retained tool receipts; these select exact Agent cells
+instead of treating the connection principal as one conversation. An empty list claims
+no Agent cells. This selection does not reconstruct earlier output states.
+`KernelShell` takes the page's code
 highlighting and Markdown; without them code stays plain and a server's skill shows as
 written. The views add their own styles once, in the page's color and type variables, and
 use its base controls (`text-button`, `primary`, `secondary`, `inline-error`).

package/node_modules/@rho-workspace/plugin-kernel/dist/contract.d.ts

@@ -105,12 +105,24 @@ export declare const sessionSchema: {
     properties: Record<string, unknown>;
     required: string[];
 };
+export declare const figureSummarySchema: {
+    type: string;
+    additionalProperties: boolean;
+    properties: Record<string, unknown>;
+    required: string[];
+};
 export declare const outputSchema: {
     type: string;
     additionalProperties: boolean;
     properties: Record<string, unknown>;
     required: string[];
 };
+export declare const savedFigureSchema: {
+    type: string;
+    additionalProperties: boolean;
+    properties: Record<string, unknown>;
+    required: string[];
+};
 export declare const cellSchema: {
     type: string;
     additionalProperties: boolean;

package/node_modules/@rho-workspace/plugin-kernel/dist/contract.js

@@ -72,7 +72,12 @@ export const sessionSchema = obj({
     // (.venv/bin/python). Sessions recorded before have none.
     program: maybe({ type: 'string' }),
 }, ['sessionId', 'language', 'state', 'version', 'pid', 'startedAt', 'startedBy', 'endedAt', 'ending', 'stop', 'problem', 'variables', 'variablesOmitted', 'variablesAt', 'cells']);
-export const outputSchema = obj({ kind: { enum: ['stdout', 'stderr', 'warning', 'error', 'plot'] }, text: { type: 'string' }, plot: { type: 'integer', minimum: 1 }, width: { type: 'integer' }, height: { type: 'integer' } }, ['kind']);
+// A described plot names what it drew: its describer, layers, marks and how many are bound to rows.
+export const figureSummarySchema = obj({ describer: text, kind: { type: 'string' }, title: { type: 'string' }, layers: { type: 'integer', minimum: 0 }, marks: { type: 'integer', minimum: 0 }, bound: { type: 'integer', minimum: 0 }, geoms: { type: 'array', items: { type: 'string' } } }, ['describer', 'layers', 'marks', 'bound', 'geoms']);
+export const outputSchema = obj({ kind: { enum: ['stdout', 'stderr', 'warning', 'error', 'plot'] }, text: { type: 'string' }, plot: { type: 'integer', minimum: 1 }, width: { type: 'integer' }, height: { type: 'integer' }, figure: figureSummarySchema, figureProblem: { type: 'string' } }, ['kind']);
+// A page the cell saved to a project file (ggsave) that an extension described: the file as the
+// cell left it, and the figure's summary or why it has none.
+export const savedFigureSchema = obj({ number: { type: 'integer', minimum: 1 }, path: text, bytes: { type: 'integer', minimum: 0 }, sha256: { type: 'string', pattern: '^[a-f0-9]{64}$' }, figure: figureSummarySchema, figureProblem: { type: 'string' } }, ['number', 'path', 'bytes', 'sha256']);
 export const cellSchema = obj({
     cellId, changeId, by: text, sessionId, language, code: { type: 'string' }, purpose: maybe({ type: 'string' }),
     queuedAt: time, startedAt: maybe(time), endedAt: maybe(time), state: { enum: [...cellStates] },
@@ -92,6 +97,8 @@ export const cellSchema = obj({
     used: { type: 'array', items: text }, files: { type: 'array', items: obj({ path: text, how: { enum: ['read', 'wrote'] } }) },
     // The program and version that ran it. Cells recorded before have neither.
     program: maybe({ type: 'string' }), version: maybe({ type: 'string' }),
+    // Plots the code saved to project files, each kept as a figure of the file's bytes.
+    saved: { type: 'array', items: savedFigureSchema },
 }, ['cellId', 'changeId', 'by', 'sessionId', 'language', 'code', 'purpose', 'queuedAt', 'startedAt', 'endedAt', 'state', 'number', 'outputs', 'bytes', 'kept', 'cut', 'interrupt', 'problem']);
 // One value of a live session as its session describes it: the kind of thing it is, short facts,
 // and one page of its rows, its elements or its parts, each part with the code that reaches it.

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

@@ -46,6 +46,16 @@ export interface Asked {
     by: string;
     at: string;
 }
+export interface FigureSummary {
+    describer: string;
+    kind?: string;
+    title?: string;
+    layers: number;
+    marks: number;
+    bound: number;
+    geoms: string[];
+    notes?: string[];
+}
 export type Output = {
     kind: 'stdout' | 'stderr' | 'warning' | 'error';
     text: string;
@@ -54,7 +64,17 @@ export type Output = {
     plot: number;
     width: number;
     height: number;
+    figure?: FigureSummary;
+    figureProblem?: string;
 };
+export interface SavedFigure {
+    number: number;
+    path: string;
+    bytes: number;
+    sha256: string;
+    figure?: FigureSummary;
+    figureProblem?: string;
+}
 export interface CellRecord {
     cellId: string;
     changeId: string;
@@ -83,6 +103,7 @@ export interface CellRecord {
     }>;
     program?: string | null;
     version?: string | null;
+    saved?: SavedFigure[];
 }
 export type InspectInput = {
     language: Language;
@@ -105,6 +126,7 @@ export declare const kernelLimits: {
     maxOutputBytes: number;
     maxPlots: number;
     maxPlotBytes: number;
+    maxFigureBytes: number;
     maxVariables: number;
     maxWaitMs: number;
     startTimeoutMs: number;
@@ -157,6 +179,10 @@ export declare class KernelHost {
         ssh?: string;
         serverctl?: string;
         onChange?: () => void;
+        extensions?: {
+            r?: string[];
+            python?: string[];
+        };
     });
     private program;
     private named;
@@ -268,6 +294,41 @@ export declare class KernelHost {
         width: number;
         height: number;
     }>;
+    figureRecord(cellId: string, plot: number): Promise<{
+        cell: {
+            cellId: string;
+            number: number;
+            by: string;
+            purpose: string | null;
+            code: string;
+            language: "r" | "python";
+            endedAt: string | null;
+            sessionId: string;
+        };
+        output: {
+            kind: "plot";
+            plot: number;
+            width: number;
+            height: number;
+            figure?: FigureSummary;
+            figureProblem?: string;
+        };
+        bytes: NonSharedBuffer;
+    }>;
+    savedFigure(sha256: string): Promise<{
+        cell: {
+            cellId: string;
+            number: number;
+            by: string;
+            purpose: string | null;
+            code: string;
+            language: "r" | "python";
+            endedAt: string | null;
+            sessionId: string;
+        };
+        output: SavedFigure;
+        bytes: NonSharedBuffer;
+    }>;
     close(): Promise<void>;
 }
 export declare const plugin: {

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

@@ -4,7 +4,8 @@ import { constants as fsConstants } from 'node:fs';
 import net from 'node:net';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
+import { createReadStream } from 'node:fs';
 import { atomicBytes, atomicJson, confined, digest, now, readJson, requireThat, stateDirectory, timelineLabel } from '@rho-workspace/plugin-contracts';
 import { ownGroup, signalGroup } from './process-group.js';
 import { checkCommand, copyCommand, listCommand, readCheck, readCopy, readList, sessionCommand, signalCommand, Ssh } from './places.js';
@@ -14,9 +15,10 @@ import { operationPresentation, presentation, viewPresentations } from './presen
 // The protected resources are this machine's processes and memory, and the project's state
 // folder. At most one session runs per language, and at most maxQueued cells wait in each. A
 // cell keeps its first maxOutputBytes of output (the rest is counted) and at most maxPlots
-// plots of at most maxPlotBytes each; at most maxCells cells are kept, the oldest going first
-// with their plots. The session lists at most maxVariables variables. A run waits at most
-// maxWaitMs for its cell. What a session's own code allocates is not bounded here.
+// plots of at most maxPlotBytes each, each with a figure record of at most maxFigureBytes; at
+// most maxCells cells are kept, the oldest going first with their plots. The session lists at
+// most maxVariables variables. A run waits at most maxWaitMs for its cell. What a session's own
+// code allocates is not bounded here.
 // Reading a value shows at most inspectColumns columns, a page of at most 200 rows, elements or
 // parts (inspectRows unless asked), cells of inspectCellChars characters and a printed form of
 // inspectTextBytes; a table sorts only up to inspectSortRows rows. A reading that takes longer
@@ -32,11 +34,37 @@ export const lineageLimits = { files: 32 };
 // after serverctlReadMs; a session through serverctl lasts at most serverctlSessionS, serverctl's
 // own limit for a command, after which serverctl ends it; a server's skill is read up to
 // serverSkillBytes.
-export const kernelLimits = { maxCells: 500, maxQueued: 16, maxCodeBytes: 65536, maxOutputBytes: 256 * 1024, maxPlots: 8, maxPlotBytes: 4 * 1024 * 1024, maxVariables: 200, maxWaitMs: 600000, startTimeoutMs: 30000, stopGraceMs: 3000, maxEndedSessions: 20,
+export const kernelLimits = { maxCells: 500, maxQueued: 16, maxCodeBytes: 65536, maxOutputBytes: 256 * 1024, maxPlots: 8, maxPlotBytes: 4 * 1024 * 1024, maxFigureBytes: 16 * 1024 * 1024, maxVariables: 200, maxWaitMs: 600000, startTimeoutMs: 30000, stopGraceMs: 3000, maxEndedSessions: 20,
     inspectRows: 50, inspectColumns: 50, inspectChildren: 200, inspectCellChars: 120, inspectTextBytes: 16 * 1024, inspectSortRows: 1000000, inspectTimeoutMs: 10000, inspectGiveUpMs: 5000,
     maxPlaces: 16, remoteStartTimeoutMs: 90000, remoteCheckTimeoutMs: 60000, remoteListTimeoutMs: 30000, remoteSignalTimeoutMs: 15000, remoteEntries: 500, remoteListBytes: 1024 * 1024, remoteCopyBytes: 64 * 1024 * 1024, remoteCopyTimeoutMs: 600000, maxCopies: 500,
     serverctlReadMs: 15000, serverctlSessionS: 7 * 24 * 3600, serverSkillBytes: 256 * 1024 };
 const markStart = '\x1eRHO:';
+// The SHA-256 of a file's bytes, read in chunks.
+async function fileDigest(file) {
+    const hash = createHash('sha256');
+    let bytes = 0;
+    for await (const chunk of createReadStream(file)) {
+        hash.update(chunk);
+        bytes += chunk.length;
+    }
+    return { sha256: hash.digest('hex'), bytes };
+}
+// What an extension said of a plot, cut to the summary a cell keeps.
+function figureSummary(value) {
+    const n = (x) => Number.isSafeInteger(x) && x >= 0 ? x : 0;
+    const t = (x) => typeof x === 'string' ? x.slice(0, 200) : undefined;
+    const geoms = Array.isArray(value.geoms) ? value.geoms : typeof value.geoms === 'string' ? [value.geoms] : [];
+    return { describer: t(value.describer) ?? 'unknown', ...(t(value.kind) ? { kind: t(value.kind) } : {}), ...(t(value.title) ? { title: t(value.title) } : {}),
+        layers: n(value.layers), marks: n(value.marks), bound: n(value.bound), geoms: geoms.filter((g) => typeof g === 'string').slice(0, 32).map((g) => g.slice(0, 64)),
+        // What the describer noticed about the figure (marks drawn elsewhere than their values, labels
+        // naming other rows than the values they sit beside), so the Agent reads it with the cell.
+        ...(Array.isArray(value.notes) && value.notes.length ? { notes: value.notes.filter((t) => typeof t === 'string').slice(0, 4).map((t) => t.slice(0, 300)) } : {}) };
+}
+// R on Windows sets these categories from the environment, and Windows has no C.UTF-8: given one,
+// as an Agent's Git Bash gives LC_CTYPE, R warns at startup, runs in the C locale and prints
+// "3 × 2" as "3 <U+00D7> 2". Without them a session takes the system's own locale, UTF-8 there.
+const posixUtf8 = /^(C|POSIX)\.UTF-?8$/i, rLocale = /^LC_(ALL|CTYPE|COLLATE|TIME|MONETARY)$/;
+const windowsEnvironment = (env) => Object.fromEntries(Object.entries(env).filter(([name, value]) => !(rLocale.test(name.toUpperCase()) && posixUtf8.test(value ?? ''))));
 // On Windows a session's descriptor 3 reaches a program built on Microsoft's C runtime (Python),
 // but R has no way to name it. There R opens a named pipe served here, by the name it is given in
 // RHO_KERNEL_ANSWERS; the first connection is the session's and no other is taken.
@@ -104,6 +132,8 @@ export class KernelHost {
     placesWriting = Promise.resolve();
     ssh;
     serverctl;
+    // extensions.r and extensions.python: files a local session loads to describe what its plots draw
+    // (the figures plugin's). A session on a server has none: its plots stay pictures.
     constructor(root, options = {}) {
         this.root = root;
         this.options = options;
@@ -210,7 +240,10 @@ export class KernelHost {
                 const [old] = this.cells.splice(index, 1);
                 for (const output of old.outputs)
                     if (output.kind === 'plot')
-                        await fs.rm(path.join(await this.plots(), `${old.cellId}-${output.plot}.png`), { force: true });
+                        for (const end of ['.png', '.figure.json'])
+                            await fs.rm(path.join(await this.plots(), `${old.cellId}-${output.plot}${end}`), { force: true });
+                for (const saved of old.saved ?? [])
+                    await fs.rm(path.join(await this.plots(), `${old.cellId}-s${saved.number}.figure.json`), { force: true });
             }
             live.record.cells++;
             const cell = { cellId: id('k-'), changeId: input.changeId, by: input.by, sessionId: live.record.sessionId, language: input.language, code: input.code, purpose: input.purpose?.trim().slice(0, 200) || null,
@@ -269,7 +302,7 @@ export class KernelHost {
         const runner = source && `.cache/rho/kernel/runner-${digest(source).slice(0, 16)}${language === 'r' ? '.R' : '.py'}`;
         const pipe = windows && language === 'r' ? await answerPipe() : null;
         const child = place ? await this.transport(place).spawn(place, sessionCommand(place, language === 'r' ? 'Rscript' : 'python3', runner, source.length), root)
-            : spawn(program, [runners[language], root], { cwd: root, ...ownGroup, stdio: ['pipe', 'pipe', 'pipe', 'pipe'], env: { ...process.env, MPLBACKEND: 'Agg', PYTHONUNBUFFERED: '1', ...(pipe ? { RHO_KERNEL_ANSWERS: pipe.name } : {}) } });
+            : spawn(program, [runners[language], root], { cwd: root, ...ownGroup, stdio: ['pipe', 'pipe', 'pipe', 'pipe'], env: { ...(windows ? windowsEnvironment(process.env) : process.env), MPLBACKEND: 'Agg', PYTHONUNBUFFERED: '1', ...(pipe ? { RHO_KERNEL_ANSWERS: pipe.name } : {}), ...(this.options.extensions?.[language]?.length ? { RHO_KERNEL_EXTENSIONS: this.options.extensions[language].join(path.delimiter) } : {}) } });
         let settle = () => { };
         const ended = new Promise(resolve => { settle = resolve; });
         const live = { started: selected, root, ended, settle, record, child, place, remotePid: null, answers: '', early: '', order: Promise.resolve(), queue: [], current: null, stopping: false, printed: '', mark: 0, held: [], answered: 0, looking: null, lookups: Promise.resolve(), pipe: pipe?.server };
@@ -523,8 +556,52 @@ export class KernelHost {
             else {
                 if (data)
                     await atomicBytes(path.join(plots, `${cell.cellId}-${number}.png`), data);
-                cell.outputs.push({ kind: 'plot', plot: number, width: Number(msg.width) || 0, height: Number(msg.height) || 0 });
+                const output = { kind: 'plot', plot: number, width: Number(msg.width) || 0, height: Number(msg.height) || 0 };
+                const figure = path.join(plots, `${cell.cellId}-${number}.figure.json`);
+                if (!live.place && msg.figure && typeof msg.figure === 'object') {
+                    const bytes = await fs.stat(figure).then(s => s.size, () => -1);
+                    if (bytes < 0)
+                        output.figureProblem = 'The figure record was not written.';
+                    else if (bytes > this.limits.maxFigureBytes) {
+                        await fs.rm(figure, { force: true });
+                        output.figureProblem = `The figure record of ${bytes} bytes was larger than maxFigureBytes and was not kept.`;
+                    }
+                    else
+                        output.figure = figureSummary(msg.figure);
+                }
+                else if (typeof msg.figureProblem === 'string')
+                    output.figureProblem = msg.figureProblem.slice(0, 500);
+                cell.outputs.push(output);
+            }
+            this.soon();
+            return;
+        }
+        if (msg.kind === 'saved') {
+            // A file in the project the cell saved a plot to, read as the cell left it.
+            const number = Number(msg.number), relative = typeof msg.path === 'string' ? msg.path : '';
+            if (live.place || !Number.isSafeInteger(number) || number < 1 || number > this.limits.maxPlots || (cell.saved ?? []).some(s => s.number === number))
+                return;
+            const file = relative.length <= 512 ? await confined(this.root, relative).catch(() => null) : null;
+            const stat = file ? await fs.stat(file).catch(() => null) : null;
+            if (!file || !stat?.isFile())
+                return;
+            const { sha256, bytes } = await fileDigest(file);
+            const saved = { number, path: relative, bytes, sha256 };
+            const record = path.join(await this.plots(), `${cell.cellId}-s${number}.figure.json`);
+            if (msg.figure && typeof msg.figure === 'object') {
+                const size = await fs.stat(record).then(s => s.size, () => -1);
+                if (size < 0)
+                    saved.figureProblem = 'The figure record was not written.';
+                else if (size > this.limits.maxFigureBytes) {
+                    await fs.rm(record, { force: true });
+                    saved.figureProblem = `The figure record of ${size} bytes was larger than maxFigureBytes and was not kept.`;
+                }
+                else
+                    saved.figure = figureSummary(msg.figure);
             }
+            else
+                saved.figureProblem = typeof msg.figureProblem === 'string' ? msg.figureProblem.slice(0, 500) : 'Nothing described what this file draws.';
+            (cell.saved ??= []).push(saved);
             this.soon();
             return;
         }
@@ -764,6 +841,44 @@ export class KernelHost {
         const data = await fs.readFile(path.join(await this.plots(), `${cellId}-${plot}.png`));
         return { mediaType: 'image/png', data: data.toString('base64'), width: output.width, height: output.height };
     }
+    // The figure record an extension kept for a plot, as it wrote it; the figures plugin reads it.
+    async figureRecord(cellId, plot) {
+        await this.load();
+        const cell = this.cells.find(c => c.cellId === cellId);
+        requireThat(cell, 'not_found', 'This cell is not in the session record.');
+        const output = cell.outputs.find(o => o.kind === 'plot' && o.plot === plot);
+        requireThat(output, 'not_found', 'This cell kept no such plot.');
+        requireThat(output.figure, 'not_found', output.figureProblem ?? 'This plot is a picture only: nothing described what it draws.');
+        const file = path.join(await this.plots(), `${cellId}-${plot}.figure.json`);
+        const stat = await fs.stat(file).catch(() => null);
+        requireThat(stat && stat.size <= this.limits.maxFigureBytes, 'not_found', 'The figure record is no longer kept.');
+        return { cell: { cellId: cell.cellId, number: cell.number, by: cell.by, purpose: cell.purpose, code: cell.code, language: cell.language, endedAt: cell.endedAt, sessionId: cell.sessionId }, output: structuredClone(output), bytes: await fs.readFile(file) };
+    }
+    // The figure a cell kept for a file it saved, found by the file's bytes: the newest cell that saved
+    // those bytes. A file written since by anything else has other bytes and no figure.
+    async savedFigure(sha256) {
+        await this.load();
+        let problem;
+        for (const cell of [...this.cells].reverse())
+            for (const saved of [...(cell.saved ?? [])].reverse()) {
+                if (saved.sha256 !== sha256)
+                    continue;
+                if (!saved.figure) {
+                    problem ??= saved.figureProblem;
+                    continue;
+                }
+                const file = path.join(await this.plots(), `${cell.cellId}-s${saved.number}.figure.json`);
+                const stat = await fs.stat(file).catch(() => null);
+                if (!stat || stat.size > this.limits.maxFigureBytes) {
+                    problem ??= 'The figure record is no longer kept.';
+                    continue;
+                }
+                return { cell: { cellId: cell.cellId, number: cell.number, by: cell.by, purpose: cell.purpose, code: cell.code, language: cell.language, endedAt: cell.endedAt, sessionId: cell.sessionId }, output: structuredClone(saved), bytes: await fs.readFile(file) };
+            }
+        // A file a cell saved but could not describe says why; one no cell saved is simply a picture.
+        requireThat(false, 'not_found', problem ?? 'No Notebook cell saved a figure as this file with these bytes: it is a picture only.', problem ? { saved: true } : {});
+        throw new Error('unreachable');
+    }
     // Closing ends the sessions: their variables live only in their processes.
     async close() {
         const exits = [...this.live.values()].map(live => new Promise(resolve => {
@@ -804,7 +919,8 @@ const content = [
     'To look at data, check a value or try a model, run code with kernel.run (language "r" or "python") instead of a one-off Rscript -e or python3 -c: what you define stays in the session for the next cell, and the person sees each cell, its output, its plots and the variables.',
     'Give each cell a short purpose. Pass waitMs to wait for it to finish; kernel.read reads it later.',
     'A session starts with the first cell of its language. Interrupt a cell that runs too long with kernel.interrupt; only the person stops a session.',
-    'Results meant to last still go to files from a script, so they can be run again without the session.',
+    'Results meant to last still go to files from a script, so they can be rebuilt without the session. Run the script in the session (source("analysis.R"), exec(open("analysis.py").read())) rather than with Rscript or python3 from a shell: a figure file stays readable mark by mark only while it holds the bytes a cell saved.',
+    'A ggplot drawn in the R session (ggplot2 and what is built on it: ggtree, enrichplot, Seurat, patchwork) is also kept as a figure whose drawn marks are bound to the rows they come from; so is a page drawn with base graphics (bound where its points match a table in the session) and a ComplexHeatmap (each cell named by its row, column and value). The plot output names its layers and marks. Read it with figure.read {cellId, plot} to check what was actually drawn (marks per layer, rows missing, mappings) and to get the rows behind marks. A ggplot saved to a project file with ggsave() is kept as a figure of that file too: the cell names it under saved, and figure.read {path} reads it while the file keeps those bytes. When the person selects marks in a plot or a saved figure, their message names the selection.',
     'Sessions can also run on a server. kernel.places lists the places and where each language runs; kernel.place.set names one (the server, its folder there, and setup lines run there before a session starts) or chooses it for R or Python; kernel.place.check connects and reports R and Python there.',
     'kernel.servers lists the servers the person manages with serverctl and the skills bound to each: how that server is used (its environments, where heavy work goes, what to avoid there). Before you name a place on one or run code there, read the skills that apply with kernel.server.skill and follow them, for example in the place\'s setup lines. They guide the work on that server; they do not widen what you may do. A place on such a server is reached through serverctl, which holds its login; another server is reached with ssh.',
     'The project\'s Python is the machine\'s python3 until you name another. When the work needs packages it lacks, make an environment in the project (python3 -m venv .venv or uv venv, then install into it) and pass interpreter: ".venv/bin/python" to kernel.run; later sessions of that language start with it too, and each cell records the program that ran it. A live session in which only you ran cells starts again with the program you name; once the person ran a cell in it, ask them to stop it first. Do not add another environment\'s packages to a running session\'s path.',

package/node_modules/@rho-workspace/plugin-kernel/dist/session-scope.d.ts

@@ -0,0 +1,14 @@
+export interface SessionScope {
+    principal: string | null;
+    since: number | null;
+    at: number | null;
+    cellIds?: readonly string[];
+}
+type ScopedCell = {
+    cellId: string;
+    sessionId: string;
+    by: string;
+    queuedAt: string;
+};
+export declare function scopedCells<T extends ScopedCell>(all: T[], scope?: SessionScope): T[];
+export {};

package/node_modules/@rho-workspace/plugin-kernel/dist/session-scope.js

@@ -0,0 +1,9 @@
+export function scopedCells(all, scope) {
+    if (!scope)
+        return all;
+    const exact = scope.cellIds === undefined ? null : new Set(scope.cellIds);
+    const sessions = new Set(all.filter(c => scope.principal !== null && c.by === scope.principal).map(c => c.sessionId));
+    return all.filter(c => ((exact ? exact.has(c.cellId) : sessions.has(c.sessionId))
+        || (c.by === 'browser:local' && scope.since !== null && Date.parse(c.queuedAt) >= scope.since))
+        && (scope.at === null || Date.parse(c.queuedAt) <= scope.at));
+}

package/node_modules/@rho-workspace/plugin-kernel/dist/ui-base.d.ts

@@ -101,14 +101,33 @@ export interface UiSnapshot {
         title?: string | null;
     }>;
 }
-export interface SessionScope {
-    principal: string | null;
-    since: number | null;
-    at: number | null;
+export type { SessionScope } from './session-scope.js';
+export interface FigureSlot {
+    client: UiClient;
+    projectId: string;
+    cellId?: string;
+    plot?: number;
+    file?: {
+        path?: string;
+        sha256: string;
+    };
+    width?: number;
+    height?: number;
+    label: string;
+    name?: string;
+    fit?: boolean;
+    cursor?: number;
+    fallback: ReactNode;
+    author?: (by: string) => {
+        name: string;
+        mine: boolean;
+    };
 }
 export interface KernelShell {
     highlight?(code: string, language: string): Promise<DocumentFragment | null>;
+    openPath?(path: string): void;
     markdown?(text: string): ReactNode;
+    figure?(slot: FigureSlot): ReactNode;
 }
 export declare const ShellProvider: import("react").Provider<KernelShell>;
 export declare const useShell: () => KernelShell;
@@ -123,4 +142,3 @@ export declare function when(iso: string, now?: Date): {
     text: string;
     full: string;
 };
-export {};

package/node_modules/@rho-workspace/plugin-kernel/dist/ui-notebook-work.js

@@ -34,5 +34,5 @@ export function NotebookWorkSection({ work, snapshot, onOpen }) {
     const sessions = [...(read?.sessions ?? [])].filter(s => s.cells > 0)
         .sort((a, b) => Number(a.state === 'ended') - Number(b.state === 'ended') || b.startedAt.localeCompare(a.startedAt)).slice(0, notebookWorkLimits.sessions);
     const newest = [...(read?.cells ?? [])].reverse(), earlier = Math.max(0, cells - newest.length);
-    return _jsxs("section", { className: "project-section notebook-work", "aria-labelledby": "notebook-work-title", children: [_jsxs("div", { className: "section-heading", children: [_jsx("h2", { id: "notebook-work-title", children: "Notebook" }), _jsx("button", { className: "text-button", onClick: onOpen, children: "Open Notebook" })] }), problem && _jsx("p", { role: "alert", children: problem }), sessions.length > 0 && _jsx("ul", { className: "notebook-work-sessions", children: sessions.map(s => _jsxs("li", { children: [_jsx(Icon, { name: s.place ? 'server' : 'code', size: 15 }), _jsxs("span", { children: [_jsx("strong", { children: versionOf(s) }), " ", s.place ? 'on ' + s.place.label : 'on this machine'] }), _jsxs("small", { children: [s.state === 'ended' ? 'ended' : s.state, " \u00B7 ", s.cells, " ", s.cells === 1 ? 'cell' : 'cells', s.state !== 'ended' ? ` · ${s.variables.length + s.variablesOmitted} ${s.variables.length + s.variablesOmitted === 1 ? 'value' : 'values'}` : ''] })] }, s.sessionId)) }), newest.length > 0 && _jsx("div", { className: "activity-list", children: newest.map(cell => _jsxs("button", { className: "activity-row", onClick: () => { askCell(cell.cellId); onOpen(); }, children: [_jsx("span", { className: 'activity-symbol' + (cell.state === 'running' || cell.state === 'queued' ? ' active' : ''), children: _jsx(Icon, { name: "code", size: 16 }) }), _jsxs("span", { className: "activity-name", children: [_jsx("strong", { children: cell.purpose || firstLine(cell.code) }), _jsxs("small", { children: [author(cell.by), " \u00B7 ", when(cell.endedAt ?? cell.startedAt ?? cell.queuedAt).text, stateWords[cell.state] ? ' · ' + stateWords[cell.state] : ''] })] }), _jsx(Icon, { name: "chevron", size: 13 })] }, cell.cellId)) }), earlier > 0 && _jsxs("p", { className: "quiet-empty", children: [earlier, " earlier ", earlier === 1 ? 'cell' : 'cells', " in the Notebook"] })] });
+    return _jsxs("section", { className: "project-section notebook-work", "aria-labelledby": "notebook-work-title", children: [_jsxs("div", { className: "section-heading", children: [_jsx("h2", { id: "notebook-work-title", children: "Notebook" }), _jsx("button", { className: "text-button", onClick: onOpen, children: "Open Notebook" })] }), problem && _jsx("p", { role: "alert", children: problem }), sessions.length > 0 && _jsx("ul", { className: "notebook-work-sessions", children: sessions.map(s => _jsxs("li", { children: [_jsx(Icon, { name: s.place ? 'server' : 'code', size: 15 }), _jsxs("span", { children: [_jsx("strong", { children: versionOf(s) }), " ", s.place ? 'on ' + s.place.label : s.state !== 'ended' ? 'on this machine' : ''] }), _jsxs("small", { children: [s.state === 'ended' ? 'ended' : s.state, " \u00B7 ", s.cells, " ", s.cells === 1 ? 'cell' : 'cells', s.state !== 'ended' ? ` · ${s.variables.length + s.variablesOmitted} ${s.variables.length + s.variablesOmitted === 1 ? 'value' : 'values'}` : ''] })] }, s.sessionId)) }), newest.length > 0 && _jsx("div", { className: "activity-list", children: newest.map(cell => _jsxs("button", { className: "activity-row", onClick: () => { askCell(cell.cellId); onOpen(); }, children: [_jsx("span", { className: 'activity-symbol' + (cell.state === 'running' || cell.state === 'queued' ? ' active' : ''), children: _jsx(Icon, { name: "code", size: 16 }) }), _jsxs("span", { className: "activity-name", children: [_jsx("strong", { children: cell.purpose || firstLine(cell.code) }), _jsxs("small", { children: [author(cell.by), " \u00B7 ", when(cell.endedAt ?? cell.startedAt ?? cell.queuedAt).text, stateWords[cell.state] ? ' · ' + stateWords[cell.state] : ''] })] }), _jsx(Icon, { name: "chevron", size: 13 })] }, cell.cellId)) }), earlier > 0 && _jsxs("p", { className: "quiet-empty", children: [earlier, " earlier ", earlier === 1 ? 'cell' : 'cells', " in the Notebook"] })] });
 }

package/node_modules/@rho-workspace/plugin-kernel/dist/ui-notebook.d.ts

@@ -1,3 +1,4 @@
+import { type ReactNode } from 'react';
 import { type CellRelations } from './lineage.js';
 import { versionOf, type KernelShell, type SessionScope, type UiClient, type UiSnapshot, type KernelOutputs } from './ui-base.js';
 export { versionOf };
@@ -70,10 +71,10 @@ export declare function SessionPane({ client, snapshot, prepared, onTaken, onCon
     shell?: KernelShell;
     beside?: Beside;
     form?: NotebookForm;
-}): string | number | bigint | boolean | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+}): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
 export declare function NotebookPage({ shell, ...props }: Parameters<typeof NotebookBody>[0] & {
     shell?: KernelShell;
-}): string | number | bigint | boolean | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<import("react").ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
+}): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;
 declare function NotebookBody({ client, snapshot, onConversation, onObject, scope, compact, inView, shown, prepared, onTaken, beside, form }: {
     client: UiClient;
     snapshot: UiSnapshot;
@@ -97,7 +98,8 @@ export declare function VariablesPane({ client, snapshot, onObject }: {
 export declare const plotsPaneLimits: {
     plots: number;
 };
-export declare function PlotsPane({ client, snapshot }: {
+export declare function PlotsPane({ client, snapshot, shell }: {
     client: UiClient;
     snapshot: UiSnapshot;
-}): import("react").JSX.Element;
+    shell?: KernelShell;
+}): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;