@vgai/editor-sdk 0.5.4 → 0.5.6

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/editor-sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "type": "module",
   "repository": {
     "type": "git",
@@ -22,7 +22,7 @@
   },
   "dependencies": {
     "@types/three": "^0.180.0",
-    "@vgai/sdk": "0.5.4"
+    "@vgai/sdk": "0.5.6"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/client.ts

@@ -51,13 +51,51 @@ const DEFAULT_URL = 'http://127.0.0.1:20173';
  */
 export class EditorCommandError extends Error {
   readonly code: string | undefined;
-  constructor(message: string, code?: string | undefined) {
+  /**
+   * True when the RELAY ended the command itself rather than the editor
+   * answering it — the HTTP 504 that `server/server-utils.ts`'s
+   * `commandResponseFor` gives any `timedOut` result, or this client's own
+   * deadline below.
+   *
+   * Read it as "no answer", not as "the budget expired". `editor-server.ts`
+   * raises `timedOut` for five conditions and only one of them takes the full
+   * budget: the command's timer expiring, the controlling tab's socket dying,
+   * the receipt window closing unanswered, a beating-but-dead tab, and no tab
+   * present at all. The last four can fail in milliseconds.
+   *
+   * A caller that converges by retrying (`vgai restart`) needs the distinction
+   * because a refusal the editor ANSWERED may go differently next time, while
+   * a command the relay abandoned tells you nothing new on a second identical
+   * attempt — and when the abandonment was a 120s budget, re-running it three
+   * times is `restart-readiness.ts`'s 361-seconds-of-silence defect.
+   */
+  readonly timedOut: boolean;
+  constructor(message: string, code?: string | undefined, timedOut = false) {
     super(message);
     this.name = 'EditorCommandError';
     this.code = code;
+    this.timedOut = timedOut;
   }
 }
 
+/**
+ * The client's own ceiling on ONE relayed command.
+ *
+ * A backstop for a LOST server, not a per-command budget: the server already
+ * owns per-type budgets (`server/server-utils.ts`'s `relayCommandTimeoutMs`)
+ * and its timer must always be the one that fires, because its message names
+ * the tab and the remedy while this one can only say "no answer". So this is
+ * deliberately ONE number, comfortably above the longest server budget
+ * (120s, `play`/`capture-story-variants`) rather than a mirror of that table —
+ * a second copy of it would drift silently, and the drift would show up as
+ * this timer winning a race it must always lose.
+ *
+ * Without it a `fetch` with no `AbortSignal` waits on the OS: a dev server
+ * that stops answering mid-command holds the CLI open indefinitely, with no
+ * output and nothing to read.
+ */
+const COMMAND_DEADLINE_MS = 150_000;
+
 /**
  * The GAME DEBUG PLANE, as a contribution's client sees it.
  *
@@ -131,14 +169,36 @@ export class EditorClient {
   private async command<T extends object = Record<string, never>>(
     body: Record<string, unknown>,
   ): Promise<T> {
-    const res = await fetch(`${this.baseUrl}/__editor/command`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(body),
-    });
+    let res: Response;
+    try {
+      res = await fetch(`${this.baseUrl}/__editor/command`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(COMMAND_DEADLINE_MS),
+      });
+    } catch (error) {
+      // Only the deadline is reshaped; a connection refused / DNS failure
+      // still surfaces as itself, because those name their own cause.
+      if ((error as { name?: string } | null)?.name !== 'TimeoutError') throw error;
+      throw new EditorCommandError(
+        `The editor at ${this.baseUrl} never answered "${String(body['type'] ?? 'command')}" ` +
+          `within ${Math.round(COMMAND_DEADLINE_MS / 1000)}s — past every server-side budget, so ` +
+          'the server itself is not answering. Check the terminal running `vgai edit`.',
+        undefined,
+        true,
+      );
+    }
     const data = (await res.json()) as { ok: boolean; error?: string; code?: string } & T;
     if (!data.ok) {
-      throw new EditorCommandError(data.error ?? `Editor command failed: ${res.status}`, data.code);
+      throw new EditorCommandError(
+        data.error ?? `Editor command failed: ${res.status}`,
+        data.code,
+        // 504 is every `timedOut` result (`commandResponseFor`) — the relay
+        // gave up, on any of its five grounds. A 200 body with `ok: false` is
+        // an ANSWER from the editor, however unwelcome. See `timedOut` above.
+        res.status === 504,
+      );
     }
     return data;
   }
@@ -149,9 +209,19 @@ export class EditorClient {
    *  explicit config leg, relayed as `cmd['seed']`; `handleCommand`'s
    *  `'play'` case threads it into `enterPlayMode`'s highest-precedence seed
    *  argument (beats manifest.determinism.defaultSeed/?vgai-seed=). Omitted,
-   *  boot seeding falls back to that precedence unchanged. */
-  async play(opts?: { seed?: number }): Promise<void> {
-    await this.command({ type: 'play', ...(opts?.seed !== undefined ? { seed: opts.seed } : {}) });
+   *  boot seeding falls back to that precedence unchanged.
+   *
+   *  `opts.name` (`vgai play --name <text>`) — an OPTIONAL label for this run,
+   *  relayed as `cmd['name']` and slugified server-side into the run's
+   *  `logs/play-*.jsonl` filename and its session-journal line. Findability
+   *  only: no registry, no uniqueness, no lookup verb — grep and `ls` are the
+   *  query engine. Omitted, the filename keeps its exact unnamed shape. */
+  async play(opts?: { seed?: number; name?: string | null }): Promise<void> {
+    await this.command({
+      type: 'play',
+      ...(opts?.seed !== undefined ? { seed: opts.seed } : {}),
+      ...(opts?.name ? { name: opts.name } : {}),
+    });
   }
 
   /** Dispose the current play session and mount it again from fresh project entry source. */

package/src/types.ts

@@ -356,15 +356,77 @@ export interface EditorState {
   /** Flattened live authoring hierarchy, useful for agent entity discovery. */
   entities?: EditorEntitySummary[];
   /**
-   * Live count of editor browser tabs holding an SSE connection right now.
-   * The rest of this object is the last snapshot a browser POSTed and persists
-   * even after every tab closes — so a `0` here means the other fields are
-   * stale cache and commands (`play`, `scene`, …) will fail with "no editor
-   * connected". Added by the server on every `/__editor/state` read.
+   * How many browser tabs are PRESENT for this session right now, read from
+   * the server's tab table (`server/tab-presence.ts`) rather than from a
+   * socket count — so a tab mid-reload still counts (it is beating), and a
+   * socket with no tab behind it does not.
+   *
+   * The rest of this object is the last snapshot a browser POSTed and
+   * persists even after every tab goes — so a `0` here means the other fields
+   * are stale cache and commands (`play`, `scene`, …) will refuse with the
+   * table's own reason. Added by the server on every `/__editor/state` read.
    */
   editorsConnected?: number;
   /** Convenience: `editorsConnected > 0`. */
   connected?: boolean;
+  /**
+   * ONE ROW PER PRESENT TAB — the whole table, because the owner's rule for
+   * this seam is "if they DO get disconnected, make it clear that it
+   * happened" and a single boolean can never say that.
+   *
+   * `lastBeatAgo` is the heartbeat age (null for a tab that cannot beat, e.g.
+   * one bridged through the share tunnel); a number climbing past a second or
+   * two is a gap in progress. `epochCount` counts page-loads, so a number
+   * that keeps rising is a reload loop. `channel: 'down'` with a fresh beat
+   * is a tab mid-reload — present, and briefly unable to take a command.
+   * `unresponsive` is the zombie: beating, but its page has never opened a
+   * command channel this page-load. Absent against an older server.
+   *
+   * `commandListener` is the standing verdict on the DOCUMENT, and it is a
+   * different question from all of the above: the control channel is opened by
+   * the tiny pre-React entry before any module loads, so a page that dies
+   * during boot beats, holds a channel, gets blessed, and executes nothing. It
+   * reads `'not attached'` for that page, `'silent since <t>'` for one whose
+   * listener stopped acknowledging relayed commands, and `'ready'` otherwise —
+   * each from a timestamp the server already stamps (the listener's own
+   * attach/detach report, and the command receipts). Absent against an older
+   * server, and absent for a tab the server cannot measure.
+   *
+   * `census` is the tab's RESOURCE PROFILE, sampled by the page every five
+   * seconds and carried on the heartbeat: what a browser-level renderer death
+   * would otherwise leave unexplained. `heapUsedMB`/`heapLimitMB` are null off
+   * Chromium (`performance.memory` is non-standard); the renderer counts are
+   * absent, never zero, when no game has registered a render-debug adapter.
+   * `censusAgeMs` says how stale the profile is — a hidden tab is not sampled.
+   */
+  tabs?: Array<{
+    tabId8: string;
+    presentFor: number;
+    lastBeatAgo: number | null;
+    epochCount: number;
+    visibility: 'visible' | 'hidden';
+    route: 'project' | 'no-project' | 'unknown';
+    blessed: boolean;
+    channel: 'open' | 'down';
+    unresponsive: boolean;
+    commandListener?: 'ready' | 'not attached' | (string & {});
+    census?: {
+      heapUsedMB: number | null;
+      heapLimitMB: number | null;
+      canvases: number;
+      canvasMB: number;
+      textures?: number;
+      geometries?: number;
+      programs?: number;
+    } | null;
+    censusAgeMs?: number | null;
+  }>;
+  /**
+   * The auto-open runaway guard. `stopped` means this session opened
+   * `attempts` tabs, none of them ever appeared in the table, and it has
+   * stopped trying — the browser, not the editor, is what to check.
+   */
+  tabAutoOpen?: { attempts: number; stopped: boolean };
   /**
    * Epoch ms when the server last received a state POST from a browser tab —
    * i.e. the age of the cached snapshot above. Omitted if no tab has ever
@@ -412,6 +474,24 @@ export interface EditorState {
    * neighbors above.
    */
   sourceValidation?: 'active' | 'awaiting-src' | 'no-project';
+  /**
+   * The compatibility verdict between this editor and the project it serves —
+   * `null` when they agree, otherwise the refusal the browser renders when it
+   * declines to activate the project, with its recovery guidance.
+   *
+   * Server-computed per read like its neighbors above. It is here because the
+   * gate was previously reported ONLY in the browser: an editor started on an
+   * incompatible project serves happily (it activates nothing), so the tab
+   * showed "This project is pinned to @vgai/engine X, but this editor is
+   * running Y" while `vgai status` reported a connected session with empty
+   * validation and `vgai play` timed out into a retry message about the tab
+   * reloading. An agent drives this editor through the CLI, so a gate visible
+   * only in pixels is invisible by construction.
+   */
+  projectCompatibility?: {
+    error: string;
+    recovery?: { kind: string; title: string; guidance: string; command?: string };
+  } | null;
   /**
    * #124: the absolute path of the project this editor server currently has
    * open — server-computed (never part of the browser-POSTed snapshot,