nanocodex 0.1.1

package/README.md

@@ -0,0 +1,116 @@
+# Nanocodex for JavaScript
+
+The Node and browser entrypoints expose the same viem-v3-style API over the
+same Rust/WASM agent. Runtime-specific host options are flattened into
+`Agent.create(...)`; generated WASM handles and host routing remain private.
+
+```js
+import { Actions, Agent } from "nanocodex/node";
+
+const agent = await Agent.create({
+  apiKey: process.env.OPENAI_API_KEY,
+  reasoningMode: "pro",
+  thinking: "high",
+  tools,
+});
+
+const turn = agent.turn.prompt({ input: "Build the thing." });
+console.log(await turn.result());
+
+const branch = await agent.session.fork({ at: turn });
+console.log(await branch.turn.prompt({ input: "Try another approach." }).result());
+
+const followOn = Actions.turn.prompt(agent, { input: "Now explain it." });
+console.log(await Actions.turn.getResult(followOn));
+```
+
+`Agent` and `Actions` are module namespaces, not classes. `Agent.create` returns
+an owned client decorated with matching domain actions:
+
+- `agent.turn.prompt(...)` / `Actions.turn.prompt(agent, ...)`
+- `agent.session.fork(...)` / `Actions.session.fork(agent, ...)`
+- `agent.session.spawn()` / `Actions.session.spawn(agent)`
+- `agent.events.watch(...)` / `Actions.events.watch(agent, ...)`
+
+Every action owns its types, for example `Actions.turn.prompt.Options`,
+`Actions.turn.prompt.ReturnType`, and `Actions.events.watch.Watcher`.
+
+Event watches are lazy, terminal handles:
+
+```js
+const watch = agent.events.watch();
+const unlisten = watch.onEvent(console.log);
+
+unlisten();
+watch.off();
+```
+
+The same watcher can instead be consumed as an ordered async iterable; breaking
+the loop releases that iterator, while `watch.off()` terminates the whole watch.
+
+```js
+const watch = agent.events.watch();
+for await (const event of watch) {
+  console.log(event);
+  if (done) break;
+}
+watch.off();
+```
+
+Applications add typed action domains with decorators:
+
+```js
+const extended = agent.extend((client) => ({
+  inspect: {
+    session: () => client.sessionId,
+  },
+}));
+
+extended.inspect.session();
+```
+
+Browser Workers use the identical shape:
+
+```js
+import { Agent } from "nanocodex/browser";
+
+const agent = await Agent.create({
+  websocketUrl: signedOrCookieAuthorizedEndpoint,
+  createWebSocket(endpoint, sessionId) {
+    const url = new URL(endpoint);
+    url.searchParams.set("session_id", sessionId);
+    return new WebSocket(url);
+  },
+  tools,
+});
+```
+
+After publication, a browser can load the same entrypoint without a package
+manager or build step:
+
+```html
+<script type="module">
+  import { Agent } from "https://cdn.jsdelivr.net/npm/nanocodex@0.1.0/browser/index.mjs";
+  const agent = await Agent.create({ websocketUrl: "/api/responses" });
+  console.log(await agent.turn.prompt({ input: "Hello." }).result());
+</script>
+```
+
+Pin the package version in production. The adjacent WASM file is part of the
+npm package and is resolved relative to the browser module. The endpoint must
+be authorized by the embedding application because browser WebSockets cannot
+attach OpenAI's upgrade authorization header.
+
+The owned Rust session retains follow-on history, response state, tool output,
+its WebSocket, and stable prompt-cache identity. Typed browser content accepts
+ordered text, remote/data-URL image, and audio items. JavaScript tools are
+ordinary async handlers described by JSON Schema and appear in the same ordered
+agent event stream as built-in code mode.
+
+Run the standalone Node proof with:
+
+```sh
+cd examples/node
+npm install
+OPENAI_API_KEY=... npm start
+```

package/actions/events.d.mts

@@ -0,0 +1,10 @@
+import type { Agent, AgentEvent, EventWatcher, WatchEventsOptions } from "../types.mjs";
+
+/** Creates a lazy, terminal watcher for an Agent's ordered event stream. */
+export function watch(agent: Agent<object>, options?: watch.Options): watch.ReturnType;
+export declare namespace watch {
+  type OnEventFn = (event: AgentEvent) => void;
+  type Options = WatchEventsOptions;
+  type ReturnType = EventWatcher;
+  type Watcher = EventWatcher;
+}

