@vgai/sdk 0.5.41 → 0.5.44

package/package.json

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

package/src/play/log-format-node.ts

@@ -0,0 +1,35 @@
+/**
+ * The Node half of the play-log format: the header fast-read over a file
+ * descriptor. Split from `log-format.ts` so the browser tier (which writes
+ * and parses the same format through the StorageBackend) can import the
+ * format without `node:fs` — the same split `game-globals-prelude.ts`
+ * established for its two programs.
+ */
+
+import { closeSync, openSync, readSync } from 'node:fs';
+import { asPlayLogHeader, type PlayLogHeader } from './log-format.js';
+
+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-format.ts

@@ -26,8 +26,6 @@
  * "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';
 
@@ -76,30 +74,3 @@ export function asPlayLogHeader(record: unknown): PlayLogHeader | 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

@@ -45,7 +45,8 @@ import {
   resolveProjectPath,
 } from '../project/shared.js';
 import { defineTool, type ToolRegistry } from '../registry.js';
-import { asPlayLogHeader, type PlayLogHeader, readPlayLogHeaderFile } from './log-format.js';
+import { asPlayLogHeader, type PlayLogHeader } from './log-format.js';
+import { readPlayLogHeaderFile } from './log-format-node.js';
 import {
   getPlayTransport,
   PLAY_READ_TIMEOUT_MS,

package/src/project/build-discipline.ts

@@ -459,7 +459,12 @@ export function unplayedSessionTier(
   sessionStartedAtMs: number | null,
   newestEvidence: number | null,
   now: number,
+  /** Does the project declare anything to play? A MODELS project (no roots)
+   *  has no game to run; the nag sent one to `vgai play`, which refused,
+   *  and the refusal sat on the console (blind lantern round, 2026-09-06). */
+  playable = true,
 ): TripwireTier {
+  if (!playable) return 'silent';
   if (sessionStartedAtMs === null) return 'silent';
   if (newestEvidence !== null && newestEvidence >= sessionStartedAtMs) return 'silent';
   const servingForMs = now - sessionStartedAtMs;
@@ -482,8 +487,9 @@ export function unplayedSessionBanner(
   sessionStartedAtMs: number | null,
   newestEvidence: number | null,
   now: number,
+  playable = true,
 ): string | null {
-  const tier = unplayedSessionTier(sessionStartedAtMs, newestEvidence, now);
+  const tier = unplayedSessionTier(sessionStartedAtMs, newestEvidence, now, playable);
   if (tier === 'silent' || sessionStartedAtMs === null) return null;
   const elapsed = formatElapsed(now - sessionStartedAtMs);
   if (tier === 'notice') {

package/src/project/session-journal.ts

@@ -290,6 +290,22 @@ export type SessionJournalEvent =
   | { 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 }
+  /** The page announced main-thread work before starting it (a play-boot
+   *  step, a model's `building src/models/x.ts`), or cleared it (`null`). */
+  | { readonly kind: 'page-phase'; readonly phase: string | null }
+  /**
+   * What the project's source watcher saw: one line per chokidar event under
+   * `src/` (`add`/`change`/`unlink`), with the file's mtime as the watcher
+   * found it (`null` when the path was gone). The instrument for "why did
+   * the page reload / the table refresh" — a reload on a file whose mtime
+   * never moved is a phantom event, and this is where it shows.
+   */
+  | {
+      readonly kind: 'src-watch';
+      readonly event: string;
+      readonly path: string;
+      readonly mtimeMs: number | null;
+    }
   /** Absent past its grace: this tab is gone. */
   | { readonly kind: 'tab-departed'; readonly tabId8: string; readonly absentMs: number }
   /**
@@ -392,6 +408,17 @@ export type SessionJournalEvent =
       readonly by: string;
       readonly reason: string;
       readonly message: string;
+    }
+  /** A condition cleared by its OWNER, which proved it gone by an event the
+   *  reload rule cannot see — a play remount resolving its own
+   *  `Restart required` warning. `by` names that owner, never a person. */
+  | {
+      readonly kind: 'console-resolved';
+      readonly id: string;
+      readonly severity: 'error' | 'warn';
+      readonly count: number;
+      readonly by: string;
+      readonly message: string;
     };
 
 /** A parsed journal line: the event plus when it was appended. */
@@ -631,6 +658,10 @@ export function formatJournalLine(line: SessionJournalLine): string {
       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 'page-phase':
+      return `journal: ${at} page-phase ${line.phase ?? '(clear)'}`;
+    case 'src-watch':
+      return `journal: ${at} src-watch ${line.event} ${line.path}${line.mtimeMs === null ? ' (gone)' : ''}`;
     case 'tab-departed':
       return `journal: ${at} tab-departed ${line.tabId8} absent ${Math.round(line.absentMs / 100) / 10}s`;
     case 'tab-duplicated':
@@ -652,6 +683,8 @@ export function formatJournalLine(line: SessionJournalLine): string {
       return `journal: ${at} console-retired ${line.id} after ${line.count} — did not recur after reload`;
     case 'console-ack':
       return `journal: ${at} console-ack ${line.id} (×${line.count}) by ${line.by}: ${line.reason}`;
+    case 'console-resolved':
+      return `journal: ${at} console-resolved ${line.id} after ${line.count} — ${line.by} cleared the condition it raised`;
   }
 }
 

package/src/project-tool-catalog.ts

@@ -68,7 +68,9 @@ export interface ProjectToolLoadError {
  *    is a FACT about the project; a host that cannot ask has not learned it.
  */
 export const NO_PROJECT_MODULE_HOST_MESSAGE =
-  'This editor host cannot load project TypeScript modules. Use the Vite-backed dev or packaged editor.';
+  'This editor host cannot RUN registered project tools (package.json#vgai.tools): callables ' +
+  'execute on the Node side. Contribution panels still load from project source; to run the ' +
+  'tools themselves, open the project in the Vite-backed dev or packaged editor.';
 
 /** The catalog row that states {@link NO_PROJECT_MODULE_HOST_MESSAGE}. */
 export function noProjectModuleHostError(): ProjectToolLoadError {

package/src/registry.ts

@@ -139,7 +139,7 @@ export type ToolOutcome<TResult = unknown> =
  *     `Error`, or a non-Error throw — normalized into INTERNAL_ERROR. The
  *     raw exception/message is never used as the identifying `code`, but it
  *     IS carried in `message` as well as `data.message`: every projection
- *     (the CLI's `vgai run`, the oclif commands, `vgai screenshot`'s module
+ *     (the CLI's `vgai tool`, the oclif commands, `vgai screenshot`'s module
  *     lane) shows `error.message` and only some of them dump `data`, so a
  *     `message` that said nothing but "threw an unstructured exception"
  *     hid the one sentence the caller needed ("No editor connected — open

package/src/types.ts

@@ -127,5 +127,15 @@ export interface ToolContext {
    *  game binds `game.instance(ctx.instance)` from it; omitted means the sole
    *  live instance. */
   instance?: string;
+  /** The HOST's project-module loader (the editor server's Vite SSR loader,
+   *  wrapped with dependency-change invalidation). A tool that imports the
+   *  project's own source at run time — `project.bake.preview` importing
+   *  `src/models/barrel.ts` — MUST load through this rather than a raw
+   *  `import()`: Node's ESM cache never invalidates, so a raw import returned
+   *  the FIRST version of a model for the life of the server and every later
+   *  edit re-rendered byte-identical until `vgai restart` (measured on the
+   *  blind modeling bench, 2026-09-05: three restarts in one barrel). Absent
+   *  only when the tool runs outside an editor server. */
+  loadProjectModule?: (absolutePath: string) => Promise<unknown>;
   [key: string]: unknown;
 }