summer-engine 4.5.0 → 4.8.0

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;

package/dist/core/sign-in-link.js

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ */
+import { randomUUID } from "crypto";
+import { getAuthToken } from "./auth.js";
+import { cliSessionLoginUrl, pollCliSession, POLL_TIMEOUT_MS } from "./cli-session.js";
+import { resolveGatewayUrl } from "./config.js";
+import { runStoreLogin } from "./oauth.js";
+/** Unref'd timers: a pending sign-in never keeps a finished process alive. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms).unref());
+}
+const defaultDependencies = {
+    gatewayUrl: resolveGatewayUrl,
+    randomId: randomUUID,
+    waitForAccount: (gatewayUrl, sessionId, cancelled) => pollCliSession(gatewayUrl, sessionId, { fetch, sleep, now: Date.now, log: () => { }, cancelled }),
+    runStore: (onUrl) => runStoreLogin({
+        fetch: (input, init) => globalThis.fetch(input, init),
+        now: Date.now,
+        log: () => { },
+        openUrl: async (url) => onUrl(url),
+    }),
+    accountToken: getAuthToken,
+    now: Date.now,
+};
+const STORE_LINK_WAIT_MS = 10_000;
+export class SignInLinks {
+    deps;
+    pending = new Map();
+    constructor(deps = defaultDependencies) {
+        this.deps = deps;
+    }
+    /** The link for this kind of sign-in, starting the wait when none is pending; null when none can be made. */
+    async link(kind) {
+        const current = this.pending.get(kind);
+        if (current && !current.done && this.deps.now() - current.startedAt < POLL_TIMEOUT_MS) {
+            return current.url;
+        }
+        const pending = { url: Promise.resolve(null), startedAt: this.deps.now(), done: false };
+        const finish = () => {
+            pending.done = true;
+        };
+        if (kind === "account") {
+            pending.url = (async () => {
+                const gatewayUrl = await this.deps.gatewayUrl();
+                const sessionId = this.deps.randomId();
+                // Another sign-in (the app, `summer login`) may save a new token
+                // first: stop then. A refused old token does not count.
+                const before = await this.deps.accountToken().catch(() => null);
+                const cancelled = async () => {
+                    const now = await this.deps.accountToken().catch(() => null);
+                    return Boolean(now) && now !== before;
+                };
+                void this.deps.waitForAccount(gatewayUrl, sessionId, cancelled).then(finish, finish);
+                return cliSessionLoginUrl(gatewayUrl, sessionId);
+            })().catch(() => {
+                finish();
+                return null;
+            });
+        }
+        else {
+            pending.url = new Promise((resolve) => {
+                const timer = setTimeout(() => resolve(null), STORE_LINK_WAIT_MS);
+                timer.unref();
+                void this.deps
+                    .runStore((url) => {
+                    clearTimeout(timer);
+                    resolve(url);
+                })
+                    .then(finish, finish)
+                    .finally(() => resolve(null));
+            });
+        }
+        this.pending.set(kind, pending);
+        const url = await pending.url;
+        if (url === null)
+            finish();
+        return url;
+    }
+}
+/** What the agent shows the person: the link, then what happens after. */
+export function signInLinkText(kind, url) {
+    return kind === "account"
+        ? `Sign-in link for the person: ${url}\nAsk them to open it and sign in to Summer. When they are done, call this tool again: it works without a restart or reinstall. Engine tools work without signing in.`
+        : `Store approval link for the person: ${url}\nAsk them to open it on this computer and approve Summer. When they are done, call this tool again: it works without a restart.`;
+}
+/** The sign-in kind a tool error code asks for, if any. */
+export function signInKindForCode(code) {
+    if (code === "not_signed_in")
+        return "account";
+    if (code === "store_login_required")
+        return "store";
+    return null;
+}

package/dist/core/store.js

@@ -39,6 +39,24 @@ async function hardenMode(path, mode) {
             throw error;
     }
 }
+/**
+ * Windows refuses a rename for a moment while another process has the file
+ * open (antivirus scanning the new file, the engine or a second summer reading
+ * the token): retry briefly, the way npm's write-file-atomic does.
+ */
+async function renameIntoPlace(from, to) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await rename(from, to);
+        }
+        catch (error) {
+            const code = error.code ?? "";
+            if (process.platform !== "win32" || attempt >= 10 || !["EPERM", "EACCES", "EBUSY"].includes(code))
+                throw error;
+            await new Promise((done) => setTimeout(done, 25 * attempt));
+        }
+    }
+}
 export async function ensureSummerStore() {
     const dir = getSummerDir();
     try {
@@ -107,7 +125,7 @@ export async function writeStoreText(name, value) {
             flag: "wx",
         });
         await hardenMode(temporary, 0o600);
-        await rename(temporary, destination);
+        await renameIntoPlace(temporary, destination);
         await hardenMode(destination, 0o600);
     }
     catch (error) {