package/actions/events.mjs

@@ -0,0 +1,91 @@
+import { subscribeAgentEvents } from "../internal.mjs";
+
+export function watch(agent, options = {}) {
+  const listeners = new Set();
+  const iterators = new Set();
+  let unsubscribe;
+  let closed = false;
+
+  const emit = (event) => {
+    for (const listener of listeners) listener(event);
+    for (const iterator of iterators) iterator.push(event);
+  };
+
+  const start = () => {
+    if (closed || unsubscribe) return;
+    unsubscribe = subscribeAgentEvents(agent, emit, options);
+  };
+
+  const watcher = {
+    onEvent(listener) {
+      if (typeof listener !== "function") throw new TypeError("events.watch.onEvent requires a listener");
+      if (closed) return () => {};
+      listeners.add(listener);
+      start();
+      return () => listeners.delete(listener);
+    },
+    off() {
+      if (closed) return;
+      closed = true;
+      unsubscribe?.();
+      unsubscribe = undefined;
+      listeners.clear();
+      for (const iterator of [...iterators]) iterator.end();
+      iterators.clear();
+    },
+    [Symbol.asyncIterator]() {
+      if (closed) return emptyIterator();
+      const iterator = eventIterator(() => iterators.delete(iterator));
+      iterators.add(iterator);
+      start();
+      return iterator;
+    },
+  };
+  return Object.freeze(watcher);
+}
+
+function eventIterator(onEnd) {
+  const queue = [];
+  let pending;
+  let done = false;
+
+  const iterator = {
+    push(event) {
+      if (done) return;
+      if (pending) {
+        const resolve = pending;
+        pending = undefined;
+        resolve({ done: false, value: event });
+      } else {
+        queue.push(event);
+      }
+    },
+    end() {
+      if (done) return;
+      done = true;
+      onEnd();
+      pending?.({ done: true, value: undefined });
+      pending = undefined;
+      queue.length = 0;
+    },
+    next() {
+      if (queue.length) return Promise.resolve({ done: false, value: queue.shift() });
+      if (done) return Promise.resolve({ done: true, value: undefined });
+      return new Promise((resolve) => { pending = resolve; });
+    },
+    return() {
+      iterator.end();
+      return Promise.resolve({ done: true, value: undefined });
+    },
+    [Symbol.asyncIterator]() { return this; },
+  };
+  return iterator;
+}
+
+function emptyIterator() {
+  return {
+    next: () => Promise.resolve({ done: true, value: undefined }),
+    return: () => Promise.resolve({ done: true, value: undefined }),
+    [Symbol.asyncIterator]() { return this; },
+  };
+}

package/actions/index.d.mts

@@ -0,0 +1,12 @@
+import type { Agent, AgentActions } from "../types.mjs";
+
+export * as events from "./events.mjs";
+export * as session from "./session.mjs";
+export * as turn from "./turn.mjs";
+
+/** Decorates a base Agent with the standard `turn`, `session`, and `events` domains. */
+export function agentActions(): agentActions.DecoratorFn;
+export declare namespace agentActions {
+  type Decorator = AgentActions;
+  type DecoratorFn = (agent: Agent<object>) => Decorator;
+}

package/actions/index.mjs

@@ -0,0 +1,20 @@
+import * as events from "./events.mjs";
+import * as session from "./session.mjs";
+import * as turn from "./turn.mjs";
+
+export { events, session, turn };
+
+export function agentActions() {
+  return (agent) => ({
+    events: {
+      watch: (options) => events.watch(agent, options),
+    },
+    session: {
+      fork: (options) => session.fork(agent, options),
+      spawn: () => session.spawn(agent),
+    },
+    turn: {
+      prompt: (options) => turn.prompt(agent, options),
+    },
+  });
+}

package/actions/session.d.mts

@@ -0,0 +1,14 @@
+import type { Agent, DefaultAgent, ForkOptions } from "../types.mjs";
+
+/** Forks the latest checkpoint, or the exact completed Turn supplied in `options.at`. */
+export function fork(agent: Agent<object>, options?: fork.Options): Promise<fork.ReturnType>;
+export declare namespace fork {
+  type Options = ForkOptions;
+  type ReturnType = DefaultAgent;
+}
+
+/** Creates a clean sibling with the Agent's configuration and tools. */
+export function spawn(agent: Agent<object>): Promise<spawn.ReturnType>;
+export declare namespace spawn {
+  type ReturnType = DefaultAgent;
+}

