@vgai/sdk 0.5.13 → 0.5.14

package/package.json

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

package/src/cinematic/theatre-operations.ts

@@ -31,7 +31,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 import { z } from 'zod';
 import { ToolError } from '../errors.js';
-import { listProjectFiles } from '../project/shared.js';
+import { isTheatreProjectPath, listProjectFiles } from '../project/shared.js';
 import { defineTool, type ToolErrorDefinition, type ToolRegistry } from '../registry.js';
 import type { ToolContext } from '../types.js';
 
@@ -153,7 +153,7 @@ export const cinematicProjectList = defineTool({
   permission: { risk: 'read', summary: 'Walks a file tree; no writes.' },
   async impl(input, ctx) {
     const root = resolveRoot(input.root, ctx);
-    const theatreProjectFiles = listProjectFiles(root, (p) => p.endsWith('theatre-project.json'));
+    const theatreProjectFiles = listProjectFiles(root, isTheatreProjectPath);
     return { root, theatreProjectFiles };
   },
 });

package/src/mcp/mcp-server.ts

@@ -159,7 +159,7 @@ export function createMcpServer(options: CreateMcpServerOptions = {}): VgaiMcpSe
       request.params.name === 'discover-project'
         ? 'Call project.discover, project.status, and project.manifest.read. Summarize each adapter root and then call editor.session.list. Do not write files.'
         : request.params.name === 'bring-existing-game'
