@pi-oxide/pi-host-web 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,132 @@
+# @pi-oxide/pi-host-web
+
+WASM host for [pi-core](https://github.com/pi-oxide/pi-oxide) — a deterministic agent state machine, compiled to WebAssembly for browser and Node.js.
+
+## What it is
+
+This package exposes the `pi-core` agent loop through typed JavaScript APIs. Every function returns a strongly-typed result envelope — never throws. The TypeScript definitions are generated directly from Rust structs via [tsify](https://github.com/madonoharu/tsify).
+
+## Install
+
+```bash
+npm install @pi-oxide/pi-host-web
+```
+
+## Usage
+
+### Browser
+
+```typescript
+import init, * as wasm from "@pi-oxide/pi-host-web";
+
+// Initialize the WASM module (async, required once)
+await init();
+
+// Create an agent
+const result = wasm.createAgent({
+  system_prompt: "You are a helpful assistant.",
+  model: {
+    id: "claude-sonnet-4-20250514",
+    name: "Claude Sonnet",
+    api: "anthropic",
+    provider: "anthropic",
+    reasoning: false,
+    context_window: 200000,
+    max_tokens: 4096,
+  },
+});
+
+const handle = result.data.handle;
+
+// Send a prompt
+const step = wasm.prompt(handle, { text: "Hello!" });
+console.log(step.data.actions);
+```
+
+### Node.js
+
+```typescript
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+const require = createRequire(import.meta.url);
+const pkgDir = dirname(require.resolve("@pi-oxide/pi-host-web/package.json"));
+const wasmPath = join(pkgDir, "pi_host_web_bg.wasm");
+const wasmBytes = readFileSync(wasmPath);
+
+const pkg = await import("@pi-oxide/pi-host-web");
+pkg.initSync({ module: wasmBytes });
+
+// Now use pkg.createAgent(), pkg.prompt(), etc.
+const result = pkg.createAgent({ ... });
+```
+
+## API
+
+### Agent lifecycle
+
+| Function | Input | Returns | Description |
+|----------|-------|---------|-------------|
+| `createAgent(options)` | `AgentOptions` | `CreateAgentResult` | Creates a new agent instance |
+| `destroyAgent(handle)` | `number` | `EmptyResult` | Destroys an agent and frees its slot |
+| `reset(handle)` | `number` | `EmptyResult` | Resets agent state (keeps config) |
+| `state(handle)` | `number` | `StateResult` | Returns current agent state |
+
+### Turn loop
+
+| Function | Input | Returns | Description |
+|----------|-------|---------|-------------|
+| `prompt(handle, request)` | `number`, `PromptRequest` | `StepResult` | Starts a new turn |
+| `feedLlmChunk(handle, chunk)` | `number`, `LlmChunk` | `EventsResult` | Feeds a streaming LLM chunk |
+| `onLlmDone(handle, result)` | `number`, `LlmResult` | `StepResult` | Signals LLM stream completion |
+| `onToolDone(handle, id, payload)` | `number`, `string`, `ToolDonePayload` | `StepResult` | Reports tool execution result |
+| `onToolStarted(handle, id)` | `number`, `string` | `EventsResult` | Signals tool execution started |
+| `onToolUpdate(handle, update)` | `number`, `ToolExecutionUpdate` | `EventsResult` | Streams tool stdout/stderr |
+| `onToolCancelled(handle, id, reason)` | `number`, `string`, `CancelReason` | `StepResult` | Cancels a running tool |
+
+### Context projection
+
+| Function | Input | Returns | Description |
+|----------|-------|---------|-------------|
+| `projectContext(input)` | `ProjectionInput` | `ProjectionResult` | Projects context to fit budget |
+
+### Steering
+
+| Function | Input | Returns | Description |
+|----------|-------|---------|-------------|
+| `steer(handle, message)` | `number`, `AgentMessage` | `EventsResult` | Injects a steering message |
+| `followUp(handle, message)` | `number`, `AgentMessage` | `EmptyResult` | Appends a follow-up message |
+
+### Observability
+
+| Function | Returns | Description |
+|----------|---------|-------------|
+| `drainTraceLog()` | `string[]` | Drains and clears the Rust trace buffer |
+
+## Result envelopes
+
+Every function returns a typed result with this shape:
+
+```typescript
+interface Result<T> {
+  ok: boolean;
+  data?: T;
+  error?: {
+    code: string;
+    message: string;
+  };
+}
+```
+
+Concrete types: `CreateAgentResult`, `StepResult`, `EventsResult`, `StateResult`, `EmptyResult`, `ProjectionResult`.
+
+## Files
+
+- `pi_host_web.js` — Main ESM entry point
+- `pi_host_web_bg.wasm` — Compiled WebAssembly binary
+- `pi_host_web.d.ts` — TypeScript declarations (generated from Rust)
+
+## License
+
+MIT

package/package.json

@@ -5,20 +5,33 @@
     "Irving Ou <irving@pi-oxide.dev>"
   ],
   "description": "WASM host for pi-core. Browser FileSystem Access API, fetch(), JS event loop.",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pi-oxide/pi-oxide"
+    "url": "git+https://github.com/pi-oxide/pi-oxide.git"
   },
   "files": [
     "pi_host_web_bg.wasm",
     "pi_host_web.js",
-    "pi_host_web.d.ts"
+    "pi_host_web.d.ts",
+    "sdk/index.js",
+    "sdk/index.d.ts"
   ],
   "main": "pi_host_web.js",
   "types": "pi_host_web.d.ts",
   "sideEffects": [
     "./snippets/*"
-  ]
+  ],
+  "exports": {
+    ".": {
+      "import": "./sdk/index.js",
+      "types": "./sdk/index.d.ts"
+    },
+    "./raw": {
+      "import": "./pi_host_web.js",
+      "types": "./pi_host_web.d.ts"
+    },
+    "./package.json": "./package.json"
+  }
 }

