@vgai/sdk 0.5.4 → 0.5.6

package/src/project/run-name.ts

@@ -0,0 +1,53 @@
+/**
+ * What a run is CALLED — one owner of the bound, and of the fallback a run
+ * gets when nobody named it.
+ *
+ * WHY THIS EXISTS. `vgai play --name <text>` and `npm run playtest --
+ * '{"name":"…"}'` both exist so a run is findable by what it was testing, and
+ * the measured answer to an optional field is that it stays empty: every play
+ * event in the foundry probe's 45-minute session journal reads `"name":null`.
+ * A label nobody supplies indexes nothing, so the run that DOES know what it
+ * was testing supplies it — a route-targeted playtest is named after its
+ * routes, and a full-suite run is named `playtest`. Nothing is taught and no
+ * habit is required; the default carries the information.
+ *
+ * WHAT STAYS UNNAMED, deliberately: interactive `vgai play` with no `--name`.
+ * A person pressing play is not testing a named thing, and inventing a label
+ * for it would put noise in exactly the directory this makes greppable.
+ *
+ * Pure — no filesystem, no clock. `editor-server.ts`'s `playRunSlug` is the
+ * OTHER half (slugging a name into a filename segment) and reads the same
+ * bound from here, so the two can never disagree about how long a run name
+ * may be.
+ */
+
+/** Bound on a run's name — long enough to stay recognisable in a directory
+ *  listing, short enough that the timestamp beside it is still readable. */
+export const MAX_RUN_NAME = 40;
+
+/** The name a full-suite run gets: it targets no route in particular, and
+ *  "which run was that" is still a question worth being able to answer. */
+export const FULL_SUITE_RUN_NAME = 'playtest';
+
+/**
+ * The name for one playtest run.
+ *
+ * An explicit name always wins — it is the caller saying what this run was,
+ * and no derivation is better informed than that. Otherwise the routes name
+ * it, joined with `+` (a separator that survives being read back as a list,
+ * unlike the `-` that route names themselves use), bounded at
+ * {@link MAX_RUN_NAME}; and a run that named no route is
+ * {@link FULL_SUITE_RUN_NAME}.
+ *
+ * `null` is impossible by construction — every playtest run gets a name — but
+ * an explicit blank/whitespace name is treated as no name at all, the same
+ * case a missing one is.
+ */
+export function derivePlaytestRunName(
+  explicit: string | null | undefined,
+  routes: readonly string[],
+): string {
+  if (typeof explicit === 'string' && explicit.trim() !== '') return explicit.trim();
+  if (routes.length === 0) return FULL_SUITE_RUN_NAME;
+  return routes.join('+').slice(0, MAX_RUN_NAME).replace(/\+$/, '');
+}

package/src/project/session-journal.ts

