@vgai/sdk 0.4.0-canary.20260715.0

package/src/play/state-operations.ts

@@ -0,0 +1,210 @@
+/**
+ * `play.gameplayState.inspect` / `play.gameplayState.list`
+ * (B4, §8 B4 "gameplay state/test-hook inspection when provided by the game";
+ * implemented for real in Wave 5, docs/SYNTHETIC-PLAYER-SPEC.md §3.5).
+ *
+ * The registration mechanism this file's old HONEST-GAP jsdoc anticipated
+ * now exists: games register named state providers via
+ * `ctx.debug.registerStateProvider(name, fn, { tier? })` (the game-scoped
+ * debug registry, `packages/engine/src/runtime/debug-registry.ts`), the
+ * editor's play mode exposes the registry through `SystemAdapters.debug`,
+ * and `command-listener.ts`'s `inspect-gameplay-state`/`list-gameplay-state`
+ * relay cases read it. `keys` are PROVIDER NAMES (the op name and its
+ * keys-in/`{state}`-out schema are unchanged — registry names are stable).
+ *
+ * Against a STALE editor page (one predating these relay cases) the
+ * transport translates the structured `UNKNOWN_COMMAND_TYPE` marker into
+ * `undefined` and this op throws its declared `GAMEPLAY_STATE_UNSUPPORTED`.
+ * A running game that exposes NO debug adapter answers `{ state: null }` —
+ * the schema's honest "the game exposes none" shape, never a fabricated
+ * snapshot.
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  getPlayTransport,
+  PLAY_READ_TIMEOUT_MS,
+  PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+  type PlayCommandResult,
+  relayErrorMarker,
+  relayStringArray,
+  resolvePlaySession,
+  withPlayTimeout,
+} from './transport.js';
+
+const GAMEPLAY_STATE_UNSUPPORTED_ERROR = {
+  code: 'GAMEPLAY_STATE_UNSUPPORTED',
+  summary:
+    'The connected editor page predates the gameplay-state relay commands (version skew, ' +
+    'matched on the structured UNKNOWN_COMMAND_TYPE marker) — reload the editor tab. ' +
+    'Never fabricated.',
+  data: z.object({}),
+} as const;
+
+const STATE_PROVIDER_NOT_FOUND_ERROR = {
+  code: 'STATE_PROVIDER_NOT_FOUND',
+  summary:
+    'A requested key names no registered state provider. `data.registered` lists every ' +
+    'provider name the running game registered (plus built-ins).',
+  data: z.object({ registered: z.array(z.string()) }),
+} as const;
+
+const COMMAND_FAILED_ERROR = {
+  code: 'COMMAND_FAILED',
+  summary: 'The connected editor rejected or failed to execute the relayed state read.',
+  data: z.object({ message: z.string() }),
+} as const;
+
+/** Map a relayed `ok: false` result onto this file's declared codes. */
+function throwStateRelayFailure(result: PlayCommandResult, label: string): never {
+  const marker = relayErrorMarker(result);
+  if (marker?.code === 'STATE_PROVIDER_NOT_FOUND') {
+    throw new OperationError(
+      'STATE_PROVIDER_NOT_FOUND',
+      result.error ?? 'state provider not found',
+      { registered: relayStringArray(marker.data['registered']) },
+    );
+  }
+  const message = result.error ?? `${label} command failed`;
+  throw new OperationError('COMMAND_FAILED', message, { message });
+}
+
+// ---------------------------------------------------------------------------
+// play.gameplayState.inspect
+// ---------------------------------------------------------------------------
+
+const PlayGameplayStateInspectInput = z.object({
+  keys: z
+    .array(z.string())
+    .optional()
+    .describe(
+      'Optional subset of registered state-provider names to read; omit for the full snapshot ' +
+        'of every provider (stateAll).',
+    ),
+});
+
+const PlayGameplayStateInspectResult = z.object({
+  state: z
+    .record(z.string(), z.unknown())
+    .nullable()
+    .describe('The game-provided state snapshot, or null when the game exposes none.'),
+});
+
+export const playGameplayStateInspect = defineOperation({
+  name: 'play.gameplayState.inspect',
+  summary: 'Inspect game-registered state providers from a running play session.',
+  description:
+    'Reads named state providers a game registered via ctx.debug.registerStateProvider ' +
+    '(docs/SYNTHETIC-PLAYER-SPEC.md §3.1) from the live editor play session, through the ' +
+    'inspect-gameplay-state relay command. `keys` are provider names; omitting them returns ' +
+    'one coherent snapshot of every provider. Returns { state: null } when the running game ' +
+    'exposes no debug adapter; throws GAMEPLAY_STATE_UNSUPPORTED against a stale editor page.',
+  input: PlayGameplayStateInspectInput,
+  result: PlayGameplayStateInspectResult,
+  errors: [
+    PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+    GAMEPLAY_STATE_UNSUPPORTED_ERROR,
+    STATE_PROVIDER_NOT_FOUND_ERROR,
+    COMMAND_FAILED_ERROR,
+  ],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: false,
+  supportsDryRun: false,
+  permission: {
+    risk: 'read',
+    summary: 'Would read game-registered state providers from the live play session.',
+  },
+  async impl(input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    const result = await withPlayTimeout(
+      transport.getGameplayState(session, input.keys, PLAY_READ_TIMEOUT_MS),
+      PLAY_READ_TIMEOUT_MS,
+      'play.gameplayState.inspect',
+    ).catch(() => undefined);
+    if (result === undefined) {
+      throw new OperationError(
+        'GAMEPLAY_STATE_UNSUPPORTED',
+        'The connected editor page predates the gameplay-state relay commands — reload it.',
+        {},
+      );
+    }
+    if (!result.ok) throwStateRelayFailure(result, 'inspect-gameplay-state');
+    const state =
+      (result.data as { state?: Record<string, unknown> | null } | undefined)?.state ?? null;
+    return { state };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// play.gameplayState.list
+// ---------------------------------------------------------------------------
+
+const PlayGameplayStateListResult = z.object({
+  providers: z
+    .array(
+      z.object({
+        name: z.string().describe('Registered provider name (built-ins: time, input.actions).'),
+        tier: z
+          .enum(['observable', 'assisted'])
+          .describe(
+            "Honesty tier (D14): 'observable' state a player could see; 'assisted' X-ray state.",
+          ),
+      }),
+    )
+    .describe('Every registered state provider of the running game, with its honesty tier.'),
+});
+
+export const playGameplayStateList = defineOperation({
+  name: 'play.gameplayState.list',
+  summary: 'List the state providers a running play session registers, with honesty tiers.',
+  description:
+    'Enumerates ctx.debug.registerStateProvider registrations (plus the time/input.actions ' +
+    'built-ins) from the live editor play session via the list-gameplay-state relay command. ' +
+    'A running game with no debug adapter lists an empty array; throws ' +
+    'GAMEPLAY_STATE_UNSUPPORTED against a stale editor page.',
+  input: z.object({}),
+  result: PlayGameplayStateListResult,
+  errors: [
+    PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+    GAMEPLAY_STATE_UNSUPPORTED_ERROR,
+    COMMAND_FAILED_ERROR,
+  ],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: false,
+  supportsDryRun: false,
+  permission: {
+    risk: 'read',
+    summary: "Would list the live play session's registered state providers.",
+  },
+  async impl(_input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    const result = await withPlayTimeout(
+      transport.listGameplayState(session, PLAY_READ_TIMEOUT_MS),
+      PLAY_READ_TIMEOUT_MS,
+      'play.gameplayState.list',
+    ).catch(() => undefined);
+    if (result === undefined) {
+      throw new OperationError(
+        'GAMEPLAY_STATE_UNSUPPORTED',
+        'The connected editor page predates the gameplay-state relay commands — reload it.',
+        {},
+      );
+    }
+    if (!result.ok) throwStateRelayFailure(result, 'list-gameplay-state');
+    const providers =
+      (result.data as { providers?: { name: string; tier: 'observable' | 'assisted' }[] })
+        ?.providers ?? [];
+    return { providers };
+  },
+});
+
+export function registerStateOperations(registry: OperationRegistry): void {
+  registry.register(playGameplayStateInspect);
+  registry.register(playGameplayStateList);
+}

package/src/play/status-operations.ts

@@ -0,0 +1,160 @@
+/**
+ * `play.status` / `play.activeWorld.inspect` (B4, §8 B4 "status and
+ * active-world inspection").
+ *
+ * status.playState is genuinely wired: `GET /__editor/state`'s `playState`
+ * field, populated by `collectState()` (`packages/editor/src/command-listener.ts`)
+ * after every relayed command. `seed`/`deterministic`/`timeScale` are ALL
+ * real (D15/T-D15.6 landed seed/deterministic; timeScale since Wave 5) —
+ * `collectState` reports the live session's `ctx.random.seed`, whether its
+ * manifest declares `determinism.seededRandom`, and the live `GameLoop
+ * .timeScale`; each is `null`/`false` only when no session/Game is running
+ * or a prior `play.seed.set`/`play.timeScale.set` never succeeded.
+ *
+ * `activeWorld.inspect` is a full HONEST GAP: `collectState()` carries no
+ * world id/kind field at all today (only a scalar `entityCount` and the
+ * other UI-state fields already listed in `../editor/transport.ts`'s
+ * jsdoc) — the live wire protocol has nothing to report. A test transport
+ * can supply a real `ActiveWorldInfo`, proving the result schema round-trips
+ * end to end (see `../../test/play-operations.test.ts`).
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  getPlayTransport,
+  PLAY_READ_TIMEOUT_MS,
+  PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+  resolvePlaySession,
+  withPlayTimeout,
+} from './transport.js';
+
+const PLAY_STATUS_UNAVAILABLE_ERROR = {
+  code: 'PLAY_STATUS_UNAVAILABLE',
+  summary: 'A session is connected but did not answer the status read in time.',
+  data: z.object({}),
+} as const;
+
+const ACTIVE_WORLD_UNAVAILABLE_ERROR = {
+  code: 'ACTIVE_WORLD_UNAVAILABLE',
+  summary:
+    'A session is connected, but its wire protocol does not carry active-world data today ' +
+    '(a documented gap, not a fabricated value — see module jsdoc).',
+  data: z.object({}),
+} as const;
+
+// ---------------------------------------------------------------------------
+// play.status
+// ---------------------------------------------------------------------------
+
+const PlayStatusInput = z
+  .object({})
+  .describe('No input — reads current play status from the target editor session.');
+
+const PlayStatusResult = z.object({
+  playState: z.enum(['stopped', 'playing', 'paused']),
+  seed: z
+    .number()
+    .nullable()
+    .describe(
+      "The running session's current ctx.random root seed, or null when no first-party Game " +
+        'is running.',
+    ),
+  deterministic: z
+    .boolean()
+    .describe(
+      'True iff the running project declares determinism.seededRandom (D15) — i.e. ' +
+        'play.seed.set and the gameplay-rng-ban/dev-mode-trap enforcers apply to it.',
+    ),
+  timeScale: z
+    .number()
+    .nullable()
+    .describe('Currently applied simulation time-scale, or null when never successfully set.'),
+});
+
+export const playStatus = defineOperation({
+  name: 'play.status',
+  summary: 'Read the current play-mode status (running/paused/stopped, seed, time-scale).',
+  description:
+    'Resolves a target session then reads its playState/seed/deterministic (real, live — D15/' +
+    'T-D15.6) plus timeScale (null unless a prior play.timeScale.set call actually succeeded — ' +
+    'see control-operations.ts).',
+  input: PlayStatusInput,
+  result: PlayStatusResult,
+  errors: [PLAY_RUNTIME_NOT_AVAILABLE_ERROR, PLAY_STATUS_UNAVAILABLE_ERROR],
+  requires: { editor: true },
+  host: 'runtime-page',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads live play status only.' },
+  async impl(_input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    const status = await withPlayTimeout(
+      transport.getStatus(session, PLAY_READ_TIMEOUT_MS),
+      PLAY_READ_TIMEOUT_MS,
+      'play.status',
+    ).catch(() => undefined);
+    if (!status) {
+      throw new OperationError(
+        'PLAY_STATUS_UNAVAILABLE',
+        'The connected editor session did not answer the status read in time.',
+        {},
+      );
+    }
+    return status;
+  },
+});
+
+// ---------------------------------------------------------------------------
+// play.activeWorld.inspect
+// ---------------------------------------------------------------------------
+
+const PlayActiveWorldInspectInput = z
+  .object({})
+  .describe('No input — inspects the active world of the running play session.');
+
+const PlayActiveWorldInspectResult = z.object({
+  worldId: z.string(),
+  worldKind: z.string(),
+});
+
+export const playActiveWorldInspect = defineOperation({
+  name: 'play.activeWorld.inspect',
+  summary: 'Inspect the active world of a running play session (id/kind).',
+  description:
+    'Real wire protocol has no world data today (see module jsdoc) — always throws the declared ' +
+    'ACTIVE_WORLD_UNAVAILABLE against the real transport; a test transport can supply real data, ' +
+    'proving the result schema round-trips end to end.',
+  input: PlayActiveWorldInspectInput,
+  result: PlayActiveWorldInspectResult,
+  errors: [PLAY_RUNTIME_NOT_AVAILABLE_ERROR, ACTIVE_WORLD_UNAVAILABLE_ERROR],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: false,
+  supportsDryRun: false,
+  permission: { risk: 'read', summary: 'Reads live active-world state only.' },
+  async impl(_input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    const world = await withPlayTimeout(
+      transport.getActiveWorld(session, PLAY_READ_TIMEOUT_MS),
+      PLAY_READ_TIMEOUT_MS,
+      'play.activeWorld.inspect',
+    ).catch(() => undefined);
+    if (!world) {
+      throw new OperationError(
+        'ACTIVE_WORLD_UNAVAILABLE',
+        "The connected editor's wire protocol does not carry active-world data today.",
+        {},
+      );
+    }
+    return world;
+  },
+});
+
+export function registerStatusOperations(registry: OperationRegistry): void {
+  registry.register(playStatus);
+  registry.register(playActiveWorldInspect);
+}