summer-engine 4.6.0 → 4.8.0

package/library/skills/summer-api/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: summer-api
+description: "Summer API game assets: models, estimate, one job or a batch, download the files."
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
+category: _meta
+user-invocable: false
+allowed-tools: Bash Read Write summer_api_models summer_api_estimate summer_api_run summer_api_batch summer_api_job
+---
+
+# Summer API: game assets for any agent
+
+The Summer API makes game assets from curated models tested for games: 3D models (GLB), images, video, voice lines, dialogue, sound effects and music. Each finished file is saved to the person's Summer library and downloads into their project. Every model runs at the provider's list price, with no markup on assets.
+
+Use this skill when the person asks for the Summer API, or wants asset files for any engine, app or pipeline from a script, a batch or a coding agent. Inside a running Summer Engine project, the asset skills (`prop-model`, `character-model`, `sound-effect`, ...) import the asset into the scene for you; use them there.
+
+Two ways in, with the same calls and the same answers:
+
+| You have | Use |
+|---|---|
+| A shell | `summer api ...` commands. If `summer --version` is missing or below 4.8, write `npx -y summer-engine@latest` in place of `summer`. |
+| Summer's local MCP server | The tools `summer_api_models`, `summer_api_estimate`, `summer_api_run`, `summer_api_batch` and `summer_api_job` |
+
+Your own code calls the same API over HTTP. The HTTP guide, the OpenAPI document and copy-paste code are on docs.summerengine.com/api (quickstart, jobs, errors).
+
+## 1. Sign in once
+
+```bash
+summer login
+```
+
+The browser opens the Summer sign-in page. The person signs in, picks a spend limit for this app and chooses **Allow**. Tell them the browser opens, and wait for them. The sign-in renews itself; do it once per computer. There are no API keys.
+
+- `summer token` prints a one-hour access token from the same sign-in, for the person's own HTTP code. Keep tokens out of game code, builds and commits.
+- Listing models and estimating need no sign-in. Running a job does.
+- The person sees and changes each app's spend limit, or revokes it, in Settings > Connected apps on summerengine.com.
+
+## 2. Pick a model
+
+```bash
+summer api models --capability 3d
+summer api models 3d/default
+```
+
+MCP: `summer_api_models({ capability: "3d" })`, `summer_api_models({ model: "3d/default" })`.
+
+- Capabilities: `image`, `3d`, `video`, `voice`, `dialogue`, `sound`, `music`.
+- `<capability>/default` (such as `3d/default`) runs the model Summer tests first for that job. A job answer names the model that ran in `model`, so you can run the same model again.
+- Each model lists its `inputSchema` (the exact fields), `outputFormats`, typical time and `price`. Read prices from this list every time, never from memory.
+- Voice and dialogue models list `voices` (`voiceId` and `name`). Use one of those ids.
+
+## 3. Price it, then ask
+
+```bash
+summer api estimate 3d/default --input '{"kind": "text-to-3d", "prompt": "a stylized treasure chest, game prop"}'
+```
+
+MCP: `summer_api_estimate({ model: "3d/default", input: { kind: "text-to-3d", prompt: "a stylized treasure chest, game prop" } })`.
+
+The answer has `price` (US dollars as a decimal string), `atMost` (`true`: the most it can cost, the charge can be lower), a `breakdown`, and a `quoteId` that holds the price for 15 minutes. Estimates are free.
+
+Before you spend: tell the person what you will make, how many, and the total. Wait for a yes. Jobs spend their paid Summer credits (plan credits and top-ups).
+
+## 4. Run one job
+
+```bash
+summer api run 3d/default \
+  --input '{"kind": "text-to-3d", "prompt": "a stylized treasure chest, game prop"}' \
+  --quote <quoteId> --download assets/props
+```
+
+MCP: `summer_api_run({ model: "3d/default", input: { kind: "text-to-3d", prompt: "a stylized treasure chest, game prop" }, quoteId: "<quoteId>", out: "assets/props" })`.
+
+- `--download <dir>` (MCP `out`) follows the job to the end and saves every file as `<assetId>.<ext>`. `--wait` (MCP `wait: true`) follows it without saving.
+- `--quote` (MCP `quoteId`): Summer refuses to charge more than the quote. If the price went up, the job does not start and nothing is charged (`conflict`): estimate again.
+- Images, voice and sound usually finish inside the call. 3D and video take minutes: one MCP call follows a job for about a minute, then answers `next`. Call `summer_api_job({ jobId, wait: true })` until the job finishes. The CLI follows it to the end by itself.
+- In Windows PowerShell or cmd, write the input to a file and pass `--input "@input.json"`: those shells break quotes inside `'{...}'`.
+- Each run sends its own idempotency key, so a retried request never runs twice. To retry the same run by hand, pass the same `--idempotency-key` (MCP `idempotencyKey`).
+
+## 5. Run many: a batch
+
+For a set of assets (props for a level, every UI icon, a sound pack), send one batch instead of many runs. One batch takes up to 500 jobs, all or none.
+
+```jsonl
+{"model": "3d/default", "input": {"kind": "text-to-3d", "prompt": "a wooden barrel with iron bands, game prop"}}
+{"model": "3d/default", "input": {"kind": "text-to-3d", "prompt": "a mossy stone well, game prop"}}
+{"model": "image/default", "input": {"prompt": "a red health potion icon, flat fantasy style, centered", "removeBackground": true}}
+{"model": "sound/default", "input": {"text": "glass potion bottle uncorked, short pop", "durationSeconds": 1}}
+```
+
+```bash
+summer api run --batch jobs.jsonl --download assets
+```
+
+MCP: `summer_api_batch({ jobs: [{ model: "3d/default", input: { kind: "text-to-3d", prompt: "a wooden barrel with iron bands, game prop" } }], out: "assets" })`. Read it again with `summer_api_batch({ batchId: "<id>", wait: true, out: "assets" })`.
+
+- Every job is priced when the batch arrives. When the paid credits and the app's limit cover all of them, all are accepted at once and run in order; each holds its price (`estimatedPrice` on the job, the total on the batch). When they do not, nothing runs: the error's `details` say how many fit (`fits`) and how much more is needed (`shortUsd`).
+- The batch answers its jobs in the order you sent them. Give each job a `title` where the model takes one (3D and image models do): it names the asset in the person's library.
+- A batch takes no `quoteId`. Estimate each distinct request first (same model and input, same price), add them up, and give the person the total for the whole batch.
+- Each line may carry its own `idempotencyKey`; the batch has one too (`--idempotency-key`). To pick up a batch after the terminal closed, run the same command with the same `--idempotency-key`: it answers the batch it already made and follows it. MCP: `summer_api_batch({ batchId, wait: true })`.
+
+## 6. Follow and read
+
+```bash
+summer api jobs <jobId> --download assets   # follow it and save its files
+```
+
+MCP: `summer_api_job({ jobId: "<jobId>", out: "assets" })`.
+
+A Summer API job runs to the end once it is accepted, queued or running: it cannot be cancelled. A job that fails costs nothing. So confirm the list with the person before you send it.
+
+| `state` | Means | Do |
+|---|---|---|
+| `queued` | Waiting for one of the account's running slots; its price is held | Keep following; it starts in order |
+| `running` | Working; `progress` 0 to 100 when known | Keep following |
+| `done` | Finished; `result.assets` has the files | Download them |
+| `failed` | It did not work; nothing is charged | Show `error.message`; change the input or the model |
+| `cancelled`, `expired`, `stale`, `declined` | Stopped without a result | Start a new job if the person still wants it |
+
+A finished job has `result.assets`: one entry per file, each with `assetId`, `fileUrl` and `thumbnailUrl`. The file type is the extension of `fileUrl` (the model's `outputFormats` lists them). Job ids may hold a colon (`gen:...`, `q:...`); send them as they are.
+
+With `--json`, or when its output is piped, every command prints the API's own answer: `{"job": {...}}` for a run or a job (plus `"files"` with `--download`), `{"batch": {...}}` for a batch, the estimate's fields at the top level, and `{"ok": false, "error": {"code", "message", "details"}}` on an error. In a terminal it prints a short summary.
+
+## Limits: money only
+
+- **No rate limits on paid usage.** Send as much work as the person agrees to pay for.
+- **Running slots.** Each account runs 10 jobs at once at the start, and up to 40 as it buys more credits. Jobs past the slots answer `queued` (their id starts with `q:`) and start in order as slots free up. Queued work is not an error; do not resend it.
+- **Two money limits**, both checked before any work starts: the person's paid balance and this app's own spend limit. Queued and running jobs hold their price against both until they are charged.
+- **A failed job costs nothing.** A retry with the same idempotency key never charges twice.
+
+## Errors
+
+Every error has a stable `code` and a `message` written for the person. Branch on the code; show the message.
+
+| Code | Means | Do |
+|---|---|---|
+| `not_signed_in` | No sign-in, the app was revoked, or a `summer token` older than an hour | CLI and MCP: run `summer login`, then retry. Own HTTP code: get a new `summer token` |
+| `no_credits` | The paid balance cannot cover the job or the batch | Show the message: it links where to add credits. Do not retry until the person tops up |
+| `over_limit` | This app's own spend limit is reached | Show the message: the person raises the limit in Connected apps, or waits for it to reset |
+| `invalid_input` | The input does not match the model, or the `quoteId` expired | Fix the field the message names (`param`); read the model's `inputSchema`. An expired quote: estimate again |
+| `not_found` | No such model, job or batch | Model ids come from `summer api models` |
+| `conflict` | The price went up since your quote | Estimate again; nothing was charged |
+| `idempotency_conflict` | The key was used for a different request | Use a new key for a new job |
+| `in_progress` | The first request with this key is still running | Send the same request again shortly |
+| `outcome_unknown` | Summer could not tell if the work started | Send the same request with the same key; never start a new job |
+| `unavailable` | A model or service is down for a moment | Retry with backoff, or pick another model for the same job |
+| `unsupported` | The job cannot do that (a cancel) | Let the job finish |
+
+`no_credits` and `over_limit` are answers about money, not failures: stop, show the person the message and its link, and continue when they say so.
+
+## Prompts that work, per asset type
+
+Write prompts as plain descriptions of the thing itself. Put the style in every prompt of a set, word for word, so the assets match.
+
+| Asset | Model | Input that works |
+|---|---|---|
+| Prop | `3d/default` | `{"kind": "text-to-3d", "prompt": "a wooden treasure chest with iron trim, stylized low-poly, game prop"}`. One object per job. Add `"targetPolycount": 3000` for a light mesh. |
+| Character | `3d/default` | `{"kind": "text-to-3d", "assetIntent": "character", "poseMode": "a-pose", "rig": true, "animationNames": ["Idle", "Walk", "Run"], "prompt": "a dwarf blacksmith, full body, stylized"}`. Full body, one character, neutral pose. |
+| 3D from concept art | `3d/default` | `{"kind": "image-to-3d", "imageUrl": "<public URL>"}`. A clean picture of one object on a plain background. |
+| Concept art, key art | `image/default` | `{"prompt": "...", "aspectRatio": "16:9"}`. Name the subject, the setting, the light and the style. |
+| Icon, sprite, item | `image/default` | `{"prompt": "a red health potion, centered, flat fantasy style", "removeBackground": true}`. One object, centered; a transparent PNG comes back. |
+| Matching set | `image/default` | Send the first image's `fileUrl` as `referenceImageUrl` in the next jobs, and keep the same `seed` and style words. |
+| Sound effect | `sound/default` | `{"text": "heavy wooden door creaks open, stone hall echo", "durationSeconds": 2}`. Source, action, material, space. `"loop": true` for ambience. |
+| Voice line | `voice/default` | `{"text": "Halt! Who goes there?", "voiceId": "<from the model's voices>"}`. Punctuation sets the delivery. |
+| Conversation | `dialogue/default` | `{"inputs": [{"text": "...", "voiceId": "..."}, {"text": "...", "voiceId": "..."}]}`. One entry per line, up to 40. |
+| Music | `music/default` | `{"prompt": "calm medieval village theme, lute and flute, 90 bpm, loopable", "durationSeconds": 60}`. Genre, mood, instruments, tempo. |
+| Video | `video/default` | `{"prompt": "slow camera push toward a castle at dawn", "duration": 5}`, or `imageUrl` to animate key art. One shot per job. |
+
+A picture input (`imageUrl`, `referenceImageUrl`) is a public URL, such as the `fileUrl` of an earlier job. For a file on the person's computer, the docs' jobs page shows the upload (`/v1/files`).
+
+## Without Summer Engine
+
+This whole skill runs without Summer Engine: the CLI, the MCP tools and the HTTP API need only the Summer sign-in. The files work in any engine or app. Stop at the files; skip any step that imports into a Summer project.
+
+## Use the files
+
+- Save files inside the project (`--download assets/...`), and keep each `assetId`: in Summer Engine, an asset imports by its id.
+- GLB files are Y up and not at real-world size. Scale them in the engine (a door about 2 m, a person about 1.7 m).
+- Assets made through the API are private to the person's Summer library. A `fileUrl` downloads without a sign-in, so share it only where the file may be seen.
+
+## Pitfalls
+
+| Pitfall | Do this instead |
+|---|---|
+| Typing a price from memory | Read `summer api models`, then `summer api estimate` |
+| Spending before the person agreed | Estimate, say the total, wait for a yes |
+| Many single runs for a set of assets | One batch: all or none, priced up front |
+| Resending a job that answered `queued` | It is accepted and its price is held. Follow it. |
+| Treating `no_credits` or `over_limit` as a bug to retry | Show the message and its link; wait for the person |
+| A new idempotency key on a retry after a timeout | The same key: it returns the first job, never a second charge |
+| A token or a sign-in in game code | Only the developer's tools sign in. A shipped game uses Summer Router (the `summer-router` skill). |
+| Several objects in one 3D prompt | One object per job; place them in the engine |
+
+## Done means
+
+- Every job you started is `done`, or you told the person which failed and why.
+- The files are in the folder the person asked for, and you told them the paths and formats.
+- You told the person what it cost (`price` on each job, or the batch's `estimatedPrice`).

package/library/skills/summer-api/resource.yaml

@@ -0,0 +1,38 @@
+id: skill/summer-api
+kind: skill
+version: 1.0.0
+summary: "Summer API game assets: models, estimate, one job or a batch, download the files."
+use_when:
+  - generating asset files (3D models, images, sounds, voice, music, video) from a script, a pipeline or a coding agent outside Summer Engine
+  - making a set of assets in one go (a level's props, every UI icon, a sound pack) as one batch
+  - choosing a generation model, pricing a job before it runs, or reading a job's state and files
+  - a generation job answered no_credits, over_limit, not_signed_in or queued
+do_not_use_when:
+  - generating inside a running Summer Engine project, where the asset skills import into the scene (asset-strategy)
+  - AI that a shipped game calls while people play (summer-router)
+facets:
+  lifecycle:
+    - build
+  domains:
+    - assets
+    - agent-workflow
+  modalities:
+    - 3d-models
+    - images
+    - audio
+    - video
+related:
+  tools:
+    - tool/api-models
+    - tool/api-estimate
+    - tool/api-run
+    - tool/api-batch
+    - tool/api-job
+  skills:
+    - skill/summer-assets
+    - skill/summer-cli
+    - skill/asset-strategy
+    - skill/summer-router
+source: official
+license: MIT
+status: preview

package/library/skills/summer-assets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: summer-assets
-description: "Make game assets with Summer, no Summer Engine: find, generate and download 3D models, images, audio and video for any engine or app."
+description: "Game assets for any engine, no Summer Engine: find, generate and download them."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
 category: _meta

package/library/skills/summer-assets/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/summer-assets
 kind: skill
-version: 1.0.1
-summary: "Make game assets with Summer, no Summer Engine: find, generate and download 3D models, images, audio and video for any engine or app."
+version: 1.0.2
+summary: "Game assets for any engine, no Summer Engine: find, generate and download them."
 use_when:
   - starting a session that has the Summer assets profile (generation tools, no engine tools)
   - the person wants assets for their own engine or web app, not a game built in Summer Engine
@@ -26,6 +26,7 @@ related:
     - tool/get-asset-download-url
   skills:
     - skill/asset-strategy
+    - skill/summer-api
     - skill/sound-effect
     - skill/prop-model
     - skill/concept-art

package/library/skills/summer-router/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: summer-router
+description: "AI characters for games on Summer Games: Summer Router replies, tools, speech, images."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: ai-and-npcs
+user-invocable: true
+allowed-tools: Read Grep Edit Write summer_get_scene_tree summer_add_node summer_set_prop summer_connect_signal summer_save_scene summer_get_script_errors
+paths: ["**/*.gd", "**/*.tscn"]
+---
+
+# Summer Router: AI characters in your game
+
+A shopkeeper who haggles, a guard who opens the gate when convinced, a narrator who says the player's name. With **Summer Router**, a game calls AI while people play. The game names a character and sends what the player said. Summer holds the instructions, the model, the voice, the caps and the provider keys, and meters each call from the creator's paid Summer credits. Players never pay, and nothing secret is in the build.
+
+## What works today (early preview)
+
+| | Status |
+|---|---|
+| Where | Games **published on Summer Games**, played in the Summer app (desktop, phone) or on summer.games, by a signed-in player. Other platforms and storefronts answer `not_on_summer_games`; they are coming soon. |
+| Engine | Summer Engine 0.8 or later: `Summer.client.router`, `Summer.authority.router` and the `SummerRouterCharacter` node |
+| Character replies | Available: text replies that keep the conversation and call your game's tools (`reply`) |
+| Speech | Available: a whole clip in the character's voice (`speak`) |
+| Images | Available: one image from a prompt and an optional reference picture (`generate("image", ...)`) |
+| Transcription | Coming soon: `transcribe` answers `unavailable`. Keep typed input. |
+| Realtime voice | Coming soon: a `talk` session in `"voice"` mode talks in text turns and still speaks the replies |
+
+In the editor and in Local Play, every call answers `unavailable`, so the game uses its offline lines. Test the character with the test conversation (step 2) and play the real thing on Summer Games.
+
+## 1. Plan: who calls
+
+Ask the person one question if it is not clear: is the game single-player or multiplayer?
+
+| Game | Who calls | Counts toward |
+|---|---|---|
+| Single-player | The player's game: `Summer.client.router` | The player's caps and the game's caps |
+| Multiplayer | The game server (the authority): `Summer.authority.router`, for one player's `SummerSession` | The game's caps and call rate |
+
+In a multiplayer game, the server owns the world. Anything a character does that changes the game (sell an item, give gold, open a shared door) runs on the server. A player's game may also talk to a character itself and tell the server what happened; then the server checks the exchange with `verify_exchange` before it acts (step 4).
+
+## 2. Make the character
+
+A character lives on Summer, not in the build. Make it in Summer Studio (the game's **Grow > Summer Router** tab), or with the Summer MCP:
+
+```text
+router.save_character({
+  gameId: "<from games.list>",
+  character: {
+    id: "shopkeeper",
+    name: "Mira the shopkeeper",
+    instructions: "You run the potion shop in Emberfall. Warm, a little greedy, never rude. You sell only what is in stock: {{stock}}. When the player agrees on a potion and its price, call sell_item. You never give items for free.",
+    first_message: "Welcome, traveller! Potions, tonics, a little luck in a bottle?",
+    variables: { stock: "health potion 25 gold, mana potion 30 gold" },
+    overridable: ["variables"],
+    tools: [{
+      name: "sell_item",
+      description: "Sell one item to the player once they agree on it and its price.",
+      parameters: { type: "object", properties: { item: { type: "string" }, price: { type: "integer" } }, required: ["item", "price"] }
+    }]
+  }
+})
+```
+
+- Over MCP, call it with `summer_call({ op: "router.save_character", input: {...} })`, or from a shell: `summer router save-character --input '<json>'`. Find the game id with `games.list`. On a game that is live, the person approves the change with one link.
+- Test it before you write game code: `router.test_character({ gameId, characterId: "shopkeeper", messages: ["Do you have anything for my wounds?", "Fine, 25 gold for the health potion."], toolOutputs: { sell_item: { ok: true } }, expectTools: ["sell_item"] })`. Test turns count toward a developer cap of their own.
+- `router.models` lists the text models, voices and the full character schema (`include: ["schema"]`). Pick `model` and `voice.id` from it, or leave them out for the game's defaults.
+- The tool `name` in the character is the name your game handles. Tool arguments come from the model: check every one in game code.
+
+The character, field by field:
+
+| Field | What it does |
+|---|---|
+| `id` | What the game calls it by: lowercase letters, digits, `_` or `-`, up to 64 |
+| `name`, `first_message`, `language` | Display name, its opening line, a language such as `en` or `pt-BR` |
+| `instructions` | Who it is and how it talks, up to 20,000 characters. `{{name}}` placeholders must be declared in `variables` |
+| `variables` | Declared placeholders and their defaults. A build may send new values only when `overridable` lists `"variables"` |
+| `overridable` | Fields a build may change per call, such as `"variables"` or `"first_message"`. `context` needs no entry: a build may always send it |
+| `model`, `temperature`, `max_output_tokens`, `reasoning` | The text model (from `router.models`) and how it answers; leave out for the game's default |
+| `voice` | `{"id": "<from router.models voices>"}` for `speak` |
+| `tools` | Up to 32: `name`, `description`, `parameters` (a JSON Schema object) |
+| `limits` | This character's own daily caps: `player_daily_micro_usd`, `game_daily_micro_usd` (1,000,000 = 1 US dollar) |
+
+## 3. Single-player: call from the player's game
+
+```gdscript
+var conversation_id := ""
+
+func ask_shopkeeper(line: String) -> void:
+	var r: SummerRouterResult = await Summer.client.router.reply("shopkeeper", line, {
+		"conversation_id": conversation_id,
+		"variables": {"stock": Shop.stock_line()},
+		"context": "The player has %d gold." % Player.gold,
+		"tools": {"sell_item": func(args: Dictionary): return Shop.sell(str(args.get("item", "")), int(args.get("price", 0)))},
+	})
+	if r.ok:
+		conversation_id = r.conversation_id
+		$Bubble.show_line(r.text, r.exchange_id)   # label it as AI; offer a report button
+	else:
+		$Bubble.show_line(OfflineLines.shopkeeper(line), "")
+```
+
+- `tools` maps each tool name to a `Callable`. The SDK runs the handler, sends what it returns back to the character, and the character goes on, up to 8 rounds in one call. Return `{"error": "..."}` when the action fails (not enough gold, out of stock); the character then says so.
+- `Shop.sell` checks the price against your own price list, the stock and the gold. The model's word is never the price.
+- `conversation_id`: Summer keeps the history. Send the one the last result named. Without it, each call starts a new conversation.
+- For a whole conversation in one node, add a `SummerRouterCharacter`, set **Character ID**, turn on **Show UI**, and give it `tools`. It shows a bar with the character's words and a text field.
+
+Speech and images from the player's game:
+
+```gdscript
+var line: SummerRouterResult = await Summer.client.router.speak("", {"exchange_id": r.exchange_id})  # voice that reply
+if line.ok:
+	$Voice.stream = line.audio
+	$Voice.play()
+
+var art: SummerRouterResult = await Summer.client.router.generate("image", {"prompt": "a shop sign shaped like a potion", "size": "1024x1024"})
+if art.ok:
+	$Sign.texture = art.texture
+```
+
+Voice only when the character has one (the `has_voice` of each entry in `status().characters`), and consider voicing on tap: speech costs more than text.
+
+`await Summer.client.router.status()` asks Summer what this player can use now: `available` (and `reason`, an error tag, when it is not), `characters` (each `id`, `name`, `has_voice`, `client_tools`), `kinds` (the capabilities Summer serves) and `voice` (realtime voice, `false` during the early preview). `report(exchange_id, reason)` answers `report_id` and `status`; it takes one of this player's replies from the last 30 days.
+
+## 4. Multiplayer: call from the server
+
+The player's game sends what the player typed to the server as a Command (the `multiplayer-state` skill sets up Commands and shared State). The server answers the Command at once, asks the character for that player's session, runs the tool calls itself, and publishes the line in shared State so every player sees it.
+
+```gdscript
+# Server (authority). Call from your Command handler for {"c": "talk", "text": ...}.
+const MAX_ROUNDS := 3
+
+func _talk(request: SummerNetworkCommandRequest, text: String) -> void:
+	var session := request.get_session()
+	request.accept({}, Game.pack({"asked": true}))   # the reply arrives in shared State
+	var conversation := "shop_" + session.session_id.md5_text()
+	var options := {"conversation_id": conversation, "variables": {"stock": Shop.stock_line()}}
+	var r: SummerRouterResult = await Summer.authority.router.reply(session, "shopkeeper", text.strip_edges().left(4000), options)
+	for _round in MAX_ROUNDS:
+		if not r.ok or r.tool_calls.is_empty():
+			break
+		var results := []
+		for call in r.tool_calls:
+			var output: Variant = {"error": "unknown tool"}
+			if call.name == "sell_item":
+				output = Shop.sell_to(session, str(call.args.get("item", "")))   # checks stock, price and wallet
+			results.append({"call_id": call.call_id, "output": output})
+		r = await Summer.authority.router.reply(session, "shopkeeper", "", {"conversation_id": conversation, "tool_results": results})
+	var line := r.text if r.ok else r.message   # r.message is a plain line for players
+	if line.is_empty():
+		line = OfflineLines.shopkeeper(text)
+	shop_doc.lines.append({"by": session.player.display_name, "text": line})
+	shop_group.reset(Game.pack(shop_doc))
+```
+
+- The server has `reply(session, character, text, options)`, `speak(session, text, {"character": id})` and `generate(session, "image", {...})`. Options are the client's without `tools`: the server reads `r.tool_calls` and answers them with `tool_results` on the next call, with the same `conversation_id`.
+- `speak` and `generate` on the server return `data` and `mime_type`. Audio and images are too big for shared State: to voice a line, each player's game calls `Summer.client.router.speak(line, {"character": "shopkeeper"})` for the line it shows (it counts toward that player's caps).
+- Server calls count toward the game's caps, not the player's. Keep your own pace per player on the server: one line in flight per player, a short gap between lines, and a length cap on the text, so one player cannot spend the whole game's daily cap.
+- `Shop.sell_to` on the server is the only place an item or gold changes hands. Never apply an effect a client reports.
+
+**A client talked, the server acts.** When the player's game called `Summer.client.router` itself and tells the server "the shopkeeper agreed to sell", the server checks the exchange first:
+
+```gdscript
+var check: SummerRouterResult = await Summer.authority.router.verify_exchange(session, exchange_id)
+if check.ok and check.tool_calls.any(func(call): return call.name == "sell_item"):
+	Shop.sell_to(session, str(check.tool_calls[0].args.get("item", "")))
+# Anything else (another player's exchange, older than an hour, made up): do nothing.
+```
+
+## 5. Every refusal keeps the game running
+
+Every call returns a `SummerRouterResult`. Read `ok` first. On a refusal, `error` is a stable tag, `fix` says what to do (for you), and `message` is a plain line you may show players. Show `message` or your own offline line, and go on. Treat a tag you do not know as `unavailable`.
+
+| Tag | Means | Game does |
+|---|---|---|
+| `unavailable` | No Summer app, an old app, the editor or Local Play, or the service is down (`reason` says which) | Offline line |
+| `not_signed_in` | The player is not signed in | Offline line |
+| `not_on_summer_games` | The game is not running from Summer Games | Offline line; publish on Summer Games |
+| `router_disabled` | The creator turned Summer Router off for the game | Offline lines until the game restarts |
+| `credits_required` | The creator's paid credits ran out | Offline lines until the game restarts |
+| `limit_reached` | A cap has no room: `scope` (such as `player_day`, `game_day`, `game_month`), `resets_at` (Unix seconds) | Offline lines until `resets_at` |
+| `rate_limited` | Too many calls a minute (`retry_after` seconds) | Offline line; wait before the next call |
+| `age_restricted` | This player may not talk to this character | Offline lines for this player |
+| `moderated` | The safety filter blocked this turn | Offline line |
+| `provider_unavailable` | The model is down for a moment | Offline line; the next call may work |
+| `character_not_found` | No character with this id | Bug: fix the id, or save the character |
+| `invalid_input` | The call breaks a limit (text 1 to 4000 characters, at most 32 variables), or sends `variables` the character does not let a build set | Bug: fix the call or the character |
+| `tool_unhandled` | The character called a tool the game has no handler for | Add the handler to `tools` |
+
+`retryable` is `true` when the same call can work later (`unavailable`, `limit_reached`, `provider_unavailable`, `rate_limited`). Never retry in a loop: a cap is the product working.
+
+## 6. Caps and money
+
+Every game starts on, with caps on from day one:
+
+| Cap | Default |
+|---|---|
+| Spend per player per day | 5 US dollars |
+| Spend per game per day | 100 US dollars |
+| Spend per game per month | 1,000 US dollars |
+| Spend per account per month, all games | 2,000 US dollars |
+| Calls a minute per player | 30 |
+| Calls a minute per game | 1,200 |
+
+- The creator changes them per game in Grow > Summer Router, or an agent asks with `router.set_settings` (the person approves with one link). `router.set_account_limit` changes the account cap. `router.usage` shows calls, units, how much of each cap is used and which calls a cap stopped.
+- A character can carry its own daily caps per player and per game (`limits` in the character).
+- Calls are paid from the creator's paid Summer credits (plan credits and top-ups), the same balance as the Summer API. A result never carries a price.
+
+## 7. Ship it safely
+
+- No provider key, provider SDK, model id or character instructions in the project. The build holds character ids only.
+- Every character keeps an offline line set that is good on its own. Most refusals happen in normal play.
+- Label AI lines as AI in the game (a small tag on the bubble), and offer a report button: `Summer.client.router.report(exchange_id, "inappropriate")`.
+- Never ask players for personal details, and keep characters off romance, self-harm and medical advice. Write it into the instructions.
+- In a multiplayer game, a reply never changes shared state on a client. The server applies every effect and checks every tool argument.
+- `Summer.client.router.is_available()` says, without a network call, whether this run can call Summer Router. `status()` asks Summer which characters and kinds it serves for this player.
+
+## Verify
+
+- `grep` the project for provider names, model ids and anything key-shaped: none.
+- In the editor every character answers with its offline line, and no error is shown.
+- `router.test_character` with `expectTools` passes for each tool the game handles.
+- Every tool handler refuses bad arguments (an unknown item, a wrong price, not enough gold).
+- In multiplayer, the server is the only code that sells, gives or opens anything, and it checks a relayed exchange with `verify_exchange`.
+- On Summer Games, signed in, the character answers, its tool works, and `router.usage` shows the calls.
+
+## Common mistakes
+
+| Mistake | Do this instead |
+|---|---|
+| Calling a provider from the game "until Summer Router is on" | Summer Router only; offline lines meanwhile |
+| Sending the character's instructions from the build | Save them on Summer; the build sends `variables` and `context` |
+| Trusting the price or item a tool call names | Check them against your own list on the game's side |
+| Retrying on `limit_reached` or `credits_required` | Offline lines until the cap resets or the creator acts |
+| Waiting for transcription before shipping | Ship typed input now; transcription is coming soon |
+| Testing only in the editor | The editor answers `unavailable`; use the test conversation, then Summer Games |
+
+<!-- shell-commands: generated from the operation catalog by npm run generate:registry; do not edit by hand -->
+## From a shell
+
+No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.
+
+| In this skill | Command |
+|---|---|
+| `summer_add_node` | `summer engine add-node` |
+| `summer_connect_signal` | `summer engine connect-signal` |
+| `summer_get_scene_tree` | `summer engine get-scene-tree` |
+| `summer_get_script_errors` | `summer engine get-script-errors` |
+| `summer_save_scene` | `summer engine save-scene` |
+| `summer_set_prop` | `summer engine set-prop` |
+| `games.list` | `summer games list` |
+<!-- /shell-commands -->

package/library/skills/summer-router/resource.yaml

@@ -0,0 +1,35 @@
+id: skill/summer-router
+kind: skill
+version: 1.0.0
+summary: "AI characters for games on Summer Games: Summer Router replies, tools, speech, images."
+use_when:
+  - a talking NPC (shopkeeper, guard, companion) players chat with, in a single-player or multiplayer game on Summer Games
+  - a game should speak a line in a character's voice, or make an image, while people play
+  - about to put a model name, a provider SDK or a provider key into a game project
+  - choosing between Summer.client.router and Summer.authority.router in a single-player or multiplayer game
+  - handling Summer Router refusals (limit_reached, credits_required, router_disabled, not_on_summer_games, unavailable) or changing its caps
+do_not_use_when:
+  - scripted dialogue trees or enemy behaviour (design-npc)
+  - making asset files while building the game (summer-api)
+facets:
+  lifecycle:
+    - build
+  domains:
+    - ai
+    - npc
+    - multiplayer
+  modalities:
+    - scripts
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/design-npc
+    - skill/multiplayer-state
+    - skill/summer-api
+source: official
+license: MIT
+status: preview
+aliases:
+  - skill/ai-characters-in-games

package/library/tools/api-batch/resource.yaml

@@ -0,0 +1,82 @@
+id: tool/api-batch
+kind: tool
+version: 1.0.0
+summary: Run up to 500 Summer API jobs at once, all or none, with the Summer sign-in; follow every job and save the files.
+use_when:
+  - making many game assets through the Summer API in one go (a set of props, sounds or icons)
+  - following or downloading a batch that summer_api_batch started
+do_not_use_when:
+  - one job (summer_api_run)
+  - the person has not agreed to spend credits
+facets:
+  lifecycle:
+    - build
+  domains:
+    - generate
+    - assets
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_api_batch
+implementation:
+  module: src/mcp/tools/api-tools.ts
+  export: registerApiTools
+surfaces:
+  mcp:
+    tool_name: summer_api_batch
+    remote: true
+input_schema:
+  type: object
+  properties:
+    jobs:
+      type: array
+      minItems: 1
+      maxItems: 500
+      items:
+        type: object
+        properties:
+          model:
+            type: string
+            minLength: 1
+            maxLength: 120
+            description: A Summer API model id or alias from summer_api_models, e.g. 3d/default.
+          input:
+            type: object
+            additionalProperties: {}
+            description: The model's input, matching its inputSchema from summer_api_models.
+          idempotencyKey:
+            type: string
+            minLength: 1
+            maxLength: 200
+            description: "This job's own key; by default the batch key and the job's position."
+        required:
+          - model
+        additionalProperties: false
+      description: Up to 500 jobs, all or none. Leave out with batchId.
+    batchId:
+      type: string
+      minLength: 1
+      maxLength: 200
+      description: Read a batch summer_api_batch answered, instead of starting one.
+    idempotencyKey:
+      type: string
+      minLength: 1
+      maxLength: 200
+      description: Reuse to retry the same batch without queuing it twice.
+    wait:
+      type: boolean
+      description: Follow every job until it finishes (up to about a minute in this call).
+    out:
+      type: string
+      minLength: 1
+      description: "A folder on this computer: save the finished job's files there (implies wait)."
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: true
+  credentials: true
+  publish: false