summer-engine 4.6.0 → 4.8.0

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

package/dist/core/engine-self-start.js

@@ -15,7 +15,7 @@
  */
 import { execSync } from "child_process";
 import { realpathSync } from "fs";
-import { resolve, sep } from "path";
+import { basename, resolve, sep } from "path";
 import { EngineApiClient } from "./api-client.js";
 import { checkEngineHealth, findProjectRoot, listEngineInstances } from "./engine.js";
 import { CLOSED_EARLY, lastLaunch, LaunchLockBusyError, launchEditor, resolveRunBinary } from "./engine-launch.js";
@@ -48,7 +48,28 @@ export const SELF_START_RECOVERY = {
     closedEarly: (root) => `Summer Engine closed before it opened ${root}. Call again; if it closes again, open the project in Summer Engine to see why.`,
     launchFailed: (code) => `Summer Engine could not start (${code}). Repair it: npx -y summer-engine@latest install --yes, then call again.`,
     autoLaunchOff: (root) => `Open it with projects.open_local, or run: npx -y summer-engine@latest run ${root}`,
+    switchUnsupported: (open, wanted) => `Summer Engine has ${open} open, not ${wanted}, and this editor cannot switch games for an agent. ` +
+        `Update Summer Engine, or switch to ${wanted} in its games list and call again.`,
+    switchFailed: (wanted, reason) => `Summer Engine could not switch to ${wanted} (${reason}). Call again; if it fails again, open it from the editor's games list.`,
 };
