summer-engine 4.2.0 → 4.5.0

package/dist/cli/commands/run.js

@@ -1,110 +1,12 @@
 import { Command } from "commander";
-import { spawn } from "child_process";
 import { existsSync } from "fs";
-import { mkdir, readFile, rm, writeFile } from "fs/promises";
 import { join, resolve } from "path";
-import { getSummerDir } from "../../core/auth.js";
-import { getApiPort, checkEngineHealth } from "../../core/engine.js";
-import { describeEngineExecutableProblem, ENGINE_BIN_ENV, engineBinaryOverride, findEngineBinary, } from "../../core/engine-install.js";
-import { advertisedBackgroundPosture, backgroundLaunchSupport, detectBackgroundLaunchSupport, planLaunch, resolveLaunchPosture, BACKGROUND_LAUNCH_FLAG, BACKGROUND_LAUNCH_MIN_ENGINE_VERSION, } from "../../core/launch-posture.js";
-import { sleep } from "../../core/util/sleep.js";
-const LAUNCH_LOCK_STALE_MS = 60_000;
-const LAUNCH_LOCK_WAIT_MS = 15_000;
-function isProcessAlive(pid) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        const code = error.code;
-        return code === "EPERM";
-    }
-}
-async function removeStaleLaunchLock(lockDir) {
-    const ownerPath = join(lockDir, "owner.json");
-    try {
-        const raw = await readFile(ownerPath, "utf-8");
-        const owner = JSON.parse(raw);
-        const pid = typeof owner.pid === "number" ? owner.pid : 0;
-        const createdAt = typeof owner.createdAt === "number" ? owner.createdAt : 0;
-        const staleByTime = Date.now() - createdAt > LAUNCH_LOCK_STALE_MS;
-        const staleByPid = !isProcessAlive(pid);
-        if (!staleByTime && !staleByPid) {
-            return false;
-        }
-    }
-    catch {
-        // Broken owner metadata should not permanently block launches.
-    }
-    await rm(lockDir, { recursive: true, force: true });
-    return true;
-}
-async function withLaunchLock(fn) {
-    const summerDir = getSummerDir();
-    await mkdir(summerDir, { recursive: true, mode: 0o700 });
-    const lockDir = join(summerDir, "launch.lock");
-    const ownerPath = join(lockDir, "owner.json");
-    const startedAt = Date.now();
-    while (true) {
-        try {
-            await mkdir(lockDir, { mode: 0o700 });
-            try {
-                await writeFile(ownerPath, JSON.stringify({ pid: process.pid, createdAt: Date.now() }, null, 2), { encoding: "utf-8", mode: 0o600 });
-                return await fn();
-            }
-            finally {
-                await rm(lockDir, { recursive: true, force: true });
-            }
-        }
-        catch (error) {
-            const code = error.code;
-            if (code !== "EEXIST") {
-                throw error;
-            }
-            if (await removeStaleLaunchLock(lockDir)) {
-                continue;
-            }
-            if (Date.now() - startedAt > LAUNCH_LOCK_WAIT_MS) {
-                throw new Error("Another `summer run` launch is still in progress. Try again in a few seconds.");
-            }
-            await sleep(100);
-        }
-    }
-}
-/**
- * Which engine executable `summer run` launches (and probes with --help):
- * `--bin <path>`, else SUMMER_BIN, else the installed engine
- * (findEngineBinary, which also honours the older SUMMER_ENGINE_BINARY).
- * An explicit override is never silently swapped for the installed engine:
- * a missing path or a bare `.app` bundle is an error, because the caller
- * asked for THAT build.
- */
-export function resolveRunBinary(binFlag, env = process.env) {
-    const fromEnv = engineBinaryOverride(env);
-    const explicit = binFlag?.trim()
-        ? { source: "--bin", path: binFlag.trim() }
-        : fromEnv?.name === ENGINE_BIN_ENV
-            ? { source: ENGINE_BIN_ENV, path: fromEnv.path }
-            : null;
-    if (explicit) {
-        const path = resolve(explicit.path);
-        const problem = describeEngineExecutableProblem(path, explicit.source);
-        return problem ? { binary: null, error: problem } : { binary: path, source: explicit.source };
-    }
-    const installed = findEngineBinary();
-    if (!installed) {
-        return {
-            binary: null,
-            error: "Summer Engine not found. Install it first:\n" +
-                "  summer install\n" +
-                "  or download from https://summerengine.com/download\n" +
-                `To launch a build that is not installed, pass --bin <executable> or set ${ENGINE_BIN_ENV}.`,
-        };
-    }
-    return { binary: installed, source: "installed" };
-}
+import { launchEditor } from "../../core/engine-launch.js";
+import { ENGINE_BIN_ENV } from "../../core/engine-install.js";
+import { resolveLaunchPosture } from "../../core/launch-posture.js";
+// The launch itself (lock, already-open check, posture flags, health wait)
+// lives in core/engine-launch.ts, shared with `summer dev` and the MCP.
+export { resolveRunBinary } from "../../core/engine-launch.js";
 export const runCommand = new Command("run")
     .description("Launch Summer Engine with a project. Without a path it launches a bare " +
     "detached editor (project manager), which requires --no-project.")
