nanocodex 0.1.1 → 0.3.0

package/README.md

@@ -9,29 +9,182 @@ 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);
 
-const branch = await agent.session.fork({ at: turn });
-console.log(await branch.turn.prompt({ input: "Try another approach." }).result());
+await agent.session.setThinking("high");
+await agent.session.setFastMode(true);
+await agent.session.compact();
+
+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
+API key. Pass an MPP session with a `ws(endpoint)` method; an `mppx` Tempo
+session manager has this shape. Nanocodex defaults the socket to
+`wss://openai.mpp.tempo.xyz/v1/responses` when `mpp` is present.
+
+```js
+import { Agent } from "nanocodex/node";
+import { Expiry } from "accounts";
+import { Provider } from "accounts/cli";
+import { tempo } from "mppx/client";
+import { parseUnits } from "viem";
+import { connect } from "viem/experimental/erc7846";
+import WebSocket from "ws";
+
+const pathUsd = "0x20c0000000000000000000000000000000000000";
+const provider = Provider.create({ mpp: false });
+if (!provider.store.persist.hasHydrated()) {
+  await new Promise((resolve) => provider.store.persist.onFinishHydration(resolve));
+}
+const status = await provider.getAccessKeyStatus();
+if (status === "missing" || status === "expired") {
+  await connect(provider.getClient(), {
+    capabilities: { authorizeAccessKey: {
+      expiry: Expiry.days(1),
+      limits: [{ token: pathUsd, limit: parseUnits("25", 6) }],
+    } },
+  });
+}
+const root = provider.getAccount();
+const account = await provider.store.accessKeys.select({
+  account: root.address,
+  chainId: provider.getClient().chain.id,
+});
+if (!account) throw new Error("Tempo account has no usable access key");
+console.error(`Tempo access-key signer: ${account.accessKeyAddress}`);
+const mpp = tempo.session.manager({
+  account,
+  autoSwap: { tokenIn: [pathUsd], slippage: 1 },
+  bootstrap: true,
+  client: provider.getClient(),
+  webSocket: WebSocket,
+  maxDeposit: "0.05",
+  topUpAmount: "0.05",
+});
+
+const agent = await Agent.create({ mpp, thinking: "none", fastMode: true, tools });
+const events = agent.events.watch();
+const unwatch = events.onEvent((event) => {
+  process.stdout.write(`${JSON.stringify(event)}\n`);
+});
+let turn;
+try {
+  turn = agent.turn.prompt({ input: "Build the thing." });
+  const result = await turn.result();
+  console.error(result.finalMessage);
+} finally {
+  turn?.dispose();
+  unwatch();
+  events.off();
+  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");
+  }
+}
 ```
 
+The application still owns its wallet, deposit policy, persisted payment
+channel store, and final settlement. Keep the manager alive to reuse its channel
+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 results can be persisted and resumed by a fresh Node or browser
+agent:
+
+```js
+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,
+so the first resumed request safely replays the committed conversation. Resume
+with the same instructions and tool definitions, and release the original
+agent before handing its snapshot to another writer.
+
+Node embedders whose bundler relocates package assets may compile and pass the
+web-target artifact explicitly. The runtime still uses the Node host for
+WebSockets and Code Mode:
+
+```js
+const module = await WebAssembly.compile(await readFile(wasmAssetPath));
+const agent = await Agent.create({ apiKey, module });
+```
+
+A Codex-compatible rollout can also be resumed by materializing its committed
+`response_item` history into a snapshot with no `request_prefix`. Nanocodex
+rebuilds the current prefix from the supplied instructions and JavaScript tools
+while preserving the rollout's workspace, lineage, cache key, canonical user
+context, and typed history.
+
 `Agent` and `Actions` are module namespaces, not classes. `Agent.create` returns
 an owned client decorated with matching domain actions:
 
 - `agent.turn.prompt(...)` / `Actions.turn.prompt(agent, ...)`
+- `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`.
 
@@ -45,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.
 
@@ -90,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,7 +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 } from "../types.mjs";
+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;
@@ -12,3 +15,12 @@ export function spawn(agent: Agent<object>): Promise<spawn.ReturnType>;
 export declare namespace spawn {
   type ReturnType = DefaultAgent;
 }
+
+/** Changes the reasoning effort for subsequently accepted turns. */
+export function setThinking(agent: Agent<object>, thinking: Thinking): Promise<void>;
+
+/** 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,4 +1,15 @@
-import { fork as forkAgent, spawn as spawnAgent } from "../internal.mjs";
+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);
@@ -7,3 +18,15 @@ export function fork(agent, options = {}) {
 export function spawn(agent) {
   return spawnAgent(agent);
 }
+
+export function setThinking(agent, thinking) {
+  return setAgentThinking(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, 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,10 +17,22 @@ 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;
+}
+
+/** 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. */

package/actions/turn.mjs

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

package/browser/Agent.d.mts

@@ -1,6 +1,7 @@
 import type {
   AgentOptions,
   DefaultAgent,
+  MppSession,
   ToolMap,
 } from "../types.mjs";
 
@@ -9,14 +10,13 @@ export type Agent = DefaultAgent;
 /** Creates a browser- or Worker-hosted Rust/WASM Agent. */
 export function create(options?: create.Options): Promise<create.ReturnType>;
 export declare namespace create {
-  type Options = AgentOptions & {
+  type Options = AgentOptions & (
+    | { apiKey?: string | undefined; mpp?: never }
+    | { apiKey?: never; mpp: MppSession }
+  ) & {
     WebSocketImpl?: typeof WebSocket | undefined;
     apiBaseUrl?: string | undefined;
-    apiKey?: 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

@@ -16,18 +16,33 @@ let initialized;
 
 export function create(options = {}) {
   const {
-    apiKey = "host-managed",
+    apiKey,
+    mpp,
     websocketUrl,
     apiBaseUrl,
     module,
     thinking,
     reasoningMode,
+    fastMode,
     instructions,
     sessionId,
-    ...hostOptions
+    workspace,
+    resume,
+    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, onEvent: events.emit });
+  const host = createBrowserHost({
+    WebSocketImpl,
+    createWebSocket,
+    mpp,
+    onEvent: events.emit,
+    tools,
+  });
   activateHost(host);
   const runtime = defineRuntime({
     key: "browser-wasm",
@@ -39,8 +54,10 @@ export function create(options = {}) {
       await initialized;
       activateHost(host);
       return new Nanocodex(JSON.stringify(toWasmConfig({
-        apiKey,
-        websocketUrl,
+        apiKey: apiKey ?? (mpp === undefined ? "host-managed" : "mpp-managed"),
+        websocketUrl: websocketUrl ?? (mpp === undefined
+          ? undefined
+          : "wss://openai.mpp.tempo.xyz/v1/responses"),
         apiBaseUrl,
         ...config,
       })));
@@ -50,5 +67,13 @@ export function create(options = {}) {
     release: (raw) => releaseHostSession(host, raw.sessionId),
     decorate: (agent) => agent.extend(agentActions()),
   });
-  return createAgentClient(runtime, { thinking, reasoningMode, instructions, sessionId });
+  return createAgentClient(runtime, {
+    thinking,
+    reasoningMode,
+    fastMode,
+    instructions,
+    sessionId,
+    workspace,
+    resume,
+  });
 }