@womp/spark-agent 3.0.0 → 3.0.2

package/README.md

@@ -1,372 +1,372 @@
-# @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
-```
-
-## 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.
-
-Before each model request Spark applies an estimated input budget (`maxInputTokens`, default 64,000).
-It first removes duplicate skill bodies and execution observations, then abbreviates older skill reads
-while retaining the latest workflow/reference pair. The agent must read an abbreviated skill again
-before using its API. Older completed scripts can be shortened only when their committed receipts and
-results remain available and their inputs are not tied to provider reasoning/signatures. Requests,
-tool pairs, targets, artifacts, receipts, errors, and unresolved work remain in context; persisted
-history is never shortened. If this cannot fit, the run returns `incomplete` with `context-limit` and
-an actionable explanation, without another model request or automatic replay.
-
-When older successful execution results contain images, their binary content can be omitted from model
-input while preserving artifact references, receipts, and observations. The latest visual result,
-user-provided media, failed/uncertain results, and provider-owned content remain intact. The agent can
-inspect an older artifact again with `emitImage` or `emitFile`; stored history retains the full result.
-Call metadata copied by the SDK onto local tool results is preserved during this trimming; it does not
-prevent compaction of the host-produced image bytes. Original model calls and signatures are unchanged.
-
-Token sizing is approximate (UTF-8 text bytes / 3 plus an 8,192-token allowance per image/file and
-2,048 for tool schemas/framing). This is an application input budget, not provider capacity metadata.
-Hosts should choose it alongside the selected model's output budget and verify their deployed models;
-the estimate cannot guarantee a provider accepts every document or image size.
-
-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
-GET  /agent/runs/:runId/stream?after=0
-POST /agent/runs/:runId/cancel
-```
-
-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.
-
-### 0.3.1 context defaults
-
-- The default input context budget is now 128,000 estimated tokens. Hosts can still
-  set `maxInputTokens` explicitly; this budget does not change the provider's context limit.
-- Images, including images in tool results, use a 512-token estimate instead of the
-  general 8,192-token file allowance. Encoded media bytes remain excluded from text
-  estimates. Token accounting is heuristic; no API or storage migration is required.
-
-### 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
+```
+
+## 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.
+
+Before each model request Spark applies an estimated input budget (`maxInputTokens`, default 64,000).
+It first removes duplicate skill bodies and execution observations, then abbreviates older skill reads
+while retaining the latest workflow/reference pair. The agent must read an abbreviated skill again
+before using its API. Older completed scripts can be shortened only when their committed receipts and
+results remain available and their inputs are not tied to provider reasoning/signatures. Requests,
+tool pairs, targets, artifacts, receipts, errors, and unresolved work remain in context; persisted
+history is never shortened. If this cannot fit, the run returns `incomplete` with `context-limit` and
+an actionable explanation, without another model request or automatic replay.
+
+When older successful execution results contain images, their binary content can be omitted from model
+input while preserving artifact references, receipts, and observations. The latest visual result,
+user-provided media, failed/uncertain results, and provider-owned content remain intact. The agent can
+inspect an older artifact again with `emitImage` or `emitFile`; stored history retains the full result.
+Call metadata copied by the SDK onto local tool results is preserved during this trimming; it does not
+prevent compaction of the host-produced image bytes. Original model calls and signatures are unchanged.
+
+Token sizing is approximate (UTF-8 text bytes / 3 plus an 8,192-token allowance per image/file and
+2,048 for tool schemas/framing). This is an application input budget, not provider capacity metadata.
+Hosts should choose it alongside the selected model's output budget and verify their deployed models;
+the estimate cannot guarantee a provider accepts every document or image size.
+
+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
+GET  /agent/runs/:runId/stream?after=0
+POST /agent/runs/:runId/cancel
+```
+
+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.
+
+### 0.3.1 context defaults
+
+- The default input context budget is now 128,000 estimated tokens. Hosts can still
+  set `maxInputTokens` explicitly; this budget does not change the provider's context limit.
+- Images, including images in tool results, use a 512-token estimate instead of the
+  general 8,192-token file allowance. Encoded media bytes remain excluded from text
+  estimates. Token accounting is heuristic; no API or storage migration is required.
+
+### 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