summer-engine 4.3.0 → 4.5.0

package/dist/core/engine-self-start.js

@@ -0,0 +1,282 @@
+/**
+ * Opening a project in Summer Engine for an agent: what the MCP does when no
+ * editor is reachable (src/mcp/server.ts getClient), and the
+ * projects.open_local operation (core/capabilities/projects-local.ts), for
+ * agents with no shell.
+ *
+ *   installed, a project, nothing open -> launch it (background), wait, connect
+ *   not installed                      -> install, only with the person's yes
+ *                                         (projects.open_local install:true, or `summer dev`)
+ *   no project for this session        -> projects.create_local (or `summer dev`)
+ *   another project open               -> name that project
+ *
+ * SUMMER_AUTO_LAUNCH=0 turns the launch on a tool call off; projects.open_local
+ * is an explicit ask and still opens.
+ */
+import { execSync } from "child_process";
+import { realpathSync } from "fs";
+import { resolve, sep } from "path";
+import { EngineApiClient } from "./api-client.js";
+import { checkEngineHealth, findProjectRoot, listEngineInstances } from "./engine.js";
+import { CLOSED_EARLY, lastLaunch, LaunchLockBusyError, launchEditor, resolveRunBinary } from "./engine-launch.js";
+import { ENGINE_BIN_ENV } from "./engine-install.js";
+import { installEngine } from "./engine-installer.js";
+import { EngineNotRunningError } from "./error-codes.js";
+import { processIsAlive } from "./util/process.js";
+import { settlesWithin, sleep } from "./util/sleep.js";
+export const AUTO_LAUNCH_ENV = "SUMMER_AUTO_LAUNCH";
+/** One tool call ends within this, all steps included (under a 60 s client timeout). */
+export const SELF_START_WAIT_MS = 40_000;
+/** A launch this recent is still starting: wait for it, never launch a second editor. */
+const LAUNCH_GRACE_MS = 5 * 60_000;
+export const DEV_COMMAND = "npx -y summer-engine@latest dev";
+export const SELF_START_RECOVERY = {
+    notInstalledHere: "Summer Engine is not installed. Ask the person first: this downloads and installs Summer Engine (about 660 MB, free). " +
+        `With their OK, call projects.open_local with install: true, or run: ${DEV_COMMAND} --yes (it installs the engine and opens this project).`,
+    notInstalled: "Summer Engine is not installed and this session has no project. Ask the person first: this downloads and installs Summer Engine " +
+        "(about 660 MB, free). With their OK: projects.create_local, then projects.open_local with install: true; " +
+        `or run: ${DEV_COMMAND} --yes (it installs, creates a starter project and opens it).`,
+    noProject: "No Summer project for this session. If summer dev is still opening one, wait and call again. Otherwise projects.create_local " +
+        `makes one (3d-basic by default) and projects.open_local opens it; or run: ${DEV_COMMAND} 3d-basic my-game.`,
+    busy: "Summer Engine has the project open but does not answer (busy, or still importing). Call again in 30 seconds.",
+    launchBusy: "Another Summer launch is in progress. Call again in 30 seconds.",
+    noDisplay: "This Linux session has no display (DISPLAY or WAYLAND_DISPLAY), so the editor cannot open here. " +
+        "Open the project in Summer Engine on a computer with a desktop.",
+    otherProject: (open, wanted) => `Summer Engine has ${open} open, not ${wanted}. Switch the editor to ${wanted}, or close it and call again.`,
+    starting: (root) => `Summer Engine is opening ${root}; the first open imports every asset and can take a few minutes. Call again in 30 seconds.`,
+    installing: (line) => `Summer Engine is installing (${line}). Call projects.open_local again in 30 seconds; it opens the project when the install is done.`,
+    closedEarly: (root) => `Summer Engine closed before it opened ${root}. Call again; if it closes again, open the project in Summer Engine to see why.`,
+    launchFailed: (code) => `Summer Engine could not start (${code}). Repair it: npx -y summer-engine@latest install --yes, then call again.`,
+    autoLaunchOff: (root) => `Open it with projects.open_local, or run: npx -y summer-engine@latest run ${root}`,
+};
+/** Projects this process launched, by root: when and which process, so a slow first start is waited on while it lives. */
+const launched = new Map();
+/** The answer just given: a caller's immediate retry (withEngine retries a
+ *  failed connect once) gets it again instead of a second wait. */
+let recent = null;
+const RECENT_MS = 3_000;
+/** The engine install this process runs for projects.open_local; it outlives
+ *  one tool call, and the next call reports it or carries on. */
+let install = null;
+/** Test-only: forget the last answer only (withEngine's immediate retry window). */
+export function _resetRecentForTests() {
+    recent = null;
+}
+/** Test-only: forget the launches and the install this process made. */
+export function _resetSelfStartForTests() {
+    launched.clear();
+    recent = null;
+    install = null;
+}
+/**
+ * The project this session works on: --project, else the folder the agent
+ * started in, else the project the last `summer dev` / `summer run` opened
+ * from this folder (it makes a subfolder the agent did not start in), while
+ * that launch is recent, its editor lives and the project is still there.
+ */
+export async function sessionProject(selection) {
+    if (selection?.projectPath)
+        return findProjectRoot(selection.projectPath);
+    if (selection?.instanceId)
+        return null;
+    const cwd = selection?.cwd ?? process.cwd();
+    const here = await findProjectRoot(cwd);
+    if (here)
+        return here;
+    const last = lastLaunch();
+    if (!last)
+        return null;
+    const root = await findProjectRoot(last.projectPath);
+    const folder = canonicalPath(cwd);
+    // Only a launch from this session's folder, or of a project below it: never another session's project.
+    const ours = root && (last.cwd === folder || root.startsWith(folder.endsWith(sep) ? folder : folder + sep));
+    return ours ? root : null;
+}
+function canonicalPath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+/** Linux with no display server: an editor window cannot open (containers, SSH, cloud agents). */
+export function hasNoDisplay(env = process.env, platform = process.platform) {
+    return platform === "linux" && !env.DISPLAY?.trim() && !env.WAYLAND_DISPLAY?.trim();
+}
+/** A live editor with another project than `root`, named for the person. */
+async function otherOpenProject(root) {
+    for (const instance of await listEngineInstances()) {
+        if (instance.resourceRoot === root)
+            continue;
+        if (await checkEngineHealth(instance.port)) {
+            return instance.projectName ? `${instance.projectName} (${instance.resourceRoot})` : instance.resourceRoot;
+        }
+    }
+    return null;
+}
+async function connectWithin(selection, connect, ms) {
+    const deadline = Date.now() + ms;
+    while (true) {
+        try {
+            return await connect(selection);
+        }
+        catch {
+            if (Date.now() >= deadline)
+                return null;
+            await sleep(1_000);
+        }
+    }
+}
+/** The MCP's stdout is its protocol: the installer never prints to it or hands it to a child. */
+const quietInstall = (opts) => installEngine(opts, { stdoutIsTTY: false, exec: (command) => execSync(command, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }) });
+/**
+ * Install the engine in the background of this process and wait up to
+ * `waitMs` for it: true when it is installed, false while it still runs.
+ * A failed install throws its EngineInstallError (once; the next call starts over).
+ */
+async function installWithin(deps, waitMs) {
+    if (!install) {
+        const state = { line: "starting", done: false, error: null, promise: Promise.resolve() };
+        state.promise = (deps.install ?? quietInstall)({ log: (line) => (state.line = line.trim() || state.line), isTTY: false }).then(() => {
+            state.done = true;
+        }, (error) => {
+            state.done = true;
+            state.error = error;
+        });
+        install = state;
+    }
+    const current = install;
+    await settlesWithin(current.promise, waitMs);
+    if (!current.done)
+        return false;
+    install = null;
+    if (current.error)
+        throw current.error;
+    return true;
+}
+/**
+ * Open `root` in the editor and return a connected client: launch it unless
+ * an editor has it, wait, and never launch it twice. Throws an
+ * EngineNotRunningError whose recovery is the one next step for the case.
+ */
+export async function openProjectInEditor(root, selection, options = {}, deps = {}) {
+    const env = deps.env ?? process.env;
+    const now = deps.now ?? Date.now;
+    const connect = deps.connect ?? ((s) => EngineApiClient.connect(s));
+    const log = deps.log ?? (() => { });
+    // One deadline for the whole call: install wait, launch, --help probe and connect.
+    const deadline = Date.now() + (deps.waitMs ?? SELF_START_WAIT_MS);
+    const left = (reserve = 0) => Math.max(0, deadline - Date.now() - reserve);
+    const reason = options.notRunning?.reason ?? "no editor has the project open";
+    const failure = (message, recovery) => new EngineNotRunningError(message, reason, recovery);
+    if (hasNoDisplay(env))
+        throw failure("Summer Engine cannot open a window here.", SELF_START_RECOVERY.noDisplay);
+    const open = await otherOpenProject(root);
+    if (open)
+        throw failure("Summer Engine has another project open.", SELF_START_RECOVERY.otherProject(open, root));
+    const binary = resolveRunBinary(undefined, env);
+    if (binary.binary === null) {
+        // A build named in SUMMER_BIN that is missing is not "not installed": installing would not change it.
+        if (env[ENGINE_BIN_ENV]?.trim())
+            throw failure("Summer Engine could not start.", binary.error);
+        if (!options.install && !install)
+            throw failure("Summer Engine is not installed.", SELF_START_RECOVERY.notInstalledHere);
+        log("Summer Engine is not installed: installing it");
+        if (!(await installWithin(deps, left(5_000)))) {
+            throw failure("Summer Engine is installing.", SELF_START_RECOVERY.installing(install?.line ?? "starting"));
+        }
+    }
+    const since = launched.get(root);
+    if (since && now() - since.at < LAUNCH_GRACE_MS && (since.pid === undefined || processIsAlive(since.pid))) {
+        log(`waiting for the editor launched ${Math.round((now() - since.at) / 1000)} s ago for ${root}`);
+        const client = await connectWithin(selection, connect, left());
+        if (client)
+            return client;
+        throw failure("Summer Engine is starting.", SELF_START_RECOVERY.starting(root));
+    }
+    launched.delete(root);
+    log(`no editor has ${root} open: launching it in the background`);
+    let result;
+    try {
+        result = await (deps.launch ?? launchEditor)({
+            projectPath: root,
+            posture: "background",
+            // The lock wait, the --help probe and the API wait end by then; the connect after it fits in the rest.
+            deadline: deadline - 5_000,
+            out: { log, error: log },
+        });
+    }
+    catch (error) {
+        // Another launch holds the lock: it may be for another project.
+        if (error instanceof LaunchLockBusyError)
+            throw failure("Another Summer launch is in progress.", SELF_START_RECOVERY.launchBusy);
+        throw failure("Summer Engine could not start.", SELF_START_RECOVERY.launchFailed(error.message));
+    }
+    switch (result.status) {
+        case "running": {
+            if (result.launched)
+                launched.set(root, { at: now(), pid: result.pid });
+            // The editor answers health a moment before it registers for discovery.
+            const client = await connectWithin(selection, connect, Math.min(5_000, left()));
+            if (client)
+                return client;
+            throw failure("Summer Engine is starting.", SELF_START_RECOVERY.starting(root));
+        }
+        case "starting":
+            launched.set(root, { at: now(), pid: result.pid });
+            throw failure("Summer Engine is starting.", SELF_START_RECOVERY.starting(root));
+        case "other_project":
+            throw failure("Summer Engine has another project open.", SELF_START_RECOVERY.otherProject(result.project, root));
+        case "no_binary":
+            throw failure("Summer Engine is not installed.", SELF_START_RECOVERY.notInstalledHere);
+        case "spawn_failed":
+            if (result.code === CLOSED_EARLY)
+                throw failure("Summer Engine closed before the project opened.", SELF_START_RECOVERY.closedEarly(root));
+            throw failure("Summer Engine could not start.", SELF_START_RECOVERY.launchFailed(result.code));
+    }
+}
+/**
+ * Open the session's project and return a connected client, or throw an
+ * EngineNotRunningError whose recovery is the one next step for this case.
+ * Never installs: that needs the person's yes (projects.open_local).
+ */
+export async function selfStartEngine(selection, notRunning, deps = {}) {
+    const now = deps.now ?? Date.now;
+    if (recent && now() - recent.at < RECENT_MS)
+        throw recent.error;
+    try {
+        return await openSessionProject(selection, notRunning, deps);
+    }
+    catch (error) {
+        if (error instanceof EngineNotRunningError)
+            recent = { at: now(), error };
+        throw error;
+    }
+}
+async function openSessionProject(selection, notRunning, deps) {
+    const env = deps.env ?? process.env;
+    const failure = (message, recovery) => new EngineNotRunningError(message, notRunning.reason, recovery);
+    // A registered editor that does not answer is busy (an import, a blocking
+    // script): it is there, so never start a second one.
+    if (/instance \S+ is not responding/.test(notRunning.reason))
+        throw failure("Summer Engine is not answering.", SELF_START_RECOVERY.busy);
+    // The person already said yes to an install this process runs: say so instead of asking again.
+    if (install && !install.done)
+        throw failure("Summer Engine is installing.", SELF_START_RECOVERY.installing(install.line));
+    const root = await sessionProject(selection);
+    if (!root) {
+        if (resolveRunBinary(undefined, env).binary === null)
+            throw failure("Summer Engine is not installed.", SELF_START_RECOVERY.notInstalled);
+        throw failure("No Summer project for this session.", SELF_START_RECOVERY.noProject);
+    }
+    if (env[AUTO_LAUNCH_ENV] === "0") {
+        const open = await otherOpenProject(root);
+        if (open)
+            throw failure("Summer Engine has another project open.", SELF_START_RECOVERY.otherProject(open, root));
+        if (resolveRunBinary(undefined, env).binary === null)
+            throw failure("Summer Engine is not installed.", SELF_START_RECOVERY.notInstalledHere);
+        throw failure(notRunning.message, SELF_START_RECOVERY.autoLaunchOff(root));
+    }
+    return openProjectInEditor(root, selection, { notRunning }, deps);
+}

