@womp/spark-agent 5.6.1 → 5.7.1

package/README.md

@@ -1,412 +1,412 @@
-# @womp/spark-agent
-
-Portable AI agent for Womp applications and Kakapo scenes with model-authored JavaScript.
-
-Spark Agent uses AI SDK 7 `UIMessage` and `UIMessageChunk` as its public chat protocol. Generated
-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
-
-- 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
-
-- Node.js 22.13 or newer
-- AI SDK 7
-- `@ai-sdk/react` 4 for React clients
-
-```bash
-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.
-
-## Package entry points
-
-- `@womp/spark-agent` — browser-safe model loop, two tools, persistence hooks, and shared contracts
-- `@womp/spark-agent/browser` — native JavaScript executor and local chat transport
-- `@womp/spark-agent/capabilities` — capability composition and skill contracts
-- `@womp/spark-agent/kakapo` — direct Kakapo runtime and scene capability
-- `@womp/spark-agent/quickjs` — optional isolated JavaScript executor
-- `@womp/spark-agent/ui` — browser-safe UI message types, schemas, and model catalog
-- `@womp/spark-agent/client` — `SparkChatTransport` and HTTP client types
-- `@womp/spark-agent/server` — run service, store interfaces, executor, and development stores
-- `@womp/spark-agent/express` — mountable Express 5 router
-
-The root, `/browser`, `/ui`, `/capabilities`, and `/client` entry points do not import QuickJS,
-Kakapo, Express, or React at runtime.
-
-## Running in a host application
-
-`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.
-
-Compose only supported capabilities with `composeCapabilities({ scene, account, ... })`. Each
-capability supplies its skills and `createApi(context)`; the returned API is bound under `womp`.
-Every invocation receives a cancellation signal and an awaited `recordReceipt` hook. Capabilities
-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`.
-
-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.
-
-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.
-
-## Local frontend
-
-`LocalSparkChatTransport` accepts a host callback returning a `SparkAgentRun` from `runSparkAgent`.
-The callback receives the standard AI SDK chat request, including its messages and abort signal.
-It persists the initiating message, resolves the model and capabilities, and starts the shared loop.
-Keep ownership of the active run outside the React renderer. Local browser runs end when the page
-closes; `reconnectToStream` returns `null`.
-
-## Remote frontend
-
-```tsx
-import { useChat } from "@ai-sdk/react";
-import { SparkChatTransport } from "@womp/spark-agent/client";
-import {
-  sparkDataPartSchemas,
-  sparkMessageMetadataSchema,
-  type SparkUIMessage,
-} from "@womp/spark-agent/ui";
-
-const transport = new SparkChatTransport({ api: "/agent" });
-
-const chat = useChat<SparkUIMessage>({
-  id: conversationId,
-  messages: initialMessages,
-  transport,
-  resume: true,
-  messageMetadataSchema: sparkMessageMetadataSchema,
-  dataPartSchemas: sparkDataPartSchemas,
-});
-```
-
-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.
-
-An explicit Stop action must cancel the durable run before stopping local observation:
-
-```ts
-await transport.cancelRun(conversationId);
-await chat.stop();
-```
-
-Closing or reloading the page only detaches the SSE subscriber. It does not cancel the run.
-
-## HTTP and SSE
-
-`SparkChatTransport` hides the durable run lifecycle from `useChat`:
-
-```text
-POST /agent/conversations/:conversationId/messages
-PATCH /agent/conversations/:conversationId/settings
-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.
-
-The SSE response contains ordered persistence envelopes around standard AI SDK chunks:
-
-```ts
-type StoredSparkChunk = {
-  sequence: number;
-  conversationId: string;
-  runId: string;
-  createdAt: string;
-  chunk: SparkUIMessageChunk;
-};
-```
-
-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.
-
-## Embedding in an Express backend
-
-Spark does not call `listen()` when imported. The host owns its HTTP server and mounts the router:
-
-```ts
-import { createSparkAgentRouter } from "@womp/spark-agent/express";
-import { SparkAgentService, createSparkRunExecutor } from "@womp/spark-agent/server";
-
-const service = new SparkAgentService({
-  store,
-  executeRun: createSparkRunExecutor({
-    resolveModel,
-    createHost,
-  }),
-});
-
-app.use(
-  "/agent",
-  userAccess,
-  createSparkAgentRouter({
-    service,
-    artifactStore,
-    resolveOwnerId: (request) => request.user.id,
-  }),
-);
-```
-
-`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()`.
-
-`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.
-
-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.
-
-## Standalone development server
-
-The package includes a local server bound to `127.0.0.1:8787`:
-
-```bash
-spark-agent
-```
-
-Configure the process with:
-
-- `OPENAI_API_KEY`
-- `ANTHROPIC_API_KEY`
-- `GEMINI_API_KEY`
-- `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`)
-
-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.
-
-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.
-
-## 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. 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.
-
-## 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.
-
-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
-session and tool call, enforce quotas, and avoid passing privileged functions through the runtime
-bridge.
-
-## Validation
-
-```bash
-yarn build
-yarn typecheck
-yarn test
-yarn web:build
-```
-
-## Release procedure
-
+# @womp/spark-agent
+
+Portable AI agent for Womp applications and Kakapo scenes with model-authored JavaScript.
+
+Spark Agent uses AI SDK 7 `UIMessage` and `UIMessageChunk` as its public chat protocol. Generated
+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
+
+- 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
+
+- Node.js 22.13 or newer
+- AI SDK 7
+- `@ai-sdk/react` 4 for React clients
+
+```bash
+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.
+
+## Package entry points
+
+- `@womp/spark-agent` — browser-safe model loop, two tools, persistence hooks, and shared contracts
+- `@womp/spark-agent/browser` — native JavaScript executor and local chat transport
+- `@womp/spark-agent/capabilities` — capability composition and skill contracts
+- `@womp/spark-agent/kakapo` — direct Kakapo runtime and scene capability
+- `@womp/spark-agent/quickjs` — optional isolated JavaScript executor
+- `@womp/spark-agent/ui` — browser-safe UI message types, schemas, and model catalog
+- `@womp/spark-agent/client` — `SparkChatTransport` and HTTP client types
+- `@womp/spark-agent/server` — run service, store interfaces, executor, and development stores
+- `@womp/spark-agent/express` — mountable Express 5 router
+
+The root, `/browser`, `/ui`, `/capabilities`, and `/client` entry points do not import QuickJS,
+Kakapo, Express, or React at runtime.
+
+## Running in a host application
+
+`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.
+
+Compose only supported capabilities with `composeCapabilities({ scene, account, ... })`. Each
+capability supplies its skills and `createApi(context)`; the returned API is bound under `womp`.
+Every invocation receives a cancellation signal and an awaited `recordReceipt` hook. Capabilities
+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`.
+
+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.
+
+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.
+
+## Local frontend
+
+`LocalSparkChatTransport` accepts a host callback returning a `SparkAgentRun` from `runSparkAgent`.
+The callback receives the standard AI SDK chat request, including its messages and abort signal.
+It persists the initiating message, resolves the model and capabilities, and starts the shared loop.
+Keep ownership of the active run outside the React renderer. Local browser runs end when the page
+closes; `reconnectToStream` returns `null`.
+
+## Remote frontend
+
+```tsx
+import { useChat } from "@ai-sdk/react";
+import { SparkChatTransport } from "@womp/spark-agent/client";
+import {
+  sparkDataPartSchemas,
+  sparkMessageMetadataSchema,
+  type SparkUIMessage,
+} from "@womp/spark-agent/ui";
+
+const transport = new SparkChatTransport({ api: "/agent" });
+
+const chat = useChat<SparkUIMessage>({
+  id: conversationId,
+  messages: initialMessages,
+  transport,
+  resume: true,
+  messageMetadataSchema: sparkMessageMetadataSchema,
+  dataPartSchemas: sparkDataPartSchemas,
+});
+```
+
+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.
+
+An explicit Stop action must cancel the durable run before stopping local observation:
+
+```ts
+await transport.cancelRun(conversationId);
+await chat.stop();
+```
+
+Closing or reloading the page only detaches the SSE subscriber. It does not cancel the run.
+
+## HTTP and SSE
+
+`SparkChatTransport` hides the durable run lifecycle from `useChat`:
+
+```text
+POST /agent/conversations/:conversationId/messages
+PATCH /agent/conversations/:conversationId/settings
+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.
+
+The SSE response contains ordered persistence envelopes around standard AI SDK chunks:
+
+```ts
+type StoredSparkChunk = {
+  sequence: number;
+  conversationId: string;
+  runId: string;
+  createdAt: string;
+  chunk: SparkUIMessageChunk;
+};
+```
+
+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.
+
+## Embedding in an Express backend
+
+Spark does not call `listen()` when imported. The host owns its HTTP server and mounts the router:
+
+```ts
+import { createSparkAgentRouter } from "@womp/spark-agent/express";
+import { SparkAgentService, createSparkRunExecutor } from "@womp/spark-agent/server";
+
+const service = new SparkAgentService({
+  store,
+  executeRun: createSparkRunExecutor({
+    resolveModel,
+    createHost,
+  }),
+});
+
+app.use(
+  "/agent",
+  userAccess,
+  createSparkAgentRouter({
+    service,
+    artifactStore,
+    resolveOwnerId: (request) => request.user.id,
+  }),
+);
+```
+
+`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()`.
+
+`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.
+
+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.
+
+## Standalone development server
+
+The package includes a local server bound to `127.0.0.1:8787`:
+
+```bash
+spark-agent
+```
+
+Configure the process with:
+
+- `OPENAI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `GEMINI_API_KEY`
+- `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`)
+
+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.
+
+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.
+
+## 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. 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.
+
+## 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.
+
+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
+session and tool call, enforce quotas, and avoid passing privileged functions through the runtime
+bridge.
+
+## Validation
+
+```bash
+yarn build
+yarn typecheck
+yarn test
+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.
-
-### Publishing
-
+
+Versions follow **MAJOR.MINOR.PATCH** (for example, `4.4.0`):
+
+- **Major:** breaking changes.
+- **Minor:** backward-compatible new features.
+- **Patch:** backward-compatible bug fixes.
+
+### Publishing
+
 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.
@@ -414,23 +414,26 @@ Versions follow **MAJOR.MINOR.PATCH** (for example, `4.4.0`):
    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`.
+   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.
-
-## Layout
-
-- `src/agent.ts` — AI SDK stream and Spark tool orchestration
-- `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
-- `src/runtime.ts` — Kakapo scene connections and edit transactions
-- `src/quickjs-executor.ts` — isolated JavaScript execution and host bridge
-- `src/womp-scene-api.ts` — Womp-compatible Kakapo scene API
-- `web/src/App.tsx` — reference `useChat<SparkUIMessage>` application
+   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.
+
+## Layout
+
+- `src/agent.ts` — AI SDK stream and Spark tool orchestration
+- `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
+- `src/runtime.ts` — Kakapo scene connections and edit transactions
+- `src/quickjs-executor.ts` — isolated JavaScript execution and host bridge
+- `src/womp-scene-api.ts` — Womp-compatible Kakapo scene API
+- `web/src/App.tsx` — reference `useChat<SparkUIMessage>` application