summer-engine 4.6.0 → 4.8.0

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) {

package/dist/core/summer-api.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The Summer API (www.summerengine.com/v1, PublicSummerEngine
+ * src/lib/ops/views/http.ts) from this computer: the curated game-dev models
+ * and their prices, an exact estimate, a job, and its files. `summer api` and
+ * the summer_api_* MCP tools both call these. Sign-in is the Summer OAuth
+ * sign-in on this computer (summer login; core/oauth.ts, refreshed by
+ * itself): one Supabase OAuth access token as the bearer. Listing models and
+ * estimating need none. There are no API keys.
+ *
+ * Until Summer opens the API, every route answers 404 "Nothing is here.":
+ * that is SummerApiError api_not_open, one plain line for people and agents.
+ */
+export declare const API_NOT_OPEN = "Summer API is not open yet.";
+export declare const SIGN_IN_GONE_MESSAGE = "Your Summer sign-in was revoked or has expired. Run \"summer login\", then retry.";
+/** The longest a --wait follows one job (a 3D model with a rig can take minutes). */
+export declare const MAX_JOB_WAIT_MS: number;
+export declare class SummerApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly body?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, status: number, body?: Record<string, unknown> | undefined);
+}
+export interface SummerApiDependencies {
+    fetch: typeof fetch;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    /** The sign-in's current access token (core/oauth.ts); tests pass a fake. */
+    token?: () => Promise<string>;
+    /** A new access token from the sign-in server now; it throws once the person revoked the app. */
+    refresh?: () => Promise<string>;
+}
+export type Job = Record<string, unknown> & {
+    id: string;
+    state: string;
+};
+/** GET /v1/models (optionally one capability), or one model with GET /v1/models/{id}. */
+export declare function listModels(options?: {
+    capability?: string;
+    model?: string;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Record<string, unknown>>;
+/** POST /v1/estimate: the exact price of one job, and a quote id that holds it 15 minutes. Charges nothing. */
+export declare function estimateJob(model: string, input: Record<string, unknown>, overrides?: Partial<SummerApiDependencies>): Promise<Record<string, unknown>>;
+export declare const isFinished: (job: Job) => boolean;
+/**
+ * POST /v1/jobs: spends the person's credits (within the key's limit). One
+ * Idempotency-Key per run, so a retried request never runs twice; `waitSeconds`
+ * (at most 60) asks the server to answer when the job is done.
+ */
+export declare function runJob(model: string, input: Record<string, unknown>, options?: {
+    quoteId?: string;
+    idempotencyKey?: string;
+    waitSeconds?: number;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Job>;
+export declare function getJob(jobId: string, overrides?: Partial<SummerApiDependencies>): Promise<Job>;
+export declare function cancelJob(jobId: string, overrides?: Partial<SummerApiDependencies>): Promise<Job>;
+/** Follow a job until it finishes or `timeoutMs` passes (then it answers the job as it is). */
+export declare function waitForJob(job: Job, options?: {
+    timeoutMs?: number;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Job>;
+/** <assetId><ext> as a file name every system accepts: no : * ? " < > | (a colon is an NTFS stream), no device name. */
+export declare function jobFileName(assetId: string, fileUrl: string): string;
+/** The finished job's files: every asset's fileUrl, saved under `dir` as <assetId><ext>. */
+export declare function downloadJobFiles(job: Job, dir: string, overrides?: Partial<SummerApiDependencies>): Promise<string[]>;
+/** One job of a batch: one line of a --batch file, one item of summer_api_batch. */
+export interface BatchJob {
+    model: string;
+    input: Record<string, unknown>;
+    idempotencyKey?: string;
+}
+export type Batch = Record<string, unknown> & {
+    id: string;
+    jobs: Job[];
+    counts?: Record<string, number>;
+};
+/** The most jobs one POST /v1/batches takes. */
+export declare const MAX_BATCH_JOBS = 500;
+/** The longest a --wait follows one batch (it runs on the account's slots, in order). */
+export declare const MAX_BATCH_WAIT_MS: number;
+/** A JSONL batch: one job per line ({"model", "input", optional "idempotencyKey"}); blank lines are skipped. */
+export declare function parseBatchLines(text: string): BatchJob[];
+/** The same checks for jobs that came as a list (summer_api_batch). */
+export declare function checkBatch(jobs: unknown[]): BatchJob[];
+export declare function getBatch(batchId: string, overrides?: Partial<SummerApiDependencies>): Promise<Batch>;
+/**
+ * POST /v1/batches: up to 500 jobs, all or none. Each is priced first; when
+ * the paid credits and the app's limit cover them all, all are queued (202)
+ * and run in order on the account's slots. When not, nothing runs and the
+ * error (402) says how many fit and how much more is needed. One
+ * Idempotency-Key for the batch, so a retried request never queues it twice.
+ */
+export declare function createBatch(jobs: BatchJob[], options?: {
+    idempotencyKey?: string;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Batch>;
+export declare const isBatchFinished: (batch: Batch) => boolean;
+/** Follow a batch until every job finishes or `timeoutMs` passes (then it answers the batch as it is). */
+export declare function waitForBatch(batch: Batch, options?: {
+    timeoutMs?: number;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Batch>;
+/** Every done job's files under `dir`, by job id. */
+export declare function downloadBatchFiles(batch: Batch, dir: string, overrides?: Partial<SummerApiDependencies>): Promise<Record<string, string[]>>;
+/** summer_api_batch: follow when asked (within one call's time), save files when `out` is given. */
+export declare function batchToolResult(batch: Batch, args: {
+    wait?: boolean;
+    out?: string;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Record<string, unknown>>;
+/** The answer the summer_api_* MCP tools (and `summer tool api-*`) give: the result, or {ok:false, error}. */
+export declare function summerApiToolAnswer(work: () => Promise<Record<string, unknown>>): Promise<Record<string, unknown>>;
+/** One MCP call waits at most this long for a job; then it answers the job as it is (call summer_api_job to keep following). */
+export declare const TOOL_JOB_WAIT_MS = 50000;
+/** summer_api_run and summer_api_job: follow when asked (within one call's time), save files when `out` is given. */
+export declare function jobToolResult(job: Job, args: {
+    wait?: boolean;
+    out?: string;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Record<string, unknown>>;

package/dist/core/summer-api.js

@@ -0,0 +1,281 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { extname, join, resolve } from "node:path";
+import { summerRequestHeaders } from "./agent-host.js";
+import { getStoreAccessToken, isSignInGone, OAuthError } from "./oauth.js";
+import { resolveGatewayUrl } from "./config.js";
+/**
+ * The Summer API (www.summerengine.com/v1, PublicSummerEngine
+ * src/lib/ops/views/http.ts) from this computer: the curated game-dev models
+ * and their prices, an exact estimate, a job, and its files. `summer api` and
+ * the summer_api_* MCP tools both call these. Sign-in is the Summer OAuth
+ * sign-in on this computer (summer login; core/oauth.ts, refreshed by
+ * itself): one Supabase OAuth access token as the bearer. Listing models and
+ * estimating need none. There are no API keys.
+ *
+ * Until Summer opens the API, every route answers 404 "Nothing is here.":
+ * that is SummerApiError api_not_open, one plain line for people and agents.
+ */
+export const API_NOT_OPEN = "Summer API is not open yet.";
+export const SIGN_IN_GONE_MESSAGE = 'Your Summer sign-in was revoked or has expired. Run "summer login", then retry.';
+const FINISHED = new Set(["done", "failed", "cancelled", "declined", "expired", "stale"]);
+/** The longest a --wait follows one job (a 3D model with a rig can take minutes). */
+export const MAX_JOB_WAIT_MS = 20 * 60_000;
+export class SummerApiError extends Error {
+    code;
+    status;
+    body;
+    constructor(code, message, status, body) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.body = body;
+    }
+}
+const defaults = {
+    fetch,
+    sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
+    now: Date.now,
+};
+async function call(method, path, options, deps) {
+    const key = await (deps.token ?? (() => getStoreAccessToken()))().catch((error) => {
+        if (options.key !== "required")
+            return null;
+        if (error instanceof OAuthError)
+            throw new SummerApiError("not_signed_in", 'This computer is not signed in to Summer. Run "summer login", then retry.', 401);
+        throw error;
+    });
+    try {
+        return await send(method, path, options, key, deps);
+    }
+    catch (error) {
+        // Before launch the API answers a refused sign-in the way it answers everyone: "Nothing is here."
+        // So check the sign-in itself: a revoked app cannot refresh, and a live one retries once with a new token.
+        if (!key || !(error instanceof SummerApiError) || error.code !== "api_not_open")
+            throw error;
+        const fresh = await (deps.refresh ?? (() => getStoreAccessToken(undefined, { force: true })))().catch((refused) => {
+            if (isSignInGone(refused))
+                throw new SummerApiError("sign_in_revoked", SIGN_IN_GONE_MESSAGE, 401);
+            throw error;
+        });
+        return send(method, path, options, fresh, deps);
+    }
+}
+async function send(method, path, options, key, deps) {
+    const gateway = await resolveGatewayUrl();
+    const res = await deps.fetch(`${gateway}/v1${path}`, {
+        method,
+        headers: {
+            ...summerRequestHeaders(),
+            ...(key ? { Authorization: `Bearer ${key}` } : {}),
+            ...(options.body !== undefined ? { "Content-Type": "application/json" } : {}),
+            ...options.headers,
+        },
+        ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+        signal: AbortSignal.timeout(90_000),
+    });
+    const body = ((await res.json().catch(() => null)) ?? {});
+    if (res.ok)
+        return { status: res.status, body };
+    const error = (body.error && typeof body.error === "object" ? body.error : {});
+    const message = typeof error.message === "string" ? error.message : `The Summer API answered ${res.status}.`;
+    if (res.status === 404 && (message === "Nothing is here." || !body.error))
+        throw new SummerApiError("api_not_open", API_NOT_OPEN, 404);
+    throw new SummerApiError(typeof error.code === "string" ? error.code : "request_failed", message, res.status, error);
+}
+/** GET /v1/models (optionally one capability), or one model with GET /v1/models/{id}. */
+export async function listModels(options = {}, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    if (options.model)
+        return (await call("GET", `/models/${options.model.split("/").map(encodeURIComponent).join("/")}`, { key: "optional" }, deps)).body;
+    const query = options.capability ? `?capability=${encodeURIComponent(options.capability)}` : "";
+    return (await call("GET", `/models${query}`, { key: "optional" }, deps)).body;
+}
+/** POST /v1/estimate: the exact price of one job, and a quote id that holds it 15 minutes. Charges nothing. */
+export async function estimateJob(model, input, overrides = {}) {
+    return (await call("POST", "/estimate", { body: { model, input }, key: "optional" }, { ...defaults, ...overrides })).body;
+}
+function jobOf(body) {
+    const job = body.job;
+    if (!job || typeof job !== "object" || typeof job.id !== "string") {
+        throw new SummerApiError("request_failed", "The Summer API answered without a job.", 502, body);
+    }
+    return job;
+}
+export const isFinished = (job) => FINISHED.has(job.state);
+/**
+ * POST /v1/jobs: spends the person's credits (within the key's limit). One
+ * Idempotency-Key per run, so a retried request never runs twice; `waitSeconds`
+ * (at most 60) asks the server to answer when the job is done.
+ */
+export async function runJob(model, input, options = {}, overrides = {}) {
+    const headers = { "Idempotency-Key": options.idempotencyKey ?? randomUUID() };
+    if (options.waitSeconds)
+        headers.Prefer = `wait=${Math.min(60, Math.max(1, Math.round(options.waitSeconds)))}`;
+    const { body } = await call("POST", "/jobs", { body: { model, input, ...(options.quoteId ? { quoteId: options.quoteId } : {}) }, headers, key: "required" }, { ...defaults, ...overrides });
+    return jobOf(body);
+}
+export async function getJob(jobId, overrides = {}) {
+    return jobOf((await call("GET", `/jobs/${encodeURIComponent(jobId)}`, { key: "required" }, { ...defaults, ...overrides })).body);
+}
+export async function cancelJob(jobId, overrides = {}) {
+    return jobOf((await call("POST", `/jobs/${encodeURIComponent(jobId)}/cancel`, { body: {}, key: "required" }, { ...defaults, ...overrides })).body);
+}
+/** Follow a job until it finishes or `timeoutMs` passes (then it answers the job as it is). */
+export async function waitForJob(job, options = {}, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    const until = deps.now() + (options.timeoutMs ?? MAX_JOB_WAIT_MS);
+    let current = job;
+    while (!isFinished(current) && deps.now() < until) {
+        const after = typeof current.pollAfterSeconds === "number" ? current.pollAfterSeconds : 5;
+        await deps.sleep(Math.min(30, Math.max(2, after)) * 1000);
+        current = await getJob(current.id, deps);
+    }
+    return current;
+}
+/** Names Windows keeps for devices, with any extension: CON.glb opens the console, not a file. */
+const WINDOWS_DEVICE_NAMES = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])$/i;
+/** <assetId><ext> as a file name every system accepts: no : * ? " < > | (a colon is an NTFS stream), no device name. */
+export function jobFileName(assetId, fileUrl) {
+    const ext = extname(new URL(fileUrl).pathname).slice(0, 8);
+    const base = assetId.replace(/[^A-Za-z0-9._-]+/g, "-");
+    return `${WINDOWS_DEVICE_NAMES.test(base.split(".")[0]) ? `_${base}` : base}${/^\.[A-Za-z0-9]+$/.test(ext) ? ext : ".bin"}`;
+}
+/** The finished job's files: every asset's fileUrl, saved under `dir` as <assetId><ext>. */
+export async function downloadJobFiles(job, dir, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    const result = (job.result && typeof job.result === "object" ? job.result : {});
+    const assets = (Array.isArray(result.assets) ? result.assets : []);
+    const target = resolve(dir);
+    await mkdir(target, { recursive: true });
+    const saved = [];
+    for (const [index, asset] of assets.entries()) {
+        if (typeof asset.fileUrl !== "string")
+            continue;
+        const res = await deps.fetch(asset.fileUrl, { signal: AbortSignal.timeout(120_000) });
+        if (!res.ok)
+            throw new SummerApiError("download_failed", `Could not download ${asset.fileUrl} (${res.status}).`, res.status);
+        const path = join(target, jobFileName(String(asset.assetId ?? `${job.id}-${index + 1}`), asset.fileUrl));
+        await writeFile(path, Buffer.from(await res.arrayBuffer()));
+        saved.push(path);
+    }
+    return saved;
+}
+/** The most jobs one POST /v1/batches takes. */
+export const MAX_BATCH_JOBS = 500;
+/** The longest a --wait follows one batch (it runs on the account's slots, in order). */
+export const MAX_BATCH_WAIT_MS = 2 * 60 * 60_000;
+function batchJobOf(value, where) {
+    const item = (value && typeof value === "object" && !Array.isArray(value) ? value : null);
+    if (!item || typeof item.model !== "string" || !item.model)
+        throw new SummerApiError("invalid_input", `${where}: needs "model", e.g. {"model": "3d/default", "input": {"prompt": "a wooden chest"}}.`, 400);
+    const input = item.input ?? {};
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new SummerApiError("invalid_input", `${where}: "input" must be a JSON object.`, 400);
+    const key = item.idempotencyKey ?? item.idempotency_key;
+    if (key !== undefined && (typeof key !== "string" || !key))
+        throw new SummerApiError("invalid_input", `${where}: "idempotencyKey" must be a string.`, 400);
+    return { model: item.model, input: input, ...(typeof key === "string" ? { idempotencyKey: key } : {}) };
+}
+/** A JSONL batch: one job per line ({"model", "input", optional "idempotencyKey"}); blank lines are skipped. */
+export function parseBatchLines(text) {
+    const jobs = [];
+    for (const [index, raw] of text.split(/\r?\n/).entries()) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            throw new SummerApiError("invalid_input", `Line ${index + 1} is not JSON.`, 400);
+        }
+        jobs.push(batchJobOf(value, `Line ${index + 1}`));
+    }
+    return checkBatch(jobs);
+}
+/** The same checks for jobs that came as a list (summer_api_batch). */
+export function checkBatch(jobs) {
+    if (jobs.length === 0)
+        throw new SummerApiError("invalid_input", "The batch has no jobs.", 400);
+    if (jobs.length > MAX_BATCH_JOBS)
+        throw new SummerApiError("invalid_input", `The batch has ${jobs.length} jobs; one batch takes at most ${MAX_BATCH_JOBS}.`, 400);
+    return jobs.map((job, index) => batchJobOf(job, `Job ${index + 1}`));
+}
+function batchOf(body) {
+    const batch = body.batch;
+    if (!batch || typeof batch !== "object" || typeof batch.id !== "string") {
+        throw new SummerApiError("request_failed", "The Summer API answered without a batch.", 502, body);
+    }
+    return batch;
+}
+export async function getBatch(batchId, overrides = {}) {
+    return batchOf((await call("GET", `/batches/${encodeURIComponent(batchId)}`, { key: "required" }, { ...defaults, ...overrides })).body);
+}
+/**
+ * POST /v1/batches: up to 500 jobs, all or none. Each is priced first; when
+ * the paid credits and the app's limit cover them all, all are queued (202)
+ * and run in order on the account's slots. When not, nothing runs and the
+ * error (402) says how many fit and how much more is needed. One
+ * Idempotency-Key for the batch, so a retried request never queues it twice.
+ */
+export async function createBatch(jobs, options = {}, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    const headers = { "Idempotency-Key": options.idempotencyKey ?? randomUUID() };
+    const batch = batchOf((await call("POST", "/batches", { body: { jobs }, headers, key: "required" }, deps)).body);
+    // A replayed batch answers its job count only: read its jobs.
+    return Array.isArray(batch.jobs) ? batch : getBatch(batch.id, deps);
+}
+export const isBatchFinished = (batch) => batch.jobs.length > 0 && batch.jobs.every(isFinished);
+/** Follow a batch until every job finishes or `timeoutMs` passes (then it answers the batch as it is). */
+export async function waitForBatch(batch, options = {}, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    const until = deps.now() + (options.timeoutMs ?? MAX_BATCH_WAIT_MS);
+    let current = batch;
+    while (!isBatchFinished(current) && deps.now() < until) {
+        await deps.sleep(10_000);
+        current = await getBatch(current.id, deps);
+    }
+    return current;
+}
+/** Every done job's files under `dir`, by job id. */
+export async function downloadBatchFiles(batch, dir, overrides = {}) {
+    const files = {};
+    for (const job of batch.jobs) {
+        if (job.state === "done")
+            files[job.id] = await downloadJobFiles(job, dir, overrides);
+    }
+    return files;
+}
+/** summer_api_batch: follow when asked (within one call's time), save files when `out` is given. */
+export async function batchToolResult(batch, args, overrides = {}) {
+    const follow = args.wait === true || typeof args.out === "string";
+    const final = follow && !isBatchFinished(batch) ? await waitForBatch(batch, { timeoutMs: TOOL_JOB_WAIT_MS }, overrides) : batch;
+    const files = typeof args.out === "string" ? await downloadBatchFiles(final, args.out, overrides) : undefined;
+    return {
+        batch: final,
+        ...(files ? { files } : {}),
+        ...(isBatchFinished(final) ? {} : { next: `Call summer_api_batch with batchId ${final.id} (wait: true${typeof args.out === "string" ? ", out" : ""}) to keep following it.` }),
+    };
+}
+/** The answer the summer_api_* MCP tools (and `summer tool api-*`) give: the result, or {ok:false, error}. */
+export async function summerApiToolAnswer(work) {
+    try {
+        return { ok: true, ...(await work()) };
+    }
+    catch (error) {
+        if (error instanceof SummerApiError)
+            return { ok: false, error: { code: error.code, message: error.message } };
+        return { ok: false, error: { code: "request_failed", message: error instanceof Error ? error.message : String(error) } };
+    }
+}
+/** One MCP call waits at most this long for a job; then it answers the job as it is (call summer_api_job to keep following). */
+export const TOOL_JOB_WAIT_MS = 50_000;
+/** summer_api_run and summer_api_job: follow when asked (within one call's time), save files when `out` is given. */
+export async function jobToolResult(job, args, overrides = {}) {
+    const follow = args.wait === true || typeof args.out === "string";
+    const final = follow && !isFinished(job) ? await waitForJob(job, { timeoutMs: TOOL_JOB_WAIT_MS }, overrides) : job;
+    const files = typeof args.out === "string" && final.state === "done" ? await downloadJobFiles(final, args.out, overrides) : undefined;
+    return { job: final, ...(files ? { files } : {}), ...(isFinished(final) ? {} : { next: `Call summer_api_job with jobId ${final.id} (wait: true) to keep following it.` }) };
+}

package/dist/mcp/ops-surface.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { type Answer } from "../core/ops/contract.js";
 import { type FileSaver } from "../core/ops/save-files.js";
 import type { HostedLocalHook } from "./hosted-mount.js";
 /**
@@ -45,6 +46,8 @@ export interface OpsSurfaceOptions {
     legacy?: boolean;
     /** Saves generated files on this machine (`out`, localPath); shared with the mounted hosted tools. */
     files: FileSaver;
+    /** A Studio page op in the running app's own Studio tab (core/ops/studio-page.ts); null sends it to Summer's server. */
+    studio?: (op: string, input: Record<string, unknown>) => Promise<Answer | null>;
 }
 /** Its v4 description, within the 300-character summary rule; the full text stays on the 3.x surface. */
 export declare const ENGINE_REFERENCE_SUMMARY = "Look up an engine class offline before writing script code: inherits, properties, methods, signals and constants, or one member. Lists only members declared on that class (walk inherits). No engine needed. Next: summer_run_script.";

package/dist/mcp/ops-surface.js

@@ -420,6 +420,12 @@ export function applyOpsSurface(server, options) {
                 return toolResult(errorAnswer("not_in_profile", `${resolved} is not served by this profile.`, { next: { say: "Run the MCP with --profile engine." } }));
             return toolResult(await runLocal(resolved, call, extra, dryRun === true, args));
         }
+        // The running Summer app answers its own Studio tab's ops itself; else Summer's server does.
+        if (options.studio && dryRun !== true) {
+            const inApp = await options.studio(resolved, args);
+            if (inApp)
+                return toolResult(inApp);
+        }
         // `out` stays here: this package saves the files (core/ops/save-files.ts).
         const { input: sent, out } = options.files.take(resolved, args);
         let raw;

package/dist/mcp/server.js

@@ -24,6 +24,7 @@ import { registerAssetTools } from "./tools/asset-tools.js";
 import { registerGenerateTools } from "./tools/generate-tools.js";
 import { registerCreatorTools } from "./tools/creator-tools.js";
 import { registerFeedbackTools } from "./tools/feedback-tools.js";
+import { registerApiTools } from "./tools/api-tools.js";
 import { registerNavigationTools } from "./tools/navigation-tools.js";
 import { registerLibraryTools } from "./tools/library-tools.js";
 import { getCachedBootDriftNotice as getCachedNotice, setCachedBootDriftNotice, } from "./boot-notice.js";
@@ -31,6 +32,7 @@ import { appendMcpLogEvent } from "../core/mcp-log.js";
 import { defaultHostedMountDependencies, prepareHostedMount } from "./hosted-mount.js";
 import { applyOpsSurface, hostedFileTools, OPS_MCP_ASSETS_INSTRUCTIONS, OPS_MCP_INSTRUCTIONS, SUMMER_CALL, SUMMER_SEARCH } from "./ops-surface.js";
 import { FileSaver } from "../core/ops/save-files.js";
+import { runInAppStudio } from "../core/ops/studio-page.js";
 import { opForToolCall } from "../core/ops/contract.js";
 import { knownOp } from "../core/ops/catalog.js";
 import { v4HostedUrl } from "../core/ops/cloud.js";
@@ -38,7 +40,8 @@ import { serveProviderSafeToolSchemas } from "./provider-safe-schema.js";
 import { legacyHostedDescription, resolveLegacy, takeLegacyToolset } from "./legacy-toolset.js";
 import { refreshInstalledSkills, refreshNotice } from "../installer/skills-refresh.js";
 import { OUTPUT_CAPS, PROFILE_TOOL_LIMIT, PROFILES, TOOLSETS, annotationsFor, registryAuthorities, resolveToolSelection, selectionIncludes, withMaxCharactersArg, } from "./tool-surface.js";
-import { shapeToolResult, singleEditCounter } from "./tool-results.js";
+import { shapeToolResult, singleEditCounter, withSignInLink } from "./tool-results.js";
+import { SignInLinks } from "../core/sign-in-link.js";
 import { recordLocalToolCall, recordMcpSession, toolErrorCode } from "../core/telemetry.js";
 import { boundProject } from "../core/usage-fields.js";
 import { currentToolContext, registerMcpClientSource, runWithToolContext } from "../core/agent-host.js";
@@ -224,7 +227,7 @@ function rawShapeIndex(args) {
     }
     return -1;
 }
-function installToolCallWrapper(server, surfaceMeta) {
+function installToolCallWrapper(server, surfaceMeta, signInLinks = new SignInLinks()) {
     const target = server;
     const original = target.tool.bind(server);
     const singleEdits = singleEditCounter();
@@ -305,6 +308,11 @@ function installToolCallWrapper(server, surfaceMeta) {
             catch {
                 // Shaping must never break the tool call; the raw result goes out.
             }
+            if (isError && !nested) {
+                // A cloud tool that needs a sign-in answers with a link the agent can
+                // show; the sign-in it starts turns the tool on without a restart.
+                result = await withSignInLink(result, toolErrorCode(result, meta?.failureReason ?? meta?.errorClass), signInLinks);
+            }
             try {
                 recordMcpSession();
                 recordUsage(!isError, durationMs, isError ? toolErrorCode(result, meta?.failureReason ?? meta?.errorClass) : null);
@@ -418,6 +426,7 @@ export function createMcpServer(selection = FULL_SELECTION, options = {}) {
     registerGenerateTools(server);
     registerCreatorTools(server);
     registerFeedbackTools(server);
+    registerApiTools(server);
     registerScriptTools(server);
     registerPerceptionTools(server);
     registerSpatialTools(server);
@@ -451,8 +460,11 @@ export function createMcpServer(selection = FULL_SELECTION, options = {}) {
     }
     // Without engine tools nothing imports a file into a project, so files save into it by default.
     const files = new FileSaver({ saveByDefault: !engine });
-    if (surface === "v4")
-        applyOpsSurface(server, { engine, cloud: options.cloud ?? NO_CLOUD, legacy: options.legacy === true, files });
+    if (surface === "v4") {
+        // Studio page ops go to the running app's own Studio tab when it offers them (no engine launch).
+        const studio = (op, input) => runInAppStudio(op, input, () => getClient({ launch: false }));
+        applyOpsSurface(server, { engine, cloud: options.cloud ?? NO_CLOUD, legacy: options.legacy === true, files, studio });
+    }
     return { server, getRegisteredToolCount: () => getWrappedToolCount() - removed, files };
 }
 /** What the hosted tools a profile mounts are, for summer_store_tools. */

package/dist/mcp/tool-results.d.ts

@@ -1,3 +1,4 @@
+import { type SignInKind } from "../core/sign-in-link.js";
 type Content = {
     type?: string;
     text?: unknown;
@@ -23,4 +24,12 @@ export declare const SINGLE_EDIT_HINT_AT = 4;
  * then every 6th.
  */
 export declare function singleEditCounter(): (tool: string, isError: boolean) => string | null;
+/**
+ * A `not_signed_in` / `store_login_required` answer gets one more text block:
+ * the sign-in link for the person (core/sign-in-link.ts). Anything else, or
+ * no link, leaves the result as it is. Never throws.
+ */
+export declare function withSignInLink(result: unknown, code: string | null, links: {
+    link: (kind: SignInKind) => Promise<string | null>;
+}): Promise<unknown>;
 export {};