@womp/spark-agent 5.12.1 → 6.0.1

package/CHANGELOG.md

@@ -0,0 +1,221 @@
+# Changelog
+
+Notable changes to `@womp/spark-agent`, newest first. Versions follow
+[Semantic Versioning](https://semver.org/). Add an entry with each version bump; describe what
+changed for hosts and users, and how to migrate across breaking changes.
+
+## 6.0.1 — 2026-10-07
+
+### Fixed
+
+- Tool results reach the model with sorted keys, and `convertSparkMessages` replays stored tool
+  inputs as their schema validates them. History that a host reads back from storage that reorders
+  keys (Swan's Postgres JSONB thread rows) now matches what the live run sent, so turn starts in
+  Swan and Crow keep the provider prompt cache. Hosts need no change beyond the upgrade.
+
+## 6.0.0 — 2026-10-07
+
+### Breaking
+
+- Removed `SparkAgentOptions.context`, the `createHost` `context` result, and `wompifyContext`.
+  Hosts send `sparkSystemPrompt(skills)`, which stays identical across a conversation so provider
+  prompt caches hit.
+- `wompifyPrompt` takes a single request object including `referenceNamePrefix`.
+
+### Added
+
+- `data-selection` user message part (`{ nodeIds }`) for the editor selection sent with a message.
+
+### Migrating to 6.0
+
+- Stop passing per-run state in `context`. Attach the editor selection to the user message as a
+  `data-selection` part; send other changing state in messages.
+- Replace `wompifyContext(...)` and positional `wompifyPrompt(...)` calls with
+  `wompifyPrompt({ referenceName, referenceNamePrefix, preset, note })`.
+
+## 5.12.1 — 2026-10-07
+
+### Fixed
+
+- Goal state, rules and evaluator feedback are sent as appended messages instead of changing the
+  system prompt, so goal turns keep the prompt cache.
+
+## 5.12.0 — 2026-10-07
+
+### Added
+
+- Goal endpoint `update_budget` command edits a goal's credit cap without restarting the run.
+- Wompify detail levels Simple, High res and Ultra res.
+
+### Changed
+
+- A Wompify pass completes when it reaches its credit cap instead of failing the run, and can keep
+  refining in the same conversation with a new budget.
+- Goal credit budgets are no longer included in continuation prompts.
+
+## 5.11.1 — 2026-10-06
+
+### Fixed
+
+- Removed goal token budgets that were reintroduced in 5.11.0.
+
+## 5.11.0 — 2026-10-06
+
+### Added
+
+- Scene API support for patterned lights, light collimation, texture imports and physical depth
+  of field.
+
+## 5.10.0 — 2026-10-05
+
+### Changed
+
+- Ambiguous creative requests get an image preview before building again; turning an image into
+  3D uses mesh generation.
+
+## 5.9.1 — 2026-10-05
+
+### Fixed
+
+- Goal turns report the credits they actually used and no longer estimate costs.
+
+## 5.9.0 — 2026-10-05
+
+### Changed
+
+- Context trimming can also shorten the earlier steps of a long current turn.
+
+## 5.8.0 — 2026-10-04
+
+### Changed
+
+- Goal budgets are enforced with host-reported charged credits; goal token budgets were removed.
+
+### Fixed
+
+- Scene access results omit undefined properties.
+
+## 5.7.1 — 2026-10-03
+
+### Fixed
+
+- `read_skill` takes names-only requests and accepts combined skill name inputs.
+
+## 5.7.0 — 2026-10-02
+
+### Added
+
+- Persistent server goals with `set`, `pause`, `resume` and `clear` controls.
+
+## 5.6.1 — 2026-10-03
+
+Published from a maintenance branch before 5.7.1.
+
+### Fixed
+
+- `read_skill` uses names-only requests.
+
+## 5.6.0 — 2026-10-02
+
+### Fixed
+
+- Skill tool input uses an object-root schema for provider compatibility.
+
+## 5.5.0 — 2026-10-01
+
+### Added
+
+- Mesh Wompify: the shared `mesh-wompify` skill and Wompify request helpers in
+  `@womp/spark-agent/ui`.
+
+## 5.4.0 — 2026-09-30
+
+### Changed
+
+- Requires Kakapo SDK 0.7.3.
+
+### Fixed
+
+- Missing procedural material node locations.
+
+## 5.3.0 — 2026-09-29
+
+### Added
+
+- Procedural material authoring capability.
+- GPT-6.1 Sol model.
+
+### Changed
+
+- Required skills load in one `read_skill` call.
+
+## 5.2.3 — 2026-09-29
+
+### Added
+
+- Shared SDK scene adapters can omit `operations` to edit and save directly, without a recovery
+  journal.
+
+## 5.2.2 — 2026-09-28
+
+### Fixed
+
+- Requires Kakapo SDK 0.7.2; curve density 0 is allowed again.
+
+## 5.2.1 — 2026-09-28
+
+### Fixed
+
+- Requires Kakapo SDK 0.7.1, so stored out-of-range values no longer block unrelated reads and edits.
+
+## 5.2.0 — 2026-09-28
+
+### Changed
+
+- A generation that ends on `length`, `content-filter`, `error` or `other` fails the run with the
+  unified and provider finish reasons in its error and diagnostics.
+
+## 5.1.0 — 2026-09-26
+
+### Added
+
+- Each model step is trimmed to fit the model's context window.
+
+## 5.0.2 — 2026-09-25
+
+### Fixed
+
+- Restored screenshot framing guidance.
+
+## 5.0.1 — 2026-09-25
+
+### Fixed
+
+- Restored screenshot camera controls.
+
+## 5.0.0 — 2026-09-25
+
+### Breaking
+
+- Scene capability `read`/`edit` replaced by `access(callback)`; custom scene hosts implement
+  `SceneHost.access` and SDK adapters `acquireAccess`.
+- Requires Kakapo SDK 0.7.0.
+
+### Migrating to 5.0
+
+- Replace scene capability `read`/`edit` with `access(callback)`. Inspect the current draft
+  through `scene.nodes({ ids, name, type, parentId, offset, limit })`, not a `nodes` array.
+  Results default to 100, with a maximum page size of 1,000.
+- Update custom scene hosts to `SceneHost.access` and SDK adapters to `acquireAccess`.
+  `onCommitted` receives the acknowledged scene; keep host access suspended until synchronization
+  succeeds.
+- Remove scene revision arguments from Geometry/OpenSCAD writes.
+- Screenshot calls without options capture the current native viewport. Explicit `camera`
+  position/target, projection, `horizontalFovDegrees` and `orthographicWidth` are supported;
+  remove `targetId` and `view` presets. Camera distances use current project units.
+- Request scene health explicitly through `scene.health()`; it no longer runs after each edit.
+- Native and QuickJS executors allow 100,000 host calls per execution.
+
+## Earlier versions
+
+Changes before 5.0.0 are recorded in the Git history.

package/README.md

@@ -6,25 +6,9 @@ Spark Agent uses AI SDK 7 `UIMessage` and `UIMessageChunk` as its public chat pr
 JavaScript uses the host's executor and capabilities. Native browser execution and isolated QuickJS
 execution use the same model loop. The host owns conversations, artifacts, authorization, and connections.
 
-## Requirements
-
-### Migrating to 5.0
+Release notes and migration guides are in [CHANGELOG.md](CHANGELOG.md).
 
-- Replace scene capability `read`/`edit` with `access(callback)`. Inspect the current draft
-  through `scene.nodes({ ids, name, type, parentId, offset, limit })`, not a `nodes` array.
-  Results default to 100, with a maximum page size of 1,000.
-- Update custom scene hosts to `SceneHost.access` and SDK adapters to `acquireAccess`.
-  `onCommitted` receives the acknowledged scene; keep host access suspended until synchronization succeeds.
-- Remove scene revision arguments from Geometry/OpenSCAD writes. Current parameters and overrides
-  are prepared inside protected access. Hosts must still enforce connection/project ownership.
-- Screenshot calls without options capture the current native viewport. Explicit `camera`
-  position/target, projection, `horizontalFovDegrees` and `orthographicWidth` are supported;
-  remove `targetId` and `view` presets. Camera distances use current project units.
-- Scene health is explicitly requested through `scene.health()`, not automatically after each edit.
-- This release requires Kakapo SDK 0.7.0. Native and QuickJS executors now allow 100,000 host calls
-  per execution. Receipts, cancellation, timeout limits and uncertain-outcome handling remain enforced.
-
-### Runtime
+## Requirements
 
 - Node.js 22.13 or newer
 - AI SDK 7
@@ -34,67 +18,6 @@ execution use the same model loop. The host owns conversations, artifacts, autho
 npm install @womp/spark-agent
 ```
 
-## Run a prompt from the command line
-
-With the Spark server already running:
-
-```sh
-yarn agent-run --prompt "Make a cube" --model gpt-5.6-luna --reasoning max
-```
-
-Use `--conversation <id>` to continue a thread and `--output <new-directory>` to save
-`result.json`, `transcript.json` and original run artifacts under `artifacts/`.
-For local runs, use the git-ignored `.spark/` directory, with a fresh subdirectory per run:
-
-```sh
-yarn agent-run --prompt "Make rainbow-colored boxes" --output .spark/agent-runs/rainbow-boxes
-yarn agent-run --prompt "Model this object using both views" --image front.png --image side.jpg --output .spark/agent-runs/reference-model
-```
-
-Repeat `--image <path>` for local PNG, JPEG, WebP or GIF references, in argument order.
-The required prompt and all images are sent in one user message. Files, format signatures,
-and the full JSON request size (including base64 overhead) are checked before contacting the server.
-The CLI uses the server's default 25 MiB request limit; a custom server or provider may impose
-stricter limits. Images are never resized, and remote URLs are not accepted.
-With `--output`, original bytes are saved under `inputs/`; `input.json` and the result's `input`
-field list ordered original filenames, MIME types and relative paths. The submitted message in
-`transcript.json` uses those paths instead of inline data. Generated artifacts stay in `artifacts/`.
-
-Without output, artifacts remain server references. The CLI never clears the scene or
-takes extra screenshots. Defaults are `gpt-6-astra`, `high`, and
-`--api http://127.0.0.1:8787/agent`; unsupported settings are rejected.
-
-Progress goes to stderr; one JSON result goes to stdout. Use `yarn --silent agent-run`
-or the installed `agent-run` executable when parsing stdout (Yarn otherwise adds banners).
-Usage comes from the provider, with per-step USD estimates; missing usage is not estimated.
-Exit codes: 0 completed, 1 run/transport/export failure, 2 invalid arguments,
-3 requires user action (continue in the UI), 130 interrupted. Interrupts attempt to cancel
-only this invocation's run; a failed cancellation is reported and the run may still be active.
-Output directories must not already exist. Artifact manifests include IDs, media types,
-server URLs and relative paths; failed downloads retain their references and report errors.
-Legacy inline base64 uploads in transcripts are replaced with `[inline data omitted]`.
-
-## Mesh Wompify
-
-Swan imports the reference mesh with Disjoint off, then requests reconstruction
-through the shared `mesh-wompify` and `scene-editing` skills. Tier and request
-helpers are exported from `@womp/spark-agent/ui`. Server mode requires Crow to
-install the updated package and be redeployed; a local Swan package link is insufficient.
-The Mesh Wompify function panel accepts a file and a detail level (Simple, High res,
-or Ultra res). Reconstruction matches the reference's shape and colors; textures
-are not carried over. Crow sets the initial cap for each level and bills actual
-usage. Wompify keeps refining across turns until the cap, even if the evaluator
-judges the reconstruction sufficient; insufficient credits or a blocker stop it.
-Reaching the cap completes the pass without a run error. Keep refining
-asks for a new pass budget, then continues in the same conversation with the
-same reference and detail level. The budget travels as structured goal data.
-
-Ordinary goals support `{ action: "update_budget", goalId, creditBudget }` on
-the goal endpoint. This edits the total credit cap without resetting usage,
-restarting the run, or adding a model message. Crow reads the current cap before
-worker and evaluator calls; an in-flight call may finish. Raising an exhausted
-cap leaves the goal paused until Resume. Wompify's tier caps cannot be edited.
-
 ## Package entry points
 
 - `@womp/spark-agent` — browser-safe model loop, two tools, persistence hooks, and shared contracts
@@ -114,8 +37,17 @@ Kakapo, Express, or React at runtime.
 
 `runSparkAgent` accepts a configured model, model messages, an executor, a capability composition,
 and an artifact resolver. It exposes exactly `read_skill` and `execute_javascript` to the model.
-Skills carry instructions, declarations, and JavaScript examples. The native executor runs in the
-page realm; it is not a sandbox and cannot interrupt a synchronous infinite loop.
+Skills carry instructions, declarations, and JavaScript examples. Kakapo skill declarations are
+generated from its typed API at build time and packaged as JavaScript strings.
+
+### System prompt and editor selection
+
+Every host sends `sparkSystemPrompt(skills)`: the shared agent prompt and the skills directory,
+with nothing host-specific, so it stays identical across a conversation. Hosts attach the editor
+selection to the user message it was sent with as a `data-selection` part (`{ nodeIds }`). It is
+not rendered as chat text; the model reads it as a short note on that message.
+
+### Capabilities
 
 Compose only supported capabilities with `composeCapabilities({ scene, account, ... })`. Each
 capability supplies its skills and `createApi(context)`; the returned API is bound under `womp`.
@@ -124,34 +56,35 @@ own their transactions and must check cancellation at their commit boundary.
 
 For a real user interaction, call `context.waitForUser(label, async signal => ...)` outside mutation
 locks. The run stays active with `requires_action` progress and resumes the same invocation after
-input. Native and QuickJS executors exclude this wait from their execution budget; service work
-continues to consume time, and QuickJS guest computation still counts even if an interaction was
-not awaited. Abort settles the wait and late answers cannot revive it. The UI host must also reject
-competing requests for a shared dialog and match callbacks to the original interaction identity.
-Custom executors must honor the optional host-owned `userWait` argument to `execute`.
+input; the wait is excluded from the execution budget. Abort settles the wait and late answers
+cannot revive it. Custom executors must honor the optional host-owned `userWait` argument to `execute`.
+
+Shared SDK scene adapters may omit `operations` to edit and save directly. Supplying `operations`
+adds a durable operation journal and recovery of uncertain edits.
+
+### Persistence and run lifecycle
 
 Persist the user message before starting a run. Supply `persistence.beforeToolCall`,
 `persistence.recordReceipt`, and `persistence.afterToolCall` for awaited storage barriers.
 Supply `persistence.saveMessage` to save the canonical UI message at each model-step boundary and
-at termination, including reasoning and provider metadata. Spark awaits each checkpoint before the
-next model request. Consume the run's stream while awaiting its result; the result settles after
-the terminal checkpoint. A host run owner must keep consuming when a view detaches.
-A failed barrier aborts the loop. The default model-step limit is 100; a limit returns
-`status: "incomplete"`. A host must not automatically restart to bypass that limit.
-A generation that ends on any other non-`stop` reason (`length`, `content-filter`, `error`,
-`other`) rejects the result and ends the run `failed`: its error names the unified reason and the
-provider's raw one, and its diagnostics carry the unified reason as `code`.
-
-Spark does not estimate or limit input tokens or automatically shorten conversation history.
-The provider enforces its context limit; rejections follow the normal provider-error path.
+at termination. Spark awaits each checkpoint before the next model request; a failed barrier aborts
+the loop. Consume the run's stream while awaiting its result; a host run owner must keep consuming
+when a view detaches.
+
+The default model-step limit is 100; reaching it returns `status: "incomplete"`, and hosts must not
+restart automatically to bypass it. A generation that ends on any other non-`stop` reason fails the
+run with the unified and provider finish reasons in its error and diagnostics.
+
+Before each model step, Spark trims older images, large tool results, and whole earlier turns to
+keep the request inside the model's context window. The latest user message and the most recent
+steps are never trimmed.
+
+### Artifacts
 
 Screenshot and file APIs return serializable artifact references. `emitImage` and `emitFile` resolve
 them through the host's artifact resolver. Keep references resolvable when reloading history, and
 pass `createSparkTools(...)` to AI SDK's `convertToModelMessages` to reconstruct multimodal results.
-`emitImage(artifact, { inspect: false })` displays an image without adding its bytes to model input,
-including restored history. Inspection is enabled by default.
-Kakapo skill declarations are generated from its actual typed API during the build and packaged as
-JavaScript strings; they do not need filesystem or Markdown loading in the browser.
+`emitImage(artifact, { inspect: false })` displays an image without adding its bytes to model input.
 
 ## Local frontend
 
@@ -186,10 +119,7 @@ const chat = useChat<SparkUIMessage>({
 
 Render `message.parts`. Standard AI SDK parts represent text, reasoning, files, tool inputs, tool
 outputs, approvals, and step boundaries. Spark adds typed `data-console`, `data-artifact`,
-`data-run-status`, `data-step-metrics`, and `data-execution-receipt` parts. Receipts are emitted before
-their storage barrier, keeping known effects visible even when saving the tool result fails.
-Hosts can consume `data-tool-input-label` once the tool's label field is complete, while the
-remaining input is still streaming.
+`data-run-status`, `data-step-metrics`, `data-execution-receipt`, and `data-tool-input-label` parts.
 
 An explicit Stop action must cancel the durable run before stopping local observation:
 
@@ -205,21 +135,16 @@ Closing or reloading the page only detaches the SSE subscriber. It does not canc
 `SparkChatTransport` hides the durable run lifecycle from `useChat`:
 
 ```text
-POST /agent/conversations/:conversationId/messages
+POST  /agent/conversations/:conversationId/messages
 PATCH /agent/conversations/:conversationId/settings
-GET  /agent/runs/:runId/stream?after=0
-POST /agent/runs/:runId/cancel
+POST  /agent/conversations/:conversationId/goal
+GET   /agent/runs/:runId/stream?after=0
+POST  /agent/runs/:runId/cancel
 ```
 
-Conversation settings contain `modelId` and `reasoningEffort`. The standalone UI saves selector
-changes immediately through `transport.saveConversationSettings(id, settings)` and restores them
-per thread. Older threads fall back to their last recorded model (or the default) and medium effort;
-unsupported choices fall back to supported settings. Assistant footers show the model recorded on
-that turn, independently of the selector.
-
-Custom stores must implement `saveConversationSettings` as a settings-only update, and preserve
-stored settings during `saveConversation` so streaming history saves cannot overwrite preferences.
-The built-in memory and SQLite stores implement this contract.
+Conversation settings contain `modelId` and `reasoningEffort`; save them with
+`transport.saveConversationSettings(id, settings)`. The goal endpoint accepts `set`, `pause`,
+`resume`, `clear`, and `update_budget` commands.
 
 The SSE response contains ordered persistence envelopes around standard AI SDK chunks:
 
@@ -234,8 +159,7 @@ type StoredSparkChunk = {
 ```
 
 The transport unwraps each envelope and returns the contained `UIMessageChunk` to `useChat`.
-Active assistant messages are replayed from sequence zero when reconnecting because `useChat`
-reconstructs the in-progress message from the resumed stream.
+Active assistant messages are replayed from sequence zero when reconnecting.
 
 ## Embedding in an Express backend
 
@@ -266,15 +190,25 @@ app.use(
 
 `MemorySparkAgentStore` and `MemorySparkArtifactStore` are development implementations. Production
 hosts must supply durable implementations backed by their database/object storage and must preserve
-the ordering contract of `appendRunChunk()`.
+the ordering contract of `appendRunChunk()`. Custom stores must also:
+
+- implement `saveConversationSettings` as a settings-only update, and preserve stored settings
+  during `saveConversation`;
+- implement `saveConversationGoal` to support goals;
+- optionally implement `releaseActiveRun(conversationId, runId, updatedAt)` to clear the active run
+  only if its ID still matches.
+
+The built-in memory and SQLite stores implement all of these.
 
 `SparkAgentServiceOptions.endOrphanedRuns` defaults to `false`. Enable it only when one process
-owns the store: a message or Stop then ends unfinished runs not held by that process. On a shared
-store, enabling it could end another process's live run.
+owns the store: a message or Stop then ends unfinished runs not held by that process.
 
-Custom stores can implement `releaseActiveRun(conversationId, runId, updatedAt)` to clear the active
-run only if its ID still matches. Memory and SQLite stores implement it. Without it, the service
-serializes read-and-save release against its own submissions.
+## Mesh Wompify
+
+Mesh Wompify reconstructs an imported reference mesh as editable primitives through the shared
+`mesh-wompify` and `scene-editing` skills. `WOMPIFY_PRESETS`, `wompifyPrompt`, and
+`parseWompifyCommand` are exported from `@womp/spark-agent/ui`. A Wompify run is a goal: it refines
+across turns until its credit cap, and can continue in the same conversation with a new budget.
 
 ## Standalone development server
 
@@ -292,107 +226,63 @@ Configure the process with:
 - `KAKAPO_URL` (defaults to `ws://127.0.0.1:5502`)
 - `PORT` (defaults to `8787`)
 - `SPARK_STORAGE_PATH` (defaults to `.spark/spark.sqlite`)
-- `SPARK_SCENE_IDENTITY` (optional stable identity for the scene behind `KAKAPO_URL`)
+- `SPARK_SCENE_IDENTITY` (optional; set only when the value names the same durable scene across
+  renderer reconnects)
 
-The CLI automatically loads `.env` from its working directory when the file exists. Copy
-`.env.example` to `.env`, then add the provider key you intend to use. Existing process environment
-variables take precedence over values loaded from the file.
+The CLI loads `.env` from its working directory when present; copy `.env.example` to `.env` and add
+the provider key you intend to use. Process environment variables take precedence.
 
 For repository development, `yarn dev` starts the Express server and Vite demo together. Open
-`http://127.0.0.1:5173`.
-
-Shared SDK scene adapters can omit `operations` to use direct edit/save with
-per-invocation outcomes and conversation receipts. This path does not persist a scene
-journal, recover uncertain edits, or reuse previous operation results. Validation,
-settlement, and the host's save policy still apply; geometry/OpenSCAD refund repair
-attempts only after confirmed rollback. Hosts that supply `operations` retain their
-existing journal and recovery behavior.
-
-Standalone scene edits use the existing `scene_state_patch` command followed by `save_scene` after
-the patch is acknowledged. The durable operation journal records the separate mutation and save
-outcomes. A failed or unknown save stops that operation with an explicit error, retaining any
-applied work without replay. The two commands are not an atomic transaction, and a renderer save
-acknowledgement proves only renderer-local history, not durable backend storage.
-
-The standalone server persists conversations, run streams, and screenshot bytes in SQLite. Only
-one local process can execute against a database. After a terminated process is replaced, startup
-preserves recorded output and marks abandoned queued/running runs incomplete without replaying
-scene edits. Pending approvals remain pending; startup does not resume abandoned runs.
-Node 22 reports an experimental warning for its built-in SQLite module.
-
-Set `SPARK_SCENE_IDENTITY` only when the host can verify that the value names the same durable
-scene across renderer reconnects. Without it, Spark uses a process-scoped identity and does not
-authorize interrupted scene mutations to continue after a server restart.
-
-`createStandaloneSparkAgentApp(options)` is asynchronous. Await it before listening, and call
-`await app.dispose()` on shutdown to settle active runs and release storage ownership.
-
-When using a sibling `kakapo-sdk` dependency, run `yarn build` in `../kakapo-sdk` before installing
-Spark dependencies. Replace local dependencies with registry versions before publishing.
-
-For the explicit fictional account profile, use `yarn dev:demo-account` or
-`spark-agent --profile demo-account`. It adds the `account` skill and `womp.account.read`
-beside the real local Kakapo scene API. Profile reads identify themselves as fictional fixtures;
-credits, billing, orders, and other account services report unavailable. The default composition
-omits account entirely. Neither profile supplies fake generation jobs, imports, or billing permission.
-Embedded development servers can select `developmentProfile: "demo-account"` explicitly.
-
-The same profile supplies two actual local material resources: `Development: Matte Blue` and
-`Development: Polished Copper`. They are bundled JSON files under `src/server/fixtures/materials`
-and imported through the normal SDK draft, not simulated scene effects. In `scene.edit`, await
-`api.materialImport(name)`, then assign its numeric ID. The default profile has no library service.
+`http://127.0.0.1:5173`. When using a sibling `kakapo-sdk` dependency, run `yarn build` in
+`../kakapo-sdk` before installing Spark dependencies.
+
+The standalone server persists conversations, run streams, and screenshots in SQLite; only one
+local process can execute against a database. `createStandaloneSparkAgentApp(options)` is
+asynchronous: await it before listening, and call `await app.dispose()` on shutdown.
+
+`yarn dev:demo-account` (or `spark-agent --profile demo-account`) adds a fictional `account` skill
+and two development material resources beside the real local Kakapo scene API. Its account reads
+identify themselves as fixtures; other account services report unavailable.
+
+## Run a prompt from the command line
+
+With the Spark server already running:
+
+```sh
+yarn agent-run --prompt "Make a cube" --model gpt-5.6-luna --reasoning max
+yarn agent-run --prompt "Model this object using both views" --image front.png --image side.jpg --output .spark/agent-runs/reference-model
+```
+
+- `--conversation <id>` continues a thread.
+- `--image <path>` attaches a local PNG, JPEG, WebP or GIF reference; repeat it for more images.
+- `--output <new-directory>` saves `result.json`, `transcript.json`, inputs, and run artifacts.
+  For local runs, use a fresh subdirectory of the git-ignored `.spark/` directory.
+
+Progress goes to stderr; one JSON result goes to stdout. Use `yarn --silent agent-run` when parsing
+stdout. Exit codes: 0 completed, 1 run/transport/export failure, 2 invalid arguments, 3 requires
+user action, 130 interrupted.
 
 ## Run cost estimates
 
-Prompt caching is enabled for every listed model: Claude Opus 5 and Fable 5 use
-automatic 5-minute caching, and GPT-6 Astra uses implicit caching with a 30-minute TTL.
-The providers manage the cache as message history grows across tool steps; no local
-response cache is used. Cache hits require matching prefixes, sufficient prompt length,
-and an unexpired entry. Goal state stays out of the system prompt: objectives,
-goal rules and evaluator feedback arrive in appended goal messages. Cache writes can cost more than uncached input, while subsequent
-cache reads are cheaper. The UI displays actual reported reads/writes, not assumed savings.
-See [Claude caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
-and [OpenAI caching](https://developers.openai.com/api/docs/guides/prompt-caching).
-Restart the server after changing these settings; existing runs keep their original configuration.
-
-The chat displays estimated API token cost in USD, updated after every completed model step.
-Hover or focus the amount to inspect uncached input, cache reads/writes, and output costs. Output usage
-already includes reasoning tokens. Image input is included in the provider's input token count.
-
-`src/pricing.ts` contains standard direct API rates verified on September 9, 2026:
-
-| Model          | Input / 1M | Cache read / 1M | Cache write / 1M      | Output / 1M |
-| -------------- | ---------- | --------------- | --------------------- | ----------- |
-| GPT-6 Astra    | $10        | $1              | $12.50                | $50         |
-| Claude Opus 5  | $5         | $0.50           | $6.25 (5m), $10 (1h)  | $25         |
-| Claude Fable 5 | $10        | $1              | $12.50 (5m), $20 (1h) | $50         |
-
-Astra requests above 272,000 input tokens use 2x input/cache rates and 1.5x output rates.
-This threshold is applied to each request before summing run costs. Claude's full context uses
-standard rates. Sources: [Astra pricing](https://developers.openai.com/api/docs/models/gpt-6-astra),
-[Claude pricing](https://platform.claude.com/docs/en/about-claude/pricing).
-
-Each `data-step-metrics` part stores a `cost` snapshot with the model, rate date, source, token
-categories, rates, and amounts. The UI sums those stored amounts, so reconnection does not double
-count steps and future price changes do not reprice recorded runs. Update the rate table and its
-verification date when provider pricing changes.
-
-The unfinished step is excluded until its usage arrives. Cancelled/failed runs show a partial
-estimate. Missing usage, unknown models, missing cache TTLs, or provider sub-inferences without
-separate attribution are marked unavailable, never silently priced as zero. Historical runs
-without step pricing remain unavailable. Estimates exclude taxes, negotiated discounts, and scene
-hosting; the provider bill is authoritative. Spark requests OpenAI's standard service tier.
+The chat displays estimated API token cost in USD after every completed model step, from the
+provider-reported usage and the rates in `src/pricing.ts`. Each `data-step-metrics` part stores
+its `cost` snapshot, so recorded runs are not repriced when rates change. Missing usage or unknown
+models are shown as unavailable, never priced as zero. Estimates exclude taxes, discounts, and
+scene hosting; the provider bill is authoritative.
+
+Prompt caching is enabled for every listed model. It depends on an identical request prefix, which
+is why per-turn state travels in messages rather than the system prompt.
 
 ## Execution security
 
 The standalone host uses a fresh QuickJS runtime for each JavaScript execution. It has no Node.js
 or browser globals and receives only the composed capability APIs. Imports, filesystem access,
 network APIs, and host environment variables are not exposed. QuickJS limits memory, stack size,
-execution time, source size, host calls, and data crossing the host bridge. Browser hosts can instead
-choose native page execution, with the page-global access and interruption limitations described above.
-Both executors allow 100,000 host calls per execution by default; the counter resets for each
-execution. QuickJS supports overriding this through `maxHostCalls`. Cancellation, timeouts,
-and the other execution limits still apply.
+execution time, source size, host calls, and data crossing the host bridge. Both executors allow
+100,000 host calls per execution by default (`maxHostCalls` overrides this in QuickJS).
+
+Browser hosts can instead use native page execution. It runs in the page realm: it is not a sandbox
+and cannot interrupt a synchronous infinite loop.
 
 QuickJS isolates generated code from the JavaScript host API; it is not an operating-system security
 boundary. Multi-tenant deployments must additionally isolate workers, authorize every Kakapo
@@ -410,41 +300,30 @@ yarn web:build
 
 ## Release procedure
 
-Pushes to `main` run `.github/workflows/publish.yml`. Publication is driven by
-`package.json`, not Git tags: already-published versions skip; unpublished stable versions
-newer than npm's `latest` run release checks and publish automatically.
-
-Versions follow **MAJOR.MINOR.PATCH** (for example, `4.4.0`):
-
-- **Major:** breaking changes.
-- **Minor:** backward-compatible new features.
-- **Patch:** backward-compatible bug fixes.
+Pushes to `main` run `.github/workflows/publish.yml`. Publication is driven by `package.json`, not
+Git tags: already-published versions are skipped; an unpublished stable version newer than npm's
+`latest` runs the release checks and is published automatically.
 
-### Publishing
+Versions follow **MAJOR.MINOR.PATCH**: major for breaking changes, minor for backward-compatible
+features, patch for backward-compatible fixes.
 
 1. Configure npm's trusted publisher once for `@womp/spark-agent`: organization `wompxyz`,
    repository `spark-agent`, workflow filename `publish.yml`, no environment, and allow direct
    `npm publish`. GitHub-hosted runners use OIDC; no publishing token is required.
-2. Deliberately bump `package.json` to an unused stable MAJOR.MINOR.PATCH version and push
-   the release commit to `main`. Prereleases/build metadata are not published by this workflow.
-3. CI installs the frozen Yarn lockfile, runs typechecks, tests and the UI build, then checks
-   package entry files and imports every exported module from a fresh tarball installation.
-   It rechecks npm before publishing that same archive and verifies registry integrity and `latest`,
-   allowing up to five minutes of polling waits for npm processing and metadata propagation.
-   A visible integrity mismatch fails immediately; missing metadata or a lagging `latest` fails
-   if it does not converge within the polling limit.
-   Releases are serialized; newer pending pushes may supersede older pending runs.
-   Registry failures stop publication rather than being treated as missing versions.
-4. If publication reports an uncertain result, inspect npm before rerunning the failed workflow.
-   Published versions cannot be replaced; corrections need a new version. No tags are required.
-5. In the consuming application, use `yarn add @womp/spark-agent@<version> --exact`. Commit its
-   manifest and lockfile together, and verify a clean frozen-lockfile installation and production
-   build. Remove the temporary archive dependency. Application deployment and merge requirements
-   remain separate from package publication.
+2. Bump `package.json` to an unused stable version, add its entry to `CHANGELOG.md`, and push the
+   release commit to `main`. Prereleases are not published by this workflow.
+3. CI installs the frozen lockfile, runs typechecks, tests and the UI build, verifies the packed
+   tarball's entry points and imports, then publishes and verifies registry integrity and `latest`.
+4. If publication reports an uncertain result, inspect npm before rerunning the workflow. Published
+   versions cannot be replaced; corrections need a new version.
+5. In the consuming application, run `yarn add @womp/spark-agent@<version> --exact` and commit its
+   manifest and lockfile together.
 
 ## Layout
 
 - `src/agent.ts` — AI SDK stream and Spark tool orchestration
+- `src/prompt.ts` — shared system prompt
+- `src/context-budget.ts` — per-step context-window trimming
 - `src/ui.ts` — browser-safe protocol types and validation schemas
 - `src/client.ts` — durable `ChatTransport` implementation
 - `src/server/` — service, storage contracts, Express adapter, artifacts, and standalone composition

package/dist/agent-tools.js

@@ -1,6 +1,6 @@
 import { tool } from "ai";
 import { z } from "zod";
-import { boundedResultText } from "./bounded-output.js";
+import { boundedResultText, canonicalJsonValue } from "./bounded-output.js";
 import { completedInputString } from "./tool-input-label.js";
 import { UserWait } from "./execution-lifetime.js";
 function errorMessage(error) {
@@ -98,6 +98,8 @@ export function createSparkTools(options) {
                 const skills = [...new Set(input.names)].map(read);
                 return { ok: skills.every(skill => skill.ok), skills };
             }),
+            // Replayed from storage that may reorder keys; see canonicalJsonValue.
+            toModelOutput: ({ output }) => ({ type: "json", value: canonicalJsonValue(output) }),
         }),
         execute_javascript: tool({
             ...inputLabels("purpose"),

package/dist/agent.d.ts

@@ -22,7 +22,6 @@ export type SparkAgentOptions = {
     runId: string;
     messageId: string;
     signal?: AbortSignal;
-    context?: string;
     instructions?: string;
     maxSteps?: number;
     maxOutputTokens?: number;

package/dist/agent.js

@@ -2,7 +2,7 @@ import { sparkErrorDiagnostics } from "./error-diagnostics.js";
 import { WompifyCreditCapReachedError } from "./wompify.js";
 import { createUIMessageStream, stepCountIs, streamText, } from "ai";
 import { createSparkTools } from "./agent-tools.js";
-import { SPARK_AGENT_PROMPT } from "./prompt.js";
+import { sparkSystemPrompt } from "./prompt.js";
 import { calculateStepCost } from "./pricing.js";
 import { contextWindowFor, fitMessagesToContext } from "./context-budget.js";
 function errorMessage(error) {
@@ -124,16 +124,7 @@ export function runSparkAgent(options) {
                     controller,
                     write: (chunk) => writer.write(chunk),
                 });
-                // Must stay identical across the turns of a conversation: any change misses the
-                // provider's prompt cache for everything after it. Changing state belongs in messages.
-                const readSystem = () => [
-                    options.instructions ?? SPARK_AGENT_PROMPT,
-                    options.context,
-                    "Available skills (read before using their APIs):",
-                    ...options.capabilities.skills.map(({ name, version, description }) => `- ${name} (${version}): ${description}`),
-                ]
-                    .filter(Boolean)
-                    .join("\n\n");
+                const readSystem = () => sparkSystemPrompt(options.capabilities.skills, options.instructions);
                 const generation = streamText({
                     model: options.model,
                     system: readSystem(),

package/dist/bounded-output.d.ts

@@ -1,5 +1,13 @@
 export declare const MODEL_RESULT_BYTE_LIMIT: number;
 export declare const MODEL_ERROR_BYTE_LIMIT: number;
+/**
+ * `value` with every object's keys sorted, recursively. Hosts store tool
+ * results in databases that reorder keys (Postgres JSONB puts shorter keys
+ * first), so a replayed result must not depend on the order it was read back
+ * in: the bytes the model reads have to match what the live run sent, or every
+ * later turn misses the provider's prompt cache from that result onward.
+ */
+export declare function canonicalJsonValue(value: unknown): unknown;
 export declare function byteLength(text: string): number;
 /**
  * `text` cut to at most `limit` bytes on a character boundary. A cut that lands
@@ -15,8 +23,9 @@ export declare function truncateUtf8(text: string, limit: number): string;
 export declare function boundedText(text: string, limit: number, label: string): string;
 /**
  * The serialized tool result the model reads, bounded to
- * `MODEL_RESULT_BYTE_LIMIT`. Persistence, the UI stream and the host's own
- * receipts keep the full output; only model input is bounded here.
+ * `MODEL_RESULT_BYTE_LIMIT`, with keys in canonical order. Persistence, the UI
+ * stream and the host's own receipts keep the full output; only model input is
+ * bounded here.
  *
  * Stages, in order, so the most useful part survives: bound `error`, then bound
  * each receipt's `details`, then keep only as many receipts as the budget

package/dist/bounded-output.js

@@ -4,6 +4,23 @@ const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 export const MODEL_RESULT_BYTE_LIMIT = 1024 * 1024;
 export const MODEL_ERROR_BYTE_LIMIT = 8 * 1024;
+/**
+ * `value` with every object's keys sorted, recursively. Hosts store tool
+ * results in databases that reorder keys (Postgres JSONB puts shorter keys
+ * first), so a replayed result must not depend on the order it was read back
+ * in: the bytes the model reads have to match what the live run sent, or every
+ * later turn misses the provider's prompt cache from that result onward.
+ */
+export function canonicalJsonValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalJsonValue);
+    if (value === null || typeof value !== "object")
+        return value;
+    const record = value;
+    return Object.fromEntries(Object.keys(record)
+        .sort()
+        .map((key) => [key, canonicalJsonValue(record[key])]));
+}
 export function byteLength(text) {
     return encoder.encode(text).byteLength;
 }
@@ -33,8 +50,9 @@ export function boundedText(text, limit, label) {
 }
 /**
  * The serialized tool result the model reads, bounded to
- * `MODEL_RESULT_BYTE_LIMIT`. Persistence, the UI stream and the host's own
- * receipts keep the full output; only model input is bounded here.
+ * `MODEL_RESULT_BYTE_LIMIT`, with keys in canonical order. Persistence, the UI
+ * stream and the host's own receipts keep the full output; only model input is
+ * bounded here.
  *
  * Stages, in order, so the most useful part survives: bound `error`, then bound
  * each receipt's `details`, then keep only as many receipts as the budget
@@ -46,7 +64,7 @@ export function boundedResultText(output, limit = MODEL_RESULT_BYTE_LIMIT) {
     const errorBounded = typeof output.error === "string"
         ? { ...output, error: boundedText(output.error, MODEL_ERROR_BYTE_LIMIT, "Error") }
         : output;
-    const asText = (value) => JSON.stringify(value) ?? "null";
+    const asText = (value) => JSON.stringify(canonicalJsonValue(value)) ?? "null";
     let text = asText(errorBounded);
     if (byteLength(text) <= limit)
         return text;

package/dist/index.d.ts

@@ -8,5 +8,5 @@ export { recoverSceneOperation, type SceneOperation, type SceneOperationStore }
 export type { JavaScriptExecutor, JavaScriptGlobals, JavaScriptUserWait } from "./executor.js";
 export { DEFAULT_MODEL_ID, getSparkModel, REASONING_EFFORT_LABELS, resolveReasoningEffort, SPARK_MODELS, } from "./models.js";
 export type { ModelProvider, ReasoningEffort, SparkModel } from "./models.js";
-export { SPARK_AGENT_PROMPT } from "./prompt.js";
+export { SPARK_AGENT_PROMPT, sparkSystemPrompt } from "./prompt.js";
 export type { ExecutionResult, ExecutionScreenshot, SparkRuntimeEvent, SparkRuntimeEventSink, SparkContextMessage, SparkImage, SparkRunInput, SparkRuntime, } from "./types.js";

package/dist/index.js

@@ -6,4 +6,4 @@ export * from "./capabilities.js";
 export { createSdkSceneEditor, createSdkSceneHost, } from "./sdk-scene-host.js";
 export { recoverSceneOperation } from "./scene-operations.js";
 export { DEFAULT_MODEL_ID, getSparkModel, REASONING_EFFORT_LABELS, resolveReasoningEffort, SPARK_MODELS, } from "./models.js";
-export { SPARK_AGENT_PROMPT } from "./prompt.js";
+export { SPARK_AGENT_PROMPT, sparkSystemPrompt } from "./prompt.js";

package/dist/model-history.d.ts

@@ -1,5 +1,5 @@
 import { type ModelMessage } from "ai";
 import type { createSparkTools } from "./agent-tools.js";
-import type { SparkUIMessage } from "./ui.js";
+import { type SparkUIMessage } from "./ui.js";
 /** UI artifact previews already represented by a tool result are not model output. */
 export declare function convertSparkMessages(messages: SparkUIMessage[], tools: ReturnType<typeof createSparkTools>): Promise<ModelMessage[]>;

package/dist/model-history.js

@@ -1,12 +1,30 @@
-import { convertToModelMessages } from "ai";
+import { asSchema, convertToModelMessages } from "ai";
+import { sparkDataPartSchemas } from "./ui.js";
 function record(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value)
         ? value
         : {};
 }
+/**
+ * A stored call's input as the live run handed it to the model: the AI SDK
+ * passes on the input its schema validated, in the schema's key order, while
+ * storage may return the keys in another order (Postgres JSONB sorts them).
+ * An input the schema refuses is replayed as stored.
+ */
+async function liveInput(tools, part) {
+    if (part.type !== "dynamic-tool" && !part.type.startsWith("tool-"))
+        return part;
+    const name = part.type === "dynamic-tool" ? part.toolName : part.type.slice(5);
+    const tool = tools[name];
+    const input = part.input;
+    if (tool === undefined || input === null || typeof input !== "object" || Array.isArray(input))
+        return part;
+    const validated = await asSchema(tool.inputSchema).validate?.(input);
+    return validated?.success ? { ...part, input: validated.value } : part;
+}
 /** UI artifact previews already represented by a tool result are not model output. */
-export function convertSparkMessages(messages, tools) {
-    const history = messages.map((message) => {
+export async function convertSparkMessages(messages, tools) {
+    const history = await Promise.all(messages.map(async (message) => {
         if (message.role !== "assistant")
             return message;
         const previews = new Set();
@@ -27,8 +45,20 @@ export function convertSparkMessages(messages, tools) {
         }
         return {
             ...message,
-            parts: message.parts.filter((part) => part.type !== "file" || (!previews.has(part.url) && part.providerMetadata?.spark?.inspect !== false)),
+            parts: await Promise.all(message.parts
+                .filter((part) => part.type !== "file" || (!previews.has(part.url) && part.providerMetadata?.spark?.inspect !== false))
+                .map((part) => liveInput(tools, part))),
         };
+    }));
+    return convertToModelMessages(history, {
+        tools,
+        convertDataPart: (part) => {
+            if (part.type !== "data-selection")
+                return undefined;
+            const selection = sparkDataPartSchemas.selection.safeParse(part.data);
+            return selection.success
+                ? { type: "text", text: `[Scene objects selected when this message was sent (node IDs): ${selection.data.nodeIds.join(", ")}]` }
+                : undefined;
+        },
     });
-    return convertToModelMessages(history, { tools });
 }

package/dist/prompt.d.ts

@@ -1 +1,8 @@
-export declare const SPARK_AGENT_PROMPT = "You are Spark, Womp's unified assistant.\nUse read_skill({names:[...]}) to load the required APIs together. Skills provide TypeScript\ndeclarations for documentation; execute_javascript runs JavaScript, with top-level await.\nOnly the listed capabilities are available. Reading a skill does not grant additional permissions.\nUse only the supplied womp APIs and output helpers to access application services and state.\nIf a capability is unavailable, explain what is missing and ask the user to enable it when applicable.\nDo not work around missing capabilities by inspecting page globals, DOM or framework internals,\nor making direct network requests. Native execution is not a security sandbox; it does not expand\nthe supported API or the user's granted capabilities.\nGive each execute_javascript call a concise present-progressive purpose, such as \"Generating a car image\", \"Inspecting the scene\", or \"Importing the model\". Write purpose before code.\nEach execution has fresh local variables. Keep stable object, job, and artifact references.\nUse print for concise, filtered observations; await emitImage or emitFile with a host-issued artifact\nreference to show actual output. emitImage inspects by default; use { inspect: false } to display without adding image bytes to model context.\nCompleted generations are shown automatically to the user; image bytes are intentionally omitted from your context. Acknowledge completion without listing, re-emitting, or inspecting outputs unless the task requires it. Use returned artifact references for follow-up work.\nDo not claim visual verification without inspecting the image. Missing artifact references must be recovered or reported; omitted image bytes alone are not a missing result.\nInspect the scene before editing and verify the committed result.\nPreserve existing content unless the user asks to replace or delete it. Use the latest target revision\nwhen a write requires one. Capabilities own transactions: an entire script is not atomic.\nIf an operation fails after earlier effects, use its receipts to inspect and retry only unresolved work.\nNever claim an uncertain commit rolled back. Never resubmit a job just because waiting timed out.\nComplete related work in this conversation without delegating to another agent. Report limits,\nunsupported actions, cancellation, and incomplete work truthfully. You cannot see what your work\ncosts: model use can be billed, not only generations. Never estimate credits used or call work free;\nreport only credit figures a host message or tool provides. Finish with a concise explanation\nof the result in the user's language; keep implementation details out of that explanation.\n\nCreation intent\n\nResolve the requested outcome from the current message and preceding dialogue, not keyword matches.\nExplicit method choices take precedence. Continue edits in the existing representation unless the user\nasks to change it. Creation defaults do not apply to help, discussion, imports, or account questions.\n\n- Build directly with editable scene shapes for ordinary 3D requests, including \"3D X\" and\n  \"make X in 3D\", and when the user wants individually editable shapes or geometry that blends\n  with existing objects. Organic appearance alone does not require Geometry Nodes.\n\n- Use OpenSCAD for parametric, measured, mechanical, printable, or real-world-fit objects,\n  except when another method is explicit (including primitives with dimensions), or when\n  parametric organic/procedural geometry, animation, or Geometry Nodes is requested:\n  use Geometry Nodes for those, not Workbench Flow. Do not claim print readiness without validation.\n\n- For mesh wompification, read mesh-wompify and scene-editing together and reconstruct only the specified reference using primitives and curves.\n\n- Use mesh generation when the user explicitly requests a mesh, asks to turn an existing or\n  attached image into 3D, or chooses a sculpted result rather than individually editable shapes.\n\n- Use image generation for pictures, logos, concept art, wallpapers, and other clearly visual output.\n\n- For an ambiguous creative request without explicit 3D or printing intent, generate one image\n  preview first. Then offer one short, outcome-based choice: refine the image, turn it into a\n  sculpted 3D piece, or build it from individually editable shapes. Offer adjustable CAD instead\n  of editable shapes when the subject is measured or must fit something real.\n\n- Also preview first when a 3D request without a named method depends on likeness or surface\n  detail that shapes cannot carry (characters, creatures, people, food, sculptures, specific\n  vehicles or branded items). Plain functional objects still build directly.\n\n- Generating a result does not authorize importing, converting, or building it in the scene.\n\n- Use Workbench Flow for image/mesh generation explicitly requested through Flow/nodes or\n  continued edits to that Flow workflow, unless the user asks for an inline result. Flow must be\n  open; explain that prerequisite if closed instead of silently generating inline. Merely opening\n  Flow does not redirect ordinary scene requests or inline generation to it.\n\n- After a preview, offer the choice above. After other completed generation, you may briefly\n  suggest a relevant next step using available capabilities. Describe its outcome, not internal tools. Suggestions are optional,\n  not a mandatory menu, and never authorize actions. Wait for a clear choice and follow existing\n  confirmations. Reuse the existing artifact/reference for the chosen follow-up, including as the\n  image-to-mesh input, instead of regenerating the source. Preserve its defining features when building it.\n\n- Choose construction methods by the user's requested workflow and the\n  available capabilities, not by assuming editable shapes require lower\n  fidelity. Outside the preview defaults above, a sculpted appearance does not by itself\n  require mesh generation.\n  Respect an explicit method choice and pursue the reference's visible shape\n  and detail with that method. Offer alternatives only for a specific\n  demonstrated limitation; ask before switching or simplifying the requested\n  result. No method guarantees exact reconstruction from a single image.\n\n- Ask at most one focused question at a time, only when a sensible default\n  would likely produce the wrong outcome. Do not repeat resolved questions.\n  Interpret replies using the preceding offer; if several options were\n  offered and \u201Cyes\u201D does not identify one, clarify briefly.\n\n- Treat a clear answer to your question as an instruction to proceed.\n  Continue from existing results rather than restarting the workflow.\n\nOffer only workflows available in this host. Follow their authorization\nand confirmation requirements before generation or scene changes. If a requested workflow is unavailable,\nexplain the limitation rather than silently substituting another.";
+import type { SparkSkill } from "./capabilities.js";
+export declare const SPARK_AGENT_PROMPT = "You are Spark, Womp's unified assistant.\nUse read_skill({names:[...]}) to load the required APIs together. Skills provide TypeScript\ndeclarations for documentation; execute_javascript runs JavaScript, with top-level await.\nOnly the listed capabilities are available. Reading a skill does not grant additional permissions.\nUse only the supplied womp APIs and output helpers to access application services and state.\nIf a capability is unavailable, explain what is missing and ask the user to enable it when applicable.\nDo not work around missing capabilities by inspecting page globals, DOM or framework internals,\nor making direct network requests. Native execution is not a security sandbox; it does not expand\nthe supported API or the user's granted capabilities.\nGive each execute_javascript call a concise present-progressive purpose, such as \"Generating a car image\", \"Inspecting the scene\", or \"Importing the model\". Write purpose before code.\nEach execution has fresh local variables. Keep stable object, job, and artifact references.\nUse print for concise, filtered observations; await emitImage or emitFile with a host-issued artifact\nreference to show actual output. emitImage inspects by default; use { inspect: false } to display without adding image bytes to model context.\nCompleted generations are shown automatically to the user; image bytes are intentionally omitted from your context. Acknowledge completion without listing, re-emitting, or inspecting outputs unless the task requires it. Use returned artifact references for follow-up work.\nDo not claim visual verification without inspecting the image. Missing artifact references must be recovered or reported; omitted image bytes alone are not a missing result.\nInspect the scene before editing and verify the committed result.\nPreserve existing content unless the user asks to replace or delete it. Use the latest target revision\nwhen a write requires one. Capabilities own transactions: an entire script is not atomic.\nRecover ordinary tool errors yourself: use confirmed receipts and fresh reads, retry only unresolved work,\npreserve successful changes, and never replay an interrupted script. Do not narrate internal failures\nunless recovery cannot continue. Never claim an uncertain commit rolled back. Never resubmit a job just because waiting timed out.\nComplete related work in this conversation without delegating to another agent. Report limits,\nunsupported actions, cancellation, and incomplete work truthfully. You cannot see what your work\ncosts: model use can be billed, not only generations. Never estimate credits used or call work free;\nreport only credit figures a host message or tool provides. Finish with a concise explanation\nof the result in the user's language; keep implementation details out of that explanation.\n\nCreation intent\n\nResolve the requested outcome from the current message and preceding dialogue, not keyword matches.\nExplicit method choices take precedence. Continue edits in the existing representation unless the user\nasks to change it. Creation defaults do not apply to help, discussion, imports, or account questions.\n\n- Build directly with editable scene shapes for ordinary 3D requests, including \"3D X\" and\n  \"make X in 3D\", and when the user wants individually editable shapes or geometry that blends\n  with existing objects. Organic appearance alone does not require Geometry Nodes.\n\n- Use OpenSCAD for parametric, measured, mechanical, printable, or real-world-fit objects,\n  except when another method is explicit (including primitives with dimensions), or when\n  parametric organic/procedural geometry, animation, or Geometry Nodes is requested:\n  use Geometry Nodes for those, not Workbench Flow. Do not claim print readiness without validation.\n\n- For mesh wompification, read mesh-wompify and scene-editing together and reconstruct only the specified reference using primitives and curves.\n\n- Use mesh generation when the user explicitly requests a mesh, asks to turn an existing or\n  attached image into 3D, or chooses a sculpted result rather than individually editable shapes.\n\n- Use image generation for pictures, logos, concept art, wallpapers, and other clearly visual output.\n\n- For an ambiguous creative request without explicit 3D or printing intent, generate one image\n  preview first. Then offer one short, outcome-based choice: refine the image, turn it into a\n  sculpted 3D piece, or build it from individually editable shapes. Offer adjustable CAD instead\n  of editable shapes when the subject is measured or must fit something real.\n\n- Also preview first when a 3D request without a named method depends on likeness or surface\n  detail that shapes cannot carry (characters, creatures, people, food, sculptures, specific\n  vehicles or branded items). Plain functional objects still build directly.\n\n- Generating a result does not authorize importing, converting, or building it in the scene.\n\n- Use Workbench Flow for image/mesh generation explicitly requested through Flow/nodes or\n  continued edits to that Flow workflow, unless the user asks for an inline result. Flow must be\n  open; explain that prerequisite if closed instead of silently generating inline. Merely opening\n  Flow does not redirect ordinary scene requests or inline generation to it.\n\n- After a preview, offer the choice above. After other completed generation, you may briefly\n  suggest a relevant next step using available capabilities. Describe its outcome, not internal tools. Suggestions are optional,\n  not a mandatory menu, and never authorize actions. Wait for a clear choice and follow existing\n  confirmations. Reuse the existing artifact/reference for the chosen follow-up, including as the\n  image-to-mesh input, instead of regenerating the source. Preserve its defining features when building it.\n\n- Choose construction methods by the user's requested workflow and the\n  available capabilities, not by assuming editable shapes require lower\n  fidelity. Outside the preview defaults above, a sculpted appearance does not by itself\n  require mesh generation.\n  Respect an explicit method choice and pursue the reference's visible shape\n  and detail with that method. Offer alternatives only for a specific\n  demonstrated limitation; ask before switching or simplifying the requested\n  result. No method guarantees exact reconstruction from a single image.\n\n- Ask at most one focused question at a time, only when a sensible default\n  would likely produce the wrong outcome. Do not repeat resolved questions.\n  Interpret replies using the preceding offer; if several options were\n  offered and \u201Cyes\u201D does not identify one, clarify briefly.\n\n- Treat a clear answer to your question as an instruction to proceed.\n  Continue from existing results rather than restarting the workflow.\n\nOffer only workflows available in this host. Follow their authorization\nand confirmation requirements before generation or scene changes. If a requested workflow is unavailable,\nexplain the limitation rather than silently substituting another.";
+/**
+ * The system prompt every host sends: the agent prompt and the skills directory.
+ * It must stay identical across the turns and steps of a conversation, or the
+ * provider's prompt cache misses; per-turn state travels in messages instead.
+ */
+export declare function sparkSystemPrompt(skills: readonly Pick<SparkSkill, "name" | "version" | "description">[], instructions?: string): string;

package/dist/prompt.js

@@ -16,8 +16,9 @@ Do not claim visual verification without inspecting the image. Missing artifact
 Inspect the scene before editing and verify the committed result.
 Preserve existing content unless the user asks to replace or delete it. Use the latest target revision
 when a write requires one. Capabilities own transactions: an entire script is not atomic.
-If an operation fails after earlier effects, use its receipts to inspect and retry only unresolved work.
-Never claim an uncertain commit rolled back. Never resubmit a job just because waiting timed out.
+Recover ordinary tool errors yourself: use confirmed receipts and fresh reads, retry only unresolved work,
+preserve successful changes, and never replay an interrupted script. Do not narrate internal failures
+unless recovery cannot continue. Never claim an uncertain commit rolled back. Never resubmit a job just because waiting timed out.
 Complete related work in this conversation without delegating to another agent. Report limits,
 unsupported actions, cancellation, and incomplete work truthfully. You cannot see what your work
 costs: model use can be billed, not only generations. Never estimate credits used or call work free;
@@ -88,3 +89,15 @@ asks to change it. Creation defaults do not apply to help, discussion, imports,
 Offer only workflows available in this host. Follow their authorization
 and confirmation requirements before generation or scene changes. If a requested workflow is unavailable,
 explain the limitation rather than silently substituting another.`;
+/**
+ * The system prompt every host sends: the agent prompt and the skills directory.
+ * It must stay identical across the turns and steps of a conversation, or the
+ * provider's prompt cache misses; per-turn state travels in messages instead.
+ */
+export function sparkSystemPrompt(skills, instructions = SPARK_AGENT_PROMPT) {
+    return [
+        instructions,
+        "Available skills (read before using their APIs):",
+        ...skills.map(({ name, version, description }) => `- ${name} (${version}): ${description}`),
+    ].join("\n\n");
+}

package/dist/server/executor.d.ts

@@ -9,7 +9,7 @@ export type ResolvedSparkModel = {
 };
 export type SparkRunExecutorOptions = {
     resolveModel(settings: SparkRunSettings): ResolvedSparkModel | Promise<ResolvedSparkModel>;
-    createHost(context: SparkRunExecutionContext): Promise<Pick<SparkAgentOptions, "capabilities" | "executor" | "artifacts" | "persistence" | "context"> & {
+    createHost(context: SparkRunExecutionContext): Promise<Pick<SparkAgentOptions, "capabilities" | "executor" | "artifacts" | "persistence"> & {
         dispose(): void;
     }>;
 };

package/dist/server/executor.js

@@ -23,7 +23,6 @@ export function createSparkRunExecutor(options) {
                 runId: context.runId,
                 messageId: context.assistantMessageId,
                 signal: context.signal,
-                context: host.context,
             });
             return { stream: run.stream, result: run.result.finally(() => host.dispose()) };
         }

package/dist/server/service.js

@@ -57,7 +57,8 @@ function normalizeUserMessage(message) {
         throw new SparkServiceError(400, "A new chat message must have the user role.");
     }
     for (const part of message.parts) {
-        if (part.type === "text")
+        // The data schemas are checked with the rest of the message (validateUIMessages).
+        if (part.type === "text" || part.type === "data-selection")
             continue;
         if (part.type === "file" &&
             part.mediaType.startsWith("image/") &&

package/dist/ui.d.ts

@@ -89,6 +89,11 @@ export type SparkDataParts = {
         toolCallId: string;
         receipt: ExecutionReceipt;
     };
+    selection: SparkSelectionData;
+};
+/** Editor node IDs selected when a user message was sent; never rendered as chat text. */
+export type SparkSelectionData = {
+    nodeIds: string[];
 };
 export type ExecuteJavaScriptInput = {
     purpose: string;
@@ -321,6 +326,13 @@ export declare const sparkDataPartSchemas: {
         }, z.core.$strip>>;
         usage: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strip>;
+    /**
+     * The editor selection when a user message was sent. Hosts attach it to that
+     * message and do not render it; the model reads it as text (model-history.ts).
+     */
+    readonly selection: z.ZodObject<{
+        nodeIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
 };
-export { parseWompifyCommand, WOMPIFY_PRESETS, wompifyPrompt, wompifyContext, wompifyContextSchema, type WompifyRequest, type WompifyContext } from "./wompify.js";
+export { parseWompifyCommand, WOMPIFY_PRESETS, wompifyPrompt, wompifyContextSchema, type WompifyRequest, type WompifyContext } from "./wompify.js";
 export { parseSparkGoalCommand, DEFAULT_GOAL_CREDITS } from "./goals.js";

package/dist/ui.js

@@ -79,6 +79,12 @@ export const sparkDataPartSchemas = {
         cost: sparkStepCostSchema.optional(),
         usage: z.unknown().optional(),
     }),
+    /**
+     * The editor selection when a user message was sent. Hosts attach it to that
+     * message and do not render it; the model reads it as text (model-history.ts).
+     */
+    // Editor ids are the engine's decimal integers; 8192 covers a select-all at the engine's budgets.
+    selection: z.object({ nodeIds: z.array(z.string().min(1).max(64)).min(1).max(8192) }),
 };
-export { parseWompifyCommand, WOMPIFY_PRESETS, wompifyPrompt, wompifyContext, wompifyContextSchema } from "./wompify.js";
+export { parseWompifyCommand, WOMPIFY_PRESETS, wompifyPrompt, wompifyContextSchema } from "./wompify.js";
 export { parseSparkGoalCommand, DEFAULT_GOAL_CREDITS } from "./goals.js";

package/dist/wompify.d.ts

@@ -29,8 +29,11 @@ export declare const wompifyContextSchema: z.ZodObject<{
     }>;
 }, z.core.$strip>;
 export type WompifyContext = z.infer<typeof wompifyContextSchema>;
-export declare function wompifyContext(context?: WompifyContext): string | undefined;
-export declare function wompifyPrompt(preset: WompifyRequest["preset"], referenceName: string, note?: string): string;
+/** The Wompify request message, which is also the goal objective every continuation repeats. */
+export declare function wompifyPrompt(request: WompifyContext & {
+    referenceName: string;
+    note?: string;
+}): string;
 export declare function parseWompifyCommand(text: string): {
     preset: WompifyRequest["preset"];
     note: string;

package/dist/wompify.js

@@ -15,13 +15,12 @@ export const wompifyContextSchema = z.object({
     referenceNamePrefix: z.string().trim().min(1).max(200),
     preset: z.enum(["simple", "high", "ultra"]),
 });
-export function wompifyContext(context) {
-    if (!context)
-        return undefined;
-    return `Use the mesh-wompify skill for reference name prefix ${JSON.stringify(context.referenceNamePrefix)} at tier ${WOMPIFY_PRESETS[context.preset].label}. Stop if that skill is unavailable.`;
-}
-export function wompifyPrompt(preset, referenceName, note = "") {
-    return `Wompify ${JSON.stringify(referenceName)} at tier ${WOMPIFY_PRESETS[preset].label}.${note.trim() ? `\n${note.trim()}` : ""}`;
+/** The Wompify request message, which is also the goal objective every continuation repeats. */
+export function wompifyPrompt(request) {
+    const note = request.note?.trim();
+    return `Wompify ${JSON.stringify(request.referenceName)} at tier ${WOMPIFY_PRESETS[request.preset].label}.`
+        + `\nUse the mesh-wompify skill for reference name prefix ${JSON.stringify(request.referenceNamePrefix)}. Stop if that skill is unavailable.`
+        + (note ? `\n${note}` : "");
 }
 export function parseWompifyCommand(text) {
     const match = /^\/wompify (simple|high|ultra)(?:\n([\s\S]*))?$/u.exec(text.trim());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@womp/spark-agent",
-  "version": "5.12.1",
+  "version": "6.0.1",
   "description": "Portable skills-based AI agent with local and durable chat transports for Womp",
   "type": "module",
   "main": "./dist/index.js",
@@ -73,7 +73,8 @@
     "dist/**/*.d.ts",
     "dist/server/fixtures/**/*.json",
     "dist/geometry/schemas/**/*.json",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "sideEffects": false,
   "engines": {