@vgai/live 0.5.2 → 0.5.4

package/dist/index.d.ts

@@ -1,10 +1,9 @@
 /**
- * `@vgai/live` — `{ editor, game, page, tools }` over the session wire
- * (docs/SHARED-SESSION-SPEC.md, Wave 2). Editor control consolidates HERE
- * from the ~19 `vgai` CLI verbs: a plain node/tsx script gets
- * `import { editor, game, page } from '@vgai/live'` instead of shelling out
- * to the CLI — semantics are discoverable from THIS module's types, not from
- * CLI usage text.
+ * `@vgai/live` — `{ editor, game, page, tools }` over the session wire.
+ * Editor control consolidates HERE from the ~19 `vgai` CLI verbs: a plain
+ * node/tsx script gets `import { editor, game, page } from '@vgai/live'`
+ * instead of shelling out to the CLI — semantics are discoverable from THIS
+ * module's types, not from CLI usage text.
  *
  * `@vgai/live` never starts or stops a session — the CLI keeps that
  * (`create`/`edit`/`sessions`/`close`). `connect()` (and the lazy
@@ -30,22 +29,23 @@
  *
  * `page(step)` = `GameClient.page(step)` (Wave-2's playwright-shim surface,
  * PR #166) — write `step` as a literal `async (page) => {...}` and inline
- * every value it needs. KNOWN WIRE LIMITATION: under the relay transport
- * this binds to (the same one `vgai e2e --in-editor` uses), `step` is
- * shipped to the editor dev server as `step.toString()` and reconstructed
- * there — closures over outer variables do NOT survive that trip. See
- * `@vgai/e2e`'s `bridge-transport.ts` (`runPageScript`'s doc comment) and
- * `relay-transport.ts` for the full honesty-boundary contract this wraps.
+ * 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
+ * trip. See `game-client/bridge-transport.ts` (`runPageScript`'s doc comment)
+ * and `game-client/relay-transport.ts` for the full honesty-boundary contract
+ * this wraps.
  */
-import type { GameClient } from '@vgai/e2e';
 import { LiveEditor } from './editor.js';
+import { type LiveGame } from './game.js';
+import type { GameClient } from './game-client/index.js';
 import { type ResolvedSession, type SessionResolutionDeps } from './session.js';
 import { LiveTools } from './tools.js';
-export type { GameClient } from '@vgai/e2e';
 export type { ActiveDocumentCapture, EditorClient, EditorView, EditorViewDocument, PresentedEditorView, } from '@vgai/editor-sdk';
-export type { ApplyDiffInput, ApplyDiffResult, PanelName } from './editor.js';
+export type { PanelName } from './editor.js';
 export { inferAssetKind, LiveEditor } from './editor.js';
-export { createGameClient } from './game.js';
+export { createGameClient, createLiveGame, type LiveGame } from './game.js';
+export * from './game-client/index.js';
 export type { ProjectSessionHint, ResolvedSession, SessionListingTransport, SessionResolutionDeps, } from './session.js';
 export { findProjectRootFrom, resolveSession } from './session.js';
 export type { LazySession } from './singleton.js';
@@ -53,16 +53,41 @@ export { createLazySession } from './singleton.js';
 export { LiveTools } from './tools.js';
 /** A `game.page(step)`-shaped call — see this module's doc comment for the closure-capture limitation. */
 export type PageStep = GameClient['page'];
