summer-engine 3.8.0 → 4.0.0

package/dist/core/capabilities/game-task-plan.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { getSkillRegistry } from "../skills-registry.js";
+import { getSkillRegistry, isAssetSkill } from "../skills-registry.js";
 export const GAME_TASK_MODES = [
     "auto",
     "new-game",
@@ -150,7 +150,7 @@ function addSkill(routes, name, why, weight) {
     }
     routes.push({ name, why, weight });
 }
-function inferSkills(mode, target, goal) {
+function inferSkills(mode, target, goal, engine = true) {
     const text = goal.toLowerCase();
     const routes = [];
     const animationIntent = includesAny(text, [
@@ -182,7 +182,12 @@ function inferSkills(mode, target, goal) {
             "voice",
             "animation clip",
         ]);
-    addSkill(routes, "using-summer", "Baseline workflow for building through Summer CLI/MCP.", 100);
+    if (engine) {
+        addSkill(routes, "using-summer", "Baseline workflow for building through Summer CLI/MCP.", 100);
+    }
+    else {
+        addSkill(routes, "summer-assets", "The asset loop without Summer Engine: reuse, generate, check, download.", 250);
+    }
     if (mode === "debug") {
         addSkill(routes, "debug", "Primary runtime/script/diagnostics loop.", 300);
         addSkill(routes, "investigating-bugs", "Systematic bug investigation workflow.", 220);
@@ -307,6 +312,8 @@ function inferSkills(mode, target, goal) {
     addSkill(routes, "gdscript-patterns", "Use guarded Summer file tools for scripts, then verify through MCP.", 90);
     addSkill(routes, "verification-before-completion", "Do not finish without a clean verification story.", 80);
     return routes
+        // Without engine tools, only the skills that work without them.
+        .filter((route) => engine || isAssetSkill(skillByName().get(route.name)))
         .sort((a, b) => b.weight - a.weight)
         .slice(0, 7)
         .map((route) => {
@@ -372,9 +379,34 @@ function buildMcpToolPlan(mode, target, assetPolicy, verification, goal = "") {
     }
     return { start, mutate, assets, verify };
 }
-function buildUserGates(mode, assetPolicy) {
+/** The plan for a session without engine tools: find, generate, check, hand over a file. */
+function buildAssetsToolPlan(target, assetPolicy, verification) {
+    const assets = ["summer_list_my_assets", "summer_search_assets", "summer_get_asset"];
+    if (assetPolicy !== "no-paid-generation") {
+        const generator = {
+            "3d": "summer_generate_3d",
+            "2d": "summer_generate_image",
+            ui: "summer_generate_image",
+            audio: "summer_generate_audio",
+            animation: "summer_generate_motion",
+        };
+        if (generator[target])
+            assets.push(generator[target]);
+        assets.push("summer_check_job");
+    }
+    assets.push("summer_get_asset_download_url");
+    return {
+        start: ["summer_search_library", "summer_read_library"],
+        mutate: [],
+        assets,
+        verify: verification === "none" ? [] : ["summer_check_job", "summer_get_asset"],
+    };
+}
+function buildUserGates(mode, assetPolicy, engine = true) {
     const gates = [
-        "Ask before destructive scene changes, deleting assets, or changing locked .summer memory.",
+        engine
+            ? "Ask before destructive scene changes, deleting assets, or changing locked .summer memory."
+            : "Ask before deleting or replacing the person's assets.",
     ];
     if (assetPolicy !== "generate-when-clearly-needed") {
         gates.push("Ask before paid generation, rigging, video, or large batch asset creation.");
@@ -395,6 +427,8 @@ export function buildGameTaskPlan(options) {
     const verification = options.verification ?? "full";
     const mode = inferMode(goal, options.mode ?? "auto");
     const target = inferTarget(goal, options.target ?? "auto");
+    if (options.engine === false)
+        return buildAssetsPlan(goal, mode, target, assetPolicy, verification);
     return {
         goal,
         mode,
@@ -431,3 +465,44 @@ export function buildGameTaskPlan(options) {
         ],
     };
 }
+/** summer_start_game_task in a session without engine tools (the assets profile). */
+function buildAssetsPlan(goal, mode, target, assetPolicy, verification) {
+    const needsEngine = mode !== "asset";
+    return {
+        goal,
+        mode,
+        target,
+        assetPolicy,
+        verification,
+        profileNote: "This session has generation and the Summer asset library, and no Summer Engine tools. Deliver files the person can use in any engine or web app." +
+            (needsEngine
+                ? " Building or changing a game needs Summer Engine and the full setup: npx -y summer-engine@latest setup <agent> --yes. Until then, make the assets the task needs."
+                : ""),
+        principles: [
+            "Deliver files, not scenes: the asset is done when it is saved where the person asked.",
+            "Reuse the person's assets and the Summer library before paid generation unless the person wants something custom.",
+            "Use the asset id a job returns; never search by name right after a generation.",
+            "Check each asset before claiming it is done: the job finished, and you saw the preview (or the person heard the sound).",
+        ],
+        recommendedSkills: inferSkills(mode, target, goal, false),
+        mcpToolPlan: buildAssetsToolPlan(target, assetPolicy, verification),
+        hostFileWork: [
+            "summer_generate_image saves the file itself when you pass out (a folder or a file path in the person's project).",
+            "Download other assets from summer_get_asset_download_url with your own shell into the folder the person named.",
+        ],
+        userGates: buildUserGates(mode, assetPolicy, false),
+        nextAgentSteps: [
+            "Load the top recommended skill; follow it until the asset exists, then its 'Without Summer Engine' section.",
+            "Ask what the asset is for: engine or app, format, size or scale, style, how many.",
+            "Check summer_list_my_assets and summer_search_assets before generating.",
+            "Generate after the person confirms the spend; poll summer_check_job until the state is terminal.",
+            "Hand the file over and tell the person its path and format.",
+        ],
+        antiPatterns: [
+            "Do not call engine tools (summer_get_project_context, summer_add_node, summer_play, summer_import_asset_by_id): this session does not have them.",
+            "Do not generate assets before checking library/user assets.",
+            "Do not search by name for an asset immediately after generation; use the returned asset ID.",
+            "Do not say an asset looks right without a preview you actually received.",
+        ],
+    };
+}

package/dist/core/capabilities/motion-generation.js

@@ -53,8 +53,8 @@ export const motionGenerationArgsSchema = z.object({
         .describe("Stable retry key so the same logical request is not billed or queued twice"),
     wait: z
         .boolean()
-        .default(true)
-        .describe("Wait for completion (default true, up to 10 min). Set false to get jobId immediately."),
+        .default(false)
+        .describe("Block until the job finishes (up to 10 min) and return the result. Default false returns the jobId at once; poll summer_check_job."),
     options: z
         .record(z.any())
         .optional()

package/dist/core/capabilities/navigation/open.d.ts

@@ -20,6 +20,7 @@
  */
 import { z } from "zod";
 import type { EngineCapabilities } from "../../capability-skew.js";
+import { type SummerErrorCode } from "../../error-codes.js";
 import { type EditorTargetMeta, type NavParam, type NavSurface, type NavTarget } from "./targets.js";
 export type OpenSurface = "auto" | NavSurface;
 /** The ONE argument shape both faces validate with (mirrors
@@ -36,14 +37,14 @@ export declare const openArgsSchema: z.ZodObject<{
     surface: z.ZodOptional<z.ZodEnum<["auto", "web", "editor"]>>;
     open: z.ZodOptional<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
+    surface?: "web" | "editor" | "auto" | undefined;
     params?: Record<string, string> | undefined;
     target?: string | undefined;
-    surface?: "web" | "editor" | "auto" | undefined;
     open?: boolean | undefined;
 }, {
+    surface?: "web" | "editor" | "auto" | undefined;
     params?: Record<string, string> | undefined;
     target?: string | undefined;
-    surface?: "web" | "editor" | "auto" | undefined;
     open?: boolean | undefined;
 }>;
 export type OpenArgs = z.infer<typeof openArgsSchema>;
@@ -93,6 +94,9 @@ export interface OpenResult {
     receipt?: unknown;
     /** Structured failure class for ok:false results (engine_lacks_op, …). */
     failure_reason?: string;
+    /** The shared code (core/error-codes.ts) when the engine is not running. */
+    code?: SummerErrorCode;
+    recovery?: string;
     matches?: OpenMatch[];
     targets?: OpenTargetSummary[];
     hint?: string;

package/dist/core/capabilities/navigation/open.js

@@ -20,6 +20,7 @@
  */
 import { z } from "zod";
 import { extractOpError } from "../engine-receipt.js";
+import { RECOVERY } from "../../error-codes.js";
 import { NAV_TARGETS, WEB_CATALOG, getNavTarget, } from "./targets.js";
 /** The ONE argument shape both faces validate with (mirrors
  *  library/tools/open/resource.yaml input_schema; parity-tested). */
@@ -516,6 +517,8 @@ export async function runOpen(args, deps) {
         return {
             ok: false,
             action: "engine_not_running",
+            code: "engine_not_running",
+            recovery: RECOVERY.engine_not_running,
             target: summary,
             op: navigateOp,
             engine: { running: false, error: message },

package/dist/core/capabilities/publish-build.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { open } from "node:fs/promises";
 import { extname, resolve } from "node:path";
+import { summerRequestHeaders } from "../agent-host.js";
 import { resolveGatewayUrl } from "../config.js";
 import { getStoreAccessToken, OAuthError } from "../oauth.js";
 import { appendStoreJsonLine } from "../store.js";
@@ -87,6 +88,7 @@ export function createStore(baseUrl, token, deps) {
                 response = await deps.fetch(`${baseUrl}${STORE_PROXY_PATH}/${path}`, {
                     method,
                     headers: {
+                        ...summerRequestHeaders(),
                         accept: "application/json",
                         authorization: `Bearer ${token}`,
                         ...(options.body === undefined ? {} : { "content-type": "application/json" }),

package/dist/core/capabilities/runtime-control.d.ts

@@ -140,18 +140,18 @@ export declare const runtimeSpawnArgsSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     action: "spawn" | "free";
     mode?: "free" | "queue_free" | undefined;
+    name?: string | undefined;
     instance?: string | undefined;
     scene?: string | undefined;
-    name?: string | undefined;
     path?: string | undefined;
     parent?: string | undefined;
     props?: Record<string, string | number | boolean> | undefined;
 }, {
     action: "spawn" | "free";
     mode?: "free" | "queue_free" | undefined;
+    name?: string | undefined;
     instance?: string | undefined;
     scene?: string | undefined;
-    name?: string | undefined;
     path?: string | undefined;
     parent?: string | undefined;
     props?: Record<string, string | number | boolean> | undefined;
@@ -182,10 +182,10 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     path: string;
     target: "tree" | "player" | "bones";
+    name?: string | undefined;
     state?: string | undefined;
     value?: string | number | boolean | undefined;
     instance?: string | undefined;
-    name?: string | undefined;
     space?: "local" | "global" | "both" | undefined;
     cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
     blend?: number | undefined;
@@ -201,10 +201,10 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
 }, {
     path: string;
     target: "tree" | "player" | "bones";
+    name?: string | undefined;
     state?: string | undefined;
     value?: string | number | boolean | undefined;
     instance?: string | undefined;
-    name?: string | undefined;
     space?: "local" | "global" | "both" | undefined;
     cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
     blend?: number | undefined;

package/dist/core/capabilities/scene-script-target.d.ts

@@ -0,0 +1,17 @@
+import { type RunSceneScriptArgs } from "./scene-script.js";
+export interface SceneScriptClient {
+    executeIdentityBoundOps(ops: Record<string, unknown>[], options?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    getSceneState(): Promise<unknown>;
+}
+export interface SceneTarget {
+    scenePath: string;
+    /** The script's scene was not the edited one, so its tab was brought forward. */
+    opened: boolean;
+    /** The scene the editor showed before, opened again after the run. */
+    restored?: string;
+    /** Why that tab could not be restored (the script still ran). */
+    restore_error?: string;
+}
+export declare function runSceneScriptOn(client: SceneScriptClient, args: RunSceneScriptArgs & {
+    scenePath?: string;
+}): Promise<unknown>;

package/dist/core/capabilities/scene-script-target.js

@@ -0,0 +1,70 @@
+/**
+ * summer_run_script with a target scene. The engine's RunSceneScript runs
+ * against the scene the editor is editing and takes no target of its own, so
+ * a scenePath is honored here, the same way for the MCP tool and the CLI:
+ *
+ * 1. Read the scene the editor is editing (a snapshot up to ~300 ms old).
+ * 2. OpenScene scenePath, alone (never in one batch with a mutation), even
+ *    when the snapshot says it is already the edited scene: the person may
+ *    have switched tabs since, and opening the current scene again changes
+ *    nothing. The engine answers ok only once that scene is the edited one,
+ *    so a failed open stops here and the script never runs.
+ * 3. Run the script.
+ * 4. Give the person back the tab they had (OpenScene of the earlier scene),
+ *    as the engine's own scene-targeted ops do.
+ *
+ * The result is the engine's RunSceneScript receipt plus `scene_target`.
+ */
+import { resolveCurrentScene } from "./project-context.js";
+import { buildRunSceneScriptOp } from "./scene-script.js";
+import { validateScenePath } from "./seeing/seeing.js";
+import { extractOpError } from "./engine-receipt.js";
+function withTarget(result, target) {
+    return result && typeof result === "object" && !Array.isArray(result)
+        ? { ...result, scene_target: target }
+        : { result, scene_target: target };
+}
+export async function runSceneScriptOn(client, args) {
+    const { op, timeoutMs } = buildRunSceneScriptOp(args);
+    if (args.scenePath === undefined)
+        return client.executeIdentityBoundOps([op], undefined, timeoutMs);
+    const scenePath = validateScenePath(args.scenePath);
+    let before = null;
+    let beforeError;
+    try {
+        before = resolveCurrentScene(undefined, await client.getSceneState(), undefined);
+    }
+    catch (error) {
+        beforeError = error instanceof Error ? error.message : String(error);
+    }
+    const open = await client.executeIdentityBoundOps([{ op: "OpenScene", path: scenePath }]);
+    const openError = extractOpError(open);
+    if (openError) {
+        return {
+            ok: false,
+            error: `Could not open ${scenePath}, so the script did not run. ${openError}`,
+            failure_reason: "scene_target_failed",
+            scene_target: { scenePath, opened: false },
+            receipt: open,
+        };
+    }
+    const opened = before !== scenePath;
+    const result = await client.executeIdentityBoundOps([op], undefined, timeoutMs);
+    const target = { scenePath, opened };
+    if (beforeError !== undefined)
+        target.restore_error = `The scene open before could not be read, so no tab was restored: ${beforeError}`;
+    if (opened && before) {
+        try {
+            const restore = await client.executeIdentityBoundOps([{ op: "OpenScene", path: before }]);
+            const restoreError = extractOpError(restore);
+            if (restoreError)
+                target.restore_error = restoreError;
+            else
+                target.restored = before;
+        }
+        catch (error) {
+            target.restore_error = error instanceof Error ? error.message : String(error);
+        }
+    }
+    return withTarget(result, target);
+}

package/dist/core/capabilities/sfx-choices.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { type SummerErrorCode } from "../error-codes.js";
 /**
  * Sound-effect choices (summer_generate_sfx_choices + summer_get_choices).
  *
@@ -59,6 +60,9 @@ export interface GatewayReply {
     data?: any;
     error?: string;
     status: number;
+    /** Set for the shared failures (not signed in, no credits, network). */
+    code?: SummerErrorCode;
+    recovery?: string;
 }
 export interface SfxChoicesDeps {
     post(endpoint: string, body: Record<string, unknown>, timeoutMs: number): Promise<GatewayReply>;

package/dist/core/capabilities/sfx-choices.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { codedFailure } from "../error-codes.js";
 /**
  * Sound-effect choices (summer_generate_sfx_choices + summer_get_choices).
  *
@@ -59,6 +60,14 @@ export const getChoicesArgsSchema = z.object({
         .optional()
         .describe("Wait up to this many seconds (max 50) for the person to decide before answering. 0 or omitted: answer now"),
 });
+/** A failed reply as a tool result; coded when the reply carries a code. */
+function replyFailure(reply) {
+    // An unavailable reply's data is already `{details: {cause}}`.
+    const details = reply.code === "unavailable" ? reply.data ?? {} : reply.data ? { details: reply.data } : {};
+    return reply.code
+        ? codedFailure(reply.code, reply.error ?? "Request failed", details, reply.recovery)
+        : { ok: false, error: reply.error, ...details };
+}
 // ---------------------------------------------------------------------------
 // Showing the page
 // ---------------------------------------------------------------------------
@@ -138,9 +147,8 @@ function clipSummary(clip) {
 }
 export async function generateSfxChoices(args, deps) {
     const reply = await deps.post(SFX_CHOICES_ENDPOINT, sfxChoicesRequestBody(args), SFX_CHOICES_TIMEOUT_MS);
-    if (reply.error) {
-        return { ok: false, error: reply.error, ...(reply.data ? { details: reply.data } : {}) };
-    }
+    if (reply.error)
+        return replyFailure(reply);
     const data = reply.data ?? {};
     const clips = Array.isArray(data.clips) ? data.clips : [];
     const failed = Array.isArray(data.failed) ? data.failed : [];
@@ -211,9 +219,8 @@ export async function getChoices(args, deps) {
     if (args.waitSeconds)
         params.set("waitSeconds", String(args.waitSeconds));
     const reply = await deps.get(choicesEndpoint(args.choiceSetId), params, choicesTimeoutMs(args.waitSeconds));
-    if (reply.error) {
-        return { ok: false, error: reply.error, ...(reply.data ? { details: reply.data } : {}) };
-    }
+    if (reply.error)
+        return replyFailure(reply);
     const data = reply.data ?? {};
     const clips = Array.isArray(data.clips) ? data.clips : [];
     const status = data.status === "decided" ? "decided" : "pending";

package/dist/core/capabilities/tool-dispatch.d.ts

@@ -1,4 +1,5 @@
 import { EngineApiClient } from "../api-client.js";
+import { type SummerErrorCode } from "../error-codes.js";
 export type DispatchArgs = Record<string, unknown>;
 export interface ToolDispatchContext {
     /** Lazily connect to the local engine. Throws EngineUnavailableError with a
@@ -19,9 +20,6 @@ export interface ToolDispatchEntry {
 /** Dispatch-level failure with a user-facing message (no stack needed). */
 export declare class ToolDispatchError extends Error {
 }
-/** The local engine is not reachable — a clean state, not a crash. */
-export declare class EngineUnavailableError extends ToolDispatchError {
-}
 /** A tool failed with a structured receipt that `summer tool` prints whole
  *  (JSON on stdout, exit 1) instead of flattening to `message`: every engine
  *  envelope extractOpError reads as a failure (the same gate the MCP face
@@ -33,6 +31,17 @@ export declare class ToolResultError extends ToolDispatchError {
     readonly result: Record<string, unknown>;
     constructor(result: Record<string, unknown>, message: string);
 }
+/** A shared failure (core/error-codes.ts) — not signed in, no credits,
+ *  network — printed as `{ok:false, code, error, recovery}` with the shell
+ *  wording of the next step. */
+export declare class CodedToolError extends ToolResultError {
+    constructor(code: SummerErrorCode, message: string, extra?: Record<string, unknown>, recovery?: string);
+}
+/** The local engine is not reachable — a clean state, not a crash. Prints
+ *  `{ok:false, code:"engine_not_running", error, recovery, hint}`. */
+export declare class EngineUnavailableError extends CodedToolError {
+    constructor(message: string);
+}
 export declare function createDefaultDispatchContext(): ToolDispatchContext;
 export declare const TOOL_DISPATCH: readonly ToolDispatchEntry[];
 export declare function listToolDispatches(): readonly ToolDispatchEntry[];