@ccmsg/cli 0.1.0

package/src/sessions/handlers.ts

@@ -0,0 +1,158 @@
+import {
+  type Capability,
+  type InstanceId,
+  type SessionDumpWriteArgs,
+  type SessionEnvReadArgs,
+  type SessionEnvReadResult,
+  type SessionForkOriginArgs,
+  type SessionForkOriginResult,
+  type SessionKillArgs,
+  type SessionKillResult,
+  type SessionLastLiveRemoveArgs,
+  type SessionLastLiveRemoveResult,
+  type SessionRenameArgs,
+  type SessionRenameResult,
+  type SessionSearchArgs,
+  type Sid,
+  TITLE_MAX_CHARS,
+  type TranscriptReadArgs,
+  type TranscriptReadResult,
+} from "@ccmsg/protocol";
+import { type HandlerInput, OpError } from "../dispatch/index.ts";
+import { sees, type Viewer } from "../files/index.ts";
+import { readSlice, type TranscriptFiles } from "../transcript/index.ts";
+import { dumpWrite } from "./dump.ts";
+import { forkOrigin } from "./fork.ts";
+import type { SessionProcesses } from "./processes.ts";
+import { search } from "./search.ts";
+
+/** The two capabilities of the session ops, present only where what they rest
+ * on is configured.
+ *
+ * `terminal` rests on a multiplexer this instance can type into, which is a
+ * deployment fact: a host without one has no handle a rename could reach.
+ * `fork` rests on the operator asking for it, because finding a seam reads
+ * whole sibling transcripts and a host holding large ones pays that on every
+ * ask. A client is told before it calls rather than refused when it does. */
+export function sessionCapabilities(config: {
+  terminal_gateway?: string;
+  fork_origin: boolean;
+}): Capability[] {
+  return [
+    ...(config.fork_origin ? (["fork"] as const) : []),
+    ...(config.terminal_gateway === undefined || config.terminal_gateway === ""
+      ? []
+      : (["terminal"] as const)),
+  ];
+}
+
+export interface SessionOpsDeps {
+  readonly self: InstanceId;
+  /** The one config home this instance answers for (M6). */
+  readonly configHome: string;
+  readonly stateDir: string;
+  readonly files: TranscriptFiles;
+  readonly processes: SessionProcesses;
+  /** Drop one entry from the list of sessions that were running when this
+   * instance last saw them. The sessions domain owns the list; this op only
+   * asks it to forget a row. */
+  readonly forget: (sid: Sid) => boolean;
+}
+
+/** The eight ops that observe and operate on sessions.
+ *
+ * None of them decides who may call it: dispatch has settled that from the
+ * attribute table. The one that narrows by role is `transcript_read`, and it
+ * narrows through the same `sees` the file ops narrow through — the visible
+ * range of a `scope: "role"` op is one rule, in one place, whatever it is
+ * a range over. */
+export function sessionHandlers(deps: SessionOpsDeps) {
+  const viewer = (input: HandlerInput): Viewer => ({ role: input.role, sid: input.identity?.sid });
+
+  return {
+    session_kill: async (input: HandlerInput): Promise<SessionKillResult> => {
+      const args = input.args as unknown as SessionKillArgs;
+      return await deps.processes.kill(args.sid, args.force === true);
+    },
+
+    session_rename: async (input: HandlerInput): Promise<SessionRenameResult> => {
+      const args = input.args as unknown as SessionRenameArgs;
+      const title = validTitle(args.title);
+      const terminal = await deps.processes.terminal(args.sid);
+      // The title is typed, so the newline that submits it is a keystroke of
+      // its own rather than a character appended to the line: the terminal
+      // drains what was typed before the submit reaches it.
+      await deps.processes.type(terminal, [`text:/rename ${title}`, "key:Enter"]);
+      return { terminal_id: terminal.id, instance: deps.self, title };
+    },
+
+    session_env_read: async (input: HandlerInput): Promise<SessionEnvReadResult> => {
+      const args = input.args as unknown as SessionEnvReadArgs;
+      const { pid, env } = await deps.processes.environment(args.sid);
+      return { pid, instance: deps.self, env };
+    },
+
+    session_search: (input: HandlerInput) =>
+      search(input.args as unknown as SessionSearchArgs, {
+        self: deps.self,
+        configHome: deps.configHome,
+        files: deps.files,
+      }),
+
+    session_dump_write: (input: HandlerInput) =>
+      dumpWrite(input.args as unknown as SessionDumpWriteArgs, {
+        self: deps.self,
+        stateDir: deps.stateDir,
+        files: deps.files,
+      }),
+
+    session_fork_origin: (input: HandlerInput): SessionForkOriginResult => {
+      const args = input.args as unknown as SessionForkOriginArgs;
+      const origin = forkOrigin(args.sid, deps.files);
+      return origin === undefined ? {} : { origin };
+    },
+
+    session_last_live_remove: (input: HandlerInput): SessionLastLiveRemoveResult => {
+      const args = input.args as unknown as SessionLastLiveRemoveArgs;
+      // An unknown session is not an error: two clients pressing the same
+      // button is the ordinary case, and the caller's goal holds either way.
+      return { removed: deps.forget(args.sid) };
+    },
+
+    transcript_read: (input: HandlerInput): TranscriptReadResult => {
+      const args = input.args as unknown as TranscriptReadArgs;
+      if (!sees(args.sid, viewer(input))) {
+        // The role sets the visible range, not the permission (§3.2): outside
+        // it there is no transcript to speak of, which is the one code this op
+        // declares. A refusal that named the session would answer a question
+        // the caller was not entitled to ask.
+        throw new OpError("not_found", `no transcript is known for ${args.sid}`);
+      }
+      const file = deps.files.locate(args.sid, args);
+      return readSlice(args.sid, file, args.before, args.max_bytes);
+    },
+  };
+}
+
+/** A title fit to be typed.
+ *
+ * A control character is refused rather than stripped: the value reaches the
+ * terminal as keystrokes, where a newline submits a half-written command and
+ * the rest are control sequences — and renaming a session to something the
+ * caller did not write is worse than an error they can act on. */
+function validTitle(raw: string): string {
+  const title = raw.trim();
+  if (title === "") throw new OpError("invalid_args", "a title is not only whitespace");
+  if (title.length > TITLE_MAX_CHARS) {
+    throw new OpError("invalid_args", `a title is at most ${TITLE_MAX_CHARS} characters`);
+  }
+  for (let at = 0; at < title.length; at++) {
+    // Code units are enough: every surrogate half is above this range, so no
+    // astral character can be read as a control character.
+    const code = title.charCodeAt(at);
+    if (code < 0x20 || code === 0x7f) {
+      throw new OpError("invalid_args", "a title carries no control characters");
+    }
+  }
+  return title;
+}