-export interface LiveSession {
+export interface LiveSession extends LiveBindings {
+    /** The resolved session this is bound to — useful for logging/debugging which port/project a script attached to. */
+    session: ResolvedSession;
+}
+/** The callable half of a session: everything `vgai eval` binds except `session` itself. */
+export interface LiveBindings {
     editor: LiveEditor;
-    game: GameClient;
+    /** The game client, plus `instances()`/`instance(id)` for addressing one of
+     *  several mounted instances (multiplayer authoring). A bare `game` call
+     *  targets the sole instance and refuses when several are live. */
+    game: LiveGame;
     /** `GameClient.page` bound to `game` — see this module's own doc comment for the wire limitation. */
     page: PageStep;
     /** Registered project callables: enumerate, inspect, and invoke. */
     tools: LiveTools;
-    /** The resolved session this is bound to — useful for logging/debugging which port/project a script attached to. */
-    session: ResolvedSession;
 }
+/**
+ * The SAME `{ editor, game, page, tools }` objects `connect()` returns —
+ * real classes, real instance fields — bound to a port nothing listens on.
+ *
+ * This exists for INTROSPECTION, and specifically for `vgai eval --list`
+ * (`packages/vgai-cli/src/eval-surface.ts`), which must answer "what could I
+ * call?" before `vgai edit` is running. Reading a CLASS instead is what
+ * shipped first, and it silently omitted `game.input` and `game.events`:
+ * those are instance fields the constructor assigns, so they exist on no
+ * prototype and a class walk cannot see them — an agent reading the listing
+ * concluded there was no honest input door. Objects, not classes, is the fix,
+ * and going through `bindTo` is what keeps it honest: the probe is assembled
+ * by the same function `connect()` uses, so a binding added there is listed
+ * here with no second place to remember.
+ *
+ * Awaiting any method on these objects will fail (connection refused). Use
+ * `connect()` for that.
+ */
+export declare function unconnectedBindings(): LiveBindings;
 /**
  * Resolve `projectDir` (default `process.cwd()`) to its live `vgai edit`
  * session and bind `{ editor, game, page }` to it. `deps` is an advanced/
@@ -73,6 +98,6 @@ export declare function connect(projectDir?: string, deps?: SessionResolutionDep
 /** Test-only reset of the lazy top-level singletons' memo — NOT part of the documented public surface (real callers never need to reconnect mid-process). */
 export declare function __resetLiveSingletonForTests(): void;
 export declare const editor: LiveEditor;
-export declare const game: GameClient;
+export declare const game: LiveGame;
 export declare const page: PageStep;
 export declare const tools: LiveTools;

package/dist/index.js

@@ -1,10 +1,9 @@
 /**
- * `@vgai/live` — `{ editor, game, page, tools }` over the session wire
- * (docs/SHARED-SESSION-SPEC.md, Wave 2). Editor control consolidates HERE
- * from the ~19 `vgai` CLI verbs: a plain node/tsx script gets
- * `import { editor, game, page } from '@vgai/live'` instead of shelling out
- * to the CLI — semantics are discoverable from THIS module's types, not from
- * CLI usage text.
+ * `@vgai/live` — `{ editor, game, page, tools }` over the session wire.
+ * Editor control consolidates HERE from the ~19 `vgai` CLI verbs: a plain
+ * node/tsx script gets `import { editor, game, page } from '@vgai/live'`
+ * instead of shelling out to the CLI — semantics are discoverable from THIS
+ * module's types, not from CLI usage text.
  *
  * `@vgai/live` never starts or stops a session — the CLI keeps that
  * (`create`/`edit`/`sessions`/`close`). `connect()` (and the lazy
@@ -30,26 +29,63 @@
  *
  * `page(step)` = `GameClient.page(step)` (Wave-2's playwright-shim surface,
  * PR #166) — write `step` as a literal `async (page) => {...}` and inline
- * every value it needs. KNOWN WIRE LIMITATION: under the relay transport
- * this binds to (the same one `vgai e2e --in-editor` uses), `step` is
- * shipped to the editor dev server as `step.toString()` and reconstructed
- * there — closures over outer variables do NOT survive that trip. See
- * `@vgai/e2e`'s `bridge-transport.ts` (`runPageScript`'s doc comment) and
- * `relay-transport.ts` for the full honesty-boundary contract this wraps.
+ * 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
+ * trip. See `game-client/bridge-transport.ts` (`runPageScript`'s doc comment)
+ * and `game-client/relay-transport.ts` for the full honesty-boundary contract
+ * this wraps.
  */
 import { join } from 'node:path';
 import { EditorClient } from '@vgai/editor-sdk';
 import { LiveEditor } from './editor.js';
-import { createGameClient } from './game.js';
+import { createLiveGame } from './game.js';
 import { lazyChainProxy } from './lazy-proxy.js';
 import { resolveSession } from './session.js';
 import { createLazySession } from './singleton.js';
 import { LiveTools } from './tools.js';
 export { inferAssetKind, LiveEditor } from './editor.js';
-export { createGameClient } from './game.js';
+export { createGameClient, createLiveGame } from './game.js';
+export * from './game-client/index.js';
 export { findProjectRootFrom, resolveSession } from './session.js';
 export { createLazySession } from './singleton.js';
 export { LiveTools } from './tools.js';
+/**
+ * Construct the binding graph for an editor on `port`. Pure — every object
+ * here is built from a URL/port and contacts nothing until a method is
+ * awaited, which is what lets `unconnectedBindings()` below reuse it.
+ */
+function bindTo(port, projectRoot) {
+    const client = new EditorClient({ url: `http://127.0.0.1:${port}` });
+    const editor = new LiveEditor(client);
+    const game = createLiveGame(port, join(projectRoot, '.vgai', 'last-run'));
+    const page = (step) => game.page(step);
+    const tools = new LiveTools(client);
+    return { editor, game, page, tools };
+}
+/**
+ * The SAME `{ editor, game, page, tools }` objects `connect()` returns —
+ * real classes, real instance fields — bound to a port nothing listens on.
+ *
+ * This exists for INTROSPECTION, and specifically for `vgai eval --list`
+ * (`packages/vgai-cli/src/eval-surface.ts`), which must answer "what could I
+ * call?" before `vgai edit` is running. Reading a CLASS instead is what
+ * shipped first, and it silently omitted `game.input` and `game.events`:
+ * those are instance fields the constructor assigns, so they exist on no
+ * prototype and a class walk cannot see them — an agent reading the listing
+ * concluded there was no honest input door. Objects, not classes, is the fix,
+ * and going through `bindTo` is what keeps it honest: the probe is assembled
+ * by the same function `connect()` uses, so a binding added there is listed
+ * here with no second place to remember.
+ *
+ * Awaiting any method on these objects will fail (connection refused). Use
+ * `connect()` for that.
+ */
+export function unconnectedBindings() {
+    return bindTo(UNCONNECTED_PORT, process.cwd());
+}
+/** Port 0 is never a listening editor — an accidental call fails loudly rather than reaching a stranger's server. */
+const UNCONNECTED_PORT = 0;
 /**
  * Resolve `projectDir` (default `process.cwd()`) to its live `vgai edit`
  * session and bind `{ editor, game, page }` to it. `deps` is an advanced/
@@ -58,12 +94,7 @@ export { LiveTools } from './tools.js';
  */
 export async function connect(projectDir, deps) {
     const resolved = await resolveSession(projectDir, deps);
-    const client = new EditorClient({ url: `http://localhost:${resolved.port}` });
-    const editor = new LiveEditor(client, resolved.projectRoot);
-    const game = createGameClient(resolved.port, join(resolved.projectRoot, '.vgai', 'e2e', 'last-run'));
-    const page = (step) => game.page(step);
-    const tools = new LiveTools(client);
-    return { editor, game, page, tools, session: resolved };
+    return { ...bindTo(resolved.port, resolved.projectRoot), session: resolved };
 }
 // ---------------------------------------------------------------------------
 // Lazy top-level singletons (usage form B above) — thin proxies over an

package/dist/session.d.ts

@@ -23,7 +23,7 @@
  *  3. Project-root discovery (`findProjectRootFrom` below) — LIFTED (not
  *     imported) from `packages/vgai-cli/src/project-root.ts`. `@vgai/sdk`'s
  *     `resolveEditorSession` takes an already-known `ctx.projectRoot`; it has
- *     no "walk up from an arbitrary cwd to find the nearest vgai.game.json"
+ *     no "walk up from an arbitrary cwd to find the nearest vgai.project.json"
  *     step of its own, which `connect(projectDir?)` needs. `@vgai/cli` is
  *     `"private": true` with no `exports` field to import through (and
  *     depending on it from here would invert the intended CLI -> SDK ->
@@ -48,7 +48,7 @@ import { type EditorTransport } from '@vgai/sdk';
 /**
  * Lifted verbatim from `packages/vgai-cli/src/project-root.ts` (see this
  * module's doc comment above for why it's duplicated rather than imported).
- * Nearest ancestor of `dir` (inclusive) containing a `vgai.game.json`, or
+ * Nearest ancestor of `dir` (inclusive) containing a `vgai.project.json`, or
  * `null` if none.
  */
 export declare function findProjectRootFrom(dir: string): string | null;
@@ -57,7 +57,7 @@ export type SessionListingTransport = Pick<EditorTransport, 'listSessions'>;
 export interface ResolvedSession {
     /** Editor dev-server port the resolved session is listening on. */
     port: number;
-    /** Absolute project root — the nearest ancestor of the requested directory containing `vgai.game.json`. */
+    /** Absolute project root — the nearest ancestor of the requested directory containing `vgai.project.json`. */
     projectRoot: string;
 }
 export interface SessionResolutionDeps {
@@ -81,6 +81,6 @@ export interface ProjectSessionHint {
  * running `vgai edit` session. Throws a descriptive error (never hangs
  * indefinitely — bounded by `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS`, and never
  * silently attaches to an unrelated project's session — see the module doc
- * above) when no vgai.game.json is found, or no live session covers it.
+ * above) when no vgai.project.json is found, or no live session covers it.
  */
 export declare function resolveSession(projectDir?: string, deps?: SessionResolutionDeps): Promise<ResolvedSession>;

package/dist/session.js

@@ -23,7 +23,7 @@
  *  3. Project-root discovery (`findProjectRootFrom` below) — LIFTED (not
  *     imported) from `packages/vgai-cli/src/project-root.ts`. `@vgai/sdk`'s
  *     `resolveEditorSession` takes an already-known `ctx.projectRoot`; it has
- *     no "walk up from an arbitrary cwd to find the nearest vgai.game.json"
+ *     no "walk up from an arbitrary cwd to find the nearest vgai.project.json"
  *     step of its own, which `connect(projectDir?)` needs. `@vgai/cli` is
  *     `"private": true` with no `exports` field to import through (and
  *     depending on it from here would invert the intended CLI -> SDK ->
@@ -50,13 +50,13 @@ import { EDITOR_SESSION_DISCOVERY_TIMEOUT_MS, HttpEditorTransport, withTimeout,
 /**
  * Lifted verbatim from `packages/vgai-cli/src/project-root.ts` (see this
  * module's doc comment above for why it's duplicated rather than imported).
- * Nearest ancestor of `dir` (inclusive) containing a `vgai.game.json`, or
+ * Nearest ancestor of `dir` (inclusive) containing a `vgai.project.json`, or
  * `null` if none.
  */
 export function findProjectRootFrom(dir) {
     let cur = resolve(dir);
     for (;;) {
-        if (existsSync(join(cur, 'vgai.game.json')))
+        if (existsSync(join(cur, 'vgai.project.json')))
             return cur;
         const parent = dirname(cur);
         if (parent === cur)
@@ -94,7 +94,7 @@ function readProjectSession(projectRoot) {
 }
 async function verifyProjectSession(hint, projectRoot) {
     try {
-        const response = await fetch(`http://localhost:${hint.port}/__editor/project`, {
+        const response = await fetch(`http://127.0.0.1:${hint.port}/__editor/project`, {
             signal: AbortSignal.timeout(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
         });
         if (!response.ok)
@@ -112,14 +112,14 @@ async function verifyProjectSession(hint, projectRoot) {
  * running `vgai edit` session. Throws a descriptive error (never hangs
  * indefinitely — bounded by `EDITOR_SESSION_DISCOVERY_TIMEOUT_MS`, and never
  * silently attaches to an unrelated project's session — see the module doc
- * above) when no vgai.game.json is found, or no live session covers it.
+ * above) when no vgai.project.json is found, or no live session covers it.
  */
 export async function resolveSession(projectDir = process.cwd(), deps = {}) {
     const findRoot = deps.findProjectRootFrom ?? findProjectRootFrom;
     const transport = deps.transport ?? new HttpEditorTransport();
     const projectRoot = findRoot(projectDir);
     if (projectRoot === null) {
-        throw new Error(`@vgai/live: no vgai.game.json found in ${projectDir} or any parent directory — is this a vgai project?`);
+        throw new Error(`@vgai/live: no vgai.project.json found in ${projectDir} or any parent directory — is this a vgai project?`);
     }
     // The editor writes this exact-project hint at boot and removes it on
     // shutdown. Prefer it over a global all-session scan: it is both faster and
@@ -139,7 +139,7 @@ export async function resolveSession(projectDir = process.cwd(), deps = {}) {
         sessions = [];
     }
     const canon = canonicalPath(projectRoot);
-    const match = sessions.find((s) => s.kind !== 'e2e' && s.project !== null && canonicalPath(s.project) === canon);
+    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 ` +

package/dist/tools.d.ts

@@ -1,14 +1,23 @@
 /** Registered project tools over the current shared editor session. */
 import type { EditorClient, ProjectToolCatalog, ProjectToolCatalogEntry, ProjectToolOutcome } from '@vgai/editor-sdk';
 export declare class LiveTools {
-    private readonly client;
+    #private;
     constructor(client: EditorClient);
     /** Enumerate the exact `package.json#vgai.tools` catalog without executing it. */
     list(): Promise<ProjectToolCatalog>;
     /** Return one tool's discoverable metadata, or `null` when it is not registered. */
     describe(name: string): Promise<ProjectToolCatalogEntry | null>;
-    /** Invoke the same validated callable used by the editor and CLI. */
-    call(name: string, input?: unknown, options?: {
+    /**
+     * Invoke the same validated callable used by the editor and CLI.
+     *
+     * `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
+     * `game.instance(ctx.instance)` from it. Omitted is the single-instance case;
+     * the tool then targets the sole live instance, exactly as before.
+     */
+    run(name: string, input?: unknown, options?: {
         confirm?: boolean;
+        instance?: string;
     }): Promise<ProjectToolOutcome>;
 }

package/dist/tools.js

@@ -1,20 +1,29 @@
 /** Registered project tools over the current shared editor session. */
 export class LiveTools {
-    client;
+    /** `#`-private for the same reason `LiveEditor.#client` is. */
+    #client;
     constructor(client) {
-        this.client = client;
+        this.#client = client;
     }
     /** Enumerate the exact `package.json#vgai.tools` catalog without executing it. */
     async list() {
-        return this.client.listProjectTools();
+        return this.#client.listProjectTools();
     }
     /** Return one tool's discoverable metadata, or `null` when it is not registered. */
     async describe(name) {
         const catalog = await this.list();
         return catalog.tools.find((tool) => tool.name === name) ?? null;
     }
-    /** Invoke the same validated callable used by the editor and CLI. */
-    async call(name, input = {}, options = {}) {
-        return this.client.runProjectTool(name, input, options);
+    /**
+     * Invoke the same validated callable used by the editor and CLI.
+     *
+     * `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
+     * `game.instance(ctx.instance)` from it. Omitted is the single-instance case;
+     * the tool then targets the sole live instance, exactly as before.
+     */
+    async run(name, input = {}, options = {}) {
+        return this.#client.runProjectTool(name, input, options);
     }
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/live",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "type": "module",
   "repository": {
     "type": "git",
@@ -30,9 +30,8 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@vgai/editor-sdk": "0.5.2",
-    "@vgai/e2e": "0.5.2",
-    "@vgai/sdk": "0.5.2"
+    "@vgai/editor-sdk": "0.5.4",
+    "@vgai/sdk": "0.5.4"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.58.2 <2"
@@ -41,5 +40,11 @@
     "@playwright/test": "^1.58.2",
     "@types/node": "^25.3.0",
     "typescript": "^5.6.0"
-  }
+  },
+  "description": "Live-session client for VGAI projects: { editor, game, page, tools } over the vgai edit session wire.",
+  "keywords": [
+    "game-engine",
+    "ai-agents",
+    "game-testing"
+  ]
 }