summer-engine 4.3.0 → 4.6.0

package/dist/cli/commands/setup.js

@@ -2,8 +2,10 @@ import { spawnSync } from "child_process";
 import { existsSync, readFileSync } from "fs";
 import { relative } from "path";
 import { Command, Option } from "commander";
-import { configureAgentMcp, configureSummerGamesMcp, resolveAgentSelection, resolveConfigScope, supportedAgents, } from "../../installer/agent-config.js";
+import { configureAgentMcp, configureSummerGamesMcp, resolveAgentSelection, resolveBundledRuntime, resolveConfigScope, supportedAgents, } from "../../installer/agent-config.js";
 import { previewNote, setupSkills } from "../../installer/setup.js";
+import { detectAgents } from "../../installer/agent-detect.js";
+import { SetupError, toStepError } from "../../installer/setup-error.js";
 import { printDoctorResult, runDoctor } from "../../core/capabilities/doctor.js";
 import { brandLine, c, sym, tildeify } from "../../core/format.js";
 import { TOOLKIT_VERSION as cliVersion } from "../../core/version.js";
@@ -23,6 +25,8 @@ const MCP_ENTRY_FLAGS = [
     ["localDev", "--local-dev"],
     ["channel", "--channel"],
     ["profile", "--profile"],
+    ["runtime", "--runtime"],
+    ["packageDir", "--package-dir"],
 ];
 export const setupCommand = new Command("setup")
     .description("Configure Summer Engine for an AI agent and run diagnostics. For agents that can sign in to it, it also adds Summer Games (summer-games). --cli installs the skills only: the agent runs summer commands in its shell, with no MCP server.")
@@ -32,6 +36,9 @@ export const setupCommand = new Command("setup")
     .option("--dry-run", "Show planned changes without writing files")
     .option("--print", "Print the MCP config snippet instead of writing files")
     .option("--local-dev", "Point the agent at this checkout's built CLI (node <repo>/dist/bin/summer.js mcp) instead of npx summer-engine@latest — for testing unpublished builds. SUMMER_DEV=1 does the same.")
+    .option("--runtime <node>", "Run the MCP server with this node executable instead of npx: <node> <package-dir>/dist/bin/summer.js mcp. Needs --package-dir. For installers that ship their own Node.js")
+    .option("--package-dir <dir>", "The summer-engine package folder (package.json and dist/bin/summer.js) that --runtime runs")
+    .option("--detect", "List every supported agent: installed or not, its MCP config file, and whether it already lists summer-engine. Writes nothing; takes no agent. Use with --json")
     .option("--channel <dist-tag>", "npm dist-tag or exact version the agent's MCP entry runs: npx -y summer-engine@<dist-tag> mcp (default latest; a CLI newer than npm latest pins next when next is this version, else this version). SUMMER_CHANNEL does the same.")
     .option("--yes", "Apply practical setup steps without prompting")
     .option("--no-games", "Do not add the Summer Games MCP (summer-games: friends, parties and messages as you, signed in through summer.games)")