package/src/sessions/harness.ts

@@ -0,0 +1,167 @@
+import { type FSWatcher, readdirSync, readFileSync, watch } from "node:fs";
+import { join } from "node:path";
+import type { AgentInfo, InstanceId, Sid } from "@ccmsg/protocol";
+
+/** The status the harness writes while a dialog is open and it is waiting for
+ * an answer, alongside a `waitingFor` naming what it waits on.
+ *
+ * Read out of the harness binary (2.1.263): `{status:"waiting",waitingFor:…}`.
+ * This is the one thing the raw status decides (§5.1 / DV-Q5) — busy and idle
+ * are the gateway's to say, so no other value of it is read here. */
+const WAITING = "waiting";
+
+/** How often the confirmation poll re-reads the directory.
+ *
+ * `fs.watch` is the route; this is not. macOS/Bun delivers FSEvents tens of
+ * seconds late under load (measured in the old daemon while many test children
+ * ran), and the poll exists so a change the watch is sitting on is picked up
+ * before a person notices it is missing (§5.1). Five seconds is the interval
+ * the old daemon's `claude agents` poller ran at as its only route, and this
+ * one replaces it as a backstop (DV-Q6), so it cannot be the slower of the
+ * two. */
+export const CONFIRM_POLL_MS = 5_000;
+
+const STATE_FILE = /^\d+\.json$/;
+
+/** The sessions the harness itself reports, read from one config home.
+ *
+ * The directory is the whole input: it says which sessions exist and which is
+ * waiting on a dialog (§5.1). Only the config home this instance was given is
+ * ever opened (M6) — the path is handed in, and nothing here searches for
+ * another one.
+ *
+ * Two things live here, and §6.3 separates them. Reading the directory answers
+ * a question, and is done whenever one is asked. Watching it says the answer
+ * may have changed, which is only worth knowing while somebody is subscribed —
+ * so the watch is what the subscription drives, and no answer waits on it. */
+export class HarnessSessions {
+  #watcher: FSWatcher | undefined;
+  #timer: ReturnType<typeof setInterval> | undefined;
+
+  constructor(
+    private readonly dir: string,
+    private readonly instance: InstanceId,
+    private readonly onChange: () => void,
+    private readonly pollMs: number = CONFIRM_POLL_MS,
+  ) {}
+
+  get running(): boolean {
+    return this.#watcher !== undefined || this.#timer !== undefined;
+  }
+
+  /** Begins watching. Called when the first subscriber arrives and not before
+   * (§6.3 / §8.3: no upstream is read until somebody is listening). */
+  start(): void {
+    if (this.running) return;
+    try {
+      this.#watcher = watch(this.dir, this.onChange);
+    } catch {
+      // The directory does not exist yet — a config home whose harness has not
+      // run. The poll below both covers the wait and picks it up when it
+      // appears, so this is not a failure to start.
+      this.#watcher = undefined;
+    }
+    this.#timer = setInterval(this.onChange, this.pollMs);
+    this.onChange();
+  }
+
+  stop(): void {
+    this.#watcher?.close();
+    this.#watcher = undefined;
+    if (this.#timer !== undefined) clearInterval(this.#timer);
+    this.#timer = undefined;
+  }
+
+  /** The directory as it is at this instant.
+   *
+   * Every answer comes from here rather than from anything the watch left
+   * behind. Which sessions exist is an input to the classification (§5.1), and
+   * classifying happens inside `message_send`'s decision and inside the
+   * recompute that writes `last_live` — neither of which can hand back a
+   * promise without changing what it means, and neither of which may depend on
+   * somebody being subscribed. The ops that signal a session's process read it
+   * here too: a pid from a poll that has not run is a number belonging to
+   * nobody.
+   *
+   * Read in place because the directory is a handful of small files of this
+   * uid's own config home (M6) — a syscall or two per session, not a wait. */
+  scan(): ReadonlyMap<Sid, AgentInfo> {
+    const rows = new Map<Sid, AgentInfo>();
+    let names: string[];
+    try {
+      names = readdirSync(this.dir);
+    } catch {
+      return rows;
+    }
+    for (const name of names) {
+      if (!STATE_FILE.test(name)) continue;
+      let document: unknown;
+      try {
+        document = JSON.parse(readFileSync(join(this.dir, name), "utf8"));
+      } catch {
+        continue;
+      }
+      const row = toRow(document, this.dir, this.instance);
+      if (row !== undefined) rows.set(row.sid, row);
+    }
+    return rows;
+  }
+}
+
+/** Whether the harness says this session is waiting on a dialog. */
+export function isWaiting(row: AgentInfo): boolean {
+  return row.status === WAITING;
+}
+
+/** The conversion of one upstream document into the contract's spelling
+ * (§3.5): renamed to snake_case, instants in Unix ms, and nothing carried over
+ * that the contract does not name.
+ *
+ * A row whose process is gone is dropped: the file outlives a session that did
+ * not clean up after itself, and "the session exists" is what this input is
+ * for. */
+function toRow(document: unknown, configDir: string, instance: InstanceId): AgentInfo | undefined {
+  if (typeof document !== "object" || document === null) return undefined;
+  const raw = document as Record<string, unknown>;
+  const sid = text(raw["sessionId"]);
+  const pid = raw["pid"];
+  const cwd = text(raw["cwd"]);
+  const kind = text(raw["kind"]);
+  const startedAt = raw["startedAt"];
+  if (sid === undefined || cwd === undefined || kind === undefined) return undefined;
+  if (typeof pid !== "number" || typeof startedAt !== "number") return undefined;
+  if (!alive(pid)) return undefined;
+  return {
+    sid,
+    instance,
+    pid,
+    cwd,
+    kind,
+    started_at: startedAt,
+    config_dir: configDir,
+    ...optional("name", text(raw["name"])),
+    ...optional("status", text(raw["status"])),
+    ...optional("waiting_for", text(raw["waitingFor"])),
+    ...optional("state", text(raw["state"])),
+    ...optional("background_id", text(raw["backgroundId"])),
+  };
+}
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    // EPERM would mean alive but ours to signal — impossible here, since the
+    // daemon and the sessions of its config home run as one uid (§2 A4).
+    return false;
+  }
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function optional<K extends string, V>(key: K, value: V | undefined): Record<K, V> | object {
+  return value === undefined ? {} : { [key]: value };
+}

