@vgai/sdk 0.4.0-canary.20260715.0

package/src/play/debug-command-operations.ts

@@ -0,0 +1,245 @@
+/**
+ * `play.debugCommand.list` / `play.debugCommand.invoke`
+ * (Wave 5, docs/SYNTHETIC-PLAYER-SPEC.md §3.5 — the editor/CLI/MCP door onto
+ * `ctx.debug.registerCommand` registrations).
+ *
+ * Debug commands are FIXTURES, never proofs (D16): they set up state so a
+ * proof can then drive honest input and assert observable state — hence
+ * `invoke` is `mutates: true` / `permission.risk: 'write'`. `list` output
+ * carries each command's `locus` (`'client' | 'server'` — server-locus
+ * commands route through the room's `__vgai:debugCommand` handler and
+ * resolution means server ACK, not replication) and `argsJsonSchema` (the
+ * JSON-Schema projection of the command's declared Zod args tuple, the same
+ * shape the editor's Debug Console renders its invoke form from).
+ *
+ * Wire: relay cases `list-debug-commands`/`invoke-debug-command`
+ * (`command-listener.ts`) against the live session's game-scoped debug
+ * registry (`SystemAdapters.debug`). Against a stale editor page the
+ * transport translates the structured `UNKNOWN_COMMAND_TYPE` marker into
+ * `undefined` and both ops throw the declared `DEBUG_COMMANDS_UNSUPPORTED`.
+ * Registry-side failures arrive as structured `data.code` markers and map
+ * onto this file's declared codes — never by parsing message prose.
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import {
+  getPlayTransport,
+  PLAY_COMMAND_TIMEOUT_MS,
+  PLAY_READ_TIMEOUT_MS,
+  PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+  relayErrorMarker,
+  relayStringArray,
+  resolvePlaySession,
+  withPlayTimeout,
+} from './transport.js';
+
+const DEBUG_COMMANDS_UNSUPPORTED_ERROR = {
+  code: 'DEBUG_COMMANDS_UNSUPPORTED',
+  summary:
+    'The connected editor page predates the debug-command relay commands (version skew, ' +
+    'matched on the structured UNKNOWN_COMMAND_TYPE marker) — reload the editor tab. ' +
+    'Never fabricated.',
+  data: z.object({}),
+} as const;
+
+const DEBUG_COMMAND_NOT_REGISTERED_ERROR = {
+  code: 'DEBUG_COMMAND_NOT_REGISTERED',
+  summary:
+    'No debug command is registered under the requested name. `data.registered` lists every ' +
+    'command name the running game registered.',
+  data: z.object({ registered: z.array(z.string()) }),
+} as const;
+
+const DEBUG_COMMAND_ARGS_INVALID_ERROR = {
+  code: 'DEBUG_COMMAND_ARGS_INVALID',
+  summary:
+    "The provided args failed the command's declared Zod tuple. `data.issues` carries the " +
+    'zod issues.',
+  data: z.object({ issues: z.array(z.unknown()) }),
+} as const;
+
+const DEBUG_COMMAND_FAILED_ERROR = {
+  code: 'DEBUG_COMMAND_FAILED',
+  summary:
+    'The command executed and threw (data.cause), or its server-locus routing failed ' +
+    '(data.reason, e.g. no room connection / server timeout).',
+  data: z.record(z.string(), z.unknown()),
+} as const;
+
+const COMMAND_FAILED_ERROR = {
+  code: 'COMMAND_FAILED',
+  summary: 'The connected editor rejected or failed to execute the relayed command.',
+  data: z.object({ message: z.string() }),
+} as const;
+
+// ---------------------------------------------------------------------------
+// play.debugCommand.list
+// ---------------------------------------------------------------------------
+
+const PlayDebugCommandListResult = z.object({
+  commands: z
+    .array(
+      z.object({
+        name: z.string().describe('Registered command name.'),
+        description: z.string().optional().describe('Author-provided description, when given.'),
+        argsJsonSchema: z
+          .unknown()
+          .optional()
+          .describe("JSON-Schema projection of the command's declared Zod args tuple."),
+        locus: z
+          .enum(['client', 'server'])
+          .describe(
+            "Where the command executes: 'server' routes through the room's __vgai:debugCommand " +
+              'handler (resolution = server ack, not replication).',
+          ),
+      }),
+    )
+    .describe('Every debug command the running game registered, with locus and arg shapes.'),
+});
+
+export const playDebugCommandList = defineOperation({
+  name: 'play.debugCommand.list',
+  summary: 'List the debug commands a running play session registers, with locus and arg shapes.',
+  description:
+    'Enumerates ctx.debug.registerCommand registrations from the live editor play session via ' +
+    'the list-debug-commands relay command. Each entry carries its locus (client/server) and ' +
+    'the JSON-Schema projection of its declared args tuple. A running game with no debug ' +
+    'adapter lists an empty array; throws DEBUG_COMMANDS_UNSUPPORTED against a stale editor page.',
+  input: z.object({}),
+  result: PlayDebugCommandListResult,
+  errors: [
+    PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+    DEBUG_COMMANDS_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 debug commands.",
+  },
+  async impl(_input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    const result = await withPlayTimeout(
+      transport.listDebugCommands(session, PLAY_READ_TIMEOUT_MS),
+      PLAY_READ_TIMEOUT_MS,
+      'play.debugCommand.list',
+    ).catch(() => undefined);
+    if (result === undefined) {
+      throw new OperationError(
+        'DEBUG_COMMANDS_UNSUPPORTED',
+        'The connected editor page predates the debug-command relay commands — reload it.',
+        {},
+      );
+    }
+    if (!result.ok) {
+      const message = result.error ?? 'list-debug-commands command failed';
+      throw new OperationError('COMMAND_FAILED', message, { message });
+    }
+    const commands =
+      (
+        result.data as {
+          commands?: {
+            name: string;
+            description?: string;
+            argsJsonSchema?: unknown;
+            locus: 'client' | 'server';
+          }[];
+        }
+      )?.commands ?? [];
+    return { commands };
+  },
+});
+
+// ---------------------------------------------------------------------------
+// play.debugCommand.invoke
+// ---------------------------------------------------------------------------
+
+const PlayDebugCommandInvokeInput = z.object({
+  name: z.string().describe('Registered debug-command name to invoke.'),
+  args: z
+    .array(z.unknown())
+    .optional()
+    .describe(
+      "Positional args, validated against the command's declared Zod tuple by the registry.",
+    ),
+});
+
+const PlayDebugCommandInvokeResult = z.object({
+  result: z.unknown().describe("The command's return value (JSON-serializable), when any."),
+});
+
+export const playDebugCommandInvoke = defineOperation({
+  name: 'play.debugCommand.invoke',
+  summary: 'Invoke a game-registered debug command in a running play session.',
+  description:
+    'Executes a ctx.debug.registerCommand registration in the live editor play session via the ' +
+    'invoke-debug-command relay command. Debug commands are FIXTURES, never proofs (D16) — ' +
+    'server-locus commands resolve on server ack, so pair them with an observable-state wait ' +
+    'for replicated effects. Registry failures map onto DEBUG_COMMAND_NOT_REGISTERED / ' +
+    'DEBUG_COMMAND_ARGS_INVALID / DEBUG_COMMAND_FAILED; a stale editor page throws ' +
+    'DEBUG_COMMANDS_UNSUPPORTED.',
+  input: PlayDebugCommandInvokeInput,
+  result: PlayDebugCommandInvokeResult,
+  errors: [
+    PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+    DEBUG_COMMANDS_UNSUPPORTED_ERROR,
+    DEBUG_COMMAND_NOT_REGISTERED_ERROR,
+    DEBUG_COMMAND_ARGS_INVALID_ERROR,
+    DEBUG_COMMAND_FAILED_ERROR,
+    COMMAND_FAILED_ERROR,
+  ],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: {
+    risk: 'write',
+    summary: 'Would execute a game-registered debug fixture command in the live play session.',
+  },
+  async impl(input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    const result = await withPlayTimeout(
+      transport.invokeDebugCommand(session, input.name, input.args ?? [], PLAY_COMMAND_TIMEOUT_MS),
+      PLAY_COMMAND_TIMEOUT_MS,
+      'play.debugCommand.invoke',
+    ).catch(() => undefined);
+    if (result === undefined) {
+      throw new OperationError(
+        'DEBUG_COMMANDS_UNSUPPORTED',
+        'The connected editor page predates the debug-command relay commands — reload it.',
+        {},
+      );
+    }
+    if (!result.ok) {
+      const marker = relayErrorMarker(result);
+      const message = result.error ?? 'invoke-debug-command command failed';
+      switch (marker?.code) {
+        case 'DEBUG_COMMAND_NOT_REGISTERED':
+          throw new OperationError('DEBUG_COMMAND_NOT_REGISTERED', message, {
+            registered: relayStringArray(marker.data['registered']),
+          });
+        case 'DEBUG_COMMAND_ARGS_INVALID':
+          throw new OperationError('DEBUG_COMMAND_ARGS_INVALID', message, {
+            issues: Array.isArray(marker.data['issues']) ? marker.data['issues'] : [],
+          });
+        case 'DEBUG_COMMAND_FAILED':
+          throw new OperationError('DEBUG_COMMAND_FAILED', message, marker.data);
+        default:
+          throw new OperationError('COMMAND_FAILED', message, { message });
+      }
+    }
+    return { result: (result.data as { result?: unknown } | undefined)?.result };
+  },
+});
+
+export function registerDebugCommandOperations(registry: OperationRegistry): void {
+  registry.register(playDebugCommandList);
+  registry.register(playDebugCommandInvoke);
+}

package/src/play/index.ts

@@ -0,0 +1,66 @@
+/**
+ * B4 — `play.*` operations
+ * (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §8 B4). Registered
+ * separately from B1's `registerBuiltinOperations` (`../operations.ts`),
+ * B2's `registerProjectOperations` (`../project/index.ts`), and B3's
+ * `registerEditorOperations` (`../editor/index.ts`) — the default
+ * `operations` singleton (`../index.ts`) calls all four.
+ */
+
+export * from './control-operations.js';
+export * from './debug-command-operations.js';
+export * from './input-operations.js';
+export * from './lifecycle-operations.js';
+export * from './log-operations.js';
+export * from './run-ticks-operations.js';
+export * from './state-operations.js';
+export * from './status-operations.js';
+export type {
+  ActiveWorldInfo,
+  InputInjectionKind,
+  InputInjectionRequest,
+  PlayCommandResult,
+  PlayLogFollowMetadata,
+  PlaySessionInfo,
+  PlayState,
+  PlayStatus,
+  PlayTransport,
+  RawPlayLogEntry,
+} from './transport.js';
+export {
+  getPlayTransport,
+  HttpPlayTransport,
+  PLAY_COMMAND_TIMEOUT_MS,
+  PLAY_PROBE_TIMEOUT_MS,
+  PLAY_READ_TIMEOUT_MS,
+  PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+  PLAY_SESSION_DISCOVERY_TIMEOUT_MS,
+  PLAY_START_TIMEOUT_MS,
+  PlayTimeoutError,
+  relayErrorMarker,
+  relayStringArray,
+  resolvePlaySession,
+  withPlayTimeout,
+} from './transport.js';
+
+import type { OperationRegistry } from '../registry.js';
+import { registerControlOperations } from './control-operations.js';
+import { registerDebugCommandOperations } from './debug-command-operations.js';
+import { registerInputOperations } from './input-operations.js';
+import { registerLifecycleOperations } from './lifecycle-operations.js';
+import { registerLogOperations } from './log-operations.js';
+import { registerRunTicksOperations } from './run-ticks-operations.js';
+import { registerStateOperations } from './state-operations.js';
+import { registerStatusOperations } from './status-operations.js';
+
+/** Register every B4 `play.*` operation onto `registry`. */
+export function registerPlayOperations(registry: OperationRegistry): void {
+  registerLifecycleOperations(registry);
+  registerStatusOperations(registry);
+  registerLogOperations(registry);
+  registerInputOperations(registry);
+  registerControlOperations(registry);
+  registerRunTicksOperations(registry);
+  registerStateOperations(registry);
+  registerDebugCommandOperations(registry);
+}

