nanocodex 0.2.0 → 0.3.0

package/README.md

@@ -9,22 +9,36 @@ import { Actions, Agent } from "nanocodex/node";
 
 const agent = await Agent.create({
   apiKey: process.env.OPENAI_API_KEY,
+  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 +91,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 +124,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 +163,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 +198,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.
 
@@ -195,9 +247,16 @@ 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.3.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

@@ -17,9 +17,6 @@ export declare namespace create {
     WebSocketImpl?: typeof WebSocket | undefined;
     apiBaseUrl?: 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;

package/browser/Agent.mjs

@@ -26,14 +26,23 @@ export function create(options = {}) {
     fastMode,
     instructions,
     sessionId,
+    workspace,
     resume,
-    ...hostOptions
+    WebSocketImpl,
+    createWebSocket,
+    tools,
   } = options;
   if (mpp !== undefined && apiKey !== undefined) {
     throw new TypeError("apiKey and mpp are mutually exclusive");
   }
   const events = createEventChannel();
-  const host = createBrowserHost({ ...hostOptions, mpp, onEvent: events.emit });
+  const host = createBrowserHost({
+    WebSocketImpl,
+    createWebSocket,
+    mpp,
+    onEvent: events.emit,
+    tools,
+  });
   activateHost(host);
   const runtime = defineRuntime({
     key: "browser-wasm",
@@ -64,6 +73,7 @@ export function create(options = {}) {
     fastMode,
     instructions,
     sessionId,
+    workspace,
     resume,
   });
 }

package/browser/host.mjs

@@ -3,26 +3,30 @@ 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;
+const WEBSOCKET_OPEN = 1;
 
 export function createBrowserHost(options = {}) {
-  const WebSocketImpl = options.WebSocketImpl || globalThis.WebSocket;
-  if (!WebSocketImpl) throw new Error("WebSocket is unavailable in this runtime");
+  const WebSocketImpl = options.WebSocketImpl ?? globalThis.WebSocket;
+  const createWebSocket = options.createWebSocket
+    ?? (WebSocketImpl && ((endpoint) => new WebSocketImpl(endpoint)));
+  if (!options.mpp && !createWebSocket) {
+    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) {
+  function connect(endpoint, _apiKey, sessionId, metadata = {}) {
     if (options.mpp) return connectMpp(endpoint);
     return new Promise((resolve, reject) => {
       let settled = false;
       const handle = nextHandle++;
-      const socket = createWebSocket(endpoint, sessionId);
+      const socket = createWebSocket(endpoint, sessionId, metadata);
       const connection = {
         socket,
         queue: [],
@@ -97,7 +101,7 @@ export function createBrowserHost(options = {}) {
 
   function send(handle, message) {
     const connection = connections.get(handle);
-    if (!connection || connection.socket.readyState !== WebSocketImpl.OPEN) {
+    if (!connection || connection.socket.readyState !== WEBSOCKET_OPEN) {
       return Promise.resolve(JSON.stringify({
         ok: false,
         reconnectable: true,
@@ -123,7 +127,7 @@ export function createBrowserHost(options = {}) {
     } catch (error) {
       return Promise.resolve(JSON.stringify({
         ok: false,
-        reconnectable: connection.socket.readyState !== WebSocketImpl.OPEN,
+        reconnectable: connection.socket.readyState !== WEBSOCKET_OPEN,
         error: error instanceof Error ? error.message : String(error),
       }));
     }

package/browser/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/index.d.mts

@@ -4,8 +4,10 @@ export type {
   AgentActions,
   AgentEvent,
   AgentOptions,
+  CostStatus,
   DefaultAgent,
   EventWatcher,
+  EstimatedUsdCost,
   ForkOptions,
   PromptInput,
   PromptItem,
@@ -16,5 +18,7 @@ export type {
   ToolContext,
   ToolMap,
   Turn,
+  TurnResult,
+  TurnUsage,
   WatchEventsOptions,
 } from "./types.mjs";