summer-engine 2.8.1 → 3.0.0

package/dist/core/capabilities/runtime-control.d.ts

@@ -0,0 +1,540 @@
+/**
+ * Runtime control & playtest ops (runtime control) — the "see and touch the
+ * RUNNING game" surface. One copy of the argument contracts, op builders,
+ * client budgets and failure hints, shared by the MCP tools
+ * (src/mcp/tools/runtime-tools.ts) and the CLI dispatcher (`summer tool …`) so
+ * both faces validate the same inputs, send the same op and wait the same
+ * budget.
+ *
+ * Engine contract (frozen): doc/SUMMER/SCENE_SCRIPTING_CONTRACTS.md "Wave I —
+ * Runtime control & playtest ops" + editor/ops/runtime_ops.h. Every op except
+ * ListGameInstances is SINGLE-ONLY and ASYNC (a debugger round-trip needs the
+ * reply channel), requires a RUNNING game, accepts `instance?` (default
+ * "main"), stamps the game frame it describes, rounds floats to 3dp and
+ * serialises math values as Godot literal strings ("Vector3(1, 2, 3)").
+ *
+ * Sixteen engine kinds are grouped into seven tools:
+ *   summer_runtime_set      SetRuntimeProp
+ *   summer_runtime_call     CallRuntimeMethod
+ *   summer_runtime_spawn    SpawnRuntimeScene | FreeRuntimeNode        (action)
+ *   summer_runtime_animate  RuntimeAnimation | RuntimeAnimationTree |
+ *                           GetRuntimeBones                            (target)
+ *   summer_game_control     GamePause | GameStep | GameSpeed |
+ *                           ListGameInstances                          (action)
+ *   summer_game_input       SimulateInputScript | InputRecordStart |
+ *                           InputRecordStop | InputReplay               (action)
+ *   summer_game_probe       GameProbe
+ * plus the instance-aware PlayGame / StopGame variants behind summer_play /
+ * summer_stop.
+ */
+import { z } from "zod";
+import { type CapabilityAdvertisingClient } from "../capability-skew.js";
+/** The fifteen async single-only kinds (RuntimeOps::async_op_kinds). */
+export declare const RUNTIME_ASYNC_OP_KINDS: readonly string[];
+/** All sixteen runtime-control kinds — the fifteen above plus the synchronous
+ *  ListGameInstances read. */
+export declare const RUNTIME_CONTROL_OP_KINDS: readonly string[];
+/** Default editor-side watchdog for a runtime op (_RT_DEFAULT_TIMEOUT_SEC). */
+export declare const RUNTIME_WATCHDOG_DEFAULT_SEC = 10;
+/** Hard cap on any runtime watchdog (_RT_MAX_TIMEOUT_SEC). */
+export declare const RUNTIME_WATCHDOG_MAX_SEC = 20;
+/** GameProbe watchdog: screenshot + PNG -> JPEG decode (_RT_PROBE_TIMEOUT_SEC). */
+export declare const RUNTIME_PROBE_WATCHDOG_SEC = 15;
+/** Offscreen child attach budget before the engine kills it (_RT_ATTACH_TIMEOUT_SEC). */
+export declare const RUNTIME_ATTACH_TIMEOUT_SEC = 15;
+/** The op is staged on the editor's async lane and polled over HTTP; the
+ *  watchdog fires editor-side, so the client always waits longer than it. */
+export declare const RUNTIME_CLIENT_HEADROOM_MS = 15000;
+/** GameStep frames cap (_RT_STEP_MAX_FRAMES). */
+export declare const GAME_STEP_MAX_FRAMES = 600;
+/** SimulateInputScript / InputReplay event cap (_RT_SCRIPT_MAX_EVENTS). */
+export declare const INPUT_SCRIPT_MAX_EVENTS = 1000;
+/** Last-event horizon: 36000 frames = 600 s at 60 fps (_RT_SCRIPT_HORIZON_FRAMES). */
+export declare const INPUT_SCRIPT_HORIZON_FRAMES = 36000;
+/** GameProbe props cap and tree bounds. */
+export declare const GAME_PROBE_MAX_PROPS = 64;
+export declare const GAME_PROBE_MAX_DEPTH = 8;
+export declare const GAME_PROBE_MAX_LIMIT = 4000;
+export declare const GAME_PROBE_MIN_DIM = 16;
+export declare const GAME_PROBE_MAX_DIM = 4096;
+/** Offscreen instance cap (4 debugger sessions total, the run bar's game included). */
+export declare const MAX_OFFSCREEN_INSTANCES = 3;
+/** PlayGame default seed when deterministic and no seed is given (_RT_DEFAULT_SEED). */
+export declare const PLAY_DEFAULT_SEED = 20260725;
+/** Client poll budget for an engine watchdog of `watchdogSec` seconds. */
+export declare function runtimeBudgetMs(watchdogSec: number): number;
+/** Instance-aware PlayGame: the child must attach within 15 s, and a cold
+ *  load of a large project can take 25-40 s on top — same 60 s as /api/play. */
+export declare const PLAY_INSTANCE_TIMEOUT_MS = 60000;
+/** StopGame {instance}: kills a PID — same 15 s budget as /api/stop. */
+export declare const STOP_INSTANCE_TIMEOUT_MS = 15000;
+export declare const RUNTIME_FALLBACKS: Readonly<Record<string, string>>;
+/** Instance-aware PlayGame rides the same engine wave as ListGameInstances;
+ *  an engine that lacks the latter would start the MAIN game and silently
+ *  ignore instance/mode, so the pre-flight keys on this kind. */
+export declare const PLAY_INSTANCE_FALLBACK = "start the main game with summer_play without instance/mode (seed and fixed_fps still apply there) and observe it with summer_screenshot target:'game' or a RunVerification probe \u2014 this engine has no parallel offscreen instances";
+export declare const RUNTIME_FAILURE_HINTS: Readonly<Record<string, string>>;
+/**
+ * Amend a runtime-op envelope with prescriptive recovery text. The structured
+ * failure_reason stays intact for programmatic callers; on a failure only the
+ * model-facing `error` string is taught. A SUCCESSFUL envelope that still
+ * carries a reason (SetRuntimeProp applied:false + not_applied, InputReplay's
+ * advisory nondeterministic_instance) gets a `hint` field instead — the op
+ * did run, so its `error` must not be invented.
+ */
+export declare function withRuntimeFailureHints(result: unknown, extraHints?: Record<string, string>): unknown;
+export interface BuiltRuntimeOp {
+    /** Engine op kind the tool resolved to (for pre-flight, hints and tests). */
+    kind: string;
+    op: Record<string, unknown>;
+    /** Client poll budget — always longer than the engine watchdog. */
+    timeoutMs: number;
+}
+export declare const runtimeSetArgsSchema: z.ZodObject<{
+    path: z.ZodString;
+    property: z.ZodString;
+    value: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    field: z.ZodOptional<z.ZodString>;
+    instance: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    value: string | number | boolean;
+    property: string;
+    instance?: string | undefined;
+    field?: string | undefined;
+}, {
+    path: string;
+    value: string | number | boolean;
+    property: string;
+    instance?: string | undefined;
+    field?: string | undefined;
+}>;
+export type RuntimeSetArgs = z.infer<typeof runtimeSetArgsSchema>;
+export declare function buildRuntimeSetOp(args: RuntimeSetArgs): BuiltRuntimeOp;
+export declare const runtimeCallArgsSchema: z.ZodObject<{
+    path: z.ZodString;
+    method: z.ZodString;
+    args: z.ZodOptional<z.ZodArray<z.ZodUnknown, "many">>;
+    instance: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    method: string;
+    args?: unknown[] | undefined;
+    instance?: string | undefined;
+}, {
+    path: string;
+    method: string;
+    args?: unknown[] | undefined;
+    instance?: string | undefined;
+}>;
+export type RuntimeCallArgs = z.infer<typeof runtimeCallArgsSchema>;
+export declare function buildRuntimeCallOp(args: RuntimeCallArgs): BuiltRuntimeOp;
+export declare const runtimeSpawnArgsSchema: z.ZodObject<{
+    action: z.ZodEnum<["spawn", "free"]>;
+    parent: z.ZodOptional<z.ZodString>;
+    scene: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    path: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<["queue_free", "free"]>>;
+    instance: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: "spawn" | "free";
+    mode?: "free" | "queue_free" | undefined;
+    instance?: string | undefined;
+    scene?: string | undefined;
+    name?: string | undefined;
+    path?: string | undefined;
+    parent?: string | undefined;
+    props?: Record<string, string | number | boolean> | undefined;
+}, {
+    action: "spawn" | "free";
+    mode?: "free" | "queue_free" | undefined;
+    instance?: string | undefined;
+    scene?: string | undefined;
+    name?: string | undefined;
+    path?: string | undefined;
+    parent?: string | undefined;
+    props?: Record<string, string | number | boolean> | undefined;
+}>;
+export type RuntimeSpawnArgs = z.infer<typeof runtimeSpawnArgsSchema>;
+export declare function buildRuntimeSpawnOp(args: RuntimeSpawnArgs): BuiltRuntimeOp;
+export declare const ANIMATION_PLAYER_CMDS: readonly ["state", "play", "pause", "stop", "seek", "speed"];
+export declare const ANIMATION_TREE_CMDS: readonly ["state", "travel", "start", "stop", "set_param", "get_param"];
+export declare const runtimeAnimateArgsSchema: z.ZodObject<{
+    target: z.ZodEnum<["player", "tree", "bones"]>;
+    path: z.ZodString;
+    cmd: z.ZodOptional<z.ZodEnum<["state", "play", "pause", "stop", "seek", "speed", "travel", "start", "set_param", "get_param"]>>;
+    name: z.ZodOptional<z.ZodString>;
+    position: z.ZodOptional<z.ZodNumber>;
+    speed: z.ZodOptional<z.ZodNumber>;
+    from_end: z.ZodOptional<z.ZodBoolean>;
+    blend: z.ZodOptional<z.ZodNumber>;
+    update: z.ZodOptional<z.ZodBoolean>;
+    state: z.ZodOptional<z.ZodString>;
+    reset: z.ZodOptional<z.ZodBoolean>;
+    param: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    playback_path: z.ZodOptional<z.ZodString>;
+    bones: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    space: z.ZodOptional<z.ZodEnum<["global", "local", "both"]>>;
+    include_rest: z.ZodOptional<z.ZodBoolean>;
+    instance: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    target: "tree" | "player" | "bones";
+    instance?: string | undefined;
+    name?: string | undefined;
+    value?: string | number | boolean | undefined;
+    blend?: number | undefined;
+    state?: string | undefined;
+    position?: number | undefined;
+    speed?: number | undefined;
+    bones?: string[] | undefined;
+    cmd?: "pause" | "play" | "stop" | "state" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
+    from_end?: boolean | undefined;
+    update?: boolean | undefined;
+    reset?: boolean | undefined;
+    param?: string | undefined;
+    playback_path?: string | undefined;
+    space?: "local" | "global" | "both" | undefined;
+    include_rest?: boolean | undefined;
+}, {
+    path: string;
+    target: "tree" | "player" | "bones";
+    instance?: string | undefined;
+    name?: string | undefined;
+    value?: string | number | boolean | undefined;
+    blend?: number | undefined;
+    state?: string | undefined;
+    position?: number | undefined;
+    speed?: number | undefined;
+    bones?: string[] | undefined;
+    cmd?: "pause" | "play" | "stop" | "state" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
+    from_end?: boolean | undefined;
+    update?: boolean | undefined;
+    reset?: boolean | undefined;
+    param?: string | undefined;
+    playback_path?: string | undefined;
+    space?: "local" | "global" | "both" | undefined;
+    include_rest?: boolean | undefined;
+}>;
+export type RuntimeAnimateArgs = z.infer<typeof runtimeAnimateArgsSchema>;
+export declare function buildRuntimeAnimateOp(args: RuntimeAnimateArgs): BuiltRuntimeOp;
+export declare const gameControlArgsSchema: z.ZodObject<{
+    action: z.ZodEnum<["pause", "resume", "step", "speed", "instances"]>;
+    frames: z.ZodOptional<z.ZodNumber>;
+    kind: z.ZodOptional<z.ZodEnum<["physics", "process"]>>;
+    speed: z.ZodOptional<z.ZodNumber>;
+    instance: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: "instances" | "pause" | "resume" | "speed" | "step";
+    instance?: string | undefined;
+    kind?: "physics" | "process" | undefined;
+    speed?: number | undefined;
+    frames?: number | undefined;
+}, {
+    action: "instances" | "pause" | "resume" | "speed" | "step";
+    instance?: string | undefined;
+    kind?: "physics" | "process" | undefined;
+    speed?: number | undefined;
+    frames?: number | undefined;
+}>;
+export type GameControlArgs = z.infer<typeof gameControlArgsSchema>;
+export declare function buildGameControlOp(args: GameControlArgs): BuiltRuntimeOp;
+export declare const inputEventSchema: z.ZodObject<{
+    at_frame: z.ZodOptional<z.ZodNumber>;
+    at_ms: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodEnum<["action", "key", "mouse_click", "axis", "raw"]>;
+    action: z.ZodOptional<z.ZodString>;
+    pressed: z.ZodOptional<z.ZodBoolean>;
+    strength: z.ZodOptional<z.ZodNumber>;
+    hold_ms: z.ZodOptional<z.ZodNumber>;
+    keycode: z.ZodOptional<z.ZodNumber>;
+    physical_keycode: z.ZodOptional<z.ZodNumber>;
+    position: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    button: z.ZodOptional<z.ZodNumber>;
+    action_negative: z.ZodOptional<z.ZodString>;
+    action_positive: z.ZodOptional<z.ZodString>;
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+    class: z.ZodOptional<z.ZodString>;
+    props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    type: "key" | "action" | "mouse_click" | "axis" | "raw";
+    action?: string | undefined;
+    button?: number | undefined;
+    class?: string | undefined;
+    position?: [number, number] | undefined;
+    props?: Record<string, unknown> | undefined;
+    at_frame?: number | undefined;
+    at_ms?: number | undefined;
+    pressed?: boolean | undefined;
+    strength?: number | undefined;
+    hold_ms?: number | undefined;
+    keycode?: number | undefined;
+    physical_keycode?: number | undefined;
+    action_negative?: string | undefined;
+    action_positive?: string | undefined;
+    duration_ms?: number | undefined;
+}, {
+    type: "key" | "action" | "mouse_click" | "axis" | "raw";
+    action?: string | undefined;
+    button?: number | undefined;
+    class?: string | undefined;
+    position?: [number, number] | undefined;
+    props?: Record<string, unknown> | undefined;
+    at_frame?: number | undefined;
+    at_ms?: number | undefined;
+    pressed?: boolean | undefined;
+    strength?: number | undefined;
+    hold_ms?: number | undefined;
+    keycode?: number | undefined;
+    physical_keycode?: number | undefined;
+    action_negative?: string | undefined;
+    action_positive?: string | undefined;
+    duration_ms?: number | undefined;
+}>;
+export type InputEvent = z.infer<typeof inputEventSchema>;
+export declare const gameInputArgsSchema: z.ZodObject<{
+    action: z.ZodEnum<["script", "record_start", "record_stop", "replay"]>;
+    events: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        at_frame: z.ZodOptional<z.ZodNumber>;
+        at_ms: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodEnum<["action", "key", "mouse_click", "axis", "raw"]>;
+        action: z.ZodOptional<z.ZodString>;
+        pressed: z.ZodOptional<z.ZodBoolean>;
+        strength: z.ZodOptional<z.ZodNumber>;
+        hold_ms: z.ZodOptional<z.ZodNumber>;
+        keycode: z.ZodOptional<z.ZodNumber>;
+        physical_keycode: z.ZodOptional<z.ZodNumber>;
+        position: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        button: z.ZodOptional<z.ZodNumber>;
+        action_negative: z.ZodOptional<z.ZodString>;
+        action_positive: z.ZodOptional<z.ZodString>;
+        duration_ms: z.ZodOptional<z.ZodNumber>;
+        class: z.ZodOptional<z.ZodString>;
+        props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "key" | "action" | "mouse_click" | "axis" | "raw";
+        action?: string | undefined;
+        button?: number | undefined;
+        class?: string | undefined;
+        position?: [number, number] | undefined;
+        props?: Record<string, unknown> | undefined;
+        at_frame?: number | undefined;
+        at_ms?: number | undefined;
+        pressed?: boolean | undefined;
+        strength?: number | undefined;
+        hold_ms?: number | undefined;
+        keycode?: number | undefined;
+        physical_keycode?: number | undefined;
+        action_negative?: string | undefined;
+        action_positive?: string | undefined;
+        duration_ms?: number | undefined;
+    }, {
+        type: "key" | "action" | "mouse_click" | "axis" | "raw";
+        action?: string | undefined;
+        button?: number | undefined;
+        class?: string | undefined;
+        position?: [number, number] | undefined;
+        props?: Record<string, unknown> | undefined;
+        at_frame?: number | undefined;
+        at_ms?: number | undefined;
+        pressed?: boolean | undefined;
+        strength?: number | undefined;
+        hold_ms?: number | undefined;
+        keycode?: number | undefined;
+        physical_keycode?: number | undefined;
+        action_negative?: string | undefined;
+        action_positive?: string | undefined;
+        duration_ms?: number | undefined;
+    }>, "many">>;
+    clock: z.ZodOptional<z.ZodEnum<["frame", "ms"]>>;
+    wait: z.ZodOptional<z.ZodBoolean>;
+    include_motion: z.ZodOptional<z.ZodBoolean>;
+    save_as: z.ZodOptional<z.ZodString>;
+    recording: z.ZodOptional<z.ZodString>;
+    seed: z.ZodOptional<z.ZodNumber>;
+    instance: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    action: "script" | "record_start" | "record_stop" | "replay";
+    events?: {
+        type: "key" | "action" | "mouse_click" | "axis" | "raw";
+        action?: string | undefined;
+        button?: number | undefined;
+        class?: string | undefined;
+        position?: [number, number] | undefined;
+        props?: Record<string, unknown> | undefined;
+        at_frame?: number | undefined;
+        at_ms?: number | undefined;
+        pressed?: boolean | undefined;
+        strength?: number | undefined;
+        hold_ms?: number | undefined;
+        keycode?: number | undefined;
+        physical_keycode?: number | undefined;
+        action_negative?: string | undefined;
+        action_positive?: string | undefined;
+        duration_ms?: number | undefined;
+    }[] | undefined;
+    instance?: string | undefined;
+    seed?: number | undefined;
+    wait?: boolean | undefined;
+    clock?: "frame" | "ms" | undefined;
+    include_motion?: boolean | undefined;
+    save_as?: string | undefined;
+    recording?: string | undefined;
+}, {
+    action: "script" | "record_start" | "record_stop" | "replay";
+    events?: {
+        type: "key" | "action" | "mouse_click" | "axis" | "raw";
+        action?: string | undefined;
+        button?: number | undefined;
+        class?: string | undefined;
+        position?: [number, number] | undefined;
+        props?: Record<string, unknown> | undefined;
+        at_frame?: number | undefined;
+        at_ms?: number | undefined;
+        pressed?: boolean | undefined;
+        strength?: number | undefined;
+        hold_ms?: number | undefined;
+        keycode?: number | undefined;
+        physical_keycode?: number | undefined;
+        action_negative?: string | undefined;
+        action_positive?: string | undefined;
+        duration_ms?: number | undefined;
+    }[] | undefined;
+    instance?: string | undefined;
+    seed?: number | undefined;
+    wait?: boolean | undefined;
+    clock?: "frame" | "ms" | undefined;
+    include_motion?: boolean | undefined;
+    save_as?: string | undefined;
+    recording?: string | undefined;
+}>;
+export type GameInputArgs = z.infer<typeof gameInputArgsSchema>;
+/** Last-event horizon in frames (at_ms mapped at 60 fps, like the engine's pre-check). */
+export declare function inputScriptHorizonFrames(events: Array<Record<string, unknown>>): number;
+/** Engine watchdog for a waited script: min(20 s, max(10 s, horizon/60 + 3 s)). */
+export declare function inputScriptWatchdogSec(horizonFrames: number, wait: boolean): number;
+export declare function buildGameInputOp(args: GameInputArgs): BuiltRuntimeOp;
+export declare const gameProbeArgsSchema: z.ZodObject<{
+    tree: z.ZodOptional<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        depth: z.ZodOptional<z.ZodNumber>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        path?: string | undefined;
+        limit?: number | undefined;
+        depth?: number | undefined;
+    }, {
+        path?: string | undefined;
+        limit?: number | undefined;
+        depth?: number | undefined;
+    }>>;
+    props: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    screenshot: z.ZodOptional<z.ZodBoolean>;
+    max_dim: z.ZodOptional<z.ZodNumber>;
+    instance: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    instance?: string | undefined;
+    tree?: {
+        path?: string | undefined;
+        limit?: number | undefined;
+        depth?: number | undefined;
+    } | undefined;
+    props?: string[] | undefined;
+    screenshot?: boolean | undefined;
+    max_dim?: number | undefined;
+}, {
+    instance?: string | undefined;
+    tree?: {
+        path?: string | undefined;
+        limit?: number | undefined;
+        depth?: number | undefined;
+    } | undefined;
+    props?: string[] | undefined;
+    screenshot?: boolean | undefined;
+    max_dim?: number | undefined;
+}>;
+export type GameProbeArgs = z.infer<typeof gameProbeArgsSchema>;
+export declare function buildGameProbeOp(args: GameProbeArgs): BuiltRuntimeOp;
+/** The GameProbe result inside an ops envelope (or the bare op result). */
+export declare function findProbePayload(result: unknown): Record<string, unknown> | null;
+/** The same envelope with the image bytes removed (for text rendering and logs). */
+export declare function stripProbeImage(result: unknown): unknown;
+/** One-line frame stamp for a probe payload: which frame the state and the
+ *  pixels describe, so a claim can cite it. */
+export declare function probeFrameStamp(payload: Record<string, unknown>): string;
+export declare const playGameExtensionSchema: {
+    instance: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<["embedded", "offscreen"]>>;
+    deterministic: z.ZodOptional<z.ZodBoolean>;
+    seed: z.ZodOptional<z.ZodNumber>;
+    fixed_fps: z.ZodOptional<z.ZodNumber>;
+    time_scale: z.ZodOptional<z.ZodNumber>;
+    speed: z.ZodOptional<z.ZodNumber>;
+    focus: z.ZodOptional<z.ZodBoolean>;
+};
+export interface PlayGameArgs {
+    scene?: string;
+    instance?: string;
+    mode?: "embedded" | "offscreen";
+    deterministic?: boolean;
+    seed?: number;
+    fixed_fps?: number;
+    time_scale?: number;
+    speed?: number;
+    /** true = today's toolbar-style launch (Game tab + focus). Absent/false = quiet. */
+    focus?: boolean;
+}
+/**
+ * Quiet is the default whenever an agent drives play — both faces of this tool
+ * (MCP and `summer tool`) ARE agent faces, so the only way to a focus-stealing
+ * launch is an explicit focus:true. Quiet travels as PlayGame `agent:true`
+ * (debug_ops.cpp play_game -> GameView::set_agent_quiet_play), which the engine
+ * has honoured since 0.5.45 (c7c490d84f3, 2026-07-02).
+ */
+export declare function playIsQuiet(args: PlayGameArgs): boolean;
+/** True when the call needs the PlayGame OP (instance-aware / determinism
+ *  params) rather than the legacy /api/play route, which forwards only `scene`. */
+export declare function playNeedsOp(args: PlayGameArgs): boolean;
+/** True when the call addresses a non-main instance or an offscreen mode —
+ *  the part of PlayGame that only a runtime-control engine understands. */
+export declare function playTargetsInstance(args: PlayGameArgs): boolean;
+export declare function buildPlayGameOp(args: PlayGameArgs): BuiltRuntimeOp;
+export declare function buildStopGameOp(instance: string): BuiltRuntimeOp;
+/**
+ * An engine that predates instance-aware PlayGame ignores `instance`/`mode`
+ * and starts the MAIN embedded game. When the caller asked for an instance
+ * and the result does not echo one, say so instead of letting the model
+ * believe a parallel instance is up.
+ */
+export declare function withPlayInstanceEcho(result: unknown, args: PlayGameArgs): unknown;
+export declare const PLAY_QUIET_NOT_SUPPORTED = "This Summer Engine build did not echo `agent_quiet` in its PlayGame result \u2014 it predates quiet play and has most likely switched the editor to the Game tab and taken focus. Update Summer Engine (restart it after updating) for launches that leave the user's screen alone.";
+/**
+ * Quiet was requested: the engine echoes `agent_quiet` when it understood the
+ * flag (debug_ops.cpp play_game — in the launch branch AND the already-running
+ * branch on current engines). No echo at all means an engine that predates
+ * the flag ignored it — say so instead of letting the model believe the user
+ * was left alone. The field is the contract; the `note` text is never matched.
+ */
+export declare function withPlayPostureEcho(result: unknown, args: PlayGameArgs): unknown;
+/** The subset of EngineApiClient summer_play drives. Structural so tests can
+ *  pass bare fakes; the capability getters come from CapabilityAdvertisingClient. */
+export interface PlayGameClient extends CapabilityAdvertisingClient {
+    play(scene?: string): Promise<unknown>;
+    executeOps(ops: Array<Record<string, unknown>>, options?: undefined, timeoutMs?: number): Promise<unknown>;
+}
+/**
+ * summer_play, ONE implementation for both faces (MCP debug-tools.ts and the
+ * CLI dispatcher). Throws ToolInputError for a bad parameter combination
+ * (nothing sent); returns the engine envelope, a structured engine_lacks_op
+ * pre-flight result, or the envelope with the old-engine / posture / instance
+ * annotations. Each face only decides how to RENDER failures.
+ *
+ * Routing: focus:true with no other parameter is the legacy /api/play route,
+ * byte-for-byte the v1 call. Everything else — including the quiet default —
+ * travels as the explicit PlayGame op, because the /api/play rung copies only
+ * `scene` into the op and would drop agent/seed/instance.
+ */
+export declare function playGame(client: PlayGameClient, args: PlayGameArgs): Promise<unknown>;