package/src/sessions/index.ts

@@ -0,0 +1,26 @@
+export * from "./classify.ts";
+export { DUMPS, dumpWrite } from "./dump.ts";
+export { forkOrigin } from "./fork.ts";
+export * from "./harness.ts";
+export { sessionCapabilities, sessionHandlers, type SessionOpsDeps } from "./handlers.ts";
+export * from "./last-live.ts";
+export {
+  elapsedSeconds,
+  GRACE_MS,
+  hostProcessDeps,
+  hostTerminalReader,
+  LIVENESS_POLL_MS,
+  parseEnvironment,
+  type ProcessDeps,
+  SECOND_SIGNAL_AFTER_MS,
+  SessionProcesses,
+  STARTED_AFTER_TOLERANCE_MS,
+  STARTED_BEFORE_TOLERANCE_MS,
+  type Terminal,
+  terminalOf,
+} from "./processes.ts";
+export * from "./registry.ts";
+export { search, type SearchDeps } from "./search.ts";
+export * from "./status.ts";
+export { TerminalCache, type TerminalReader } from "./terminals.ts";
+export { workspaceFolders } from "./workspace.ts";

package/src/sessions/last-live.ts

@@ -0,0 +1,111 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  LAST_LIVE_RETENTION_MS,
+  type LastLiveSession,
+  type Sid,
+  type Timestamp,
+} from "@ccmsg/protocol";
+
+export const LAST_LIVE_FILE = "last-live.json";
+
+/** What is stored per session: the contract's entry, minus the one field that
+ * is derived rather than observed.
+ *
+ * `state` is left out on purpose (M4). It follows from `stopped_at` and from
+ * whether the session is live again, both of which are known when the list is
+ * read, so storing it would be storing a conclusion that can go stale on disk.
+ * `pinned` is left out because no pin is held anywhere yet; when one is, it
+ * belongs to the session rather than to this list. */
+export type StoredEntry = Omit<LastLiveSession, "state" | "pinned">;
+
+interface Document {
+  version: number;
+  sessions: StoredEntry[];
+}
+
+const VERSION = 1;
+
+/** The sessions that were running when this instance last saw them.
+ *
+ * One of the three things written to disk (§3.6): losing it loses the Paused
+ * and Disappeared rows of the list entirely, and nothing else on the host
+ * remembers that a session used to be here. Only observations are stored — the
+ * classification is derived from them at read time, never written (M4). */
+export class LastLiveStore {
+  #entries = new Map<Sid, StoredEntry>();
+
+  constructor(private readonly file: string) {}
+
+  /** Read at startup (§8.3 step 4), before anything can ask for the list. A
+   * file that is missing or unreadable starts an empty list: the daemon has no
+   * way to recover it and refusing to start would cost more than the rows. */
+  load(now: Timestamp = Date.now()): void {
+    let document: unknown;
+    try {
+      document = JSON.parse(readFileSync(this.file, "utf8"));
+    } catch {
+      return;
+    }
+    const sessions = (document as Document | null)?.sessions;
+    if (!Array.isArray(sessions)) return;
+    for (const entry of sessions as StoredEntry[]) {
+      if (typeof entry?.sid === "string") this.#entries.set(entry.sid, entry);
+    }
+    this.#prune(now);
+  }
+
+  /** Every entry still within the retention window. */
+  entries(now: Timestamp = Date.now()): StoredEntry[] {
+    if (this.#prune(now)) this.#save();
+    return [...this.#entries.values()];
+  }
+
+  get(sid: Sid): StoredEntry | undefined {
+    return this.#entries.get(sid);
+  }
+
+  /** Note a session as no longer live. A `stopped_at` already recorded for it
+   * survives, since the session being gone is what that stop led to; the entry
+   * carries one when the session declared it was going, which is what makes it
+   * Paused rather than Disappeared (§5.2). */
+  record(entry: StoredEntry): void {
+    const stopped = this.#entries.get(entry.sid)?.stopped_at ?? entry.stopped_at;
+    this.#entries.set(entry.sid, stopped === undefined ? entry : { ...entry, stopped_at: stopped });
+    this.#save();
+  }
+
+  /** Drop one entry: `session_last_live_remove`, and a session registering
+   * again, which is what moves it back to the connected list. */
+  remove(sid: Sid): boolean {
+    if (!this.#entries.delete(sid)) return false;
+    this.#save();
+    return true;
+  }
+
+  #prune(now: Timestamp): boolean {
+    let dropped = false;
+    for (const [sid, entry] of this.#entries) {
+      if (now - entry.last_seen_at <= LAST_LIVE_RETENTION_MS) continue;
+      this.#entries.delete(sid);
+      dropped = true;
+    }
+    return dropped;
+  }
+
+  /** Written whole through a temporary file, so a daemon killed mid-write
+   * leaves the previous list rather than half of this one. */
+  #save(): void {
+    const document: Document = { version: VERSION, sessions: [...this.#entries.values()] };
+    const temporary = `${this.file}.${process.pid}.tmp`;
+    mkdirSync(dirname(this.file), { recursive: true });
+    writeFileSync(temporary, `${JSON.stringify(document)}\n`);
+    renameSync(temporary, this.file);
+  }
+}
+
+/** Where the list lives for an instance whose state directory is `stateDir`
+ * (§8.1: every per-instance path is derived from its config home). */
+export function lastLivePath(stateDir: string): string {
+  return join(stateDir, LAST_LIVE_FILE);
+}