beatrina 0.8.6

package/host/planes/ai.mjs

@@ -0,0 +1,467 @@
+// planes/ai.mjs — the provider key, the administrator's policy, the audit
+// stream, the console's history and the appearance carry.
+//
+// Five small stores that share one rule: they are the USER'S OWN MACHINE STATE,
+// kept by the supervisor because the browser is the wrong place for them, and
+// answered for the NOTEBOOK PAGE and nobody else.
+//
+// ── who may ask, and why it is TWO questions ────────────────────────────────
+//
+// AGENT_REFUSED asks "did this client DECLARE itself an agent?" — an honour
+// system: a socket's role is "page" until the client volunteers `mcp-hello`, so
+// an agent CLI that simply never declared was handed the user's provider key
+// until 0.60.89. PAGE_ONLY_CLASSES asks what the UPGRADE GATE already proved
+// about the connection, which nothing the client says afterwards can change.
+// Two lists rather than one flagged one, for the reason FORWARDED and
+// ANALYZE_FORWARDED stay two.
+//
+// A native client is refused even though it could read the 0600 file itself as
+// this user: the point is not that the kernel can stop it, but that the kernel
+// does not hand it over — so the promise holds for every agent instead of only
+// the polite ones. A published site is refused because its reader approved it
+// to RUN THE CHUNKS THEY PRESS, not to collect a credential on the way past.
+
+import fs from "node:fs";
+import path from "node:path";
+import { PAGE_ONLY_CLASSES } from "../server.mjs";
+import { appId, ensureUserDir, privateModeHeld } from "../user-dirs.mjs";
+import { carmarAiPolicy, aiPolicyReason } from "../ai-policy.mjs";
+
+const envOf = (name, unset = "") => (process.env[name] == null ? unset : String(process.env[name]));
+const isStr = (v) => typeof v === "string" && v.length > 0;
+
+// ── what the page may write into the audit stream ───────────────────────────
+//
+// The AI conversation happens in the BROWSER — a key-based turn is a fetch from
+// the page — so the kernel cannot observe it and the page has to report. That
+// makes this the one op whose log content comes from OUTSIDE, which is a
+// log-injection surface if it is a free-text channel. It is not one:
+//
+//   · `event` must be one of a fixed vocabulary,
+//   · every other field is an ALLOW-LIST of scalars, bounded and stripped of
+//     control characters (a newline in a JSON-lines log is a forged record),
+//   · and the fields that ESTABLISH the record — the timestamp, the pid, which
+//     connection sent it and whether that connection is a page or a declared
+//     agent — are stamped by the supervisor and cannot be supplied at all.
+//
+// An allow-list rather than a deny-list, for the reason FORWARDED is one: a
+// field added to the page later is absent from the log until someone puts it
+// here on purpose.
+export const AI_AUDIT_EVENTS = Object.freeze(["turn", "tool", "insert", "patch", "accept", "reject", "error"]);
+export const AI_AUDIT_FIELDS = Object.freeze(["provider", "model", "lane", "tool", "chunk", "decision",
+  "kind", "by", "reason", "ms", "input_tokens", "output_tokens", "prompt_chars", "response_chars", "error"]);
+// The prompt and the response themselves. OFF unless an administrator asks,
+// because a notebook that silently recorded everything its user typed at an AI
+// would be a worse thing to ship than no audit at all — the same judgement
+// CARMAR_LOG itself is off by default for.
+export const AI_AUDIT_TEXT_FIELDS = Object.freeze(["prompt", "response"]);
+/** How many ai-* records the reviewer export may read back at once. */
+export const AI_AUDIT_READ_MAX = 5000;
+
+// ── the console's history, across sessions ───────────────────────────────────
+//
+// RStudio keeps `.Rhistory`; a console whose ↑ forgets everything the moment
+// the tab reloads is a demo, not a tool. It lives beside the key and for the
+// same reason: this is MACHINE state, not notebook content, so it belongs in
+// the R user directory and never in the notebook file, an export, or
+// localStorage — where any local page sharing the file:// origin could read the
+// user's code. Off entirely with CARMAR_NO_HISTORY=1 (and from Settings),
+// because "record everything I type" must be refusable.
+export const HISTORY_MAX = 2000;
+
+// ── appearance, across the two origins the notebook is delivered from ────────
+//
+// The same notebook is delivered from a file:// page and from this kernel's own
+// http://127.0.0.1:PORT, and browsers partition storage by origin — so a theme
+// chosen at one door is invisible at the other. This is a small named store so
+// a choice already made at either door is not thrown away when the other opens.
+// It is a CARRY, not a sync: the page adopts only keys its own origin does not
+// already hold (lib/prefs-mirror.js), so the kernel can never overwrite a live
+// choice, and localStorage still decides what gets painted.
+//
+// PREF_KEYS is CLOSED, here as well as in the page, because the two lists
+// answer different questions. The page's asks "what should I carry?"; this one
+// asks "what may anything store in the user's data directory?" — and every
+// local HTML file shares the file:// origin, so without it `prefs` is a
+// free-form key/value bag any of them could fill.
+//
+// The values travel as the STRINGS localStorage holds. carmar-chunk-custom is
+// itself JSON; re-parsing it here would make the kernel a party to a format
+// only the page understands.
+export const PREF_MAX_VALUE = 4096;
+export const PREF_KEYS = Object.freeze([
+  "carmar-app-theme",        // lib/app-themes.js       standard/flat/plain/graphite/onyx
+  "carmar-editor-theme",     // lib/editor-themes.js    one of 37
+  "carmar-chunk-style",      // lib/chunk-style.js      the pre-7.8 key, kept in step
+  "carmar-chunk-style-v2",   // lib/chunk-style.js      the explicit choice
+  "carmar-chunk-custom",     // lib/chunk-style.js      the designer's token overrides
+  "carmar-writing-chunk",    // lib/writing-chunk.js    the Writing surface's own card
+  "carmar-run-style",        // lib/run-style.js
+  "carmar-table-style-v2",   // lib/table-render.js
+  "carmar-line-numbering",   // lib/line-numbering.js
+  "carmar-density",          // lib/density.js
+  "carmar-add-strip-v3",     // lib/add-strip.js
+  "carmar-soft-wrap",        // lib/soft-wrap.js
+  "carmar-content-width-v1", // src/notebook-entry.js   Standard / Wide / Full
+  "carmar-brand-v1",         // lib/brand.js            the organisation's accent
+  "carmar:rich-text",        // lib/rtf-editor.js
+  "carmar:latex-template",   // lib/latex-templates.js
+]);
+
+const AGENT_WHY = Object.freeze({
+  "ai-key": "Agents cannot read or write the stored key.",
+  "ai-audit-read": "Agents cannot read the audit stream.",
+  console_history: "Agents cannot read the console history.",
+  prefs: "Agents have no appearance; the notebook page keeps that.",
+});
+
+/** One field of an audit record, made safe to write on one line. */
+export function aiAuditScalar(value, limit) {
+  if (value == null || Array.isArray(value) || (typeof value === "object")) return null;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") return null;
+  // R's [[:cntrl:]] — 0x00-0x1f and 0x7f — spelled out. A newline inside a
+  // JSON-lines log is a forged record, not a formatting problem.
+  // eslint-disable-next-line no-control-regex
+  return value.replace(/[\u0000-\u001f\u007f]/g, " ").slice(0, limit).trim();
+}
+
+// ── the provider key ────────────────────────────────────────────────────────
+
+export const aiKeyPath = () => path.join(ensureUserDir(appId(), "config"), "ai-key");
+
+export function aiKeyRead() {
+  const file = aiKeyPath();
+  if (!fs.existsSync(file)) return "";
+  try { return (fs.readFileSync(file, "utf8").split("\n")[0] || "").trim(); } catch { return ""; }
+}
+
+export function aiKeyWrite(value) {
+  const file = aiKeyPath();
+  if (!value.length) {
+    // Removing a file REPORTS failure rather than raising, so an unwritable
+    // config directory used to answer {ok:true} while the key sat there.
+    // "Forget the key" reporting success over a key still on disk is the one
+    // lie this function must not tell.
+    if (!fs.existsSync(file)) return true;
+    try { fs.unlinkSync(file); } catch { return false; }
+    return !fs.existsSync(file);
+  }
+  // Lock the file down BEFORE the secret goes into it. Creating it with the key
+  // already inside leaves a window where it is world-readable, and a key that
+  // was briefly readable has already leaked.
+  try { if (!fs.existsSync(file)) fs.writeFileSync(file, "", { mode: 0o600 }); } catch { return false; }
+  // The chmod runs before the secret exists in the file, and its result is
+  // CHECKED: on a filesystem that allows writing but not mode changes the key
+  // would otherwise be written world-readable under a promise of 0600.
+  try {
+    fs.chmodSync(file, 0o600);
+    if (!privateModeHeld(file)) throw new Error("mode");
+  } catch { try { fs.unlinkSync(file); } catch { /* gone */ } return false; }
+  try { fs.writeFileSync(file, `${value}\n`); return true; }
+  catch { try { fs.unlinkSync(file); } catch { /* gone */ } return false; }
+}
+
+// ── console history ─────────────────────────────────────────────────────────
+
+export const historyPath = () => path.join(ensureUserDir(appId(), "data"), "console-history");
+
+const readLines = (file) => {
+  if (!fs.existsSync(file)) return [];
+  try { return fs.readFileSync(file, "utf8").split("\n").filter((l) => l.length > 0); } catch { return []; }
+};
+
+export function historyRead(enabled) {
+  if (!enabled) return [];
+  // ONE JSON STRING PER LINE, not raw text. A history entry can be a whole
+  // multi-line function definition, and the file is line-oriented, so the entry
+  // has to survive a newline inside it — hand-rolled backslash escaping got
+  // this wrong in both directions on the first attempt. A malformed line is
+  // dropped rather than allowed to poison the rest.
+  const out = [];
+  for (const raw of readLines(historyPath())) {
+    let v = null;
+    try { v = JSON.parse(raw); } catch { v = null; }
+    if (typeof v === "string") out.push(v);
+  }
+  return out;
+}
+
+export function historyAdd(enabled, line) {
+  if (!enabled || !line.trim().length) return true;
+  const file = historyPath();
+  const flat = JSON.stringify(line);
+  const prior = readLines(file);
+  // Consecutive duplicates are noise in a history: pressing ↑ twice should
+  // reach the command BEFORE the one just run, not the same one again.
+  let kept = prior.length && prior[prior.length - 1] === flat ? prior : [...prior, flat];
+  if (kept.length > HISTORY_MAX) kept = kept.slice(kept.length - HISTORY_MAX);
+  // Same order as the key: create, lock, then write. History is a record of
+  // everything the user has typed and is nobody else's business.
+  try { if (!fs.existsSync(file)) fs.writeFileSync(file, "", { mode: 0o600 }); } catch { return false; }
+  try {
+    fs.chmodSync(file, 0o600);
+    if (!privateModeHeld(file)) return false;
+  } catch { return false; }
+  try { fs.writeFileSync(file, `${kept.join("\n")}\n`); return true; } catch { return false; }
+}
+
+// ── appearance ──────────────────────────────────────────────────────────────
+
+export const prefsPath = () => path.join(ensureUserDir(appId(), "data"), "appearance.json");
+
+/** Known keys only, one bounded string each, in a stable order. */
+export function prefsClean(values) {
+  if (!values || typeof values !== "object" || Array.isArray(values)) return {};
+  const out = {};
+  for (const k of PREF_KEYS) {                 // PREF_KEYS first: fixes the order
+    if (!Object.prototype.hasOwnProperty.call(values, k)) continue;
+    const v = values[k];
+    if (typeof v === "string" && Buffer.byteLength(v, "utf8") <= PREF_MAX_VALUE) out[k] = v;
+  }
+  return out;
+}
+
+export function prefsRead(enabled) {
+  if (!enabled) return {};
+  const file = prefsPath();
+  if (!fs.existsSync(file)) return {};
+  try { return prefsClean(JSON.parse(fs.readFileSync(file, "utf8"))); } catch { return {}; }
+}
+
+export function prefsWrite(enabled, values) {
+  if (!enabled) return false;
+  const clean = prefsClean(values);
+  const file = prefsPath();
+  // Create, then lock, then write — the order the key and the history beside it
+  // use. A theme is not a secret; the point is that everything the kernel puts
+  // in the user's data directory is the user's, and judging file by file which
+  // ones are harmless is how one of them eventually gets it wrong.
+  try { if (!fs.existsSync(file)) fs.writeFileSync(file, "", { mode: 0o600 }); } catch { return false; }
+  try {
+    fs.chmodSync(file, 0o600);
+    if (!privateModeHeld(file)) return false;
+  } catch { return false; }
+  // An empty store has to be {} and not []: the page asked for an object.
+  try { fs.writeFileSync(file, `${JSON.stringify(clean)}\n`); return true; } catch { return false; }
+}
+
+// ── the plane ───────────────────────────────────────────────────────────────
+
+const OPS = Object.freeze(["ai-key", "ai-policy", "ai-audit", "ai-audit-read", "console_history", "prefs"]);
+
+export function createPlane({ audit, settings } = {}) {
+  const policy = carmarAiPolicy();
+  const logPath = envOf("CARMAR_LOG");
+  const auditText = envOf("CARMAR_LOG_AI_TEXT") === "1";
+  const prefsEnabled = envOf("CARMAR_NO_PREFS") !== "1";
+  const historyEnabled = () => (settings ? settings.historyEnabled() : envOf("CARMAR_NO_HISTORY") !== "1");
+
+  return {
+    name: "ai",
+    ops: OPS,
+    commands: [],
+    audits: true,                 // this plane logs what it means to log, itself
+    policy,
+    init() {
+      // A governance control that silently failed to apply is worse than one
+      // that refuses to start, because nobody finds out until the data has
+      // already gone to the wrong vendor. A policy that permits NOTHING is an
+      // error, never an empty allow-list.
+      if (policy.errors.length) {
+        for (const m of policy.errors) console.error(`Beatrina refuses to start: ${m}`);
+        throw new Error(policy.errors.join(" "));
+      }
+    },
+    handle(cmd, rec, ctx) {
+      const type = cmd.type;
+      const reply = (extra) => rec.ws.send(ctx.enc({ type, id: cmd.id, ...extra }));
+
+      // ── the AI conversation, into the audit stream ───────────────────────
+      // Fire-and-forget: there is no reply, because a turn must never wait on
+      // its own logging, and a page that could tell whether the write landed
+      // would be a probe for whether auditing is on. A DECLARED AGENT IS NOT
+      // REFUSED here — an agent reporting its own work is exactly what should
+      // be in the log, labelled as an agent, which is a thing it cannot say
+      // otherwise.
+      if (type === "ai-audit") {
+        const event = aiAuditScalar(cmd.event, 32);
+        if (typeof event !== "string" || !AI_AUDIT_EVENTS.includes(event)) return undefined;
+        const fields = {};
+        for (const f of AI_AUDIT_FIELDS) {
+          const v = aiAuditScalar(cmd[f], 200);
+          if (v != null && v !== "") fields[f] = v;
+        }
+        if (auditText) {
+          for (const f of AI_AUDIT_TEXT_FIELDS) {
+            const v = aiAuditScalar(cmd[f], 4000);
+            if (v != null && v !== "") fields[f] = v;
+          }
+        }
+        // Stamped, never accepted: who this is, and what kind of client it is.
+        audit?.(`ai-${event}`, { ...fields, class: rec.class || "unknown", role: rec.role || "page", user: rec.user || "" });
+        return undefined;
+      }
+
+      // What the administrator permits. Deliberately readable by ANY socket,
+      // including a declared agent: it discloses provider names and an
+      // administrator's own sentence, never a credential, and an agent that
+      // knows the constraint can respect it instead of failing into it.
+      if (type === "ai-policy") {
+        if (!isStr(cmd.id)) return undefined;
+        reply({ set: policy.set === true,
+          providers: policy.providers, models: policy.models, base_urls: policy.base_urls,
+          local_only: policy.local_only === true, note: policy.note,
+          // Is anything listening? The page asks once, here, rather than
+          // sending audit frames into a kernel that discards them.
+          audit: logPath.length > 0, audit_text: auditText,
+          source: policy.source === "env" ? "environment" : (policy.source.length ? "file" : "") });
+        return undefined;
+      }
+
+      if (!isStr(cmd.id)) return undefined;
+      if (rec.role === "mcp" && AGENT_WHY[type]) {
+        audit?.("mcp-refused", { reason: `agent asked for ${type}` });
+        reply({ error: AGENT_WHY[type] });
+        return undefined;
+      }
+
+      // ── the key: get / set / clear ───────────────────────────────────────
+      if (type === "ai-key") {
+        // See PAGE_ONLY_CLASSES: the key is for the notebook page, and "is this
+        // the notebook page?" is answered by the connection, not by the sender.
+        if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+          audit?.("ai-key-refused", { class: rec.class || "unknown" });
+          reply({ error: "Only the notebook page may read or write the stored key." });
+          return undefined;
+        }
+        // ONE OF THE TWO DOORS THE SUPERVISOR ACTUALLY OWNS. A policy that
+        // permits no key-based provider means no provider key is kept at all:
+        // not handed out, not stored. The user can still paste one into the tab
+        // — this is their own browser — but nothing persists it for them and
+        // the attempt is in the audit log. The refusal covers `set` as much as
+        // `get`, because a key held under a local-only policy is a key that
+        // should never have been accepted.
+        if (policy.set === true && policy.allows_key !== true) {
+          audit?.("ai-key-refused", { reason: "policy", class: rec.class || "unknown" });
+          reply({ error: aiPolicyReason(policy), policy: true });
+          return undefined;
+        }
+        const action = isStr(cmd.action) ? cmd.action : "get";
+        if (action === "get") {
+          audit?.("ai-key", { detail: "get", class: rec.class });
+          reply({ key: aiKeyRead() });
+        } else if (action === "set" || action === "clear") {
+          // A `set` whose key is not a string used to fall through to value =
+          // "", DELETE the stored key, and answer ok:true. A malformed request
+          // must not be answered by destroying the thing it named. (`set ""` is
+          // still a clear — that one is deliberate.)
+          if (action === "set" && !isStr(cmd.key)) {
+            reply({ error: "ai-key: `set` needs `key` to be a string." });
+            return undefined;
+          }
+          const value = action === "set" ? cmd.key : "";
+          let ok = false;
+          try { ok = aiKeyWrite(value); } catch { ok = false; }
+          // `ok` belongs in the log. Recording only the INTENT left the one
+          // question an audit trail exists to answer — did the write land? —
+          // unanswerable.
+          audit?.("ai-key", { detail: value.length ? "set" : "clear", class: rec.class, ok: ok === true });
+          reply({ ok: ok === true });
+        } else {
+          reply({ error: "ai-key: action must be get, set or clear." });
+        }
+        return undefined;
+      }
+
+      // ── reading the audit stream BACK, for the reviewer export ───────────
+      //
+      // Only `ai-*` records are returned. The same file also holds socket
+      // opens, refusals and the startup posture — operational security detail
+      // that a notebook page has no business reading back, and that the
+      // reviewer export would have no use for. The narrower answer is the whole
+      // point of having a separate op rather than "read me the log".
+      if (type === "ai-audit-read") {
+        if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+          audit?.("ai-audit-read-refused", { class: rec.class || "unknown" });
+          reply({ error: "Only the notebook page may read the audit stream." });
+          return undefined;
+        }
+        if (!logPath.length || !fs.existsSync(logPath)) {
+          // Not an error: no log configured is the ordinary single-user state,
+          // and the export says so in words rather than showing an empty table
+          // that would read as "the AI did nothing".
+          reply({ records: [], configured: logPath.length > 0 });
+          return undefined;
+        }
+        let lines = [];
+        try { lines = fs.readFileSync(logPath, "utf8").split("\n").filter((l) => l.length > 0); } catch { lines = []; }
+        lines = lines.filter((l) => l.includes('"event":"ai-'));
+        // Bounded: a long-lived kernel accumulates, and one frame must not
+        // become megabytes. The TAIL, because a reviewer wants this session.
+        if (lines.length > AI_AUDIT_READ_MAX) lines = lines.slice(lines.length - AI_AUDIT_READ_MAX);
+        // Forwarded as the BYTES they were written as, parsed once by the
+        // browser: re-encoding here would round numbers and collapse fields.
+        reply({ records: lines, configured: true, truncated: lines.length >= AI_AUDIT_READ_MAX });
+        return undefined;
+      }
+
+      // ── the console's cross-session history ──────────────────────────────
+      // Page-only on the same grounds as the key: it is a record of everything
+      // this user has typed at their own machine.
+      if (type === "console_history") {
+        if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+          audit?.("console-history-refused", { class: rec.class || "unknown" });
+          reply({ error: "Only the notebook page may read or write the console history." });
+          return undefined;
+        }
+        const enabled = historyEnabled();
+        const action = isStr(cmd.action) ? cmd.action : "get";
+        if (action === "get") {
+          reply({ lines: historyRead(enabled), enabled });
+        } else if (action === "add") {
+          if (!isStr(cmd.line)) { reply({ error: "console_history: `line` must be a string." }); return undefined; }
+          let ok = false;
+          try { ok = historyAdd(enabled, cmd.line); } catch { ok = false; }
+          reply({ ok: ok === true });
+        } else if (action === "clear") {
+          const file = historyPath();
+          try { fs.unlinkSync(file); } catch { /* already gone */ }
+          reply({ ok: !fs.existsSync(file) });
+        } else {
+          reply({ error: "console_history: action must be get, add or clear." });
+        }
+        return undefined;
+      }
+
+      // ── appearance carried between the two origins ───────────────────────
+      if (type === "prefs") {
+        if (!PAGE_ONLY_CLASSES.includes(rec.class)) {
+          audit?.("prefs-refused", { class: rec.class || "unknown" });
+          reply({ error: "Only the notebook page may read or write appearance preferences." });
+          return undefined;
+        }
+        const action = isStr(cmd.action) ? cmd.action : "get";
+        if (action === "get") {
+          reply({ values: prefsRead(prefsEnabled), keys: PREF_KEYS, enabled: prefsEnabled });
+        } else if (action === "put") {
+          // A put MERGES. The page sends what ITS origin holds, and a page that
+          // has never heard of a key must not be able to delete it for the
+          // other door — which is what a replacing write would do the first
+          // time an older build shares this store with a newer one.
+          const merged = { ...prefsRead(prefsEnabled), ...prefsClean(cmd.values) };
+          reply({ ok: prefsWrite(prefsEnabled, merged) === true });
+        } else if (action === "clear") {
+          const file = prefsPath();
+          try { fs.unlinkSync(file); } catch { /* already gone */ }
+          reply({ ok: !fs.existsSync(file) });
+        } else {
+          reply({ error: "prefs: action must be get, put or clear." });
+        }
+        return undefined;
+      }
+      return undefined;
+    },
+  };
+}