summer-engine 2.8.2 → 3.1.0

package/dist/core/headless/worker-engine-client.d.ts

@@ -0,0 +1,58 @@
+import type { EngineSnapshot } from "../api-client.js";
+import type { WorkerConnection } from "./worker-connection.js";
+import { type EngineCapabilities } from "../capability-skew.js";
+type JsonRecord = Record<string, unknown>;
+export declare class WorkerEngineClient {
+    private connection;
+    /** Last `status` answer, for the capability/version getters withEngine's
+     *  pre-flight (missingEngineOpResult) and skew warning read synchronously. */
+    private lastStatus;
+    constructor(connection: WorkerConnection);
+    get projectPath(): string;
+    isAlive(): boolean;
+    close(): void;
+    health(): Promise<unknown>;
+    /** The worker's capability advert from the last `status` read (health()),
+     *  or undefined before the first read / when the worker advertises none.
+     *  Same contract as EngineApiClient.getEngineCapabilities: an absent
+     *  advert proves nothing, so the pre-flight lets the call through. */
+    getEngineCapabilities(): EngineCapabilities | undefined;
+    /** Engine version string from the last `status` read, for skew messages. */
+    getEngineVersion(): string | undefined;
+    readFile(path: string, maxBytes?: number): Promise<unknown>;
+    readProjectFile(path: string, maxBytes?: number): Promise<unknown>;
+    getFsTree(root?: string, _limit?: number): Promise<unknown>;
+    getSceneState(scenePath?: string, _options?: {
+        depth?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    play(scene?: string): Promise<unknown>;
+    stop(): Promise<unknown>;
+    gameSnapshot(): Promise<EngineSnapshot>;
+    /**
+     * The worker exposes a fixed op set, not the editor's generic ops queue.
+     * Batches made ONLY of ops with worker equivalents are translated
+     * (WriteFile -> fs.write, GetConsoleOutput -> game.logs {tail},
+     * IsGameRunning -> game.logs reading result.running); anything else fails
+     * loudly BEFORE any op in the batch is applied.
+     */
+    executeOps(ops: JsonRecord[], _options?: JsonRecord): Promise<unknown>;
+    executeIdentityBoundOps(ops: JsonRecord[], options?: JsonRecord): Promise<unknown>;
+    getBoundProjectIdHash(): string | undefined;
+    rebind(): Promise<string | undefined>;
+    getPort(): number;
+    credentialsChanged(): Promise<boolean>;
+    getProjectState(_prefix?: string): Promise<unknown>;
+    getDiagnostics(): Promise<unknown>;
+    inspectNode(_path: string): Promise<unknown>;
+    inspectResource(_path: string): Promise<unknown>;
+    getScriptErrors(_path: string): Promise<unknown>;
+    getSelection(): Promise<unknown>;
+    viewportSnapshot(): Promise<EngineSnapshot>;
+    scenePreview(_input?: unknown): Promise<EngineSnapshot>;
+    /** The worker has no events channel (no /api/events); the events tools'
+     *  pre-flight already refuses on a status without capabilities.events, so
+     *  this is reached only with SUMMER_CAPABILITY_PREFLIGHT=off. */
+    pollEvents(_params?: unknown, _timeoutMs?: number): Promise<unknown>;
+}
+export {};

package/dist/core/headless/worker-engine-client.js

@@ -0,0 +1,246 @@
+import { parseEngineCapabilities, } from "../capability-skew.js";
+import { UnsupportedOperationError } from "../tool-errors.js";
+/**
+ * EngineApiClient-shaped facade over a WorkerConnection, so the existing MCP
+ * tool handlers (which all call typed methods on the client withEngine hands
+ * them) can be served by a headless worker WITHOUT any tool-file changes.
+ *
+ * Implements the FULL public method surface of EngineApiClient:
+ *   - methods with a worker equivalent delegate to the worker op
+ *   - methods without one throw a clean, actionable error, which withEngine
+ *     surfaces verbatim as an isError tool result — nothing is silently faked
+ *
+ * The MCP wiring (mcp-routing.ts) returns this cast to EngineApiClient; the
+ * cast is sound because every public method exists here. Only reachable when
+ * SUMMER_HEADLESS_ROUTING=1 and no live editor has the project open.
+ */
+/** Tagged so withEngine classifies it "unsupported" (nothing sent, keep the
+ *  client, no transport recovery recipe) instead of "transport". */
+function unsupported(method) {
+    throw new UnsupportedOperationError(`"${method}" is not supported by the headless worker serving this project. ` +
+        "Only file, import, scene-read, and game run/stop/log/screenshot operations work headless. " +
+        "Open the project in the Summer editor (npx -y summer-engine@latest run <path>) for full coverage.");
+}
+/** Worker ops take project-relative paths; the editor tool surface speaks
+ *  res:// URIs. Strip the scheme before anything crosses the wire (the
+ *  worker is also adding acceptance — both sides tolerate both forms). */
+function stripRes(path) {
+    return path.startsWith("res://") ? path.slice("res://".length) : path;
+}
+export class WorkerEngineClient {
+    connection;
+    /** Last `status` answer, for the capability/version getters withEngine's
+     *  pre-flight (missingEngineOpResult) and skew warning read synchronously. */
+    lastStatus;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    get projectPath() {
+        return this.connection.projectPath;
+    }
+    isAlive() {
+        return this.connection.isAlive();
+    }
+    close() {
+        this.connection.close();
+    }
+    // ---- supported surface -------------------------------------------------
+    async health() {
+        const status = await this.connection.call("status");
+        this.lastStatus =
+            status && typeof status === "object" && !Array.isArray(status)
+                ? status
+                : undefined;
+        return status;
+    }
+    /** The worker's capability advert from the last `status` read (health()),
+     *  or undefined before the first read / when the worker advertises none.
+     *  Same contract as EngineApiClient.getEngineCapabilities: an absent
+     *  advert proves nothing, so the pre-flight lets the call through. */
+    getEngineCapabilities() {
+        return parseEngineCapabilities(this.lastStatus?.capabilities);
+    }
+    /** Engine version string from the last `status` read, for skew messages. */
+    getEngineVersion() {
+        const version = this.lastStatus?.version;
+        return typeof version === "string" && version.length > 0 ? version : undefined;
+    }
+    async readFile(path, maxBytes) {
+        // Worker supports maxBytes up to 8MiB — clamp client-side.
+        const clamped = maxBytes !== undefined
+            ? Math.min(maxBytes, 8 * 1024 * 1024)
+            : undefined;
+        return this.connection.call("fs.read", {
+            path: stripRes(path),
+            ...(clamped !== undefined ? { maxBytes: clamped } : {}),
+        });
+    }
+    async readProjectFile(path, maxBytes = 200_000) {
+        return this.readFile(path, maxBytes);
+    }
+    async getFsTree(root = "res://", _limit = 2000) {
+        // Worker contract: fs.list takes {dir}, project-relative — the default
+        // res:// root maps to "" (project root). `limit` is not implemented
+        // worker-side — dropped (results are project-file listings, bounded in
+        // practice by the project itself).
+        return this.connection.call("fs.list", { dir: stripRes(root) });
+    }
+    async getSceneState(scenePath, _options) {
+        // Worker contract: scene.read takes {path}. depth/limit are not part of
+        // the worker contract — dropped (the editor path still honors them).
+        return this.connection.call("scene.read", {
+            ...(scenePath ? { path: stripRes(scenePath) } : {}),
+        });
+    }
+    async play(scene) {
+        return this.connection.call("game.run", scene ? { scene: stripRes(scene) } : {});
+    }
+    async stop() {
+        return this.connection.call("game.stop", {}, { timeoutMs: 15_000 });
+    }
+    async gameSnapshot() {
+        try {
+            const result = (await this.connection.call("game.screenshot"));
+            const base64 = typeof result?.base64 === "string"
+                ? result.base64
+                : typeof result?.image_base64 === "string"
+                    ? result.image_base64
+                    : undefined;
+            return { ok: true, ...(result ?? {}), base64 };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                ok: false,
+                error: message.includes("needs_display")
+                    ? "The headless worker has no display to capture. Open the project in the Summer editor to take game screenshots."
+                    : message,
+                ...(message.includes("needs_display")
+                    ? { failureReason: "needs_display" }
+                    : {}),
+            };
+        }
+    }
+    /**
+     * The worker exposes a fixed op set, not the editor's generic ops queue.
+     * Batches made ONLY of ops with worker equivalents are translated
+     * (WriteFile -> fs.write, GetConsoleOutput -> game.logs {tail},
+     * IsGameRunning -> game.logs reading result.running); anything else fails
+     * loudly BEFORE any op in the batch is applied.
+     */
+    async executeOps(ops, _options) {
+        const supported = new Set(["WriteFile", "GetConsoleOutput", "IsGameRunning"]);
+        const rejected = ops.find((op) => !supported.has(String(op.op)));
+        if (rejected) {
+            unsupported(`executeOps op "${String(rejected.op)}"`);
+        }
+        const results = [];
+        for (const op of ops) {
+            const name = String(op.op);
+            if (name === "WriteFile") {
+                const result = await this.connection.call("fs.write", {
+                    path: stripRes(String(op.path ?? "")),
+                    content: op.content,
+                    ...(op.expectedSha256 !== undefined
+                        ? { expectedSha256: op.expectedSha256 }
+                        : {}),
+                    ...(op.mustNotExist === true ? { mustNotExist: true } : {}),
+                });
+                results.push({ ok: true, op: name, ...result });
+            }
+            else if (name === "GetConsoleOutput") {
+                // Worker contract: game.logs takes {tail}; filter/type are not
+                // supported worker-side. `filter` is applied client-side on the
+                // returned lines; `type` is dropped (documented in
+                // docs/HEADLESS_ROUTING.md).
+                const result = (await this.connection.call("game.logs", {
+                    ...(op.max_lines !== undefined ? { tail: op.max_lines } : {}),
+                }));
+                let shaped = result;
+                const filter = typeof op.filter === "string" ? op.filter : null;
+                if (filter && result && Array.isArray(result.lines)) {
+                    shaped = {
+                        ...result,
+                        lines: result.lines.filter((line) => typeof line === "string" && line.includes(filter)),
+                    };
+                }
+                results.push({ ok: true, op: name, ...(shaped ?? {}) });
+            }
+            else {
+                // IsGameRunning: the worker's status op has NO running field — the
+                // authoritative flag rides on game.logs as result.running. Before
+                // the first game.run, older workers ERROR on game.logs while newer
+                // ones answer {running:false}; both mean "not running" and must
+                // never throw. Transport failures (dead connection) still propagate.
+                let running = false;
+                try {
+                    const result = (await this.connection.call("game.logs", {
+                        tail: 0,
+                    }));
+                    running = result?.running === true;
+                }
+                catch (error) {
+                    const isWorkerAnswer = error instanceof Error && error.name === "WorkerOpError";
+                    if (!isWorkerAnswer)
+                        throw error;
+                    // The worker answered with an error — no game session exists.
+                    running = false;
+                }
+                results.push({ ok: true, op: name, running });
+            }
+        }
+        return { ok: true, results };
+    }
+    async executeIdentityBoundOps(ops, options) {
+        // A worker serves exactly one project by construction — the identity
+        // binding the editor needs (project switches under one HTTP port) has no
+        // headless analogue.
+        return this.executeOps(ops, options);
+    }
+    // ---- identity / cache plumbing getClient() relies on --------------------
+    getBoundProjectIdHash() {
+        return undefined;
+    }
+    async rebind() {
+        return undefined;
+    }
+    getPort() {
+        return -1;
+    }
+    async credentialsChanged() {
+        // A dropped worker socket = stale client; getClient's cache check drops
+        // it and the next call re-resolves (editor-beats-worker-beats-spawn).
+        return !this.connection.isAlive();
+    }
+    // ---- editor-only surface (fails loudly, never fakes) --------------------
+    async getProjectState(_prefix) {
+        unsupported("getProjectState");
+    }
+    async getDiagnostics() {
+        unsupported("getDiagnostics");
+    }
+    async inspectNode(_path) {
+        unsupported("inspectNode");
+    }
+    async inspectResource(_path) {
+        unsupported("inspectResource");
+    }
+    async getScriptErrors(_path) {
+        unsupported("getScriptErrors");
+    }
+    async getSelection() {
+        unsupported("getSelection");
+    }
+    async viewportSnapshot() {
+        unsupported("viewportSnapshot");
+    }
+    async scenePreview(_input) {
+        unsupported("scenePreview");
+    }
+    /** The worker has no events channel (no /api/events); the events tools'
+     *  pre-flight already refuses on a status without capabilities.events, so
+     *  this is reached only with SUMMER_CAPABILITY_PREFLIGHT=off. */
+    async pollEvents(_params, _timeoutMs) {
+        unsupported("pollEvents");
+    }
+}

package/dist/core/launch-posture.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Editor launch posture — the ONE place that decides whether `summer run`
+ * brings the Summer window to the front or leaves it in the background.
+ *
+ * The problem: when an agent drives Summer, every editor launch activates the
+ * app and steals the user's screen, so they cannot keep working while their
+ * game is built. The engine grows a launch posture for this:
+ *
+ *   focus       today's launch — the window appears and takes focus.
+ *   background  `--summer-background` — the window exists but never activates
+ *               or takes focus until the user clicks it.
+ *   offscreen   `--summer-offscreen` (also `--summer-verify`) — never
+ *               activates, never frontmost; on shipped engines an unfocusable
+ *               window pushed off-screen where a sliver may stay visible
+ *               (main.cpp says so), on the background-posture engine a
+ *               no-Dock-icon accessory process. Used by RunVerification /
+ *               offscreen play instances, never by `summer run`.
+ *
+ * Default posture: BACKGROUND when stdout is not a TTY, FOCUS when it is. A
+ * human typing `summer run` in a terminal wants to see the editor come up —
+ * that is the whole point of the command for them. An agent (Claude Code's
+ * Bash tool, an MCP host, a CI shell) never has a TTY on stdout, and for it
+ * the launch is a means to an end: the user is doing something else on the
+ * same Mac and must not be interrupted. `--focus` / `--background` override
+ * the heuristic either way; pass one explicitly in scripts.
+ *
+ * Engine support: the flag ships in a future 0.5.x. Godot's argument parser
+ * passes an unknown `--x` through to main_args instead of rejecting it
+ * (main/main.cpp, final `else` of the parse loop), so an old engine would not
+ * fail — it would silently launch WITH focus while the toolkit claimed a
+ * background launch. That is the lie we refuse to tell: the flag is passed
+ * only when the installed engine is known to honour it, and otherwise the
+ * caller gets a one-line note. The engine is not running before `summer run`,
+ * so /api/health cannot be consulted. Two pre-launch sources, in order:
+ *
+ *   1. `<binary> --help` and look for the flag in the help text — the PRIMARY
+ *      gate. `--help` is handled in Main::setup() before any display server
+ *      exists (main.cpp `arg == "--help"` -> ERR_HELP), and on macOS it is in
+ *      OS_MacOS::headless_args (os_macos.h; godot_main_macos.mm sets
+ *      is_headless and instantiates OS_MacOS_Headless), so the bundle runs
+ *      with no NSApp, no window, no activation, no Dock bounce. Definitive on
+ *      every engine version; the only probe that never lies. The answer is
+ *      cached per binary path + mtime + size in ~/.summer, so it runs once per
+ *      install.
+ *   2. The installed version (macOS Info.plist, Windows Velopack sq.version)
+ *      is ONLY the fallback when `--help` cannot run (spawn error, timeout).
+ *      It is never a pre-check: pre-release and dev builds carry the flag
+ *      while still stamped with the previous version (the first such build
+ *      says 0.5.65), so a version gate would refuse exactly the builds being
+ *      verified. Linux exposes no version file, so there it reads unknown.
+ *
+ * Once the engine is up, /api/health `capabilities.launchPostures`
+ * (["focus","background","offscreen"] on macOS builds, ["focus"] elsewhere,
+ * absent on older engines = ["focus"]) is the authoritative advert and is
+ * used for the post-launch note.
+ *
+ * `summer run` spawns the executable directly (Summer.app/Contents/MacOS/Summer
+ * on macOS), never through `open` — LaunchServices would activate the app and
+ * defeat the posture whatever flags were passed. The same holds for a
+ * `--bin` / SUMMER_BIN override: it must be the in-bundle executable, and the
+ * --help probe below runs against THAT binary (cache key: path + mtime + size).
+ */
+import { spawn } from "node:child_process";
+import type { EngineCapabilities } from "./capability-skew.js";
+export type LaunchPosture = "focus" | "background";
+/** Engine flag for the background posture (main/main.cpp). */
+export declare const BACKGROUND_LAUNCH_FLAG = "--summer-background";
+/** First RELEASED engine version expected to honour BACKGROUND_LAUNCH_FLAG.
+ *  Used only when the --help probe cannot run; dev/pre-release builds carry
+ *  the flag while still stamped 0.5.65, which is why the probe is the gate. */
+export declare const BACKGROUND_LAUNCH_MIN_ENGINE_VERSION = "0.5.66";
+export interface LaunchPostureFlags {
+    focus?: boolean;
+    background?: boolean;
+}
+export interface LaunchIo {
+    /** `process.stdout.isTTY` — true only for a human at a terminal. */
+    stdoutIsTTY: boolean;
+}
+/** BACKGROUND for agents (no TTY), FOCUS for a human at a terminal. */
+export declare function defaultLaunchPosture(io: LaunchIo): LaunchPosture;
+/** Explicit flag wins; both flags together is a caller error. */
+export declare function resolveLaunchPosture(flags: LaunchPostureFlags, io: LaunchIo): LaunchPosture;
+export type BackgroundLaunchSupport = {
+    supported: true;
+    source: "help_probe" | "version";
+    version: string | null;
+} | {
+    supported: false;
+    source: "help_probe" | "version";
+    reason: "engine_too_old";
+    version: string | null;
+} | {
+    supported: false;
+    source: "version";
+    reason: "version_unknown";
+    version: null;
+};
+/**
+ * Whether the installed engine honours the background flag. The `--help`
+ * probe answer (true/false) is definitive when it ran; a probe that could not
+ * run (null) falls back to the version gate, where an unreadable or
+ * unparseable version is "unknown", never "supported".
+ */
+export declare function backgroundLaunchSupport(installedVersion: string | null | undefined, helpProbe?: boolean | null): BackgroundLaunchSupport;
+/** True when the help text of an engine binary lists the background flag. */
+export declare function helpTextListsBackgroundFlag(helpText: string): boolean;
+export declare const HELP_PROBE_TIMEOUT_MS = 5000;
+/** The bit of child_process.spawn the probe uses; injectable for tests. */
+export type HelpProbeSpawn = (command: string, args: string[], options: {
+    stdio: ["ignore", "pipe", "pipe"];
+}) => ReturnType<typeof spawn>;
+/**
+ * Run `<binary> --help` and report whether the flag is listed: true / false,
+ * or null when the probe could not answer (spawn error, timeout). Safe on
+ * every version: --help exits in Main::setup() before a display server exists,
+ * and the macOS bundle runs it headless (OS_MacOS::headless_args), so nothing
+ * appears on screen and nothing is activated.
+ */
+export declare function probeBackgroundLaunchSupport(binary: string, timeoutMs?: number, spawnImpl?: HelpProbeSpawn): Promise<boolean | null>;
+export declare const HELP_PROBE_CACHE_FILE = "launch-probe-cache.json";
+export interface DetectBackgroundSupportOptions {
+    /** Installed version if already read; undefined = read it from the binary. */
+    installedVersion?: string | null;
+    summerDir?: string;
+    probe?: (binary: string) => Promise<boolean | null>;
+    now?: number;
+}
+/**
+ * The pre-launch decision for one binary, in the order the module header
+ * describes: cached `--help` answer, fresh `--help` probe (cached when it
+ * answers), and the version gate ONLY as the fallback when the probe cannot
+ * run. The probe is the sole positive gate — no version pre-check, so a dev
+ * build stamped 0.5.65 that lists the flag launches in the background.
+ */
+export declare function detectBackgroundLaunchSupport(binary: string, options?: DetectBackgroundSupportOptions): Promise<BackgroundLaunchSupport>;
+/**
+ * The running engine's own word, once it is up: /api/health
+ * `capabilities.launchPostures` (engine tool_net_thread.cpp, newer builds;
+ * "focus" always, "background" / "offscreen" only where enforced). true /
+ * false when advertised, null when the engine predates the advert.
+ */
+export declare function advertisedBackgroundPosture(capabilities: EngineCapabilities | undefined | null): boolean | null;
+export interface LaunchPlan {
+    posture: LaunchPosture;
+    /** Extra engine argv (after --path/--editor). Empty for focus, or when the
+     *  engine cannot honour background. */
+    extraArgs: string[];
+    /** True when the launch will actually stay in the background. */
+    background: boolean;
+    /** One line for the caller when background was requested but will not
+     *  happen (or cannot be verified). Null when there is nothing to say. */
+    note: string | null;
+}
+/** The launch decision: which flags to pass and what to tell the caller. */
+export declare function planLaunch(posture: LaunchPosture, support: BackgroundLaunchSupport): LaunchPlan;
+/** CFBundleShortVersionString out of a macOS Info.plist. */
+export declare function parseMacBundleVersion(plistText: string): string | null;
+/** Version string of an installed macOS bundle, or null when unreadable. */
+export declare function readMacBundleVersion(appPath: string): string | null;
+/** `<version>` out of a Velopack `sq.version` file (the nuspec Velopack drops
+ *  next to the current binary on Windows). Best effort: any other shape reads
+ *  as unknown. */
+export declare function parseVelopackVersion(sqVersionText: string): string | null;
+/**
+ * Installed engine version for a resolved engine binary, or null. macOS reads
+ * the bundle's Info.plist; Windows reads Velopack's sq.version beside the exe;
+ * Linux has no version source today and always reads null.
+ */
+export declare function readInstalledEngineVersion(binary: string, os?: NodeJS.Platform): string | null;