summer-engine 4.6.0 → 4.8.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "summer",
       "source": "./",
-      "version": "4.6.0",
+      "version": "4.8.0",
       "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. A first-run guide (/summer:start), game-dev skills, and two MCP servers: the bridge to the Summer Engine desktop app, and Summer's hosted cloud server for people without it.",
       "author": {
         "name": "Summer Engine",

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "summer",
   "displayName": "Summer Engine",
-  "version": "4.6.0",
+  "version": "4.8.0",
   "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. A first-run guide (/summer:start), game-dev skills, and two MCP servers: the bridge to the Summer Engine desktop app, and Summer's hosted cloud server for people without it.",
   "author": {
     "name": "Summer Engine",
@@ -35,7 +35,6 @@
     "./library/skills/3d-lighting/",
     "./library/skills/adaptive-music/",
     "./library/skills/agent-playtesting/",
-    "./library/skills/ai-characters-in-games/",
     "./library/skills/ambient-bed/",
     "./library/skills/animated-loop/",
     "./library/skills/animation-tree/",
@@ -115,6 +114,7 @@
     "./library/skills/store-art/",
     "./library/skills/store-listing/",
     "./library/skills/summer-analytics/",
+    "./library/skills/summer-api/",
     "./library/skills/summer-apps/",
     "./library/skills/summer-apps-design/",
     "./library/skills/summer-assets/",
@@ -125,6 +125,7 @@
     "./library/skills/summer-matchmaking/",
     "./library/skills/summer-parties/",
     "./library/skills/summer-player-data/",
+    "./library/skills/summer-router/",
     "./library/skills/summer-store/",
     "./library/skills/summer-world-chat/",
     "./library/skills/summer-world-saves/",

package/.codex-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "_generated": "GENERATED from integrations/codex — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "4.6.0",
-  "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. Game-dev skills, lifecycle hooks, and a 125-tool MCP bridge to the Summer Engine desktop app.",
+  "version": "4.8.0",
+  "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. Game-dev skills, lifecycle hooks, and a 131-tool MCP bridge to the Summer Engine desktop app.",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com",
@@ -25,7 +25,6 @@
     "./library/skills/3d-lighting/",
     "./library/skills/adaptive-music/",
     "./library/skills/agent-playtesting/",
-    "./library/skills/ai-characters-in-games/",
     "./library/skills/ambient-bed/",
     "./library/skills/animated-loop/",
     "./library/skills/animation-tree/",
@@ -105,6 +104,7 @@
     "./library/skills/store-art/",
     "./library/skills/store-listing/",
     "./library/skills/summer-analytics/",
+    "./library/skills/summer-api/",
     "./library/skills/summer-apps/",
     "./library/skills/summer-apps-design/",
     "./library/skills/summer-assets/",
@@ -115,6 +115,7 @@
     "./library/skills/summer-matchmaking/",
     "./library/skills/summer-parties/",
     "./library/skills/summer-player-data/",
+    "./library/skills/summer-router/",
     "./library/skills/summer-store/",
     "./library/skills/summer-world-chat/",
     "./library/skills/summer-world-saves/",
@@ -148,7 +149,7 @@
   "interface": {
     "displayName": "Summer Engine",
     "shortDescription": "Make games with AI",
-    "longDescription": "Summer Engine is the game engine built for AI. Codex builds a full multiplayer game in it, plays and tests it, and publishes it on summer.games. The plugin adds game-dev skills, lifecycle hooks, and a 125-tool MCP bridge to the Summer Engine desktop app: project files, scenes, asset import, play mode, screenshots, diagnostics, asset generation and the store. Git, shell, and grep stay with Codex. Session-start orients each session. The pre-commit doctor (opt-in) blocks bad commits.",
+    "longDescription": "Summer Engine is the game engine built for AI. Codex builds a full multiplayer game in it, plays and tests it, and publishes it on summer.games. The plugin adds game-dev skills, lifecycle hooks, and a 131-tool MCP bridge to the Summer Engine desktop app: project files, scenes, asset import, play mode, screenshots, diagnostics, asset generation and the store. Git, shell, and grep stay with Codex. Session-start orients each session. The pre-commit doctor (opt-in) blocks bad commits.",
     "developerName": "Summer Labs, Inc.",
     "category": "Developer Tools",
     "capabilities": [

package/.cursor-plugin/plugin.json

@@ -3,8 +3,8 @@
   "_generated": "GENERATED from integrations/cursor — do not edit; npm run generate:registry",
   "name": "summer",
   "displayName": "Summer Engine",
-  "version": "4.6.0",
-  "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. Game-dev skills, lifecycle hooks, and a 125-tool MCP bridge to the Summer Engine desktop app.",
+  "version": "4.8.0",
+  "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. Game-dev skills, lifecycle hooks, and a 131-tool MCP bridge to the Summer Engine desktop app.",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com"
@@ -38,7 +38,6 @@
     "./library/skills/3d-lighting/",
     "./library/skills/adaptive-music/",
     "./library/skills/agent-playtesting/",
-    "./library/skills/ai-characters-in-games/",
     "./library/skills/ambient-bed/",
     "./library/skills/animated-loop/",
     "./library/skills/animation-tree/",
@@ -118,6 +117,7 @@
     "./library/skills/store-art/",
     "./library/skills/store-listing/",
     "./library/skills/summer-analytics/",
+    "./library/skills/summer-api/",
     "./library/skills/summer-apps/",
     "./library/skills/summer-apps-design/",
     "./library/skills/summer-assets/",
@@ -128,6 +128,7 @@
     "./library/skills/summer-matchmaking/",
     "./library/skills/summer-parties/",
     "./library/skills/summer-player-data/",
+    "./library/skills/summer-router/",
     "./library/skills/summer-store/",
     "./library/skills/summer-world-chat/",
     "./library/skills/summer-world-saves/",

package/.factory-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "_generated": "GENERATED from integrations/factory — do not edit; npm run generate:registry",
   "name": "summer",
-  "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. Game-dev skills, lifecycle hooks, and a 125-tool MCP bridge to the Summer Engine desktop app.",
-  "version": "4.6.0",
+  "description": "The game engine built for AI. Any agent makes a multiplayer game and publishes it. Game-dev skills, lifecycle hooks, and a 131-tool MCP bridge to the Summer Engine desktop app.",
+  "version": "4.8.0",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com",
@@ -22,7 +22,6 @@
     "./library/skills/3d-lighting/",
     "./library/skills/adaptive-music/",
     "./library/skills/agent-playtesting/",
-    "./library/skills/ai-characters-in-games/",
     "./library/skills/ambient-bed/",
     "./library/skills/animated-loop/",
     "./library/skills/animation-tree/",
@@ -102,6 +101,7 @@
     "./library/skills/store-art/",
     "./library/skills/store-listing/",
     "./library/skills/summer-analytics/",
+    "./library/skills/summer-api/",
     "./library/skills/summer-apps/",
     "./library/skills/summer-apps-design/",
     "./library/skills/summer-assets/",
@@ -112,6 +112,7 @@
     "./library/skills/summer-matchmaking/",
     "./library/skills/summer-parties/",
     "./library/skills/summer-player-data/",
+    "./library/skills/summer-router/",
     "./library/skills/summer-store/",
     "./library/skills/summer-world-chat/",
     "./library/skills/summer-world-saves/",

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to summer-engine will be documented here. Following [Keep a
 
 ## [Unreleased]
 
+## [4.8.0] - 2026-10-24
+
+The Summer API with the Summer sign-in (no static API keys), Studio inside the Summer app, and agents that show the person what they work on. 4.7.0 and the 2026-10-22 4.8.0 draft were never published; this 4.8.0 includes them (sections below).
+
+- **`engine.view_set` (`summer_view_set`) shows the person what the agent works on**: the Summer app's view (home, chat, 3D, 2D, script, game, Studio), the right rail, the focus and the nodes to frame, through the engine's `SetView` operation. Needs Summer Engine 4.6 or newer.
+- **`studio.radio`**: agents read and play Summer Radio in the person's open Studio tab (state, play, stop, station, track, next, previous, volume). The operations catalog is synced from PublicSummerEngine main (262 operations).
+- **A generated file never saves into Summer's own folders.** `out` on the generate operations, `assets.get` and `jobs.wait` refuses a game's `.summer/local` (checkpoints, project id) and `~/.summer` (sign-in, runtime), with a warning; nothing is downloaded. The game's memory beside it (`.summer/GameSoul.md`, `.summer/memory/`) is unchanged.
+- **`projects.open_local` switches the running editor.** When Summer Engine already has another project open, that editor now opens the asked one in the same window (the engine's `SwitchProject` operation) instead of answering "another project is open". The MCP says "Opening <game>…" at once (MCP progress) and waits up to 10 s for the new editor to register, then connects to it. An editor without the operation keeps the old answer and names the open project. Other tools never switch the open project.
+- **Signed out? Cloud tools answer with a sign-in link.** When an MCP tool needs the Summer sign-in (`not_signed_in`) or the store approval (`store_login_required`), its answer now ends with a link the agent shows to the person. The MCP starts the same browser sign-in `summer login` uses (`cli_session`) without opening anything, waits for it in the background, and saves the token to `~/.summer`, so the next call works with no restart or reinstall. Engine tools keep working signed out. One link per process until that sign-in finishes or expires (15 minutes).
+- **`summer api` and the `summer_api_*` MCP tools use the Summer sign-in on this computer**: the same Supabase OAuth 2.1 login (PKCE, a loopback redirect on 127.0.0.1) as the store tools. It stores the refresh token in `~/.summer/oauth-token` and refreshes by itself. Each app spends the person's paid credits up to the limit they set in Connected apps.
+- **`summer api run --batch jobs.jsonl`** queues up to 500 Summer API jobs at once (`POST /v1/batches`), one job per line (`model`, `input`, optional `idempotencyKey`), all or none: when paid credits or the app's limit cannot cover them all, nothing runs and the error says how many fit. `--wait` follows every job, `--download [dir]` saves their files, and the JSON summary prints when piped. The MCP tool `summer_api_batch` does the same. No rate limits on paid usage: jobs past the account's running slots answer `queued` and start in order.
+- **`summer api` on Windows.** `--input "@input.json"` reads the input from a file (Windows PowerShell 5 strips the quotes inside `'{"prompt":"..."}'`, and cmd.exe has no single quotes). Batch and input files may be UTF-16 (what Windows PowerShell 5 writes with `>`) or UTF-8 with a BOM, with CRLF lines. Saved files never get a name Windows keeps for a device (`CON`, `NUL`, `COM1`...) or a `:` that would write an NTFS stream. Writing the sign-in to `~/.summer` retries for a moment while antivirus or another Summer process has the file open, and `out` refuses `~/.summer` in any letter case on Windows. CI runs the Summer API and sign-in tests on Windows, macOS and Linux.
+- **`summer token`** prints a one-hour access token for curl: `curl -H "Authorization: Bearer $(summer token)" https://www.summerengine.com/v1/models`.
+- **Studio page ops run in the Summer app's own Studio tab.** `summer_call` sends `studio.map`, `studio.page`, `studio.use_page`, `studio.read_form` and `studio.submit_form` to the running Summer Engine (`POST /api/studio`) when it lists them in `capabilities.studioPage`, with the same input and answers and no store sign-in. When the app has no Studio tab (`no_tab`) or is not running, they go to Summer's server as before.
+- The operations catalog is synced from PublicSummerEngine main: `account.usage` (plan, share used and refill day, in words) and asset generations in `jobs.list`.
+- **Studio pages open in the Summer app's Studio tab.** `studio.open` (`summer_open`, `summer open`) with a `/studio...` page sends the running Summer Engine `Navigate {target: "studio", path}` when the engine lists the `studio` destination, so the app's own Studio tab moves instead of a browser opening. With the engine off or an older engine, the browser opens as before.
+- **Skills `summer-api` and `summer-router`.** `summer-api`: sign in, models, estimate, one job or a batch, follow and download, money refusals (`no_credits`, `over_limit`), prompts per asset type. `summer-router`: AI characters in games on Summer Games (early preview): client and server calls, the character document, tools, speech and images, caps and error tags. `ai-characters-in-games` is retired (its id points to `summer-router`).
+- **`summer router <action>`** runs the Summer Router operations from a shell: `save-character`, `test-character`, `models`, `settings`, `set-settings`, `usage` and the rest. The operations catalog is synced from PublicSummerEngine main.
+- `summer_api_run`, `summer_api_batch` and `summer_api_job` name `no_credits` and `over_limit`, and say that Summer API jobs run to the end once accepted.
+- **Removed:** `summer login --api-key`, the MCP tool `summer_api_key_login` (operation `account.api_key_login`), `SUMMER_API_KEY` and `~/.summer/api-key`.
+
+## 4.8.0 draft - 2026-10-22 (not published)
+
+The Summer API from a shell and from MCP. 4.7.0 was not published to npm; 4.8.0 is the first release with it (the [4.7.0] section below).
+
+- **`summer api models|estimate|run|jobs`** call the Summer API (`/v1`) with the Summer API key on this computer (`summer login --api-key`, or `SUMMER_API_KEY`). `models` lists the curated game-dev models with their input and USD price (one model by id, `--capability` to filter); `estimate <model> --input '<json>'` prices one exact job and gives a quote id; `run <model> --input '<json>'` spends the person's credits within the key's limit, with one idempotency key per run, `--quote`, `--wait` to follow the job and `--download [dir]` to save its files; `jobs <id>` reads, follows (`--wait`), downloads or `--cancel`s a job. JSON when stdout is not a terminal (or `--json`), a short summary otherwise.
+- **MCP tools** `summer_api_models`, `summer_api_estimate`, `summer_api_run` and `summer_api_job` do the same (operations `models.list`, `models.estimate`, `models.run`, `models.job`, local), in the assets and full profiles.
+- **Until Summer opens the API**, `summer api` and `summer login --api-key` print one line, "Summer API is not open yet.", and exit 1.
+- The operations catalog is synced from PublicSummerEngine main.
+
+## [4.7.0] - 2026-10-22
+
+A Summer API key for your agent with one Allow click, and Node 22.
+
+- **A Summer API key for your agent with one Allow click.** `summer login --api-key` (and the MCP tool `summer_api_key_login`, operation `account.api_key_login`) asks Summer for a key: the person opens the Summer page it names, checks the code matches and presses Allow, choosing the spend limit there. The key is saved to `~/.summer/api-key` (owner-only, like `auth-token`) and is never printed or returned to the agent; `SUMMER_API_KEY` wins over the file. Without a terminal, `summer login --api-key` prints JSON lines (`needs_approval` with `approve_url` and `user_code`, then `approved`, `denied`, `expired` or `failed`). `summer logout` removes the key too. Until Summer turns API keys on, the request answers `keys_unavailable`.
+- **Node 22+** (`engines.node >= 22`, was 20). Node 20 reached end of life on 2026-04-30 and gets no security fixes. `summer doctor` now fails on Node below 22, and CI runs the CLI on Node 22.23.4 (the 2026-10-21 security release) on macOS, Windows and Ubuntu.
+
 ## [4.6.0] - 2026-10-21
 
 A first game that looks finished, and `summer setup` for the Summer desktop app's one-click agent connect.

package/README.md

@@ -20,10 +20,10 @@
 
 ## Install
 
-- **Start a game now** (Node 20+): `npx -y summer-engine@latest dev`. It asks before it installs the Summer Engine app (about 660 MB, free) when it is missing, creates a starter project here (in `./my-game` when this folder has other files) and opens it, ready for your agent. No sign-in needed to build.
+- **Start a game now** (Node 22+): `npx -y summer-engine@latest dev`. It asks before it installs the Summer Engine app (about 660 MB, free) when it is missing, creates a starter project here (in `./my-game` when this folder has other files) and opens it, ready for your agent. No sign-in needed to build.
 - **Chat apps** (Claude, ChatGPT, Cursor...): add `https://mcp.summerengine.com/mcp`. Nothing to install.
 - **Homebrew:** `brew install summerengine/tap/summer`
-- **npm** (Node 20+): `npm install -g summer-engine`
+- **npm** (Node 22+): `npm install -g summer-engine`
 
 **CLI only** (summer-engine 4.2.0 or newer), no MCP server: `summer setup --cli`. `summer ops search "publish my game"` finds any operation, signed in or not.
 
@@ -40,7 +40,7 @@
 | Devin Desktop (formerly Windsurf) | add `"summer-cloud": {"serverUrl": "https://mcp.summerengine.com/mcp"}` under `mcpServers` in `~/.config/devin/mcp_config.json` (Windows `%APPDATA%\devin\mcp_config.json`) |
 | Claude Desktop, claude.ai | Settings > Connectors > Add custom connector, then paste the URL |
 
-**Engine work: `npx -y summer-engine@latest setup <agent> --yes`** (needs Node 20+). It writes the local server (`summer mcp`) into your agent's config with the skills. The local server drives the Summer Engine app on your machine: build scenes, write scripts, play the game, take screenshots, read errors. After `summer login` it also runs every cloud operation, so your agent needs one server. Or paste the prompt in [Get started](#get-started-one-prompt) and your agent does every step.
+**Engine work: `npx -y summer-engine@latest setup <agent> --yes`** (needs Node 22+). It writes the local server (`summer mcp`) into your agent's config with the skills. The local server drives the Summer Engine app on your machine: build scenes, write scripts, play the game, take screenshots, read errors. After `summer login` it also runs every cloud operation, so your agent needs one server. Or paste the prompt in [Get started](#get-started-one-prompt) and your agent does every step.
 
 **CLI only (summer-engine 4.2.0 or newer): `npx -y summer-engine@latest setup <agent> --cli --yes`.** No MCP server: your agent runs Summer as commands in its shell. Setup installs the skills for your agent, with `summer-cli`, the guide to the commands, and writes no MCP entry. Your agent signs you in with `summer login`, finds an operation with `summer ops search "<what you want>"` and runs it as `summer <area> <action> --<field> <value>`, with `--dry-run`, `--wait` and `--json`. Engine commands (`summer engine …`) drive the Summer Engine app on your machine. Each skill ends with a table of the command for every tool it names. Add `--assets-only` for only the asset skills. `--no-mcp` is the same as `--cli`.
 

package/commands/start.md

@@ -17,7 +17,7 @@ $ARGUMENTS
 ## 1. Look before you ask (read-only, a few seconds)
 
 - Tools you already have: the `summer-engine` server (local, drives the Summer Engine desktop app; its tools include `summer_get_project_context`) and the `summer-cloud` server (hosted, Summer's cloud; its tools include `summer_whoami`, `summer_search` and `summer_call` once the user is signed in). A server that needs sign-in shows no tools yet.
-- `npx -y summer-engine@latest status` tells you whether the engine is running. If `npx` is missing, there is no Node: plan it first (3a) and have them install Node 20 or later (nodejs.org) for the build.
+- `npx -y summer-engine@latest status` tells you whether the engine is running. If `npx` is missing, there is no Node: plan it first (3a) and have them install Node 22 or later (nodejs.org) for the build.
 
 Do not run `summer setup claude-code` here: this plugin already brings the MCP servers and the skills, and a second copy of the skills only crowds the list.
 

package/dist/cli/commands/api.d.ts

@@ -0,0 +1,43 @@
+import { Command } from "commander";
+import { type SummerApiDependencies } from "../../core/summer-api.js";
+/**
+ * `summer api models|estimate|run|jobs`: the Summer API (core/summer-api.ts)
+ * from a shell. JSON when stdout is not a terminal (or with --json); a short
+ * summary for people. `--wait` follows a job until it finishes; `--download
+ * [dir]` also saves its files. `run --batch file.jsonl` queues up to 500
+ * jobs at once (all or none). While Summer has not opened the API, every
+ * command prints one line, "Summer API is not open yet.", and exits 1.
+ */
+export interface ApiCommandIo {
+    isTTY: boolean;
+    print: (line: string) => void;
+    printError: (line: string) => void;
+}
+type JsonOption = {
+    json?: boolean;
+};
+/** A text file as any system writes it: UTF-8 with or without a BOM, or UTF-16 (Windows PowerShell 5's > and Out-File). */
+export declare function readTextFile(file: string): Promise<string>;
+/**
+ * --input: a JSON object, or "@file" with one. Windows PowerShell 5 strips the
+ * inner quotes of '{"prompt":"..."}' before the CLI sees them, and cmd.exe has
+ * no single quotes, so a file is the dependable way there (quoted: PowerShell
+ * reads a bare @ as splatting).
+ */
+export declare function parseInput(text: string | undefined): Promise<Record<string, unknown>>;
+/** Run one api command: its answer as JSON or as the summary, its errors as one line (or one JSON object). */
+export declare function runApiAction(opts: JsonOption, work: () => Promise<{
+    data: unknown;
+    summary: string[];
+}>, io?: ApiCommandIo): Promise<number>;
+/** run --batch: queue every line of the file as one batch, then --wait and --download as for one job. */
+export declare function runBatch(file: string, opts: {
+    idempotencyKey?: string;
+    wait?: boolean;
+    download?: string | boolean;
+}, overrides?: Partial<SummerApiDependencies>): Promise<{
+    data: unknown;
+    summary: string[];
+}>;
+export declare const apiCommand: Command;
+export {};

package/dist/cli/commands/api.js

@@ -0,0 +1,191 @@
+import { readFile } from "node:fs/promises";
+import { Command } from "commander";
+import { API_NOT_OPEN, SummerApiError, cancelJob, createBatch, downloadBatchFiles, downloadJobFiles, estimateJob, getJob, isFinished, listModels, isBatchFinished, parseBatchLines, runJob, waitForBatch, waitForJob, } from "../../core/summer-api.js";
+const defaultIo = () => ({
+    isTTY: process.stdout.isTTY === true,
+    print: (line) => console.log(line),
+    printError: (line) => console.error(line),
+});
+/** A text file as any system writes it: UTF-8 with or without a BOM, or UTF-16 (Windows PowerShell 5's > and Out-File). */
+export async function readTextFile(file) {
+    const bytes = await readFile(file);
+    if (bytes[0] === 0xff && bytes[1] === 0xfe)
+        return bytes.subarray(2).toString("utf16le");
+    return bytes.toString("utf8").replace(/^\uFEFF/, "");
+}
+/**
+ * --input: a JSON object, or "@file" with one. Windows PowerShell 5 strips the
+ * inner quotes of '{"prompt":"..."}' before the CLI sees them, and cmd.exe has
+ * no single quotes, so a file is the dependable way there (quoted: PowerShell
+ * reads a bare @ as splatting).
+ */
+export async function parseInput(text) {
+    if (!text)
+        return {};
+    if (text.startsWith("@")) {
+        try {
+            text = await readTextFile(text.slice(1));
+        }
+        catch {
+            throw new SummerApiError("invalid_input", `Cannot read the input file ${text.slice(1)}.`, 400);
+        }
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new SummerApiError("invalid_input", "--input must be a JSON object, e.g. --input '{\"prompt\":\"a wooden chest\"}', or a file with one: --input \"@input.json\" (in Windows PowerShell and cmd).", 400);
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new SummerApiError("invalid_input", "--input must be a JSON object.", 400);
+    return value;
+}
+/** Run one api command: its answer as JSON or as the summary, its errors as one line (or one JSON object). */
+export async function runApiAction(opts, work, io = defaultIo()) {
+    const json = opts.json === true || !io.isTTY;
+    try {
+        const { data, summary } = await work();
+        if (json)
+            io.print(JSON.stringify(data, null, 2));
+        else
+            for (const line of summary)
+                io.print(line);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof SummerApiError && error.code === "api_not_open") {
+            io.printError(API_NOT_OPEN);
+            return 1;
+        }
+        const code = error instanceof SummerApiError ? error.code : "request_failed";
+        const message = error instanceof Error ? error.message : String(error);
+        // A refused batch's details say how many jobs fit and how much more is needed.
+        const details = error instanceof SummerApiError && error.body?.details && typeof error.body.details === "object" ? error.body.details : undefined;
+        if (json)
+            io.print(JSON.stringify({ ok: false, error: { code, message, ...(details ? { details } : {}) } }));
+        else
+            io.printError(message);
+        return 1;
+    }
+}
+function jobSummary(job, files = []) {
+    const lines = [`Job ${job.id}: ${job.state}${typeof job.price === "string" ? ` (${job.price} USD)` : typeof job.estimatedPrice === "string" ? ` (estimated ${job.estimatedPrice} USD)` : ""}`];
+    const result = (job.result && typeof job.result === "object" ? job.result : {});
+    for (const asset of (Array.isArray(result.assets) ? result.assets : [])) {
+        lines.push(`  ${asset.assetId ?? "asset"}: ${asset.fileUrl ?? ""}`);
+    }
+    for (const file of files)
+        lines.push(`  saved ${file}`);
+    if (!isFinished(job))
+        lines.push(`  Follow it: summer api jobs ${job.id} --wait`);
+    return lines;
+}
+/** --wait and --download for a job that came back: follow it, then save its files. */
+async function finish(job, opts) {
+    const follow = opts.wait === true || opts.download !== undefined;
+    const final = follow && !isFinished(job) ? await waitForJob(job) : job;
+    const dir = typeof opts.download === "string" ? opts.download : ".";
+    const files = opts.download !== undefined && final.state === "done" ? await downloadJobFiles(final, dir) : [];
+    return { data: { job: final, ...(opts.download !== undefined ? { files } : {}) }, summary: jobSummary(final, files) };
+}
+function batchSummary(batch, files = {}) {
+    const counts = Object.entries(batch.counts ?? {}).map(([state, count]) => `${count} ${state}`).join(", ");
+    const lines = [`Batch ${batch.id}: ${batch.jobs.length} jobs${typeof batch.estimatedPrice === "string" ? ` (estimated ${batch.estimatedPrice} USD)` : ""}${counts ? `, ${counts}` : ""}`];
+    for (const job of batch.jobs) {
+        lines.push(`  ${job.id}: ${job.state}${typeof job.model === "string" ? ` ${job.model}` : ""}`);
+        for (const file of files[job.id] ?? [])
+            lines.push(`    saved ${file}`);
+    }
+    if (!isBatchFinished(batch))
+        lines.push(`  Follow a job: summer api jobs <id> --wait`);
+    return lines;
+}
+/** run --batch: queue every line of the file as one batch, then --wait and --download as for one job. */
+export async function runBatch(file, opts, overrides = {}) {
+    let text;
+    try {
+        text = await readTextFile(file);
+    }
+    catch {
+        throw new SummerApiError("invalid_input", `Cannot read the batch file ${file}.`, 400);
+    }
+    const batch = await createBatch(parseBatchLines(text), opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}, overrides);
+    const follow = opts.wait === true || opts.download !== undefined;
+    const final = follow && !isBatchFinished(batch) ? await waitForBatch(batch, {}, overrides) : batch;
+    const files = opts.download !== undefined ? await downloadBatchFiles(final, typeof opts.download === "string" ? opts.download : ".", overrides) : undefined;
+    return { data: { batch: final, ...(files ? { files } : {}) }, summary: batchSummary(final, files) };
+}
+const exit = (code) => {
+    if (code)
+        process.exitCode = code;
+};
+const modelsCommand = new Command("models")
+    .description("The Summer API's curated game-dev models, with input and price; one model with its id (no sign-in needed)")
+    .argument("[model]", "A model id or alias, e.g. 3d/default")
+    .option("--capability <capability>", "Only one kind: image, 3d, video, voice, dialogue, sound or music")
+    .option("--json", "JSON (the default when stdout is not a terminal)")
+    .action(async (model, opts) => exit(await runApiAction(opts, async () => {
+    const data = await listModels({ ...(model ? { model } : {}), ...(opts.capability ? { capability: opts.capability } : {}) });
+    const models = (Array.isArray(data.models) ? data.models : data.model ? [data.model] : []);
+    const price = (entry) => {
+        const p = (entry.price && typeof entry.price === "object" ? entry.price : {});
+        return typeof p.price === "string" ? `${p.price} USD${typeof p.unit === "string" ? ` per ${p.unit}` : ""}` : "";
+    };
+    return { data, summary: models.map((entry) => `${String(entry.id).padEnd(28)} ${String(entry.capability ?? "").padEnd(9)} ${price(entry)}`) };
+})));
+const estimateCommand = new Command("estimate")
+    .description("The exact price of one job before it runs, and a quote id that holds it for 15 minutes; charges nothing")
+    .argument("<model>", "A model id or alias, e.g. 3d/default")
+    .option("--input <json>", "The model's input as a JSON object, or @file.json (summer api models <model> shows its schema)")
+    .option("--json", "JSON (the default when stdout is not a terminal)")
+    .action(async (model, opts) => exit(await runApiAction(opts, async () => {
+    const data = await estimateJob(model, await parseInput(opts.input));
+    return { data, summary: [`${data.model ?? model}: ${data.atMost ? "at most " : ""}${data.price} ${data.currency ?? "USD"}${data.quoteId ? `  quote ${data.quoteId}` : ""}`] };
+})));
+const runSubcommand = new Command("run")
+    .description("Run one job into your Summer assets, or a batch of up to 500 with --batch; spends your paid credits within this app's limit (Connected apps)")
+    .argument("[model]", "A model id or alias, e.g. 3d/default (not with --batch)")
+    .option("--input <json>", "The model's input as a JSON object, or @file.json")
+    .option("--batch <file>", "A JSONL file, one job per line: {\"model\": ..., \"input\": {...}, \"idempotencyKey\": optional}; up to 500, all or none")
+    .option("--quote <quoteId>", "From summer api estimate: refuse to charge more than it quoted")
+    .option("--idempotency-key <key>", "Reuse to retry the same run or batch without running it twice (default: a new one)")
+    .option("--wait", "Follow the job (or every job of the batch) until it finishes")
+    .option("--download [dir]", "Follow it and save its files (default: this folder)")
+    .option("--json", "JSON (the default when stdout is not a terminal)")
+    .action(async (model, opts) => exit(await runApiAction(opts, async () => {
+    if (opts.batch) {
+        if (model || opts.input || opts.quote)
+            throw new SummerApiError("invalid_input", "--batch takes the model and input from each line of its file; leave out <model>, --input and --quote.", 400);
+        return runBatch(opts.batch, opts);
+    }
+    if (!model)
+        throw new SummerApiError("invalid_input", "Name a model (summer api run 3d/default --input '{...}'), or pass --batch file.jsonl.", 400);
+    const follow = opts.wait === true || opts.download !== undefined;
+    const job = await runJob(model, await parseInput(opts.input), {
+        ...(opts.quote ? { quoteId: opts.quote } : {}),
+        ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
+        ...(follow ? { waitSeconds: 60 } : {}),
+    });
+    return finish(job, opts);
+})));
+const jobsCommand = new Command("jobs")
+    .description("Read a job; --wait follows it, --download saves its files")
+    .argument("<jobId>", "The job id summer api run answered")
+    .option("--wait", "Follow the job until it finishes")
+    .option("--download [dir]", "Follow it and save its files (default: this folder)")
+    .option("--cancel", "Ask to stop the job (Summer API jobs, queued or running, run to the end: the answer is unsupported)")
+    .option("--json", "JSON (the default when stdout is not a terminal)")
+    .action(async (jobId, opts) => exit(await runApiAction(opts, async () => {
+    if (opts.cancel) {
+        const job = await cancelJob(jobId);
+        return { data: { job }, summary: jobSummary(job) };
+    }
+    return finish(await getJob(jobId), opts);
+})));
+export const apiCommand = new Command("api")
+    .description("The Summer API: game-dev models, prices, estimates and jobs, with this computer's Summer sign-in (summer login)")
+    .addCommand(modelsCommand)
+    .addCommand(estimateCommand)
+    .addCommand(runSubcommand)
+    .addCommand(jobsCommand);

package/dist/cli/commands/login.d.ts

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import { type CliSessionPollDependencies } from "../../core/cli-session.js";
 export declare const loginCommand: Command;
 /** How long `summer login` waits for the store's Allow click after the account sign-in. */
 export declare const STORE_STEP_TIMEOUT_MS: number;
@@ -27,12 +28,8 @@ export declare function runLoginCommand(opts: {
     store?: boolean;
     force?: boolean;
 }, overrides?: Partial<LoginCommandDependencies>): Promise<void>;
-export interface LoginDependencies {
-    fetch: typeof fetch;
+export interface LoginDependencies extends CliSessionPollDependencies {
     openUrl: (url: string) => Promise<unknown>;
     randomId: () => string;
-    sleep: (ms: number) => Promise<void>;
-    now: () => number;
-    log: (message: string) => void;
 }
 export declare function runLogin(overrides?: Partial<LoginDependencies>): Promise<void>;

package/dist/cli/commands/login.js

@@ -1,21 +1,13 @@
 import { Command } from "commander";
 import { randomUUID } from "crypto";
 import open from "open";
-import { getAuthToken, saveLoginSession, } from "../../core/auth.js";
-import { summerRequestHeaders } from "../../core/agent-host.js";
+import { getAuthToken } from "../../core/auth.js";
+import { cliSessionLoginUrl, pollCliSession } from "../../core/cli-session.js";
 import { resolveGatewayUrl } from "../../core/config.js";
-import { readStoredOAuthToken, runStoreLogin } from "../../core/oauth.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.
-const POLL_TIMEOUT_MS = 900000;
-const HEARTBEAT_MS = 30000;
+import { runStoreLogin, storeSignInWorks } from "../../core/oauth.js";
 export const loginCommand = new Command("login")
-    .description("Sign in to Summer in your browser: your Summer account, then the store, publishing and Grow tools in the same browser")
-    .option("--store", "Only the store sign-in (uploads with store.upload_file, item sync with economy.sync_items, the store, publishing, board and Grow tools); plain summer login does it too")
+    .description("Sign in to Summer in your browser: your Summer account, then the Summer sign-in (OAuth) the Summer API, store, publishing and Grow tools use, in the same browser")
+    .option("--store", "Only the Summer sign-in (OAuth): the Summer API (summer api, summer token), uploads with store.upload_file, item sync, the store, publishing, board and Grow tools; plain summer login does it too")
     .option("--no-store", "Only the Summer account sign-in; skip the store sign-in")
     .option("--force", "Force re-authentication even if already logged in")
     .action(async (opts) => {
@@ -25,7 +17,8 @@ export const loginCommand = new Command("login")
 export const STORE_STEP_TIMEOUT_MS = 3 * 60_000;
 const defaultCommandDependencies = {
     hasAuthToken: async () => Boolean(await getAuthToken()),
-    hasStoreSignIn: async () => Boolean(await readStoredOAuthToken()),
+    // Checked with the sign-in server: a stored token for a revoked app is not a sign-in.
+    hasStoreSignIn: () => storeSignInWorks(),
     login: () => runLogin(),
     storeLogin: ({ newClient, timeoutMs }) => runStoreLogin({ fetch, now: Date.now, openUrl: open, log: console.log, newClient, ...(timeoutMs ? { timeoutMs } : {}) }),
     log: console.log,
@@ -79,9 +72,6 @@ export async function runLoginCommand(opts, overrides = {}) {
         deps.log('Your Summer login is saved. To add the store, publishing and Grow tools later, run "summer login --store".');
     }
 }
-/** The gateway answered with a terminal 4xx — retrying the same URL cannot help. */
-class LoginRejectedError extends Error {
-}
 const defaultDependencies = {
     fetch,
     openUrl: open,
@@ -94,7 +84,7 @@ export async function runLogin(overrides = {}) {
     const deps = { ...defaultDependencies, ...overrides };
     const gatewayUrl = await resolveGatewayUrl();
     const sessionId = deps.randomId();
-    const loginUrl = `${gatewayUrl}/login?cli_session=${encodeURIComponent(sessionId)}`;
+    const loginUrl = cliSessionLoginUrl(gatewayUrl, sessionId);
     deps.log("Sign in at: " + loginUrl);
     deps.log("");
     try {
@@ -105,67 +95,6 @@ export async function runLogin(overrides = {}) {
         deps.log("");
     }
     deps.log("Waiting for authentication...");
-    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.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);
-            deps.log(`\nLogged in as ${completed.user?.email || "unknown"}`);
-            return;
-        }
-    }
-    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.`);
+    const completed = await pollCliSession(gatewayUrl, sessionId, deps);
+    deps.log(`\nLogged in as ${completed.user?.email || "unknown"}`);
 }