@ccmsg/cli 0.1.0

package/src/sessions/search.ts

@@ -0,0 +1,278 @@
+import { readFileSync } from "node:fs";
+import { parse, sep } from "node:path";
+import type {
+  InstanceId,
+  SessionSearchArgs,
+  SessionSearchHit,
+  SessionSearchMatch,
+  SessionSearchResult,
+} from "@ccmsg/protocol";
+import { OpError } from "../dispatch/index.ts";
+import { readRecord, type TranscriptFile, type TranscriptFiles } from "../transcript/index.ts";
+
+/** What one search may read, and what it may answer with.
+ *
+ * A search walks transcripts that were never opened for it and cannot know how
+ * many will match, so both ends are bounded: the bytes stop a query that
+ * matches nothing from reading a whole config home, and the hits stop one that
+ * matches everything from becoming a payload nobody can use. Reaching either
+ * is `truncated` rather than an error — the hits found are still hits. */
+const SCAN_BUDGET_BYTES = 64 * 1024 * 1024;
+const HITS = 50;
+/** What one hit shows of what it matched. Enough to recognise the passage;
+ * the transcript itself is one `transcript_read` away. */
+const MATCHES_PER_HIT = 5;
+const MATCH_CHARS = 400;
+
+/** The longest one clause may be. A query is something a person types, and the
+ * pattern's own size is one of the things that decides what matching it costs;
+ * past this it is a program rather than a query. */
+const MAX_CLAUSE_CHARS = 1000;
+
+/** What one regular-expression clause may spend on matching, over the whole
+ * search.
+ *
+ * The contract lets a caller state a regular expression and says nothing about
+ * which ones, so the patterns that backtrack super-linearly are admitted — and
+ * they are not only the crafted ones: `[a-z]+ing` over records of ordinary
+ * prose is quadratic in each record's length, and measured here it spends 86
+ * seconds on the scan budget below where a literal or an alternation spends
+ * 7 to 12 milliseconds on the same bytes. Two seconds is two orders of
+ * magnitude above what a well-formed clause needs and far below what the
+ * instance can afford to be blocked for, since it answers one op at a time.
+ * Reaching it is `truncated`, which is what every other cap on this op is. */
+const CLAUSE_BUDGET_MS = 2000;
+
+export interface SearchDeps {
+  readonly self: InstanceId;
+  /** The one config home this instance answers for (M6). */
+  readonly configHome: string;
+  readonly files: TranscriptFiles;
+}
+
+/** Search the transcripts of sessions that have run on this instance.
+ *
+ * Two stages, because opening every transcript to answer a query about one is
+ * the cost this op is bounded against: the enumeration filters on what a
+ * directory listing and a `stat` already say — the session id, the working
+ * directory as the project directory spells it, when the file was last touched
+ * — and only what survives that is read. */
+export function search(args: SessionSearchArgs, deps: SearchDeps): SessionSearchResult {
+  if ((args.config_dirs ?? [deps.configHome]).every((dir) => dir !== deps.configHome)) {
+    // Every config home the caller named is one this instance does not know,
+    // which the contract says to ignore — leaving nothing to search.
+    return { hits: [], truncated: false };
+  }
+  const { clauses, budgets } = compile(args);
+  const sid = args.sid?.toLowerCase();
+  const cwdWords = (args.cwd ?? "").trim().split(/\s+/).filter(Boolean);
+  const since = args.modified_within_ms === undefined ? 0 : Date.now() - args.modified_within_ms;
+  const wanted = { user: args.target_user ?? true, agent: args.target_agent ?? true };
+
+  const hits: SessionSearchHit[] = [];
+  let budget = SCAN_BUDGET_BYTES;
+  let truncated = false;
+  for (const candidate of deps.files.all()) {
+    if (sid !== undefined && !candidate.sid.toLowerCase().includes(sid)) continue;
+    if (candidate.updated_at < since) continue;
+    if (!looksLike(candidate.project, cwdWords)) continue;
+    // Every clause having given up leaves nothing that could still match, so
+    // the rest of the walk would read transcripts to decide nothing.
+    const spent = budgets.length > 0 && budgets.every((each) => each.spent);
+    if (hits.length >= HITS || budget <= 0 || spent) {
+      truncated = true;
+      break;
+    }
+    budget -= candidate.size;
+    const hit = read(candidate, clauses, wanted, deps);
+    // The working directory the project directory only approximates: a hit is
+    // kept when the transcript's own `cwd` holds every word asked for.
+    if (hit !== undefined && holds(hit.cwd, cwdWords)) hits.push(hit);
+  }
+  // A clause that ran out of time answered about fewer records than it was
+  // asked about, whether or not the walk itself reached an end.
+  return { hits, truncated: truncated || budgets.some((each) => each.spent) };
+}
+
+/** One clause of a query: the terms that must all appear for it to match.
+ *
+ * Clauses are ORed and the terms within one are ANDed, which is what lets a
+ * caller ask for two unrelated passages in one search. A query stating nothing
+ * matches every record, so a search by working directory alone is a search. */
+type Clause = (text: string) => boolean;
+
+/** What one clause has left to spend, and whether it has stopped.
+ *
+ * Only a regular-expression clause carries one. A clause of terms is a
+ * substring search per term, linear in what it is given, and the bytes it may
+ * be given are already bounded — there is nothing a clock would tell it that
+ * the scan budget does not. */
+class Budget {
+  #left = CLAUSE_BUDGET_MS;
+  /** The clause gave up part-way, so what it did not match it did not decide
+   * about. */
+  spent = false;
+
+  run(test: () => boolean): boolean {
+    if (this.spent) return false;
+    const at = performance.now();
+    try {
+      return test();
+    } finally {
+      this.#left -= performance.now() - at;
+      if (this.#left <= 0) this.spent = true;
+    }
+  }
+}
+
+function compile(args: SessionSearchArgs): { clauses: Clause[]; budgets: Budget[] } {
+  const query = args.query?.trim();
+  if (query === undefined || query === "") return { clauses: [], budgets: [] };
+  const sensitive = args.case_sensitive === true;
+  const budgets: Budget[] = [];
+  const clauses = query
+    .split("\n")
+    .map((clause) => clause.trim())
+    .filter((clause) => clause !== "")
+    .map((clause): Clause => {
+      if (clause.length > MAX_CLAUSE_CHARS) {
+        throw new OpError(
+          "invalid_args",
+          `a query clause may be at most ${MAX_CLAUSE_CHARS} characters, and this one is ${clause.length}`,
+        );
+      }
+      if (args.regex === true) {
+        let matcher: RegExp;
+        try {
+          matcher = new RegExp(clause, sensitive ? "" : "i");
+        } catch (cause) {
+          throw new OpError(
+            "invalid_args",
+            `${clause} is not a regular expression: ${String(cause)}`,
+          );
+        }
+        const budget = new Budget();
+        budgets.push(budget);
+        return (text: string) => budget.run(() => matcher.test(text));
+      }
+      const terms = clause.split(/\s+/).map((term) => (sensitive ? term : term.toLowerCase()));
+      return (text: string) => {
+        const against = sensitive ? text : text.toLowerCase();
+        return terms.every((term) => against.includes(term));
+      };
+    });
+  return { clauses, budgets };
+}
+
+/** Read one transcript, and state it as a hit when it matched.
+ *
+ * The pass is one: the records that carry the query also carry the working
+ * directory, the title and what the session last ran as, so a hit is built
+ * from the reading that decided it rather than from a second one. */
+function read(
+  candidate: TranscriptFile,
+  clauses: readonly Clause[],
+  wanted: { user: boolean; agent: boolean },
+  deps: SearchDeps,
+): SessionSearchHit | undefined {
+  let text: string;
+  try {
+    text = readFileSync(candidate.file, "utf8");
+  } catch {
+    // Gone since it was listed, which is a session that ended mid-search.
+    return undefined;
+  }
+  const matches: SessionSearchMatch[] = [];
+  let cwd: string | undefined;
+  let title: string | undefined;
+  let model: string | undefined;
+  let effort: string | undefined;
+  let createdAt: number | undefined;
+  for (const line of text.split("\n")) {
+    if (line === "") continue;
+    const record = readRecord(line);
+    if (record === undefined) continue;
+    cwd ??= record.cwd;
+    createdAt ??= record.said_at;
+    if (record.title !== undefined) title = record.title;
+    // What the session runs as is a property of its latest turn rather than of
+    // its first: a session whose model was changed mid-run resumes as what it
+    // is now. Sidechain rows are a subagent's own turns and say nothing of it.
+    if (!record.sidechain && record.model !== undefined) {
+      model = record.model;
+      effort = record.effort;
+    }
+    if (matches.length >= MATCHES_PER_HIT) continue;
+    const said = record.text;
+    if (said === undefined || record.said_by === undefined || !wanted[record.said_by]) continue;
+    if (!says(said, clauses)) continue;
+    matches.push({
+      role: record.said_by,
+      text: said.length > MATCH_CHARS ? `${said.slice(0, MATCH_CHARS)}…` : said,
+      ...(record.said_at === undefined ? {} : { said_at: record.said_at }),
+    });
+  }
+  if (clauses.length > 0 && matches.length === 0) return undefined;
+  const location = repoLocation(cwd);
+  return {
+    sid: candidate.sid,
+    instance: deps.self,
+    config_dir: deps.configHome,
+    file: candidate.file,
+    ...(cwd === undefined ? {} : { cwd }),
+    ...location,
+    ...(title === undefined ? {} : { title }),
+    created_at: createdAt ?? candidate.created_at,
+    updated_at: candidate.updated_at,
+    size: candidate.size,
+    matches,
+    ...(model === undefined ? {} : { model }),
+    ...(effort === undefined ? {} : { effort }),
+  };
+}
+
+/** Whether any clause matches. A query stating no clause matches everything,
+ * which is what makes a search by working directory alone a search. */
+function says(text: string, clauses: readonly Clause[]): boolean {
+  return clauses.length === 0 || clauses.some((clause) => clause(text));
+}
+
+/** Whether the project directory could be the working directory asked for.
+ *
+ * The harness flattens a working directory into one name, and the flattening
+ * is lossy — separators, dots and underscores all become dashes — so this only
+ * narrows what is opened. What decides a hit is the transcript's own `cwd`. */
+function looksLike(project: string, words: readonly string[]): boolean {
+  if (words.length === 0) return true;
+  const flat = flatten(project);
+  return words.every((word) => flat.includes(flatten(word)));
+}
+
+function holds(cwd: string | undefined, words: readonly string[]): boolean {
+  if (words.length === 0) return true;
+  if (cwd === undefined) return false;
+  const flat = flatten(cwd);
+  return words.every((word) => flat.includes(flatten(word)));
+}
+
+function flatten(value: string): string {
+  return value.toLowerCase().replace(/[-/._\s]/g, "");
+}
+
+/** `owner/repo` and the workspace within it, when the working directory
+ * follows the layout that states them. A directory that does not is reported
+ * without them rather than with a guess. */
+function repoLocation(cwd: string | undefined): { repo?: string; ws?: string } {
+  if (cwd === undefined) return {};
+  const root = parse(cwd).root;
+  const parts = cwd.slice(root.length).split(sep).filter(Boolean);
+  for (let at = parts.length - 1; at >= 0; at--) {
+    if (parts[at] !== "repos" || at + 3 >= parts.length) continue;
+    const workspace = parts.slice(at + 4);
+    return {
+      repo: `${parts[at + 2]}/${parts[at + 3]}`,
+      ...(workspace.length === 0 ? {} : { ws: workspace.join(sep) }),
+    };
+  }
+  return {};
+}

package/src/sessions/status.ts

@@ -0,0 +1,209 @@
+import type {
+  InstanceId,
+  SessionApiError,
+  SessionErrorEntry,
+  SessionStatusSnapshot,
+  Sid,
+} from "@ccmsg/protocol";
+import { canonical, within } from "../files/containment.ts";
+import type { TopicValue, UpstreamResource } from "../topics/index.ts";
+import { topicParam } from "../topics/index.ts";
+import type { TranscriptFacts } from "../transcript/index.ts";
+import { workspaceFolders } from "./workspace.ts";
+
+/** What the fold says stopped a session, read in one place.
+ *
+ * Three values rest on it: whether a live session is Waiting (§5.2), what
+ * `session_errors` lists, and the `api_error` of `session_status:<sid>`. They
+ * ask this rather than each reading the fold's field, so the three cannot come
+ * to different answers about the same session (§7.4, M5). */
+export function stoppedOn(facts: TranscriptFacts): SessionApiError | undefined {
+  return facts.api_error;
+}
+
+/** The `session_status:<sid>` payload.
+ *
+ * Almost every field is the fold's, stated as the fold left it: one pass over
+ * the transcript settles the error, the task list, the files it named and what
+ * is running below it, and this assembles them rather than reading anything a
+ * second time (M5).
+ *
+ * The two fields that are not the fold's are the ones the transcript does not
+ * carry. `workspace_folders` is read from the editor's own workspace file, and
+ * `external_files` needs a root to be outside of — a greeting's fact, not a
+ * transcript's — so the paths the fold collected are filtered here, where the
+ * root is known. A session that stated no root contributes none of them rather
+ * than all of them: the list is the allowlist an `external` read is checked
+ * against, so not knowing where the session works has to admit nothing. */
+export function sessionStatusOf(
+  sid: Sid,
+  facts: TranscriptFacts,
+  where: SessionWhere = {},
+): SessionStatusSnapshot & {
+  sid: Sid;
+} {
+  const stopped = stoppedOn(facts);
+  const root = where.root === undefined ? undefined : canonical(where.root);
+  return {
+    sid,
+    todos: [...facts.todos],
+    workflows: [...facts.workflows],
+    background: [...facts.background],
+    teammates: [...facts.teammates],
+    agent_tree: facts.agent_tree,
+    external_files:
+      root === undefined
+        ? []
+        : facts.named_files.filter((file) => !within(canonical(file.path), root)),
+    workspace_folders: workspaceFolders(where.cwd),
+    ...(stopped === undefined ? {} : { api_error: stopped }),
+  };
+}
+
+/** Where a session works, as it greeted (§5.1). The same two values the file
+ * surfaces are decided against, asked for here so that what `session_status`
+ * says and what a read is admitted by come from one answer. */
+export interface SessionWhere {
+  readonly root?: string;
+  readonly cwd?: string;
+}
+
+export interface SessionStatusDeps {
+  readonly self: InstanceId;
+  /** The sessions this instance can follow a transcript of: the ones that
+   * greeted, since a greeting is the only thing that names a transcript path
+   * (§5.1). A session it cannot follow has no error to fold. */
+  readonly sessions: () => readonly Sid[];
+  readonly facts: (sid: Sid) => TranscriptFacts;
+  /** Where each session works, for the two fields the transcript does not
+   * state. */
+  readonly where: (sid: Sid) => SessionWhere;
+  /** The tail behind a session's fold, asked for and let go by name. */
+  readonly hold: (sid: Sid) => void;
+  readonly release: (sid: Sid) => void;
+  /** The one way a value reaches subscribers (§6.1). */
+  readonly publish: (topic: string, data: unknown) => void;
+}
+
+/** The two topics the fold's error state feeds, and the tails they keep
+ * running (§6.3).
+ *
+ * `session_errors` is one list for the instance and `session_status:<sid>` is
+ * one session, so what they hold differs: the first wants every session's fold
+ * and the second wants one. Both wants are the same mechanism — a subscription
+ * arrives, the tails it needs are held, and the last subscription to go
+ * releases them — which is why the two topics share one owner rather than
+ * having a hold rule each. */
+export class SessionStatus implements UpstreamResource {
+  /** The topic names currently subscribed. */
+  readonly #wanted = new Set<string>();
+  /** The tails held for those subscriptions, one hold per session however many
+   * topics want it. */
+  readonly #held = new Set<Sid>();
+  /** Holding and releasing a tail settles the fold, which reaches back here as
+   * a change. The outer pass is left to finish and then runs again, so the
+   * convergence happens once rather than in the middle of itself. */
+  #converging = false;
+  #pending = false;
+
+  constructor(private readonly deps: SessionStatusDeps) {}
+
+  // --- UpstreamResource (§6.3)
+
+  start(topic: string): void {
+    this.#wanted.add(topic);
+    this.refresh();
+  }
+
+  stop(topic: string): void {
+    this.#wanted.delete(topic);
+    this.refresh();
+  }
+
+  snapshot(topic: string): readonly TopicValue[] {
+    const data = this.value(topic);
+    return data === undefined ? [] : [{ instance: this.deps.self, data }];
+  }
+
+  /** The tails follow the sessions and the subscriptions: what the fold now
+   * says, and which sessions exist, are the two things that move either.
+   *
+   * Called by whoever changes one of them, rather than on a timer (M3). */
+  refresh(): void {
+    if (this.#converging) {
+      this.#pending = true;
+      return;
+    }
+    this.#converging = true;
+    try {
+      do {
+        this.#pending = false;
+        this.#hold();
+      } while (this.#pending);
+    } finally {
+      this.#converging = false;
+    }
+    for (const topic of this.#wanted) {
+      const data = this.value(topic);
+      if (data !== undefined) this.deps.publish(topic, data);
+    }
+  }
+
+  /** Whether a session's fold is being kept for these topics, which is how
+   * "the subscription drives the resource" is observable from outside. */
+  holding(sid: Sid): boolean {
+    return this.#held.has(sid);
+  }
+
+  /** Every session this instance holds stopped on an error. A session that
+   * recovers drops out rather than appearing with an empty error, so a client
+   * that missed a frame converges on the next one. */
+  errors(): { errors: SessionErrorEntry[] } {
+    const errors: SessionErrorEntry[] = [];
+    for (const sid of this.deps.sessions()) {
+      const stopped = stoppedOn(this.deps.facts(sid));
+      if (stopped !== undefined) errors.push({ sid, instance: this.deps.self, ...stopped });
+    }
+    return { errors };
+  }
+
+  /** What a topic of this owner currently says, for a snapshot and for a
+   * change alike — built here and nowhere else, so the two cannot drift. */
+  private value(topic: string): unknown {
+    if (topic === "session_errors") return this.errors();
+    const sid = topicParam(topic);
+    return sid === undefined
+      ? undefined
+      : sessionStatusOf(sid, this.deps.facts(sid), this.deps.where(sid));
+  }
+
+  /** Bring the held tails in line with what the subscriptions need. */
+  #hold(): void {
+    const wanted = this.#wantedSessions();
+    for (const sid of wanted) {
+      if (this.#held.has(sid)) continue;
+      this.#held.add(sid);
+      this.deps.hold(sid);
+    }
+    for (const sid of this.#held) {
+      if (wanted.has(sid)) continue;
+      this.#held.delete(sid);
+      this.deps.release(sid);
+    }
+  }
+
+  #wantedSessions(): Set<Sid> {
+    const wanted = new Set<Sid>();
+    // One list for the instance means every session's fold; the list is what
+    // the subscriber asked for, and it cannot be built from a subset of it.
+    if (this.#wanted.has("session_errors")) {
+      for (const sid of this.deps.sessions()) wanted.add(sid);
+    }
+    for (const topic of this.#wanted) {
+      if (topic === "session_errors") continue;
+      const sid = topicParam(topic);
+      if (sid !== undefined) wanted.add(sid);
+    }
+    return wanted;
+  }
+}

package/src/sessions/terminals.ts

@@ -0,0 +1,72 @@
+import type { Terminal } from "./processes.ts";
+
+/** Reads the terminal one process names, or nothing when it names none. The
+ * effect is injected for the same reason every other process effect is: the
+ * host's answer comes from a child, and a test states it instead. */
+export type TerminalReader = (pid: number) => Promise<Terminal | undefined>;
+
+/** The terminal each live session runs in, read once per process.
+ *
+ * `agents` states a session's terminal and the classification reads it: a live
+ * session that neither holds a connection here nor names a terminal is the one
+ * nothing can reach (§5.2, `live_unmanaged`). Both want the value on every
+ * row, and neither may pay for it on every read — the harness's directory is
+ * scanned whenever any question is asked of it, and reading every session's
+ * environment there would spawn a child per session per question.
+ *
+ * So the value is remembered per pid and read exactly once for a pid the scan
+ * has not seen before. A pid the scan no longer holds is forgotten, which is
+ * both how the map stays the size of the session list and how a resumed
+ * session — a new process, possibly in another terminal — is read afresh
+ * rather than answered from what the process before it named. */
+export class TerminalCache {
+  /** A pid that has been read. Undefined as a value means the process named no
+   * terminal, which is remembered so it is not asked again. */
+  readonly #known = new Map<number, Terminal | undefined>();
+  readonly #reading = new Set<number>();
+
+  constructor(
+    private readonly read: TerminalReader,
+    /** A read finished, so a row may say something it did not when the list
+     * was last built. Whoever publishes the list is told — including when the
+     * process named no terminal, because "asked and told nothing" is what the
+     * row settles on and suppressing an unchanged payload is the topic
+     * mechanism's to do (M5), not this one's. */
+    private readonly filled: () => void,
+  ) {}
+
+  /** What the pid's process named, as far as is known right now. Undefined
+   * covers both "not read yet" and "names none": neither is a terminal to type
+   * into, and nothing here asks further of the difference. */
+  get(pid: number): Terminal | undefined {
+    return this.#known.get(pid);
+  }
+
+  /** The pids that exist now. New ones are read, gone ones are forgotten. */
+  observe(pids: Iterable<number>): void {
+    const present = new Set(pids);
+    for (const pid of this.#known.keys()) {
+      if (!present.has(pid)) this.#known.delete(pid);
+    }
+    for (const pid of present) {
+      if (this.#known.has(pid) || this.#reading.has(pid)) continue;
+      this.#reading.add(pid);
+      void this.#fill(pid);
+    }
+  }
+
+  async #fill(pid: number): Promise<void> {
+    let terminal: Terminal | undefined;
+    try {
+      terminal = await this.read(pid);
+    } catch {
+      // A process that ended while it was being read, or a host that does not
+      // let this one read it. The session's terminal is unknown, which is a
+      // state the classification has.
+    } finally {
+      this.#reading.delete(pid);
+    }
+    this.#known.set(pid, terminal);
+    this.filled();
+  }
+}