@womp/spark-agent 4.2.2 → 4.4.0

package/README.md

@@ -1,457 +1,457 @@
-# @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
-
-- 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]`.
-
-## 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.
-
-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.
-Provider-reported usage and cost tracking are unchanged.
-
-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.
-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.
-
-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 do this without a database migration.
-
-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()`.
-
-## 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`.
-
-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. Full operation reconciliation and run continuation
-are still being integrated. 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.
-
-This development branch currently installs `kakapo-sdk` from the sibling checkout. Run `yarn build`
-in `../kakapo-sdk` before installing Spark dependencies. A registry version must replace this local
-dependency before release; no new package has been published by this migration.
-
-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.
-
-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
-
-Releases use a manual package publication; no separate release service is required.
-
-### Migration to 0.3
-
-- The package root is browser-safe. Import `KakapoRuntime`, `createWompSceneApi`, and its enums
-  from `/kakapo`, and `QuickJSJavaScriptExecutor` from `/quickjs`.
-- `runSparkAgent` takes the host's selected model, executor, capability composition, artifact
-  resolver, and persistence hooks. The host owns connection setup and disposal. The model sees
-  only `read_skill` and `execute_javascript`; domain methods live under the supplied `womp` APIs.
-- Replace fixed scene/screenshot tool history with the host's history adapter. Use
-  `convertSparkMessages` when rebuilding model input from current Spark UI messages so artifact
-  references become model-visible content. Preserve old records; do not replay historical tools.
-- Custom server executors receive `uiMessages` and convert them using their actual capability
-  tools. `SparkRunExecutionContext.modelMessages` has been removed.
-- Custom JavaScript executors must honor cancellation and host-owned user waits. Callback-based
-  scene edits and artifact references work with both the native and QuickJS executors.
-
-### 4.1.0
-
-- `emitImage(artifact, { inspect: false })` displays an image without adding its bytes to model input, including restored history. Inspection remains the default.
-- Generation instructions use completed outputs directly and avoid redundant listing or emission; explicit inspection and follow-up imports remain supported.
-- Streamed tool labels are emitted only after their label field is complete. Hosts can consume `data-tool-input-label` while the rest of the input streams.
-- Server cancellation waits for active execution to settle before reporting its terminal state.
-- Includes the latest geometry material, scalar-port, and primitive improvements from main.
-
-### 4.2.2
-
-The published 4.2.1 was packed from the 4.2.0 sources and differs from 4.2.0 only in its version
-number, so none of the changes below are in it. Use 4.2.2.
-
-Compatible: both additions are optional, and a host that sets neither behaves as before except that a
-run whose progress cannot be stored now ends instead of staying `running`.
-
-- A run whose stream chunk, `running` status or ending cannot be stored ends `failed` with a sentence
-  instead of staying `running` until a restart. The final status and the conversation release are
-  retried in the background for about five minutes; a message or a Stop for that conversation stores
-  the ending at once.
-- `SparkAgentServiceOptions.endOrphanedRuns` (default `false`): a message or a Stop ends an unfinished
-  active run that no execution in this process holds, with "This run stopped unexpectedly and could
-  not be finished." Turn it on only when one process owns the store; on a shared store it would end
-  another process's live runs.
-- `SparkAgentStore.releaseActiveRun(conversationId, runId, updatedAt)` (optional): clears the active
-  run only while it still names that run. The memory and SQLite stores implement it. A store without
-  it has the read-and-save release serialised against the service's own submits, so a late retry
-  cannot overwrite a newer message.
-
-### 4.2.0
-
-Incompatible: a color that can only be a 0-1 one is now refused where it used to be stored as
-near-black, and the `scene-editing` skill payload changed. Hosts that pin the skill surface in a
-fixture must regenerate it.
-
-- Model-facing colors state their domain in the declared parameter name: `nodeSetColor`,
-  `materialSetColor`, `materialSetSecondaryColor`, `materialSetSubsurfaceColor` and
-  `setBackgroundColor` take `rgb255`, and the internal type is `Color255`. The `scene-editing` skill
-  version is 30.
-- A color whose every component is strictly between 0 and 1 and none an integer throws, naming the
-  0-255 conversion (`{r:0.2, g:0.4, b:0.6}` → "use `{r:51, g:102, b:153}` … or `{r:0, g:0, b:0}` for
-  black"). Nothing is auto-scaled: `{r:1, g:0, b:0}`, `{r:0, g:0, b:0}`, `{r:0.5, g:0, b:0}` and
-  every 0-255 color write exactly as before.
-- `scene.health` accepts the object ids `scene.read()` publishes, including `0`; a value that is not
-  an id is refused with a sentence naming it instead of a serialized schema error. Ids belonging to
-  no Area (the root, a root-level Group, a Light) are dropped and reported rather than making the
-  whole reading `unverified`.
-- A tool result can no longer cost a turn. Geometry diagnostics quote a source line once per line
-  and cap at 5 diagnostics and 4 KiB; the `execute_javascript` envelope bounds the error to 8 KiB and
-  the receipts to a 1 MiB model input, always as valid JSON. Only model input is bounded —
-  `persistence.afterToolCall`, the UI stream and the host's own receipts keep the original object.
-- A scene-health receipt keeps its totals, limits and overflow flags whole and bounds the per-Area
-  rows to 8, affected and overflowing Areas first, naming the omission in `reason`. Health read for a
-  decision (`hasGeometryOverflow`, `hasSceneResourcePressure`, `options.onHealth`) still sees every
-  row, so no repair decision changes. A consumer fixture that recorded a receipt with more than 8
-  Areas will differ.
-- `operations.generate` keeps a host's own cancellation message on a stopped generation instead of
-  replacing it with the bare abort reason.
-
-### Publishing
-
-1. Choose an unused package version after checking `npm view @womp/spark-agent versions --json`.
-   Update `package.json` and record public API changes and migration notes. Use a new minor version
-   for incompatible changes while the package is below 1.0.
-2. On a supported Node version, run `yarn install --frozen-lockfile`, `yarn typecheck`, `yarn test`,
-   and `yarn web:build`. Do not bypass dependency engine checks. Commit the release changes and
-   record the commit used to build the package.
-3. Run `yarn pack --filename spark-agent-release.tgz`. Inspect the archive contents and install
-   that archive in the consuming application. Verify packaged declarations and skills, browser
-   import boundaries, the production build, and the applicable integration cases without source
-   aliases. Keep the archive outside Git and do not rebuild or change it after verification.
-4. Publish the verified archive with `npm publish ./spark-agent-release.tgz --access public`.
-   If the response is uncertain, inspect the registry's version and integrity before retrying.
-   Verify the published version and archive integrity, then tag the recorded commit as `v<version>`
-   and push the release commit and tag. An already published version cannot be replaced; corrections
-   need a new version.
-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
+# @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
+
+- 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]`.
+
+## 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.
+
+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.
+Provider-reported usage and cost tracking are unchanged.
+
+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.
+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.
+
+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 do this without a database migration.
+
+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()`.
+
+## 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`.
+
+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. Full operation reconciliation and run continuation
+are still being integrated. 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.
+
+This development branch currently installs `kakapo-sdk` from the sibling checkout. Run `yarn build`
+in `../kakapo-sdk` before installing Spark dependencies. A registry version must replace this local
+dependency before release; no new package has been published by this migration.
+
+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.
+
+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
+
+Releases use a manual package publication; no separate release service is required.
+
+### Migration to 0.3
+
+- The package root is browser-safe. Import `KakapoRuntime`, `createWompSceneApi`, and its enums
+  from `/kakapo`, and `QuickJSJavaScriptExecutor` from `/quickjs`.
+- `runSparkAgent` takes the host's selected model, executor, capability composition, artifact
+  resolver, and persistence hooks. The host owns connection setup and disposal. The model sees
+  only `read_skill` and `execute_javascript`; domain methods live under the supplied `womp` APIs.
+- Replace fixed scene/screenshot tool history with the host's history adapter. Use
+  `convertSparkMessages` when rebuilding model input from current Spark UI messages so artifact
+  references become model-visible content. Preserve old records; do not replay historical tools.
+- Custom server executors receive `uiMessages` and convert them using their actual capability
+  tools. `SparkRunExecutionContext.modelMessages` has been removed.
+- Custom JavaScript executors must honor cancellation and host-owned user waits. Callback-based
+  scene edits and artifact references work with both the native and QuickJS executors.
+
+### 4.1.0
+
+- `emitImage(artifact, { inspect: false })` displays an image without adding its bytes to model input, including restored history. Inspection remains the default.
+- Generation instructions use completed outputs directly and avoid redundant listing or emission; explicit inspection and follow-up imports remain supported.
+- Streamed tool labels are emitted only after their label field is complete. Hosts can consume `data-tool-input-label` while the rest of the input streams.
+- Server cancellation waits for active execution to settle before reporting its terminal state.
+- Includes the latest geometry material, scalar-port, and primitive improvements from main.
+
+### 4.2.2
+
+The published 4.2.1 was packed from the 4.2.0 sources and differs from 4.2.0 only in its version
+number, so none of the changes below are in it. Use 4.2.2.
+
+Compatible: both additions are optional, and a host that sets neither behaves as before except that a
+run whose progress cannot be stored now ends instead of staying `running`.
+
+- A run whose stream chunk, `running` status or ending cannot be stored ends `failed` with a sentence
+  instead of staying `running` until a restart. The final status and the conversation release are
+  retried in the background for about five minutes; a message or a Stop for that conversation stores
+  the ending at once.
+- `SparkAgentServiceOptions.endOrphanedRuns` (default `false`): a message or a Stop ends an unfinished
+  active run that no execution in this process holds, with "This run stopped unexpectedly and could
+  not be finished." Turn it on only when one process owns the store; on a shared store it would end
+  another process's live runs.
+- `SparkAgentStore.releaseActiveRun(conversationId, runId, updatedAt)` (optional): clears the active
+  run only while it still names that run. The memory and SQLite stores implement it. A store without
+  it has the read-and-save release serialised against the service's own submits, so a late retry
+  cannot overwrite a newer message.
+
+### 4.2.0
+
+Incompatible: a color that can only be a 0-1 one is now refused where it used to be stored as
+near-black, and the `scene-editing` skill payload changed. Hosts that pin the skill surface in a
+fixture must regenerate it.
+
+- Model-facing colors state their domain in the declared parameter name: `nodeSetColor`,
+  `materialSetColor`, `materialSetSecondaryColor`, `materialSetSubsurfaceColor` and
+  `setBackgroundColor` take `rgb255`, and the internal type is `Color255`. The `scene-editing` skill
+  version is 30.
+- A color whose every component is strictly between 0 and 1 and none an integer throws, naming the
+  0-255 conversion (`{r:0.2, g:0.4, b:0.6}` → "use `{r:51, g:102, b:153}` … or `{r:0, g:0, b:0}` for
+  black"). Nothing is auto-scaled: `{r:1, g:0, b:0}`, `{r:0, g:0, b:0}`, `{r:0.5, g:0, b:0}` and
+  every 0-255 color write exactly as before.
+- `scene.health` accepts the object ids `scene.read()` publishes, including `0`; a value that is not
+  an id is refused with a sentence naming it instead of a serialized schema error. Ids belonging to
+  no Area (the root, a root-level Group, a Light) are dropped and reported rather than making the
+  whole reading `unverified`.
+- A tool result can no longer cost a turn. Geometry diagnostics quote a source line once per line
+  and cap at 5 diagnostics and 4 KiB; the `execute_javascript` envelope bounds the error to 8 KiB and
+  the receipts to a 1 MiB model input, always as valid JSON. Only model input is bounded —
+  `persistence.afterToolCall`, the UI stream and the host's own receipts keep the original object.
+- A scene-health receipt keeps its totals, limits and overflow flags whole and bounds the per-Area
+  rows to 8, affected and overflowing Areas first, naming the omission in `reason`. Health read for a
+  decision (`hasGeometryOverflow`, `hasSceneResourcePressure`, `options.onHealth`) still sees every
+  row, so no repair decision changes. A consumer fixture that recorded a receipt with more than 8
+  Areas will differ.
+- `operations.generate` keeps a host's own cancellation message on a stopped generation instead of
+  replacing it with the bare abort reason.
+
+### Publishing
+
+1. Choose an unused package version after checking `npm view @womp/spark-agent versions --json`.
+   Update `package.json` and record public API changes and migration notes. Use a new minor version
+   for incompatible changes while the package is below 1.0.
+2. On a supported Node version, run `yarn install --frozen-lockfile`, `yarn typecheck`, `yarn test`,
+   and `yarn web:build`. Do not bypass dependency engine checks. Commit the release changes and
+   record the commit used to build the package.
+3. Run `yarn pack --filename spark-agent-release.tgz`. Inspect the archive contents and install
+   that archive in the consuming application. Verify packaged declarations and skills, browser
+   import boundaries, the production build, and the applicable integration cases without source
+   aliases. Keep the archive outside Git and do not rebuild or change it after verification.
+4. Publish the verified archive with `npm publish ./spark-agent-release.tgz --access public`.
+   If the response is uncertain, inspect the registry's version and integrity before retrying.
+   Verify the published version and archive integrity, then tag the recorded commit as `v<version>`
+   and push the release commit and tag. An already published version cannot be replaced; corrections
+   need a new version.
+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