package/actions/session.mjs

@@ -0,0 +1,9 @@
+import { fork as forkAgent, spawn as spawnAgent } from "../internal.mjs";
+
+export function fork(agent, options = {}) {
+  return forkAgent(agent, options);
+}
+
+export function spawn(agent) {
+  return spawnAgent(agent);
+}

package/actions/turn.d.mts

@@ -0,0 +1,30 @@
+import type { Agent, PromptInput, Turn } from "../types.mjs";
+
+/** Accepts a prompt on an owned Agent and returns its independently awaitable Turn. */
+export function prompt<const agent extends Agent<object>>(
+  agent: agent,
+  options: prompt.Options,
+): prompt.ReturnType<agent>;
+export declare namespace prompt {
+  type Options = { input: PromptInput };
+  type ReturnType<agent extends Agent<object> = Agent<object>> = Turn<agent>;
+}
+
+/** Waits for a Turn's final assistant message. */
+export function getResult(turn: Turn): Promise<getResult.ReturnType>;
+export declare namespace getResult {
+  type ReturnType = string;
+}
+
+/** Adds input to an active Turn. */
+export function steer(turn: Turn, options: steer.Options): Promise<void>;
+export declare namespace steer {
+  type Options = { input: PromptInput };
+  type ReturnType = void;
+}
+
+/** Cancels an active or queued Turn. */
+export function cancel(turn: Turn): Promise<void>;
+export declare namespace cancel {
+  type ReturnType = void;
+}

package/actions/turn.mjs

@@ -0,0 +1,22 @@
+import {
+  cancel as cancelTurn,
+  getTurnResult,
+  prompt as promptTurn,
+  steer as steerTurn,
+} from "../internal.mjs";
+
+export function prompt(agent, options) {
+  return promptTurn(agent, options);
+}
+
+export function getResult(turn) {
+  return getTurnResult(turn);
+}
+
+export function steer(turn, options) {
+  return steerTurn(turn, options);
+}
+
+export function cancel(turn) {
+  return cancelTurn(turn);
+}

package/browser/Agent.d.mts

@@ -0,0 +1,25 @@
+import type {
+  AgentOptions,
+  DefaultAgent,
+  ToolMap,
+} from "../types.mjs";
+
+export type Agent = DefaultAgent;
+
+/** Creates a browser- or Worker-hosted Rust/WASM Agent. */
+export function create(options?: create.Options): Promise<create.ReturnType>;
+export declare namespace create {
+  type Options = AgentOptions & {
+    WebSocketImpl?: typeof WebSocket | undefined;
+    apiBaseUrl?: string | undefined;
+    apiKey?: string | undefined;
+    createWebSocket?(endpoint: string, sessionId: string): WebSocket;
+    maxBufferedSendBytes?: number | undefined;
+    maxQueuedBytes?: number | undefined;
+    maxQueuedMessages?: number | undefined;
+    module?: unknown;
+    tools?: ToolMap | undefined;
+    websocketUrl?: string | undefined;
+  };
+  type ReturnType = Agent;
+}

package/browser/Agent.mjs

@@ -0,0 +1,54 @@
+import init, { Nanocodex } from "../pkg-web/nanocodex.js";
+
+import { agentActions } from "../actions/index.mjs";
+import {
+  activateHost,
+  bindHostSession,
+  createAgentClient,
+  createEventChannel,
+  defineRuntime,
+  releaseHostSession,
+  toWasmConfig,
+} from "../internal.mjs";
+import { createBrowserHost } from "./host.mjs";
+
+let initialized;
+
+export function create(options = {}) {
+  const {
+    apiKey = "host-managed",
+    websocketUrl,
+    apiBaseUrl,
+    module,
+    thinking,
+    reasoningMode,
+    instructions,
+    sessionId,
+    ...hostOptions
+  } = options;
+  const events = createEventChannel();
+  const host = createBrowserHost({ ...hostOptions, onEvent: events.emit });
+  activateHost(host);
+  const runtime = defineRuntime({
+    key: "browser-wasm",
+    name: "Nanocodex Browser WASM",
+    type: "browser",
+    async create(config) {
+      activateHost(host);
+      initialized ||= module === undefined ? init() : init({ module_or_path: module });
+      await initialized;
+      activateHost(host);
+      return new Nanocodex(JSON.stringify(toWasmConfig({
+        apiKey,
+        websocketUrl,
+        apiBaseUrl,
+        ...config,
+      })));
+    },
+    subscribe: events.subscribe,
+    adopt: (raw) => bindHostSession(host, raw.sessionId),
+    release: (raw) => releaseHostSession(host, raw.sessionId),
+    decorate: (agent) => agent.extend(agentActions()),
+  });
+  return createAgentClient(runtime, { thinking, reasoningMode, instructions, sessionId });
+}

