nanocodex 0.2.0 → 0.4.0

package/README.md

@@ -9,22 +9,37 @@ import { Actions, Agent } from "nanocodex/node";
 
 const agent = await Agent.create({
   apiKey: process.env.OPENAI_API_KEY,
+  model: "gpt-5.6-luna",
+  instructions: "You are a Rust coding agent. Preserve unrelated work and run relevant tests.",
   reasoningMode: "pro",
   thinking: "high",
   tools,
+  workspace: process.cwd(),
 });
 
 const turn = agent.turn.prompt({ input: "Build the thing." });
-console.log(await turn.result());
+const result = await turn.result();
+turn.dispose();
+console.log(result.finalMessage);
+console.log(result.usage);
+console.log(result.usage.estimated_cost?.usd);
+console.log(result.usage.cost_status);
 
 await agent.session.setThinking("high");
 await agent.session.setFastMode(true);
+await agent.session.compact();
 
-const branch = await agent.session.fork({ at: turn });
-console.log(await branch.turn.prompt({ input: "Try another approach." }).result());
+const branch = await agent.session.fork({ at: result });
+const branchTurn = branch.turn.prompt({ input: "Try another approach." });
+const branchResult = await branchTurn.result();
+branchTurn.dispose();
+console.log(branchResult.finalMessage);
 
 const followOn = Actions.turn.prompt(agent, { input: "Now explain it." });
-console.log(await Actions.turn.getResult(followOn));
+console.log((await Actions.turn.getResult(followOn)).finalMessage);
+followOn.dispose();
+await branch.session.shutdown();
+await agent.session.shutdown();
 ```
 
 Node and browser applications can instead pay through MPP without an OpenAI
@@ -77,13 +92,30 @@ const events = agent.events.watch();
 const unwatch = events.onEvent((event) => {
   process.stdout.write(`${JSON.stringify(event)}\n`);
 });
+let turn;
 try {
-  console.error(await agent.turn.prompt({ input: "Build the thing." }).result());
+  turn = agent.turn.prompt({ input: "Build the thing." });
+  const result = await turn.result();
+  console.error(result.finalMessage);
 } finally {
-  await mpp.close();
+  turn?.dispose();
   unwatch();
   events.off();
-  agent.dispose();
+  const cleanupErrors = [];
+  try {
+    await agent.session.shutdown();
+  } catch (error) {
+    cleanupErrors.push(error);
+  }
+  try {
+    await mpp.close();
+  } catch (error) {
+    cleanupErrors.push(error);
+  }
+  if (cleanupErrors.length === 1) throw cleanupErrors[0];
+  if (cleanupErrors.length > 1) {
+    throw new AggregateError(cleanupErrors, "agent shutdown and MPP settlement both failed");
+  }
 }
 ```
 
@@ -93,17 +125,19 @@ across agents, and supply mppx `channelStore` for reuse after a process or page
 restart. Nanocodex never closes a caller-owned MPP session. `apiKey` and `mpp`
 are mutually exclusive.
 
-Completed turns can be persisted and resumed by a fresh Node or browser agent:
+Completed results can be persisted and resumed by a fresh Node or browser
+agent:
 
 ```js
-const snapshot = turn.snapshot();
-agent.dispose();
+const snapshot = result.snapshot;
+await agent.session.shutdown();
 
 const resumed = await Agent.create({
   apiKey: process.env.OPENAI_API_KEY,
   resume: snapshot,
   tools,
 });
+await resumed.session.shutdown();
 ```
 
 The snapshot contains authoritative typed history but no provider response ID,
@@ -130,13 +164,28 @@ context, and typed history.
 an owned client decorated with matching domain actions:
 
 - `agent.turn.prompt(...)` / `Actions.turn.prompt(agent, ...)`
-- `turn.snapshot()` / `Actions.turn.getSnapshot(turn)`
+- `turn.result()` / `Actions.turn.getResult(turn)`
+- `result.snapshot` / `Actions.turn.getSnapshot(result)`
+- `result.usage` / `Actions.turn.getUsage(result)`
 - `agent.session.fork(...)` / `Actions.session.fork(agent, ...)`
+- `agent.session.compact()` / `Actions.session.compact(agent)`
 - `agent.session.setThinking(...)` / `Actions.session.setThinking(agent, ...)`
 - `agent.session.setFastMode(...)` / `Actions.session.setFastMode(agent, ...)`
+- `agent.session.shutdown()` / `Actions.session.shutdown(agent)`
 - `agent.session.spawn()` / `Actions.session.spawn(agent)`
 - `agent.events.watch(...)` / `Actions.events.watch(agent, ...)`
 
