@monster-orange/den 0.3.0 → 0.4.0

package/src/shared/sessions/names.ts

@@ -0,0 +1,85 @@
+/**
+ * Session names: `<dist>-<workspace>:<name>` (AG spec §2, MD-1). The
+ * distribution prefix keeps two distributions apart on one machine; the
+ * workspace part is what scopes a list to one workspace (§5c gate).
+ */
+import { WORKSPACE_NAME_RE } from "../agent-actor.js";
+import type { SessionInfo } from "./types.js";
+
+/** A session's own name: the same rules as a workspace name. */
+export const SESSION_NAME_RE = WORKSPACE_NAME_RE;
+
+export function sessionName(
+  dist: string,
+  workspace: string,
+  name: string,
+): string {
+  if (!WORKSPACE_NAME_RE.test(workspace))
+    throw new Error(
+      `workspace "${workspace}" is not a workspace name (letters, digits, ".", "_", "-"; 1-64 long)`,
+    );
+  if (!SESSION_NAME_RE.test(name))
+    throw new Error(
+      `session name "${name}" must be letters, digits, ".", "_" or "-", 1-64 long, starting with a letter or digit`,
+    );
+  return `${dist}-${workspace}:${name}`;
+}
+
+/** The workspace and name in `full`, or null when it isn't one of `dist`'s. */
+export function parseSessionName(
+  full: string,
+  dist: string,
+): { workspace: string; name: string } | null {
+  const prefix = `${dist}-`;
+  if (!full.startsWith(prefix)) return null;
+  const rest = full.slice(prefix.length);
+  const colon = rest.lastIndexOf(":");
+  if (colon <= 0) return null;
+  const workspace = rest.slice(0, colon);
+  const name = rest.slice(colon + 1);
+  if (!WORKSPACE_NAME_RE.test(workspace) || !SESSION_NAME_RE.test(name))
+    return null;
+  return { workspace, name };
+}
+
+/** Whether `s` belongs to `workspace` of `dist`. */
+export function inWorkspace(
+  s: Pick<SessionInfo, "name">,
+  dist: string,
+  workspace: string,
+): boolean {
+  return parseSessionName(s.name, dist)?.workspace === workspace;
+}
+
+/**
+ * The session `target` names: an id, a full name, `<workspace>:<name>`, or
+ * a bare name that only one session has (within `workspace` when given). A
+ * running session wins over an exited one of the same name.
+ */
+export function resolveSession(
+  sessions: SessionInfo[],
+  dist: string,
+  target: string,
+  workspace?: string,
+): SessionInfo {
+  const byId = sessions.find((s) => s.ref.id === target);
+  if (byId) return byId;
+  const matches = sessions.filter((s) => {
+    const p = parseSessionName(s.name, dist);
+    if (!p) return s.name === target;
+    if (s.name === target) return true;
+    if (`${p.workspace}:${p.name}` === target) return true;
+    return p.name === target && (!workspace || p.workspace === workspace);
+  });
+  const running = matches.filter((s) => !s.exited);
+  const pool = running.length ? running : matches;
+  const names = [...new Set(pool.map((s) => s.name))];
+  if (names.length === 1) return pool[pool.length - 1];
+  if (!names.length)
+    throw new Error(
+      `no session "${target}"${workspace ? ` in ${workspace}` : ""}`,
+    );
+  throw new Error(
+    `"${target}" names more than one session: ${names.sort().join(", ")}. Give the full name or the id.`,
+  );
+}

package/src/shared/sessions/paths.ts

@@ -0,0 +1,27 @@
+/**
+ * Where the session host keeps its files, in the distribution's state dir
+ * (getStateDir: the profile's ~/.<name>, or <PREFIX>_HOME):
+ *
+ *   sessions.sock         the host's unix socket (0600)
+ *   sessions.lock         held only while a host starts
+ *   sessions/<id>.json    a session's record (no argv, no env)
+ *   sessions/<id>.log     its scrollback (0600)
+ */
+import * as path from "path";
+
+export interface SessionPaths {
+  socket: string;
+  lock: string;
+  dir: string;
+}
+
+export function sessionPaths(stateDir: string): SessionPaths {
+  return {
+    socket: path.join(stateDir, "sessions.sock"),
+    lock: path.join(stateDir, "sessions.lock"),
+    dir: path.join(stateDir, "sessions"),
+  };
+}
+
+/** A unix socket path's limit, in bytes (macOS's sun_path is 104, with NUL). */
+export const MAX_SOCKET_PATH = 103;