@@ -148,108 +50,17 @@ export const runCommand = new Command("run")
             process.exit(1);
         }
     }
-    await withLaunchLock(async () => {
-        const port = await getApiPort();
-        const health = await checkEngineHealth(port);
-        if (health) {
-            const runningProjectPath = health.project_path
-                ? resolve(health.project_path)
-                : null;
-            if (!fullProjectPath || runningProjectPath === fullProjectPath) {
-                console.log(`Summer Engine is already running (v${health.version}) on port ${port}`);
-                if (health.project_name) {
-                    console.log(`  Project: ${health.project_name}`);
-                }
-                if (health.project_path) {
-                    console.log(`  Path: ${health.project_path}`);
-                }
-                return;
-            }
-            console.log(`Summer Engine is already running (v${health.version}) on port ${port}`);
-            console.log(`  Current project: ${health.project_path ?? health.project_name ?? "unknown"}`);
-            console.error(`Refusing to launch a second editor for: ${fullProjectPath}\n` +
-                "Close or switch the current Summer Engine project first, then run this command again.");
-            process.exitCode = 1;
-            return;
-        }
-        const resolved = resolveRunBinary(opts.bin);
-        if (resolved.binary === null) {
-            console.error(resolved.error);
-            process.exitCode = 1;
-            return;
-        }
-        const binary = resolved.binary;
-        if (resolved.source !== "installed") {
-            console.log(`Using engine from ${resolved.source}: ${binary}`);
-        }
-        // The engine is not running yet, so /api/health cannot tell us whether
-        // it honours --summer-background. Ask THAT binary itself (`--help`, which
-        // exits headless before any window exists; cached per install) with the
-        // installed version as pre-check and fallback; pass the flag only when
-        // the engine is known to support it. Focus launches have nothing to decide.
-        const support = posture === "background" ? await detectBackgroundLaunchSupport(binary) : backgroundLaunchSupport(null);
-        const plan = planLaunch(posture, support);
-        const args = ["--editor", ...plan.extraArgs];
-        if (fullProjectPath) {
-            args.unshift("--path", fullProjectPath);
-        }
-        if (plan.note)
-            console.log(plan.note);
-        console.log(plan.background
-            ? "Launching Summer Engine in the background (the window will not take focus until you click it)..."
-            : "Launching Summer Engine...");
-        // Direct executable, never `open -a`: LaunchServices activates whatever
-        // it opens and would defeat --summer-background regardless of flags.
-        const child = spawn(binary, args, { detached: true, stdio: "ignore" });
-        // A stale or non-executable binary surfaces as an async "error" event
-        // (ENOENT/EACCES). Without a listener Node raises it as an uncaught
-        // exception with a raw stack; catch it and report the path instead.
-        const spawnState = { error: null };
-        child.on("error", (error) => {
-            spawnState.error = error;
-        });
-        child.unref();
-        // Wait for engine to start responding
-        const startTime = Date.now();
-        const timeout = 20000;
-        while (Date.now() - startTime < timeout) {
-            await sleep(500);
-            if (spawnState.error) {
-                reportSpawnFailure(spawnState.error, binary);
-                return;
-            }
-            const newPort = await getApiPort();
-            const h = await checkEngineHealth(newPort);
-            if (h) {
-                console.log(`Summer Engine running (v${h.version}) on port ${newPort}`);
-                if (h.project_name) {
-                    console.log(`  Project: ${h.project_name}`);
-                }
-                // Background was wanted but the flag was withheld, and the running
-                // engine now says (capabilities.launchPostures, else its version)
-                // that it would have honoured it: say so, so the next launch can be
-                // fixed rather than silently repeating a focus launch.
-                if (posture === "background" && !plan.background) {
-                    const advert = advertisedBackgroundPosture(h.capabilities);
-                    const wouldHonour = advert ?? backgroundLaunchSupport(h.version).supported;
-                    if (wouldHonour) {
-                        console.log(`  Note: this engine (v${h.version}) ${advert ? "advertises" : "should support"} background launches (${BACKGROUND_LAUNCH_FLAG}, ${BACKGROUND_LAUNCH_MIN_ENGINE_VERSION}+), but that could not be confirmed before launch on this platform.`);
-                    }
-                }
-                return;
-            }
-        }
-        if (spawnState.error) {
-            reportSpawnFailure(spawnState.error, binary);
-            return;
-        }
+    const result = await launchEditor({
+        projectPath: fullProjectPath,
+        posture,
+        bin: opts.bin,
+        out: { log: (line) => console.log(line), error: (line) => console.error(line) },
+    });
+    if (result.status === "starting") {
         console.log("Summer Engine launched but API not responding yet.\n" +
             "It may still be loading. Run 'summer status' to check.");
-    });
+    }
+    else if (result.status !== "running") {
+        process.exitCode = 1;
+    }
 });