+`turn.result()` resolves to a frozen completed `TurnResult`. Its
+`finalMessage` is eager; `usage` and `snapshot` cross the WASM boundary lazily
+once and are then cached. Historical `fork({ at })` accepts this completed
+result, never an unfinished turn or a provider response ID.
+
+`turn.dispose()` only releases the JavaScript/WASM handle; like dropping the
+Rust `Turn`, it does not cancel accepted work. Await `turn.cancel()` before
+disposing unfinished work. At an application or session boundary,
+`agent.session.shutdown()` cancels unfinished turns and joins driver, model,
+tool, and transport cleanup.
+
 Every action owns its types, for example `Actions.turn.prompt.Options`,
 `Actions.turn.prompt.ReturnType`, and `Actions.events.watch.Watcher`.
 
@@ -150,6 +199,10 @@ unlisten();
 watch.off();
 ```
 
+A throwing callback is reported through the host's `reportError` hook (or
+`console.error` when that hook is unavailable) without interrupting later
+listeners or the owned agent lifecycle.
+
 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.
 
@@ -190,14 +243,59 @@ const agent = await Agent.create({
 });
 ```
 
+Server-side Worker runtimes can await a `fetch()`-based WebSocket upgrade. The
+third callback argument is a discriminated authorization request plus connection
+metadata. With `apiKey`, `authorization` is `"bearer"` and `bearerToken` is
+present. With `hostAuth: true`, it is `"host_managed"`; the host must resolve
+credentials without exposing them to WASM. Do not retain or log bearer tokens.
+Return the socket alone or a descriptor containing response metadata:
+
+```js
+import { Agent } from "nanocodex/browser";
+import module from "nanocodex/wasm";
+
+const agent = await Agent.create({
+  apiKey,
+  module,
+  async createWebSocket(endpoint, sessionId, request) {
+    if (request.authorization !== "bearer") {
+      throw new Error("this host requires Nanocodex bearer authorization");
+    }
+    const response = await fetch(endpoint.replace("wss:", "https:"), {
+      headers: {
+        Authorization: `Bearer ${request.bearerToken}`,
+        Upgrade: "websocket",
+        "session-id": sessionId,
+      },
+    });
+    if (!response.webSocket) throw new Error(`upgrade failed: ${response.status}`);
+    response.webSocket.accept();
+    return { socket: response.webSocket, status: response.status };
+  },
+});
+```
+
+`hostAuth` is useful when the embedding runtime owns rotating credentials. The
+callback can acquire a fresh token, attempt the upgrade, and refresh-and-retry
+on 401. Bound and reject upgrade work in the callback: until it returns a
+socket, there is no connection handle for Nanocodex to close. `apiKey`,
+`hostAuth`, and `mpp` are mutually exclusive.
+
 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";
+  import { Agent } from "https://cdn.jsdelivr.net/npm/nanocodex@0.4.0/browser/index.mjs";
   const agent = await Agent.create({ websocketUrl: "/api/responses" });
