@ravefox/space 0.0.0-stage → 0.2.0

package/node_modules/@commonlyai/seats/src/trace/store.js

@@ -0,0 +1,276 @@
+/**
+ * Append-only trace store on the local filesystem.
+ *
+ *   <root>/runs/<runId>.jsonl   the run record (docs/record-v1.md): one
+ *                               canonical, hash-chained entry per line
+ *   <root>/index.jsonl          one line per started run, one per settled run;
+ *                               a store convenience, not part of the format
+ *
+ * Files are 0600 and directories 0700: a trace holds agent output.
+ */
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, mkdirSync, readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  appendEntry, hashLine, kindOfType, readRecord, traceTypeOf, validateActor, verifyRecord, BOARD_ACTOR,
+} from '../record/format.js';
+
+const RUN_ID = /^[A-Za-z0-9_-]{6,64}$/;
+const readJsonl = (path) => (existsSync(path)
+  ? readFileSync(path, 'utf8').split('\n').filter(Boolean).flatMap((line) => {
+    try { return [JSON.parse(line)]; } catch { return []; }
+  })
+  : []);
+
+/**
+ * Known credential values never reach a line, even inside agent text. Every
+ * registered value is replaced, whatever its length: the eight-character
+ * floor in redactKnownCredentials belongs to the refusal-text reader, not to
+ * the record. `secrets` is kept longest first, so a value that contains a
+ * shorter one is replaced whole rather than in pieces.
+ */
+const scrubText = (text, secrets) => {
+  let out = text;
+  for (const value of secrets) out = out.split(value).join('[redacted]');
+  return out;
+};
+
+const scrub = (value, secrets) => {
+  if (secrets.length === 0) return value;
+  if (typeof value === 'string') return scrubText(value, secrets);
+  if (Array.isArray(value)) return value.map((item) => scrub(item, secrets));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, scrub(item, secrets)]));
+  }
+  return value;
+};
+
+/**
+ * Streamed agent text arrives in deltas, so a value can be split across two or
+ * more of them and match none on its own. Each stream (kind + actor) is
+ * scrubbed over a rolling window instead: the held tail is joined to the next
+ * delta, the join is scrubbed, and the longest suffix of the result that
+ * could still begin a known value is held back again. What is written is the
+ * rest.
+ *
+ * Why that is enough: an occurrence that started inside written text and ran
+ * past its end would make the written part plus the held tail a proper prefix
+ * of that value, a longer such suffix than the one held. So no value spans a
+ * written boundary, and each written piece is itself scrubbed. The tail is
+ * shorter than the longest value, and only as long as an actual prefix match.
+ */
+const STREAMED_KINDS = new Set(['agent.message_chunk', 'agent.thought_chunk']);
+// The held text is written out before these, so it stays in its own attempt
+// and is never lost at settle, whichever path (ok, failure, cancel, kill) got there.
+const FLUSH_BEFORE = new Set(['attempt.started', 'attempt.settled', 'run.settled']);
+
+const heldLength = (text, secrets) => {
+  const longest = secrets.length ? secrets[0].length : 0;
+  for (let start = Math.max(0, text.length - longest + 1); start < text.length; start += 1) {
+    const tail = text.slice(start);
+    if (secrets.some((value) => value.length > tail.length && value.startsWith(tail))) return text.length - start;
+  }
+  return 0;
+};
+
+/** What readRun has always returned, plus the envelope: `type` is the trace name. */
+const asEvent = (entry) => (entry.kind ? { ...entry, type: traceTypeOf(entry.kind) } : entry);
+
+export const createTraceStore = ({ root, now = () => new Date() } = {}) => {
+  if (!root) throw new Error('createTraceStore needs a root directory');
+  const runsDir = join(root, 'runs');
+  mkdirSync(runsDir, { recursive: true, mode: 0o700 });
+  const append = (path, value) => appendFileSync(path, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+  const indexPath = join(root, 'index.jsonl');
+
+  /**
+   * startRun({ runId?, adapter?, label?, taskId?, podId?, actor? })
+   *   → { runId, emit, redact, revokeGrant, expireGrants, openGrants, settled }
+   *
+   * `taskId` is the board's task id verbatim and needs `podId`, since task
+   * ids repeat across pods. `actor` is the run's own party, normally
+   * {type: 'agent', id: <user id>, owner: <user id>}.
+   */
+  const startRun = (meta = {}) => {
+    const runId = meta.runId || randomUUID();
+    if (!RUN_ID.test(runId)) throw new Error('runId must be 6-64 characters of [A-Za-z0-9_-]');
+    const taskId = meta.taskId || undefined;
+    const podId = meta.podId || undefined;
+    if (taskId && !podId) throw new Error('a taskId needs a podId: task ids repeat across pods');
+    const runActor = meta.actor === undefined ? null : validateActor(meta.actor);
+    const path = join(runsDir, `${runId}.jsonl`);
+    try {
+      writeFileSync(path, '', { mode: 0o600, flag: 'wx' });
+    } catch (error) {
+      if (error.code === 'EEXIST') throw new Error(`run ${runId} already exists`);
+      throw error;
+    }
+    let last = null; // the previous line, which the next one hashes
+    let seq = 0;
+    let settled = false;
+    let broken = false;
+    const secrets = []; // longest first; see scrubText
+    const streams = new Map(); // stream key → { kind, actor, held }
+    const grants = new Map(); // open grants: grantId → { parentGrantId, binding, expiresAt }
+    const startedAt = now();
+
+    const writeLine = (kind, data, actor) => {
+      const line = appendEntry(last, {
+        runId, taskId, podId, ts: now().toISOString(), kind, data: scrub(data, secrets), actor,
+      }, { runActor });
+      try {
+        appendFileSync(path, `${line}\n`, { mode: 0o600 });
+      } catch (error) {
+        // Some bytes may have landed; a chain cannot continue past an unknown tail.
+        broken = true;
+        throw error;
+      }
+      last = line;
+      seq += 1;
+      const entry = JSON.parse(line);
+      if (kind === 'grant.issued') {
+        grants.set(entry.data.grantId, {
+          parentGrantId: entry.data.parentGrantId ?? null, binding: entry.data.binding || null, expiresAt: entry.data.expiresAt || null,
+        });
+      }
+      if (kind === 'grant.revoked') for (const id of entry.data.grantIds) grants.delete(id);
+      return asEvent(entry);
+    };
+
+    /** A streamed delta's text, less a tail that could begin a known value. */
+    const windowed = (kind, data, actor) => {
+      if (!STREAMED_KINDS.has(kind) || typeof data?.text !== 'string') return data;
+      const key = JSON.stringify([kind, actor ?? null]);
+      const joined = scrubText(`${streams.get(key)?.held ?? ''}${data.text}`, secrets);
+      const cut = joined.length - heldLength(joined, secrets);
+      if (cut < joined.length) streams.set(key, { kind, actor, held: joined.slice(cut) });
+      else streams.delete(key);
+      return { ...data, text: joined.slice(0, cut) };
+    };
+
+    const write = (kind, data, actor) => writeLine(kind, windowed(kind, data, actor), actor);
+
+    /**
+     * The stream has ended, so each held tail can no longer complete a value.
+     * A tail is held only while it is a prefix of a known value, so it is part
+     * of a credential: write the marker in its place, never the prefix.
+     */
+    const flushStreams = () => {
+      for (const [key, { kind, actor }] of streams) {
+        streams.delete(key);
+        writeLine(kind, { text: '[redacted]' }, actor);
+      }
+    };
+
+    const revoke = (grantIds, reason, actor) => (grantIds.length ? write('grant.revoked', { grantIds, reason }, actor) : null);
+
+    const emit = (type, data = {}, options = {}) => {
+      const kind = kindOfType(type);
+      if (!kind) throw new Error(`unknown trace event type: ${type}`);
+      if (settled) return null;
+      if (broken) throw new Error(`run ${runId}: the record is broken after a failed write`);
+      if (FLUSH_BEFORE.has(kind)) flushStreams();
+      const event = write(kind, data, options?.actor);
+      if (kind === 'task.done') {
+        // The board closed the task: every grant bound to it ends, in one write.
+        const bound = [...grants].filter(([, g]) => g.binding?.endsOn === 'task.done').map(([id]) => id);
+        revoke(bound, 'task.done', BOARD_ACTOR);
+      }
+      if (kind === 'run.settled') {
+        settled = true;
+        append(indexPath, {
+          runId,
+          settledAt: event.ts,
+          outcome: event.data.outcome,
+          failure: event.data.failure || null,
+          durationMs: event.data.durationMs ?? null,
+          entries: seq,
+          head: hashLine(last),
+        });
+      }
+      return event;
+    };
+
+    /** Revoke a grant and every descendant this run knows of, in one entry. */
+    const revokeGrant = (grantId, { actor } = {}) => {
+      if (settled || !grants.has(grantId)) return null;
+      const lineage = [grantId];
+      for (let i = 0; i < lineage.length; i += 1) {
+        for (const [id, g] of grants) if (g.parentGrantId === lineage[i] && !lineage.includes(id)) lineage.push(id);
+      }
+      return revoke(lineage, lineage.length > 1 ? 'cascade' : 'manual', actor);
+    };
+
+    /** Record the end of every open grant whose expiresAt has passed. */
+    const expireGrants = (at = now()) => {
+      if (settled) return null;
+      const cutoff = at.getTime();
+      return revoke([...grants].filter(([, g]) => g.expiresAt && Date.parse(g.expiresAt) <= cutoff).map(([id]) => id), 'expired');
+    };
+
+    /** Every non-empty string is scrubbed from here on, whatever its length. */
+    const redact = (values = []) => {
+      for (const value of values) if (typeof value === 'string' && value && !secrets.includes(value)) secrets.push(value);
+      secrets.sort((a, b) => b.length - a.length);
+    };
+
+    append(indexPath, {
+      runId,
+      startedAt: startedAt.toISOString(),
+      adapter: meta.adapter || null,
+      label: meta.label || null,
+      ...(taskId ? { taskId, podId } : podId ? { podId } : {}),
+      ...(runActor ? { actor: runActor } : {}),
+    });
+    return {
+      runId,
+      taskId: taskId ?? null,
+      podId: podId ?? null,
+      emit,
+      redact,
+      revokeGrant,
+      expireGrants,
+      openGrants: () => [...grants.keys()],
+      get settled() { return settled; },
+    };
+  };
+
+  const listRuns = ({ limit = 50 } = {}) => {
+    const byId = new Map();
+    for (const line of readJsonl(indexPath)) {
+      const row = byId.get(line.runId) || { runId: line.runId, outcome: 'running' };
+      Object.assign(row, line);
+      byId.set(line.runId, row);
+    }
+    return [...byId.values()].sort((a, b) => String(b.startedAt).localeCompare(String(a.startedAt))).slice(0, limit);
+  };
+
+  const runPath = (runId) => (RUN_ID.test(String(runId)) ? join(runsDir, `${runId}.jsonl`) : null);
+
+  const readRun = (runId) => {
+    const path = runPath(runId);
+    return path && existsSync(path) ? readRecord(readFileSync(path, 'utf8')).map(asEvent) : null;
+  };
+
+  /**
+   * verifyRun(runId) → { ok, errors: [{seq, reason, detail?}], entries, head, settled } | null
+   *
+   * The chain check from verifyRecord, plus the last line against the head the
+   * index recorded at settle (head_mismatch, count_mismatch). The index sits
+   * beside the record, so that check catches accidents, not an editor.
+   */
+  const verifyRun = (runId) => {
+    const path = runPath(runId);
+    if (!path || !existsSync(path)) return null;
+    const result = verifyRecord(readFileSync(path, 'utf8'));
+    const sealed = readJsonl(indexPath).filter((row) => row.runId === runId && row.head).pop();
+    if (sealed) {
+      if (sealed.entries !== result.entries) result.errors.push({ seq: sealed.entries, reason: 'count_mismatch', detail: `index ${sealed.entries}, file ${result.entries}` });
+      else if (sealed.head !== result.head) result.errors.push({ seq: sealed.entries, reason: 'head_mismatch' });
+      result.ok = result.errors.length === 0;
+    }
+    return result;
+  };
+
+  return { root, startRun, listRuns, readRun, verifyRun };
+};

package/node_modules/@commonlyai/seats/src/turn-processes.js

@@ -0,0 +1,226 @@
+/**
+ * Processes a turn leaves running.
+ *
+ * A turn can start work that outlives it. A dev server backgrounded from a
+ * shell tool (`npm exec vite &`) is orphaned the moment that shell exits and
+ * is reparented to launchd, where no group kill or descendant walk from the
+ * turn's child can reach it. Six such trees, one to four days old, took the
+ * fleet host's swap to 12 GB (SRE, 2026-11-01).
+ *
+ * So a turn's child is started with a fresh marker in its environment, which
+ * every process it starts inherits however it detaches. When the child has
+ * closed, the processes still carrying the marker are stopped: SIGTERM, then
+ * SIGKILL after a grace for any still alive. That includes a lasting server
+ * the turn started on first use, such as tmux, and a seat it restarted. A
+ * process started with COMMONLY_KEEP_PROCESS=1 is left running, and so is
+ * anything it starts, even one that clears the setting; the turn's child itself
+ * never inherits it. A confined seat's turn does not honour the setting: what
+ * a confined turn leaves running is stopped whatever its environment says,
+ * because a process that outlives the turn would keep running with the
+ * turn's grants after the host has moved on to preparing the next one.
+ * COMMONLY_TURN_REAP=0 turns the whole check off.
+ *
+ * Only processes started since the turn began are read, and each one's
+ * environment is only compared against the marker and the keep setting. Each
+ * pid is re-read just before it is signalled, and is signalled only while its
+ * start time is still the one recorded, so a reused pid is left alone.
+ *
+ * What it does not catch: on macOS `ps -E` cannot read the environment of an
+ * Apple platform binary (sh, bash, sleep), so one of those is stopped only as
+ * a descendant of a marked process. A process that clears its environment
+ * loses the marker. Both are left running. The same unreadable environment
+ * hides a keep setting: a kept Apple binary is not seen as kept, so a process
+ * it starts is kept only if that process keeps the setting itself.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import {
+  PROCESS_GROUPS_SUPPORTED, readProcesses, readProcessTable, startedMs,
+} from './process-group.js';
+
+export const TURN_MARK_ENV = 'COMMONLY_TURN_ID';
+export const KEEP_PROCESS_ENV = 'COMMONLY_KEEP_PROCESS';
+export const TURN_REAP_ENV = 'COMMONLY_TURN_REAP';
+export const TURN_REAP_GRACE_MS = 5_000;
+// How far before the turn a process's recorded start may read and still be
+// looked at. lstart has one-second resolution, and on Linux ps derives it from
+// the boot time, which drifts from the wall clock by a second or more. The
+// window only bounds what is read; the marker decides.
+export const TURN_START_SLACK_MS = 60_000;
+
+export const turnReapEnabled = (env = process.env) => PROCESS_GROUPS_SUPPORTED && env?.[TURN_REAP_ENV] !== '0';
+
+const PS_ENV = { ...process.env, LC_ALL: 'C' };
+
+// pid -> the set of tokens its environment reads as. A pid whose environment
+// could not be read has no entry, or a set without NAME=value pairs.
+const readEnvironmentsDarwin = (pids) => {
+  const out = new Map();
+  const res = spawnSync('ps', ['-E', '-ww', '-o', 'pid=,command=', '-p', pids.join(',')], {
+    encoding: 'utf8', env: PS_ENV, timeout: 5000, maxBuffer: 64 * 1024 * 1024,
+  });
+  if (res.error) return out;
+  for (const line of String(res.stdout || '').split('\n')) {
+    const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+    if (match) out.set(Number(match[1]), new Set(match[2].split(/\s+/)));
+  }
+  return out;
+};
+
+const readEnvironmentsLinux = (pids) => {
+  const out = new Map();
+  for (const pid of pids) {
+    try {
+      out.set(pid, new Set(readFileSync(`/proc/${pid}/environ`, 'utf8').split('\0')));
+    } catch { /* gone, or not readable */ }
+  }
+  return out;
+};
+
+export const readEnvironments = (pids) => {
+  if (!pids.length || !PROCESS_GROUPS_SUPPORTED) return new Map();
+  return process.platform === 'linux' ? readEnvironmentsLinux(pids) : readEnvironmentsDarwin(pids);
+};
+
+const selfAndAncestors = (table, pid) => {
+  const byPid = new Map(table.map((row) => [row.pid, row]));
+  const out = new Set([pid]);
+  for (let row = byPid.get(pid); row && row.ppid > 0 && !out.has(row.ppid); row = byPid.get(row.ppid)) {
+    out.add(row.ppid);
+  }
+  return out;
+};
+
+/**
+ * The processes still carrying `mark`, as { pid, ppid, started }: started at
+ * or after `since` (ms), neither this process nor an ancestor of it, and
+ * neither kept nor under a kept one. Each one brings its descendants, except a
+ * kept one and everything
+ * under it, whose environments may be unreadable. The start-time window only
+ * limits what is read; the marker is what decides. With `honorKeep: false`
+ * (a confined turn) nothing is kept, and a row whose environment carried the
+ * keep setting is returned with `keepIgnored: true`. `io` is a test seam
+ * ({ table, envs, self }).
+ */
+export const findTurnProcesses = (mark, since, io = {}, { honorKeep = true } = {}) => {
+  const { table = readProcessTable, envs = readEnvironments, self = process.pid } = io;
+  if (!mark) return [];
+  const rows = table();
+  if (!rows) return [];
+  const skip = selfAndAncestors(rows, self);
+  const floor = Number(since) - TURN_START_SLACK_MS;
+  const recent = rows.filter((row) => !skip.has(row.pid) && startedMs(row.started) >= floor);
+  const environments = envs(recent.map((row) => row.pid));
+  const marked = `${TURN_MARK_ENV}=${mark}`;
+  const keep = `${KEEP_PROCESS_ENV}=1`;
+  const askedToKeep = (pid) => environments.get(pid)?.has(keep) === true;
+  const kept = (pid) => honorKeep && askedToKeep(pid);
+  const byPid = new Map(rows.map((row) => [row.pid, row]));
+  // A kept process keeps what it starts even when that drops the setting.
+  const underKept = (row) => {
+    for (let up = byPid.get(row.ppid), seen = new Set(); up && !seen.has(up.pid); up = byPid.get(up.ppid)) {
+      if (kept(up.pid)) return true;
+      seen.add(up.pid);
+    }
+    return false;
+  };
+  const found = new Map();
+  for (const row of recent) {
+    if (environments.get(row.pid)?.has(marked) && !kept(row.pid) && !underKept(row)) found.set(row.pid, row);
+  }
+  const byParent = new Map();
+  for (const row of rows) {
+    if (row.pid === row.ppid) continue;
+    if (!byParent.has(row.ppid)) byParent.set(row.ppid, []);
+    byParent.get(row.ppid).push(row);
+  }
+  for (const stack = [...found.keys()]; stack.length;) {
+    for (const child of byParent.get(stack.pop()) || []) {
+      if (found.has(child.pid) || skip.has(child.pid) || kept(child.pid)) continue;
+      found.set(child.pid, child);
+      stack.push(child.pid);
+    }
+  }
+  const out = [...found.values()];
+  return honorKeep ? out : out.map((row) => (askedToKeep(row.pid) ? { ...row, keepIgnored: true } : row));
+};
+
+/**
+ * Stop what `findTurnProcesses` returns. SIGTERM is sent before this returns;
+ * `done` settles after `graceMs`, once anything still alive has had SIGKILL.
+ * A pid is signalled only while its start time is the one recorded, read for
+ * all of them in one ps call per signal. The grace timer holds the process
+ * open until SIGKILL has gone out, so a seat stopped mid-turn still escalates.
+ * `io` adds `read` (pids -> rows) to the find seam.
+ */
+export const reapTurnProcesses = (mark, since, { graceMs = TURN_REAP_GRACE_MS, io = {}, honorKeep = true } = {}) => {
+  const read = io.read || readProcesses;
+  const signal = (rows, name) => {
+    const now = new Map((read(rows.map((row) => row.pid)) || []).map((row) => [row.pid, row]));
+    return rows.filter((row) => {
+      if (now.get(row.pid)?.started !== row.started) return false;
+      try { process.kill(row.pid, name); return true; } catch { return false; }
+    });
+  };
+  const termed = signal(findTurnProcesses(mark, since, io, { honorKeep }), 'SIGTERM');
+  const done = termed.length === 0
+    ? Promise.resolve({ killed: [] })
+    : new Promise((resolve) => {
+      setTimeout(() => resolve({ killed: signal(termed, 'SIGKILL').map((row) => row.pid) }), graceMs);
+    });
+  return {
+    termed: termed.map((row) => row.pid),
+    keepIgnored: termed.filter((row) => row.keepIgnored).map((row) => row.pid),
+    honorKeep,
+    done,
+  };
+};
+
+/**
+ * One turn's marker. `env` is the child's environment with the marker added;
+ * `reap(child)` runs once the child has closed, and returns what
+ * `reapTurnProcesses` does, or null when the check is off, the child never had
+ * a pid, or the turn was already reaped. `confined` marks a confined seat's
+ * turn, whose reap does not honour the keep setting.
+ */
+export const markTurn = (env, {
+  enabled = turnReapEnabled(), now = Date.now, graceMs, confined = false,
+} = {}) => {
+  if (!enabled) return { env, mark: null, reap: () => null };
+  const mark = randomUUID();
+  const since = now();
+  // A keep setting the seat itself was started with would keep every turn.
+  const childEnv = { ...env, [TURN_MARK_ENV]: mark };
+  delete childEnv[KEEP_PROCESS_ENV];
+  let reaped = false;
+  return {
+    env: childEnv,
+    mark,
+    reap: (child, { io } = {}) => {
+      if (reaped || !Number.isInteger(child?.pid) || child.pid <= 0) return null;
+      reaped = true;
+      try {
+        return reapTurnProcesses(mark, since, { graceMs, io, honorKeep: !confined });
+      } catch { return null; }
+    },
+  };
+};
+
+/**
+ * The log line for a reap that stopped something, or null. A confined turn's
+ * line offers no keep setting, and says once when one was set and not
+ * honoured.
+ */
+export const describeTurnReap = (result) => {
+  if (!result?.termed?.length) return null;
+  const n = result.termed.length;
+  const stopped = `stopped ${n} process${n === 1 ? '' : 'es'} this turn left running (pid ${result.termed.join(', ')})`;
+  if (result.honorKeep !== false) {
+    return `${stopped}; start one with ${KEEP_PROCESS_ENV}=1 to keep it across turns`;
+  }
+  if (!result.keepIgnored?.length) return stopped;
+  return `${stopped}; ${KEEP_PROCESS_ENV}=1 was set on pid ${result.keepIgnored.join(', ')} `
+    + 'and is not honoured on a confined seat';
+};