@vgai/live 0.5.22 → 0.5.24

package/src/game-client/relay-transport.ts

@@ -102,6 +102,17 @@ export class RelayTransport implements BridgeTransport {
     this.instance = opts.instance;
   }
 
+  /**
+   * Deliberately NOT guarded against a page-fallback answer the way the browser
+   * (`packages/editor/src/editor-server-response.ts`) and the CLI client
+   * (`@vgai/editor-sdk`'s `EditorClient.readJson`) are. Those two can be pointed
+   * at an arbitrary URL — a share tunnel, a static host — where a `200
+   * text/html` for an unserved route is real. This `baseUrl` is
+   * `http://127.0.0.1:<port>` and nothing else, and `session.ts` has already
+   * PROVED that port is this project's editor server (`probeServedProject`, whose
+   * own unparseable-answer path is exactly the refusal): a foreign occupant is
+   * refused there, before any command reaches here.
+   */
   private async postCommand(
     body: Record<string, unknown>,
     timeoutMs: number,
@@ -176,7 +187,7 @@ export class RelayTransport implements BridgeTransport {
    *
    * It runs on every leg, not just `call('snapshot')`, because that is where
    * the measured gap was: a bot that drives the game with `hold`/`command` and
-   * reads through them — the shape `npm run playtest` actually has — could run
+   * reads through them could run
    * its entire session against a backgrounded tab and never be told, so a
    * later failure read as a generic relay timeout instead of "your tab is
    * hidden". Returns whether the tab is hidden so `call` can decide whether to
@@ -189,7 +200,14 @@ export class RelayTransport implements BridgeTransport {
       // P21: what was measured, and what this run is doing about it — not a
       // claim about where the tab is. The reading is a `presence` snapshot
       // (`isHidden` below), which ages between the tab's own reports.
-      process.stdout.write(
+      // STDERR, not stdout. `vgai status` and every other `--json`-shaped verb
+      // put their PAYLOAD on stdout and every banner on stderr; this notice went
+      // to stdout and prepended a prose sentence to the JSON, so any machine
+      // consumer piping `vgai status` into a parser got a SyntaxError the moment
+      // the tab happened to be hidden — measured while reading the coverage
+      // table on a backgrounded session. A diagnostic that breaks the payload it
+      // annotates is worse than no diagnostic.
+      process.stderr.write(
         'vgai: the editor page last REPORTED document.visibilityState "hidden" — the engine ' +
           'stops its loop while the page reports itself hidden, so this run drives ' +
           'deterministic runTicks through the session relay instead of wall clock. Sim time ' +
@@ -302,7 +320,7 @@ export class RelayTransport implements BridgeTransport {
   }
 
   /**
-   * Wave-2: ships `src` (`step.toString()`) to the editor dev server's
+   * Ships `src` (`step.toString()`) to the editor dev server's
    * `page-script` op — a STANDALONE relay command (like `bridge-screenshot`
    * above), not a `bridge-call` method (see `command-listener.ts`'s
    * `handlePageScript` doc comment for why). `step` itself is unused on this
@@ -327,6 +345,31 @@ export class RelayTransport implements BridgeTransport {
     }
   }
 
+  /** THE MODULE LANE over the relay — same wire shape as `page-script`. */
+  async runGameScript(
+    src: string,
+    _step: (scope: unknown) => unknown,
+    instance?: string,
+  ): Promise<BridgeCallOutcome> {
+    try {
+      const body = await this.postCommand(
+        { type: 'game-eval', src, ...(instance === undefined ? {} : { instance }) },
+        PAGE_SCRIPT_TIMEOUT_MS,
+      );
+      return this.toBridgeOutcome(body);
+    } catch (err) {
+      return {
+        ok: false,
+        error: {
+          code: 'RELAY_UNREACHABLE',
+          message:
+            `vgai: could not reach the editor dev server relay at ${this.baseUrl} — ` +
+            `${err instanceof Error ? err.message : String(err)}`,
+        },
+      };
+    }
+  }
+
   /**
    * P20 — order the tab to reload, then wait for EVIDENCE that it came back.
    *

package/src/game-client/types.ts

@@ -45,22 +45,22 @@ export interface DebugBridgeInput {
   setVirtualAction(action: string, value: VirtualActionValue): VirtualActionResult;
   tapVirtualAction(action: string): VirtualActionResult;
   clearVirtualActions(): void;
-  /** D15/T-D15.5 — schedule a virtual actuation for a specific tick, applied
-   *  at the start of that tick's input phase. Declared here (Wave-2
-   *  bridge↔wire coverage-parity gate) for type-shape completeness with
+  /** Schedule a virtual actuation for a specific tick, applied
+   *  at the start of that tick's input phase. Declared here for the
+   *  bridge↔wire coverage-parity gate — type-shape completeness with
    *  `runtime/debug-bridge.ts`'s `VgaiDebugInputHandle` — this package still
    *  exposes no client-side convenience wrapper around it (deliberately
    *  parked; see `GameInput` in `client.ts`), this is pure type-shape
    *  mirroring. */
   scheduleActionAtTick(tick: number, action: string, value: VirtualActionValue): void;
-  /** Wave-2 pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
+  /** Pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
    *  `VgaiDebugInputHandle.injectPointerDelta`: accumulates a synthetic
    *  pointer delta for a named test source (sums within a frame, clears each
    *  frame). Declared here for type-shape completeness with the bridge, same
    *  precedent as `scheduleActionAtTick` above — no client-side convenience
    *  wrapper in `client.ts` (deliberately parked). */
   injectPointerDelta(sourceId: string, delta: { x: number; y: number }): void;
-  /** Wave-2 pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
+  /** Pointer-dispatch op — mirrors `runtime/debug-bridge.ts`'s
    *  `VgaiDebugInputHandle.injectPointerPosition`: sets a synthetic absolute
    *  pointer position for a named test source (last-write-wins, persists
    *  until changed). Same type-shape-only precedent as `scheduleActionAtTick`. */

package/src/game-client/wait-for.ts

@@ -168,7 +168,7 @@ export interface WaitForClock {
 }
 
 // ---------------------------------------------------------------------------
-// Fixture heartbeat (Wave-6 findings ledger: "Watchdog sim-awareness / fixture
+// Fixture heartbeat ("Watchdog sim-awareness / fixture
 // heartbeat for long silent tests" — Session C hit exit-5 on the runner's
 // 2x90s stdout-liveness watchdog during a legitimately silent 5-minute test).
 //
@@ -179,7 +179,7 @@ export interface WaitForClock {
 // advancing test can never false-wedge regardless of duration, no matter how
 // long a single `simSeconds` budget runs.
 //
-// INVARIANT (tested below and in fixture.test.ts): a heartbeat requires BOTH
+// INVARIANT (tested below): a heartbeat requires BOTH
 // (a) >= HEARTBEAT_INTERVAL_MS of wall time since the last heartbeat, AND
 // (b) the tick has ADVANCED since the last heartbeat (not merely since the
 // last poll). Without (b), the poll loop itself — which keeps running

package/src/game.ts

@@ -22,7 +22,7 @@ import { GameClient, RelayTransport } from './game-client/index.js';
 /** A `GameClient` addressing ONE mounted instance, tagged with the mount `id`
  *  it drives. `id` is the whole point of the handle to a CALLER: it is what
  *  `tools.run(name, args, { instance: handle.id })` passes to scope a
- *  node-hosted tool (e.g. `project.autoplay`) to this seat — the two-seat
+ *  node-hosted tool to this seat — the two-seat
  *  multiplayer verification pattern. Without it the caller has a client it can
  *  drive but no id to hand a tool, so the seat-scoped path silently degrades to
  *  the sole-instance one. */

package/src/index.ts

@@ -34,8 +34,8 @@
  * and driven through the product. It is scoped to the ACTIVE document and
  * refuses anything outside it by name (`editor-document.ts`).
  *
- * `page(step)` = `GameClient.page(step)` (Wave-2's playwright-shim surface,
- * PR #166) — write `step` as a literal `async (page) => {...}` and inline
+ * `page(step)` = `GameClient.page(step)`, the playwright-shim surface —
+ * write `step` as a literal `async (page) => {...}` and inline
  * every value it needs. KNOWN WIRE LIMITATION: under the relay transport this
  * binds to, `step` is shipped to the editor dev server as `step.toString()`
  * and reconstructed there — closures over outer variables do NOT survive that

package/src/recording.ts

@@ -54,17 +54,10 @@ export class LiveGameplayRecording {
       await copyFile(capture.path, path);
     }
     return {
+      ...capture,
+      // The caller's `destination` copy, when there was one — otherwise the
+      // project path the recorder wrote. Spread first so this wins.
       path,
-      startedAt: capture.startedAt,
-      mimeType: capture.mimeType,
-      width: capture.width,
-      height: capture.height,
-      fps: capture.fps,
-      audio: capture.audio,
-      durationMs: capture.durationMs,
-      droppedFrames: capture.droppedFrames,
-      frameErrors: capture.frameErrors,
-      layers: capture.layers,
     };
   }
 }

package/src/session.ts

@@ -54,6 +54,7 @@ import {
   HttpEditorTransport,
   withTimeout,
 } from '@vgai/sdk';
+import { servedProjectAnswer } from '../../vgai-sdk/src/editor/session-registry-format';
 
 /**
  * Lifted verbatim from `packages/vgai-cli/src/project-root.ts` (see this
@@ -144,16 +145,6 @@ function readProjectSession(projectRoot: string): ProjectSessionHint | null {
  * but none open this project)" — sending the operator to start an editor that
  * was already running, with the real defect (their own manifest) never named.
  */
-function servedProject(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),
-  };
-}
 
 /**
  * What the server on `port` says it serves — `undefined` when it did not
@@ -168,7 +159,7 @@ async function probeServedProject(
       signal: AbortSignal.timeout(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
     });
     if (!response.ok) return undefined;
-    return servedProject(await response.json());
+    return servedProjectAnswer(await response.json());
   } catch {
     return undefined;
   }
@@ -200,6 +191,62 @@ function manifestRefusal(projectRoot: string, manifestError: string): Error {
  * silently attaches to an unrelated project's session — see the module doc
  * above) when no vgai.project.json is found, or no live session covers it.
  */
+/**
+ * THE REFUSAL WHEN NOTHING MATCHED — and it says WHICH nothing.
+ *
+ * "No live editor session found … run `vgai edit`" used to be the answer to
+ * four different states, only one of which it described. The other three sent
+ * the operator to start an editor that was already running:
+ *
+ *  - discovery FAILED (a probe timeout under load) — nothing was learned, so
+ *    "no session is running" is not a fact anyone established;
+ *  - the registry was read and is genuinely empty — the one case the old text
+ *    was right about;
+ *  - sessions exist, but every one resolves to a different canonical path. In
+ *    a repo worked through git worktrees this is the ORDINARY miss: two
+ *    checkouts of the same project differ only in a path prefix, and a
+ *    symlinked worktree's `realpath` diverges from the path the caller typed.
+ *    Naming both sides is what makes it a two-second diagnosis instead of a
+ *    hunt.
+ *
+ * Each branch prescribes only what its own state supports.
+ */
+function noMatchingSessionRefusal(
+  projectRoot: string,
+  canon: string,
+  sessions: readonly EditorSessionInfo[],
+  discoveryFailure: string | null,
+): Error {
+  if (discoveryFailure !== null) {
+    return new Error(
+      `@vgai/live: could not READ the editor session registry while looking for ${projectRoot} — ` +
+        `${discoveryFailure}. This is not the answer "no editor is running": the question went ` +
+        'unanswered, so nothing is known about what is live. Retry (a probe can time out while ' +
+        'the box is loaded); if it keeps failing, `vgai sessions` asks the same question directly.',
+    );
+  }
+  if (sessions.length === 0) {
+    return new Error(
+      `@vgai/live: the editor session registry is readable and lists NO live sessions, so none ` +
+        `covers ${projectRoot}. @vgai/live only attaches to an already-running session — it ` +
+        'never starts one — so run `vgai edit` in that project first, then retry.',
+    );
+  }
+  const listed = sessions
+    .map((s) => `    port ${s.port} → ${s.project === null ? '(no project)' : s.project}`)
+    .join('\n');
+  return new Error(
+    `@vgai/live: ${sessions.length} live editor session(s) are running, but none of them opens ` +
+      `${projectRoot}. @vgai/live never silently attaches to a different project.\n` +
+      `  looking for (resolved): ${canon}\n` +
+      `  live sessions:\n${listed}\n` +
+      '  If one of those is meant to be this project, the two paths differ after resolution — ' +
+      'the usual cause is a git worktree or a symlink, where the session was opened through a ' +
+      'different path to the same files. Run `vgai edit` from THIS path, or use the path the ' +
+      'session lists.',
+  );
+}
+
 export async function resolveSession(
   projectDir: string = process.cwd(),
   deps: SessionResolutionDeps = {},
@@ -239,30 +286,26 @@ export async function resolveSession(
   }
 
   let sessions: EditorSessionInfo[];
+  // A FAILED discovery is not an empty one. Collapsing the two into `[]` is
+  // what made this door answer "no live editor session found" — and prescribe
+  // `vgai edit` — for a probe that merely timed out under load, sending the
+  // operator to start an editor that was already running while the real defect
+  // went unnamed. The same collapse the manifest refusal above was added for.
+  let discoveryFailure: string | null = null;
   try {
     sessions = await withTimeout(
       transport.listSessions(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
       EDITOR_SESSION_DISCOVERY_TIMEOUT_MS,
       'editor session discovery',
     );
-  } catch {
+  } catch (err) {
     sessions = [];
+    discoveryFailure = err instanceof Error ? err.message : String(err);
   }
 
   const canon = canonicalPath(projectRoot);
   const match = sessions.find((s) => s.project !== null && canonicalPath(s.project) === canon);
-  if (!match) {
-    const otherCount = sessions.length;
-    throw new Error(
-      `@vgai/live: no live editor session found for ${projectRoot}. @vgai/live only attaches to ` +
-        'an already-running session — it never starts one — so run `vgai edit` in that project ' +
-        'first, then retry.' +
-        (otherCount > 0
-          ? ` (${otherCount} other live session(s) found, but none open this project — @vgai/live ` +
-            'never silently attaches to a different project.)'
-          : ''),
-    );
-  }
+  if (!match) throw noMatchingSessionRefusal(projectRoot, canon, sessions, discoveryFailure);
 
   if (match.manifestError != null) throw manifestRefusal(projectRoot, match.manifestError);
 

package/src/tools.ts

@@ -31,7 +31,7 @@ export class LiveTools {
    *
    * `instance` names WHICH mounted instance the tool should drive when several
    * are live (multiplayer authoring) — it reaches the tool as `ctx.instance`,
-   * and a tool that drives the game (e.g. `project.autoplay`) binds
+   * and a tool that drives the game binds
    * `game.instance(ctx.instance)` from it. Omitted is the single-instance case;
    * the tool then targets the sole live instance, exactly as before.
    */