summer-engine 4.3.0 → 4.5.0

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;
 }>;

package/dist/core/capabilities/content-make/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * content.make on the person's computer: one finished piece for a game,
+ * copied beat for beat from a reference in Summer's library, from the
+ * team's own footage, into the team's Review.
+ *
+ *   pick -> study -> footage -> plan -> voice -> render -> checks -> compare -> upload
+ *
+ * It runs directly (an agent's "clip what we just built"), or it claims the
+ * oldest make request Summer's server queued for the team (the daily
+ * scheduler, a Change pressed on Today) and reports every stage to it. A
+ * make that names revisePieceId revises that piece instead of saving a new one.
+ *
+ * Every stage leaves its record in the piece's work folder, so a run that
+ * stops (missing words, a missing voice-over, a network drop) continues
+ * from there with the same workDir. Words are the one thing it never makes
+ * up: our lines come from the caller (an agent, or the person), and the
+ * reference's own words never reach the piece.
+ */
+/** The stage names Summer's server shows live on Today (content.update_make). */
+export type Stage = "pick" | "study" | "footage" | "plan" | "voice" | "render" | "checks" | "compare" | "upload";
+export interface ContentMakeInput {
+    teamId?: string;
+    contentGameId?: string;
+    referenceId?: string;
+    referenceFile?: string;
+    /** What to make it about (the commits since the last piece, "the new boss"): weighs the pick. */
+    note?: string;
+    /** Claim a queued make request (the named one, else the team's oldest) and make it. */
+    claim?: boolean;
+    /** The make request to claim, from content.make. */
+    requestId?: string;
+    /** The kit learnings (content.get_kit) the words and choices applied. */
+    learningIds?: string[];
+    footage?: string[];
+    voiceFile?: string;
+    lines?: string[];
+    title?: string;
+    caption?: string;
+    hashtags?: string[];
+    music?: string;
+    font?: string;
+    workDir?: string;
+    out?: string;
+    repo?: string;
+    stage?: "plan" | "all";
+    upload?: boolean;
+    replan?: boolean;
+    status?: "draft" | "in_review";
+    face?: "cli" | "mcp";
+}
+/** One operation on Summer's server: its answer envelope. */
+export type CloudCall = (op: string, input: Record<string, unknown>) => Promise<{
+    ok: boolean;
+    status?: string;
+    result?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}>;
+export interface ContentMakeDeps {
+    cloud: CloudCall;
+    put: (url: string, file: string, contentType: string) => Promise<void>;
+    progress: (stage: Stage, message: string) => void;
+    now: () => Date;
+    cwd: string;
+}
+export declare function defaultDeps(face?: "cli" | "mcp"): ContentMakeDeps;
+export interface ContentMakeResult {
+    ok: true;
+    status: "saved" | "planned" | "needs_words" | "needs_changes" | "needs_voice" | "rendered" | "nothing_queued" | "cannot_make";
+    workDir?: string;
+    referenceId?: string;
+    next?: string;
+    [key: string]: unknown;
+}
+/** The input from a tool call's arguments (MCP or CLI), unknown fields left out. */
+export declare function contentMakeInput(args: Record<string, unknown>): ContentMakeInput;
+/** Makes one piece; see the header of this file. */
+export declare function contentMake(input: ContentMakeInput, deps?: ContentMakeDeps): Promise<ContentMakeResult>;