package/pi_host_web.d.ts

@@ -16,6 +16,7 @@ export interface AgentOptions {
     tool_execution_mode?: ToolExecutionMode;
     session_id?: SessionId;
     messages?: AgentMessage[];
+    session_state?: SessionState | null;
 }
 
 export interface AgentState {
@@ -46,10 +47,9 @@ export interface AssistantMessage {
     usage: TokenUsage;
 }
 
-export interface BackgroundJobRef {
-    job_id: string;
-    tool_call_id: ToolCallId;
-    command_label: string;
+export interface BranchSummary {
+    summary: string;
+    details?: JsonSchema;
 }
 
 export interface ContextProjectionBudget {
@@ -104,6 +104,20 @@ export interface ErrorDto {
     message: string;
 }
 
+export interface EstimateTokensInput {
+    messages: AgentMessage[];
+}
+
+export interface EstimateTokensOutput {
+    tokens: number;
+}
+
+export interface EstimateTokensResult {
+    ok: boolean;
+    data?: EstimateTokensOutput;
+    error?: ErrorDto;
+}
+
 export interface EventsOutput {
     events: AgentEvent[];
 }
@@ -158,6 +172,16 @@ export interface ModelCost {
     cache_write: number;
 }
 
+export interface MoveToOutput {
+    summary_entry_id: string | null;
+}
+
+export interface MoveToResult {
+    ok: boolean;
+    data?: MoveToOutput;
+    error?: ErrorDto;
+}
+
 export interface ProjectionInput {
     system_prompt: string;
     messages: AgentMessage[];
@@ -177,6 +201,39 @@ export interface ProjectionResult {
     error?: ErrorDto;
 }
 
+export interface SessionBranchOutput {
+    entries: SessionEntry[];
+}
+
+export interface SessionBranchResult {
+    ok: boolean;
+    data?: SessionBranchOutput;
+    error?: ErrorDto;
+}
+
+export interface SessionEntry {
+    id: string;
+    parent_id?: string;
+    kind: EntryKind;
+    timestamp: number;
+}
+
+export interface SessionState {
+    entries: SessionEntry[];
+    leaf_id: string;
+    name?: string;
+}
+
+export interface SessionStateOutput {
+    state: SessionState;
+}
+
+export interface SessionStateResult {
+    ok: boolean;
+    data?: SessionStateOutput;
+    error?: ErrorDto;
+}
+
 export interface StateOutput {
     state: AgentState;
 }
@@ -285,6 +342,8 @@ export type ContentKind = "file_read" | "command_output" | "diff" | "search_resu
 
 export type ContextStrategy = { type: "keep_full" } | { type: "head"; max_chars: number } | { type: "tail"; max_chars: number } | { type: "head_tail"; head_chars: number; tail_chars: number } | { type: "drop_if_old" } | { type: "microcompacted" };
 
+export type EntryKind = ({ type: "message" } & {} & AgentMessage) | { type: "compaction"; summary: string; first_kept_entry_id: string; tokens_before: number; details?: JsonSchema } | { type: "branch_summary"; summary: string; details?: JsonSchema } | { type: "model_change"; provider: string; model_id: string } | ({ type: "thinking_level_change" } & ThinkingLevel) | { type: "custom"; custom_type: string; data?: JsonSchema };
+
 export type ExecutionMode = "parallel" | "sequential";
 
 export type JsonSchema = Value;
@@ -299,7 +358,7 @@ export type ModelName = string;
 
 export type ModelProvider = "open_ai" | "anthropic" | "google" | "ollama" | "custom";
 
-export type Phase = "idle" | "streaming" | "executing_tools" | "wait_for_input";
+export type Phase = "idle" | "streaming" | "wait_for_input";
 
 export type PromptRequest = AgentMessage | { text: string };
 
@@ -330,16 +389,28 @@ export type ToolOutputStream = "stdout" | "stderr" | "status";
 export type WaitMode = "steering" | "follow_up" | "any";
 
 
+export function appendSessionEntry(handle: number, entry: SessionEntry): EmptyResult;
+
 export function createAgent(options: AgentOptions): CreateAgentResult;
 
 export function destroyAgent(handle: number): EmptyResult;
 
-export function drainTraceLog(): string[];
+export function estimateTokens(input: EstimateTokensInput): EstimateTokensResult;
+
+export function estimateTokensForText(text: string): EstimateTokensResult;
+
+export function fallbackStrategy(tool_name: string): ContextStrategy;
 
 export function feedLlmChunk(handle: number, chunk: LlmChunk): EventsResult;
 
 export function followUp(handle: number, message: AgentMessage): EmptyResult;
 
+export function getSessionBranch(handle: number): SessionBranchResult;
+
+export function getSessionState(handle: number): SessionStateResult;
+
+export function moveTo(handle: number, target_id: string, summary?: BranchSummary | null): MoveToResult;
+
 export function onLlmDone(handle: number, result: LlmResult): StepResult;
 
 export function onToolCancelled(handle: number, tool_call_id: string, reason: CancelReason): StepResult;
@@ -356,6 +427,10 @@ export function prompt(handle: number, prompt: PromptRequest): StepResult;
 
 export function reset(handle: number): EmptyResult;
 
+export function setLogLevel(level: string): void;
+
+export function setSessionState(handle: number, state: SessionState): EmptyResult;
+
 export function state(handle: number): StateResult;
 
 export function steer(handle: number, message: AgentMessage): EventsResult;
@@ -364,11 +439,17 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly appendSessionEntry: (a: number, b: any) => any;
     readonly createAgent: (a: any) => any;
     readonly destroyAgent: (a: number) => any;
-    readonly drainTraceLog: () => [number, number];
+    readonly estimateTokens: (a: any) => any;
+    readonly estimateTokensForText: (a: number, b: number) => any;
+    readonly fallbackStrategy: (a: number, b: number) => any;
     readonly feedLlmChunk: (a: number, b: any) => any;
     readonly followUp: (a: number, b: any) => any;
+    readonly getSessionBranch: (a: number) => any;
+    readonly getSessionState: (a: number) => any;
+    readonly moveTo: (a: number, b: number, c: number, d: number) => any;
     readonly onLlmDone: (a: number, b: any) => any;
     readonly onToolCancelled: (a: number, b: number, c: number, d: any) => any;
     readonly onToolDone: (a: number, b: number, c: number, d: any) => any;
@@ -377,6 +458,8 @@ export interface InitOutput {
     readonly projectContext: (a: any) => any;
     readonly prompt: (a: number, b: any) => any;
     readonly reset: (a: number) => any;
+    readonly setLogLevel: (a: number, b: number) => void;
+    readonly setSessionState: (a: number, b: any) => any;
     readonly state: (a: number) => any;
     readonly steer: (a: number, b: any) => any;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
@@ -385,7 +468,6 @@ export interface InitOutput {
     readonly __wbindgen_exn_store: (a: number) => void;
     readonly __externref_table_alloc: () => number;
     readonly __wbindgen_externrefs: WebAssembly.Table;
-    readonly __externref_drop_slice: (a: number, b: number) => void;
     readonly __wbindgen_start: () => void;
 }
 

package/pi_host_web.js

@@ -1,5 +1,15 @@
 /* @ts-self-types="./pi_host_web.d.ts" */
 
+/**
+ * @param {number} handle
+ * @param {SessionEntry} entry
+ * @returns {EmptyResult}
+ */
+export function appendSessionEntry(handle, entry) {
+    const ret = wasm.appendSessionEntry(handle, entry);
+    return ret;
+}
+
 /**
  * @param {AgentOptions} options
  * @returns {CreateAgentResult}
@@ -19,13 +29,34 @@ export function destroyAgent(handle) {
 }
 
 /**
- * @returns {string[]}
+ * @param {EstimateTokensInput} input
+ * @returns {EstimateTokensResult}
  */
-export function drainTraceLog() {
-    const ret = wasm.drainTraceLog();
-    var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]).slice();
-    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
-    return v1;
+export function estimateTokens(input) {
+    const ret = wasm.estimateTokens(input);
+    return ret;
+}
+
+/**
+ * @param {string} text
+ * @returns {EstimateTokensResult}
+ */
+export function estimateTokensForText(text) {
+    const ptr0 = passStringToWasm0(text, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.estimateTokensForText(ptr0, len0);
+    return ret;
+}
+
+/**
+ * @param {string} tool_name
+ * @returns {ContextStrategy}
+ */
+export function fallbackStrategy(tool_name) {
+    const ptr0 = passStringToWasm0(tool_name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.fallbackStrategy(ptr0, len0);
+    return ret;
 }
 
 /**
@@ -48,6 +79,37 @@ export function followUp(handle, message) {
     return ret;
 }
 
+/**
+ * @param {number} handle
+ * @returns {SessionBranchResult}
+ */
+export function getSessionBranch(handle) {
+    const ret = wasm.getSessionBranch(handle);
+    return ret;
+}
+
+/**
+ * @param {number} handle
+ * @returns {SessionStateResult}
+ */
+export function getSessionState(handle) {
+    const ret = wasm.getSessionState(handle);
+    return ret;
+}
+
+/**
+ * @param {number} handle
+ * @param {string} target_id
+ * @param {BranchSummary | null} [summary]
+ * @returns {MoveToResult}
+ */
+export function moveTo(handle, target_id, summary) {
+    const ptr0 = passStringToWasm0(target_id, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.moveTo(handle, ptr0, len0, isLikeNone(summary) ? 0 : addToExternrefTable0(summary));
+    return ret;
+}
+
 /**
  * @param {number} handle
  * @param {LlmResult} result
@@ -134,6 +196,25 @@ export function reset(handle) {
     return ret;
 }
 
+/**
+ * @param {string} level
+ */
+export function setLogLevel(level) {
+    const ptr0 = passStringToWasm0(level, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    wasm.setLogLevel(ptr0, len0);
+}
+
+/**
+ * @param {number} handle
+ * @param {SessionState} state
+ * @returns {EmptyResult}
+ */
+export function setSessionState(handle, state) {
+    const ret = wasm.setSessionState(handle, state);
+    return ret;
+}
+
 /**
  * @param {number} handle
  * @returns {StateResult}
@@ -181,6 +262,47 @@ function __wbg_get_imports() {
                 wasm.__wbindgen_free(deferred0_0, deferred0_1, 1);
             }
         },
+        __wbg_log_0c201ade58bb55e1: function(arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7) {
+            let deferred0_0;
+            let deferred0_1;
+            try {
+                deferred0_0 = arg0;
+                deferred0_1 = arg1;
+                console.log(getStringFromWasm0(arg0, arg1), getStringFromWasm0(arg2, arg3), getStringFromWasm0(arg4, arg5), getStringFromWasm0(arg6, arg7));
+            } finally {
+                wasm.__wbindgen_free(deferred0_0, deferred0_1, 1);
+            }
+        },
+        __wbg_log_ce2c4456b290c5e7: function(arg0, arg1) {
+            let deferred0_0;
+            let deferred0_1;
+            try {
+                deferred0_0 = arg0;
+                deferred0_1 = arg1;
+                console.log(getStringFromWasm0(arg0, arg1));
+            } finally {
+                wasm.__wbindgen_free(deferred0_0, deferred0_1, 1);
+            }
+        },
+        __wbg_mark_b4d943f3bc2d2404: function(arg0, arg1) {
+            performance.mark(getStringFromWasm0(arg0, arg1));
+        },
+        __wbg_measure_84362959e621a2c1: function() { return handleError(function (arg0, arg1, arg2, arg3) {
+            let deferred0_0;
+            let deferred0_1;
+            let deferred1_0;
+            let deferred1_1;
+            try {
+                deferred0_0 = arg0;
+                deferred0_1 = arg1;
+                deferred1_0 = arg2;
+                deferred1_1 = arg3;
+                performance.measure(getStringFromWasm0(arg0, arg1), getStringFromWasm0(arg2, arg3));
+            } finally {
+                wasm.__wbindgen_free(deferred0_0, deferred0_1, 1);
+                wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+            }
+        }, arguments); },
         __wbg_new_227d7c05414eb861: function() {
             const ret = new Error();
             return ret;
@@ -200,11 +322,6 @@ function __wbg_get_imports() {
             const ret = JSON.stringify(arg0);
             return ret;
         }, arguments); },
-        __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Ref(String) -> Externref`.
-            const ret = getStringFromWasm0(arg0, arg1);
-            return ret;
-        },
         __wbindgen_init_externref_table: function() {
             const table = wasm.__wbindgen_externrefs;
             const offset = table.grow(4);
@@ -227,17 +344,6 @@ function addToExternrefTable0(obj) {
     return idx;
 }
 
-function getArrayJsValueFromWasm0(ptr, len) {
-    ptr = ptr >>> 0;
-    const mem = getDataViewMemory0();
-    const result = [];
-    for (let i = ptr; i < ptr + 4 * len; i += 4) {
-        result.push(wasm.__wbindgen_externrefs.get(mem.getUint32(i, true)));
-    }
-    wasm.__externref_drop_slice(ptr, len);
-    return result;
-}
-
 let cachedDataViewMemory0 = null;
 function getDataViewMemory0() {
     if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) {

package/sdk/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * High-level JS SDK for @pi-oxide/pi-host-web.
+ *
+ * Re-exports all raw types so consumers never need to import from ./raw.
+ */
+
+export * from "../pi_host_web.js";
+
+export declare function ensureInit(): Promise<void>;
+
+export declare function toolResult(
+  text: string,
+  opts?: { terminate?: boolean }
+): { content: Array<{ type: "text"; text: string }>; terminate?: boolean };
+
+export declare function toolError(
+  code: string,
+  message: string
+): { error: { code: string; message: string } };
+
+export interface LlmStream {
+  chunks: AsyncIterable<LlmChunk>;
+  result: Promise<LlmResult>;
+}
+
+export interface LlmProvider {
+  call(context: LlmContext): Promise<LlmStream> | LlmStream;
+}
+
+export type ToolMap = Record<
+  string,
+  (call: ToolCall) => Promise<ToolResult> | ToolResult
+>;
+
+export interface AgentRunConfig {
+  llm: LlmProvider;
+  tools: ToolMap;
+  onEvent?: (event: AgentEvent) => void;
+}
+
+export declare class Agent {
+  static create(options: AgentOptions): Promise<Agent>;
+  run(promptText: string, config: AgentRunConfig): Promise<AgentAction>;
+  reset(): void;
+  state(): AgentState;
+  getSessionState(): SessionState;
+  setSessionState(sessionState: SessionState): void;
+  steer(message: AgentMessage): AgentEvent[];
+  followUp(message: AgentMessage): void;
+  destroy(): void;
+}

package/sdk/index.js

@@ -0,0 +1,216 @@
+/**
+ * High-level JS SDK for @pi-oxide/pi-host-web.
+ *
+ * Hides WASM loading, numeric handles, and the agent drive-loop.
+ * Supports streaming LLM responses and full agent lifecycle.
+ *
+ * Import from the package root:
+ *   import { Agent, toolResult } from "@pi-oxide/pi-host-web";
+ */
+
+import {
+  createAgent,
+  destroyAgent,
+  feedLlmChunk,
+  followUp,
+  getSessionState,
+  initSync,
+  onLlmDone,
+  onToolCancelled,
+  onToolDone,
+  onToolStarted,
+  projectContext,
+  prompt,
+  reset,
+  setSessionState,
+  state,
+  steer,
+  default as init,
+} from "../pi_host_web.js";
+
+export { projectContext };
+
+let initialized = false;
+
+/** Ensure the WASM module is loaded. Safe to call multiple times. */
+export async function ensureInit() {
+  if (initialized) return;
+  if (typeof window !== "undefined") {
+    await init();
+  } else {
+    const { readFileSync } = await import("node:fs");
+    const bytes = readFileSync(
+      new URL("../pi_host_web_bg.wasm", import.meta.url)
+    );
+    initSync({ module: bytes });
+  }
+  initialized = true;
+}
+
+class HostError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "HostError";
+  }
+}
+
+function unwrap(result) {
+  if (!result.ok) {
+    throw new HostError(result.error.code, result.error.message);
+  }
+  return result.data;
+}
+
+/** Build a successful tool result payload. */
+export function toolResult(text, opts = {}) {
+  const payload = {
+    content: [{ type: "text", text }],
+  };
+  if (opts.terminate) {
+    payload.terminate = true;
+  }
+  return payload;
+}
+
+/** Build an error tool result payload. */
+export function toolError(code, message) {
+  return { error: { code, message } };
+}
+
+/**
+ * High-level agent that manages the WASM handle and drive-loop.
+ *
+ * Usage:
+ *   const agent = await Agent.create(options);
+ *   const finalAction = await agent.run("hello", { llm, tools, onEvent });
+ *   agent.destroy();
+ */
+export class Agent {
+  /** @type {number} */
+  #handle;
+
+  constructor(handle) {
+    this.#handle = handle;
+  }
+
+  /** Create a new agent. Loads WASM on first call automatically. */
+  static async create(options) {
+    await ensureInit();
+    const result = unwrap(createAgent(options));
+    return new Agent(result.handle);
+  }
+
+  /**
+   * Run one user prompt through the full turn loop.
+   *
+   * @param {string} promptText
+   * @param {object} config
+   * @param {LlmProvider} config.llm
+   * @param {Record<string, (call: ToolCall) => Promise<ToolResult> | ToolResult>} config.tools
+   * @param {(event: AgentEvent) => void} [config.onEvent]
+   * @returns {Promise<AgentAction>} terminal action (finished or wait_for_input)
+   */
+  async run(promptText, config) {
+    let step = unwrap(prompt(this.#handle, { text: promptText }));
+    for (const event of step.events) {
+      config.onEvent?.(event);
+    }
+
+    while (true) {
+      let actions = step.actions ?? [];
+      if (actions.length === 0) {
+        return { type: "finished", messages: [] };
+      }
+
+      for (const action of actions) {
+        switch (action.type) {
+          case "stream_llm": {
+            const stream = await config.llm.call(action.context);
+            for await (const chunk of stream.chunks) {
+              const ev = unwrap(feedLlmChunk(this.#handle, chunk));
+              for (const e of ev.events) config.onEvent?.(e);
+            }
+            const result = await stream.result;
+            step = unwrap(onLlmDone(this.#handle, result));
+            for (const e of step.events) config.onEvent?.(e);
+            break;
+          }
+
+          case "execute_tools": {
+            for (const call of action.calls) {
+              const started = unwrap(onToolStarted(this.#handle, call.id));
+              for (const e of started.events) config.onEvent?.(e);
+
+              const handler = config.tools[call.name];
+              let result;
+              if (handler) {
+                result = await handler(call);
+              } else {
+                result = toolError("unknown_tool", `No handler for ${call.name}`);
+              }
+              step = unwrap(onToolDone(this.#handle, call.id, result));
+              for (const e of step.events) config.onEvent?.(e);
+            }
+            break;
+          }
+
+          case "cancel_tools": {
+            for (const id of action.tool_call_ids) {
+              step = unwrap(
+                onToolCancelled(this.#handle, id, action.reason)
+              );
+              for (const e of step.events) config.onEvent?.(e);
+            }
+            break;
+          }
+
+          case "finished":
+            return action;
+
+          case "wait_for_input":
+            return action;
+
+          default:
+            return action;
+        }
+      }
+    }
+  }
+
+  /** Reset agent state (clear messages, return to idle). */
+  reset() {
+    unwrap(reset(this.#handle));
+  }
+
+  /** Get public agent state. */
+  state() {
+    return unwrap(state(this.#handle));
+  }
+
+  /** Get session state for persistence. */
+  getSessionState() {
+    return unwrap(getSessionState(this.#handle));
+  }
+
+  /** Set session state (e.g. after restoring from storage). */
+  setSessionState(sessionState) {
+    unwrap(setSessionState(this.#handle, sessionState));
+  }
+
+  /** Send a steering message mid-turn. */
+  steer(message) {
+    const out = unwrap(steer(this.#handle, message));
+    return out.events;
+  }
+
+  /** Queue a follow-up message. */
+  followUp(message) {
+    unwrap(followUp(this.#handle, message));
+  }
+
+  /** Destroy the underlying WASM handle. */
+  destroy() {
+    destroyAgent(this.#handle);
+  }
+}