package/dist/core/engine.d.ts

@@ -48,7 +48,13 @@ export interface EngineConnection {
 export declare function getApiToken(summerDir?: string): Promise<string | null>;
 export declare function getApiPort(summerDir?: string): Promise<number>;
 export declare function findProjectRoot(startPath: string): Promise<string | null>;
-export declare function listEngineInstances(nowMs?: number, summerDir?: string): Promise<EngineInstance[]>;
+export declare function listEngineInstances(nowMs?: number, summerDir?: string, 
+/** Keep entries whose heartbeat is old (up to 30 min): an editor that is
+ *  alive but busy (a long import) stops beating; the launcher must still
+ *  not start a second one. */
+options?: {
+    anyHeartbeat?: boolean;
+}): Promise<EngineInstance[]>;
 export declare function resolveEngineConnection(selection?: EngineSelection, options?: EngineDiscoveryOptions): Promise<EngineConnection>;
 /**
  * The registry half of no-selection discovery (the CLI face; see

package/dist/core/engine.js

@@ -7,6 +7,7 @@ import { parseEngineCapabilities, } from "./capability-skew.js";
 const DEFAULT_PORT = 6550;
 const INSTANCE_SCHEMA_VERSION = 1;
 const INSTANCE_STALE_MS = 180_000;
+const BUSY_INSTANCE_STALE_MS = 30 * 60_000;
 const MAX_INSTANCE_FILE_BYTES = 64 * 1024;
 /** Env names the MCP server already honours for an explicit selection
  *  (src/mcp/server.ts startMcpServer). The CLI face reads the same two so a
@@ -116,7 +117,11 @@ function parseEngineInstance(value) {
         engineVersion: stringFromUnknown(record.engineVersion),
     };
 }
-export async function listEngineInstances(nowMs = Date.now(), summerDir = getSummerDir()) {
+export async function listEngineInstances(nowMs = Date.now(), summerDir = getSummerDir(), 
+/** Keep entries whose heartbeat is old (up to 30 min): an editor that is
+ *  alive but busy (a long import) stops beating; the launcher must still
+ *  not start a second one. */
+options = {}) {
     const instancesDir = join(summerDir, "instances");
     try {
         const dirInfo = await lstat(instancesDir);
@@ -142,7 +147,9 @@ export async function listEngineInstances(nowMs = Date.now(), summerDir = getSum
             const parsed = parseEngineInstance(JSON.parse(await readFile(path, "utf-8")));
             if (!parsed || !processIsAlive(parsed.pid))
                 continue;
-            if (nowMs - parsed.heartbeatAt * 1000 > INSTANCE_STALE_MS)
+            // A busy editor's heartbeat may lag; one silent this long is gone (its pid reused).
+            const staleAfter = options.anyHeartbeat ? BUSY_INSTANCE_STALE_MS : INSTANCE_STALE_MS;
+            if (nowMs - parsed.heartbeatAt * 1000 > staleAfter)
                 continue;
             parsed.resourceRoot = await canonicalPath(parsed.resourceRoot);
             instances.push(parsed);

package/dist/core/error-codes.d.ts

@@ -51,8 +51,11 @@ export declare function networkDetails(error: unknown): {
  *  registry paths) stays in the logs, not in the line the agent repeats. */
 export declare class EngineNotRunningError extends Error {
     readonly reason: string;
+    readonly recovery: string;
     readonly code: "engine_not_running";
-    constructor(message: string, reason: string);
+    /** `recovery`: the one next step for this case (not installed, no project,
+     *  another project open, still starting); the general step by default. */
+    constructor(message: string, reason: string, recovery?: string);
 }
 /** A connect error from core/engine.ts → EngineNotRunningError when it means
  *  no editor is reachable; null for the others (several editors open, …),

package/dist/core/error-codes.js

@@ -71,10 +71,14 @@ export function networkDetails(error) {
  *  registry paths) stays in the logs, not in the line the agent repeats. */
 export class EngineNotRunningError extends Error {
     reason;
+    recovery;
     code = "engine_not_running";
-    constructor(message, reason) {
+    /** `recovery`: the one next step for this case (not installed, no project,
+     *  another project open, still starting); the general step by default. */
+    constructor(message, reason, recovery = RECOVERY.engine_not_running) {
         super(message);
         this.reason = reason;
+        this.recovery = recovery;
         this.name = "EngineNotRunningError";
     }
 }
@@ -93,5 +97,5 @@ export function engineNotRunningFromConnectError(reason) {
     return null;
 }
 /** Engine-free tools keep working while the engine is down. */
-export const ENGINE_FREE_NOTE = "Only tools that touch the local project need the engine. Library, generation and asset tools " +
-    "(summer_search_library, summer_generate_*, summer_search_assets, summer_list_my_assets, summer_get_asset, summer_check_job) work now.";
+export const ENGINE_FREE_NOTE = "Only tools that touch the local project need the engine. Docs, generation and asset tools " +
+    "(summer_docs_search, summer_docs_read, summer_assets_generate_*, summer_assets_search, summer_assets_get, summer_jobs_get) work now.";

package/dist/core/library-read.d.ts

@@ -21,10 +21,10 @@ export declare const readLibraryInputSchema: z.ZodObject<{
     part: z.ZodOptional<z.ZodEnum<["skill", "resource", "all"]>>;
 }, "strict", z.ZodTypeAny, {
     id: string;
-    part?: "resource" | "all" | "skill" | undefined;
+    part?: "resource" | "skill" | "all" | undefined;
 }, {
     id: string;
-    part?: "resource" | "all" | "skill" | undefined;
+    part?: "resource" | "skill" | "all" | undefined;
 }>;
 export type ReadLibraryArgs = z.infer<typeof readLibraryInputSchema>;
 export interface LibraryReadDeps extends LibrarySearchDeps {

package/dist/core/library-search.d.ts

@@ -98,12 +98,12 @@ export declare const searchLibraryInputSchema: z.ZodObject<{
     include_preview: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     query: string;
-    kinds?: ("template" | "tool" | "skill" | "reference" | "example" | "collection")[] | undefined;
+    kinds?: ("skill" | "tool" | "template" | "reference" | "example" | "collection")[] | undefined;
     limit?: number | undefined;
     include_preview?: boolean | undefined;
 }, {
     query: string;
-    kinds?: ("template" | "tool" | "skill" | "reference" | "example" | "collection")[] | undefined;
+    kinds?: ("skill" | "tool" | "template" | "reference" | "example" | "collection")[] | undefined;
     limit?: number | undefined;
     include_preview?: boolean | undefined;
 }>;

package/dist/core/local-project.d.ts

@@ -0,0 +1,50 @@
+import { type TemplateEntry } from "./templates.js";
+import { type InstructionFileResult } from "../project-memory/agent-instructions.js";
+/**
+ * Built-in templates are generated in-process — no download, no pin. Their
+ * library manifests (`library/templates/<slug>/resource.yaml`) declare
+ * `builtin: true`; this map supplies the generator for each such slug.
+ */
+type BuiltinGenerator = (dir: string, projectName: string) => void;
+export declare const BUILTIN_GENERATORS: Readonly<Record<string, BuiltinGenerator>>;
+/**
+ * Copy the autopilot verification scaffold into a fresh project.
+ *
+ * Every project gets a working example of how to prove its own gameplay: a probe
+ * that drives the player with real input, saves rendered frames, asserts, and
+ * exits. Without it every agent reinvents verification from scratch, and most
+ * settle for asking the user to play the game instead.
+ *
+ * Never overwrites — an existing tests/autopilot/ is the user's, not ours.
+ */
+export declare function scaffoldAutopilot(projectDir: string): boolean;
+/** A folder `summer dev` may create a project in: missing, empty, or only
+ *  dotfiles (.git, .claude, .vscode, ...). */
+export declare function isEmptyProjectFolder(dir: string): boolean;
+/** The home folder or a filesystem root: never a project folder by default. */
+export declare function isHomeOrRoot(dir: string, home?: string): boolean;
+/** The project that holds `dir` (project.godot here or above, never above the home folder), or null. */
+export declare function projectRootAbove(dir: string, home?: string): string | null;
+export interface CreatedProject {
+    scaffolded: boolean;
+    instructions: InstructionFileResult[];
+}
+/**
+ * Write a project from a template into `fullPath`: generate a built-in, or
+ * fetch a pinned template (verified tree digest), then the autopilot
+ * scaffold, `.summer/project.json` and the agent instruction files.
+ * `fullPath` may already exist when isEmptyProjectFolder says so; files that
+ * are already there are kept, never replaced.
+ */
+export declare function createProject(entry: TemplateEntry, fullPath: string, options: {
+    name: string;
+    keepGit?: boolean;
+    log: (line: string) => void;
+}): Promise<CreatedProject>;
+/**
+ * project.godot uses C-style double-quoted strings; a project name containing
+ * `"` or `\` must be escaped or the file does not parse.
+ */
+export declare function escapeGodotString(value: string): string;
+export declare function renderProjectSettings(name: string, mainScene: string): string;
+export {};