@monster-orange/den 0.4.0 → 0.4.1

package/src/ui/server/session-routes.ts

@@ -0,0 +1,445 @@
+/**
+ * The Agents tab's routes (AG-4a-term, AG spec §5d):
+ *
+ *   GET /api/sessions            every session and agent in the active
+ *                                workspaces (read-only class)
+ *   WS  /api/sessions/<id>/io    a session's terminal (shell-grade)
+ *
+ * The list joins the session host's sessions to the agent records, as
+ * `<cli> agents list` does (agent-ops.ts agentRows), and adds the plain
+ * sessions (`sessions start`), labelled kind "session". An agent whose
+ * actor token `web logout --all` revoked is marked (tokenRevoked). The
+ * host knows nothing of approvals yet, so `waiting` is never set here
+ * (AG-6a adds it). Asking never starts a session host.
+ *
+ * The io route bridges one WebSocket to one attachment on the session host
+ * (its own connection to the host, so a browser and the CLI, or two
+ * browsers, attach at once and each gets every byte):
+ *   - on attach, the scrollback replay, then live output: binary frames;
+ *   - a text frame `{"type":"session",…}` first (what is attached), and
+ *     `{"type":"exit","exitCode":n}` when the session ends;
+ *   - in: binary frames are input; a text frame is JSON control:
+ *     `{"type":"resize","cols":c,"rows":r}` (or `{"type":"input","data":s}`).
+ * Closing the socket detaches. Nothing here ever signals a session: leaving
+ * the tab never kills it.
+ *
+ * The request checks ran before (index.ts, request-guard.ts): Host, Origin
+ * on the upgrade, CSRF (the `den.csrf.<token>` subprotocol: a browser's
+ * WebSocket can't send a header), a signed-in session beyond loopback, and
+ * an agent token's own session only. The attach and the detach are audited
+ * with the actor from the credential.
+ */
+import type * as http from "http";
+import type { Duplex } from "stream";
+import { getActiveWorkspaces } from "../../shared/environment-manager/workspaces.js";
+import { getStateDir } from "../../shared/paths.js";
+import { product } from "../../shared/product.js";
+import { revokedAgentIds } from "../../shared/actor-token.js";
+import { listRecords } from "../../shared/agents/records.js";
+import {
+  connectHost,
+  noHost,
+  type HostClient,
+} from "../../shared/sessions/client.js";
+import { parseSessionName } from "../../shared/sessions/names.js";
+import { sessionPaths } from "../../shared/sessions/paths.js";
+import { loadPty, type PtyLoad } from "../../shared/sessions/pty.js";
+import type { SessionInfo } from "../../shared/sessions/types.js";
+import { agentRows } from "../cli/agent-ops.js";
+import { state as sessionState } from "../cli/sessions-command.js";
+import { recordAction } from "./audit.js";
+import { sendJson } from "./http-helpers.js";
+import { auditActorOf, principalOf } from "./request-guard.js";
+import {
+  acceptWebSocket,
+  handshakeRefusal,
+  refuseUpgrade,
+  WS_CLOSE,
+} from "./websocket.js";
+
+export interface SessionRouteDeps {
+  stateDir?: () => string;
+  /** The distribution's name: the `<dist>` of a session name. */
+  dist?: () => string;
+  /** A client of the running host, or null (never starts one). */
+  connectExisting?: () => Promise<HostClient | null>;
+  activeWorkspaces?: () => string[];
+  pty?: () => PtyLoad;
+}
+
+interface Resolved {
+  stateDir: () => string;
+  dist: () => string;
+  connectExisting: () => Promise<HostClient | null>;
+  activeWorkspaces: () => string[];
+  pty: () => PtyLoad;
+}
+
+function resolve(d: SessionRouteDeps = {}): Resolved {
+  const stateDir = d.stateDir ?? (() => getStateDir());
+  return {
+    stateDir,
+    dist: d.dist ?? (() => product().name),
+    connectExisting:
+      d.connectExisting ??
+      (async () => {
+        try {
+          return await connectHost(sessionPaths(stateDir()).socket);
+        } catch (e) {
+          if (noHost(e)) return null;
+          throw e;
+        }
+      }),
+    activeWorkspaces: d.activeWorkspaces ?? (() => getActiveWorkspaces()),
+    pty: d.pty ?? (() => loadPty()),
+  };
+}
+
+/** The subprotocol the io route answers with. */
+export const IO_PROTOCOL = "den.io";
+
+const IO_PATH = /^\/api\/sessions\/([^/]+)\/io$/;
+
+/** One row of the Agents tab's list. */
+export interface ListedSession {
+  /** The session host's id; for an agent with no session, its last one. */
+  id: string;
+  /** `<dist>-<ws>:<name>`. */
+  name: string;
+  workspace: string;
+  kind: "agent" | "session";
+  /** The `<name>` part: an agent's id, a plain session's name. */
+  label: string;
+  agent?: string;
+  persona?: string;
+  runtime?: string;
+  model?: string;
+  cwd?: string;
+  /** running, stopping, exited (<code>), stopped, ended. */
+  state: string;
+  exited: boolean;
+  exitCode?: number;
+  startedAt?: string;
+  /** The host has it (running, or ended with its scrollback): a pane can attach. */
+  attachable: boolean;
+  resumable?: boolean;
+  /** Its actor token was revoked (`web logout --all`): restart or resume it. */
+  tokenRevoked?: boolean;
+  /** An approval is pending (AG-6a; only when the host knows). */
+  waiting?: boolean;
+}
+
+/** The list, from the host's sessions and the agent records. */
+export function listedSessions(
+  sessions: SessionInfo[],
+  d: Pick<Resolved, "stateDir" | "dist" | "activeWorkspaces">,
+): ListedSession[] {
+  const dist = d.dist();
+  const active = new Set(d.activeWorkspaces());
+  const mine = sessions.filter((s) => {
+    const p = parseSessionName(s.name, dist);
+    return p !== null && active.has(p.workspace);
+  });
+  const records = listRecords(d.stateDir()).filter((r) =>
+    active.has(r.workspace),
+  );
+  const revoked = revokedAgentIds(d.stateDir());
+  const out: ListedSession[] = [];
+  const agentSessions = new Set<string>();
+  for (const r of agentRows(mine, records)) {
+    const rec = records.find((x) => x.id === r.agent)!;
+    const s = r.session;
+    if (s) agentSessions.add(s.ref.id);
+    out.push({
+      id: s?.ref.id ?? rec.session.id,
+      name: s?.name ?? rec.sessionName,
+      workspace: rec.workspace,
+      kind: "agent",
+      label: rec.id,
+      agent: rec.id,
+      persona: rec.persona,
+      runtime: rec.runtime,
+      ...(rec.model ? { model: rec.model } : {}),
+      cwd: rec.cwd,
+      state: r.state,
+      exited: !s || s.exited === true,
+      ...(s?.exitCode !== undefined ? { exitCode: s.exitCode } : {}),
+      ...(r.startedAt ? { startedAt: r.startedAt } : {}),
+      attachable: Boolean(s),
+      resumable: r.resumable,
+      ...(revoked.has(rec.id) && s && !s.exited ? { tokenRevoked: true } : {}),
+    });
+  }
+  for (const s of mine) {
+    if (agentSessions.has(s.ref.id)) continue;
+    const p = parseSessionName(s.name, dist)!;
+    out.push({
+      id: s.ref.id,
+      name: s.name,
+      workspace: p.workspace,
+      kind: "session",
+      label: p.name,
+      state: sessionState(s),
+      exited: s.exited === true,
+      ...(s.exitCode !== undefined ? { exitCode: s.exitCode } : {}),
+      startedAt: s.startedAt,
+      attachable: true,
+    });
+  }
+  const order = [...active];
+  return out.sort(
+    (a, b) =>
+      order.indexOf(a.workspace) - order.indexOf(b.workspace) ||
+      (a.startedAt ?? "").localeCompare(b.startedAt ?? "") ||
+      a.label.localeCompare(b.label),
+  );
+}
+
+/**
+ * `GET /api/sessions`; false when `pathname` isn't it. `ioAllowed` is what
+ * the request checks say about this browser: beyond loopback without a
+ * session, the page lists but can't open a terminal.
+ */
+export async function handleSessionList(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  pathname: string,
+  ioAllowed: boolean,
+  deps: SessionRouteDeps = {},
+): Promise<boolean> {
+  if (pathname !== "/api/sessions") return false;
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    res.setHeader("Allow", "GET");
+    sendJson(res, { ok: false, error: "method not allowed" }, 405);
+    return true;
+  }
+  const d = resolve(deps);
+  const pty = d.pty();
+  let sessions: SessionInfo[] = [];
+  let host = false;
+  let hostError: string | undefined;
+  try {
+    const c = await d.connectExisting();
+    if (c) {
+      host = true;
+      try {
+        sessions = await c.list();
+      } finally {
+        c.close();
+      }
+    }
+  } catch (e) {
+    hostError = (e as Error).message;
+  }
+  sendJson(res, {
+    sessions: listedSessions(sessions, d),
+    workspaces: d.activeWorkspaces(),
+    host,
+    ...(hostError ? { hostError } : {}),
+    backend: pty.available
+      ? { id: "den-pty", available: true }
+      : { id: "den-pty", available: false, reason: pty.reason },
+    io: { allowed: ioAllowed },
+  });
+  return true;
+}
+
+/** Whether `pathname` is a session's io route. */
+export function isSessionIoPath(pathname: string): boolean {
+  return IO_PATH.test(pathname);
+}
+
+const TEXT = (code: number) =>
+  code === 400
+    ? "Bad Request"
+    : code === 404
+      ? "Not Found"
+      : code === 426
+        ? "Upgrade Required"
+        : "Service Unavailable";
+
+/**
+ * A plain HTTP request to an io route: it is a WebSocket. 426 for a GET,
+ * 404 for anything else under /api/sessions/.
+ */
+export function sendSessionHttp(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  pathname: string,
+): void {
+  if (
+    IO_PATH.test(pathname) &&
+    (req.method === "GET" || req.method === "HEAD")
+  ) {
+    res.setHeader("Upgrade", "websocket");
+    res.setHeader("Connection", "Upgrade");
+    sendJson(
+      res,
+      {
+        ok: false,
+        error: "This is a WebSocket: open it with an upgrade",
+        code: "upgrade_required",
+      },
+      426,
+    );
+    return;
+  }
+  sendJson(
+    res,
+    { ok: false, error: "No such session route", code: "not_found" },
+    404,
+  );
+}
+
+/**
+ * `GET /api/sessions/<id>/io` with an upgrade, after the request checks.
+ * `<id>` is the host's id or the full session name. Refusals answer as
+ * HTTP on the raw socket; past them, the WebSocket bridge above.
+ */
+export async function handleSessionUpgrade(
+  req: http.IncomingMessage,
+  socket: Duplex,
+  head: Buffer,
+  pathname: string,
+  requestId: string,
+  deps: SessionRouteDeps = {},
+): Promise<void> {
+  const refuse = (status: number, error: string, code: string) =>
+    refuseUpgrade(
+      socket,
+      status,
+      { ok: false, error, code, requestId },
+      TEXT(status),
+    );
+  const m = IO_PATH.exec(pathname);
+  if (!m) return refuse(404, "No WebSocket route here", "not_found");
+  const bad = handshakeRefusal(req);
+  if (bad) return refuse(400, bad, "bad_handshake");
+  let target = m[1];
+  try {
+    target = decodeURIComponent(target);
+  } catch {
+    /* as given */
+  }
+  const d = resolve(deps);
+  let c: HostClient | null;
+  try {
+    c = await d.connectExisting();
+  } catch (e) {
+    return refuse(
+      503,
+      `the session host: ${(e as Error).message}`,
+      "session_host",
+    );
+  }
+  if (!c)
+    return refuse(
+      404,
+      `no session "${target}" (no session host is running)`,
+      "not_found",
+    );
+  const client = c;
+  let info: SessionInfo | undefined;
+  try {
+    const dist = d.dist();
+    const active = new Set(d.activeWorkspaces());
+    info = (await client.list()).find((s) => {
+      const p = parseSessionName(s.name, dist);
+      return (
+        p !== null &&
+        active.has(p.workspace) &&
+        (s.ref.id === target || s.name === target)
+      );
+    });
+  } catch (e) {
+    client.close();
+    return refuse(
+      503,
+      `the session host: ${(e as Error).message}`,
+      "session_host",
+    );
+  }
+  if (!info) {
+    client.close();
+    return refuse(404, `no session "${target}" here`, "not_found");
+  }
+  if (socket.destroyed) {
+    client.close();
+    return;
+  }
+
+  const s = info;
+  const actor = auditActorOf(req);
+  const principal = principalOf(req);
+  const audit = (detail: string) =>
+    recordAction(actor, { verb: "sessions", detail }, principal);
+  const ws = acceptWebSocket(req, socket, head, { protocol: IO_PROTOCOL });
+  const since = Date.now();
+  audit(`attach ${s.name} (browser)`);
+  const p = parseSessionName(s.name, d.dist())!;
+  ws.send(
+    JSON.stringify({
+      type: "session",
+      id: s.ref.id,
+      name: s.name,
+      workspace: p.workspace,
+      label: p.name,
+      exited: s.exited === true,
+      ...(s.exitCode !== undefined ? { exitCode: s.exitCode } : {}),
+    }),
+  );
+  let exited = s.exited === true;
+  const att = client.attach(s.ref.id, {
+    onData: (data) => ws.send(data),
+    onExit: (exitCode) => {
+      exited = true;
+      ws.send(
+        JSON.stringify({
+          type: "exit",
+          ...(exitCode !== undefined ? { exitCode } : {}),
+        }),
+      );
+    },
+  });
+  att.ready.catch((e: Error) => {
+    ws.send(JSON.stringify({ type: "error", error: e.message }));
+    ws.close(WS_CLOSE.internal, "attach failed");
+  });
+  ws.on("message", (data: Buffer, binary: boolean) => {
+    if (binary) {
+      if (!exited && data.length) client.write(s.ref.id, data);
+      return;
+    }
+    let msg: { type?: unknown; cols?: unknown; rows?: unknown; data?: unknown };
+    try {
+      msg = JSON.parse(data.toString("utf-8")) as typeof msg;
+    } catch {
+      return;
+    }
+    if (msg?.type === "resize") {
+      const ok = (n: unknown): n is number =>
+        typeof n === "number" && Number.isInteger(n) && n >= 1 && n <= 1000;
+      if (!exited && ok(msg.cols) && ok(msg.rows))
+        client.resize(s.ref.id, msg.cols, msg.rows);
+    } else if (msg?.type === "input" && typeof msg.data === "string") {
+      if (!exited && msg.data)
+        client.write(s.ref.id, Buffer.from(msg.data, "utf-8"));
+    }
+  });
+  let done = false;
+  const detach = () => {
+    if (done) return;
+    done = true;
+    // Detach only: the session keeps running in the host.
+    att.detach();
+    client.close();
+    audit(
+      `detach ${s.name} (browser, ${Math.round((Date.now() - since) / 1000)}s)`,
+    );
+  };
+  ws.on("close", detach);
+  client.once("close", () => {
+    if (ws.open) ws.close(WS_CLOSE.goingAway, "the session host went away");
+    detach();
+  });
+}

