@womp/spark-agent 5.2.2 → 5.3.0

package/README.md

@@ -1,423 +1,430 @@
-# @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]`.
-
-## 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`.
-
-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
-
-Releases use a manual package publication; no separate release service is required.
-
-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. 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
+
+### 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]`.
+
+## 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
+
+Releases use a manual package publication; no separate release service is required.
+
+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. 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