@vgai/sdk 0.5.48 → 0.5.50

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.48",
+  "version": "0.5.50",
   "type": "module",
   "repository": {
     "type": "git",
@@ -21,17 +21,19 @@
     "./build-discipline": "./src/project/build-discipline.ts",
     "./generations": "./src/generations.ts",
     "./mcp-stdio": "./src/mcp/mcp-stdio-server.ts",
+    "./output-roots": "./src/project/output-roots.ts",
     "./project-tool-catalog": "./src/project-tool-catalog.ts",
     "./project-inspection-node": "./src/project/inspection-node.ts",
     "./registry": "./src/registry.ts",
     "./run-name": "./src/project/run-name.ts",
     "./session-journal": "./src/project/session-journal.ts",
     "./tab-census": "./src/project/tab-census.ts",
-    "./tools": "./src/tools.ts"
+    "./tools": "./src/tools.ts",
+    "./provider-execution": "./src/provider-execution.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@vgai/engine": "0.5.48",
+    "@vgai/engine": "0.5.50",
     "playwright": "^1.58.2",
     "zod": "^4.3.6"
   }

package/src/account.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-// Which account backend this session is signed into: the zero-charge in-process mock control plane, or the live VGAI account service. NOT a generation switch — generation execution routes (mock/managed/byok) are chosen per call; see preferredRoute for the UI default.
+// Account identity and billing preference are host configuration, never generation-call inputs.
 export const AccountBackendSchema = z.enum(['mock', 'live']);
 export const AccountPlanSchema = z.object({
   id: z.string().min(1),
@@ -123,7 +123,7 @@ export const AccountSnapshotSchema = z.discriminatedUnion('authenticated', [
 ]);
 /** Product-facing routes. Provider tools may translate BYOK to their native
  * transport name (`direct`) internally. */
-export const GenerationExecutionRouteSchema = z.enum(['mock', 'managed', 'byok']);
+export const GenerationExecutionRouteSchema = z.enum(['auto', 'mock', 'managed', 'byok']);
 export const ProviderCredentialIdSchema = z.enum(['fal', 'tripo', 'worldlabs', 'openrouter']);
 export const CodingInferenceSettingsSchema = z.object({
   enabled: z.boolean(),

package/src/perf/perf-run.ts

@@ -24,7 +24,7 @@
  */
 
 import { join as joinPath } from 'node:path';
-import { type Browser, chromium } from 'playwright';
+import type { Browser } from 'playwright';
 import {
   DEFAULT_ENGINE_ROOT,
   findFreeRenderPort,
@@ -138,7 +138,7 @@ export async function runPerfCapture(request: PerfRunRequest): Promise<PerfRunRe
   const server = await launchEntryServer(entry, port, engineRoot, undefined);
   let browser: Browser | undefined;
   try {
-    browser = await chromium.launch({
+    browser = await (await import('playwright')).chromium.launch({
       headless: true,
       args: ['--use-gl=angle', '--use-angle=swiftshader'],
       // Cancellation/exit is owned by the caller, never Playwright's own

package/src/project/output-roots.ts

@@ -0,0 +1,73 @@
+/**
+ * The project directories a tool may commit generated bytes into, and the one
+ * normalizer every writer validates a path with.
+ *
+ * A project has two of them, and the difference is what SHIPS:
+ *
+ *   - `public/`     — game assets. Exported, served at a root-relative URL,
+ *                     loaded by the game's own source.
+ *   - `references/` — reference material: moodboards, style plates, generated
+ *                     stills and clips an author or an agent looks at while
+ *                     building. Ordinary files, indexed by the editor's Content
+ *                     panel like any other media, and NOT exported — the
+ *                     project's own build copies `publicDir` and nothing else.
+ *
+ * This lives in the SDK rather than beside one writer because the rule has more
+ * than one enforcer: the editor host's atomic project-output writer, and every
+ * registered provider boundary that takes an `outputDirectory` from a caller.
+ * Two copies of "must be under public/" is how a reference output becomes
+ * writable through one door and refused at the next.
+ */
+
+/** The writable output roots, in the order a chooser should offer them. */
+export const PROJECT_OUTPUT_ROOTS = ['public', 'references'] as const;
+
+export type ProjectOutputRoot = (typeof PROJECT_OUTPUT_ROOTS)[number];
+
+/** Human-readable list for an error message: `public/` or `references/`. */
+function rootList(): string {
+  return PROJECT_OUTPUT_ROOTS.map((root) => `${root}/`).join(' or ');
+}
+
+/** POSIX-normalized, `./`-stripped, trailing-slash-stripped. */
+function normalizeSlashes(path: string): string {
+  const slashed = path.replaceAll('\\', '/');
+  const segments: string[] = [];
+  for (const segment of slashed.split('/')) {
+    if (segment === '' || segment === '.') continue;
+    segments.push(segment);
+  }
+  return segments.join('/');
+}
+
+/** The root `path` sits under, or `undefined` when it sits under none. */
+export function projectOutputRootOf(path: string): ProjectOutputRoot | undefined {
+  const normalized = normalizeSlashes(path);
+  return PROJECT_OUTPUT_ROOTS.find(
+    (root) => normalized === root || normalized.startsWith(`${root}/`),
+  );
+}
+
+/**
+ * Validate and normalize a project-relative output path.
+ *
+ * Throws — with a message naming BOTH roots, because the common mistake is
+ * knowing about one of them — for an absolute path, an escape, a bare root
+ * with no file under it, or anything outside the roots above. `subject` names
+ * what is being validated in that message (`Generated output path`, `Fal
+ * outputDirectory`, …).
+ */
+export function normalizeProjectOutputPath(
+  path: string,
+  subject = 'Generated output path',
+): string {
+  const normalized = normalizeSlashes(path);
+  const escapes = normalized.split('/').includes('..');
+  const root = projectOutputRootOf(normalized);
+  if (path.startsWith('/') || escapes || root === undefined || normalized === root) {
+    throw new Error(
+      `${subject} ${JSON.stringify(path)} is invalid; it must be a project-relative path under ${rootList()}.`,
+    );
+  }
+  return normalized;
+}

package/src/project/session-journal.ts

@@ -237,6 +237,12 @@ export type SessionJournalEvent =
     }
   /** The tab said its command listener PICKED THE COMMAND UP. */
   | { readonly kind: 'command-receipt'; readonly requestId8: string }
+  /**
+   * The last tab's connection went away while UNRECEIPTED commands were still
+   * queued, and this many were swept. Receipted ones are deliberately not
+   * counted here — they keep their own work budget.
+   */
+  | { readonly kind: 'command-swept-on-last-tab-gone'; readonly settled: number }
   /** The command settled — by the tab's own answer or by the relay refusing. */
   | {
       readonly kind: 'command-result';
@@ -640,6 +646,8 @@ export function formatJournalLine(line: SessionJournalLine): string {
       return `journal: ${at} command-relayed ${line.command} ${line.requestId8} -> tab ${line.tabId8 ?? 'none'}`;
     case 'command-receipt':
       return `journal: ${at} command-receipt ${line.requestId8}`;
+    case 'command-swept-on-last-tab-gone':
+      return `journal: ${at} command-swept-on-last-tab-gone ${line.settled} unreceipted`;
     case 'command-result':
       return `journal: ${at} command-result ${line.requestId8} ${line.ok ? 'ok' : `FAILED ${line.error ?? ''}`}`;
     case 'command-held':

package/src/provider-execution.ts

@@ -0,0 +1,70 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { GenerationJobDraft } from './generations.js';
+
+export type ProviderExecutionMode = 'direct' | 'managed' | 'mock';
+export type ProviderModeResolver = (
+  provider: string,
+  requestId?: string,
+) => Promise<ProviderExecutionMode>;
+
+const credentialNames: Record<string, string> = {
+  fal: 'FAL_KEY',
+  tripo: 'TRIPO_API_KEY',
+  worldlabs: 'WORLDLABS_API_KEY',
+  openrouter: 'OPENROUTER_API_KEY',
+};
+
+// Project SSR and installed packages can load separate module instances.
+// The host's async context must still be shared, without sharing requests.
+const key = Symbol.for('vgai.provider-execution-context');
+const globals = globalThis as typeof globalThis & {
+  [key]?: AsyncLocalStorage<{
+    resolve: ProviderModeResolver;
+    record?: ((job: GenerationJobDraft) => Promise<void>) | undefined;
+  }>;
+};
+const context = globals[key] ?? new AsyncLocalStorage();
+globals[key] = context;
+
+/** Trusted host configuration. Provider choice and billing never enter tool input. */
+export function withProviderExecution<T>(
+  resolve: ProviderModeResolver,
+  work: () => Promise<T>,
+  record?: (job: GenerationJobDraft) => Promise<void>,
+) {
+  const pending = new Map<string, Promise<ProviderExecutionMode>>();
+  return context.run(
+    {
+      record,
+      resolve: (provider, requestId) => {
+        const key = JSON.stringify([provider, requestId]);
+        let result = pending.get(key);
+        if (!result) {
+          result = resolve(provider, requestId);
+          pending.set(key, result);
+        }
+        return result;
+      },
+    },
+    work,
+  );
+}
+
+/** Native provider clients use the same project ledger as registered tools. */
+export async function recordProviderGeneration(job: GenerationJobDraft): Promise<void> {
+  await context.getStore()?.record?.(job);
+}
+
+/** Library-side connection resolution; callers supply only native provider input. */
+export async function resolveProviderMode(
+  provider: string,
+  requestId?: string,
+): Promise<ProviderExecutionMode> {
+  const resolve = context.getStore()?.resolve;
+  if (resolve) return resolve(provider, requestId);
+  const name = credentialNames[provider];
+  if (!name) throw new Error(`Unknown generation provider ${JSON.stringify(provider)}.`);
+  if (process.env[name]?.trim()) return 'direct';
+  if (process.env['VGAI_GENERATION_GATEWAY'] && process.env['VGAI_ACCESS_TOKEN']) return 'managed';
+  throw new Error(`Connect ${provider} or sign in to VGAI in Account before generating.`);
+}

package/src/render/render-cinematic.ts

@@ -34,7 +34,6 @@ import { tmpdir } from 'node:os';
 import { dirname, join, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { Browser, Page } from 'playwright';
-import { chromium } from 'playwright';
 import { checkFfmpegCapability, type FfmpegCapabilityError } from './capabilities/ffmpeg';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -1539,7 +1538,7 @@ export async function openRenderCinematicPage(
   );
   let browser: Browser | undefined;
   try {
-    browser = await chromium.launch({
+    browser = await (await import('playwright')).chromium.launch({
       headless: true,
       args: ['--use-gl=angle', '--use-angle=swiftshader'],
       // B7 review fold-in (SIGINT race): Playwright's DEFAULT is to install
@@ -1836,7 +1835,7 @@ export async function renderCinematic(
   signal?.addEventListener('abort', onAbort, { once: true });
   try {
     onProgress?.({ phase: 'browser-launch' });
-    browser = await chromium.launch({
+    browser = await (await import('playwright')).chromium.launch({
       headless: true,
       args: ['--use-gl=angle', '--use-angle=swiftshader'],
       // B7 review fold-in (SIGINT race, #10): without this, Playwright