nanocodex 0.1.1 → 0.3.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,7 +15,7 @@ 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 onEvent = options.onEvent || (() => {});
@@ -23,28 +26,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);
@@ -80,6 +102,35 @@ export function createNodeHost(options = {}) {
     });
   }
 
+  async function connectMpp(endpoint) {
+    if (typeof options.mpp.ws !== "function") {
+      throw new TypeError("mpp must provide ws(endpoint)");
+    }
+    const socket = await options.mpp.ws(endpoint);
+    if (!socket || typeof socket.addEventListener !== "function") {
+      throw new TypeError("mpp.ws(endpoint) must return a WebSocket");
+    }
+    const handle = nextHandle++;
+    const connection = queueState(socket);
+    connection.managed = true;
+    connections.set(handle, connection);
+    socket.addEventListener("message", (event) => {
+      enqueue(connection, typeof event.data === "string"
+        ? { kind: "text", text: event.data }
+        : { kind: "binary" });
+    });
+    socket.addEventListener("close", (event) => {
+      if (!connection.intentionallyClosed && !connection.overflowed) {
+        const suffix = event.reason ? `: ${event.reason}` : "";
+        enqueue(connection, { kind: "closed", detail: `with code ${event.code ?? 1000}${suffix}` });
+      }
+    });
+    socket.addEventListener("error", () => {
+      enqueue(connection, { kind: "error", detail: "MPP WebSocket connection failed" });
+    });
+    return JSON.stringify({ handle, status: 101, reasoning_included: false });
+  }
+
   function send(handle, message) {
     const connection = connections.get(handle);
     if (!connection || connection.socket.readyState !== WebSocket.OPEN) {
@@ -89,6 +140,18 @@ export function createNodeHost(options = {}) {
         error: "WebSocket is no longer open",
       }));
     }
+    if (connection.managed) {
+      try {
+        connection.socket.send(JSON.stringify({ mpp: "message", data: message }));
+        return Promise.resolve(JSON.stringify({ ok: true }));
+      } catch (error) {
+        return Promise.resolve(JSON.stringify({
+          ok: false,
+          reconnectable: connection.socket.readyState !== WebSocket.OPEN,
+          error: errorMessage(error),
+        }));
+      }
+    }
     return new Promise((resolve) => {
       let completed = false;
       const timer = setTimeout(() => finish({
@@ -159,7 +222,8 @@ export function createNodeHost(options = {}) {
         detail: `receive queue exceeded ${maxQueuedMessages} messages or ${maxQueuedBytes} bytes`,
       };
       connection.queue.push({ message: error, bytes: messageBytes(error) });
-      connection.socket.terminate();
+      if (typeof connection.socket.terminate === "function") connection.socket.terminate();
+      else connection.socket.close(1009, "receive queue exceeded configured bounds");
       return;
     }
     connection.queue.push({ message, bytes });
@@ -187,6 +251,7 @@ function queueState(socket) {
     waiter: undefined,
     intentionallyClosed: false,
     overflowed: false,
+    managed: false,
   };
 }
 

package/node/index.d.mts

@@ -1,13 +1,18 @@
 export { Actions } from "../index.mjs";
 export type {
   AgentEvent,
+  CostStatus,
+  EstimatedUsdCost,
   PromptInput,
   PromptItem,
   ReasoningMode,
+  SessionSnapshot,
   Thinking,
   Tool,
   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.1.1",
+  "version": "0.3.0",
   "description": "Viem-style Node and browser bindings for the Nanocodex WASM agent",
   "type": "module",
   "sideEffects": false,
@@ -25,7 +25,6 @@
     "pkg-node",
     "pkg-web",
     "runtime",
-    "scripts/check-package.mjs",
     "internal.mjs",
     "index.d.mts",
     "index.mjs",
@@ -39,7 +38,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,41 +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;
     /**
-     * Start a clean sibling with the same configuration and tools.
+     * Enables or disables priority processing for subsequently accepted turns.
+     *
+     * # Errors
+     *
+     * Rejects after the driver stops.
+     */
+    setFastMode(enabled: boolean): Promise<void>;
+    /**
+     * Changes the reasoning effort for subsequently accepted turns.
+     *
+     * # Errors
+     *
+     * Rejects an invalid effort or a stopped driver.
+     */
+    setThinking(thinking: string): Promise<void>;
+    /**
+     * 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
      *
@@ -58,52 +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>;
     /**
-     * Inject input at this active turn's next safe model boundary.
+     * Injects text input at the active turn's next safe model boundary.
      *
      * # Errors
      *
-     * Rejects for empty input, a queued or terminal turn, a full steer queue,
-     * or a stopped driver.
+     * Rejects if the turn is not active or its driver stopped.
      */
     steer(instruction: string): Promise<void>;
     /**
-     * Inject ordered browser-safe text, image, or audio 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 malformed or empty content, local filesystem inputs, a
-     * queued or terminal turn, a full steer queue, or a stopped driver.
+     * Rejects malformed input or a turn that is no longer active.
      */
     steerContent(content_json: string): Promise<void>;
 }
+
+/**
+ * JavaScript binding over one completed Rust turn result.
+ */
+export class TurnResult {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Serializes this completed boundary's resumable session snapshot.
+     *
+     * # Errors
+     *
+     * Throws when serialization fails.
+     */
+    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;
+}