@@ -49,8 +56,52 @@ export const setupCommand = new Command("setup")
     // Pre-reversal opt-in, kept one release as a hidden no-op so old scripts still parse.
     .addOption(new Option("--include-preview", "No-op: preview skills install by default").hideHelp())
     .action(async (agentArg, opts) => {
-    const agent = resolveAgentSelection(agentArg, opts.agent);
-    const scope = resolveConfigScope(opts.scope);
+    if (opts.detect) {
+        runDetect(agentArg, opts);
+        return;
+    }
+    if (!opts.json) {
+        await setupAgent(agentArg, opts);
+        return;
+    }
+    // --json: one JSON document on stdout, also when setup cannot start.
+    try {
+        await setupAgent(agentArg, opts);
+    }
+    catch (error) {
+        console.log(JSON.stringify({ ok: false, error: toStepError(error, "setup_failed"), steps: [] }, null, 2));
+        process.exit(1);
+    }
+});
+/**
+ * Runs one step. With --json a throw becomes the step's coded error and the
+ * other steps still run; without it the throw ends setup as it always did.
+ */
+async function runStep(json, fallbackCode, run) {
+    if (!json)
+        return { value: await run() };
+    try {
+        return { value: await run() };
+    }
+    catch (error) {
+        return { value: null, error: toStepError(error, fallbackCode) };
+    }
+}
+async function setupAgent(agentArg, opts) {
+    let agent;
+    try {
+        agent = resolveAgentSelection(agentArg, opts.agent);
+    }
+    catch (error) {
+        throw new SetupError("unknown_agent", error instanceof Error ? error.message : String(error));
+    }
+    let scope;
+    try {
+        scope = resolveConfigScope(opts.scope);
+    }
+    catch (error) {
+        throw new SetupError("invalid_scope", error instanceof Error ? error.message : String(error));
+    }
     if (opts.removeAllowRules) {
         await removeCliAllowRules(agent, scope, opts);
         return;
@@ -63,8 +114,14 @@ export const setupCommand = new Command("setup")
     if (opts.allowRules)
         console.error(`  ${sym.warn()}  ${c.yellow("--allow-rules works with --cli only (the MCP server asks through the agent's own tool approvals); no rules were added.")}`);
     const profile = resolveSetupProfile(opts);
-    const defaultChannel = await resolveDefaultChannel(cliVersion);
-    const config = await configureAgentMcp({
+    const runtime = resolveBundledRuntime(opts.runtime, opts.packageDir);
+    if (runtime && (opts.localDev || opts.channel)) {
+        throw new SetupError("invalid_option", `--runtime runs a bundled summer-engine; leave out ${opts.localDev ? "--local-dev" : "--channel"}.`);
+    }
+    const json = Boolean(opts.json);
+    // A bundled runtime runs the package beside it, so npm's tags do not matter (and no network call is made).
+    const defaultChannel = runtime ? { channel: "latest" } : await resolveDefaultChannel(cliVersion);
+    const mcp = await runStep(json, "mcp_entry_failed", () => configureAgentMcp({
         agent,
         scope,
         dryRun: opts.dryRun,
@@ -72,14 +129,19 @@ export const setupCommand = new Command("setup")
         localDev: Boolean(opts.localDev) || process.env.SUMMER_DEV === "1",
         channel: opts.channel ?? process.env.SUMMER_CHANNEL ?? defaultChannel.channel,
         profile,
-    });
-    const games = opts.games === false || opts.assetsOnly || opts.print
-        ? null
-        : await configureSummerGamesMcp({ agent, scope, dryRun: opts.dryRun });
-    if (!opts.channel && !process.env.SUMMER_CHANNEL && defaultChannel.note && !opts.print) {
-        console.log(`  ${c.dim(defaultChannel.note)}`);
-    }
-    const skills = setupSkills(agent, {
+        runtime: runtime ?? undefined,
+    }));
+    const config = mcp.value;
+    const gamesSkipped = opts.games === false || opts.assetsOnly || opts.print;
+    const gamesStep = gamesSkipped
+        ? { value: null }
+        : await runStep(json, "summer_games_failed", () => configureSummerGamesMcp({ agent, scope, dryRun: opts.dryRun }));
+    const games = gamesStep.value;
+    if (!runtime && !opts.channel && !process.env.SUMMER_CHANNEL && defaultChannel.note && !opts.print) {
+        // On stderr with --json, so stdout stays one JSON document.
+        (json ? console.error : console.log)(`  ${c.dim(defaultChannel.note)}`);
+    }
+    const skillsStep = await runStep(json, "skills_install_failed", () => setupSkills(agent, {
         dryRun: Boolean(opts.dryRun || opts.print),
         yes: Boolean(opts.yes),
         force: Boolean(opts.force),
@@ -87,26 +149,104 @@ export const setupCommand = new Command("setup")
         recommended: Boolean(opts.recommended),
         stableOnly: Boolean(opts.stableOnly),
         assetsOnly: Boolean(opts.assetsOnly),
-    });
-    const projectFiles = setupProjectInstructions(opts);
+    }));
+    const skills = skillsStep.value ?? { status: "failed", message: skillsStep.error?.message ?? "Skill install failed." };
+    const projectStep = await runStep(json, "project_files_failed", () => setupProjectInstructions(opts));
+    const projectFiles = projectStep.value;
     const doctor = await runDoctor({ quiet: true });
-    if (opts.json) {
-        console.log(JSON.stringify({
-            ok: doctor.ok && skills.status !== "failed",
-            config,
-            games,
-            skills,
-            projectFiles,
-            doctor,
-        }, null, 2));
-    }
-    else {
-        printSetupResult(config, games, skills, doctor, projectFiles);
+    if (json) {
+        const steps = [
+            mcpEntryStep(config, mcp.error),
+            summerGamesStep(agent, games, gamesSkipped ? "skipped" : null, gamesStep.error, Boolean(opts.dryRun)),
+            skillsStepResult(skills, skillsStep.error),
+            projectFilesStep(projectFiles, projectStep.error, opts),
+            doctorStep(doctor),
+        ];
+        const ok = steps.every((step) => step.ok);
+        console.log(JSON.stringify({ ok, agent, scope, steps, config, games, skills, projectFiles, doctor }, null, 2));
+        if (!ok)
+            process.exit(1);
+        return;
     }
+    printSetupResult(config, games, skills, doctor, projectFiles);
     if (!doctor.ok || skills.status === "failed") {
         process.exit(1);
     }
-});
+}
+function mcpEntryStep(config, error) {
+    if (!config)
+        return { step: "mcp_entry", ok: false, status: "failed", error: error ?? { code: "mcp_entry_failed", message: "The MCP entry was not written." } };
+    const status = config.print ? "printed" : config.dryRun ? (config.changed ? "planned" : "unchanged") : config.wrote ? "written" : "unchanged";
+    return { step: "mcp_entry", ok: true, status, path: config.path, ...(config.warnings.length ? { warnings: config.warnings } : {}) };
+}
+function summerGamesStep(agent, games, skipped, error, dryRun) {
+    if (error)
+        return { step: "summer_games", ok: false, status: "failed", error };
+    if (skipped)
+        return { step: "summer_games", ok: true, status: "skipped" };
+    // configureSummerGamesMcp returns null only for agents without a Summer Games entry shape.
+    if (!games)
+        return { step: "summer_games", ok: true, status: "not_supported", warnings: [`${agentLabel(agent)} gets no Summer Games entry from setup.`] };
+    const status = games.existingName ? "exists" : dryRun ? (games.changed ? "planned" : "unchanged") : games.wrote ? "written" : "unchanged";
+    return { step: "summer_games", ok: true, status, path: games.path };
+}
+function skillsStepResult(skills, error) {
+    if (skills.status === "failed") {
+        return {
+            step: "skills",
+            ok: false,
+            status: "failed",
+            error: error ?? { code: "skills_install_failed", message: [skills.message, skills.stderr].filter(Boolean).join(" ") },
+        };
+    }
+    return { step: "skills", ok: true, status: skills.status, ...(skills.destination ? { path: skills.destination } : {}) };
+}
+function projectFilesStep(project, error, opts) {
+    if (error)
+        return { step: "project_files", ok: false, status: "failed", error };
+    if (!project) {
+        const skipped = opts.projectFiles === false || opts.print || opts.assetsOnly;
+        return { step: "project_files", ok: true, status: skipped ? "skipped" : "not_in_project" };
+    }
+    // A file setup leaves alone (a link out of the project, a broken Summer block) is a warning, as in the human output.
+    const warnings = project.files.filter((file) => file.reason).map((file) => `${file.path}: ${file.reason}`);
+    return { step: "project_files", ok: true, status: project.written ? "written" : "planned", path: project.root, ...(warnings.length ? { warnings } : {}) };
+}
+function doctorStep(doctor) {
+    if (doctor.ok)
+        return { step: "doctor", ok: true, status: "passed" };
+    const failed = doctor.checks.filter((check) => check.status === "fail");
+    return {
+        step: "doctor",
+        ok: false,
+        status: "failed",
+        error: { code: "doctor_failed", message: failed.map((check) => `${check.label}: ${check.message}`).join("; ") || "Doctor found a problem." },
+    };
+}
+/** `summer setup --detect`: every agent, installed or not, and whether it is linked. Writes nothing. */
+function runDetect(agentArg, opts) {
+    if (agentArg || opts.agent) {
+        const message = "--detect lists every agent; leave out the agent name.";
+        if (!opts.json)
+            throw new Error(message);
+        console.log(JSON.stringify({ ok: false, error: { code: "invalid_option", message }, agents: [] }, null, 2));
+        process.exit(1);
+        return;
+    }
+    const agents = detectAgents();
+    if (opts.json) {
+        console.log(JSON.stringify({ ok: true, os: process.platform, agents }, null, 2));
+        return;
+    }
+    console.log("");
+    for (const agent of agents) {
+        if (agent.status === "legacy" && !agent.installed)
+            continue;
+        const mark = agent.installed ? sym.ok() : c.dim("-");
+        const linked = agent.mcpEntry ? c.dim(`linked  ${tildeify(agent.configPath)}`) : agent.installed ? c.dim(`not linked: summer setup ${agent.id}`) : c.dim("not found");
+        console.log(`  ${mark}  ${agent.label}  ${linked}`);
+    }
+}
 /**
  * `summer setup <agent> --cli`: the skills (the asset skills with --assets-only)
  * and no MCP server, so the agent runs Summer as `summer <area> <action>` in its
@@ -117,7 +257,7 @@ async function setupCliOnly(agent, scope, opts) {
     const spec = agentSpec(agent);
     const mcpFlags = MCP_ENTRY_FLAGS.filter(([key]) => opts[key] !== undefined && opts[key] !== false).map(([, flag]) => flag);
     if (mcpFlags.length > 0) {
-        throw new Error(`${mcpFlags.join(", ")} sets up the MCP entry, and --cli writes none. Leave ${mcpFlags.length === 1 ? "it" : "them"} out, or leave out --cli.`);
+        throw new SetupError("invalid_option", `${mcpFlags.join(", ")} sets up the MCP entry, and --cli writes none. Leave ${mcpFlags.length === 1 ? "it" : "them"} out, or leave out --cli.`);
     }
     const refusal = cliSetupRefusal(spec);
     if (refusal)
@@ -278,11 +418,11 @@ async function recordedMcpEntry(agent, scope) {
 function resolveSetupProfile(opts) {
     const profile = opts.profile === undefined ? undefined : parseProfile(opts.profile);
     if (profile === null) {
-        throw new Error(`Unknown --profile "${opts.profile}". Use one of: ${Object.keys(PROFILES).join(", ")}.`);
+        throw new SetupError("invalid_option", `Unknown --profile "${opts.profile}". Use one of: ${Object.keys(PROFILES).join(", ")}.`);
     }
     if (opts.assetsOnly) {
         if (profile && profile !== "assets")
-            throw new Error("--assets-only uses the assets profile; leave out --profile.");
+            throw new SetupError("invalid_option", "--assets-only uses the assets profile; leave out --profile.");
         return "assets";
     }
     return profile;
@@ -305,7 +445,10 @@ function printSetupResult(config, games, skills, doctor, projectFiles) {
     else {
         console.log(`  ${sym.ok()}  Already linked to ${c.bold(label)}  ${c.dim(tildeify(config.path))}`);
     }
-    if (config.localDev) {
+    if (config.runtime) {
+        console.log(`  ${c.dim("(bundled runtime)")}  MCP server command: ${c.dim(`${config.server.command} ${config.server.args.join(" ")}`)}`);
+    }
+    else if (config.localDev) {
         console.log(`  ${c.dim("(local dev)")}  MCP server command: ${c.dim(`${config.server.command} ${config.server.args.join(" ")}`)}`);
     }
     else if (config.channel !== "latest") {

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,6 +16,7 @@ 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";
@@ -36,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);
@@ -53,6 +56,7 @@ 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") {
@@ -76,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

@@ -52,6 +52,9 @@ export declare function resolveAgentHost(env?: Env, client?: McpClientInfo | und
 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

@@ -160,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() {

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.",
     };
 }

package/dist/core/capabilities/connect-signal.d.ts

@@ -43,14 +43,14 @@ export declare const connectSignalInputSchema: z.ZodObject<{
     method: z.ZodString;
 }, "strict", z.ZodTypeAny, {
     method: string;
-    scenePath: string;
     signal: string;
+    scenePath: string;
     emitter: string;
     receiver: string;
 }, {
     method: string;
-    scenePath: string;
     signal: string;
+    scenePath: string;
     emitter: string;
     receiver: string;
 }>;