# nanocode-wasm

The nanocode SDK compiled to one WebAssembly module, with a TypeScript host for Workers, Node, Deno, and browsers.

`nanocode-wasm` runs the same agent, durability, turn, and event logic as the Rust SDK. The host supplies everything platform-specific through narrow interfaces: SQLite transactions, model HTTPS requests, host tools, and remote Code Mode frames. The package has no Cloudflare types and checks against the standard web platform types only.

## Install

The package is not on npm. Depend on it from git or a `file:` link, then compile `dist/nanocode_wasm.wasm` with `npm run build`. The build requires Rust 1.97 or newer, the `wasm32-unknown-unknown` target, and Node.js 22.18 or newer.

The build reads the SDK from a `../nanocodex` sibling checkout. `sdk-revision.json` in the package records the SDK revision to check out there.

```bash
# 1. Check out the SDK as the nanocodex sibling, then the package
git clone https://github.com/gakonst/nanocode nanocodex
git clone https://github.com/gakonst/nanocode-wasm

# 2. Build the WebAssembly module into dist/nanocode_wasm.wasm
cd nanocode-wasm && npm ci && npm run build

# 3. Link it from the consuming project
cd ../my-host && npm install file:../nanocode-wasm
```

## Entrypoints

| Entrypoint                         | Contents                                                                                                          |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `nanocode-wasm`                    | The TypeScript source (`src/index.ts`). Node 22.18 or newer runs it with type stripping, and bundlers compile it. |
| `nanocode-wasm/nanocode_wasm.wasm` | The compiled module (`dist/nanocode_wasm.wasm`).                                                                  |

A bundler that loads `.wasm` imports as `WebAssembly.Module`, such as Wrangler, imports the module directly. Other hosts compile the file with `WebAssembly.compile`.

## Example

```ts title="host.ts"
import { readFileSync } from 'node:fs'
import { AgentRuntime, sessionUuid, type SqlHost } from 'nanocode-wasm'

// 1. Compile the module and instantiate it with a SQL host
declare const sql: SqlHost
const module = await WebAssembly.compile(
  readFileSync('node_modules/nanocode-wasm/dist/nanocode_wasm.wasm'),
)
const runtime = await AgentRuntime.instantiate(module, sql, {
  published: (events) => console.log(events),
})

// 2. Open the session. The host adds credentials in dispatch.
await runtime.open(
  {
    endpoint: 'https://api.anthropic.com/v1/messages',
    provider: 'claude',
    scope: 'owner',
    session_id: sessionUuid(),
    subscription: false,
  },
  {
    dispatch: (request, signal) =>
      fetch(request.endpoint, {
        body: request.body as Uint8Array<ArrayBuffer>,
        headers: request.headers,
        method: 'POST',
        redirect: 'error',
        signal,
      }),
  },
)

// 3. Queue a turn, drive it, and read its report
await runtime.submit('owner', {
  metadata: {},
  prompt: 'Say hello.',
  request_id: 'turn-1',
})
await runtime.drive('turn-1')
console.log((await runtime.turn('owner', 'turn-1'))?.report)
```

## AgentRuntime

- [AgentRuntime](/docs/api/wasm/AgentRuntime): The class that runs one session scope and its lifecycle.

- [instantiate](/docs/api/wasm/instantiate): Instantiate the module for one session scope.

- [open](/docs/api/wasm/open): Open the SDK session with a configuration and host options.

- [submit](/docs/api/wasm/submit): Queue a turn in the session log.

- [drive](/docs/api/wasm/drive): Run one root turn through the turn inbox.

- [turn and pending](/docs/api/wasm/turn): Read one turn, or the queued and running turns.

- [page](/docs/api/wasm/page): Read logged events after a cursor.

- [cancel](/docs/api/wasm/cancel): Cancel a queued or running turn.

- [dispose](/docs/api/wasm/dispose): Shut the SDK session down.

## Host Contracts

- [SqlHost](/docs/api/wasm/SqlHost): Run each operation's statements in one SQLite transaction.

- [HostTool](/docs/api/wasm/HostTool): Declare a host tool and run its calls.

- [RemoteExecutor](/docs/api/wasm/RemoteExecutor): Carry remote Code Mode frames over a message socket.

## Utilities

- [EventHub](/docs/api/wasm/EventHub): Keep a bounded event tail and serve Server-Sent Events.

- [sessionUuid](/docs/api/wasm/sessionUuid): Make the UUIDv7 session IDs that the SDK requires.

- [HostFailure](/docs/api/wasm/HostFailure): An error with a kind and a permanent flag.

- [Types](/docs/api/wasm/types): The remaining exported types and constants.

## Exported Types

| Export               | Page                                            |
| -------------------- | ----------------------------------------------- |
| `AgentConfiguration` | [open](/docs/api/wasm/open)                     |
| `Driven`             | [drive](/docs/api/wasm/drive)                   |
| `HostOptions`        | [instantiate](/docs/api/wasm/instantiate)       |
| `HostTool`           | [HostTool](/docs/api/wasm/HostTool)             |
| `LoggedEvent`        | [Types](/docs/api/wasm/types#loggedevent)       |
| `LogPage`            | [page](/docs/api/wasm/page)                     |
| `MessageSocket`      | [Types](/docs/api/wasm/types#messagesocket)     |
| `ModelProvider`      | [Types](/docs/api/wasm/types#modelprovider)     |
| `ModelTiming`        | [Types](/docs/api/wasm/types#modeltiming)       |
| `RECENT_MODEL_LIMIT` | [Types](/docs/api/wasm/types#recentmodellimit)  |
| `RemotePolicy`       | [RemoteExecutor](/docs/api/wasm/RemoteExecutor) |
| `RemoteRefusal`      | [RemoteExecutor](/docs/api/wasm/RemoteExecutor) |
| `RemoteRequest`      | [Types](/docs/api/wasm/types#remoterequest)     |
| `RuntimeMetrics`     | [Types](/docs/api/wasm/types#runtimemetrics)    |
| `RuntimeOptions`     | [open](/docs/api/wasm/open)                     |
| `RuntimeTiming`      | [Types](/docs/api/wasm/types#runtimetiming)     |
| `SocketHandshake`    | [Types](/docs/api/wasm/types#sockethandshake)   |
| `SqlHost`            | [SqlHost](/docs/api/wasm/SqlHost)               |
| `SqlKind`            | [SqlHost](/docs/api/wasm/SqlHost)               |
| `SqlValue`           | [SqlHost](/docs/api/wasm/SqlHost)               |
| `Statement`          | [SqlHost](/docs/api/wasm/SqlHost)               |
| `Submitted`          | [submit](/docs/api/wasm/submit)                 |
| `Timings`            | [Types](/docs/api/wasm/types#timings)           |
| `timingDifference`   | [Types](/docs/api/wasm/types#timingdifference)  |
| `TimingSnapshot`     | [Types](/docs/api/wasm/types#timingsnapshot)    |
| `TimingValue`        | [Types](/docs/api/wasm/types#timingsnapshot)    |
| `TurnReport`         | [turn and pending](/docs/api/wasm/turn)         |
| `TurnView`           | [turn and pending](/docs/api/wasm/turn)         |