package/src/shared/sessions/protocol.ts

@@ -0,0 +1,72 @@
+/**
+ * The session host's wire protocol, version 1: newline-delimited JSON over
+ * the host's unix socket, both ways. Terminal bytes travel base64 in `data`.
+ *
+ *   request   {v, id, op, ...}            client → host
+ *   reply     {id, ok: true, ...}         host → client, one per request
+ *             {id, ok: false, code, error}
+ *   event     {ev: "data", aid, data}     host → client, per attachment
+ *             {ev: "exit", aid, exitCode}
+ *
+ * ops: hello, start, list, attach, detach, write, resize, signal,
+ * scrollback, forget, shutdown. A request whose `v` is not the host's is
+ * refused with code "protocol", except `shutdown`, which every version
+ * takes, so an older host can always be stopped.
+ *
+ * An attach reply comes after its replay: once a client has the reply, the
+ * scrollback has been delivered and live output follows, with no gap and
+ * nothing twice.
+ */
+import { StringDecoder } from "string_decoder";
+
+export const PROTOCOL_VERSION = 1;
+
+/** A line longer than this ends the connection (a replay is ~2.7 MB). */
+export const MAX_LINE_BYTES = 16 * 1024 * 1024;
+
+export type HostErrorCode =
+  | "protocol"
+  | "bad-request"
+  | "not-found"
+  | "exists"
+  | "cap"
+  | "unavailable"
+  | "spawn"
+  | "exited";
+
+export interface Request {
+  v: number;
+  id: number;
+  op: string;
+  [key: string]: unknown;
+}
+
+export type Reply =
+  | ({ id: number; ok: true } & Record<string, unknown>)
+  | { id: number; ok: false; code: HostErrorCode; error: string };
+
+export type HostEvent =
+  | { ev: "data"; aid: string; data: string }
+  | { ev: "exit"; aid: string; exitCode?: number };
+
+/** Splits a byte stream into lines; refuses one that grows too long. */
+export class LineReader {
+  private buf = "";
+  private readonly decoder = new StringDecoder("utf8");
+
+  constructor(private readonly onLine: (line: string) => void) {}
+
+  /** Returns false once a line is too long: drop the connection. */
+  push(chunk: Buffer | string): boolean {
+    this.buf += typeof chunk === "string" ? chunk : this.decoder.write(chunk);
+    let nl: number;
+    while ((nl = this.buf.indexOf("\n")) !== -1) {
+      const line = this.buf.slice(0, nl);
+      this.buf = this.buf.slice(nl + 1);
+      if (line.trim()) this.onLine(line);
+    }
+    return this.buf.length <= MAX_LINE_BYTES;
+  }
+}
+
+export const frame = (o: unknown): string => JSON.stringify(o) + "\n";

package/src/shared/sessions/pty.ts