package/src/ui/server/shutdown-guard.ts

@@ -0,0 +1,91 @@
+/**
+ * The web server's exit, bounded whatever happens.
+ *
+ * 1. **Lost output.** When the reader of the server's stdout or stderr goes
+ *    away (the terminal, test runner or script that started it was killed),
+ *    every write fails with EPIPE. Unhandled, that error reached the
+ *    "continue" uncaughtException guard, which logged it with console.error
+ *    to the equally dead stderr, which failed again: a tight loop that pinned
+ *    a core and stopped the server answering requests, for as long as the
+ *    orphan lived. Now the streams' errors are handled here, nothing is
+ *    written once the output is gone, and the server shuts down (its launcher
+ *    is gone; nobody can see it).
+ * 2. **A deadline.** The first SIGTERM or SIGINT starts the shutdown; when
+ *    nothing waits on the person (stdin isn't a TTY) a timer forces the exit
+ *    after `DEN_SHUTDOWN_DEADLINE_MS` (10 s), whatever the shutdown is stuck
+ *    on. A second signal exits at once (it was ignored, which left a stuck
+ *    shutdown deaf to every later SIGTERM).
+ */
+
+const DEFAULT_DEADLINE_MS = 10_000;
+
+let lost = false;
+let started = false;
+
+/** An error that says the stream's reader is gone. */
+export function isLostOutputError(e: unknown): boolean {
+  const code = (e as { code?: unknown } | null)?.code;
+  return code === "EPIPE" || code === "ERR_STREAM_DESTROYED";
+}
+
+/** True once stdout or stderr has lost its reader: write nothing more. */
+export function outputLost(): boolean {
+  return lost;
+}
+
+/**
+ * Handle stdout's and stderr's errors (so none is ever uncaught); on the
+ * first lost-output error, call `onLost` once.
+ */
+export function guardStdio(onLost: () => void): void {
+  for (const s of [process.stdout, process.stderr]) {
+    s.on("error", (e: unknown) => {
+      if (!isLostOutputError(e) || lost) return;
+      lost = true;
+      onLost();
+    });
+  }
+}
+
+/** The deadline, from DEN_SHUTDOWN_DEADLINE_MS (ms, > 0), else 10 s. */
+export function shutdownDeadlineMs(
+  env: NodeJS.ProcessEnv = process.env,
+): number {
+  const n = Number(env.DEN_SHUTDOWN_DEADLINE_MS);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_DEADLINE_MS;
+}
+
+function say(msg: string): void {
+  if (lost) return;
+  try {
+    process.stderr.write(msg + "\n");
+  } catch {
+    /* nowhere left to say it */
+  }
+}
+
+/**
+ * Start the shutdown for `signal` (`run`), once. A later call exits at once;
+ * a shutdown nobody waits on is forced to exit after the deadline.
+ */
+export function requestShutdown(
+  signal: string,
+  run: (signal: string) => void,
+  opts: { interactive: boolean; deadlineMs?: number },
+): void {
+  if (started) {
+    say(`[server] ${signal} again: exiting now.`);
+    process.exit(1);
+  }
+  started = true;
+  if (!opts.interactive) {
+    const ms = opts.deadlineMs ?? shutdownDeadlineMs();
+    setTimeout(() => {
+      say(
+        `[server] ${signal}: the shutdown did not finish within ${ms} ms; exiting.`,
+      );
+      process.exit(1);
+    }, ms).unref();
+  }
+  run(signal);
+}

