nanocodex 0.1.1

package/internal.mjs

@@ -0,0 +1,303 @@
+const AGENT_STATE = Symbol("nanocodex.agent");
+const TURN_STATE = Symbol("nanocodex.turn");
+const hostSessions = new Map();
+const hostConnections = new Map();
+let activeHost;
+let nextHostConnection = 1;
+let nextAgentUid = 1;
+
+export function defineRuntime(definition) {
+  if (!definition || typeof definition.create !== "function") {
+    throw new TypeError("a Nanocodex runtime must define create(options)");
+  }
+  return Object.freeze({
+    key: definition.key ?? "custom",
+    name: definition.name ?? "Nanocodex Agent",
+    type: definition.type ?? "custom",
+    create: definition.create,
+    dispose: definition.dispose || ((agent) => agent.free()),
+    subscribe: definition.subscribe,
+    adopt: definition.adopt,
+    release: definition.release,
+    decorate: definition.decorate,
+  });
+}
+
+export async function createAgentClient(runtime, options = {}) {
+  if (!runtime || typeof runtime.create !== "function") {
+    throw new TypeError("createAgent requires a Nanocodex runtime");
+  }
+  return createAgent(await runtime.create(options), runtime);
+}
+
+export function prompt(agent, options) {
+  const state = agentState(agent);
+  const input = actionInput(options);
+  const raw = typeof input === "string"
+    ? state.raw.prompt(input)
+    : state.raw.promptContent(JSON.stringify(input));
+  return createTurn(raw, agent);
+}
+
+export function getTurnResult(turn) {
+  const state = turnState(turn);
+  state.result ||= Promise.resolve().then(() => state.raw.result());
+  return state.result;
+}
+
+export function steer(turn, options) {
+  const state = turnState(turn);
+  const input = actionInput(options);
+  return typeof input === "string"
+    ? state.raw.steer(input)
+    : state.raw.steerContent(JSON.stringify(input));
+}
+
+export function cancel(turn) {
+  return turnState(turn).raw.cancel();
+}
+
+export async function fork(agent, options) {
+  const state = agentState(agent);
+  const at = options?.at;
+  const raw = at === undefined
+    ? await state.raw.fork()
+    : await state.raw.forkFrom(turnState(at).raw);
+  return createAgent(raw, state.runtime);
+}
+
+export async function spawn(agent) {
+  const state = agentState(agent);
+  return createAgent(await state.raw.spawn(), state.runtime);
+}
+
+export function subscribeAgentEvents(agent, listener, options = {}) {
+  const state = agentState(agent);
+  if (typeof state.runtime.subscribe !== "function") {
+    throw new Error("this Nanocodex runtime does not expose agent events");
+  }
+  if (typeof listener !== "function") {
+    throw new TypeError("watchAgentEvents requires a listener");
+  }
+  return state.runtime.subscribe((event) => {
+    if (options.includeAllSessions || !event?.request_id || event.request_id === agent.sessionId) {
+      listener(event);
+    }
+  });
+}
+
+export function toWasmConfig(options = {}) {
+  const apiKey = options.apiKey;
+  if (typeof apiKey !== "string" || !apiKey.trim()) {
+    throw new TypeError("apiKey must be a non-empty string");
+  }
+  const config = { api_key: apiKey };
+  copy(config, "thinking", options.thinking);
+  copy(config, "reasoning_mode", options.reasoningMode);
+  copy(config, "websocket_url", options.websocketUrl);
+  copy(config, "api_base_url", options.apiBaseUrl);
+  copy(config, "instructions", options.instructions);
+  copy(config, "session_id", options.sessionId);
+  return config;
+}
+
+export function createEventChannel() {
+  const listeners = new Set();
+  return Object.freeze({
+    emit(eventJson) {
+      const event = typeof eventJson === "string" ? JSON.parse(eventJson) : eventJson;
+      for (const listener of listeners) listener(event);
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  });
+}
+
+export function activateHost(host) {
+  if (!host || typeof host.connect !== "function") {
+    throw new TypeError("a Nanocodex host must define connect()");
+  }
+  activeHost = host;
+  globalThis.nanocodexHost = hostBridge;
+}
+
+export function bindHostSession(host, sessionId) {
+  const existing = hostSessions.get(sessionId);
+  if (existing && existing !== host) {
+    throw new Error(`Nanocodex session ID is already active: ${sessionId}`);
+  }
+  hostSessions.set(sessionId, host);
+}
+
+export function releaseHostSession(host, sessionId) {
+  if (hostSessions.get(sessionId) === host) hostSessions.delete(sessionId);
+}
+
+const hostBridge = Object.freeze({
+  async connect(endpoint, apiKey, sessionId) {
+    const host = requiredSessionHost(sessionId);
+    const result = JSON.parse(await host.connect(endpoint, apiKey, sessionId));
+    const handle = nextHostConnection++;
+    hostConnections.set(handle, { host, handle: result.handle });
+    hostSessions.set(sessionId, host);
+    return JSON.stringify({ ...result, handle });
+  },
+  send(handle, message) {
+    const connection = hostConnections.get(handle);
+    return connection
+      ? connection.host.send(connection.handle, message)
+      : Promise.resolve(JSON.stringify({ ok: false, reconnectable: true, error: "unknown WebSocket handle" }));
+  },
+  next(handle, timeoutMs) {
+    const connection = hostConnections.get(handle);
+    return connection
+      ? connection.host.next(connection.handle, timeoutMs)
+      : Promise.resolve(JSON.stringify({ kind: "closed", detail: "for an unknown WebSocket handle" }));
+  },
+  close(handle) {
+    const connection = hostConnections.get(handle);
+    if (!connection) return;
+    hostConnections.delete(handle);
+    connection.host.close(connection.handle);
+  },
+  sleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+  },
+  executeCode(source, sessionId, callId) {
+    return requiredSessionHost(sessionId).executeCode(source, sessionId, callId);
+  },
+  toolDefinitions(sessionId) {
+    // ModelRun builds its stable tool prefix inside the WASM constructor,
+    // immediately before the returned session can be adopted. Runtime
+    // factories activate their host directly around that synchronous step.
+    return (hostSessions.get(sessionId) ?? requiredActiveHost()).toolDefinitions();
+  },
+  emitEvent(eventJson) {
+    const event = JSON.parse(eventJson);
+    requiredSessionHost(event.request_id).emitEvent(eventJson);
+  },
+});
+
+function createAgent(raw, runtime) {
+  if (!raw || typeof raw.prompt !== "function") {
+    throw new TypeError("the runtime returned an invalid Nanocodex agent handle");
+  }
+  const state = {
+    raw,
+    runtime,
+    disposed: false,
+    sessionId: raw.sessionId,
+    uid: `agent-${nextAgentUid++}`,
+  };
+  try {
+    runtime.adopt?.(raw);
+  } catch (error) {
+    runtime.dispose(raw);
+    throw error;
+  }
+  const agent = agentView(state, {});
+  return runtime.decorate ? runtime.decorate(agent) : agent;
+}
+
+function agentView(state, extensions) {
+  let agent;
+  const base = {
+    uid: state.uid,
+    key: state.runtime.key,
+    name: state.runtime.name,
+    type: state.runtime.type,
+    get sessionId() { return state.sessionId; },
+    extend(fn) {
+      if (typeof fn !== "function") throw new TypeError("agent.extend requires a decorator function");
+      const value = fn(agent);
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError("an agent decorator must return an object");
+      }
+      const extension = { ...value };
+      for (const key of Object.keys(base)) delete extension[key];
+      return agentView(state, deepMerge(extensions, extension));
+    },
+    dispose() {
+      if (state.disposed) return;
+      state.disposed = true;
+      state.runtime.release?.(state.raw);
+      state.runtime.dispose(state.raw);
+    },
+  };
+  agent = Object.assign(base, extensions);
+  Object.defineProperty(agent, AGENT_STATE, { value: state });
+  return agent;
+}
+
+function requiredSessionHost(sessionId) {
+  const host = hostSessions.get(sessionId);
+  if (!host) throw new Error(`no Nanocodex host is active for session: ${sessionId}`);
+  return host;
+}
+
+function requiredActiveHost() {
+  if (!activeHost) throw new Error("no Nanocodex host is active");
+  return activeHost;
+}
+
+function createTurn(raw, agent) {
+  if (!raw || typeof raw.result !== "function") {
+    throw new TypeError("the runtime returned an invalid Nanocodex turn handle");
+  }
+  const state = { raw, agent, result: undefined, disposed: false };
+  const turn = {
+    get agent() { return state.agent; },
+    result: () => getTurnResult(turn),
+    steer: (input) => steer(turn, input),
+    cancel: () => cancel(turn),
+    dispose() {
+      if (state.disposed) return;
+      state.disposed = true;
+      state.raw.free();
+    },
+  };
+  Object.defineProperty(turn, TURN_STATE, { value: state });
+  return Object.freeze(turn);
+}
+
+function agentState(agent) {
+  const state = agent?.[AGENT_STATE];
+  if (!state) throw new TypeError("expected a Nanocodex agent");
+  if (state.disposed) throw new Error("the Nanocodex agent has been disposed");
+  return state;
+}
+
+function turnState(turn) {
+  const state = turn?.[TURN_STATE];
+  if (!state) throw new TypeError("expected a Nanocodex turn");
+  if (state.disposed) throw new Error("the Nanocodex turn has been disposed");
+  return state;
+}
+
+function actionInput(options) {
+  const input = options?.input;
+  if (typeof input !== "string" && !Array.isArray(input)) {
+    throw new TypeError("turn input must be a string or ordered content array");
+  }
+  return input;
+}
+
+function deepMerge(left, right) {
+  const merged = { ...left };
+  for (const [key, value] of Object.entries(right)) {
+    merged[key] = isObject(merged[key]) && isObject(value)
+      ? deepMerge(merged[key], value)
+      : value;
+  }
+  return merged;
+}
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function copy(target, key, value) {
+  if (value !== undefined) target[key] = value;
+}

