@vgai/sdk 0.5.40 → 0.5.42

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.40",
+  "version": "0.5.42",
   "type": "module",
   "repository": {
     "type": "git",
@@ -31,7 +31,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@vgai/engine": "0.5.40",
+    "@vgai/engine": "0.5.42",
     "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/session-journal.ts

@@ -210,6 +210,23 @@ export type SessionJournalEvent =
     }
   /** The server granted a socket the duplex control capability. */
   | { readonly kind: 'duplex-granted'; readonly clientId8: string }
+  /** A page proved it is speaking the exact generation the server granted. */
+  | {
+      readonly kind: 'control-lifecycle-confirmed';
+      readonly clientId8: string;
+      readonly connectionGeneration8: string;
+    }
+  /** A stale or contradictory control frame was refused. */
+  | {
+      readonly kind: 'control-lifecycle-rejected';
+      readonly clientId8: string;
+      readonly mismatch:
+        | 'serverGeneration'
+        | 'connectionGeneration'
+        | 'clientId'
+        | 'tabId'
+        | 'pageGeneration';
+    }
   /** A command left the relay for one tab's command channel. */
   | {
       readonly kind: 'command-relayed';
@@ -588,6 +605,10 @@ export function formatJournalLine(line: SessionJournalLine): string {
       return `journal: ${at} client-disconnected ${line.clientId8} code ${line.code ?? '-'} settled ${line.commandsSettled}`;
     case 'duplex-granted':
       return `journal: ${at} duplex-granted ${line.clientId8}`;
+    case 'control-lifecycle-confirmed':
+      return `journal: ${at} control-lifecycle-confirmed ${line.clientId8} connection ${line.connectionGeneration8}`;
+    case 'control-lifecycle-rejected':
+      return `journal: ${at} control-lifecycle-rejected ${line.clientId8} stale ${line.mismatch}`;
     case 'command-relayed':
       return `journal: ${at} command-relayed ${line.command} ${line.requestId8} -> tab ${line.tabId8 ?? 'none'}`;
     case 'command-receipt':

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 {