package/src/ui/server/sudo-store.ts

@@ -9,7 +9,15 @@
  * because intermediate launchers (opctl, make, etc.) may reset the environment
  * before sudo is invoked. The cache is valid for ~5 min by default, which is
  * more than enough for a service to finish its startup sudo calls.
+ *
+ * SEC-1c (R8, SEC-1 §5): an agent's request never passes the lock. The
+ * server runs every request in its own lock scope (inRequestLockScope) and
+ * closes it for an agent's actor token (closeLockForThisRequest): inside a
+ * closed scope, and in everything the request starts (its spawned
+ * commands' callbacks included), the store reads as locked and hands out
+ * no sudo wrapper and warms no sudo cache.
  */
+import { AsyncLocalStorage } from "async_hooks";
 
 import * as fs from "fs";
 import * as os from "os";
@@ -19,6 +27,23 @@ import { CLI_SPAWN_TIMEOUT_MS } from "../../shared/constants.js";
 
 import { product } from "../../shared/product.js";
 let _sudoPassword: string | null = null;
+const lockScope = new AsyncLocalStorage<{ closed: boolean }>();
+
+/** Run one request in its own lock scope (open unless closed below). */
+export function inRequestLockScope<T>(fn: () => T): T {
+  return lockScope.run({ closed: false }, fn);
+}
+
+/** This request is an agent's: the lock stays shut for all it starts. */
+export function closeLockForThisRequest(): void {
+  const s = lockScope.getStore();
+  if (s) s.closed = true;
+}
+
+/** Whether the current request's lock scope is closed (an agent's). */
+export function lockClosedHere(): boolean {
+  return lockScope.getStore()?.closed === true;
+}
 let _sudoDir: string | null = null;
 
 export function setSudoPassword(password: string): void {
@@ -53,7 +78,7 @@ export function clearSudoPassword(): void {
  * 'sudo' call in the spawned process tree uses the stored password.
  */
 export function getSudoEnv(): NodeJS.ProcessEnv {
-  if (!_sudoDir) return {};
+  if (!_sudoDir || lockClosedHere()) return {};
   const currentPath = process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin";
   return { PATH: `${_sudoDir}:${currentPath}` };
 }
@@ -63,7 +88,7 @@ export function getSudoEnv(): NodeJS.ProcessEnv {
  * belt-and-suspenders fallback alongside the PATH wrapper.
  */
 export function prewarmSudo(): void {
-  if (!_sudoPassword) return;
+  if (!_sudoPassword || lockClosedHere()) return;
   try {
     execSync("sudo -S -v", {
       input: _sudoPassword + "\n",
@@ -77,7 +102,7 @@ export function prewarmSudo(): void {
 
 /** True when a sudo password has been set. */
 export function hasSudoPassword(): boolean {
-  return _sudoDir !== null;
+  return _sudoDir !== null && !lockClosedHere();
 }
 
 let _passwordlessCache: { value: boolean; at: number } | null = null;
@@ -92,6 +117,7 @@ const PASSWORDLESS_TTL_MS = 60_000;
  * status endpoint doesn't spawn sudo on every check.
  */
 export function hasPasswordlessSudo(): boolean {
+  if (lockClosedHere()) return false;
   const now = Date.now();
   if (_passwordlessCache && now - _passwordlessCache.at < PASSWORDLESS_TTL_MS) {
     return _passwordlessCache.value;

package/src/ui/server/ui-assets.ts

@@ -32,6 +32,8 @@ export const UI_MODULES: readonly string[] = [
   "/topbar.js",
   "/edge-page.js",
   "/error-page.js",
+  "/agents-section.js",
+  "/agents-page.js",
   // The UI's catalogs other than English (R19; en is in shell.js).
   "/i18n/ja.js",
   "/i18n/es.js",
@@ -40,6 +42,11 @@ export const UI_MODULES: readonly string[] = [
 /** URL path → file inside node_modules. */
 export const VENDOR_ASSETS: Readonly<Record<string, string>> = {
   "/vendor/elk.bundled.js": "elkjs/lib/elk.bundled.js",
+  // The Agents tab's terminal panes (AG-4a-term): xterm.js and its fit
+  // addon, ES modules, MIT.
+  "/vendor/xterm.mjs": "@xterm/xterm/lib/xterm.mjs",
+  "/vendor/xterm.css": "@xterm/xterm/css/xterm.css",
+  "/vendor/addon-fit.mjs": "@xterm/addon-fit/lib/addon-fit.mjs",
 };
 
 /** The installed file for a vendored URL path, or null. */
@@ -81,7 +88,9 @@ export function serveUiAsset(
   // Pinned versions: the bytes only change with Den itself. Not run through
   // the product-token fill the UI's own scripts get.
   res.writeHead(200, {
-    "Content-Type": "application/javascript",
+    "Content-Type": file.endsWith(".css")
+      ? "text/css"
+      : "application/javascript",
     "Cache-Control": "public, max-age=86400",
   });
   res.end(fs.readFileSync(file));