@vgai/sdk 0.5.21 → 0.5.23

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.21",
+  "version": "0.5.23",
   "type": "module",
   "repository": {
     "type": "git",
@@ -26,11 +26,12 @@
     "./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"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@vgai/engine": "0.5.21",
+    "@vgai/engine": "0.5.23",
     "playwright": "^1.58.2",
     "zod": "^4.3.6"
   }

package/src/editor/console-operations.ts

@@ -5,7 +5,7 @@
  * request/response SDK operation cannot itself BE a stream. This describes
  * the real, existing subscription mechanics: the general SSE endpoint
  * (`GET /__editor/events`, broadcasting `editor-command`/`project-changed`/
- * `asset-moved`/`scene-changed`) and the play-mode log persistence pair
+ * `asset-moved`) and the play-mode log persistence pair
  * (`POST /__editor/log-session`, `GET/POST /__editor/log-entries`), plus a
  * live count of currently-buffered log entries as a liveness signal. Editor
  * console messages themselves (`packages/editor/src/editor-console.ts`) are

package/src/editor/open-operations.ts

@@ -1,10 +1,9 @@
 /**
- * `editor.scene.open` / `editor.asset.open` / `editor.story.open`
- * (B3, §8 B3 "open scene/asset/story").
+ * `editor.asset.open` / `editor.story.open`.
  *
- * scene/asset open are genuinely wired end to end: `{type:'open-scene'}` /
- * `{type:'open-asset-tab'}` are existing, already-handled cases in the
- * browser's `handleCommand` switch (`command-listener.ts`).
+ * asset open is genuinely wired end to end: `{type:'open-asset-tab'}` is an
+ * existing, already-handled case in the browser's `handleCommand` switch
+ * (`command-listener.ts`).
  *
  * story open remains an HONEST GAP (see `./transport.ts` module jsdoc), and
  * still does after the B3-followup false-ack fix: the editor has no
@@ -48,14 +47,6 @@ const STORY_OPEN_UNSUPPORTED_ERROR = {
 
 const OkResult = z.object({ ok: z.literal(true) });
 
-// ---------------------------------------------------------------------------
-// WO-8: `editor.scene.open` lived here. It relayed `{type:'open-scene', path}` to
-// a connected editor, and that verb now REJECTS — there is no scene document to
-// open, because the `.vscn.json` format is deleted. A tool whose only relay is a
-// guaranteed rejection is worse than no tool.
-// ---------------------------------------------------------------------------
-
-
 // ---------------------------------------------------------------------------
 // editor.asset.open
 // ---------------------------------------------------------------------------

package/src/editor/session-registry-format.ts

@@ -0,0 +1,218 @@
+/**
+ * `~/.vgai/editor-sessions.json` — the ONE spelling of the editor-session
+ * registry contract, and the shared machinery every reader was hand-copying.
+ *
+ * The registry's WRITE half stays with its owner
+ * (`packages/editor/server/session-registry.ts`); this module owns the
+ * FORMAT: the entry shape, the shape guards, the file path, the
+ * liveness-filtered read, the `/__editor/project` answer parser, and the
+ * deterministic session-selection core. It existed as FOUR drifting copies
+ * (server registry, the CLI, and both vgai-sdk transports) held together by
+ * a "the CLI has no editor dependency" premise that had stopped being true —
+ * and the drift was already real: one copy's `/__editor/project` parser
+ * dropped `manifestError`, reporting a degraded session as belonging to no
+ * project.
+ */
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+/** One registry entry, exactly as the server's write half records it. */
+export interface EditorSessionEntry {
+  /** Canonical project root currently open, or null when none. */
+  project: string | null;
+  port: number;
+  /** PID of the dev-server process. */
+  pid: number;
+  /** ISO timestamp of server start. */
+  startedAt: string;
+  sessionId: string | null;
+  /** Private loopback control credential — never returned by an editor HTTP
+   *  route; exists only in this user-private registry. */
+  controlSecret?: string | null;
+  repositoryId: string | null;
+  worktreeId: string | null;
+  worktreeRoot: string | null;
+  projectRelativePath: string | null;
+  branch: string | null;
+  headCommit: string | null;
+  baseCommit: string | null;
+}
+
+export const EDITOR_SESSIONS_REGISTRY_FILE = join(homedir(), '.vgai', 'editor-sessions.json');
+
+export function isEditorSessionEntry(v: unknown): v is EditorSessionEntry {
+  if (typeof v !== 'object' || v === null) return false;
+  const s = v as Record<string, unknown>;
+  const optionalIdentity = (value: unknown) =>
+    value === undefined || value === null || typeof value === 'string';
+  return (
+    (typeof s['project'] === 'string' || s['project'] === null) &&
+    typeof s['port'] === 'number' &&
+    typeof s['pid'] === 'number' &&
+    typeof s['startedAt'] === 'string' &&
+    optionalIdentity(s['sessionId']) &&
+    optionalIdentity(s['controlSecret']) &&
+    optionalIdentity(s['repositoryId']) &&
+    optionalIdentity(s['worktreeId']) &&
+    optionalIdentity(s['worktreeRoot']) &&
+    optionalIdentity(s['projectRelativePath']) &&
+    optionalIdentity(s['branch']) &&
+    optionalIdentity(s['headCommit']) &&
+    optionalIdentity(s['baseCommit'])
+  );
+}
+
+export function normalizeEditorSessionEntry(session: EditorSessionEntry): EditorSessionEntry {
+  return {
+    ...session,
+    sessionId: session.sessionId ?? null,
+    controlSecret: session.controlSecret ?? null,
+    repositoryId: session.repositoryId ?? null,
+    worktreeId: session.worktreeId ?? null,
+    worktreeRoot: session.worktreeRoot ?? null,
+    projectRelativePath: session.projectRelativePath ?? null,
+    branch: session.branch ?? null,
+    headCommit: session.headCommit ?? null,
+    baseCommit: session.baseCommit ?? null,
+  };
+}
+
+export function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The registry's live entries — shape-validated and PID-liveness-filtered. */
+export function readLiveRegisteredSessions(): EditorSessionEntry[] {
+  try {
+    const raw: unknown = JSON.parse(readFileSync(EDITOR_SESSIONS_REGISTRY_FILE, 'utf8'));
+    return Array.isArray(raw)
+      ? raw
+          .filter(isEditorSessionEntry)
+          .map(normalizeEditorSessionEntry)
+          .filter((s) => pidAlive(s.pid))
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * WHICH PROJECT a `/__editor/project` body says its server is serving.
+ *
+ * `serving` is that server's own statement of "I AM serving this project, I
+ * just cannot describe it" (its manifest is unparseable or fails strict
+ * validation) — added to the route precisely because a bare
+ * `{ project: null }` is indistinguishable from "no project open". Reading
+ * only `project.path` collapses the two, and the cost is that every
+ * project-matched command loses a live session the moment a save breaks its
+ * manifest, reporting it as belonging to no project rather than as this
+ * project's degraded session.
+ */
+export function servedProjectAnswer(body: unknown): {
+  path: string | null;
+  manifestError: string | null;
+} {
+  const b = body as {
+    project?: { path?: string } | null;
+    serving?: { path?: string; error?: string } | null;
+  };
+  return {
+    path: b.project?.path ?? b.serving?.path ?? null,
+    manifestError: b.project ? null : (b.serving?.error ?? null),
+  };
+}
+
+/** Canonical (realpathed when possible) absolute form of a project path. */
+function canonicalizeProjectPath(p: string): string {
+  const absolute = resolve(p);
+  try {
+    return realpathSync(absolute);
+  } catch {
+    return absolute;
+  }
+}
+
+/** Extract the port from an `http(s)://host:port` URL, or undefined if unparseable. */
+function portOfUrl(url: string): number | undefined {
+  try {
+    const port = new URL(url).port;
+    return port ? Number(port) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Deterministic session selection — the ONE precedence order every surface
+ * follows: explicit `ctx.editorUrl` probe > port match against the listing >
+ * `ctx.projectRoot` match > lowest live port > not-running. Generic over the
+ * session shape so the editor and play transports (whose probe results
+ * differ) share the algorithm rather than a copy of it.
+ */
+export async function resolveRegisteredSession<
+  T extends { port: number; project: string | null; url?: string },
+>(
+  ctx: { editorUrl?: string | undefined; projectRoot?: string | undefined },
+  transport: {
+    listSessions(timeoutMs: number): Promise<T[]>;
+    probeSessionUrl?:
+      | ((url: string, timeoutMs: number) => Promise<T | null | undefined>)
+      | undefined;
+  },
+  options: {
+    probeTimeoutMs: number;
+    discoveryTimeoutMs: number;
+    withTimeout: <V>(work: Promise<V>, timeoutMs: number, what: string) => Promise<V>;
+    notRunning: () => never;
+  },
+): Promise<T> {
+  const editorUrl = ctx.editorUrl;
+  if (editorUrl !== undefined && transport.probeSessionUrl) {
+    try {
+      const session = await options.withTimeout(
+        transport.probeSessionUrl(editorUrl, options.probeTimeoutMs),
+        options.probeTimeoutMs,
+        'explicit editor URL probe',
+      );
+      if (session) return session;
+    } catch {}
+    return options.notRunning();
+  }
+
+  let sessions: T[];
+  try {
+    sessions = await options.withTimeout(
+      transport.listSessions(options.discoveryTimeoutMs),
+      options.discoveryTimeoutMs,
+      'editor session discovery',
+    );
+  } catch {
+    return options.notRunning();
+  }
+  if (sessions.length === 0) return options.notRunning();
+
+  if (editorUrl !== undefined) {
+    const port = portOfUrl(editorUrl);
+    const match = sessions.find((s) => s.port === port);
+    if (!match) return options.notRunning();
+    return { ...match, url: editorUrl.replace(/\/+$/, '') };
+  }
+
+  if (ctx.projectRoot !== undefined) {
+    const canon = canonicalizeProjectPath(ctx.projectRoot);
+    const match = sessions.find(
+      (s) => s.project !== null && canonicalizeProjectPath(s.project) === canon,
+    );
+    if (!match) return options.notRunning();
+    return match;
+  }
+
+  return [...sessions].sort((a, b) => a.port - b.port)[0]!;
+}

package/src/editor/transport.ts

@@ -110,13 +110,15 @@
  *    deliberately never exercised in the first place.)
  */
 
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
 import { z } from 'zod';
 import { ToolError } from '../errors.js';
 import type { ToolErrorDefinition } from '../registry.js';
 import type { ToolContext } from '../types.js';
+import {
+  readLiveRegisteredSessions,
+  resolveRegisteredSession,
+  servedProjectAnswer,
+} from './session-registry-format';
 
 // ---------------------------------------------------------------------------
 // Named timeouts (§8 B3 AC: "enforce a named timeout, don't block forever")
@@ -377,74 +379,6 @@ export interface EditorTransport {
 // Real transport
 // ---------------------------------------------------------------------------
 
-interface RegistrySessionEntry {
-  project: string | null;
-  port: number;
-  pid: number;
-  startedAt: string;
-  kind?: string;
-}
-
-function isRegistrySessionEntry(v: unknown): v is RegistrySessionEntry {
-  if (typeof v !== 'object' || v === null) return false;
-  const s = v as Record<string, unknown>;
-  return (
-    (typeof s['project'] === 'string' || s['project'] === null) &&
-    typeof s['port'] === 'number' &&
-    typeof s['pid'] === 'number' &&
-    typeof s['startedAt'] === 'string'
-  );
-}
-
-function pidAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Read `~/.vgai/editor-sessions.json` (the format contract owned by
- * `packages/editor/server/session-registry.ts`), PID-liveness-filtered.
- * Deliberate light duplicate of the read half — see module jsdoc.
- */
-function readRegisteredSessions(): RegistrySessionEntry[] {
-  const registryFile = join(homedir(), '.vgai', 'editor-sessions.json');
-  if (!existsSync(registryFile)) return [];
-  try {
-    const raw: unknown = JSON.parse(readFileSync(registryFile, 'utf8'));
-    return Array.isArray(raw)
-      ? raw.filter(isRegistrySessionEntry).filter((s) => pidAlive(s.pid))
-      : [];
-  } catch {
-    return [];
-  }
-}
-
-/**
- * WHICH PROJECT a `/__editor/project` body says its server is serving.
- *
- * `serving` is that server's own statement of "I AM serving this project, I
- * just cannot describe it" (its manifest is unparseable or fails strict
- * validation) — added to the route precisely because a bare `{ project: null }`
- * is indistinguishable from "no project open". Reading only `project.path`
- * collapses the two, and the cost is that every project-matched command loses
- * a live session the moment a save breaks its manifest, reporting it as
- * belonging to no project rather than as this project's degraded session.
- */
-function servedProjectPath(body: unknown): { path: string | null; manifestError: string | null } {
-  const b = body as {
-    project?: { path?: string } | null;
-    serving?: { path?: string; error?: string } | null;
-  };
-  return {
-    path: b.project?.path ?? b.serving?.path ?? null,
-    manifestError: b.project ? null : (b.serving?.error ?? null),
-  };
-}
-
 async function fetchJson(url: string, timeoutMs: number): Promise<unknown | undefined> {
   try {
     const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
@@ -494,7 +428,7 @@ export class HttpEditorTransport implements EditorTransport {
     const base = editorUrl.replace(/\/+$/, '');
     const body = await fetchJson(`${base}/__editor/project`, timeoutMs);
     if (body === undefined) return undefined;
-    const served = servedProjectPath(body);
+    const served = servedProjectAnswer(body);
     const port = url.port ? Number(url.port) : url.protocol === 'https:' ? 443 : 80;
     return {
       port,
@@ -506,7 +440,7 @@ export class HttpEditorTransport implements EditorTransport {
   }
 
   async listSessions(timeoutMs: number): Promise<EditorSessionInfo[]> {
-    const registered = readRegisteredSessions();
+    const registered = readLiveRegisteredSessions();
     const perProbeTimeout = Math.min(EDITOR_PROBE_TIMEOUT_MS, Math.max(200, timeoutMs));
     const probes = await Promise.all(
       registered.map(async (s) => {
@@ -515,7 +449,7 @@ export class HttpEditorTransport implements EditorTransport {
           perProbeTimeout,
         );
         if (body === undefined) return undefined;
-        const served = servedProjectPath(body);
+        const served = servedProjectAnswer(body);
         const info: EditorSessionInfo = {
           port: s.port,
           project: served.path,
@@ -671,7 +605,7 @@ export class HttpEditorTransport implements EditorTransport {
     if (!body) return undefined;
     return {
       sseUrl: `${baseUrl(session)}/__editor/events`,
-      events: ['editor-command', 'project-changed', 'asset-moved', 'scene-changed'],
+      events: ['editor-command', 'project-changed', 'asset-moved'],
       logEntriesUrl: `${baseUrl(session)}/__editor/log-entries`,
       logSessionUrl: `${baseUrl(session)}/__editor/log-session`,
       bufferedLogCount: Array.isArray(body.entries) ? body.entries.length : 0,
@@ -731,25 +665,6 @@ export const EDITOR_NOT_RUNNING_ERROR: ToolErrorDefinition = {
   data: z.object({ editorUrl: z.string().optional() }),
 };
 
-function canonicalize(p: string): string {
-  const absolute = resolve(p);
-  try {
-    return realpathSync(absolute);
-  } catch {
-    return absolute;
-  }
-}
-
-/** Extract the port from an `http(s)://host:port` URL, or undefined if unparseable. */
-function portOf(url: string): number | undefined {
-  try {
-    const port = new URL(url).port;
-    return port ? Number(port) : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 /**
  * Deterministic session selection (§8 B3 AC: "Session selection is
  * deterministic when multiple editors are running"). Precedence, in order:
@@ -775,52 +690,17 @@ function portOf(url: string): number | undefined {
  */
 export async function resolveEditorSession(
   ctx: ToolContext,
-  transport: EditorTransport,
+  transport: Pick<EditorTransport, 'listSessions' | 'probeSessionUrl'>,
 ): Promise<EditorSessionInfo> {
   const editorUrl = ctx.editorUrl;
-  const notRunning = (): never => {
-    throw new ToolError('EDITOR_NOT_RUNNING', 'No editor connected.', {
-      ...(editorUrl !== undefined ? { editorUrl } : {}),
-    });
-  };
-
-  if (editorUrl !== undefined && transport.probeSessionUrl) {
-    try {
-      const session = await withTimeout(
-        transport.probeSessionUrl(editorUrl, EDITOR_PROBE_TIMEOUT_MS),
-        EDITOR_PROBE_TIMEOUT_MS,
-        'explicit editor URL probe',
-      );
-      if (session) return session;
-    } catch {}
-    return notRunning();
-  }
-
-  let sessions: EditorSessionInfo[];
-  try {
-    sessions = await withTimeout(
-      transport.listSessions(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
-      EDITOR_SESSION_DISCOVERY_TIMEOUT_MS,
-      'editor session discovery',
-    );
-  } catch {
-    return notRunning();
-  }
-  if (sessions.length === 0) return notRunning();
-
-  if (editorUrl !== undefined) {
-    const port = portOf(editorUrl);
-    const match = sessions.find((s) => s.port === port);
-    if (!match) return notRunning();
-    return { ...match, url: editorUrl.replace(/\/+$/, '') };
-  }
-
-  if (ctx.projectRoot !== undefined) {
-    const canon = canonicalize(ctx.projectRoot);
-    const match = sessions.find((s) => s.project !== null && canonicalize(s.project) === canon);
-    if (!match) return notRunning();
-    return match;
-  }
-
-  return [...sessions].sort((a, b) => a.port - b.port)[0]!;
+  return resolveRegisteredSession<EditorSessionInfo>(ctx, transport, {
+    probeTimeoutMs: EDITOR_PROBE_TIMEOUT_MS,
+    discoveryTimeoutMs: EDITOR_SESSION_DISCOVERY_TIMEOUT_MS,
+    withTimeout,
+    notRunning: (): never => {
+      throw new ToolError('EDITOR_NOT_RUNNING', 'No editor connected.', {
+        ...(editorUrl !== undefined ? { editorUrl } : {}),
+      });
+    },
+  });
 }

package/src/generations.ts

@@ -18,67 +18,116 @@ export const GenerationJobStatusSchema = z.enum([
 ]);
 
 export const GenerationBillingSchema = z.discriminatedUnion('route', [
-  z.object({ route: z.literal('mock') }),
-  z.object({
-    route: z.literal('managed'),
-    estimatedCredits: z.number().nonnegative().optional(),
-    settledCredits: z.number().nonnegative().optional(),
-  }),
-  z.object({
-    route: z.literal('byok'),
-    currency: z.literal('USD'),
-    estimatedAmount: z.number().nonnegative().optional(),
-    settledAmount: z.number().nonnegative().optional(),
-  }),
+  z.object({ route: z.literal('mock') }).strict(),
+  z
+    .object({
+      route: z.literal('managed'),
+      estimatedCredits: z.number().nonnegative().optional(),
+      settledCredits: z.number().nonnegative().optional(),
+    })
+    .strict(),
+  z
+    .object({
+      route: z.literal('byok'),
+      currency: z.literal('USD'),
+      estimatedAmount: z.number().nonnegative().optional(),
+      settledAmount: z.number().nonnegative().optional(),
+    })
+    .strict(),
 ]);
 
-const GenerationOperationReferenceSchema = z.object({
-  tool: z.string().min(1),
-  input: z.unknown(),
-});
+const GenerationOperationReferenceSchema = z
+  .object({
+    tool: z.string().min(1),
+    input: z.unknown(),
+  })
+  .strict();
 
-export const GenerationJobSchema = z.object({
-  id: z.string().min(1),
-  provider: z.string().min(1),
-  externalId: z.string().min(1),
-  label: z.string().min(1),
-  operation: z.string().min(1),
-  mode: z.enum(['mock', 'direct', 'managed']),
-  status: GenerationJobStatusSchema,
-  createdAt: z.string().datetime(),
-  updatedAt: z.string().datetime(),
-  progress: z.number().min(0).max(1).optional(),
-  providerStatus: z.string().optional(),
-  queuePosition: z.number().int().nonnegative().optional(),
-  message: z.string().optional(),
-  lastPolledAt: z.string().datetime().optional(),
-  lastProviderChangeAt: z.string().datetime().optional(),
-  pollError: z.string().optional(),
-  pollErrorAt: z.string().datetime().optional(),
-  pollFailureCount: z.number().int().nonnegative().optional(),
-  nextPollAt: z.string().datetime().optional(),
-  billing: GenerationBillingSchema,
-  poll: GenerationOperationReferenceSchema,
-  cancel: GenerationOperationReferenceSchema.optional(),
-  accept: GenerationOperationReferenceSchema.optional(),
-  acceptedAt: z.string().datetime().optional(),
-  /** Last time a human/agent opened the native result. A later provider
-   * update makes the terminal result unread again without changing status. */
-  readAt: z.string().datetime().optional(),
-  provenanceOperationId: z.string().optional(),
-  outputPaths: z.array(z.string()).optional(),
-});
+export const GenerationJobSchema = z
+  .object({
+    id: z.string().min(1),
+    provider: z.string().min(1),
+    externalId: z.string().min(1),
+    label: z.string().min(1),
+    operation: z.string().min(1),
+    mode: z.enum(['mock', 'direct', 'managed']),
+    status: GenerationJobStatusSchema,
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    progress: z.number().min(0).max(1).optional(),
+    providerStatus: z.string().optional(),
+    queuePosition: z.number().int().nonnegative().optional(),
+    message: z.string().optional(),
+    lastPolledAt: z.string().datetime().optional(),
+    lastProviderChangeAt: z.string().datetime().optional(),
+    pollError: z.string().optional(),
+    pollErrorAt: z.string().datetime().optional(),
+    pollFailureCount: z.number().int().nonnegative().optional(),
+    nextPollAt: z.string().datetime().optional(),
+    billing: GenerationBillingSchema,
+    poll: GenerationOperationReferenceSchema,
+    cancel: GenerationOperationReferenceSchema.optional(),
+    accept: GenerationOperationReferenceSchema.optional(),
+    acceptedAt: z.string().datetime().optional(),
+    /** Last time a human/agent opened the native result. A later provider
+     * update makes the terminal result unread again without changing status. */
+    readAt: z.string().datetime().optional(),
+    provenanceOperationId: z.string().optional(),
+    outputPaths: z.array(z.string()).optional(),
+  })
+  .strict();
 
-export const GenerationJobsDocumentSchema = z.object({
-  version: z.literal(1),
-  jobs: z.array(GenerationJobSchema),
-});
+export const GenerationJobsDocumentSchema = z
+  .object({
+    version: z.literal(1),
+    jobs: z.array(GenerationJobSchema),
+  })
+  .strict();
 
 export type GenerationJobStatus = z.infer<typeof GenerationJobStatusSchema>;
 export type GenerationBilling = z.infer<typeof GenerationBillingSchema>;
 export type GenerationJob = z.infer<typeof GenerationJobSchema>;
 export type GenerationJobsDocument = z.infer<typeof GenerationJobsDocumentSchema>;
 
+/** The MANAGED arm of {@link GenerationBilling} — vgai credits, not currency. */
+export type ManagedGenerationBilling = Extract<GenerationBilling, { route: 'managed' }>;
+
+/**
+ * The managed-route billing leg of a provider tool's `toUpdate`, spread-ready.
+ *
+ * Every provider poll tool needs the same three-part decision — is this run on
+ * the managed route at all, did the provider report either credit figure, and
+ * which of the two are present — and Fal, Tripo, World Labs and OpenRouter had
+ * each spelled it out identically, fourteen lines apiece. The conditions are
+ * not obvious enough to retype safely: reporting `route: 'managed'` with both
+ * figures absent claims a charge nobody measured, and writing
+ * `estimatedCredits: undefined` is NOT the same as omitting it under
+ * `exactOptionalPropertyTypes` — it fails the schema rather than leaving the
+ * field unset.
+ *
+ * Call it with the parsed result itself; only the two credit fields are read.
+ *
+ *     ...managedBilling(input.mode, result),
+ */
+export function managedBilling(
+  mode: string,
+  credits: {
+    readonly estimatedCredits?: number | undefined;
+    readonly settledCredits?: number | undefined;
+  },
+): { billing?: ManagedGenerationBilling } {
+  if (mode !== 'managed') return {};
+  const { estimatedCredits, settledCredits } = credits;
+  if (estimatedCredits === undefined && settledCredits === undefined) return {};
+  return {
+    billing: {
+      route: 'managed',
+      ...(estimatedCredits === undefined ? {} : { estimatedCredits }),
+      ...(settledCredits === undefined ? {} : { settledCredits }),
+    },
+  };
+}
+
 export interface GenerationJobDraft {
   provider: string;
   externalId: string;

package/src/play/control-operations.ts

@@ -2,7 +2,7 @@
  * `play.seed.set` / `play.timeScale.set`
  * (B4, §8 B4 "deterministic seed and time-scale control").
  *
- * TIME-SCALE is REAL since Wave 5: the `set-time-scale` relay case
+ * TIME-SCALE is REAL: the `set-time-scale` relay case
  * (`command-listener.ts`) reaches the live session's `GameLoop.timeScale`
  * (`packages/engine/src/core/game-loop.ts`, a live get/set property clamped
  * to `[0, 8]`) through `play-mode.ts`'s `getPlayRuntimeAccess()`, and