@womp/spark-agent

Local browser workspace for controlling Kakapo with model-authored JavaScript.

The agent runs in the tab, calls OpenAI through the AI SDK, and connects directly to Kakapo through @womp/kakapo-sdk. Scene access is restricted to a private build root. Top-level createNode() calls are automatically parented to that root, and the native screenshot tool frames the build for visual inspection.

Run

Install the reusable core from npm:

yarn add @womp/spark-agent @womp/kakapo-sdk

The package entrypoint exports only the environment-neutral agent core. It does not import React, Vite, browser storage, or the browser JavaScript executor.

Browser test application

Requirements:

• Node.js 20 or newer
• D:/Womp/kakapo/kakapo_app.exe listening on ws://127.0.0.1:5502
• VITE_OPENAI_API_KEY or VITE_ANTHROPIC_API_KEY in the repository root .env, or a key entered in Runtime settings

yarn install
yarn dev

Open http://127.0.0.1:5173.

Browser workspace

The workspace provides:

• local threads with search, fork, and delete actions;
• model and reasoning controls;
• pasted and uploaded reference images;
• streamed assistant messages and reasoning summaries;
• formatted JavaScript execution and result traces;
• native Kakapo screenshots inline with the execution timeline.

Threads and images are stored in IndexedDB. Model and runtime preferences use browser storage. An API key entered in Runtime settings is kept in session storage and is not stored with threads.

Core package

The environment-neutral agent is under src/. It accepts a language model, a scene runtime, a JavaScript executor, byte-based images, and an event sink. The browser supplies those dependencies in web/src/api.ts; a server can supply its own credentials, isolated executor, and durable event sink without importing React or browser storage.

Agent execution

The model has two tools:

• executeJavaScript runs code against the scoped @womp/kakapo-sdk facade;
• screenshot moves Kakapo's native camera, frames a target bounding box, and returns the rendered image to the model.

Node, material, transform, inspection, and refresh operations are SDK calls made from JavaScript. The private build root is runtime state and is not exposed as a generated-code variable.

Validation

yarn build
yarn typecheck
yarn lint
yarn test
yarn web:build

Layout

• src/agent.ts — environment-neutral model loop and tool orchestration
• src/runtime.ts — Kakapo scene runtime and atomic JavaScript transactions
• src/womp-scene-api.ts — Womp-compatible scene API
• src/prompt.ts — JavaScript agent instructions and SDK reference
• src/coordinates.ts — Womp basis, units, rotations, and goop conversion
• web/src/api.ts — browser model, image, runtime, and event adapters
• web/src/browser-executor.ts — local generated-JavaScript executor
• web/src/App.tsx — local chat, persistence, traces, screenshots, and streaming UI