@vgai/sdk 0.5.16 → 0.5.18

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.16",
+  "version": "0.5.18",
   "type": "module",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@vgai/engine": "0.5.16",
+    "@vgai/engine": "0.5.18",
     "playwright": "^1.58.2",
     "zod": "^4.3.6"
   }

package/src/play/log-format.ts

@@ -0,0 +1,105 @@
+/**
+ * THE on-disk shape of `<project>/logs/play-*.jsonl` — one definition, shared
+ * by the writer (`editor-server.ts`'s `/__editor/log-session` +
+ * `/__editor/log-entries` handlers) and every reader (`play.log.*` here,
+ * `vgai status`'s play-error banner, the project Logs utility).
+ *
+ * A play log is JSONL with TWO record kinds:
+ *
+ *   1. THE HEADER — always the FIRST line, written when the file is opened:
+ *      `{"kind":"session","v":1,"session":…,"project":…,"run":…,"startedAt":…}`.
+ *      This is where the run's IDENTITY lives, recorded ONCE. The alternative
+ *      (stamping session/project onto every entry) pays the same constant
+ *      thousands of times per run for facts that cannot change while the file
+ *      is open — the file is opened by one session, for one project, at one
+ *      instant.
+ *   2. ENTRIES — every later line: `{t, level, source?, sub?, msg, meta?,
+ *      tick?, simT?, world?, simSpeed?}`. Only genuinely per-entry facts go
+ *      here: `tick`/`simT` (the frame the line was written on), `simSpeed`
+ *      (the live time scale, which an instrument can change mid-run) and
+ *      `world` (the world the run is presenting, unknown until the roots
+ *      mount — so the entries written during boot honestly carry none).
+ *
+ * A reader must SKIP the header when counting or listing entries
+ * (`asPlayLogHeader` is the one test), and must tolerate its ABSENCE: logs
+ * written before the header existed are still on disk in real projects, and
+ * "no header" means "this run's identity was never recorded", never an error.
+ */
+
+import { closeSync, openSync, readSync } from 'node:fs';
+
+/** `kind` value marking a play log's header line. */
+export const PLAY_LOG_HEADER_KIND = 'session';
+
+/** Bumped only when the on-disk record shapes change incompatibly. */
+export const PLAY_LOG_FORMAT_VERSION = 1;
+
+/** The run identity a play log carries on its first line. */
+export interface PlayLogHeader {
+  readonly kind: typeof PLAY_LOG_HEADER_KIND;
+  readonly v: number;
+  /** The editor session that opened the file (`processSessionId()`) — the same
+   *  id `vgai sessions` lists, so a log file names the session that wrote it. */
+  readonly session: string;
+  /** Absolute project root the session was serving. */
+  readonly project: string;
+  /** The run's slug (`vgai play --name <text>`), `null` for an unnamed run —
+   *  the same slug that goes in the filename and the session journal. */
+  readonly run: string | null;
+  /** Wall-clock ms at which the file was opened. */
+  readonly startedAt: number;
+}
+
+/** The header line (newline included) for a run's identity. */
+export function playLogHeaderLine(identity: Omit<PlayLogHeader, 'kind' | 'v'>): string {
+  const header: PlayLogHeader = {
+    kind: PLAY_LOG_HEADER_KIND,
+    v: PLAY_LOG_FORMAT_VERSION,
+    ...identity,
+  };
+  return `${JSON.stringify(header)}\n`;
+}
+
+/** The parsed header, or `null` when this record is an ordinary entry (or a
+ *  header from an unreadable/older shape). Every reader's one header test. */
+export function asPlayLogHeader(record: unknown): PlayLogHeader | null {
+  if (typeof record !== 'object' || record === null || Array.isArray(record)) return null;
+  const rec = record as Record<string, unknown>;
+  if (rec['kind'] !== PLAY_LOG_HEADER_KIND) return null;
+  if (typeof rec['session'] !== 'string' || typeof rec['project'] !== 'string') return null;
+  return {
+    kind: PLAY_LOG_HEADER_KIND,
+    v: typeof rec['v'] === 'number' ? rec['v'] : 0,
+    session: rec['session'],
+    project: rec['project'],
+    run: typeof rec['run'] === 'string' ? rec['run'] : null,
+    startedAt: typeof rec['startedAt'] === 'number' ? rec['startedAt'] : 0,
+  };
+}
+
+/** How much of a log file's start is read to find its header. A header line is
+ *  a few hundred bytes; anything longer is not one. */
+const HEADER_READ_BYTES = 4096;
+
+/**
+ * The header of the log file at `path`, read WITHOUT loading the file — a
+ * listing walks every log in `logs/`, and those files are unbounded (a long
+ * run writes megabytes). `null` for an unreadable file or one with no header.
+ */
+export function readPlayLogHeaderFile(path: string): PlayLogHeader | null {
+  let fd: number | null = null;
+  try {
+    fd = openSync(path, 'r');
+    const buffer = Buffer.alloc(HEADER_READ_BYTES);
+    const bytes = readSync(fd, buffer, 0, HEADER_READ_BYTES, 0);
+    const head = buffer.subarray(0, bytes).toString('utf-8');
+    const newline = head.indexOf('\n');
+    const line = newline === -1 ? head : head.slice(0, newline);
+    if (line.trim() === '') return null;
+    return asPlayLogHeader(JSON.parse(line));
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
+}

package/src/play/log-operations.ts

@@ -12,25 +12,17 @@
  * (reusing "the logs/play-*.jsonl reader" per this unit's own brief, taken
  * literally: read the files).
  *
- * IDENTITY FIELDS (§8 B4 AC "Logs identify session, project, world, and
- * simulation speed"): the real persisted `LogEntry` shape
- * (`packages/editor/src/editor-api.ts`) is `{t, level, source?, sub?, msg,
- * meta?}` — NO session/project/world/simSpeed fields exist in the file
- * format today (a genuine gap against this AC in the CURRENT persistence
- * layer, which predates it; closing it for real would mean threading these
- * fields through `play-mode.ts`'s log sink and `editor-server.ts`'s
- * append handler — both outside this unit's file ownership,
- * packages/editor/src|server). `play.log.read` satisfies the AC honestly,
- * without fabricating anything:
- *   - `session`: the log FILENAME itself (e.g. "play-2026-...jsonl") — the
- *     closest real identity a persisted play run has today.
- *   - `project`: `ctx.projectRoot`, always real (these ops require it).
- *   - `world`/`simSpeed`: read from each entry's own `meta.world` /
- *     `meta.simSpeed`, when the entry happens to carry them (`meta` is
- *     already a free-form bag in the real format) — `null` otherwise. This
- *     is the honest state of affairs: against TODAY's real files these are
- *     always `null` (the current sink never stamps them); a test fixture
- *     that DOES embed them in `meta` proves the read-through path for real.
+ * IDENTITY FIELDS: every one of them is now WRITTEN, so nothing here
+ * synthesizes any of them (`play/log-format.ts` is the format's one
+ * definition, shared with the writer):
+ *   - `session`/`project`/`run`/`startedAt`: the file's HEADER line, written
+ *     once when the editor server opens the file. Recorded once because they
+ *     cannot change while it is open.
+ *   - `world`/`simSpeed`: stamped per ENTRY by `play-mode.ts`'s writers, from
+ *     the live run (the presented world; `game.loop.timeScale`) — and only
+ *     when they genuinely know them, so absence is a real answer.
+ * A log written before the header existed reads back with `null` identity and
+ * no error: those files are still on disk in real projects.
  *
  * `play.log.follow` describes the REAL, existing poll-based subscription
  * for the CURRENTLY ACTIVE play session's log (there is no push/SSE
@@ -53,6 +45,7 @@ import {
   resolveProjectPath,
 } from '../project/shared.js';
 import { defineTool, type ToolRegistry } from '../registry.js';
+import { asPlayLogHeader, type PlayLogHeader, readPlayLogHeaderFile } from './log-format.js';
 import {
   getPlayTransport,
   PLAY_READ_TIMEOUT_MS,
@@ -75,10 +68,33 @@ const PlayLogDiscoverInput = z
   .object({})
   .describe("No input — lists every persisted play-mode log file under the project's logs/ dir.");
 
+const PlayLogRunSchema = z.object({
+  file: z.string().describe('The log filename this run wrote.'),
+  session: z
+    .string()
+    .nullable()
+    .describe(
+      'The editor session that wrote it (the id `vgai sessions` lists), from the file header — ' +
+        'null for a log written before headers existed.',
+    ),
+  project: z.string().nullable().describe('Absolute project root the session was serving.'),
+  run: z
+    .string()
+    .nullable()
+    .describe('The run name slug (`vgai play --name`), null for an unnamed run.'),
+  startedAt: z.number().nullable().describe('Wall-clock ms at which the run opened its log.'),
+});
+
 const PlayLogDiscoverResult = z.object({
   logFiles: z
     .array(z.string())
     .describe('Filenames (e.g. "play-2026-07-11T10-00-00.jsonl"), oldest first (name-sorted).'),
+  runs: z
+    .array(PlayLogRunSchema)
+    .describe(
+      "The same files with each one's recorded identity, read from its header line — this is " +
+        "how a caller picks ITS session's log out of the directory instead of guessing by name.",
+    ),
 });
 
 export const playLogDiscover = defineTool({
@@ -87,7 +103,8 @@ export const playLogDiscover = defineTool({
   description:
     'Reads <projectRoot>/logs/ directly off disk and filters play-*.jsonl (the exact naming ' +
     "convention editor-server.ts's log-session handler writes). Works with no editor/play " +
-    'session running — these files persist after play stops.',
+    'session running — these files persist after play stops. Each file also reports the ' +
+    'session/project/run identity from its own header line (null for pre-header logs).',
   input: PlayLogDiscoverInput,
   result: PlayLogDiscoverResult,
   errors: [NO_PROJECT_ROOT_ERROR, PATH_OUTSIDE_PROJECT_ERROR],
@@ -106,7 +123,17 @@ export const playLogDiscover = defineTool({
       names = [];
     }
     const logFiles = names.filter((f) => f.startsWith('play-') && f.endsWith('.jsonl')).sort();
-    return { logFiles };
+    const runs = logFiles.map((file) => {
+      const header = readPlayLogHeaderFile(join(logsDir, file));
+      return {
+        file,
+        session: header?.session ?? null,
+        project: header?.project ?? null,
+        run: header?.run ?? null,
+        startedAt: header?.startedAt ?? null,
+      };
+    });
+    return { logFiles, runs };
   },
 });
 
@@ -121,21 +148,33 @@ const PlayLogEntrySchema = z.object({
   sub: z.string().nullable(),
   msg: z.string(),
   meta: z.record(z.string(), z.unknown()).nullable(),
-  session: z.string().describe('The log filename identifying this play run (see module jsdoc).'),
+  tick: z
+    .number()
+    .nullable()
+    .describe('Engine fixed-step counter at write time, when the writer could read it.'),
+  simT: z.number().nullable().describe('Accumulated sim-seconds at write time — same source.'),
+  session: z
+    .string()
+    .nullable()
+    .describe(
+      "The editor session that wrote this log, from the file's header line — null for a log " +
+        'written before headers existed.',
+    ),
   project: z.string().describe('Absolute project root this log belongs to.'),
   world: z
     .string()
     .nullable()
     .describe(
-      'Active world id for this entry, read from meta.world when the writer stamped it — null ' +
-        "otherwise (today's real sink never stamps this; see module jsdoc).",
+      'The world the run was presenting when this entry was written, as the play-mode writer ' +
+        'stamped it — null when it had no unambiguous world (boot-time entries, multi-root runs ' +
+        'presenting none).',
     ),
   simSpeed: z
     .number()
     .nullable()
     .describe(
-      'Simulation time-scale for this entry, read from meta.simSpeed when the writer stamped it ' +
-        "— null otherwise (today's real sink never stamps this; see module jsdoc).",
+      "The loop's live time scale when this entry was written (1 real time, 0 paused) — null " +
+        'when no game was running yet.',
     ),
 });
 
@@ -157,24 +196,25 @@ const PlayLogReadInput = z.object({
 
 const PlayLogReadResult = z.object({
   entries: z.array(PlayLogEntrySchema),
-  totalEntries: z.number().describe('Total entries in the file, regardless of offset/limit.'),
+  totalEntries: z
+    .number()
+    .describe('Total entries in the file, regardless of offset/limit (the header is not one).'),
+  run: PlayLogRunSchema.describe("This log's own recorded identity, from its header line."),
 });
 
 function isRecord(v: unknown): v is Record<string, unknown> {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 
-/** Parse one raw JSONL line into a `PlayLogEntrySchema`-shaped entry, stamping the identity fields (see module jsdoc). */
+/** Parse one raw JSONL entry line, carrying the file-level session identity
+ *  from the header onto it. Every field is read from what the writer actually
+ *  wrote; nothing is derived from the filename or invented. */
 function parseLogLine(
-  line: string,
-  session: string,
+  rec: Record<string, unknown>,
+  session: string | null,
   project: string,
 ): z.infer<typeof PlayLogEntrySchema> {
-  const parsed: unknown = JSON.parse(line);
-  const rec = isRecord(parsed) ? parsed : {};
   const meta = isRecord(rec['meta']) ? (rec['meta'] as Record<string, unknown>) : null;
-  const worldRaw = meta?.['world'];
-  const simSpeedRaw = meta?.['simSpeed'];
   return {
     t: typeof rec['t'] === 'number' ? rec['t'] : 0,
     level: typeof rec['level'] === 'string' ? rec['level'] : 'log',
@@ -182,10 +222,12 @@ function parseLogLine(
     sub: typeof rec['sub'] === 'string' ? rec['sub'] : null,
     msg: typeof rec['msg'] === 'string' ? rec['msg'] : '',
     meta,
+    tick: typeof rec['tick'] === 'number' ? rec['tick'] : null,
+    simT: typeof rec['simT'] === 'number' ? rec['simT'] : null,
     session,
     project,
-    world: typeof worldRaw === 'string' ? worldRaw : null,
-    simSpeed: typeof simSpeedRaw === 'number' ? simSpeedRaw : null,
+    world: typeof rec['world'] === 'string' ? rec['world'] : null,
+    simSpeed: typeof rec['simSpeed'] === 'number' ? rec['simSpeed'] : null,
   };
 }
 
@@ -193,10 +235,10 @@ export const playLogRead = defineTool({
   name: 'play.log.read',
   summary: 'Read entries from a persisted play-mode log file.',
   description:
-    'Reads <projectRoot>/logs/<file> directly off disk, parsing each JSONL line. Each returned ' +
-    'entry is enriched with session (the log filename)/project (ctx.projectRoot) — both real — ' +
-    "plus world/simSpeed read from the entry's own meta bag when present, null otherwise (see " +
-    'module jsdoc for why the raw persisted format has no dedicated fields for these yet).',
+    "Reads <projectRoot>/logs/<file> directly off disk, parsing each JSONL line. The file's " +
+    'header line supplies the run identity (session/project/run/startedAt, reported as `run` and ' +
+    'carried onto every entry); world/simSpeed/tick/simT come from each entry as the play-mode ' +
+    'writer stamped them. A pre-header log reads back with null identity, never an error.',
   input: PlayLogReadInput,
   result: PlayLogReadResult,
   errors: [NO_PROJECT_ROOT_ERROR, PATH_OUTSIDE_PROJECT_ERROR, FILE_NOT_FOUND_ERROR],
@@ -209,12 +251,33 @@ export const playLogRead = defineTool({
     const projectRoot = requireProjectRoot(ctx);
     const absPath = resolveProjectPath(projectRoot, join('logs', input.file));
     const { raw } = readFileWithHash(absPath);
-    const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+    const records = raw
+      .split('\n')
+      .filter((l) => l.trim().length > 0)
+      .map((line): unknown => JSON.parse(line));
+    // The header is the file's identity, not one of its entries: it is peeled
+    // off before offset/limit and before totalEntries, so a caller paging
+    // through a log never has to know it is there.
+    const header: PlayLogHeader | null = records.length > 0 ? asPlayLogHeader(records[0]) : null;
+    const entryRecords = header === null ? records : records.slice(1);
     const offset = input.offset ?? 0;
-    const limit = input.limit ?? lines.length;
-    const slice = lines.slice(offset, offset + limit);
-    const entries = slice.map((line) => parseLogLine(line, input.file, projectRoot));
-    return { entries, totalEntries: lines.length };
+    const limit = input.limit ?? entryRecords.length;
+    const entries = entryRecords
+      .slice(offset, offset + limit)
+      .map((record) =>
+        parseLogLine(isRecord(record) ? record : {}, header?.session ?? null, projectRoot),
+      );
+    return {
+      entries,
+      totalEntries: entryRecords.length,
+      run: {
+        file: input.file,
+        session: header?.session ?? null,
+        project: header?.project ?? null,
+        run: header?.run ?? null,
+        startedAt: header?.startedAt ?? null,
+      },
+    };
   },
 });
 
@@ -235,7 +298,17 @@ const PlayLogFollowResult = z.object({
     .describe('POST {action:"start"|"end"} — already bracketing the active play session.'),
   bufferedLogCount: z
     .number()
-    .describe('Live count of entries buffered for the active play session.'),
+    .describe('Live count of entries buffered for the active play session (header excluded).'),
+  file: z
+    .string()
+    .nullable()
+    .describe("The active run's log filename under logs/ — what play.log.read should be given."),
+  session: z
+    .string()
+    .nullable()
+    .describe("The editor session that opened it, from the file's header line."),
+  project: z.string().nullable().describe('Absolute project root that session is serving.'),
+  run: z.string().nullable().describe('The run name slug, null for an unnamed run.'),
 });
 
 export const playLogFollow = defineTool({
@@ -244,7 +317,8 @@ export const playLogFollow = defineTool({
   description:
     'Metadata only (no push/SSE for log lines exists today): reports the real ' +
     'GET/POST /__editor/log-entries + /__editor/log-session endpoints for the CURRENTLY active ' +
-    'play session, plus a live buffered-entry count — same contract as editor.console.subscribe.',
+    'play session, plus a live buffered-entry count and the run identity the active log file ' +
+    'recorded in its header — same contract as editor.console.subscribe.',
   input: PlayLogFollowInput,
   result: PlayLogFollowResult,
   errors: [PLAY_RUNTIME_NOT_AVAILABLE_ERROR, PLAY_LOG_FOLLOW_UNAVAILABLE_ERROR],
@@ -268,7 +342,18 @@ export const playLogFollow = defineTool({
         {},
       );
     }
-    return metadata;
+    // A transport that predates the header (or an older editor answering it)
+    // reports the endpoints and the count and says `null` for the identity —
+    // absence, never a name inferred from somewhere else.
+    return {
+      logEntriesUrl: metadata.logEntriesUrl,
+      logSessionUrl: metadata.logSessionUrl,
+      bufferedLogCount: metadata.bufferedLogCount,
+      file: metadata.file ?? null,
+      session: metadata.session ?? null,
+      project: metadata.project ?? null,
+      run: metadata.run ?? null,
+    };
   },
 });
 

package/src/play/transport.ts

@@ -79,6 +79,7 @@ import { z } from 'zod';
 import { ToolError } from '../errors.js';
 import type { ToolErrorDefinition } from '../registry.js';
 import type { ToolContext } from '../types.js';
+import { asPlayLogHeader } from './log-format.js';
 
 // ---------------------------------------------------------------------------
 // Named timeouts
@@ -239,6 +240,13 @@ export interface PlayLogFollowMetadata {
   logEntriesUrl: string;
   logSessionUrl: string;
   bufferedLogCount: number;
+  /** The active log's filename and the identity its header line recorded
+   *  (`@vgai/sdk`'s `play/log-format.ts`). Optional on the seam so a fake
+   *  transport may omit what it has no wire for; the op reports `null`. */
+  file?: string | null;
+  session?: string | null;
+  project?: string | null;
+  run?: string | null;
 }
 
 export type InputInjectionKind = 'axis' | 'vector2' | 'pointerDelta' | 'pointerPosition';
@@ -633,13 +641,18 @@ export class HttpPlayTransport implements PlayTransport {
     timeoutMs: number,
   ): Promise<PlayLogFollowMetadata | undefined> {
     const body = (await fetchJson(`${baseUrl(session)}/__editor/log-entries`, timeoutMs)) as
-      | { entries?: unknown[] }
+      | { entries?: unknown[]; header?: unknown; file?: unknown }
       | undefined;
     if (!body) return undefined;
+    const header = asPlayLogHeader(body.header);
     return {
       logEntriesUrl: `${baseUrl(session)}/__editor/log-entries`,
       logSessionUrl: `${baseUrl(session)}/__editor/log-session`,
       bufferedLogCount: Array.isArray(body.entries) ? body.entries.length : 0,
+      file: typeof body.file === 'string' ? body.file : null,
+      session: header?.session ?? null,
+      project: header?.project ?? null,
+      run: header?.run ?? null,
     };
   }