package/node/Agent.d.mts

@@ -0,0 +1,24 @@
+import type {
+  AgentOptions,
+  DefaultAgent,
+  ToolMap,
+} from "../types.mjs";
+
+export type Agent = DefaultAgent;
+
+/** Creates a Node-hosted Rust/WASM Agent. */
+export function create(options: create.Options): Promise<create.ReturnType>;
+export declare namespace create {
+  type Options = AgentOptions & {
+    apiBaseUrl?: string | undefined;
+    apiKey: string;
+    connectTimeoutMs?: number | undefined;
+    maxFrameBytes?: number | undefined;
+    maxQueuedBytes?: number | undefined;
+    maxQueuedMessages?: number | undefined;
+    sendTimeoutMs?: number | undefined;
+    tools?: ToolMap | undefined;
+    websocketUrl?: string | undefined;
+  };
+  type ReturnType = Agent;
+}

package/node/Agent.mjs

@@ -0,0 +1,51 @@
+import { createRequire } from "node:module";
+
+import { agentActions } from "../actions/index.mjs";
+import {
+  activateHost,
+  bindHostSession,
+  createAgentClient,
+  createEventChannel,
+  defineRuntime,
+  releaseHostSession,
+  toWasmConfig,
+} from "../internal.mjs";
+import { createNodeHost } from "./host.mjs";
+
+const require = createRequire(import.meta.url);
+const { Nanocodex } = require("../pkg-node/nanocodex.js");
+
+export function create(options = {}) {
+  const {
+    thinking,
+    reasoningMode,
+    instructions,
+    sessionId,
+    apiKey,
+    websocketUrl,
+    apiBaseUrl,
+    ...hostOptions
+  } = options;
+  const events = createEventChannel();
+  const host = createNodeHost({ ...hostOptions, onEvent: events.emit });
+  activateHost(host);
+  const runtime = defineRuntime({
+    key: "node-wasm",
+    name: "Nanocodex Node WASM",
+    type: "node",
+    create(config) {
+      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/node/host.mjs

@@ -0,0 +1,204 @@
+import { Console } from "node:console";
+import { createRequire } from "node:module";
+import WebSocket from "ws";
+
+import { createCodeRuntime } from "../runtime/code-runtime.mjs";
+
+const RESPONSES_WEBSOCKETS_BETA = "responses_websockets=2026-02-06";
+const DEFAULT_MAX_QUEUED_MESSAGES = 4_096;
+const DEFAULT_MAX_QUEUED_BYTES = 32 * 1024 * 1024;
+const DEFAULT_MAX_FRAME_BYTES = 16 * 1024 * 1024;
+
+export function createNodeHost(options = {}) {
+  const connections = new Map();
+  const code = createCodeRuntime(options.tools, {
+    require: createRequire(`${process.cwd()}/`),
+    console: new Console({ stdout: process.stderr, stderr: process.stderr }),
+  });
+  const onEvent = options.onEvent || (() => {});
+  const connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
+  const sendTimeoutMs = options.sendTimeoutMs ?? 30_000;
+  const maxQueuedMessages = options.maxQueuedMessages ?? DEFAULT_MAX_QUEUED_MESSAGES;
+  const maxQueuedBytes = options.maxQueuedBytes ?? DEFAULT_MAX_QUEUED_BYTES;
+  const maxFrameBytes = options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES;
+  let nextHandle = 1;
+
+  function connect(endpoint, apiKey, sessionId) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let upgradeResponse;
+      const socket = new WebSocket(endpoint, {
+        handshakeTimeout: connectTimeoutMs,
+        maxPayload: maxFrameBytes,
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "OpenAI-Beta": RESPONSES_WEBSOCKETS_BETA,
+          "x-openai-internal-codex-responses-lite": "true",
+          "session-id": sessionId,
+          "thread-id": sessionId,
+          "x-client-request-id": sessionId,
+          "x-responsesapi-include-timing-metrics": "true",
+          "User-Agent": "nanocodex-wasm/0.1.0",
+        },
+      });
+      const handle = nextHandle++;
+      const connection = queueState(socket);
+
+      socket.on("upgrade", (response) => { upgradeResponse = response; });
+      socket.on("open", () => {
+        settled = true;
+        connections.set(handle, connection);
+        const headers = upgradeResponse?.headers || {};
+        resolve(JSON.stringify({
+          handle,
+          status: upgradeResponse?.statusCode || 101,
+          request_id: header(headers, "x-request-id"),
+          server_model: header(headers, "openai-model"),
+          reasoning_included: header(headers, "x-reasoning-included") !== undefined,
+          turn_state: header(headers, "x-codex-turn-state"),
+        }));
+      });
+      socket.on("message", (data, isBinary) => {
+        enqueue(connection, isBinary
+          ? { kind: "binary" }
+          : { kind: "text", text: data.toString("utf8") });
+      });
+      socket.on("close", (status, reason) => {
+        if (!connection.intentionallyClosed && !connection.overflowed) {
+          const suffix = reason.length ? `: ${reason.toString("utf8")}` : "";
+          enqueue(connection, { kind: "closed", detail: `with code ${status}${suffix}` });
+        }
+      });
+      socket.on("error", (error) => {
+        if (!settled) {
+          settled = true;
+          reject(error);
+        } else {
+          enqueue(connection, { kind: "error", detail: errorMessage(error) });
+        }
+      });
+    });
+  }
+
+  function send(handle, message) {
+    const connection = connections.get(handle);
+    if (!connection || connection.socket.readyState !== WebSocket.OPEN) {
+      return Promise.resolve(JSON.stringify({
+        ok: false,
+        reconnectable: true,
+        error: "WebSocket is no longer open",
+      }));
+    }
+    return new Promise((resolve) => {
+      let completed = false;
+      const timer = setTimeout(() => finish({
+        ok: false,
+        reconnectable: false,
+        error: `sending a WebSocket frame exceeded ${sendTimeoutMs} milliseconds`,
+      }), sendTimeoutMs);
+      function finish(result) {
+        if (completed) return;
+        completed = true;
+        clearTimeout(timer);
+        resolve(JSON.stringify(result));
+      }
+      connection.socket.send(message, (error) => finish(error ? {
+        ok: false,
+        reconnectable: connection.socket.readyState !== WebSocket.OPEN,
+        error: errorMessage(error),
+      } : { ok: true }));
+    });
+  }
+
+  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 = messageBytes(message);
+    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`,
+      };
+      connection.queue.push({ message: error, bytes: messageBytes(error) });
+      connection.socket.terminate();
+      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,
+  });
+}
+
+function queueState(socket) {
+  return {
+    socket,
+    queue: [],
+    queuedBytes: 0,
+    waiter: undefined,
+    intentionallyClosed: false,
+    overflowed: false,
+  };
+}
+
+function header(headers, name) {
+  const value = headers[name];
+  return Array.isArray(value) ? value[0] : value;
+}
+
+function messageBytes(message) {
+  return Buffer.byteLength(message.kind === "text" ? message.text : JSON.stringify(message), "utf8");
+}
+
+function errorMessage(error) {
+  return error && (error.stack || error.message) || String(error);
+}

package/node/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/node/index.mjs

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

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "nanocodex",
+  "version": "0.1.1",
+  "description": "Viem-style Node and browser bindings for the Nanocodex WASM agent",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./index.d.mts",
+      "import": "./index.mjs"
+    },
+    "./node": {
+      "types": "./node/index.d.mts",
+      "import": "./node/index.mjs"
+    },
+    "./browser": {
+      "types": "./browser/index.d.mts",
+      "import": "./browser/index.mjs"
+    }
+  },
+  "files": [
+    "actions",
+    "browser",
+    "node",
+    "pkg-node",
+    "pkg-web",
+    "runtime",
+    "scripts/check-package.mjs",
+    "internal.mjs",
+    "index.d.mts",
+    "index.mjs",
+    "types.d.mts",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "check:package": "node scripts/check-package.mjs",
+    "prepack": "npm run check:package",
+    "test": "node --test test/*.test.mjs && npm run test:typecheck && npm run check:package",
+    "test:typecheck": "tsc -p test/tsconfig.json"
+  },
+  "dependencies": {
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "pkg-pr-new": "0.0.79",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gakonst/nanocodex.git",
+    "directory": "js/bindings"
+  }
+}