summer-engine 4.5.0 → 4.8.0

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

@@ -87,6 +87,50 @@ export function resPathProblem(value) {
         return "must not contain control characters";
     return null;
 }
+/** A summerengine.com Studio path (`/studio`, `/studio/games`, `/studio?tab=assets`), the
+ *  only paths the engine's `studio` Navigate row opens. */
+export function isStudioPath(path) {
+    return /^\/studio(?:[/?#]|$)/.test(path);
+}
+/**
+ * A Studio path opens in the Summer app's own Studio tab when the running
+ * engine advertises the `studio` Navigate destination (it loads the tab when
+ * the person has not opened it yet). Otherwise, the engine off, an older
+ * engine or a refused Navigate, null: the caller opens the browser as before.
+ */
+async function openInAppStudio(deps, path, url, extra) {
+    if (!isStudioPath(path))
+        return null;
+    let client;
+    try {
+        client = await deps.engine();
+    }
+    catch {
+        return null;
+    }
+    if (!advertisedNavigation(client)?.has("studio"))
+        return null;
+    const op = { op: "Navigate", target: "studio", path };
+    let receipt;
+    try {
+        receipt = await client.executeOps([op]);
+    }
+    catch {
+        return null;
+    }
+    if (extractOpError(receipt))
+        return null;
+    return {
+        ok: true,
+        action: "opened",
+        url,
+        ...extra,
+        op,
+        engine: { running: true, version: client.getEngineVersion?.(), navigation: true },
+        receipt,
+        hint: "Opened in the Studio tab of the Summer app, not a browser.",
+    };
+}
 /** Launch the browser; a failed launch is a result, not a crash. */
 async function launch(deps, url) {
     try {
@@ -444,6 +488,9 @@ export async function runOpen(args, deps) {
         };
         if (print)
             return base;
+        const inApp = await openInAppStudio(deps, resolution.url, url, { unmapped: true });
+        if (inApp)
+            return inApp;
         const failure = await launch(deps, url);
         if (failure)
             return openFailed(url, failure, { unmapped: true });
@@ -479,6 +526,12 @@ export async function runOpen(args, deps) {
         };
         if (print)
             return result;
+        if (target.web.origin !== "docs") {
+            // The app's Studio tab is signed in with the app: no login detour.
+            const inApp = await openInAppStudio(deps, path, url, { target: summary });
+            if (inApp)
+                return inApp;
+        }
         const toOpen = needsLogin && loggedIn === false ? loginUrl : url;
         const failure = await launch(deps, toOpen);
         if (failure)

package/dist/core/capabilities/projects-local.js

@@ -143,7 +143,8 @@ sessionFolder = process.cwd()) {
     }
     let client;
     try {
-        client = await openProjectInEditor(root, { cwd: root }, { install: input.install === true }, deps);
+        // The agent asked for this game: an editor with another one switches (J16.1).
+        client = await openProjectInEditor(root, { cwd: root }, { install: input.install === true, switchOpen: true }, deps);
     }
     catch (error) {
         if (error instanceof EngineInstallError)

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

@@ -141,18 +141,18 @@ export declare const runtimeSpawnArgsSchema: z.ZodObject<{
     action: "free" | "spawn";
     mode?: "free" | "queue_free" | undefined;
     name?: string | undefined;
+    path?: string | undefined;
     instance?: string | undefined;
     scene?: string | undefined;
-    path?: string | undefined;
     parent?: string | undefined;
     props?: Record<string, string | number | boolean> | undefined;
 }, {
     action: "free" | "spawn";
     mode?: "free" | "queue_free" | undefined;
     name?: string | undefined;
+    path?: string | undefined;
     instance?: string | undefined;
     scene?: string | undefined;
-    path?: string | undefined;
     parent?: string | undefined;
     props?: Record<string, string | number | boolean> | undefined;
 }>;

package/dist/core/capabilities/seeing/args.d.ts

@@ -177,10 +177,10 @@ export declare const shotSheetArgsSchema: z.ZodObject<{
         bookmark_name?: string | undefined;
     }[];
     scenePath?: string | undefined;
+    view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
     compare_previous?: boolean | undefined;
     max_size?: number | undefined;
     save_to?: string | undefined;
-    view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
     update_previous?: boolean | undefined;
     aspect?: number | undefined;
 }, {
@@ -192,10 +192,10 @@ export declare const shotSheetArgsSchema: z.ZodObject<{
         bookmark_name?: string | undefined;
     }[];
     scenePath?: string | undefined;
+    view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
     compare_previous?: boolean | undefined;
     max_size?: number | undefined;
     save_to?: string | undefined;
-    view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
     update_previous?: boolean | undefined;
     aspect?: number | undefined;
 }>;
@@ -251,11 +251,11 @@ export declare const zoomArgsSchema: z.ZodObject<{
     camera_position?: string | undefined;
     camera_look_at?: string | undefined;
     fov?: number | undefined;
+    view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
     bookmark_name?: string | undefined;
     region?: number[] | undefined;
     max_size?: number | undefined;
     save_to?: string | undefined;
-    view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
     mark?: number | undefined;
     reference_size?: number[] | undefined;
     pad?: number | undefined;
@@ -264,11 +264,11 @@ export declare const zoomArgsSchema: z.ZodObject<{
     camera_position?: string | undefined;
     camera_look_at?: string | undefined;
     fov?: number | undefined;
+    view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
     bookmark_name?: string | undefined;
     region?: number[] | undefined;
     max_size?: number | undefined;
     save_to?: string | undefined;
-    view?: "lighting" | "beauty" | "unshaded" | "normals" | "overdraw" | "wireframe" | undefined;
     mark?: number | undefined;
     reference_size?: number[] | undefined;
     pad?: number | undefined;

package/dist/core/capabilities/tool-dispatch.js

@@ -16,6 +16,7 @@
  * as the single per-tool dispatch table so the handler bodies stop being two
  * mirrors as well.
  */
+import { viewSetOp } from "./view-set.js";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
@@ -79,6 +80,7 @@ import { captureGame, captureScene, captureViewport } from "./capture.js";
 // the scripting ones come with their op builders from ./scene-script.js.
 import { ALIGN_DISTRIBUTE_FALLBACK, GREP_FALLBACK, NAVIGATION_PROBE_FALLBACK, RUNTIME_NODE_FALLBACK, RUNTIME_TREE_FALLBACK, SNAP_TO_SURFACE_FALLBACK, SNAPSHOT_DIFF_FALLBACK, STARCAST_FALLBACK, TEST_PLACEMENT_FALLBACK, WORLD_SNAPSHOT_FALLBACK, } from "./engine-fallbacks.js";
 import { sendLibraryFeedback, } from "../feedback/client.js";
+import { batchToolResult, cancelJob, checkBatch, createBatch, estimateJob, getBatch, getJob, jobToolResult, listModels, runJob, summerApiToolAnswer } from "../summer-api.js";
 // One copy of the batch op classification and the instantiate/batch engine
 // path, shared with the MCP face.
 import { PLACEMENT_FIELDS, SCENE_MUTATION_OPS, SCENE_QUERY_OPS, instantiateScene, runBatch, } from "./placement-batch.js";
@@ -1296,6 +1298,11 @@ export const TOOL_DISPATCH = [
             op.scenePath = args.scenePath;
         return requireEngineSuccess(await (await ctx.engine()).executeOps([op]));
     }),
+    entry("summer_view_set", "Show the person a view, rail and focus in the editor", true, async (args, ctx) => {
+        const frame = Array.isArray(args.frame) ? args.frame.filter((entry) => typeof entry === "string") : undefined;
+        const op = viewSetOp({ view: str(args, "view"), rail: optStr(args, "rail"), focus: optStr(args, "focus"), frame });
+        return requireEngineSuccess(await (await ctx.engine()).executeOps([op]));
+    }),
     entry("summer_replace_node", "Replace a node with a different scene or type and verify the saved scene", true, async (args, ctx) => {
         // ONE implementation for both faces (core/capabilities/replace-node.ts):
         // persisted ops + read-back of the saved .tscn.
@@ -1767,6 +1774,36 @@ export const TOOL_DISPATCH = [
             throw new ToolResultError(result, result.hint);
         return result;
     }),
+    // --- account ---
+    entry("summer_api_models", "The Summer API's models with input and price", false, async (args) => summerApiToolAnswer(() => listModels({ ...(optStr(args, "model") ? { model: optStr(args, "model") } : {}), ...(optStr(args, "capability") ? { capability: optStr(args, "capability") } : {}) }))),
+    entry("summer_api_estimate", "The exact price of one Summer API job; charges nothing", false, async (args) => summerApiToolAnswer(() => estimateJob(str(args, "model"), args.input ?? {}))),
+    entry("summer_api_run", "Run one Summer API job with the Summer sign-in on this computer", false, async (args) => summerApiToolAnswer(async () => {
+        const out = optStr(args, "out");
+        const follow = args.wait === true || Boolean(out);
+        const job = await runJob(str(args, "model"), args.input ?? {}, {
+            ...(optStr(args, "quoteId") ? { quoteId: optStr(args, "quoteId") } : {}),
+            ...(optStr(args, "idempotencyKey") ? { idempotencyKey: optStr(args, "idempotencyKey") } : {}),
+            ...(follow ? { waitSeconds: 30 } : {}),
+        });
+        return jobToolResult(job, { wait: args.wait === true, ...(out ? { out } : {}) });
+    })),
+    entry("summer_api_batch", "Run up to 500 Summer API jobs at once (all or none), or read a batch", false, async (args) => summerApiToolAnswer(async () => {
+        const out = optStr(args, "out");
+        const follow = { wait: args.wait === true, ...(out ? { out } : {}) };
+        const batchId = optStr(args, "batchId");
+        if (batchId)
+            return batchToolResult(await getBatch(batchId), follow);
+        const key = optStr(args, "idempotencyKey");
+        const batch = await createBatch(checkBatch(Array.isArray(args.jobs) ? args.jobs : []), key ? { idempotencyKey: key } : {});
+        return batchToolResult(batch, follow);
+    })),
+    entry("summer_api_job", "Read, follow, download or cancel a Summer API job", false, async (args) => summerApiToolAnswer(async () => {
+        const jobId = str(args, "jobId");
+        if (args.cancel === true)
+            return { job: await cancelJob(jobId) };
+        const out = optStr(args, "out");
+        return jobToolResult(await getJob(jobId), { wait: args.wait === true, ...(out ? { out } : {}) });
+    })),
     // --- feedback ---
     entry("summer_library_feedback", "Report library entry outcomes so Summer can fix and re-rank them", false, async (args) => {
         if (!Array.isArray(args.reports) || args.reports.length === 0) {

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

@@ -88,16 +88,16 @@ export declare const uiActivateArgsSchema: z.ZodObject<{
     button: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     value?: string | number | undefined;
-    title?: string | undefined;
     path?: string | undefined;
+    title?: string | undefined;
     action?: "focus" | "press" | "select_tab" | "toggle" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
     button?: string | undefined;
     index?: number | undefined;
     submit?: boolean | undefined;
 }, {
     value?: string | number | undefined;
-    title?: string | undefined;
     path?: string | undefined;
+    title?: string | undefined;
     action?: "focus" | "press" | "select_tab" | "toggle" | "set_text" | "set_value" | "dismiss_dialog" | undefined;
     button?: string | undefined;
     index?: number | undefined;

package/dist/core/capabilities/view-set.d.ts

@@ -0,0 +1,11 @@
+/**
+ * summer_view_set / engine.view_set (PRODUCT-SPEC J17): an outside agent shows
+ * the person what it works on, through the engine's SetView op: the view, the
+ * right rail, what to focus, and the nodes to frame the camera on.
+ */
+export declare function viewSetOp(args: {
+    view: string;
+    rail?: string;
+    focus?: string;
+    frame?: string[];
+}): Record<string, unknown>;

package/dist/core/capabilities/view-set.js

@@ -0,0 +1,15 @@
+/**
+ * summer_view_set / engine.view_set (PRODUCT-SPEC J17): an outside agent shows
+ * the person what it works on, through the engine's SetView op: the view, the
+ * right rail, what to focus, and the nodes to frame the camera on.
+ */
+export function viewSetOp(args) {
+    const op = { op: "SetView", view: args.view };
+    if (args.rail)
+        op.rail = args.rail;
+    if (args.focus)
+        op.focus = args.focus;
+    if (args.frame?.length)
+        op.frame = args.frame;
+    return op;
+}

package/dist/core/capability-skew.d.ts

@@ -81,6 +81,9 @@ export interface EngineCapabilities {
      *  destination ids this build can open. Absent = engine predates the op;
      *  summer_open then falls back to the legacy per-surface ops it can map. */
     navigation?: EngineNavigationCapabilities;
+    /** The Studio page ops this app answers itself through its own Studio tab
+     *  (POST /api/studio). Absent = send them to Summer's server. */
+    studioPage?: EngineStudioPageCapabilities;
     /** Launch postures this build ENFORCES: "focus" (always), "background"
      *  (`--summer-background`), "offscreen" (`--summer-offscreen` /
      *  `--summer-verify`). Non-macOS builds advertise ["focus"] only. Absent =
@@ -89,6 +92,11 @@ export interface EngineCapabilities {
      *  snake_case spelling too. */
     launchPostures?: string[];
 }
+export interface EngineStudioPageCapabilities {
+    version?: number;
+    path: string;
+    ops: string[];
+}
 export interface EngineNavigationCapabilities {
     version?: number;
     targets: EngineNavigationTarget[];

package/dist/core/capability-skew.js

@@ -49,6 +49,8 @@ export const CLI_KNOWN_OP_NEEDS = [
     // engine's one-table op; the other three are the legacy
     // fallbacks on engines that predate it.
     "Navigate", "OpenResource", "FocusDock", "RevealInFileSystem",
+    // engine.view_set: the frame's view, rail, focus and frame (core/capabilities/view-set.ts)
+    "SetView",
     // Summer Apps editor docks (summer_app_dock: core/capabilities/apps.ts)
     "OpenAppDock", "CloseAppDock", "ListAppDocks",
     // summer_enable_plugin (core/capabilities/enable-plugin.ts)
@@ -188,11 +190,27 @@ export function parseEngineCapabilities(raw) {
     const navigation = parseNavigation(record.navigation);
     if (navigation)
         out.navigation = navigation;
+    const studioPage = parseStudioPage(record.studioPage);
+    if (studioPage)
+        out.studioPage = studioPage;
     const launchPostures = stringList(record.launchPostures) ?? stringList(record.launch_postures);
     if (launchPostures)
         out.launchPostures = launchPostures;
     return Object.keys(out).length > 0 ? out : undefined;
 }
+function parseStudioPage(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    const ops = stringList(record.ops);
+    if (!ops?.length)
+        return undefined;
+    return {
+        ...(typeof record.version === "number" ? { version: record.version } : {}),
+        path: typeof record.path === "string" && record.path.startsWith("/api/") ? record.path : "/api/studio",
+        ops,
+    };
+}
 function parseNavigation(raw) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         return undefined;

package/dist/core/cli-session.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The browser sign-in for the Summer account (the `cli_session` flow): the
+ * person opens `{gateway}/login?cli_session=<id>`, signs in, and approves;
+ * this polls `{gateway}/api/auth/cli-login?session=<id>` until the gateway
+ * hands over the CLI token, then saves it to ~/.summer (the files the desktop
+ * engine and every tool read). `summer login` and the MCP's sign-in link
+ * (core/sign-in-link.ts) share it.
+ */
+import { type LoginSession } from "./auth.js";
+export declare const POLL_TIMEOUT_MS = 900000;
+export interface CliSessionPollDependencies {
+    fetch: typeof fetch;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    log: (message: string) => void;
+    /** Stop waiting (another sign-in already saved a token, the server is closing). */
+    cancelled?: () => boolean | Promise<boolean>;
+}
+/** The page the person opens to sign in. */
+export declare function cliSessionLoginUrl(gatewayUrl: string, sessionId: string): string;
+/**
+ * Wait for the browser sign-in of `sessionId`, save it, and return it.
+ * Throws on a rejected request, an invalid token, a timeout, or `cancelled`.
+ */
+export declare function pollCliSession(gatewayUrl: string, sessionId: string, deps: CliSessionPollDependencies): Promise<LoginSession>;

package/dist/core/cli-session.js

@@ -0,0 +1,97 @@
+/**
+ * The browser sign-in for the Summer account (the `cli_session` flow): the
+ * person opens `{gateway}/login?cli_session=<id>`, signs in, and approves;
+ * this polls `{gateway}/api/auth/cli-login?session=<id>` until the gateway
+ * hands over the CLI token, then saves it to ~/.summer (the files the desktop
+ * engine and every tool read). `summer login` and the MCP's sign-in link
+ * (core/sign-in-link.ts) share it.
+ */
+import { saveLoginSession } from "./auth.js";
+import { summerRequestHeaders } from "./agent-host.js";
+const POLL_INTERVAL_MS = 2000;
+// One generous window on ONE session id. First-time users may need to create an
+// account and confirm an email before they can approve the CLI. The gateway
+// never expires a pending session (the completed payload waits under this id
+// for pickup), so the worst mistake would be rotating ids mid-wait — the user
+// would approve the original browser tab while we poll a different session.
+export const POLL_TIMEOUT_MS = 900000;
+const HEARTBEAT_MS = 30000;
+/** The gateway answered with a terminal 4xx — retrying the same URL cannot help. */
+class LoginRejectedError extends Error {
+}
+/** The page the person opens to sign in. */
+export function cliSessionLoginUrl(gatewayUrl, sessionId) {
+    return `${gatewayUrl}/login?cli_session=${encodeURIComponent(sessionId)}`;
+}
+/**
+ * Wait for the browser sign-in of `sessionId`, save it, and return it.
+ * Throws on a rejected request, an invalid token, a timeout, or `cancelled`.
+ */
+export async function pollCliSession(gatewayUrl, sessionId, deps) {
+    const loginUrl = cliSessionLoginUrl(gatewayUrl, sessionId);
+    const pollUrl = `${gatewayUrl}/api/auth/cli-login?session=${encodeURIComponent(sessionId)}`;
+    const startTime = deps.now();
+    let lastHeartbeat = startTime;
+    let lastError = null;
+    while (deps.now() - startTime < POLL_TIMEOUT_MS) {
+        await deps.sleep(POLL_INTERVAL_MS);
+        if (deps.cancelled && (await deps.cancelled())) {
+            throw new Error("The sign-in wait was cancelled.");
+        }
+        if (deps.now() - lastHeartbeat >= HEARTBEAT_MS) {
+            lastHeartbeat = deps.now();
+            deps.log('Still waiting — finish signing in (or creating your account) in the browser, then click "Yes, Sign In". Same link: ' +
+                loginUrl +
+                (lastError ? ` (last error: ${lastError})` : ""));
+        }
+        // Only the network round-trip is retried. A completed session is handled
+        // OUTSIDE this try: saveLoginSession rejecting the token (mismatched sub,
+        // non-CLI token type, already expired) is terminal — the gateway will
+        // return the same payload forever, so polling on would only bury the
+        // recovery message under a 15-minute timeout.
+        let completed = null;
+        try {
+            const res = await deps.fetch(pollUrl, {
+                headers: summerRequestHeaders({ surface: "cli" }),
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!res.ok) {
+                if (res.status === 503) {
+                    lastError =
+                        "The login service is unavailable (Redis/auth is not configured).";
+                }
+                else if (res.status >= 500) {
+                    lastError = `The login service failed (${res.status}).`;
+                }
+                else if (res.status === 429 || res.status === 408) {
+                    lastError = `The login service asked us to slow down (${res.status}).`;
+                }
+                else {
+                    // 401/403/404 and the other 4xx are terminal: this URL will not
+                    // start succeeding on its own.
+                    throw new LoginRejectedError(`The login request was rejected (${res.status}). Recovery: check that gateway.url (${gatewayUrl}) is the Summer gateway you meant, then run "summer login" again.`);
+                }
+                continue;
+            }
+            const data = (await res.json());
+            if (data.status === "pending")
+                continue;
+            if (data.status === "complete" && data.token) {
+                completed = { token: data.token, user: data.user, scopes: data.scopes };
+            }
+            else {
+                lastError = "The login service returned an incomplete authentication result.";
+            }
+        }
+        catch (err) {
+            if (err instanceof LoginRejectedError)
+                throw err;
+            lastError = err instanceof Error ? err.message : "Network error";
+        }
+        if (completed) {
+            await saveLoginSession(completed);
+            return completed;
+        }
+    }
+    throw new Error(`Login timed out after ${Math.round(POLL_TIMEOUT_MS / 60000)} minutes.${lastError ? ` Last error: ${lastError}` : ""} Recovery: run "summer login" again and complete "Yes, Sign In" in the browser tab it opens.`);
+}

package/dist/core/engine-self-start.d.ts

@@ -20,7 +20,20 @@ export declare const SELF_START_RECOVERY: {
     closedEarly: (root: string) => string;
     launchFailed: (code: string) => string;
     autoLaunchOff: (root: string) => string;
+    switchUnsupported: (open: string, wanted: string) => string;
+    switchFailed: (wanted: string, reason: string) => string;
 };
+/** The engine operation that makes a running editor open another game in
+ *  the same window (the editor's own switch, J16.1). */
+export declare const SWITCH_PROJECT_OP = "SwitchProject";
+/** How long the new editor has to register after a switch: it boots first
+ *  and registers about 5 s after the operation returns locally, about 14 s
+ *  on CI (J17), so the next tool never meets a half-open game. */
+export declare const SWITCH_REGISTER_MS = 30000;
+/** While a game opens, the agent hears "Opening <game>…" this often. */
+export declare const OPEN_PROGRESS_EVERY_MS = 3000;
+/** Says `message` now and every OPEN_PROGRESS_EVERY_MS until the returned stop is called. */
+export declare function keepSaying(progress: SelfStartDeps["progress"], message: string): () => void;
 export interface SelfStartDeps {
     launch?: typeof launchEditor;
     connect?: (selection: EngineSelection | undefined) => Promise<EngineApiClient>;
@@ -29,6 +42,10 @@ export interface SelfStartDeps {
     waitMs?: number;
     env?: NodeJS.ProcessEnv;
     now?: () => number;
+    /** A progress line for the agent while it waits (MCP notifications/progress). */
+    progress?: (message: string) => void;
+    /** Tests: how long a switch waits for the new editor (default SWITCH_REGISTER_MS). */
+    switchWaitMs?: number;
 }
 /** Test-only: forget the last answer only (withEngine's immediate retry window). */
 export declare function _resetRecentForTests(): void;
@@ -48,6 +65,9 @@ export interface OpenProjectOptions {
     install?: boolean;
     /** The error to build answers from (a failed connect), or the op's own. */
     notRunning?: EngineNotRunningError;
+    /** An editor with another game open switches to this one in the same
+     *  window instead of refusing (projects.open_local: the agent asked). */
+    switchOpen?: boolean;
 }
 /**
  * Open `root` in the editor and return a connected client: launch it unless