-  console.log(await agent.turn.prompt({ input: "Hello." }).result());
+  const turn = agent.turn.prompt({ input: "Hello." });
+  try {
+    const result = await turn.result();
+    console.log(result.finalMessage);
+  } finally {
+    turn.dispose();
+    await agent.session.shutdown();
+  }
 </script>
 ```
 

package/actions/events.mjs

@@ -1,19 +1,34 @@
 import { subscribeAgentEvents } from "../internal.mjs";
 
+const MAX_BUFFERED_EVENTS = 4_096;
+const MAX_BUFFERED_EVENT_CHARACTERS = 32 * 1024 * 1024;
+
 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 emit = (event, encodedLength) => {
+    for (const listener of listeners) {
+      try {
+        listener(event);
+      } catch (error) {
+        reportListenerError(error);
+      }
+    }
+    for (const iterator of iterators) iterator.push(event, encodedLength);
   };
 
   const start = () => {
     if (closed || unsubscribe) return;
-    unsubscribe = subscribeAgentEvents(agent, emit, options);
+    unsubscribe = subscribeAgentEvents(agent, emit, options, () => watcher.off());
+  };
+
+  const stopIfIdle = () => {
+    if (listeners.size || iterators.size) return;
+    unsubscribe?.();
+    unsubscribe = undefined;
   };
 
   const watcher = {
@@ -22,7 +37,10 @@ export function watch(agent, options = {}) {
       if (closed) return () => {};
       listeners.add(listener);
       start();
-      return () => listeners.delete(listener);
+      return () => {
+        listeners.delete(listener);
+        stopIfIdle();
+      };
     },
     off() {
       if (closed) return;
@@ -35,7 +53,10 @@ export function watch(agent, options = {}) {
     },
     [Symbol.asyncIterator]() {
       if (closed) return emptyIterator();
-      const iterator = eventIterator(() => iterators.delete(iterator));
+      const iterator = eventIterator(() => {
+        iterators.delete(iterator);
+        stopIfIdle();
+      });
       iterators.add(iterator);
       start();
       return iterator;
@@ -46,32 +67,82 @@ export function watch(agent, options = {}) {
 
 function eventIterator(onEnd) {
   const queue = [];
-  let pending;
-  let done = false;
+  let head = 0;
+  let bufferedCharacters = 0;
+  const pending = [];
+  let pendingHead = 0;
+  let ended = false;
+  let failure;
+  let failureReported = false;
+  let detached = false;
+
+  const detach = () => {
+    if (detached) return;
+    detached = true;
+    onEnd();
+  };
 
   const iterator = {
-    push(event) {
-      if (done) return;
-      if (pending) {
-        const resolve = pending;
-        pending = undefined;
+    push(event, encodedLength) {
+      if (ended || failure) return;
+      if (pendingHead < pending.length) {
+        const resolve = pending[pendingHead++];
+        if (pendingHead === pending.length) {
+          pending.length = 0;
+          pendingHead = 0;
+        }
         resolve({ done: false, value: event });
       } else {
-        queue.push(event);
+        const characters = encodedLength ?? JSON.stringify(event).length;
+        if (
+          queue.length - head >= MAX_BUFFERED_EVENTS
+          || bufferedCharacters + characters > MAX_BUFFERED_EVENT_CHARACTERS
+        ) {
+          failure = new RangeError(
+            `event iterator exceeded its private buffer of ${MAX_BUFFERED_EVENTS} events or `
+              + `${MAX_BUFFERED_EVENT_CHARACTERS} serialized characters`,
+          );
+          detach();
+          return;
+        }
+        queue.push({ characters, event });
+        bufferedCharacters += characters;
       }
     },
     end() {
-      if (done) return;
-      done = true;
-      onEnd();
-      pending?.({ done: true, value: undefined });
-      pending = undefined;
+      if (ended) return;
+      ended = true;
+      detach();
+      while (pendingHead < pending.length) {
+        pending[pendingHead++]({ done: true, value: undefined });
+      }
+      pending.length = 0;
+      pendingHead = 0;
       queue.length = 0;
+      head = 0;
+      bufferedCharacters = 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; });
+      if (head < queue.length) {
+        const entry = queue[head++];
+        bufferedCharacters -= entry.characters;
+        if (head === queue.length) {
+          queue.length = 0;
+          head = 0;
+        }
+        return Promise.resolve({ done: false, value: entry.event });
+      }
+      if (failure && !failureReported) {
+        failureReported = true;
+        return Promise.reject(failure);
+      }
+      if (ended || failure) return Promise.resolve({ done: true, value: undefined });
+      if (pending.length - pendingHead >= MAX_BUFFERED_EVENTS) {
+        return Promise.reject(new RangeError(
+          `event iterator exceeded its private buffer of ${MAX_BUFFERED_EVENTS} pending reads`,
+        ));
+      }
+      return new Promise((resolve) => { pending.push(resolve); });
     },
     return() {
       iterator.end();
@@ -89,3 +160,15 @@ function emptyIterator() {
     [Symbol.asyncIterator]() { return this; },
   };
 }
+
+function reportListenerError(error) {
+  try {
+    if (typeof globalThis.reportError === "function") {
+      globalThis.reportError(error);
+      return;
+    }
+  } catch {}
+  try {
+    globalThis.console?.error?.("Nanocodex event listener failed", error);
+  } catch {}
+}

package/actions/index.mjs

@@ -10,9 +10,11 @@ export function agentActions() {
       watch: (options) => events.watch(agent, options),
     },
     session: {
+      compact: () => session.compact(agent),
       fork: (options) => session.fork(agent, options),
       setFastMode: (enabled) => session.setFastMode(agent, enabled),
       setThinking: (thinking) => session.setThinking(agent, thinking),
+      shutdown: () => session.shutdown(agent),
       spawn: () => session.spawn(agent),
     },
     turn: {

package/actions/session.d.mts

@@ -1,6 +1,9 @@
 import type { Agent, DefaultAgent, ForkOptions, Thinking } from "../types.mjs";
 
-/** Forks the latest checkpoint, or the exact completed Turn supplied in `options.at`. */
+/** Compacts retained history immediately without fabricating a user prompt. */
+export function compact(agent: Agent<object>): Promise<void>;
+
+/** Forks the latest checkpoint, or the exact completed result supplied in `options.at`. */
 export function fork(agent: Agent<object>, options?: fork.Options): Promise<fork.ReturnType>;
 export declare namespace fork {
   type Options = ForkOptions;
@@ -18,3 +21,6 @@ export function setThinking(agent: Agent<object>, thinking: Thinking): Promise<v
 
 /** Enables or disables priority processing for subsequently accepted turns. */
 export function setFastMode(agent: Agent<object>, enabled: boolean): Promise<void>;
+
+/** Stops the driver and joins every resource owned by this Agent. */
+export function shutdown(agent: Agent<object>): Promise<void>;

package/actions/session.mjs

@@ -1,10 +1,16 @@
 import {
+  compact as compactAgent,
   fork as forkAgent,
   setFastMode as setAgentFastMode,
   setThinking as setAgentThinking,
+  shutdown as shutdownAgent,
   spawn as spawnAgent,
 } from "../internal.mjs";
 
+export function compact(agent) {
+  return compactAgent(agent);
+}
+
 export function fork(agent, options = {}) {
   return forkAgent(agent, options);
 }
@@ -20,3 +26,7 @@ export function setThinking(agent, thinking) {
 export function setFastMode(agent, enabled) {
   return setAgentFastMode(agent, enabled);
 }
+
+export function shutdown(agent) {
+  return shutdownAgent(agent);
+}

package/actions/turn.d.mts

@@ -1,4 +1,11 @@
-import type { Agent, PromptInput, SessionSnapshot, Turn } from "../types.mjs";
+import type {
+  Agent,
+  PromptInput,
+  SessionSnapshot,
+  Turn,
+  TurnResult,
+  TurnUsage,
+} from "../types.mjs";
 
 /** Accepts a prompt on an owned Agent and returns its independently awaitable Turn. */
 export function prompt<const agent extends Agent<object>>(
@@ -10,18 +17,24 @@ export declare namespace prompt {
   type ReturnType<agent extends Agent<object> = Agent<object>> = Turn<agent>;
 }
 
-/** Waits for a Turn's final assistant message. */
+/** Waits for a Turn's typed completed result. */
 export function getResult(turn: Turn): Promise<getResult.ReturnType>;
 export declare namespace getResult {
-  type ReturnType = string;
+  type ReturnType = TurnResult;
 }
 
-/** Copies a completed Turn into a serializable session snapshot. */
-export function getSnapshot(turn: Turn): getSnapshot.ReturnType;
+/** Returns a completed result's serializable session snapshot. */
+export function getSnapshot(result: TurnResult): getSnapshot.ReturnType;
 export declare namespace getSnapshot {
   type ReturnType = SessionSnapshot;
 }
 
+/** Returns exact aggregate token usage from a completed result. */
+export function getUsage(result: TurnResult): getUsage.ReturnType;
+export declare namespace getUsage {
+  type ReturnType = TurnUsage;
+}
+
 /** Adds input to an active Turn. */
 export function steer(turn: Turn, options: steer.Options): Promise<void>;
 export declare namespace steer {

package/actions/turn.mjs

@@ -2,6 +2,7 @@ import {
   cancel as cancelTurn,
   getTurnResult,
   getTurnSnapshot,
+  getTurnUsage,
   prompt as promptTurn,
   steer as steerTurn,
 } from "../internal.mjs";
@@ -14,8 +15,12 @@ export function getResult(turn) {
   return getTurnResult(turn);
 }
 
-export function getSnapshot(turn) {
-  return getTurnSnapshot(turn);
+export function getSnapshot(result) {
+  return getTurnSnapshot(result);
+}
+
+export function getUsage(result) {
+  return getTurnUsage(result);
 }
 
 export function steer(turn, options) {

package/browser/Agent.d.mts

@@ -4,6 +4,10 @@ import type {
   MppSession,
   ToolMap,
 } from "../types.mjs";
+import type {
+  BrowserWebSocketConnection,
+  BrowserWebSocketRequest,
+} from "./host.mjs";
 
 export type Agent = DefaultAgent;
 
@@ -11,17 +15,21 @@ export type Agent = DefaultAgent;
 export function create(options?: create.Options): Promise<create.ReturnType>;
 export declare namespace create {
   type Options = AgentOptions & (
-    | { apiKey?: string | undefined; mpp?: never }
-    | { apiKey?: never; mpp: MppSession }
+    | { apiKey?: string | undefined; hostAuth?: never; mpp?: never }
+    | { apiKey?: never; hostAuth?: true; mpp?: never }
+    | { apiKey?: never; hostAuth?: never; mpp: MppSession }
   ) & {
     WebSocketImpl?: typeof WebSocket | undefined;
     apiBaseUrl?: string | undefined;
-    createWebSocket?(endpoint: string, sessionId: string): WebSocket;
-    maxBufferedSendBytes?: number | undefined;
-    maxQueuedBytes?: number | undefined;
-    maxQueuedMessages?: number | undefined;
+    createWebSocket?(
+      endpoint: string,
+      sessionId: string,
+      request: BrowserWebSocketRequest,
+    ): WebSocket | BrowserWebSocketConnection | Promise<WebSocket | BrowserWebSocketConnection>;
     module?: unknown;
     tools?: ToolMap | undefined;
+    /** Direct dispatch is CSP-safe; Code Mode requires dynamic JavaScript evaluation. */
+    toolMode?: "code" | "direct" | undefined;
     websocketUrl?: string | undefined;
   };
   type ReturnType = Agent;

package/browser/Agent.mjs

@@ -17,23 +17,40 @@ let initialized;
 export function create(options = {}) {
   const {
     apiKey,
+    hostAuth,
     mpp,
     websocketUrl,
     apiBaseUrl,
     module,
+    model,
     thinking,
     reasoningMode,
     fastMode,
     instructions,
     sessionId,
+    workspace,
     resume,
-    ...hostOptions
+    WebSocketImpl,
+    createWebSocket,
+    tools,
+    toolMode,
   } = options;
   if (mpp !== undefined && apiKey !== undefined) {
     throw new TypeError("apiKey and mpp are mutually exclusive");
   }
+  if (hostAuth && (apiKey !== undefined || mpp !== undefined)) {
+    throw new TypeError("hostAuth is mutually exclusive with apiKey and mpp");
+  }
   const events = createEventChannel();
-  const host = createBrowserHost({ ...hostOptions, mpp, onEvent: events.emit });
+  const host = createBrowserHost({
+    WebSocketImpl,
+    createWebSocket,
+    hostAuth: hostAuth === true || (apiKey === undefined && mpp === undefined),
+    mpp,
+    onEvent: events.emit,
+    tools,
+    toolMode,
+  });
   activateHost(host);
   const runtime = defineRuntime({
     key: "browser-wasm",
@@ -59,11 +76,13 @@ export function create(options = {}) {
     decorate: (agent) => agent.extend(agentActions()),
   });
   return createAgentClient(runtime, {
+    model,
     thinking,
     reasoningMode,
     fastMode,
     instructions,
     sessionId,
+    workspace,
     resume,
   });
 }

package/browser/host.d.mts

@@ -9,9 +9,41 @@ export type BrowserTool = {
 
 export type BrowserToolMap = Record<string, BrowserTool>;
 
+type BrowserWebSocketMetadata = {
+  accountId?: string | undefined;
+  fedramp?: boolean | undefined;
+  turnState?: string | undefined;
+};
+
+export type BrowserWebSocketRequest = BrowserWebSocketMetadata & (
+  | {
+    authorization: "bearer";
+    /** Resolved credential for this handshake. Do not retain or log it. */
+    bearerToken: string;
+  }
+  | {
+    authorization: "host_managed";
+    bearerToken?: never;
+  }
+);
+
+export type BrowserWebSocketConnection = {
+  socket: WebSocket;
+  status?: number | undefined;
+  requestId?: string | undefined;
+  serverModel?: string | undefined;
+  reasoningIncluded?: boolean | undefined;
+  turnState?: string | undefined;
+};
+
 export function createBrowserHost(options?: {
   WebSocketImpl?: typeof WebSocket;
-  createWebSocket?: (endpoint: string, sessionId: string) => WebSocket;
+  hostAuth?: boolean;
+  createWebSocket?: (
+    endpoint: string,
+    sessionId: string,
+    request: BrowserWebSocketRequest,
+  ) => WebSocket | BrowserWebSocketConnection | Promise<WebSocket | BrowserWebSocketConnection>;
   onEvent?: (eventJson: string) => void;
   tools?: BrowserToolMap;
   maxQueuedMessages?: number;