package/browser/host.d.mts

@@ -0,0 +1,20 @@
+export type BrowserTool = {
+  description: string;
+  parameters: Record<string, unknown>;
+  handler: (
+    input: unknown,
+    context: { sessionId: string },
+  ) => unknown | Promise<unknown>;
+};
+
+export type BrowserToolMap = Record<string, BrowserTool>;
+
+export function createBrowserHost(options?: {
+  WebSocketImpl?: typeof WebSocket;
+  createWebSocket?: (endpoint: string, sessionId: string) => WebSocket;
+  onEvent?: (eventJson: string) => void;
+  tools?: BrowserToolMap;
+  maxQueuedMessages?: number;
+  maxQueuedBytes?: number;
+  maxBufferedSendBytes?: number;
+}): unknown;

package/browser/host.mjs

@@ -0,0 +1,161 @@
+import { createCodeRuntime } from "../runtime/code-runtime.mjs";
+
+const DEFAULT_MAX_QUEUED_MESSAGES = 4_096;
+const DEFAULT_MAX_QUEUED_BYTES = 32 * 1024 * 1024;
+const DEFAULT_MAX_BUFFERED_SEND_BYTES = 16 * 1024 * 1024;
+
+export function createBrowserHost(options = {}) {
+  const WebSocketImpl = options.WebSocketImpl || globalThis.WebSocket;
+  if (!WebSocketImpl) throw new Error("WebSocket is unavailable in this runtime");
+  const connections = new Map();
+  const code = createCodeRuntime(options.tools);
+  const onEvent = options.onEvent || (() => {});
+  const createWebSocket = options.createWebSocket || ((endpoint) => new WebSocketImpl(endpoint));
+  const maxQueuedMessages = options.maxQueuedMessages ?? DEFAULT_MAX_QUEUED_MESSAGES;
+  const maxQueuedBytes = options.maxQueuedBytes ?? DEFAULT_MAX_QUEUED_BYTES;
+  const maxBufferedSendBytes = options.maxBufferedSendBytes ?? DEFAULT_MAX_BUFFERED_SEND_BYTES;
+  const encoder = new TextEncoder();
+  let nextHandle = 1;
+
+  function connect(endpoint, _apiKey, sessionId) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const handle = nextHandle++;
+      const socket = createWebSocket(endpoint, sessionId);
+      const connection = {
+        socket,
+        queue: [],
+        queuedBytes: 0,
+        waiter: undefined,
+        intentionallyClosed: false,
+        overflowed: false,
+      };
+      socket.addEventListener("open", () => {
+        settled = true;
+        connections.set(handle, connection);
+        resolve(JSON.stringify({ handle, status: 101, reasoning_included: false }));
+      }, { once: true });
+      socket.addEventListener("message", (event) => {
+        enqueue(connection, typeof event.data === "string"
+          ? { kind: "text", text: event.data }
+          : { kind: "binary" });
+      });
+      socket.addEventListener("close", (event) => {
+        if (!settled) {
+          settled = true;
+          reject(new Error(`WebSocket closed during connection with code ${event.code}`));
+        } else if (!connection.intentionallyClosed && !connection.overflowed) {
+          enqueue(connection, { kind: "closed", detail: `with code ${event.code}` });
+        }
+      });
+      socket.addEventListener("error", () => {
+        if (!settled) {
+          settled = true;
+          reject(new Error("WebSocket connection failed"));
+        } else {
+          enqueue(connection, { kind: "error", detail: "WebSocket connection failed" });
+        }
+      });
+    });
+  }
+
+  function send(handle, message) {
+    const connection = connections.get(handle);
+    if (!connection || connection.socket.readyState !== WebSocketImpl.OPEN) {
+      return Promise.resolve(JSON.stringify({
+        ok: false,
+        reconnectable: true,
+        error: "WebSocket is no longer open",
+      }));
+    }
+    try {
+      const frameBytes = encoder.encode(message).byteLength;
+      if (frameBytes > maxBufferedSendBytes
+        || connection.socket.bufferedAmount + frameBytes > maxBufferedSendBytes) {
+        return Promise.resolve(JSON.stringify({
+          ok: false,
+          reconnectable: false,
+          error: `buffered WebSocket sends exceeded ${maxBufferedSendBytes} bytes`,
+        }));
+      }
+      connection.socket.send(message);
+      return Promise.resolve(JSON.stringify({ ok: true }));
+    } catch (error) {
+      return Promise.resolve(JSON.stringify({
+        ok: false,
+        reconnectable: connection.socket.readyState !== WebSocketImpl.OPEN,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    }
+  }
+
+  function next(handle, timeoutMs) {
+    const connection = connections.get(handle);
+    if (!connection) {
+      return Promise.resolve(JSON.stringify({ kind: "closed", detail: "before the next frame" }));
+    }
+    if (connection.queue.length) {
+      const entry = connection.queue.shift();
+      connection.queuedBytes -= entry.bytes;
+      return Promise.resolve(JSON.stringify(entry.message));
+    }
+    if (connection.waiter) return Promise.reject(new Error("concurrent reads are unsupported"));
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        connection.waiter = undefined;
+        resolve(JSON.stringify({ kind: "timeout" }));
+      }, timeoutMs);
+      connection.waiter = (message) => {
+        clearTimeout(timer);
+        connection.waiter = undefined;
+        resolve(JSON.stringify(message));
+      };
+    });
+  }
+
+  function close(handle) {
+    const connection = connections.get(handle);
+    if (!connection) return;
+    connections.delete(handle);
+    connection.intentionallyClosed = true;
+    connection.waiter?.({ kind: "closed", detail: "by the WASM runtime" });
+    connection.socket.close();
+  }
+
+  function enqueue(connection, message) {
+    if (connection.overflowed) return;
+    if (connection.waiter) {
+      connection.waiter(message);
+      return;
+    }
+    const bytes = encoder.encode(message.kind === "text" ? message.text : JSON.stringify(message)).byteLength;
+    if (connection.queue.length >= maxQueuedMessages || connection.queuedBytes + bytes > maxQueuedBytes) {
+      connection.queue.length = 0;
+      connection.queuedBytes = 0;
+      connection.overflowed = true;
+      const error = {
+        kind: "error",
+        detail: `receive queue exceeded ${maxQueuedMessages} messages or ${maxQueuedBytes} bytes`,
+      };
+      const errorBytes = encoder.encode(JSON.stringify(error)).byteLength;
+      connection.queue.push({ message: error, bytes: errorBytes });
+      connection.queuedBytes = errorBytes;
+      connection.socket.close(1009, "receive queue exceeded configured bounds");
+      return;
+    }
+    connection.queue.push({ message, bytes });
+    connection.queuedBytes += bytes;
+  }
+
+  return Object.freeze({
+    connect,
+    send,
+    next,
+    close,
+    sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+    executeCode: code.executeCode,
+    toolDefinitions: code.toolDefinitions,
+    emitEvent: onEvent,
+    reset: code.reset,
+  });
+}

package/browser/index.d.mts

@@ -0,0 +1,13 @@
+export { Actions } from "../index.mjs";
+export type {
+  AgentEvent,
+  PromptInput,
+  PromptItem,
+  ReasoningMode,
+  Thinking,
+  Tool,
+  ToolContext,
+  ToolMap,
+  Turn,
+} from "../types.mjs";
+export * as Agent from "./Agent.mjs";

package/browser/index.mjs

@@ -0,0 +1,2 @@
+export { Actions } from "../index.mjs";
+export * as Agent from "./Agent.mjs";

package/index.d.mts

@@ -0,0 +1,19 @@
+export * as Actions from "./actions/index.mjs";
+export type {
+  Agent,
+  AgentActions,
+  AgentEvent,
+  AgentOptions,
+  DefaultAgent,
+  EventWatcher,
+  ForkOptions,
+  PromptInput,
+  PromptItem,
+  ReasoningMode,
+  Thinking,
+  Tool,
+  ToolContext,
+  ToolMap,
+  Turn,
+  WatchEventsOptions,
+} from "./types.mjs";

package/index.mjs

@@ -0,0 +1 @@
+export * as Actions from "./actions/index.mjs";