@vgai/sdk 0.5.2 → 0.5.4

package/src/project/manifest-operations.ts

@@ -1,6 +1,5 @@
 /**
- * `project.discover` and `project.manifest.*` (B2,
- * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B2 "project
+ * `project.discover` and `project.manifest.*` (B2, "project
  * discovery/status" + "manifest read/validate/update").
  *
  * REUSE, not reimplementation: `project.manifest.validate`/`.update` both
@@ -33,7 +32,7 @@ import {
   writeFileAtomic,
 } from './shared.js';
 
-const MANIFEST_FILENAME = 'vgai.game.json';
+const MANIFEST_FILENAME = 'vgai.project.json';
 
 // ---------------------------------------------------------------------------
 // project.discover — richer, real project-native discovery (B1's
@@ -49,7 +48,7 @@ const ProjectDiscoverResult = z
     projectRoot: z.string().describe('Absolute path this discovery ran against.'),
     hasManifest: z
       .boolean()
-      .describe('True when vgai.game.json exists directly under projectRoot.'),
+      .describe('True when vgai.project.json exists directly under projectRoot.'),
     manifestName: z
       .string()
       .optional()
@@ -58,9 +57,6 @@ const ProjectDiscoverResult = z
       .array(z.string())
       .optional()
       .describe('Adapter-root ids declared in the manifest, when present/valid.'),
-    sceneFiles: z
-      .array(z.string())
-      .describe('Every *.vscn.json found under the project (project-relative).'),
     inputMapFiles: z
       .array(z.string())
       .describe('Every *.inputmap.json found under the project (project-relative).'),
@@ -114,7 +110,6 @@ export const projectDiscover = defineTool({
       hasManifest,
       ...(manifestName !== undefined ? { manifestName } : {}),
       ...(rootIds !== undefined ? { rootIds } : {}),
-      sceneFiles: listProjectFiles(projectRoot, (p) => p.endsWith('.vscn.json')),
       inputMapFiles: listProjectFiles(projectRoot, (p) => p.endsWith('.inputmap.json')),
       storyFiles: listProjectFiles(
         projectRoot,
@@ -133,11 +128,11 @@ export const projectDiscover = defineTool({
 
 const ProjectManifestReadInput = z
   .object({})
-  .describe('No input — reads vgai.game.json under ctx.projectRoot.');
+  .describe('No input — reads vgai.project.json under ctx.projectRoot.');
 
 const ProjectManifestReadResult = z
   .object({
-    path: z.string().describe('Absolute path to vgai.game.json.'),
+    path: z.string().describe('Absolute path to vgai.project.json.'),
     contentHash: z
       .string()
       .describe(
@@ -153,7 +148,7 @@ const ProjectManifestReadResult = z
 
 export const projectManifestRead = defineTool({
   name: 'project.manifest.read',
-  summary: 'Read the raw vgai.game.json manifest for the project.',
+  summary: 'Read the raw vgai.project.json manifest for the project.',
   description:
     'File-native read. Returns the raw parsed JSON plus a content hash for optimistic-concurrency updates.',
   input: ProjectManifestReadInput,
@@ -163,7 +158,7 @@ export const projectManifestRead = defineTool({
   host: 'node',
   mutates: false,
   supportsDryRun: false,
-  permission: { risk: 'read', summary: 'Reads vgai.game.json; no writes.' },
+  permission: { risk: 'read', summary: 'Reads vgai.project.json; no writes.' },
   async impl(_input, ctx) {
     const projectRoot = requireProjectRoot(ctx);
     const path = resolveProjectPath(projectRoot, MANIFEST_FILENAME);
@@ -181,7 +176,7 @@ const ProjectManifestValidateInput = z
     manifest: z
       .unknown()
       .optional()
-      .describe('Validate this raw value instead of re-reading vgai.game.json from disk.'),
+      .describe('Validate this raw value instead of re-reading vgai.project.json from disk.'),
   })
   .describe('Validate the on-disk manifest, or a given candidate document.');
 
@@ -209,7 +204,7 @@ export const projectManifestValidate = defineTool({
   supportsDryRun: false,
   permission: {
     risk: 'read',
-    summary: 'Reads vgai.game.json (or validates a given document); no writes.',
+    summary: 'Reads vgai.project.json (or validates a given document); no writes.',
   },
   async impl(input, ctx) {
     let raw: unknown;
@@ -264,7 +259,7 @@ const ProjectManifestUpdateInput = z
     dryRun: DryRunField,
     baseHash: BaseHashField,
   })
-  .describe('Patch a subset of top-level vgai.game.json fields.');
+  .describe('Patch a subset of top-level vgai.project.json fields.');
 
 const ProjectManifestUpdateResult = mutationResultSchema(
   z
@@ -274,7 +269,7 @@ const ProjectManifestUpdateResult = mutationResultSchema(
 
 export const projectManifestUpdate = defineTool({
   name: 'project.manifest.update',
-  summary: 'Patch name/version/resolution on vgai.game.json, dry-run capable, conflict-checked.',
+  summary: 'Patch name/version/resolution on vgai.project.json, dry-run capable, conflict-checked.',
   description:
     'Merges `patch` onto the raw on-disk manifest, re-validates the FULL merged document through ' +
     'GameManifestSchema (the real schema, cross-field rules included) before ever writing, and ' +
@@ -296,7 +291,7 @@ export const projectManifestUpdate = defineTool({
   host: 'node',
   mutates: true,
   supportsDryRun: true,
-  permission: { risk: 'write', summary: 'Writes vgai.game.json.' },
+  permission: { risk: 'write', summary: 'Writes vgai.project.json.' },
   async impl(input, ctx) {
     const projectRoot = requireProjectRoot(ctx);
     const path = resolveProjectPath(projectRoot, MANIFEST_FILENAME);

package/src/project/shared.ts

@@ -1,11 +1,12 @@
 /**
- * Shared plumbing for B2's `project.*` operations
- * (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B2).
+ * Shared plumbing for B2's `project.*` operations.
  *
  * Every `project.*` op is file-native (host: 'node', requires: { project: true })
  * and runs with NO editor process — it resolves `ctx.projectRoot`, reads/writes
  * plain files on disk, and reuses the engine's existing Zod schemas +
- * `applyDiff` for anything scene-shaped (see `../../../engine/src/scene/scene-apply.ts`).
+ * schemas. (WO-8: this also said it reused the engine's `applyDiff` for anything
+ * scene-shaped — `engine/src/scene/scene-apply.ts` and the twelve
+ * `project.scene.*` ops that used it are deleted with the `.vscn.json` format.)
  *
  * Two cross-cutting decisions (pinned by the B2 task brief) live here so every
  * operation module applies them identically:
@@ -38,7 +39,6 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve, win32 } from 'node:path';
-import type { SceneEntity } from '@vgai/engine/scene/scene-types';
 import { z } from 'zod';
 import { ToolError } from '../errors.js';
 import type { ToolErrorDefinition } from '../registry.js';
@@ -274,41 +274,6 @@ export function mutationResultSchema<T extends z.ZodType>(afterSchema: T) {
   });
 }
 
-// ---------------------------------------------------------------------------
-// Scene entity tree walk (read-side helper shared by entity/component ops)
-// ---------------------------------------------------------------------------
-
-export const ENTITY_NOT_FOUND_ERROR: ToolErrorDefinition = {
-  code: 'ENTITY_NOT_FOUND',
-  summary: 'No entity with the given id exists in the scene.',
-  data: z.object({ id: z.string() }),
-};
-
-/** Depth-first search for an entity by its stable `id` — the SAME identity `applyDiff` addresses by (never an array index). */
-export function findEntityById(entities: SceneEntity[], id: string): SceneEntity | undefined {
-  for (const e of entities) {
-    if (e.id === id) return e;
-    if (e.children) {
-      const found = findEntityById(e.children, id);
-      if (found) return found;
-    }
-  }
-  return undefined;
-}
-
-/** Require an entity by id, throwing the declared `ENTITY_NOT_FOUND` shape otherwise. */
-export function requireEntityById(entities: SceneEntity[], id: string): SceneEntity {
-  const found = findEntityById(entities, id);
-  if (!found) {
-    throw new ToolError(
-      'ENTITY_NOT_FOUND',
-      `No entity with id "${id}" exists in this scene.`,
-      { id },
-    );
-  }
-  return found;
-}
-
 // ---------------------------------------------------------------------------
 // Project-wide file discovery (shared by project.discover / story / theatre /
 // xstate discovery ops — all "find files matching X under the project" ops).