package/src/play/input-operations.ts

@@ -0,0 +1,316 @@
+/**
+ * `play.input.inject` (B4, §8 B4 "input injection through normal input
+ * paths"; wired for real in Wave 5, docs/SYNTHETIC-PLAYER-SPEC.md §3.2/§3.5).
+ *
+ * MUST exercise the NORMAL input action path, never a direct game-state
+ * mutation (§8 B4 AC). Two tiers, both engine-native:
+ *
+ *  - `kind: 'action'` (PRIMARY) — `InputManager.setVirtualAction(action,
+ *    value)`: OR'd/summed into the same action reads humans drive, gated by
+ *    the SAME `inputActive` (focus/enabled) gate as human input. A gated
+ *    actuation surfaces `{delivered: false, reason}` and this op throws the
+ *    declared `INPUT_GATED` — never a false ok. Unknown action names throw
+ *    `INPUT_ACTION_NOT_FOUND` carrying the declared-action list. `atTick`
+ *    (D15/T-D15.5, docs/D15-DETERMINISM-DESIGN.md §2.c) defers the actuation
+ *    to `InputManager.scheduleActionAtTick` instead: applied at the START of
+ *    that tick's input phase, composing with `play.runTicks`/
+ *    `window.__vgai.runTicks` (schedule at tick 500, run 1000 ticks, the
+ *    action fires exactly at 500 — a digital `true` produces a genuine
+ *    `isJustPressed` edge exactly at that tick, not merely a held value). A
+ *    past tick throws the declared `TICK_ALREADY_PASSED` (`data.currentTick`,
+ *    the NEXT tick the target session will service); the result carries
+ *    `scheduled: true` instead of `delivered` (there is no gate outcome to
+ *    report yet — the actuation hasn't happened). CAVEAT: a world that is
+ *    paused/frozen when its target tick would have been serviced (or is
+ *    skipped by a multi-tick gap) silently drops the schedule rather than
+ *    applying it late — the only trace is an `'input.schedule.dropped'`
+ *    debug event (`{tick, action}`), readable via `play.gameplayState
+ *    .inspect`/`play.debugCommand`'s event surface, not through this op.
+ *  - The four legacy named-test-source kinds (`'axis' | 'vector2' |
+ *    'pointerDelta' | 'pointerPosition'`) — `InputManager.injectAxis`/
+ *    `injectVector2`/`injectPointerDelta`/`injectPointerPosition`: push a
+ *    raw value into a NAMED source, read back only by an action bound to a
+ *    `test_*` binding in the project's `.inputmap.json` — the same
+ *    deadzone/normalize/combine aggregation path real devices go through.
+ *    `atTick` does not apply to these (no schedule primitive exists for a
+ *    raw named source).
+ *
+ * Either way there is structurally no way to express "set entity X's field
+ * Y" through this op — an injected value only affects gameplay if a declared
+ * action reads it, exactly like a real device.
+ *
+ * `worldId` (D15/T-D15.5, all kinds — the closed-PR review's objection-2
+ * fix): targets a SPECIFIC world's `InputManager` in a multi-world project.
+ * Omitted, it resolves to the SAME default world `window.__vgai.input.*`
+ * (door a) resolves to — one shared resolution function
+ * (`debug-registry.ts`'s `resolveInputWorldId`), so this op and the debug
+ * bridge can never disagree about which world an unqualified injection
+ * targets. An explicit, unregistered `worldId` throws the declared
+ * `INPUT_WORLD_NOT_FOUND` (`data.registered` lists every world with a wired
+ * `InputManager`).
+ *
+ * Wire: relay case `inject-input` (`command-listener.ts`) reaching the live
+ * session's per-world `InputManager` (via `play-mode.ts`'s
+ * `getPlayRuntimeAccess().getInputTarget(worldId?)`, itself backed by
+ * `DebugRegistry.getVirtualInputTarget`). Against a stale editor page the
+ * transport translates the structured `UNKNOWN_COMMAND_TYPE` marker into
+ * `undefined` and this op throws the declared `INPUT_INJECTION_UNSUPPORTED`.
+ */
+
+import { z } from 'zod';
+import { OperationError } from '../errors.js';
+import { defineOperation, type OperationRegistry } from '../registry.js';
+import type { InputInjectionRequest, PlayCommandResult } from './transport.js';
+import {
+  getPlayTransport,
+  PLAY_COMMAND_TIMEOUT_MS,
+  PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+  relayErrorMarker,
+  relayStringArray,
+  resolvePlaySession,
+  withPlayTimeout,
+} from './transport.js';
+
+const INPUT_INJECTION_UNSUPPORTED_ERROR = {
+  code: 'INPUT_INJECTION_UNSUPPORTED',
+  summary:
+    'The connected editor page predates the inject-input relay command (version skew, matched ' +
+    'on the structured UNKNOWN_COMMAND_TYPE marker) — reload the editor tab. Never silently ' +
+    'reported as success.',
+  data: z.object({}),
+} as const;
+
+const INPUT_ACTION_NOT_FOUND_ERROR = {
+  code: 'INPUT_ACTION_NOT_FOUND',
+  summary:
+    'An action-level injection named an action the game never declared. `data.registered` ' +
+    'lists every declared action name.',
+  data: z.object({ registered: z.array(z.string()) }),
+} as const;
+
+const INPUT_GATED_ERROR = {
+  code: 'INPUT_GATED',
+  summary:
+    'The injection reached the live InputManager but input is gated (page unfocused, Game tab ' +
+    'inactive, or input disabled) — nothing was delivered. The honest {delivered:false} ' +
+    'surface, never a false ok.',
+  data: z.object({ reason: z.string() }),
+} as const;
+
+const TICK_ALREADY_PASSED_ERROR = {
+  code: 'TICK_ALREADY_PASSED',
+  summary:
+    'atTick named a tick the running session already elapsed — scheduling only applies to the ' +
+    'current or a future tick. data.currentTick carries the NEXT tick the session will service.',
+  data: z.object({ currentTick: z.number() }),
+} as const;
+
+const INPUT_WORLD_NOT_FOUND_ERROR = {
+  code: 'INPUT_WORLD_NOT_FOUND',
+  summary:
+    'An explicit worldId named a world with no wired InputManager. data.registered lists every ' +
+    'world id that has one.',
+  data: z.object({ worldId: z.string(), 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 injection command.',
+  data: z.object({ message: z.string() }),
+} as const;
+
+const Vector2Schema = z.object({ x: z.number(), y: z.number() });
+
+const WorldIdField = z
+  .string()
+  .optional()
+  .describe(
+    'D15/T-D15.5 — target a SPECIFIC world (multi-world projects). Omitted resolves to the ' +
+      'same default world window.__vgai.input.* resolves to (one shared resolution function) — ' +
+      'never "whichever world happened to mount last". Throws INPUT_WORLD_NOT_FOUND for an ' +
+      'explicit, unregistered id.',
+  );
+
+const PlayInputInjectInput = z
+  .discriminatedUnion('kind', [
+    z.object({
+      kind: z.literal('action'),
+      action: z
+        .string()
+        .describe(
+          'Declared input-action name to drive at the action level ' +
+            '(InputManager.setVirtualAction) — the honest, focus-gated path.',
+        ),
+      value: z
+        .union([z.boolean(), z.number(), Vector2Schema])
+        .describe(
+          "Value matching the action's declared valueType: boolean holds/releases a digital " +
+            'action, number a scalar, {x,y} a vector2.',
+        ),
+      atTick: z
+        .number()
+        .int()
+        .optional()
+        .describe(
+          "D15/T-D15.5 — if set, defers the actuation to the START of that tick's input phase " +
+            '(InputManager.scheduleActionAtTick) instead of applying it immediately; composes ' +
+            'with play.runTicks/window.__vgai.runTicks. Throws TICK_ALREADY_PASSED for a tick ' +
+            'that already elapsed in the running session.',
+        ),
+      worldId: WorldIdField,
+    }),
+    z.object({
+      kind: z.literal('axis'),
+      sourceId: z.string().describe('Named test-input source id an action binds to (test_axis).'),
+      value: z.number().describe('Raw scalar value (same units InputManager.injectAxis takes).'),
+      worldId: WorldIdField,
+    }),
+    z.object({
+      kind: z.literal('vector2'),
+      sourceId: z
+        .string()
+        .describe('Named test-input source id an action binds to (test_vector2).'),
+      value: Vector2Schema,
+      worldId: WorldIdField,
+    }),
+    z.object({
+      kind: z.literal('pointerDelta'),
+      sourceId: z
+        .string()
+        .describe('Named test-input source id an action binds to (test_pointer_delta).'),
+      value: Vector2Schema,
+      worldId: WorldIdField,
+    }),
+    z.object({
+      kind: z.literal('pointerPosition'),
+      sourceId: z
+        .string()
+        .describe('Named test-input source id an action binds to (test_pointer_position).'),
+      value: Vector2Schema,
+      worldId: WorldIdField,
+    }),
+  ])
+  .describe(
+    'Action-level virtual input (setVirtualAction — primary, optionally scheduled via atTick) ' +
+      'plus the four named-test-source shapes InputManager exposes (injectAxis/injectVector2/' +
+      'injectPointerDelta/injectPointerPosition) — never an arbitrary game-state write. worldId ' +
+      'targets a specific world in a multi-world project.',
+  );
+
+/** Maps a relayed inject-input failure's structured marker onto this op's
+ *  declared error codes — extracted from `impl` below purely to keep that
+ *  function's cognitive complexity under the repo's lint ceiling; the
+ *  mapping itself is a plain lookup with no independent behavior. */
+function throwForInjectFailure(result: PlayCommandResult): never {
+  const marker = relayErrorMarker(result);
+  const message = result.error ?? 'inject-input command failed';
+  if (marker?.code === 'INPUT_ACTION_NOT_FOUND') {
+    throw new OperationError('INPUT_ACTION_NOT_FOUND', message, {
+      registered: relayStringArray(marker.data['registered']),
+    });
+  }
+  if (marker?.code === 'TICK_ALREADY_PASSED') {
+    throw new OperationError('TICK_ALREADY_PASSED', message, {
+      currentTick: typeof marker.data['currentTick'] === 'number' ? marker.data['currentTick'] : 0,
+    });
+  }
+  if (marker?.code === 'DEBUG_INPUT_WORLD_NOT_FOUND') {
+    throw new OperationError('INPUT_WORLD_NOT_FOUND', message, {
+      worldId: typeof marker.data['worldId'] === 'string' ? marker.data['worldId'] : '',
+      registered: relayStringArray(marker.data['registered']),
+    });
+  }
+  throw new OperationError('COMMAND_FAILED', message, { message });
+}
+
+const PlayInputInjectResult = z.object({
+  ok: z.literal(true),
+  scheduled: z
+    .boolean()
+    .optional()
+    .describe(
+      'D15/T-D15.5 — true when atTick deferred the actuation to a future tick instead of ' +
+        'applying it immediately (omitted for an immediate actuation).',
+    ),
+});
+
+export const playInputInject = defineOperation({
+  name: 'play.input.inject',
+  summary: 'Inject synthetic input into a running play session through the normal action path.',
+  description:
+    'Drives a declared action at the action level (setVirtualAction — gated identically to ' +
+    'human input; a gated call throws INPUT_GATED, never a false ok — or, with atTick, ' +
+    'scheduleActionAtTick, deferred to a future tick) or pushes a raw value into a named ' +
+    'InputManager test source (injectAxis family, read back only by a declared test_* ' +
+    'binding). worldId targets a specific world in a multi-world project. Never mutates game ' +
+    'state directly. Throws INPUT_INJECTION_UNSUPPORTED against a stale editor page.',
+  input: PlayInputInjectInput,
+  result: PlayInputInjectResult,
+  errors: [
+    PLAY_RUNTIME_NOT_AVAILABLE_ERROR,
+    INPUT_INJECTION_UNSUPPORTED_ERROR,
+    INPUT_ACTION_NOT_FOUND_ERROR,
+    INPUT_GATED_ERROR,
+    TICK_ALREADY_PASSED_ERROR,
+    INPUT_WORLD_NOT_FOUND_ERROR,
+    COMMAND_FAILED_ERROR,
+  ],
+  requires: { editor: true, play: true },
+  host: 'runtime-page',
+  mutates: true,
+  supportsDryRun: false,
+  permission: {
+    risk: 'write',
+    summary:
+      'Feeds a value into one declared action or named synthetic input source of the live ' +
+      'play session only.',
+  },
+  async impl(input, ctx) {
+    const transport = getPlayTransport(ctx);
+    const session = await resolvePlaySession(ctx, transport);
+    const request: InputInjectionRequest =
+      input.kind === 'action'
+        ? {
+            kind: 'action',
+            action: input.action,
+            value: input.value,
+            ...(input.atTick !== undefined ? { atTick: input.atTick } : {}),
+            ...(input.worldId !== undefined ? { worldId: input.worldId } : {}),
+          }
+        : {
+            kind: input.kind,
+            sourceId: input.sourceId,
+            value: input.value,
+            ...(input.worldId !== undefined ? { worldId: input.worldId } : {}),
+          };
+    const result = await withPlayTimeout(
+      transport.injectInput(session, request, PLAY_COMMAND_TIMEOUT_MS),
+      PLAY_COMMAND_TIMEOUT_MS,
+      'play.input.inject',
+    ).catch(() => undefined);
+    if (!result) {
+      throw new OperationError(
+        'INPUT_INJECTION_UNSUPPORTED',
+        'The connected editor page predates the inject-input relay command — reload it.',
+        {},
+      );
+    }
+    if (!result.ok) {
+      throwForInjectFailure(result);
+    }
+    const outcome = result.data as
+      | { delivered?: boolean; reason?: string; scheduled?: boolean }
+      | undefined;
+    if (outcome?.delivered === false) {
+      const reason = outcome.reason ?? 'input-gated';
+      throw new OperationError('INPUT_GATED', reason, { reason });
+    }
+    return outcome?.scheduled === true
+      ? { ok: true as const, scheduled: true }
+      : { ok: true as const };
+  },
+});
+
+export function registerInputOperations(registry: OperationRegistry): void {
+  registry.register(playInputInject);
+}