@@ -0,0 +1,141 @@
+/**
+ * The PTY seam for den-pty (AG-3a, Q-AG-1).
+ *
+ * A real terminal needs a native module: @lydell/node-pty, an
+ * optionalDependency at an exact version. Its binaries are prebuilt and
+ * ship in per-platform packages npm installs alongside it (no install
+ * script, nothing downloaded after install). When it is missing (an
+ * `--omit=optional` install, an unsupported platform, a node_modules copied
+ * across operating systems), loadPty says why instead of throwing, and
+ * den-pty reports itself unavailable with that reason (`<cli> doctor`).
+ *
+ * The host only ever sees PtyFactory, so tests run a scripted or piped
+ * stand-in and never need the module.
+ */
+import { createRequire } from "module";
+import * as path from "path";
+import { getEngineRoot } from "../paths.js";
+
+export const PTY_MODULE = "@lydell/node-pty";
+
+export interface PtySpawnOptions {
+  cwd: string;
+  env: Record<string, string>;
+  cols: number;
+  rows: number;
+}
+
+export interface PtyExit {
+  exitCode: number;
+  signal?: number;
+}
+
+/** What the host needs of a terminal. Data is bytes both ways. */
+export interface PtyProcess {
+  readonly pid: number;
+  onData(fn: (data: Buffer) => void): void;
+  onExit(fn: (e: PtyExit) => void): void;
+  write(data: Buffer): void;
+  resize(cols: number, rows: number): void;
+  /** `signal` is a Node signal name ("SIGTERM"). */
+  kill(signal: string): void;
+}
+
+export type PtyFactory = (
+  file: string,
+  args: string[],
+  opts: PtySpawnOptions,
+) => PtyProcess;
+
+export type PtyLoad =
+  | { available: true; factory: PtyFactory }
+  | { available: false; reason: string };
+
+/** The subset of the module's API that is used. */
+interface NativePty {
+  pid: number;
+  onData(fn: (d: string | Buffer) => void): unknown;
+  onExit(fn: (e: { exitCode: number; signal?: number }) => void): unknown;
+  write(d: string | Buffer): void;
+  resize(cols: number, rows: number): void;
+  kill(signal?: string): void;
+}
+interface NativeModule {
+  spawn(file: string, args: string[], opts: Record<string, unknown>): NativePty;
+}
+
+/** Resolve modules as Den's own package does (hoisted in a distribution). */
+function engineRequire(id: string): unknown {
+  return createRequire(path.join(getEngineRoot(), "package.json"))(id);
+}
+
+function wrap(mod: NativeModule): PtyFactory {
+  return (file, args, opts) => {
+    const p = mod.spawn(file, args, {
+      name: opts.env.TERM || "xterm-256color",
+      cols: opts.cols,
+      rows: opts.rows,
+      cwd: opts.cwd,
+      env: opts.env,
+      // Bytes, not strings: output is relayed as it came.
+      encoding: null,
+    });
+    return {
+      pid: p.pid,
+      onData: (fn) =>
+        void p.onData((d) => fn(Buffer.isBuffer(d) ? d : Buffer.from(d))),
+      onExit: (fn) =>
+        void p.onExit((e) => fn({ exitCode: e.exitCode, signal: e.signal })),
+      write: (d) => p.write(d),
+      resize: (c, r) => p.resize(c, r),
+      // The session leads its own process group: signal all of it, so a
+      // shell's foreground job gets the INT too.
+      kill: (signal) => {
+        try {
+          process.kill(-p.pid, signal as NodeJS.Signals);
+        } catch {
+          try {
+            p.kill(signal);
+          } catch {
+            /* already gone */
+          }
+        }
+      },
+    };
+  };
+}
+
+let memo: PtyLoad | null = null;
+
+/**
+ * The PTY module, or why it can't be used. `req` is for tests; the default
+ * resolves from Den's package and is remembered.
+ */
+export function loadPty(req?: (id: string) => unknown): PtyLoad {
+  if (!req && memo) return memo;
+  let result: PtyLoad;
+  try {
+    const mod = (req ?? engineRequire)(PTY_MODULE) as Partial<NativeModule>;
+    result =
+      typeof mod?.spawn === "function"
+        ? { available: true, factory: wrap(mod as NativeModule) }
+        : {
+            available: false,
+            reason: `${PTY_MODULE} loaded but has no spawn(): not a PTY module Den knows`,
+          };
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    const own =
+      err.code === "MODULE_NOT_FOUND" &&
+      String(err.message).includes(`'${PTY_MODULE}'`);
+    result = {
+      available: false,
+      reason: own
+        ? `${PTY_MODULE} is not installed (an optional dependency of Den; ` +
+          `reinstall without --omit=optional, on a platform it ships binaries for)`
+        : String(err.message).split("\n")[0].trim(),
+    };
+  }
+  if (!req) memo = result;
+  return result;
+}

package/src/shared/sessions/ring-buffer.ts