package/src/registry.ts

@@ -137,8 +137,14 @@ export type ToolOutcome<TResult = unknown> =
  *     forwarding unvalidated data).
  *  3. Anything else — an `ToolError` with an undeclared code, a plain
  *     `Error`, or a non-Error throw — normalized into INTERNAL_ERROR. The
- *     raw exception/message is tucked into `data.message`, never used as
- *     the identifying `code`.
+ *     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
+ *     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
+ *     the editor in a browser tab, then retry.") behind whichever surface
+ *     happened to print the whole outcome.
  */
 function normalizeThrown(def: ToolDefinition, err: unknown): StructuredOperationError {
   if (isOperationError(err)) {
@@ -173,7 +179,7 @@ function normalizeThrown(def: ToolDefinition, err: unknown): StructuredOperation
   const message = err instanceof Error ? err.message : String(err);
   return {
     code: CORE_ERROR_CODES.INTERNAL_ERROR,
-    message: `"${def.name}" threw an unstructured exception.`,
+    message: `"${def.name}" failed: ${message}`,
     data: { message },
   };
 }

package/src/render/index.ts

@@ -1,9 +1,8 @@
 /**
  * The render pipeline core (I0/I2-I8, A1) — relocated INTO `@vgai/sdk` so the
- * dependency direction is CLI -> SDK -> engine, never SDK -> CLI (per
- * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md` §3.4: the SDK is the
- * authoritative operation core; CLI/HTTP/MCP are projections on top of it).
- * Formerly `packages/vgai-cli/src/render-cinematic.ts` +
+ * dependency direction is CLI -> SDK -> engine, never SDK -> CLI (the SDK is
+ * the authoritative operation core; CLI/HTTP/MCP are projections on top of
+ * it). Formerly `packages/vgai-cli/src/render-cinematic.ts` +
  * `packages/vgai-cli/src/capabilities/ffmpeg.ts`, imported by the SDK's own
  * `cinematic.*` operations (`../cinematic/`) via a deep-src `@vgai/cli`
  * tsconfig path alias — a package-layering inversion once B6 makes the CLI

package/src/render/render-cinematic.ts

@@ -1,6 +1,5 @@
 /**
- * `vgai render-cinematic` — the I0 crux deliverable
- * (`docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md` §18 "I0 — recording
+ * `vgai render-cinematic` — the I0 crux deliverable ("I0 — recording
  * spike", §15 Workstream I). Produces a REAL, deterministic, playable video
  * file from an authored Theatre-driven cinematic: launches headless
  * Chromium (SwiftShader) against a render-mode page (`?vgai-render=1`,
@@ -81,8 +80,7 @@ export function defaultSimulateCinematicViteConfig(
 export type RenderCinematicFormat = 'mp4' | 'webm' | 'png';
 export type RenderCinematicBackground = 'opaque' | 'transparent';
 /**
- * I6 audio mode (`docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md` §15 I6 +
- * the audio-capture half of §13 G4):
+ * I6 audio mode (+ the audio-capture half of §13 G4):
  *  - `'auto'` (default) — mux audio iff the render page declares a Tone
  *    score (`window.__vgaiRenderAudio.hasAudio === true`,
  *    `@engine/runtime/render-audio-control`); a page with no score renders
@@ -890,19 +888,21 @@ async function readExcludedFromDeterminism(page: Page): Promise<string[]> {
  * the ACTUAL fixed gameplay substep `dt` the harness is using, instead of
  * this pipeline assuming every fixture matches its own `1/60` default. Only
  * called for a `resolved.simulate: true` request (see the call site in
- * {@link renderCinematic}). Returns `undefined` — rather than throwing — for
- * a render-mode page that predates this harness method (back-compat: an
- * older/unmodified real game's own render-mode page might not have it yet);
- * {@link buildSimulateManifest} falls back to the documented `1/60` engine
- * default in that case, with an honest comment, never a silent guess dressed
- * up as a measured value.
+ * {@link renderCinematic}).
+ *
+ * `simulateFixedDt()` is a REQUIRED member of `VgaiRenderHarness` and every
+ * render page is built from this repo, so there is no "older page" case: the
+ * former `typeof === 'function'` probe (and the `?? 1/60` fallback it fed in
+ * {@link buildSimulateManifest}) could only ever have converted a genuinely
+ * broken harness into a plausible-looking guess. Both are deleted — a
+ * missing method now throws where it happens.
  */
-async function readSimulateFixedDt(page: Page): Promise<number | undefined> {
-  return page.evaluate(() => {
-    const harness = (globalThis as unknown as { __vgaiRender: { simulateFixedDt?: () => number } })
-      .__vgaiRender;
-    return typeof harness.simulateFixedDt === 'function' ? harness.simulateFixedDt() : undefined;
-  });
+async function readSimulateFixedDt(page: Page): Promise<number> {
+  return page.evaluate(() =>
+    (
+      globalThis as unknown as { __vgaiRender: { simulateFixedDt(): number } }
+    ).__vgaiRender.simulateFixedDt(),
+  );
 }
 
 /**
@@ -1558,25 +1558,26 @@ async function preparePipelineOutputs(
  * (`RenderControlHarnessOptions.simulateFixedDt`) — silently wrong for any
  * fixture that set a different substep dt. `actualFixedDt` is
  * {@link readSimulateFixedDt}'s result — the REAL value read off the live
- * harness right before the page closed. The `?? 1 / 60` fallback below is
- * ONLY reached for a render-mode page that predates the
- * `simulateFixedDt()` harness method (an older/unmodified page) — an
- * honestly-commented "best known default", not a value ever claimed to be
- * measured.
+ * harness right before the page closed, always measured, never defaulted.
+ * It is `undefined` only for a non-`--simulate` request, where this function
+ * returns `undefined` before reading it.
  */
 function buildSimulateManifest(
   resolved: ResolvedRenderCinematicRequest,
   actualFixedDt: number | undefined,
 ): RenderManifestSimulate | undefined {
   if (!resolved.simulate) return undefined;
+  if (actualFixedDt === undefined) {
+    throw new Error(
+      'renderCinematic: --simulate requested but the render harness reported no ' +
+        'simulateFixedDt() — the page is not a real @engine/runtime/render-control harness.',
+    );
+  }
   return {
     seed: resolved.seed,
     substeps: resolved.simulateSubsteps,
     warmupSubsteps: resolved.simulateWarmupSubsteps,
-    // Honest fallback only: the harness didn't expose `simulateFixedDt()`
-    // (predates I7), so this is the engine-wide documented default
-    // (`render-control.ts`'s own `1/60`), NOT a measured value.
-    fixedTimestep: actualFixedDt ?? 1 / 60,
+    fixedTimestep: actualFixedDt,
   };
 }
 
@@ -1815,9 +1816,7 @@ export async function renderCinematic(
     const excludedFromDeterminism = await readExcludedFromDeterminism(page);
     // I7 fold-in (I5 nit) — the ACTUAL harness dt, read before the page/
     // browser closes, same constraint as the two calls above. `undefined`
-    // for a non-`--simulate` request (never called) or a render-mode page
-    // that predates this harness method (back-compat fallback in
-    // `buildSimulateManifest`).
+    // only for a non-`--simulate` request, where it is never called.
     const actualSimulateFixedDt = resolved.simulate ? await readSimulateFixedDt(page) : undefined;
 
     await page.context().close();

package/src/types.ts

@@ -1,6 +1,5 @@
 /**
- * Shared vocabulary for the operation registry (B1,
- * docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B1 / §5.7 / §3.4).
+ * Shared vocabulary for the operation registry (B1).
  */
 
 /** The four namespaces every operation name must live under (§5.7). */
@@ -53,7 +52,7 @@ export interface ProjectOutputFile {
   path: string;
   content: string | Uint8Array;
   mediaType?: string;
-  role?: 'asset' | 'prefab' | 'provenance' | 'other';
+  role?: 'asset' | 'provenance' | 'other';
 }
 
 /** JSON-safe summary returned after an atomic generated-output transaction. */
@@ -123,5 +122,10 @@ export interface ToolContext {
   signal?: AbortSignal;
   /** Atomic writer for generated project assets (Node project operations). */
   projectOutputs?: ProjectOutputWriter;
+  /** WHICH mounted instance a game-driving tool should address, when the
+   *  editor has several live (multiplayer authoring). A tool that drives the
+   *  game binds `game.instance(ctx.instance)` from it; omitted means the sole
+   *  live instance. */
+  instance?: string;
   [key: string]: unknown;
 }