-function reportSpawnFailure(error, binary) {
-    const code = error.code ?? error.message;
-    console.error(`Summer Engine binary failed to start: ${code} (${binary})\n` +
-        "Re-run 'summer install' to repair the installation, or check the binary path.");
-    process.exitCode = 1;
-}

package/dist/cli/commands/tool.js

@@ -14,6 +14,7 @@ import { PACKAGE_ROOT } from "../../core/package-root.js";
 import { Command, Option } from "commander";
 import { ToolDispatchError, ToolResultError, dispatchTool, listToolDispatches, resolveToolDispatch, } from "../../core/capabilities/tool-dispatch.js";
 import { c } from "../../core/format.js";
+import { noteCliHosted, noteCliTool } from "../../core/cli-usage.js";
 import { callHostedToolForCli, hostedResultPayload, listHostedToolsForCli, } from "../../core/hosted-mcp.js";
 /** The hosted store and publishing tools (Summer Engine MCP); replaceable in tests. */
 export const hostedCli = { list: listHostedToolsForCli, call: callHostedToolForCli };
@@ -116,6 +117,8 @@ export const toolCommand = new Command("tool")
     const entry = resolveToolForCli(name);
     if (!entry) {
         // Not a local tool: the hosted store and publishing tools, with the store sign-in.
+        // Summer's server records the call itself (X-Summer-Client-Surface: cli).
+        noteCliHosted();
         const hosted = await hostedCli.call(name, parseJsonArgs(options.args ?? options.json));
         if (hosted.status === "called") {
             const payload = hostedResultPayload(hosted.result);
@@ -135,6 +138,7 @@ export const toolCommand = new Command("tool")
         console.error("Note: 'summer tool --json <args>' is deprecated; use --args <json>.");
     }
     const args = parseJsonArgs(options.args ?? options.json);
+    noteCliTool(entry.name);
     let result;
     try {
         result = await dispatchTool(entry.slug, args);

package/dist/cli/index.js

@@ -6,6 +6,7 @@ import { runCommand } from "./commands/run.js";
 import { openCommand } from "./commands/open.js";
 import { installCommand } from "./commands/install.js";
 import { createCommand } from "./commands/create.js";
+import { devCommand } from "./commands/dev.js";
 import { listCommand } from "./commands/list.js";
 import { memoryCommand } from "./commands/memory.js";
 import { skillsCommand } from "./commands/skills.js";
@@ -15,12 +16,14 @@ import { planCommand } from "./commands/plan.js";
 import { debugCommand } from "./commands/debug.js";
 import { configCommand } from "./commands/config.js";
 import { eventsCommand } from "./commands/events.js";
+import { previewCommand } from "./commands/preview.js";
 import { toolCommand } from "./commands/tool.js";
 import { opsCliCommands } from "./commands/ops.js";
 import { getBanner } from "./banner.js";
 import { runRootAction } from "./root-action.js";
 import { c, sym } from "../core/format.js";
 import { resolveSurface } from "../core/tool-profiles.js";
+import { trackCommandUsage } from "./command-usage.js";
 import { TOOLKIT_VERSION as version } from "../core/version.js";
 /**
  * Build and run the summer CLI. The `mcp` command is injected by the bin
@@ -35,6 +38,7 @@ export function runCli(mcpCommand) {
         .action((_opts, command) => {
         runRootAction(command.args, () => printIntro(version));
     });
+    program.addCommand(devCommand);
     program.addCommand(installCommand);
     program.addCommand(loginCommand);
     program.addCommand(logoutCommand);
@@ -52,12 +56,14 @@ export function runCli(mcpCommand) {
     program.addCommand(planCommand);
     program.addCommand(configCommand);
     program.addCommand(eventsCommand);
+    program.addCommand(previewCommand);
     program.addCommand(toolCommand);
     // The 4.0 operation catalog (`summer <area> <action>`); SUMMER_SURFACE=v3 leaves it out.
     if (resolveSurface(undefined) === "v4") {
         for (const command of opsCliCommands())
             program.addCommand(command);
     }
+    trackCommandUsage(program);
     program.parseAsync().catch((err) => {
         console.error(err instanceof Error ? err.message : String(err));
         process.exit(1);
@@ -74,6 +80,7 @@ function printIntro(version) {
     console.log(`     ${c.brand("\"Install Summer Engine and let's make a game.\"")}`);
     console.log("");
     console.log(`     ${c.bold("Manual commands")}`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest dev   ${c.dim("# install, create a starter project, open it")}`);
     console.log(`     ${c.dim("$")} npx -y summer-engine@latest setup claude-code --yes`);
     console.log(`     ${c.dim("$")} npx -y summer-engine@latest create 3d-basic my-game`);
     console.log(`     ${c.dim("$")} npx -y summer-engine@latest plan make a small arena shooter`);

package/dist/core/agent-host.d.ts

@@ -36,6 +36,7 @@ export interface McpClientInfo {
 }
 type Env = Record<string, string | undefined>;
 /** The opt-out switches, the same two the library feedback mailbox honors. */
+/** SUMMER_NO_TELEMETRY or DO_NOT_TRACK set to 1, true, yes or on. */
 export declare function isTelemetryDisabled(env?: Env): boolean;
 /** Lowercase `[a-z0-9-]`, at most 40 characters: the server's host id shape. */
 export declare function sanitizeHostId(raw: string): string;
@@ -43,12 +44,17 @@ export declare function sanitizeHostId(raw: string): string;
 export declare function hostFromClientName(name: string | undefined | null): string | null;
 /** AI_AGENT ("<name>_<version>_<mode>") first, then the per-host variables. */
 export declare function hostFromEnv(env: Env): string | null;
+/** `mcp` inside `summer mcp` (it registers its handshake), `cli` for every other command. */
+export declare function processSurface(): ClientSurface;
 export declare function registerMcpClientSource(source: (() => McpClientInfo | undefined) | null): void;
 export declare function currentMcpClient(): McpClientInfo | undefined;
 export declare function resolveAgentHost(env?: Env, client?: McpClientInfo | undefined): AgentHost;
 interface ToolContext {
     tool: string;
     surface: ClientSurface;
+    /** Usage fields the call noted for its usage line (telemetry.ts noteToolUsage);
+     *  one object shared with any tool it runs, so the outer call's line has them. */
+    usage: Record<string, unknown>;
 }
 /** Run one tool call so every Summer request it makes names the tool and surface. */
 export declare function runWithToolContext<T>(tool: string, surface: ClientSurface, fn: () => T): T;

package/dist/core/agent-host.js

@@ -27,8 +27,10 @@ export const AGENT_HOST_VERSION_HEADER = "X-Summer-Agent-Host-Version";
 export const MCP_TOOL_HEADER = "X-Summer-MCP-Tool";
 export const AGENT_HOST_OVERRIDE_ENV = "SUMMER_AGENT_HOST";
 /** The opt-out switches, the same two the library feedback mailbox honors. */
+/** SUMMER_NO_TELEMETRY or DO_NOT_TRACK set to 1, true, yes or on. */
 export function isTelemetryDisabled(env = process.env) {
-    return env.SUMMER_NO_TELEMETRY === "1" || env.DO_NOT_TRACK === "1";
+    const on = (value) => value !== undefined && /^(1|true|yes|on)$/i.test(value.trim());
+    return on(env.SUMMER_NO_TELEMETRY) || on(env.DO_NOT_TRACK);
 }
 const set = (env, key) => {
     const value = env[key];
@@ -128,6 +130,10 @@ export function hostFromEnv(env) {
 // The MCP server registers a getter; it is read at request time, after the
 // initialize handshake has given the client's name and version.
 let mcpClientSource = null;
+/** `mcp` inside `summer mcp` (it registers its handshake), `cli` for every other command. */
+export function processSurface() {
+    return mcpClientSource ? "mcp" : "cli";
+}
 export function registerMcpClientSource(source) {
     mcpClientSource = source;
 }
@@ -154,7 +160,7 @@ export function resolveAgentHost(env = process.env, client = currentMcpClient())
 const toolContext = new AsyncLocalStorage();
 /** Run one tool call so every Summer request it makes names the tool and surface. */
 export function runWithToolContext(tool, surface, fn) {
-    return toolContext.run({ tool, surface }, fn);
+    return toolContext.run({ tool, surface, usage: toolContext.getStore()?.usage ?? {} }, fn);
 }
 /** The tool call running now, if any (a tool that runs inside another one sees the outer call). */
 export function currentToolContext() {
@@ -168,7 +174,7 @@ const headerValue = (value, max) => value.replace(/[^\x20-\x7e]/g, "").trim().sl
  */
 export function summerRequestHeaders(options = {}, env = process.env) {
     const context = toolContext.getStore();
-    const surface = context?.surface ?? options.surface ?? (mcpClientSource ? "mcp" : "cli");
+    const surface = context?.surface ?? options.surface ?? processSurface();
     const headers = {
         "X-Summer-Client": "summer-cli",
         "X-Summer-Client-Version": TOOLKIT_VERSION,

package/dist/core/api-client.d.ts

@@ -45,6 +45,14 @@ export type EngineSnapshot = {
      *  (item 4, client-side drift check). */
     projectMismatch?: boolean;
 };
+/** Options for a viewport or game capture. */
+export type SnapshotOptions = {
+    /** Write the frame into the snapshots folder and return its localPath
+     *  (default true). The live preview (`summer preview`) passes false: it
+     *  sends each frame straight to the browser, so polling a few frames a
+     *  second never fills the temp folder. */
+    saveFile?: boolean;
+};
 type EngineTargetIdentity = {
     instanceId?: string;
     projectId?: string;
@@ -199,8 +207,8 @@ export declare class EngineApiClient {
      * plain error rather than silently claiming "bridge required".
      */
     private _bridgeRequiredFromResponse;
-    viewportSnapshot(): Promise<EngineSnapshot>;
-    gameSnapshot(): Promise<EngineSnapshot>;
+    viewportSnapshot(options?: SnapshotOptions): Promise<EngineSnapshot>;
+    gameSnapshot(options?: SnapshotOptions): Promise<EngineSnapshot>;
     /**
      * Offscreen scene render via the `ScenePreview` op over /api/ops (no game
      * boot; physics/animations are static). Mirrors the web previewScene op input

package/dist/core/api-client.js

@@ -7,6 +7,7 @@ import { asRecord, boolFrom, numberFrom, stringFrom } from "./util/json.js";
 import { classifyOpsResponse, pollOpToTerminal, } from "./async-op-lifecycle.js";
 import { pickPlayDeterminism } from "./capabilities/play-determinism.js";
 import { honestSceneReceipt } from "./capabilities/engine-receipt.js";
+import { noteBoundProject } from "./usage-fields.js";
 function findSnapshotPayload(value) {
     const record = asRecord(value);
     if (!record)
@@ -139,6 +140,7 @@ export class EngineApiClient {
                 projectIdHash: connection.health.projectIdHash,
             }, { ...effective });
             client.lastHealth = connection.health;
+            noteBoundProject(connection.health.projectIdHash);
             return client;
         }
         // Bind to whatever project is open right now. On a genuine engine restart the
@@ -157,6 +159,7 @@ export class EngineApiClient {
                     projectIdHash: health.projectIdHash,
                 });
                 client.lastHealth = health;
+                noteBoundProject(health.projectIdHash);
                 return client;
             }
         }
@@ -169,6 +172,7 @@ export class EngineApiClient {
             projectIdHash: connection.health.projectIdHash,
         });
         client.lastHealth = connection.health;
+        noteBoundProject(connection.health.projectIdHash);
         client.registryDiscovery = { ...discovery };
         return client;
     }
@@ -215,6 +219,7 @@ export class EngineApiClient {
             projectId: health.projectId,
             projectIdHash: health.projectIdHash,
         };
+        noteBoundProject(health.projectIdHash);
         return this.targetIdentity.projectIdHash;
     }
     /** Identity to attach to a MUTATING command's options so the engine can reject
@@ -584,7 +589,7 @@ export class EngineApiClient {
         await writeFile(localPath, buffer);
         return localPath;
     }
-    async snapshot(kind) {
+    async snapshot(kind, options = {}) {
         // Block E: /api/snapshot/* is queued (GET -> 202 -> poll /api/ops/result).
         // The terminal result is the apply dict; the image rides as base64 inside it
         // (no raw-binary channel). Legacy/dormant engines answer 200 synchronously
@@ -609,11 +614,11 @@ export class EngineApiClient {
         catch (err) {
             return { ok: false, error: err instanceof Error ? err.message : String(err) };
         }
-        return this._parseSnapshotResponse(response, kind);
+        return this._parseSnapshotResponse(response, kind, options.saveFile !== false);
     }
     /** Shared: turn an ops/snapshot response envelope into an EngineSnapshot.
      *  Used by viewport/game snapshots and by scenePreview. */
-    async _parseSnapshotResponse(response, kind) {
+    async _parseSnapshotResponse(response, kind, saveFile = true) {
         const payload = findSnapshotPayload(response);
         if (!payload) {
             return {
@@ -635,7 +640,7 @@ export class EngineApiClient {
         }
         const { format, mime, ext } = snapshotFormat(payload);
         const buffer = Buffer.from(base64, "base64");
-        const localPath = await this.writeSnapshotFile(kind, buffer, ext);
+        const localPath = saveFile ? await this.writeSnapshotFile(kind, buffer, ext) : undefined;
         // Client-side identity drift check (item 4). Current engines validate the
         // identity query on snapshot reads, but older builds may ignore it. Re-read
         // health and compare to the bound hash so a frame from a switched project is
@@ -701,11 +706,11 @@ export class EngineApiClient {
             error: stringFrom(body.error) ?? "Game snapshots require the desktop bridge async transport.",
         };
     }
-    async viewportSnapshot() {
-        return this.snapshot("viewport");
+    async viewportSnapshot(options) {
+        return this.snapshot("viewport", options);
     }
-    async gameSnapshot() {
-        return this.snapshot("game");
+    async gameSnapshot(options) {
+        return this.snapshot("game", options);
     }
     /**
      * Offscreen scene render via the `ScenePreview` op over /api/ops (no game

package/dist/core/capabilities/agent-playbook.js

@@ -17,6 +17,7 @@ export function buildAgentPlaybook(options = {}) {
         // VISUAL VERIFICATION — pixels are the second signal.
         // ------------------------------------------------------------------
         visualVerification: [
+            "Opening the Summer editor and playing the game in a window is allowed and expected: summer_play, then summer_screenshot or summer_frame_shot to see the result. Close what you opened when you are done (summer_stop); one editor at a time.",
             "Use summer_screenshot BEFORE making changes to see the current state, and AFTER every mutation batch or asset import to verify the result. Two signals, two jobs: summer_snapshot_diff proves exact structural facts; the screenshot proves appearance. Run both.",
             "For lighting, mood, environment, or emissive materials, use summer_screenshot target:'scene' framing:'camera' — it renders through the scene's OWN camera with its REAL WorldEnvironment. The preset framings (iso/top/...) substitute a flat preview environment and CANNOT verify lighting.",
             "When executing multiple batches, screenshot between them — catch the wrong turn at batch 2, not batch 7.",

package/dist/core/capabilities/apps.d.ts

@@ -18,9 +18,9 @@ export declare const APP_DOCK_SLOTS: readonly ["left", "right", "bottom"];
 export declare const appGuideArgsSchema: z.ZodObject<{
     section: z.ZodDefault<z.ZodEnum<["all", "overview", "manifest", "sdk", "kit", "layout", "design", "examples", "types"]>>;
 }, "strip", z.ZodTypeAny, {
-    section: "all" | "examples" | "kit" | "layout" | "manifest" | "overview" | "sdk" | "design" | "types";
+    section: "examples" | "all" | "kit" | "layout" | "manifest" | "overview" | "sdk" | "design" | "types";
 }, {
-    section?: "all" | "examples" | "kit" | "layout" | "manifest" | "overview" | "sdk" | "design" | "types" | undefined;
+    section?: "examples" | "all" | "kit" | "layout" | "manifest" | "overview" | "sdk" | "design" | "types" | undefined;
 }>;
 export declare const appListArgsSchema: z.ZodObject<{
     workspaceId: z.ZodOptional<z.ZodString>;
@@ -112,10 +112,10 @@ export declare const appEventsArgsSchema: z.ZodObject<{
     after: number;
     timeoutSeconds: number;
     appId: string;
-    kinds?: ("error" | "agent" | "tool" | "feedback")[] | undefined;
+    kinds?: ("error" | "tool" | "agent" | "feedback")[] | undefined;
 }, {
     appId: string;
-    kinds?: ("error" | "agent" | "tool" | "feedback")[] | undefined;
+    kinds?: ("error" | "tool" | "agent" | "feedback")[] | undefined;
     after?: number | undefined;
     timeoutSeconds?: number | undefined;
 }>;
@@ -195,8 +195,8 @@ export declare const appScreenshotArgsSchema: z.ZodObject<{
     appId: string;
     fullPage: boolean;
     version?: number | undefined;
-    params?: Record<string, string> | undefined;
     out?: string | undefined;
+    params?: Record<string, string> | undefined;
     steps?: {
         wait?: number | undefined;
         press?: string | undefined;
@@ -205,10 +205,10 @@ export declare const appScreenshotArgsSchema: z.ZodObject<{
 }, {
     appId: string;
     version?: number | undefined;
+    out?: string | undefined;
+    params?: Record<string, string> | undefined;
     width?: number | undefined;
     height?: number | undefined;
-    params?: Record<string, string> | undefined;
-    out?: string | undefined;
     theme?: "light" | "dark" | undefined;
     steps?: {
         wait?: number | undefined;
@@ -234,9 +234,9 @@ export declare const appDataArgsSchema: z.ZodObject<{
 }, {
     appId: string;
     ops?: Record<string, unknown>[] | undefined;
-    limit?: number | undefined;
     as?: "seed" | "agent" | undefined;
     collection?: string | undefined;
+    limit?: number | undefined;
     after?: string | undefined;
 }>;
 export declare const appToolsArgsSchema: z.ZodObject<{
@@ -251,8 +251,8 @@ export declare const appCallArgsSchema: z.ZodObject<{
     tool: z.ZodString;
     input: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
-    input: Record<string, unknown>;
     tool: string;
+    input: Record<string, unknown>;
     appId: string;
 }, {
     tool: string;

package/dist/core/capabilities/asset-import.d.ts

@@ -14,6 +14,8 @@ export type GatewayAsset = {
     pack?: string | null;
     packSlug?: string | null;
     importUrl?: string;
+    /** A video's Ogg Theora rendition (summerengine.com names it): the one video file Summer Engine can load. */
+    ogvUrl?: string | null;
     downloadUrl?: string;
     fileName?: string | null;
     mimeType?: string | null;
@@ -36,7 +38,6 @@ export interface ImportResolvedAssetArgs {
  *  packs) and, for 3D models with a `parent`, instantiate it into `scenePath`
  *  and save. Throws with a user-facing message on any engine refusal. */
 export declare function importResolvedAsset(client: EngineApiClient, args: ImportResolvedAssetArgs): Promise<{
-    success: boolean;
     assetId: string;
     asset: string;
     type: string;
@@ -45,4 +46,6 @@ export declare function importResolvedAsset(client: EngineApiClient, args: Impor
     parent: string | null;
     scenePath: string | null;
     sceneReceipt: unknown;
+    note?: string | undefined;
+    success: boolean;
 }>;

package/dist/core/capabilities/asset-import.js

@@ -1,4 +1,5 @@
 import { ToolInputError } from "../tool-errors.js";
+import { importUrls, ogvResPath } from "./video-ogv.js";
 /** Kenney Cloudinary URL pattern: .../summer_art/kenney/3d/{pack-slug}/{filename}.glb */
 const KENNEY_URL_PATTERN = /\/kenney\/3d\/([^/]+)\//;
 function getPackSlugFromUrl(fileUrl) {
@@ -49,6 +50,12 @@ async function buildImportEntriesForAsset(asset, targetPath) {
     const fileUrl = asset.importUrl || asset.fileUrl;
     if (!fileUrl)
         throw new Error("Asset has no import URL.");
+    if (asset.ogvUrl) {
+        // A video: import its .ogv rendition, the one video file Summer Engine can load.
+        const name = asset.fileName || fileNameFromUrl(asset.fileUrl || fileUrl);
+        const path = ogvResPath({ url: asset.fileUrl || fileUrl, path: targetPath ?? `res://assets/videos/${name}` });
+        return { importPath: path, imports: [{ url: asset.ogvUrl, path }] };
+    }
     const fileName = targetPath?.split("/").pop() || asset.fileName || fileNameFromUrl(fileUrl);
     const packSlug = asset.packSlug ?? getPackSlugFromUrl(fileUrl) ?? "misc";
     if (targetPath) {
@@ -88,12 +95,11 @@ export async function importResolvedAsset(client, args) {
     if (parent && !scenePath) {
         throw new ToolInputError("scenePath is required when importing an asset into a scene");
     }
-    const { imports, importPath } = await buildImportEntriesForAsset(asset, path);
-    const importResult = imports.length === 1
-        ? await client.executeOps([
-            { op: "ImportFromUrl", url: imports[0].url, path: imports[0].path },
-        ])
-        : await client.executeOps([{ op: "ImportFromUrlBatch", imports }]);
+    const { imports, importPath: plannedPath } = await buildImportEntriesForAsset(asset, path);
+    // A video without a rendition is converted to .ogv on the way in (video-ogv.ts).
+    const importResult = await importUrls(client, imports, { batch: imports.length > 1 });
+    const conversions = importResult?.videoConversions;
+    const importPath = conversions?.[conversions.length - 1]?.to ?? plannedPath;
     const importReceipts = importResult?.results ?? [];
     const importFailure = importReceipts.find((receipt) => receipt?.ok === false);
     if (importResult?.status === "error" || importFailure) {
@@ -122,6 +128,9 @@ export async function importResolvedAsset(client, args) {
     }
     return {
         success: true,
+        ...(conversions?.length || asset.ogvUrl
+            ? { note: `Summer Engine plays video only as Ogg Theora (.ogv), so the video was imported as ${importPath}. Load it from that path.` }
+            : {}),
         assetId: asset.id,
         asset: asset.title,
         type: asset.type,

package/dist/core/capabilities/capture-gameplay.js

@@ -639,6 +639,6 @@ export async function captureGameplay(input, overrides = {}) {
         ...(imported && importReason ? { importReason } : {}),
         durationMs: deps.now().getTime() - started.getTime(),
         ...(warnings.length ? { warnings } : {}),
-        next: "Look at each frame before using it. For the store: upload with summer_upload_image_begin/complete and set them as desktop.screenshots or mobile.screenshots (summer_store_set_art). The game's own HUD may show; add no captions, logos or overlays.",
+        next: "Look at each frame before using it. For the store: upload with assets.upload_begin and assets.upload_complete and set them as desktop.screenshots or mobile.screenshots (store.set_art). The game's own HUD may show; add no captions, logos or overlays.",
     };
 }