+/** The engine operation that makes a running editor open another game in
+ *  the same window (the editor's own switch, J16.1). */
+export 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 const SWITCH_REGISTER_MS = 30_000;
+/** While a game opens, the agent hears "Opening <game>…" this often. */
+export const OPEN_PROGRESS_EVERY_MS = 3_000;
+/** Says `message` now and every OPEN_PROGRESS_EVERY_MS until the returned stop is called. */
+export function keepSaying(progress, message) {
+    if (!progress)
+        return () => { };
+    progress(message);
+    const timer = setInterval(() => progress(message), OPEN_PROGRESS_EVERY_MS);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
 /** Projects this process launched, by root: when and which process, so a slow first start is waited on while it lives. */
 const launched = new Map();
 /** The answer just given: a caller's immediate retry (withEngine retries a
@@ -104,17 +125,36 @@ function canonicalPath(path) {
 export function hasNoDisplay(env = process.env, platform = process.platform) {
     return platform === "linux" && !env.DISPLAY?.trim() && !env.WAYLAND_DISPLAY?.trim();
 }
-/** A live editor with another project than `root`, named for the person. */
+/** A live editor with another project than `root`, and its name for the person. */
 async function otherOpenProject(root) {
     for (const instance of await listEngineInstances()) {
         if (instance.resourceRoot === root)
             continue;
         if (await checkEngineHealth(instance.port)) {
-            return instance.projectName ? `${instance.projectName} (${instance.resourceRoot})` : instance.resourceRoot;
+            return { instance, name: instance.projectName ? `${instance.projectName} (${instance.resourceRoot})` : instance.resourceRoot };
         }
     }
     return null;
 }
+/** A registered editor with `root` open that answers health, polled until `ms` pass. */
+async function waitForRegisteredEditor(root, ms) {
+    const deadline = Date.now() + ms;
+    while (true) {
+        for (const instance of await listEngineInstances()) {
+            if (instance.resourceRoot === root && (await checkEngineHealth(instance.port)))
+                return true;
+        }
+        if (Date.now() >= deadline)
+            return false;
+        await sleep(50);
+    }
+}
+/** The first op result of an /api/ops answer, or null when it has none. */
+function firstOpResult(answer) {
+    const results = answer?.results;
+    const first = Array.isArray(results) ? results[0] : null;
+    return first && typeof first === "object" ? first : null;
+}
 async function connectWithin(selection, connect, ms) {
     const deadline = Date.now() + ms;
     while (true) {
@@ -173,8 +213,10 @@ export async function openProjectInEditor(root, selection, options = {}, deps =
     if (hasNoDisplay(env))
         throw failure("Summer Engine cannot open a window here.", SELF_START_RECOVERY.noDisplay);
     const open = await otherOpenProject(root);
+    if (open && options.switchOpen)
+        return switchOpenEditor(open, root, selection, connect, log, left, deps);
     if (open)
-        throw failure("Summer Engine has another project open.", SELF_START_RECOVERY.otherProject(open, root));
+        throw failure("Summer Engine has another project open.", SELF_START_RECOVERY.otherProject(open.name, root));
     const binary = resolveRunBinary(undefined, env);
     if (binary.binary === null) {
         // A build named in SUMMER_BIN that is missing is not "not installed": installing would not change it.
@@ -197,6 +239,16 @@ export async function openProjectInEditor(root, selection, options = {}, deps =
     }
     launched.delete(root);
     log(`no editor has ${root} open: launching it in the background`);
+    const stop = keepSaying(deps.progress, `Opening ${basename(root)}…`);
+    try {
+        return await launchAndConnect(root, selection, connect, log, deadline, left, deps, failure);
+    }
+    finally {
+        stop();
+    }
+}
+async function launchAndConnect(root, selection, connect, log, deadline, left, deps, failure) {
+    const now = deps.now ?? Date.now;
     let result;
     try {
         result = await (deps.launch ?? launchEditor)({
@@ -236,6 +288,57 @@ export async function openProjectInEditor(root, selection, options = {}, deps =
             throw failure("Summer Engine could not start.", SELF_START_RECOVERY.launchFailed(result.code));
     }
 }
+/**
+ * J16.1: the running editor opens `root` itself (one window: it starts the
+ * next editor and hands over), then the new editor is waited for through the
+ * registry and connected. An editor without the switch operation keeps the
+ * old answer: it names the open game.
+ */
+async function switchOpenEditor(open, root, selection, connect, log, left, deps) {
+    const reason = `${open.name} is open`;
+    const failure = (message, recovery) => new EngineNotRunningError(message, reason, recovery);
+    log(`switching the editor from ${open.name} to ${root}`);
+    // The agent hears at once and every few seconds; the new editor needs a while (J16.5, J17).
+    const stop = keepSaying(deps.progress, `Opening ${basename(root)}…`);
+    try {
+        return await switchAndConnect(root, selection, connect, left, deps, open, failure);
+    }
+    finally {
+        stop();
+    }
+}
+async function switchAndConnect(root, selection, connect, left, deps, open, failure) {
+    let answer;
+    try {
+        const current = await connect({ instanceId: open.instance.instanceId });
+        answer = await current.executeOps([{ op: SWITCH_PROJECT_OP, path: root }], undefined, Math.max(5_000, left()));
+    }
+    catch (error) {
+        const message = error.message ?? String(error);
+        if (/unknown op|not supported|unsupported|engine_lacks_op/i.test(message)) {
+            throw failure("Summer Engine has another project open.", SELF_START_RECOVERY.switchUnsupported(open.name, root));
+        }
+        throw failure("Summer Engine could not switch games.", SELF_START_RECOVERY.switchFailed(root, message));
+    }
+    const result = firstOpResult(answer);
+    if (result && result.ok === false) {
+        const error = String(result.error ?? result.message ?? "the editor refused");
+        if (/unknown op|not supported|unsupported/i.test(error) || result.failure_reason === "engine_lacks_op") {
+            throw failure("Summer Engine has another project open.", SELF_START_RECOVERY.switchUnsupported(open.name, root));
+        }
+        throw failure("Summer Engine could not switch games.", SELF_START_RECOVERY.switchFailed(root, error));
+    }
+    // The new editor boots, then registers (about 5 s); a first open that
+    // imports assets answers health later: "switching", call again.
+    if (!(await waitForRegisteredEditor(root, Math.min(deps.switchWaitMs ?? SWITCH_REGISTER_MS, left())))) {
+        launched.set(root, { at: Date.now() });
+        throw failure("Summer Engine is switching to the project.", SELF_START_RECOVERY.starting(root));
+    }
+    const client = await connectWithin({ ...selection, instanceId: undefined, projectPath: root }, connect, Math.min(5_000, left()));
+    if (client)
+        return client;
+    throw failure("Summer Engine is starting.", SELF_START_RECOVERY.starting(root));
+}
 /**
  * Open the session's project and return a connected client, or throw an
  * EngineNotRunningError whose recovery is the one next step for this case.
@@ -273,7 +376,7 @@ async function openSessionProject(selection, notRunning, deps) {
     if (env[AUTO_LAUNCH_ENV] === "0") {
         const open = await otherOpenProject(root);
         if (open)
-            throw failure("Summer Engine has another project open.", SELF_START_RECOVERY.otherProject(open, root));
+            throw failure("Summer Engine has another project open.", SELF_START_RECOVERY.otherProject(open.name, root));
         if (resolveRunBinary(undefined, env).binary === null)
             throw failure("Summer Engine is not installed.", SELF_START_RECOVERY.notInstalledHere);
         throw failure(notRunning.message, SELF_START_RECOVERY.autoLaunchOff(root));

package/dist/core/oauth.d.ts

@@ -72,7 +72,20 @@ export declare function runStoreLogin(deps: StoreLoginDependencies): Promise<Sto
 export declare function readStoredOAuthToken(): Promise<StoredOAuthToken | null>;
 /**
  * A current store access token: the stored one, refreshed when it expires
- * within a minute.
+ * within a minute. `force` refreshes now: the sign-in server refuses the
+ * refresh once the person revoked the app, so it checks a token the API
+ * refused.
  */
-export declare function getStoreAccessToken(deps?: OAuthDependencies): Promise<string>;
+export declare function getStoreAccessToken(deps?: OAuthDependencies, options?: {
+    force?: boolean;
+}): Promise<string>;
+/** The sign-in errors that mean the stored sign-in is gone (revoked or expired), not a server or network failure. */
+export declare const SIGN_IN_GONE: Set<string>;
+export declare const isSignInGone: (error: unknown) => boolean;
+/**
+ * Whether this machine's store sign-in still works, checked with the sign-in
+ * server (one refresh). A server or network failure counts as signed in, so
+ * an outage never starts a new sign-in.
+ */
+export declare function storeSignInWorks(deps?: OAuthDependencies): Promise<boolean>;
 export {};

package/dist/core/oauth.js

@@ -287,14 +287,16 @@ export async function readStoredOAuthToken() {
 }
 /**
  * A current store access token: the stored one, refreshed when it expires
- * within a minute.
+ * within a minute. `force` refreshes now: the sign-in server refuses the
+ * refresh once the person revoked the app, so it checks a token the API
+ * refused.
  */
-export async function getStoreAccessToken(deps = defaultDependencies) {
+export async function getStoreAccessToken(deps = defaultDependencies, options = {}) {
     const stored = await readStoredOAuthToken();
     if (!stored) {
         throw new OAuthError("store_login_required", "This machine is not signed in to the Summer store.", 'Recovery: run "summer login --store" in a terminal and approve access in the browser, then retry.');
     }
-    if (Date.parse(stored.expiresAt) - deps.now() > REFRESH_MARGIN_MS)
+    if (!options.force && Date.parse(stored.expiresAt) - deps.now() > REFRESH_MARGIN_MS)
         return stored.accessToken;
     if (!stored.refreshToken) {
         throw new OAuthError("store_login_expired", "The Summer store sign-in expired.", 'Recovery: run "summer login --store --force", then retry.');
@@ -311,3 +313,24 @@ export async function getStoreAccessToken(deps = defaultDependencies) {
     await writeStoreJson(OAUTH_TOKEN_FILE, next);
     return next.accessToken;
 }
+/** The sign-in errors that mean the stored sign-in is gone (revoked or expired), not a server or network failure. */
+export const SIGN_IN_GONE = new Set(["store_login_required", "store_login_expired", "oauth_grant_invalid", "oauth_token_refused", "oauth_token_invalid"]);
+export const isSignInGone = (error) => error instanceof OAuthError && SIGN_IN_GONE.has(error.code);
+/**
+ * Whether this machine's store sign-in still works, checked with the sign-in
+ * server (one refresh). A server or network failure counts as signed in, so
+ * an outage never starts a new sign-in.
+ */
+export async function storeSignInWorks(deps = defaultDependencies) {
+    if (!(await readStoredOAuthToken()))
+        return false;
+    try {
+        await getStoreAccessToken(deps, { force: true });
+        return true;
+    }
+    catch (error) {
+        if (isSignInGone(error))
+            return false;
+        return true;
+    }
+}

package/dist/core/ops/areas.d.ts

@@ -7,5 +7,5 @@
  * Areas with operations today: each is one `summer <area> <action>` command
  * (src/cli/commands/ops.ts). CLI command words stay out of this list.
  */
-export declare const CLI_AREAS: readonly ["team", "profile", "docs", "assets", "makers", "jobs", "projects", "plans", "games", "store", "jams", "pricing", "analytics", "experiments", "marketing", "content", "players", "economy", "inbox", "apps", "studio", "chats", "stories", "plugins", "engine", "account"];
+export declare const CLI_AREAS: readonly ["team", "profile", "docs", "assets", "makers", "jobs", "projects", "plans", "games", "store", "jams", "pricing", "analytics", "experiments", "marketing", "content", "players", "economy", "inbox", "apps", "studio", "chats", "stories", "plugins", "engine", "account", "router", "board"];
 export declare function isLocalOp(op: string): boolean;

package/dist/core/ops/areas.js

@@ -10,7 +10,7 @@
 export const CLI_AREAS = [
     "team", "profile", "docs", "assets", "makers", "jobs", "projects", "plans", "games", "store", "jams", "pricing",
     "analytics", "experiments", "marketing", "content", "players", "economy", "inbox", "apps", "studio", "chats", "stories",
-    "plugins", "engine", "account",
+    "plugins", "engine", "account", "router", "board",
 ];
 /**
  * Operations that run in this package: everything in `engine`, the library
@@ -21,10 +21,12 @@ export const CLI_AREAS = [
  * summer.items.json, and making a
  * piece of content from footage on this computer (content.make; Summer's
  * server keeps the request it reports to), and creating and opening a
- * project on this computer (projects.create_local, projects.open_local).
+ * project on this computer (projects.create_local, projects.open_local),
+ * and the Summer API calls made with the Summer sign-in on this computer
+ * (models.list, models.estimate, models.run, models.batch, models.job).
  * Everything else runs on the hosted server.
  */
-const LOCAL_OPS = new Set(["docs.search", "docs.read", "docs.feedback", "docs.plan", "docs.engine_api", "studio.open", "apps.dock", "apps.publish_folder", "store.upload_file", "store.go_live", "store.set_details", "economy.sync_items", "content.make", "projects.create_local", "projects.open_local"]);
+const LOCAL_OPS = new Set(["docs.search", "docs.read", "docs.feedback", "docs.plan", "docs.engine_api", "studio.open", "apps.dock", "apps.publish_folder", "store.upload_file", "store.go_live", "store.set_details", "economy.sync_items", "content.make", "projects.create_local", "projects.open_local", "models.list", "models.estimate", "models.run", "models.batch", "models.job"]);
 export function isLocalOp(op) {
     return op.startsWith("engine.") || LOCAL_OPS.has(op);
 }

package/dist/core/ops/engine-answer.js

@@ -73,8 +73,11 @@ export function engineFailure(text, op, options) {
     if (code === "engine_lacks_op" || reason === "engine_lacks_op" || reason === "engine_lacks_events" || /engine_lacks_op/.test(text)) {
         return errorAnswer("engine_lacks_op", message, { next: { say: "Update Summer Engine." }, details });
     }
-    if (code && PASSED_CODES.has(code))
-        return errorAnswer(code, message, { details, ...(code === "invalid_input" ? { next: describe } : {}) });
+    if (code && PASSED_CODES.has(code)) {
+        // A signed-out tool answers with a sign-in link (mcp/tool-results.ts withSignInLink): the next step says it.
+        const signIn = code === "not_signed_in" && str(body?.signInUrl) ? { next: { say: str(body?.recovery) ?? `Sign-in link for the person: ${str(body?.signInUrl)}` } } : {};
+        return errorAnswer(code, message, { details, ...signIn, ...(code === "invalid_input" ? { next: describe } : {}) });
+    }
     if (!body && TRANSPORT.test(text)) {
         return options.effect === "read"
             ? errorAnswer("unavailable", message, { retry: "safe", next: { op: "engine.get_project_context" }, details })

package/dist/core/ops/engine.js

@@ -221,6 +221,12 @@ export const ENGINE_OPS = {
         effect: "write",
         example: { input: { nodePath: "Player" }, note: "Show the person the player node." },
     },
+    "engine.view_set": {
+        title: "Show the person a view",
+        summary: "Switch what the person sees while you work: the view (3d, 2d, script, game, chat, home, studio), the right rail, the node or file in focus and the nodes to frame. Only the screen changes. Which view when: the navigate-summer skill.",
+        effect: "write",
+        example: { input: { view: "3d", rail: "scene", focus: "Track/Trees", frame: ["Track/Trees"] }, note: "Watch the level while you place trees." },
+    },
     "engine.batch": {
         title: "Run engine ops in one call",
         summary: "Send a list of raw engine ops (AddNode, SetProp, RunVerification...) in one call: one undo step unless an op must travel alone, and one save at the end. Ask for receipt summary on long lists. For computed edits, engine.run_script is simpler.",

package/dist/core/ops/save-files.d.ts

@@ -50,6 +50,8 @@ export interface FileSaverOptions {
     maxBytes?: number;
 }
 /** Saves the files of generate, assets.get and jobs.wait answers; one per session (it remembers each job's `out`). */
+/** Summer's own stores: a game's .summer/local (checkpoints, project id) and ~/.summer (sign-in, runtime). A save never lands there. */
+export declare function inSummerStore(path: string): boolean;
 export declare class FileSaver {
     private readonly options;
     private readonly jobs;

package/dist/core/ops/save-files.js

@@ -210,6 +210,17 @@ async function claimName(temp, dir, base, ext) {
     throw new Error(`no free file name for ${base}${ext} in ${dir}`);
 }
 /** Saves the files of generate, assets.get and jobs.wait answers; one per session (it remembers each job's `out`). */
+/** Summer's own stores: a game's .summer/local (checkpoints, project id) and ~/.summer (sign-in, runtime). A save never lands there. */
+export function inSummerStore(path) {
+    // Windows paths ignore case: C:\Users\me\.Summer is the same folder.
+    const fold = (value) => (process.platform === "win32" ? value.toLowerCase() : value);
+    const full = fold(resolve(path));
+    const home = fold(join(homedir(), ".summer"));
+    if (full === home || full.startsWith(home + sep))
+        return true;
+    const parts = full.split(/[\\/]/).map((part) => part.toLowerCase());
+    return parts.some((part, index) => part === ".summer" && parts[index + 1] === "local");
+}
 export class FileSaver {
     options;
     jobs = new Map();
@@ -350,6 +361,8 @@ export class FileSaver {
         else {
             path = isAbsolute(out) ? out : resolve(this.cwd(), out);
         }
+        if (inSummerStore(path))
+            return { error: `out: ${out} is Summer's own folder (.summer/local or ~/.summer). Nothing was saved on this machine.` };
         const folder = /[\\/]$/.test(out) || !extname(path) || (await isDirectory(path));
         return folder ? { dir: path } : { dir: dirname(path), file: basename(path) };
     }

package/dist/core/ops/studio-page.d.ts

@@ -0,0 +1,22 @@
+import type { EngineCapabilities } from "../capability-skew.js";
+import { type Answer } from "./contract.js";
+/**
+ * The Studio page ops a running Summer app answers itself, through its own
+ * Studio tab (engine POST /api/studio, advertised as
+ * capabilities.studioPage): the same op names, input and answers as on
+ * Summer's server, with no store sign-in. When the app cannot answer (no
+ * engine, an older build, or no Studio tab: `no_tab`), the caller sends the op
+ * to Summer's server as before.
+ */
+export declare const STUDIO_PAGE_OPS: ReadonlySet<string>;
+export interface StudioPageClient {
+    getEngineCapabilities?(): EngineCapabilities | undefined;
+    studioPage(op: string, input: Record<string, unknown>): Promise<unknown>;
+}
+/** The page's answer as the one answer shape, or null for "send it to Summer's server". */
+export declare function studioPageAnswer(envelope: unknown): Answer | null;
+/**
+ * Run a Studio page op in the app's own Studio tab when the running app
+ * offers it; null when it does not (the op goes to Summer's server).
+ */
+export declare function runInAppStudio(op: string, input: Record<string, unknown>, engine: () => Promise<StudioPageClient>): Promise<Answer | null>;

package/dist/core/ops/studio-page.js

@@ -0,0 +1,63 @@
+import { errorAnswer } from "./contract.js";
+/**
+ * The Studio page ops a running Summer app answers itself, through its own
+ * Studio tab (engine POST /api/studio, advertised as
+ * capabilities.studioPage): the same op names, input and answers as on
+ * Summer's server, with no store sign-in. When the app cannot answer (no
+ * engine, an older build, or no Studio tab: `no_tab`), the caller sends the op
+ * to Summer's server as before.
+ */
+export const STUDIO_PAGE_OPS = new Set(["studio.map", "studio.page", "studio.use_page", "studio.read_form", "studio.submit_form"]);
+const CODES = new Set([
+    "invalid_input", "not_signed_in", "forbidden", "not_found", "conflict", "idempotency_conflict", "in_progress", "rate_limited",
+    "no_credits", "over_limit", "unsupported", "moved", "outcome_unknown", "unavailable",
+]);
+const asRecord = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null;
+/** The page's answer as the one answer shape, or null for "send it to Summer's server". */
+export function studioPageAnswer(envelope) {
+    const record = asRecord(envelope);
+    const first = asRecord(Array.isArray(record?.results) ? record.results[0] : null);
+    if (!first) {
+        return errorAnswer("outcome_unknown", "The Summer app did not say how the Studio page answered.", { next: { op: "studio.page" } });
+    }
+    if (first.ok === true) {
+        const result = asRecord(first.result) ?? {};
+        // An op that waits on the person (needs_approval) or runs on comes back as the answer itself.
+        if (result.status === "needs_approval" || result.status === "running")
+            return { ok: true, ...result };
+        return { ok: true, status: "done", result };
+    }
+    const reason = typeof first.failure_reason === "string" ? first.failure_reason : "unavailable";
+    if (reason === "no_tab")
+        return null;
+    const message = typeof first.error === "string" && first.error ? first.error : "The Studio page refused this.";
+    const code = reason === "timeout" ? "outcome_unknown" : CODES.has(reason) ? reason : "unavailable";
+    return errorAnswer(code, message, code === "outcome_unknown" || code === "conflict" ? { next: { op: "studio.page" } } : {});
+}
+/**
+ * Run a Studio page op in the app's own Studio tab when the running app
+ * offers it; null when it does not (the op goes to Summer's server).
+ */
+export async function runInAppStudio(op, input, engine) {
+    if (!STUDIO_PAGE_OPS.has(op))
+        return null;
+    let client;
+    try {
+        client = await engine();
+    }
+    catch {
+        return null;
+    }
+    if (!client.getEngineCapabilities?.()?.studioPage?.ops.includes(op))
+        return null;
+    const { tabId: _tabId, ...rest } = input;
+    let envelope;
+    try {
+        envelope = await client.studioPage(op, rest);
+    }
+    catch (error) {
+        // Not acknowledged: nothing reached the page.
+        return errorAnswer("unavailable", `The Summer app did not take the Studio op: ${error instanceof Error ? error.message : String(error)}`, { retry: "safe" });
+    }
+    return studioPageAnswer(envelope);
+}

package/dist/core/sign-in-link.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Sign-in links the MCP hands to the agent when a cloud tool needs a sign-in.
+ *
+ * An agent outside Summer (Claude Code, Codex, Cursor) cannot click a browser
+ * for the person, and `summer login` blocks a terminal. So when a tool answers
+ * `not_signed_in`, the long-lived MCP process starts the same `cli_session`
+ * sign-in `summer login` uses, without opening anything, and returns its link;
+ * the agent shows it, the person signs in, and the poll saves the token to
+ * ~/.summer. The next call works: no restart, no reinstall. A
+ * `store_login_required` answer gets the store's approval link the same way
+ * (core/oauth.ts runStoreLogin, loopback callback on this machine).
+ *
+ * One pending sign-in of each kind per process: repeated failures return the
+ * same link until it finishes or expires.
+ */
+export type SignInKind = "account" | "store";
+export interface SignInLinkDependencies {
+    gatewayUrl: () => Promise<string>;
+    randomId: () => string;
+    /** Waits for the account sign-in and saves it; resolves when done. */
+    waitForAccount: (gatewayUrl: string, sessionId: string, cancelled: () => Promise<boolean>) => Promise<unknown>;
+    /** Runs the store approval; calls `onUrl` with its link, resolves when approved. */
+    runStore: (onUrl: (url: string) => void) => Promise<unknown>;
+    /** The saved account token, if any. */
+    accountToken: () => Promise<string | null>;
+    now: () => number;
+}
+export declare class SignInLinks {
+    private readonly deps;
+    private pending;
+    constructor(deps?: SignInLinkDependencies);
+    /** The link for this kind of sign-in, starting the wait when none is pending; null when none can be made. */
+    link(kind: SignInKind): Promise<string | null>;
+}
+/** What the agent shows the person: the link, then what happens after. */
+export declare function signInLinkText(kind: SignInKind, url: string): string;
+/** The sign-in kind a tool error code asks for, if any. */
+export declare function signInKindForCode(code: string | null): SignInKind | null;