beatrina 0.8.6 → 0.8.7

package/host/planes/sessions.mjs

@@ -37,6 +37,7 @@ import { spawn, execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { PAGE_ONLY_CLASSES, secureToken } from "../server.mjs";
 import { stateDir } from "../user-dirs.mjs";
+import { encodeSessionDocuments, keepTokenOk } from "../session-keep.mjs";
 
 export const SESSION_OPS = Object.freeze(["session_list", "r_versions", "session-new"]);
 export const HANDOFF_OPS = Object.freeze(["session_upgrade", "session_restart"]);
@@ -268,7 +269,7 @@ export function createPlane({ root, env, audit }) {
     return script ? { cmd: process.execPath, args: [script] } : { cmd: process.execPath, args: [] };
   };
 
-  const handoffBegin = (ctx, mode = "upgrade", force = false) => {
+  const handoffBegin = (ctx, mode = "upgrade", force = false, resume = null) => {
     mode = mode === "restart" ? "restart" : "upgrade";
     force = force === true && mode === "restart";
     const auditName = mode === "restart" ? "session-restart" : "session-upgrade";
@@ -281,13 +282,13 @@ export function createPlane({ root, env, audit }) {
     const cap = secureToken(32);
     const page = ctx.notebookFileUrl(ctx.notebookPage(installed), ctx.port(), cap);
     const started = ctx.startedSeconds;
-    handoff = { to: installed, cap, page, mode, force };
+    handoff = { to: installed, cap, page, mode, force, resume: keepTokenOk(resume) ? resume : null };
     audit(auditName, { from: ctx.kernelBuild, to: installed, force });
     // Every page learns where its successor's notebook is — over the gated
     // socket only; the capability never appears in /health. `started` is this
     // kernel's boot time: a page recognises its successor by a LATER one, the
     // only test that also works when the build does not change.
-    const told = ctx.enc({ type: "session-upgrade", from: ctx.kernelBuild, to: installed, page, started, mode, force });
+    const told = ctx.enc({ type: "session-upgrade", from: ctx.kernelBuild, to: installed, page, started, mode, force, keep: handoff.resume != null });
     ctx.pageRecs().forEach((r) => { try { r.ws.send(told); } catch { /* gone */ } });
     const spawned = handoffSpawn(ctx);
     if (!spawned) return { ok: false, error: "The installed CarmaR could not be started.", reason: "spawn" };
@@ -314,7 +315,10 @@ export function createPlane({ root, env, audit }) {
       // polling a dead one; strict means it refuses and its log says why.
       CARMAR_PORT_STRICT: "1",
       CARMAR_FILE_LAUNCH_CAP: h.cap, CARMAR_HANDOFF_FROM: ctx.kernelBuild,
-      CARMAR_SESSION_TITLE: record.title || "" };
+      CARMAR_SESSION_TITLE: record.title || "",
+      CARMAR_SESSION_DOCUMENTS: encodeSessionDocuments(ctx.sessionDocuments?.() || []),
+      // Only a token travels, never a path; the successor re-checks it.
+      CARMAR_RESUME_TOKEN: h.resume || "" };
     if (record.listen) childEnv.CARMAR_LISTEN = "1"; else delete childEnv.CARMAR_LISTEN;
     let out = "ignore";
     try { out = fs.openSync(path.join(dir, `kernel-handoff-${port}.log`), "a"); } catch { out = "ignore"; }
@@ -375,7 +379,7 @@ export function createPlane({ root, env, audit }) {
         return reply({ error: "Only the local notebook page may ask this." });
       }
       if (HANDOFF_OPS.includes(cmd.type)) {
-        return reply(handoffBegin(ctx, cmd.type === "session_restart" ? "restart" : "upgrade", cmd.force === true));
+        return reply(handoffBegin(ctx, cmd.type === "session_restart" ? "restart" : "upgrade", cmd.force === true, keepTokenOk(cmd.resume) ? cmd.resume : null));
       }
       if (cmd.type === "session_list") {
         const own = ctx.port();

package/host/server.mjs

@@ -30,11 +30,16 @@ import http from "node:http";
 import path from "node:path";
 import { attachWebSocket } from "./ws.mjs";
 import { rookOf, proxyUser } from "./deployment.mjs";
+import { cleanSessionDocuments } from "./session-keep.mjs";
 
 export const FORWARDED = Object.freeze(["env", "obj", "struct", "view", "colstats", "rm", "packages", "doctor",
   "package_action", "package_help", "project_status", "project_action", "help", "wd",
   "parse", "complete", "files", "import", "readfile", "writefile", "writefiles_atomic",
-  "hover", "format", "sniff", "mkdir", "renamepath", "deletepath", "copypath", "revealpath", "debug_breaks"]);
+  "hover", "format", "sniff", "mkdir", "renamepath", "deletepath", "copypath", "revealpath", "debug_breaks",
+  // "Restart, keep variables", step one (spike/workspace-keep.R). Page-only in both senses: AGENT_REFUSED
+  // below and the class gate in handleFrame. Step two, `resume`, is deliberately NOT here — only the
+  // host asks it, after a restart it performed (WorkerPlane.startResume).
+  "suspend"]);
 export const SESSION_CONTROLS = Object.freeze(["exec", "interrupt", "force_stop", "restart", "runstate", "runs", "adopt",
   "input_reply", "debug_cmd"]);
 /** Answered by serve.R itself, not yet by this host. Refused by NAME so the page never hangs. */
@@ -48,12 +53,16 @@ export const NOT_YET = Object.freeze({
   "open-request": "the open-file door", "page-title": "", "session-new": "session management",
   cite_styles: "citations",
 });
-export const AGENT_REFUSED = Object.freeze(["exec", "interrupt", "force_stop", "restart", "debug_cmd", "input_reply", "project_action"]);
+export const AGENT_REFUSED = Object.freeze(["exec", "interrupt", "force_stop", "restart", "debug_cmd", "input_reply", "project_action",
+  // A copy of every object in the session, written to disk.
+  "suspend", "suspend_cancel"]);
 /** Why, in the sentence serve.R uses. A plane supplies its own via `agentReason`. */
 export const AGENT_WHY_DEFAULT = "Agents run code through notebook chunks (chunk_run), not raw exec.";
 export const AGENT_WHY = Object.freeze({
   input_reply: "Agents cannot answer a prompt on the user's behalf.",
   project_action: "Agents cannot install or restore project packages.",
+  suspend: "Agents cannot keep the user's workspace.",
+  suspend_cancel: "Agents cannot keep the user's workspace.",
 });
 export const PAGE_ONLY_CLASSES = Object.freeze(["served", "file", "local"]);
 export const FILE_ORIGIN = "null";
@@ -111,9 +120,13 @@ export function createHostServer(opts) {
   const hostsOk = deployment.hosts;
   const sockets = [];                       // records: {ws, role, name, class, user, lastSeen, beats}
   const approvals = new Set();              // exact origins the user approved this session
-  const state = { everConnected: false, heldAt: null, pendingOpen: opts.pendingOpen || null, quit: false };
+  const state = { everConnected: false, heldAt: null, pendingOpen: opts.pendingOpen || null, quit: false,
+    // The documents open in this session, as the pages last reported them (host/session-keep.mjs).
+    sessionDocuments: Array.isArray(opts.sessionDocuments) ? opts.sessionDocuments : [] };
   plane.sockets = () => sockets;
   plane.on("broadcast", (payload) => sockets.forEach((r) => r.ws.send(payload)));
+  // A restore's report is about every object in the session: pages only, never an agent or a native client.
+  plane.on("broadcast-pages", (payload) => sockets.filter((r) => PAGE_ONLY_CLASSES.includes(r.class) && r.role === "page").forEach((r) => r.ws.send(payload)));
 
   // The session stamp: ONE string, rendered once, that the page's meta and
   // /health's `started` share so they can never differ in their digits.
@@ -187,6 +200,7 @@ export function createHostServer(opts) {
   const ctx = {
     deployment, plane, audit, sockets, approvals, state, opts,
     enc, scalarChr, pageRecs, socketClass,
+    sessionDocuments: () => state.sessionDocuments,
     port: () => (server.address() ? server.address().port : deployment.port),
     respond: (res, status, type, body, extra) => respond(res, status, type, body, extra),
     reject: (res, reason, detail) => reject(res, reason, detail),
@@ -285,6 +299,11 @@ export function createHostServer(opts) {
       if (plane.hello) ws.send(plane.hello);
       if (plane.notice) ws.send(plane.notice);
       if (typeof plane.replay === "function") plane.replay(ws);
+      // …and a restore that finished before this page arrived (a page following a handoff).
+      if (PAGE_ONLY_CLASSES.includes(rec.class) && typeof plane.freshResumeReport === "function") {
+        const report = plane.freshResumeReport();
+        if (report) ws.send(report);
+      }
       for (const pl of planes) { try { pl.onOpen?.(rec, ctx); } catch (e) { audit("plane-error", { plane: pl.name, detail: e.message }); } }
       ws.onMessage((message) => {
         try { handleFrame(message, rec); } catch (e) { audit("frame-error", { detail: e.message }); }
@@ -346,6 +365,24 @@ export function createHostServer(opts) {
       rec.ws.send(enc({ type: "open-request", id: scalarChr(cmd.id) ? cmd.id : "open", path: p || "" }));
       return undefined;
     }
+    // The documents this session has open. Page-only in BOTH senses: the list is file paths, and a page
+    // that could not open a terminal must not be able to rewrite what the session reopens either.
+    if (type === "page-documents") {
+      if (rec.role === "page" && PAGE_ONLY_CLASSES.includes(rec.class)) {
+        state.sessionDocuments = cleanSessionDocuments(cmd.documents);
+        opts.onSessionDocuments?.(state.sessionDocuments);
+      }
+      return undefined;
+    }
+    // A page asks what this session had open, to reopen it. `others` counts the OTHER pages attached: a
+    // page joining a session another window shows must not open the same documents a second time.
+    if (type === "session-documents") {
+      if (!scalarChr(cmd.id)) return undefined;
+      const allowed = rec.role === "page" && PAGE_ONLY_CLASSES.includes(rec.class);
+      const others = pageRecs().filter((r) => r !== rec).length;
+      rec.ws.send(enc({ type, id: cmd.id, documents: allowed ? state.sessionDocuments : [], others, refused: !allowed }));
+      return undefined;
+    }
     if (AGENT_REFUSED.includes(type) && rec.role === "mcp") {
       audit("mcp-refused", { reason: `agent asked for ${type}` });
       // serve.R answers IN THE ASKED TYPE with an `error`, never a `done`: the
@@ -363,14 +400,22 @@ export function createHostServer(opts) {
       audit("project-action-refused", { reason: "class", class: rec.class || "unknown" });
       return undefined;
     }
+    // "Restart, keep variables": the save is a copy of the whole session, so it is page-only in BOTH
+    // senses, and its cancel interrupts only a save THIS page asked for.
+    if ((type === "suspend" || type === "suspend_cancel") && !PAGE_ONLY_CLASSES.includes(rec.class)) {
+      if (scalarChr(cmd.id)) rec.ws.send(enc({ type, id: cmd.id, error: "Only the local notebook page may keep the workspace." }));
+      audit("suspend-refused", { reason: "class", class: rec.class || "unknown" });
+      return undefined;
+    }
     switch (type) {
+      case "suspend_cancel": if (typeof plane.cancelSuspend === "function") plane.cancelSuspend(rec); return undefined;
       case "exec": return plane.exec(cmd, rec);
       case "interrupt": return plane.interrupt(cmd, rec);
       // Both carry an OPTIONAL engine. `restart` with none is the primary
       // engine's — which is what "Restart R" in the page means and what every
       // client built before there was a second engine sends (§6.5).
       case "force_stop": return plane.forceStop(rec, cmd);
-      case "restart": Promise.resolve(plane.restart(cmd.engine)).catch((e) => audit("restart-failed", { detail: e.message })); return undefined;
+      case "restart": Promise.resolve(plane.restart(cmd.engine, { resume: cmd.resume })).catch((e) => audit("restart-failed", { detail: e.message })); return undefined;
       case "runstate": return plane.runstate(cmd, rec);
       case "runs": return plane.runs(cmd, rec);
       case "adopt": return plane.adopt(cmd, rec);

package/host/session-keep.mjs

@@ -0,0 +1,70 @@
+// session-keep.mjs — the pure rules behind two CarmaR 0.8.5 features, as the host answers them.
+//
+//   · "Restart, keep variables": the worker saves the session (`suspend`, spike/workspace-keep.R) and
+//     answers a TOKEN; the host never reads a kept workspace, it only checks that a token is one the
+//     worker could have minted and carries it to the next worker (`resume`). A path is never a token.
+//   · "A session keeps its documents": the page reports what it has open (`page-documents`), the host
+//     keeps the list, labels the runtime record with it, and hands it back (`session-documents`).
+//
+// Transcribed rule for rule from spike/workspace-keep.R (keep_token_ok) and spike/session-documents.R
+// (session_documents_clean/label/encode/decode), which CarmaR's R supervisor sources; pinned against
+// the same cases by test/session-keep.test.mjs.
+
+import path from "node:path";
+
+export const KEEP_TOKEN_RE = /^[0-9]{14}-[0-9a-f]{16}$/;
+export const SESSION_DOCUMENTS_MAX = 64;
+export const SESSION_DOCUMENT_FORMATS = Object.freeze(["qmd", "Rmd", "md", "carmd"]);
+/** How long a restore's report is replayed to a page that connects late (serve.R: 120 s). */
+export const RESUME_REPORT_MS = 120000;
+
+/** Is `x` a token the worker could have minted? */
+export const keepTokenOk = (x) => typeof x === "string" && KEEP_TOKEN_RE.test(x);
+
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\x00-\x1f\x7f]/g;
+const textOf = (value, cap) => {
+  if (typeof value !== "string") return null;
+  const v = value.replace(CONTROL, " ");
+  return v.length > cap ? null : v;
+};
+
+/** The documents a page reported, cleaned: absolute paths, bounded names, known formats, no duplicates. */
+export function cleanSessionDocuments(documents) {
+  if (!Array.isArray(documents) || !documents.length) return [];
+  const rows = [];
+  const seen = new Set();
+  for (const row of documents) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    const p = textOf(row.path ?? "", 4096);
+    const name = textOf(row.name ?? "", 200);
+    let format = textOf(row.format ?? "", 16);
+    if (p == null || name == null || format == null) continue;
+    // Reopened through the file ops, which resolve it themselves; here it need only be absolute.
+    if (p && !/^(\/|[A-Za-z]:[/\\])/.test(p)) continue;
+    if (!p && !name.trim()) continue;
+    if (!SESSION_DOCUMENT_FORMATS.includes(format)) format = "qmd";
+    if (p) { if (seen.has(p)) continue; seen.add(p); }
+    rows.push({ path: p, name: name.trim(), format, active: row.active === true });
+    if (rows.length >= SESSION_DOCUMENTS_MAX) break;
+  }
+  return rows;
+}
+
+/** "SezerProfiles.qmd + 1 more": what the menu helper shows for a session. */
+export function sessionDocumentsLabel(documents) {
+  if (!Array.isArray(documents) || !documents.length) return "";
+  const lead = documents.find((d) => d.active === true) || documents[0];
+  let name = lead.path ? path.basename(lead.path.replace(/\\/g, "/")) : lead.name;
+  if (!lead.path) name = `${name} (unsaved)`;
+  const rest = documents.length - 1;
+  const label = rest > 0 ? `${name} + ${rest} more` : name;
+  return label.replace(CONTROL, " ").replace(/["\\]/g, "'").slice(0, 120).trim();
+}
+
+export const encodeSessionDocuments = (documents) => (Array.isArray(documents) && documents.length ? JSON.stringify(documents) : "");
+
+export function decodeSessionDocuments(text) {
+  if (typeof text !== "string" || !text) return [];
+  try { return cleanSessionDocuments(JSON.parse(text)); } catch { return []; }
+}

package/host/worker-plane.mjs

@@ -35,6 +35,7 @@
 //     an explicit `restart` is the one door out of it.
 
 import { EventEmitter } from "node:events";
+import { RESUME_REPORT_MS, keepTokenOk } from "./session-keep.mjs";
 
 export const WORKER_DEADLINE_FAST = 120;
 export const WORKER_DEADLINE_SLOW = 600;
@@ -119,6 +120,10 @@ export class WorkerPlane extends EventEmitter {
     this.terminal = null;          // {wireId, route, frame, timer}
     this.running = new Set();      // exec wire ids in flight (the busy guard's evidence)
     this.hello = null;             // the decorated ready payload, replayed to late pages
+    // "Restart, keep variables" (host/session-keep.mjs): a token for the NEXT ready worker, consumed
+    // once; and the restore's report, replayed to a page that connects within RESUME_REPORT_MS.
+    this.resumePending = null;
+    this.resumeReport = null;
     this.notice = null;            // a kept give-up notice
     this.readyFrame = null;
     this.workerWd = process.cwd();
@@ -314,8 +319,8 @@ export class WorkerPlane extends EventEmitter {
     if (this.alive) this.engine.kill();
   }
 
-  async restart() {
-    this.audit("restart", {});
+  async restart({ resume } = {}) {
+    this.audit("restart", { keep: keepTokenOk(resume) });
     this.failRoutes(`${this.label} was restarted — this request was abandoned.`);
     this.expectedExit = true;
     if (this.engine) await this.engine.stop(1000);
@@ -325,9 +330,48 @@ export class WorkerPlane extends EventEmitter {
     this.restartAttempts = 0;
     this.gaveUp = false;
     this.notice = null;
+    this.resumePending = keepTokenOk(resume) ? resume : null;
     await this.start();
   }
 
+  /** A token for the next ready worker (a handoff successor's CARMAR_RESUME_TOKEN). */
+  setResumePending(token) { this.resumePending = keepTokenOk(token) ? token : null; }
+
+  /**
+   * Ask the fresh worker to restore a kept workspace, and tell every page what came back. Queued like
+   * any command, so a chunk run pressed meanwhile waits for the restore rather than racing it.
+   */
+  startResume() {
+    const token = this.resumePending;
+    this.resumePending = null;
+    if (!keepTokenOk(token)) return;
+    this.audit("resume-start", {});
+    this.internal({ type: "resume", token }, (frame) => {
+      if (scalarChr(frame.cwd)) this.workerWd = frame.cwd;
+      const report = { type: "workspace_restored", restored: frame.restored ?? 0, failed: frame.failed ?? [],
+        skipped: frame.skipped ?? [], wd_missing: frame.wd_missing ?? null, error: frame.error ?? null };
+      const payload = enc(report);
+      this.resumeReport = { at: Date.now(), payload };
+      this.audit("resume-done", { restored: report.restored, failed: Array.isArray(report.failed) ? report.failed.length : 0, error: report.error != null });
+      this.emit("broadcast-pages", payload);
+    });
+  }
+
+  /** The report of a restore that finished in the last RESUME_REPORT_MS, or null. */
+  freshResumeReport(now = Date.now()) {
+    return this.resumeReport && now - this.resumeReport.at < RESUME_REPORT_MS ? this.resumeReport.payload : null;
+  }
+
+  /** Cancel a `suspend` — only one THIS page asked for, never someone else's run. */
+  cancelSuspend(rec) {
+    const route = this.active != null ? this.routes.get(this.active) : null;
+    if (this.activeType !== "suspend" || !route || route.rec !== rec) return false;
+    this.audit("suspend-cancel", {});
+    const wireId = this.active;
+    this.engine.interrupt(() => wireId === this.active);
+    return true;
+  }
+
   resetSession() {
     this.running.clear();
     this.routes.clear();
@@ -535,6 +579,7 @@ export class WorkerPlane extends EventEmitter {
       this.hello = payload;
       this.emit("broadcast", payload);
       this.emit("ready", decorated);
+      if (this.resumePending) this.startResume();
       return;
     }
     this.emit("broadcast", relayFrame(e));

package/kernel/kernel-version

@@ -1 +1 @@
-0.8.6
+0.8.7

package/kernel/kernel.R

@@ -246,16 +246,18 @@ kernel_start <- function(worker_path, sentinel = NULL, rscript = detect_rscript(
     clean_env[["CARMAR_SENTINEL"]] <- sentinel
     clean_env[["CARMAR_CMD_TAG"]] <- cmdtag
     clean_env[["CARMAR_WORKER_MODE"]] <- "interactive"
+    # readline's screen width: at 80 a long command line echoes as "<" + tail with
+    # no cmdtag (Linux; host/engine-r.mjs has the measurement). The boot line gives
+    # user code back its own COLUMNS.
+    clean_env[["CARMAR_USER_COLUMNS"]] <- Sys.getenv("COLUMNS", "")
+    clean_env[["COLUMNS"]] <- "100000"
     clean_env[["CARMAR_WORKER_DIR"]] <- dirname(normalizePath(worker_path, mustWork = FALSE))
   }
   spawn_bin <- if (identical(mode, "interactive")) r_binary else rscript
   spawn_args <- if (identical(mode, "interactive")) {
     # --no-echo suppresses the "> " prompt; the input ECHO it does not suppress
     # is scrubbed in kernel_poll by the cmdtag / pending-echo machinery.
-    # --no-readline FIRST: R ignores it after --interactive, and with readline
-    # R echoes each line read — on Linux as a scrolled "<" + tail that carries no
-    # cmdtag (host/engine-r.mjs has the measurement).
-    c("--no-readline", "--interactive", "--no-echo", "--no-save", "--no-restore", "--no-site-file")
+    c("--interactive", "--no-echo", "--no-save", "--no-restore", "--no-site-file")
   } else {
     # --vanilla, NOT --no-init-file: the user's .Rprofile/.Renviron are part of
     # their R (library paths, repos, options). Only history and saved workspaces
@@ -292,7 +294,8 @@ kernel_start <- function(worker_path, sentinel = NULL, rscript = detect_rscript(
     if (!file.exists(real_worker)) real_worker <- worker_path
     worker_boot <- sprintf('sys.source("%s", envir = globalenv(), keep.source = FALSE)',
                            encodeString(normalizePath(real_worker)))
-    boot <- paste(Filter(nzchar, c(macos_background_boot(worker_path), worker_boot)),
+    width_boot <- 'local({ cols <- Sys.getenv("CARMAR_USER_COLUMNS"); Sys.unsetenv("CARMAR_USER_COLUMNS"); if (nzchar(cols)) Sys.setenv(COLUMNS = cols) else Sys.unsetenv("COLUMNS") })'
+    boot <- paste(Filter(nzchar, c(width_boot, macos_background_boot(worker_path), worker_boot)),
                   collapse = ";")
     kernel_console(k, boot)
   }