-          ? 'Call project.inspect before writing anything. Use its detected technologies, entry candidates, and blockers to identify Three.js/R3F, PixiJS, or React by renderer; explain the honest adapter tier and obtain consent before metadata or source writes.'
+          ? 'Call project.inspect before writing anything. Use its detected technologies, entry candidates, and blockers to identify Three.js/R3F, PixiJS, or React by renderer; name any capability the adapter has not yet reached and obtain consent before metadata or source writes.'
           : `Implement only this requested outcome: ${task}. Discover the project first, preserve unrelated work, use dryRun for file mutations when available, then verify through the exact matching editor with Play, status/logs, and a legible capture.`;
     return {
       description: requested.description,

package/src/project/discovery-operations.ts

@@ -9,7 +9,8 @@
  *  - Stories (CSF) are ordinary `.tsx`/`.ts` modules (§5.2/C3) — VGAI stores
  *    no duplicate story registry, so there is nothing to mutate here; listing
  *    `*.stories.tsx`/`*.stories.ts` is the whole B2 surface.
- *  - Theatre project state (`*.theatre-project.json`) is a real, versioned,
+ *  - Theatre project state (`theatre-project.json` or `*.theatre-project.json`)
+ *    is a real, versioned,
  *    proprietary Theatre.js format this repo does not own (§3.2/§5.3 — "the
  *    committed Theatre project state is authoritative authored data"). B2
  *    validates only the OUTER shape (`sheetsById`/`definitionVersion`/
@@ -29,6 +30,7 @@ import { z } from 'zod';
 import { ToolError } from '../errors.js';
 import { defineTool, type ToolRegistry } from '../registry.js';
 import {
+  isTheatreProjectPath,
   listProjectFiles,
   NO_PROJECT_ROOT_ERROR,
   PATH_OUTSIDE_PROJECT_ERROR,
@@ -71,7 +73,7 @@ export const projectStoryDiscover = defineTool({
 export const projectTheatreDiscover = defineTool({
   name: 'project.theatre.discover',
   summary:
-    'List every committed Theatre project-state file (*.theatre-project.json) in the project.',
+    'List every committed Theatre project-state file (theatre-project.json or *.theatre-project.json) in the project.',
   description:
     'List-only (§3.2/§5.3: the committed Theatre project state is authoritative authored data VGAI does not own the internal format of).',
   input: z.object({}),
@@ -86,9 +88,7 @@ export const projectTheatreDiscover = defineTool({
   permission: { risk: 'read', summary: 'Walks the project file tree; no writes.' },
   async impl(_input, ctx) {
     const projectRoot = requireProjectRoot(ctx);
-    const theatreProjectFiles = listProjectFiles(projectRoot, (p) =>
-      p.endsWith('.theatre-project.json'),
-    );
+    const theatreProjectFiles = listProjectFiles(projectRoot, isTheatreProjectPath);
     return { theatreProjectFiles };
   },
 });

package/src/project/manifest-operations.ts

@@ -22,6 +22,7 @@ import {
   checkNotStale,
   DryRunField,
   FILE_NOT_FOUND_ERROR,
+  isTheatreProjectPath,
   listProjectFiles,
   mutationResultSchema,
   NO_PROJECT_ROOT_ERROR,
@@ -65,7 +66,7 @@ const ProjectDiscoverResult = z
       .describe('Every *.stories.tsx / *.stories.ts found under the project.'),
     theatreProjectFiles: z
       .array(z.string())
-      .describe('Every *.theatre-project.json found under the project.'),
+      .describe('Every theatre-project.json / *.theatre-project.json found under the project.'),
   })
   .describe('A one-call survey of the project at ctx.projectRoot.');
 
@@ -115,9 +116,7 @@ export const projectDiscover = defineTool({
         projectRoot,
         (p) => p.endsWith('.stories.tsx') || p.endsWith('.stories.ts'),
       ),
-      theatreProjectFiles: listProjectFiles(projectRoot, (p) =>
-        p.endsWith('.theatre-project.json'),
-      ),
+      theatreProjectFiles: listProjectFiles(projectRoot, isTheatreProjectPath),
     };
   },
 });

package/src/project/session-journal.ts

@@ -235,16 +235,78 @@ export type SessionJournalEvent =
   /** 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.
+   * The tab is present but its PAGE never came up this page-load. Presence
+   * proves the tab exists, not that the document works — a main thread that
+   * died after the inline bootstrap keeps beating and holding its control
+   * connection, and can run nothing. Such a tab is passed over for blessing
+   * and named in the refusal.
+   *
+   * `reason` says which stage it is stuck at: `'no-channel'` (the page never
+   * opened a control connection at all) or `'no-command-listener'` (it did,
+   * and the module graph behind it never produced a listener).
    */
   | {
       readonly kind: 'tab-unresponsive';
       readonly tabId8: string;
-      readonly noChannelForMs: number;
+      readonly reason: 'no-channel' | 'no-command-listener';
+      readonly unresponsiveForMs: number;
+    }
+  /**
+   * An uncaught error or unhandled rejection in a tab's PAGE, captured by
+   * `index.html`'s inline bootstrap — before the module graph, so it is
+   * recorded even when the boot that would have reported it is the thing that
+   * died. This is the line that says WHY a `tab-unresponsive` tab is
+   * unresponsive.
+   */
+  | {
+      readonly kind: 'page-error';
+      readonly tabId8: string;
+      readonly message: string;
+    }
+  /**
+   * One batch of occurrences of ONE console error/warning condition, as the
+   * server's unresolved-console ledger recorded it
+   * (`packages/editor/server/console-ledger.ts`).
+   *
+   * This is the DURABLE half of the loudness convention, and the reason it is
+   * a row per observation rather than a row per distinct message: `count` is
+   * the running total after this batch, so the file answers "how many times
+   * did this actually fire, and when did it stop" long after the ledger (and
+   * the tab, and the server) are gone. A repeat is never filtered out here —
+   * deduping repeats to silence is precisely the failure that made a session's
+   * eleven errors read as one line and then nothing.
+   */
+  | {
+      readonly kind: 'console-entry';
+      readonly id: string;
+      readonly severity: 'error' | 'warn';
+      readonly source: string | null;
+      /** Occurrences in THIS batch. */
+      readonly added: number;
+      /** Running total for this condition, across every page-load. */
+      readonly count: number;
+      readonly message: string;
+    }
+  /** A condition cleared by the honest re-test: the page reloaded and it did
+   *  not recur. `count` is what it reached before it stopped. */
+  | {
+      readonly kind: 'console-retired';
+      readonly id: string;
+      readonly severity: 'error' | 'warn';
+      readonly count: number;
+      readonly message: string;
+    }
+  /** A condition waved through BY NAME (`vgai console ack`). The audit row is
+   *  the whole point: an acknowledgment records who and why, and never erases
+   *  what was acknowledged. */
+  | {
+      readonly kind: 'console-ack';
+      readonly id: string;
+      readonly severity: 'error' | 'warn';
+      readonly count: number;
+      readonly by: string;
+      readonly reason: string;
+      readonly message: string;
     };
 
 /** A parsed journal line: the event plus when it was appended. */
@@ -449,9 +511,22 @@ export function formatJournalLine(line: SessionJournalLine): string {
     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`;
+      return `journal: ${at} tab-unresponsive ${line.tabId8} ${line.reason} for ${Math.round(line.unresponsiveForMs / 1000)}s`;
+    case 'page-error':
+      return `journal: ${at} page-error ${line.tabId8} ${line.message}`;
     case 'tab-death-profile':
       return `journal: ${at} tab-death-profile ${line.tabId8} code ${line.code} — ${tabDeathProfileBody(line)}`;
+    // The CONSOLE arm. `count` is the running total for that condition, so a
+    // reader scanning the column sees a repeat climbing rather than the same
+    // line over and over with nothing to distinguish the fiftieth from the
+    // first. Every line leads with the ack id, because that is what a reader
+    // types next.
+    case 'console-entry':
+      return `journal: ${at} console-${line.severity} ${line.id} +${line.added} (total ${line.count}) ${line.source === null ? '' : `[${line.source}] `}${line.message.split('\n')[0]}`;
+    case 'console-retired':
+      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}`;
   }
 }
 

package/src/project/shared.ts

@@ -44,6 +44,12 @@ import { ToolError } from '../errors.js';
 import type { ToolErrorDefinition } from '../registry.js';
 import type { ToolContext } from '../types.js';
 
+/** Both Theatre project-state names already established in shipped projects. */
+export function isTheatreProjectPath(path: string): boolean {
+  const filename = path.slice(Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\')) + 1);
+  return filename === 'theatre-project.json' || filename.endsWith('.theatre-project.json');
+}
+
 // ---------------------------------------------------------------------------
 // Project-root resolution
 // ---------------------------------------------------------------------------