@@ -0,0 +1,495 @@
+/**
+ * The editor session's console stream, as a STRUCTURED FILE an agent can read
+ * at any moment: `<project>/logs/editor-<sessionstamp>.jsonl`.
+ *
+ * WHY. Agents do not watch terminals; they read files. Every discipline signal
+ * the editor server already produces — a save that failed validation, a
+ * build-discipline tripwire crossing (`build-discipline.ts`), the session's own
+ * lifecycle — was delivered ONLY as a terminal print, which in detach mode goes
+ * to a raw capture nobody parses and in foreground scrolls past whoever was not
+ * looking. Same measured shape as the tripwires' own origin story: the
+ * mechanism was right and the delivery assumption was false.
+ *
+ * SO THE JOURNAL IS THE RECORD AND THE PRINTS ARE ITS RENDERERS. Every caller
+ * emits the event here first and renders second, from one emit point, so no
+ * line can reach a terminal without a durable twin on disk. Nothing new is
+ * measured for the journal's sake: each event is a fact one of those surfaces
+ * was about to print anyway.
+ *
+ * IT LIVES BESIDE `logs/play-*.jsonl`, in the project, deliberately: that is
+ * the established idiom for "durable evidence this session produced", the
+ * scaffold already gitignores `logs/`, and `build-discipline.ts` already skips
+ * `logs/` when dating source (so a journal line can never read as a source
+ * change and make a tripwire cry wolf on its own output).
+ *
+ * SCHEMA-LIGHT ON PURPOSE. One discriminated union, one writer, no zod: nothing
+ * reads a journal back through a validator — an agent reads it, and `JSON.parse`
+ * per line is the whole contract. Append-only, one object per line, no levels,
+ * no transports, no config.
+ *
+ * BOUNDS. Same rule the play logs follow (`/__editor/log-session`): prune to the
+ * newest `MAX_JOURNAL_FILES` when a new one is opened. Within a session the file
+ * grows unbounded, which is what an append-only record means.
+ */
+
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import type { TripwireTier } from './build-discipline';
+
+/** `editor-` + an ISO instant with `:`/`.` flattened + `.jsonl` — the same
+ *  lexicographic-order-is-chronological-order shape `play-*.jsonl` uses. */
+const PREFIX = 'editor-';
+const SUFFIX = '.jsonl';
+
+/** Journals kept per project. Matches the play logs' own `MAX_LOG_FILES`. */
+const MAX_JOURNAL_FILES = 20;
+
+/**
+ * One journal line's payload. `at` (ISO) is added by the writer, so a caller
+ * only ever describes WHAT happened.
+ *
+ * The tripwire arm reuses `build-discipline.ts`'s vocabulary verbatim — its
+ * `TripwireTier`, its tripwire names, and the same inputs its banners are
+ * computed from — so the JSONL and the printed banner can never disagree about
+ * what fired or how loud it was.
+ */
+export type SessionJournalEvent =
+  /** This server began serving this project (the process's own start). */
+  | { readonly kind: 'session-started'; readonly project: string; readonly pid: number }
+  /** `POST /__editor/open-project` switched the live session's project. */
+  | {
+      readonly kind: 'project-opened';
+      readonly project: string;
+      readonly previousProject: string | null;
+    }
+  /** The session is going down (best-effort: a SIGKILL logs nothing). */
+  | { readonly kind: 'session-shutdown' }
+  /** A save-validation verdict — the same facts `runFileValidation` reports. */
+  | {
+      readonly kind: 'validation';
+      /** Project-relative, forward-slash. */
+      readonly path: string;
+      /** The validatable kind the server classified this file as. */
+      readonly fileKind: string;
+      readonly ok: boolean;
+      readonly errors?: readonly string[];
+      readonly warnings?: readonly string[];
+    }
+  /** A build-discipline tripwire CROSSED a step (never a repeat at one tier). */
+  | {
+      readonly kind: 'tripwire';
+      readonly tripwire: 'commit-cadence';
+      readonly tier: TripwireTier;
+      readonly ageMs: number;
+      readonly fileCount: number;
+    }
+  | {
+      readonly kind: 'tripwire';
+      readonly tripwire: 'unplayed-session';
+      readonly tier: TripwireTier;
+      readonly servingForMs: number;
+    }
+  /**
+   * A play-mode log session opened or closed.
+   *
+   * `name` is the run's OPTIONAL slug (`vgai play --name <text>`), `null` for
+   * an unnamed run — the same slug that goes in the log filename, so grepping
+   * the journal for a run and listing `logs/` for it are the same question.
+   */
+  | {
+      readonly kind: 'play';
+      readonly action: 'start' | 'stop';
+      readonly name: string | null;
+      readonly logFile: string | null;
+    }
+  /**
+   * THE TRANSPORT ARM. Everything below is one line per transport or
+   * presence fact, and it exists because the journal was BLIND to all of
+   * them: on 2026-08-09 a session refused five `vgai play` commands against
+   * a healthy connected tab and the whole file it left behind was
+   * `session-started` plus validation lines. A relay that can refuse has to
+   * be able to say who it refused, to which tab, and on what evidence.
+   *
+   * Ids are truncated to 8 characters (`clientId8`, `tabId8`, `requestId8`)
+   * — enough to correlate lines within one session, short enough that a
+   * human can scan a column of them. No payload bodies, ever: a state
+   * snapshot or a command argument list would turn an append-only record
+   * into a memory dump.
+   */
+  /** A control connection opened (either transport). */
+  | {
+      readonly kind: 'client-connected';
+      readonly clientId8: string;
+      readonly transport: 'ws' | 'sse';
+      readonly participant: string | null;
+    }
+  /** A control connection closed, and how many pending commands it settled. */
+  | {
+      readonly kind: 'client-disconnected';
+      readonly clientId8: string;
+      readonly transport: 'ws' | 'sse';
+      /** WebSocket close code, or null for SSE (which has none). */
+      readonly code: number | null;
+      readonly reason: string | null;
+      readonly commandsSettled: number;
+    }
+  /** The server granted a socket the duplex control capability. */
+  | { readonly kind: 'duplex-granted'; readonly clientId8: string }
+  /** A command left the relay for one tab's command channel. */
+  | {
+      readonly kind: 'command-relayed';
+      readonly command: string;
+      readonly requestId8: string;
+      readonly tabId8: string | null;
+      readonly clientId8: string | null;
+    }
+  /** The tab said its command listener PICKED THE COMMAND UP. */
+  | { readonly kind: 'command-receipt'; readonly requestId8: string }
+  /** The command settled — by the tab's own answer or by the relay refusing. */
+  | {
+      readonly kind: 'command-result';
+      readonly requestId8: string;
+      readonly ok: boolean;
+      /** Present only when `ok` is false; the refusal/failure text. */
+      readonly error?: string;
+    }
+  /**
+   * The relay HELD a command instead of refusing it: the target tab is
+   * present by heartbeat but its command channel is not carrying right now
+   * (mid-reload, or a channel that has not answered an echo).
+   */
+  | {
+      readonly kind: 'command-held';
+      readonly requestId8: string;
+      readonly tabId8: string;
+      readonly reason: 'no-channel' | 'unacknowledged';
+    }
+  /** The main-thread echo probe over a duplex socket. */
+  | {
+      readonly kind: 'echo-probe';
+      readonly clientId8: string;
+      readonly answered: boolean;
+      readonly waitedMs: number;
+    }
+  /** The blessed tab changed (or was chosen for the first time). */
+  | {
+      readonly kind: 'tab-blessed';
+      readonly tabId8: string;
+      readonly previousTabId8: string | null;
+      readonly reason: 'sticky' | 'oldest' | 'claimed';
+    }
+  /** An extra tab was told to yield. */
+  | { readonly kind: 'tab-yielded'; readonly tabId8: string }
+  /**
+   * PRESENCE, IN TAB VOCABULARY. These five say what the tab table saw, and
+   * they deliberately do NOT use socket words: a socket closing is not a tab
+   * leaving, and that conflation is what produced "editor tab lost —
+   * reopening" against a tab that had never gone anywhere.
+   */
+  /** A tabId beat for the first time. */
+  | {
+      readonly kind: 'tab-appeared';
+      readonly tabId8: string;
+      readonly visibility: 'visible' | 'hidden';
+    }
+  /** Beats stopped arriving for longer than the notice threshold. */
+  | { readonly kind: 'tab-heartbeat-gap'; readonly tabId8: string; readonly sinceMs: number }
+  /** A gap closed — the same tab resumed beating. `gapMs` is its full length. */
+  | { readonly kind: 'tab-gap-closed'; readonly tabId8: string; readonly gapMs: number }
+  /** Same tabId, new epoch: the page reloaded. The tab never left. */
+  | { readonly kind: 'tab-reloaded'; readonly tabId8: string; readonly epochCount: number }
+  /** Absent past its grace: this tab is gone. */
+  | { readonly kind: 'tab-departed'; readonly tabId8: string; readonly absentMs: number }
+  /**
+   * WHAT THE TAB WAS HOLDING WHEN IT DIED WITHOUT A GOODBYE.
+   *
+   * Emitted beside `client-disconnected` on an ABNORMAL close (1006 — the
+   * socket ended with no close frame, which is what a killed renderer process
+   * leaves behind; an ordinary tab close sends one). Measured 2026-08-10: a
+   * game tab's renderer was killed repeatedly at Chrome's undocumented
+   * per-process ceiling and the whole session record said `1006` and nothing
+   * else — the recovery worked perfectly and the CAUSE was unrecorded.
+   *
+   * `census` is the tab's last resource profile and `censusAgeMs` how stale it
+   * was; both null for a tab that never reported one (an older page, a
+   * tunnelled tab). Numbers only — this stays a journal line, not a dump.
+   */
+  | {
+      readonly kind: 'tab-death-profile';
+      readonly tabId8: string;
+      /** The abnormal close code that triggered the line. */
+      readonly code: number;
+      readonly censusAgeMs: number | null;
+      readonly census: {
+        readonly heapUsedMB: number | null;
+        readonly heapLimitMB: number | null;
+        readonly canvases: number;
+        readonly canvasMB: number;
+        readonly textures?: number;
+        readonly geometries?: number;
+        readonly programs?: number;
+      } | null;
+    }
+  /** Two epochs beating under one tabId — "Duplicate Tab" copied sessionStorage. */
+  | { readonly kind: 'tab-duplicated'; readonly tabId8: string }
+  /**
+   * The tab is present (its worker is beating) but its PAGE has never opened
+   * a command channel this page-load. A heartbeat proves the tab exists, not
+   * that the document works — a main thread that died after the inline
+   * bootstrap beats forever and can run nothing. Such a tab is passed over
+   * for blessing and named in the refusal.
+   */
+  | {
+      readonly kind: 'tab-unresponsive';
+      readonly tabId8: string;
+      readonly noChannelForMs: number;
+    };
+
+/** A parsed journal line: the event plus when it was appended. */
+export type SessionJournalLine = SessionJournalEvent & { readonly at: string };
+
+/** An open journal. `append` never throws — a journal that breaks a save would
+ *  be worse than a journal that misses a line. */
+export interface SessionJournal {
+  /** Absolute path of the file being appended to. */
+  readonly path: string;
+  append(event: SessionJournalEvent): void;
+}
+
+/** `editor-2026-08-09T12-34-56-789Z.jsonl` for a given instant. */
+export function sessionJournalFilename(startedAt: Date): string {
+  return `${PREFIX}${startedAt.toISOString().replace(/[:.]/g, '-')}${SUFFIX}`;
+}
+
+/**
+ * Open (create) this session's journal under `<projectRoot>/logs/`.
+ *
+ * `null` when the directory cannot be created or the first write fails —
+ * an unwritable project must degrade to "no journal", never to a crashed boot.
+ */
+export function openSessionJournal(
+  projectRoot: string,
+  startedAt: Date = new Date(),
+): SessionJournal | null {
+  const logsDir = join(projectRoot, 'logs');
+  try {
+    mkdirSync(logsDir, { recursive: true });
+  } catch {
+    return null;
+  }
+  pruneJournals(logsDir);
+  const path = join(logsDir, sessionJournalFilename(startedAt));
+  const journal: SessionJournal = {
+    path,
+    append(event) {
+      const line: SessionJournalLine = { at: new Date().toISOString(), ...event };
+      try {
+        appendFileSync(path, `${JSON.stringify(line)}\n`, 'utf-8');
+      } catch {
+        /* a journal that breaks the caller is worse than a missing line */
+      }
+    },
+  };
+  try {
+    appendFileSync(path, '', 'utf-8');
+  } catch {
+    return null;
+  }
+  return journal;
+}
+
+/** Drop the oldest journals so opening one more stays at `MAX_JOURNAL_FILES`. */
+function pruneJournals(logsDir: string): void {
+  try {
+    const files = readdirSync(logsDir)
+      .filter((f) => f.startsWith(PREFIX) && f.endsWith(SUFFIX))
+      .sort();
+    for (const f of files.slice(0, Math.max(0, files.length - MAX_JOURNAL_FILES + 1))) {
+      try {
+        unlinkSync(join(logsDir, f));
+      } catch {
+        /* already gone */
+      }
+    }
+  } catch {
+    /* no logs dir yet */
+  }
+}
+
+/**
+ * The newest journal in a project, or `null`.
+ *
+ * File-native on purpose (the same shape as the CLI's newest-play-log reader):
+ * the journal path is a fact about the PROJECT DIRECTORY, so `vgai status` and
+ * the boot pointer can name it without a server round-trip — and can still name
+ * it after the session that wrote it is gone.
+ */
+export function newestSessionJournal(projectRoot: string): string | null {
+  try {
+    const files = readdirSync(join(projectRoot, 'logs'))
+      .filter((f) => f.startsWith(PREFIX) && f.endsWith(SUFFIX))
+      .sort();
+    const newest = files.at(-1);
+    return newest ? join(projectRoot, 'logs', newest) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The newest journal's last `limit` lines of the requested kinds, oldest first.
+ *
+ * WHY A READER EXISTS AT ALL. The journal was written as a file an agent
+ * "can read at any time", and the measured answer to that invitation was: it
+ * doesn't. The foundry probe's journal held the notice-tier tripwire crossing
+ * that predicted its own end-of-run batch commit, and nothing that agent ran
+ * ever rendered a line of it. So the record grows a RENDERER on the command
+ * agents already poll (`vgai status`) — same principle as the tripwires' own
+ * origin: the mechanism was right and the delivery assumption was false.
+ *
+ * Every failure is the same case — no project, no journal, unreadable file, a
+ * line that will not parse — and it is the empty list, never a throw. A status
+ * command that crashed on a malformed log line would be a worse outcome than
+ * one that says nothing about it.
+ *
+ * The whole file is read, which is what bounds this: a journal is one editor
+ * session's surface-worthy transitions (the happy-path silence rule keeps
+ * clean saves out), the pruner caps how many exist, and the alternative — a
+ * reverse streaming reader over a file measured in kilobytes — is machinery
+ * with nothing to buy.
+ */
+export function readRecentJournalEvents(
+  projectRoot: string,
+  kinds: readonly SessionJournalEvent['kind'][],
+  limit: number,
+): SessionJournalLine[] {
+  const path = newestSessionJournal(projectRoot);
+  if (path === null || limit <= 0) return [];
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf-8');
+  } catch {
+    return [];
+  }
+  const wanted = new Set<string>(kinds);
+  const matched: SessionJournalLine[] = [];
+  for (const line of raw.split('\n')) {
+    if (line === '') continue;
+    let parsed: SessionJournalLine;
+    try {
+      parsed = JSON.parse(line) as SessionJournalLine;
+    } catch {
+      continue; // a torn final line is not a reason to report nothing
+    }
+    if (parsed && typeof parsed === 'object' && wanted.has(parsed.kind)) matched.push(parsed);
+  }
+  return matched.slice(-limit);
+}
+
+/**
+ * One journal line as a scannable terminal line: `HH:MM:SS`, the kind, and
+ * the few facts that line is about.
+ *
+ * ONE OWNER of this rendering, for `sessionJournalPointerLine`'s reason — the
+ * events already have exactly one wording as data, and a second prose form per
+ * caller is how a reader ends up believing there are two records.
+ */
+export function formatJournalLine(line: SessionJournalLine): string {
+  const at = line.at.slice(11, 19);
+  switch (line.kind) {
+    case 'tripwire':
+      return line.tripwire === 'commit-cadence'
+        ? `journal: ${at} tripwire commit-cadence ${line.tier} (${line.fileCount} files, ${Math.round(line.ageMs / 60_000)}m)`
+        : `journal: ${at} tripwire unplayed-session ${line.tier} (${Math.round(line.servingForMs / 60_000)}m)`;
+    case 'validation':
+      return `journal: ${at} validation ${line.ok ? 'ok' : 'FAILED'} ${line.path}`;
+    case 'play':
+      return `journal: ${at} play ${line.action}${line.name === null ? '' : ` [${line.name}]`}`;
+    case 'session-started':
+      return `journal: ${at} session-started pid ${line.pid}`;
+    case 'project-opened':
+      return `journal: ${at} project-opened ${line.project}`;
+    case 'session-shutdown':
+      return `journal: ${at} session-shutdown`;
+    // The TRANSPORT arm. One short line each, and every one of them names the
+    // TAB or the request it is about — a column of ids is how these lines get
+    // correlated, and a paragraph per line is how a reader stops reading.
+    case 'client-connected':
+      return `journal: ${at} client-connected ${line.clientId8} (${line.transport})`;
+    case 'client-disconnected':
+      return `journal: ${at} client-disconnected ${line.clientId8} code ${line.code ?? '-'} settled ${line.commandsSettled}`;
+    case 'duplex-granted':
+      return `journal: ${at} duplex-granted ${line.clientId8}`;
+    case 'command-relayed':
+      return `journal: ${at} command-relayed ${line.command} ${line.requestId8} -> tab ${line.tabId8 ?? 'none'}`;
+    case 'command-receipt':
+      return `journal: ${at} command-receipt ${line.requestId8}`;
+    case 'command-result':
+      return `journal: ${at} command-result ${line.requestId8} ${line.ok ? 'ok' : `FAILED ${line.error ?? ''}`}`;
+    case 'command-held':
+      return `journal: ${at} command-held ${line.requestId8} tab ${line.tabId8} (${line.reason})`;
+    case 'echo-probe':
+      return `journal: ${at} echo-probe ${line.clientId8} ${line.answered ? 'answered' : 'UNANSWERED'} in ${line.waitedMs}ms`;
+    case 'tab-blessed':
+      return `journal: ${at} tab-blessed ${line.tabId8} (${line.reason})`;
+    case 'tab-yielded':
+      return `journal: ${at} tab-yielded ${line.tabId8}`;
+    case 'tab-appeared':
+      return `journal: ${at} tab-appeared ${line.tabId8} (${line.visibility})`;
+    case 'tab-heartbeat-gap':
+      return `journal: ${at} tab-heartbeat-gap ${line.tabId8} ${Math.round(line.sinceMs / 100) / 10}s`;
+    case 'tab-gap-closed':
+      return `journal: ${at} tab-gap-closed ${line.tabId8} after ${Math.round(line.gapMs / 100) / 10}s`;
+    case 'tab-reloaded':
+      return `journal: ${at} tab-reloaded ${line.tabId8} (page load ${line.epochCount})`;
+    case 'tab-departed':
+      return `journal: ${at} tab-departed ${line.tabId8} absent ${Math.round(line.absentMs / 100) / 10}s`;
+    case 'tab-duplicated':
+      return `journal: ${at} tab-duplicated ${line.tabId8}`;
+    case 'tab-unresponsive':
+      return `journal: ${at} tab-unresponsive ${line.tabId8} no channel for ${Math.round(line.noChannelForMs / 1000)}s`;
+    case 'tab-death-profile':
+      return `journal: ${at} tab-death-profile ${line.tabId8} code ${line.code} — ${tabDeathProfileBody(line)}`;
+  }
+}
+
+/** The census half of a `tab-death-profile` line, split out so the switch above
+ *  stays one expression per case. */
+function tabDeathProfileBody(line: SessionJournalEvent & { kind: 'tab-death-profile' }): string {
+  const census = formatTabCensus(line.census);
+  if (line.censusAgeMs === null) return census;
+  return `${census} (sampled ${Math.round(line.censusAgeMs / 100) / 10}s before)`;
+}
+
+/** The resource profile a `tab-death-profile` line and a `vgai status` tab row
+ *  both quote. ONE wording, for `sessionJournalPointerLine`'s reason: two
+ *  phrasings of the same numbers is how a reader ends up believing there are
+ *  two measurements. Renderer counts appear only when the page could read them
+ *  (no mounted render-debug adapter = the words are absent, never a zero). */
+export function formatTabCensus(
+  census: (SessionJournalEvent & { kind: 'tab-death-profile' })['census'],
+): string {
+  if (census === null) return 'no resource census';
+  const parts = [
+    census.heapUsedMB === null
+      ? 'heap n/a'
+      : `heap ${census.heapUsedMB}MB${census.heapLimitMB === null ? '' : `/${census.heapLimitMB}MB`}`,
+    `canvas ${census.canvasMB}MB in ${census.canvases}`,
+  ];
+  if (census.textures !== undefined) parts.push(`tex ${census.textures}`);
+  if (census.geometries !== undefined) parts.push(`geo ${census.geometries}`);
+  if (census.programs !== undefined) parts.push(`prog ${census.programs}`);
+  return parts.join(', ');
+}
+
+/**
+ * The ONE wording for "here is the journal" — printed by the editor server's
+ * boot block, by `vgai edit`'s ready/detach lines, and by `vgai status`.
+ *
+ * One owner of the sentence, for `build-discipline.ts`'s reason: three
+ * processes point at this file, and a second phrasing of the same pointer is
+ * how a reader ends up believing there are two things.
+ */
+export function sessionJournalPointerLine(journalPath: string): string {
+  return `Session journal: ${journalPath} — structured JSONL, read it any time`;
+}