nanocodex 0.2.0 → 0.4.0

package/node/host.mjs

@@ -1,10 +1,13 @@
 import { Console } from "node:console";
 import { createRequire } from "node:module";
+import { resolve } from "node:path";
 import WebSocket from "ws";
+import packageMetadata from "../package.json" with { type: "json" };
 
 import { createCodeRuntime } from "../runtime/code-runtime.mjs";
 
 const RESPONSES_WEBSOCKETS_BETA = "responses_websockets=2026-02-06";
+const USER_AGENT = `nanocodex-wasm/${packageMetadata.version}`;
 const DEFAULT_MAX_QUEUED_MESSAGES = 4_096;
 const DEFAULT_MAX_QUEUED_BYTES = 32 * 1024 * 1024;
 const DEFAULT_MAX_FRAME_BYTES = 16 * 1024 * 1024;
@@ -12,9 +15,13 @@ 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()}/`),
+    require: createRequire(resolve(options.workspace ?? process.cwd(), ".nanocodex-code-mode.cjs")),
     console: new Console({ stdout: process.stderr, stderr: process.stderr }),
   });
+  const toolMode = options.toolMode ?? "code";
+  if (toolMode !== "code" && toolMode !== "direct") {
+    throw new TypeError("toolMode must be code or direct");
+  }
   const onEvent = options.onEvent || (() => {});
   const connectTimeoutMs = options.connectTimeoutMs ?? 30_000;
   const sendTimeoutMs = options.sendTimeoutMs ?? 30_000;
@@ -23,29 +30,47 @@ export function createNodeHost(options = {}) {
   const maxFrameBytes = options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES;
   let nextHandle = 1;
 
-  function connect(endpoint, apiKey, sessionId) {
+  function connect(endpoint, apiKey, sessionId, metadata = {}) {
     if (options.mpp) return connectMpp(endpoint);
     return new Promise((resolve, reject) => {
       let settled = false;
       let upgradeResponse;
+      const 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": USER_AGENT,
+      };
+      if (metadata.accountId) headers["ChatGPT-Account-ID"] = metadata.accountId;
+      if (metadata.fedramp) headers["X-OpenAI-Fedramp"] = "true";
+      if (metadata.turnState) headers["x-codex-turn-state"] = metadata.turnState;
       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",
-        },
+        headers,
       });
       const handle = nextHandle++;
       const connection = queueState(socket);
 
       socket.on("upgrade", (response) => { upgradeResponse = response; });
+      socket.on("unexpected-response", (_request, response) => {
+        if (settled) return;
+        settled = true;
+        const chunks = [];
+        response.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        response.on("end", () => {
+          const error = new Error(`WebSocket handshake was rejected with HTTP ${response.statusCode}`);
+          error.status = response.statusCode;
+          error.body = chunks.length ? Buffer.concat(chunks).toString("utf8") : "empty response body";
+          const retryAfter = Number(header(response.headers, "retry-after"));
+          if (Number.isFinite(retryAfter) && retryAfter >= 0) error.retryAfter = retryAfter;
+          reject(error);
+        });
+      });
       socket.on("open", () => {
         settled = true;
         connections.set(handle, connection);
@@ -216,6 +241,8 @@ export function createNodeHost(options = {}) {
     close,
     sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
     executeCode: code.executeCode,
+    executeTool: code.executeTool,
+    toolMode: () => toolMode,
     toolDefinitions: code.toolDefinitions,
     emitEvent: onEvent,
     reset: code.reset,

package/node/index.d.mts

@@ -1,6 +1,8 @@
 export { Actions } from "../index.mjs";
 export type {
   AgentEvent,
+  CostStatus,
+  EstimatedUsdCost,
   PromptInput,
   PromptItem,
   ReasoningMode,
@@ -10,5 +12,7 @@ export type {
   ToolContext,
   ToolMap,
   Turn,
+  TurnResult,
+  TurnUsage,
 } from "../types.mjs";
 export * as Agent from "./Agent.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nanocodex",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Viem-style Node and browser bindings for the Nanocodex WASM agent",
   "type": "module",
   "sideEffects": false,
@@ -16,6 +16,10 @@
     "./browser": {
       "types": "./browser/index.d.mts",
       "import": "./browser/index.mjs"
+    },
+    "./wasm": {
+      "types": "./wasm.d.mts",
+      "import": "./pkg-web/nanocodex_bg.wasm"
     }
   },
   "files": [
@@ -25,10 +29,10 @@
     "pkg-node",
     "pkg-web",
     "runtime",
-    "scripts/check-package.mjs",
     "internal.mjs",
     "index.d.mts",
     "index.mjs",
+    "wasm.d.mts",
     "types.d.mts",
     "README.md"
   ],
@@ -39,7 +43,8 @@
   "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": "node --test test/*.test.mjs && npm run test:performance && npm run test:typecheck && npm run check:package",
+    "test:performance": "node --test test/performance.bench.mjs",
     "test:typecheck": "tsc -p test/tsconfig.json"
   },
   "dependencies": {

package/pkg-node/nanocodex.d.ts

@@ -2,13 +2,21 @@
 /* eslint-disable */
 
 /**
- * Persistent WASM agent handle hosted by Node.js or a browser Worker.
+ * JavaScript binding over the shared Rust agent lifecycle.
  */
 export class Nanocodex {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Fork the latest safe committed model boundary.
+     * Compacts retained history immediately without fabricating a user prompt.
+     *
+     * # Errors
+     *
+     * Throws when compaction or the agent driver fails.
+     */
+    compact(): Promise<void>;
+    /**
+     * Forks the latest safe committed model boundary.
      *
      * # Errors
      *
@@ -16,57 +24,63 @@ export class Nanocodex {
      */
     fork(): Promise<Nanocodex>;
     /**
-     * Fork from the exact checkpoint retained by a completed historical turn.
+     * Forks from an exact completed historical turn.
      *
      * # Errors
      *
-     * Rejects if the turn is incomplete, belongs to another lineage, or the
-     * driver stops.
+     * Rejects if the result belongs to another agent or the driver stopped.
      */
-    forkFrom(turn: Turn): Promise<Nanocodex>;
+    forkFrom(result: TurnResult): Promise<Nanocodex>;
     /**
-     * Build a persistent agent from a JSON configuration object.
+     * Builds an agent from its JavaScript JSON configuration.
      *
      * # Errors
      *
-     * Throws when the JSON or required configuration is invalid.
+     * Throws when the JSON or agent policy is invalid.
      */
     constructor(config_json: string);
     /**
-     * Accept a prompt immediately and return its independently awaitable turn.
+     * Accepts a text prompt and returns its independently awaitable turn.
      *
      * # Errors
      *
-     * Throws when the prompt is empty or the agent driver has stopped.
+     * Throws when the prompt is empty.
      */
     prompt(instruction: string): Turn;
     /**
-     * Accept ordered browser-safe text, image, or audio input encoded as JSON.
+     * Accepts browser-safe multimodal input encoded as JSON.
      *
      * # Errors
      *
-     * Throws for malformed or empty content, local filesystem inputs, or a
-     * stopped driver.
+     * Throws for malformed, empty, or local-filesystem input.
      */
     promptContent(content_json: string): Turn;
     /**
-     * Enable or disable priority processing for subsequently accepted turns.
+     * Enables or disables priority processing for subsequently accepted turns.
      *
      * # Errors
      *
-     * Rejects after the agent driver stops.
+     * Rejects after the driver stops.
      */
     setFastMode(enabled: boolean): Promise<void>;
     /**
-     * Change the reasoning effort for subsequently accepted turns.
+     * Changes the reasoning effort for subsequently accepted turns.
      *
      * # Errors
      *
-     * Rejects an unsupported effort or a stopped agent driver.
+     * Rejects an invalid effort or a stopped driver.
      */
     setThinking(thinking: string): Promise<void>;
     /**
-     * Start a clean sibling with the same configuration and tools.
+     * Gracefully stops the driver and joins every resource owned by this agent.
+     *
+     * # Errors
+     *
+     * Rejects when the driver had already stopped or cleanup fails.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Starts a clean sibling with the same private agent policy.
      *
      * # Errors
      *
@@ -74,60 +88,77 @@ export class Nanocodex {
      */
     spawn(): Promise<Nanocodex>;
     /**
-     * Stable session identifier used to route this agent's event stream.
+     * Returns the stable `UUIDv7` session identity.
      */
     readonly sessionId: string;
 }
 
 /**
- * Completion and control handle for one accepted WASM turn.
+ * JavaScript binding over one shared Rust turn.
  */
 export class Turn {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Cancel this exact active or queued turn.
+     * Cancels this exact active or queued turn.
      *
      * # Errors
      *
-     * Rejects if the turn is already terminal or the driver stops.
+     * Rejects if the turn is already terminal or its driver stopped.
      */
     cancel(): Promise<void>;
     /**
-     * Wait for the turn and return its final assistant message.
+     * Waits for the final assistant message.
      *
      * # Errors
      *
-     * Rejects when the model run fails, the driver stops, or two consumers
-     * await the same pending turn concurrently.
+     * Rejects when the model run or driver fails.
      */
-    result(): Promise<string>;
+    result(): Promise<TurnResult>;
     /**
-     * Serialize this completed turn's resumable session snapshot.
+     * Injects text input at the active turn's next safe model boundary.
      *
      * # Errors
      *
-     * Throws until the turn has completed or if serialization fails.
+     * Rejects if the turn is not active or its driver stopped.
      */
-    snapshot(): string;
+    steer(instruction: string): Promise<void>;
     /**
-     * Inject input at this active turn's next safe model boundary.
+     * Injects browser-safe multimodal input at the active turn's next boundary.
      *
      * # Errors
      *
-     * Rejects for empty input, a queued or terminal turn, a full steer queue,
-     * or a stopped driver.
+     * Rejects malformed input or a turn that is no longer active.
      */
-    steer(instruction: string): Promise<void>;
+    steerContent(content_json: string): Promise<void>;
+}
+
+/**
+ * JavaScript binding over one completed Rust turn result.
+ */
+export class TurnResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
     /**
-     * Inject ordered browser-safe text, image, or audio input at this active
-     * turn's next safe model boundary.
+     * Serializes this completed boundary's resumable session snapshot.
      *
      * # Errors
      *
-     * Rejects for malformed or empty content, local filesystem inputs, a
-     * queued or terminal turn, a full steer queue, or a stopped driver.
+     * Throws when serialization fails.
      */
-    steerContent(content_json: string): Promise<void>;
+    snapshot(): string;
+    /**
+     * Serializes exact aggregate usage for this completed logical turn.
+     *
+     * # Errors
+     *
+     * Throws when serialization fails.
+     */
+    usage(): string;
+    /**
+     * Returns the final assistant message.
+     */
+    readonly finalMessage: string;
 }