@@ -0,0 +1,160 @@
+/**
+ * Scrollback (AG spec §3): a ring buffer per session that keeps the newest
+ * bytes (default 2 MB), and its log at `<stateDir>/sessions/<id>.log`, so a
+ * host that restarted can still replay a session's history.
+ *
+ * The log is appended to as output arrives (flushed every `flushMs`), and
+ * rewritten from the ring once it passes twice the ring's capacity, so it
+ * never grows without bound. A truncation can split a multi-byte character
+ * or an escape sequence at the very start of a replay; a terminal shrugs
+ * that off.
+ */
+import * as fs from "fs";
+
+export const DEFAULT_SCROLLBACK_BYTES = 2 * 1024 * 1024;
+
+export class ScrollbackRing {
+  private buf: Buffer;
+  /** Index of the oldest byte. */
+  private start = 0;
+  private length = 0;
+  private droppedBytes = 0;
+
+  constructor(readonly capacity: number = DEFAULT_SCROLLBACK_BYTES) {
+    if (!Number.isInteger(capacity) || capacity < 1)
+      throw new Error(`scrollback capacity must be a positive whole number`);
+    this.buf = Buffer.alloc(capacity);
+  }
+
+  get size(): number {
+    return this.length;
+  }
+
+  /** Bytes pushed out of the ring so far. */
+  get dropped(): number {
+    return this.droppedBytes;
+  }
+
+  push(chunk: Uint8Array): void {
+    let data = Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+    if (data.length >= this.capacity) {
+      this.droppedBytes += this.length + data.length - this.capacity;
+      data = data.subarray(data.length - this.capacity);
+      data.copy(this.buf, 0);
+      this.start = 0;
+      this.length = this.capacity;
+      return;
+    }
+    const overflow = this.length + data.length - this.capacity;
+    if (overflow > 0) {
+      this.start = (this.start + overflow) % this.capacity;
+      this.length -= overflow;
+      this.droppedBytes += overflow;
+    }
+    const end = (this.start + this.length) % this.capacity;
+    const first = Math.min(data.length, this.capacity - end);
+    data.copy(this.buf, end, 0, first);
+    if (first < data.length) data.copy(this.buf, 0, first);
+    this.length += data.length;
+  }
+
+  /** The newest `maxBytes` (all of it by default), oldest first. */
+  snapshot(maxBytes: number = this.capacity): Buffer {
+    const n = Math.max(0, Math.min(maxBytes, this.length));
+    const from = (this.start + this.length - n) % this.capacity;
+    if (from + n <= this.capacity)
+      return Buffer.from(this.buf.subarray(from, from + n));
+    return Buffer.concat([
+      this.buf.subarray(from),
+      this.buf.subarray(0, n - (this.capacity - from)),
+    ]);
+  }
+}
+
+export interface ScrollbackLogOptions {
+  /** How long output waits before it is written; 0 writes on flush() only. */
+  flushMs?: number;
+}
+
+export class ScrollbackLog {
+  private pending: Buffer[] = [];
+  private timer: NodeJS.Timeout | null = null;
+  private written: number;
+
+  constructor(
+    readonly file: string,
+    readonly ring: ScrollbackRing,
+    private readonly opts: ScrollbackLogOptions = {},
+  ) {
+    try {
+      this.written = fs.statSync(file).size;
+    } catch {
+      this.written = 0;
+    }
+  }
+
+  /** A ring holding the newest `capacity` bytes of `file` (empty if none). */
+  static load(
+    file: string,
+    capacity: number = DEFAULT_SCROLLBACK_BYTES,
+  ): ScrollbackRing {
+    const ring = new ScrollbackRing(capacity);
+    let fd: number;
+    try {
+      fd = fs.openSync(file, "r");
+    } catch {
+      return ring;
+    }
+    try {
+      const size = fs.fstatSync(fd).size;
+      const n = Math.min(size, capacity);
+      const buf = Buffer.alloc(n);
+      fs.readSync(fd, buf, 0, n, size - n);
+      ring.push(buf);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return ring;
+  }
+
+  append(chunk: Uint8Array): void {
+    this.ring.push(chunk);
+    this.pending.push(Buffer.from(chunk));
+    const ms = this.opts.flushMs ?? 200;
+    if (ms > 0 && !this.timer) {
+      this.timer = setTimeout(() => {
+        this.timer = null;
+        this.flush();
+      }, ms);
+      this.timer.unref();
+    }
+  }
+
+  /** Write what is pending; rewrite the log from the ring once it is too big. */
+  flush(): void {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (!this.pending.length) return;
+    const data = Buffer.concat(this.pending);
+    this.pending = [];
+    try {
+      if (this.written + data.length > 2 * this.ring.capacity) {
+        const all = this.ring.snapshot();
+        fs.writeFileSync(this.file, all, { mode: 0o600 });
+        this.written = all.length;
+      } else {
+        fs.appendFileSync(this.file, data, { mode: 0o600 });
+        this.written += data.length;
+      }
+    } catch {
+      /* the ring still has it; the next flush tries again from there */
+      this.written = Number.POSITIVE_INFINITY;
+    }
+  }
+
+  close(): void {
+    this.flush();
+  }
+}

package/src/shared/sessions/types.ts

@@ -0,0 +1,81 @@
+/**
+ * The session backend contract (strategy kind `session-backend`, AG spec
+ * §2). A backend starts an argv in a cwd with an env and keeps its PTY; it
+ * knows nothing about agents, personas or runtimes. Den maps a session to
+ * its agent (AG-2a); the backend never does.
+ *
+ * Session names are `<dist>-<workspace>:<name>` (names.ts), so two
+ * distributions on one machine never collide.
+ */
+
+/** Which backend holds a session, and its id there. */
+export interface SessionRef {
+  backend: string;
+  id: string;
+}
+
+/** A session as a backend lists it. */
+export interface SessionInfo {
+  ref: SessionRef;
+  /** `<dist>-<workspace>:<name>`. */
+  name: string;
+  pid: number;
+  /** ISO 8601. */
+  startedAt: string;
+  exited?: boolean;
+  exitCode?: number;
+  /**
+   * Set once input ending a line (Enter) has been written to it: someone
+   * prompted it. A runtime with nothing to resume until then (den-claude)
+   * starts afresh instead. Never what was typed.
+   */
+  prompted?: boolean;
+}
+
+/** What to run. `env` is the whole environment: nothing is inherited. */
+export interface SessionSpec {
+  name: string;
+  cwd: string;
+  argv: string[];
+  env: Record<string, string>;
+  cols: number;
+  rows: number;
+}
+
+export interface AttachHandlers {
+  /** Output, scrollback replay first. */
+  onData(data: Buffer): void;
+  /** The session ended (at once, after the replay, when it already had). */
+  onExit?(exitCode: number | undefined): void;
+}
+
+/** One attachment; a session has any number, each gets all the output. */
+export interface Attachment {
+  /** Settles once the replay has been delivered and live output follows. */
+  readonly ready: Promise<SessionInfo>;
+  /** Stop receiving output. The session keeps running. */
+  detach(): void;
+}
+
+export type SessionSignal = "INT" | "TERM" | "KILL";
+export const SESSION_SIGNALS: readonly SessionSignal[] = [
+  "INT",
+  "TERM",
+  "KILL",
+];
+
+export interface SessionBackend {
+  /** "den-pty", "tmux". */
+  readonly id: string;
+  start(spec: SessionSpec): Promise<SessionRef>;
+  /** Survives a web server restart: the sessions live elsewhere. */
+  list(): Promise<SessionInfo[]>;
+  attach(ref: SessionRef, handlers: AttachHandlers): Attachment;
+  write(ref: SessionRef, bytes: Uint8Array): void;
+  resize(ref: SessionRef, cols: number, rows: number): void;
+  signal(ref: SessionRef, signal: SessionSignal): void;
+  /** The newest `maxBytes` of output, for a replay on attach. */
+  scrollback(ref: SessionRef, maxBytes: number): Promise<Uint8Array>;
+  /** A command a person can run to attach outside Den (tmux), or null. */
+  externalAttach?(ref: SessionRef): string | null;
+}