nanocodex 0.6.1 → 0.6.5

package/README.md

@@ -10,7 +10,7 @@ import { Actions, Agent, Transport } from "nanocodex/node";
 
 const agent = await Agent.create({
   transport: Transport.openAi({ apiKey: process.env.OPENAI_API_KEY }),
-  model: "gpt-5.6-luna",
+  model: "gpt-6-luna",
   instructions: "You are a Rust coding agent. Preserve unrelated work and run relevant tests.",
   reasoningMode: "pro",
   thinking: "high",
@@ -80,6 +80,23 @@ Worker, Durable Object, or application proxy that owns rotating credentials.
 Authentication modes are constructors rather than a union of mutually
 exclusive fields on `Agent.create`.
 
+### Personal memories and caller context
+
+Managed agents can keep user preferences separate from team knowledge:
+
+```js
+import { Agent } from "nanocodex/managed";
+
+await Agent.memory({ operation: "scan", query: "my preferences" }, { scope: "personal" });
+await Agent.memory({ operation: "put", content: "I prefer concise replies." }, { scope: "personal" });
+```
+
+The default scope remains `team`. Personal memories belong to the authenticated
+user within their organization, across teams; use the same scope when reading,
+replacing, or deleting a memory. Managed clients also accept descriptive
+`requestOrigin: { client: "desktop", hand: "user:HAND_ID", cwd: "/HAND_ID" }`.
+Caller context is included once at startup and never grants execution authority.
+
 ### Compose and place tools
 
 `createTools` owns one deterministic tool recipe. Custom functions, a portable
@@ -158,8 +175,11 @@ workspace or MCP configuration to an Agent that already receives them through
 `Tools`.
 
 Browser consumers can attach Codex's ChatGPT Realtime voice lifecycle to the
-same retained Agent. The resource owns microphone, speaker, WebRTC, sideband,
+same retained Agent. The resource owns microphone, speaker, WebRTC control,
 and delegation cleanup; stopping voice does not cancel an active coding turn.
+Managed and Connect voice use the WebRTC data channel for live events and
+commands. Speech and captions can flow while durable startup completes;
+delegated work still waits for admission. Local Agents retain the sideband path.
 Snapshots update each speaker's transcript row as speech arrives, using a stable
 `id` and `isPartial` flag. Completion replaces that row. `transcript.delta` events
 carry the current partial text; `transcript` events retain completed-turn semantics.
@@ -214,15 +234,22 @@ subscription adapter (which treats all roles as context), and
 `appendContext(voice, text)` adds background commentary without
 requesting speech. Context and speech are split into provider-sized messages.
 These commands retain frames until sent and preserve them
-across a sideband reconnect. They are also methods on the resource and on
-`useVoice` from `nanocodex-react`. These settings use ChatGPT subscription voice;
-custom voices and Platform audio configuration are not accepted.
+across reconnects when using the sideband transport. They are also methods on
+the resource and on
+`useVoice` from `nanocodex-react`. Choose `outputProvider: "elevenlabs"` and `elevenLabsVoiceId` to synthesize
+spoken output with an ElevenLabs account voice, including an instant clone.
+The account voice settings panel connects the API key, lists voices, and uploads
+cloning samples after explicit consent. Keys are encrypted on the server and
+never included in saved voice settings. ChatGPT still owns live input and agent
+handoffs; `voice` continues to select its built-in voice. The default output
+provider is `openai`. Platform audio configuration is not accepted.
 
 `Voice.create(...)` remains the equivalent namespaced resource constructor, and
 `Voice.voices` is the exact ChatGPT V3 voice catalog. The constructor accepts a
 normal browser Agent, an account-owned managed Agent, or a grant-scoped
-`ConnectAgent`. Authentication stays in the owning host routes; Connect uses a
-fresh one-use sideband ticket, and the browser binding never receives ChatGPT
+`ConnectAgent`. Authentication stays in the owning host routes. An explicit
+`sidebandUrl` override selects the sideband transport; Connect uses a fresh
+one-use ticket for that path. The browser binding never receives ChatGPT
 credentials or places its reusable grant bearer in a WebSocket URL.
 
 ### Durable Cloudflare Agent
@@ -280,10 +307,12 @@ Cloudflare Agents default to direct tool mode because Workers prohibit dynamic
 `eval`/`new Function`. Caller-defined tools therefore work without a code
 evaluator. Select `toolMode: "code"` only when also supplying an evaluator that
 is explicitly compatible with the deployed Worker runtime. Runtime-owned
-Subagents are installed by default, including on a durable root. Clean children
-persist independent execution state under their own agent session IDs. The
-Rust task-tree registry remains in memory and is closed with the live root, so
-tree-local IDs and topology are not reconstructed from those agent states. Use
+Subagents are installed by default, including on a durable root. All children are
+ephemeral: their identities, topology, conversations, results, and routing exist
+only for the lifetime of the root runtime. Root shutdown or restart discards the
+entire child tree; only the root's own durable history resumes. Existing child
+checkpoints from older versions are discarded. Within a live runtime, completed
+children remain available for follow-up messages until closed. Use
 `Subagents.create({ maxConcurrency })` in `tools` to set an explicit finite
 concurrency limit. Active subagent turns are unlimited by default.
 
@@ -327,6 +356,11 @@ native and WASM consumers run the same Rust implementation and receive the
 same seven tools: `spawn_agent`, `submit_result`, `send_agent_message`,
 `list_agents`, `wait_agent`, `interrupt_agent`, and `close_agent`.
 
+Children call `submit_result({output})`; the runtime supplies the trusted
+instruction revision. The response is `{accepted: true, status: "accepted"}` or
+`{accepted: false, status: "superseded"}`. Superseded submissions are normal
+continuations: incorporate the updated instructions and submit again.
+
 Inside a caller-owned Worker or server isolate, host capabilities stay as
 ordinary functions without crossing another compatibility protocol:
 
@@ -500,7 +534,7 @@ use the individual factories in server-side Cloudflare Workers. Vite integration
 is provided separately by `nanocodex-vite`.
 
 The browser composition includes native `browseX` public X browsing, advertised
-by `accountInfo().apis` without an X connector. The embedding app serves
+by `environment().apis` without an X connector. The embedding app serves
 `/api/tools/x/browse` and `/api/tools/x/convert`; Nanocodex's account app forwards
 these requests to the private X Worker.
 
@@ -664,7 +698,7 @@ const mpp = tempoProvider.session;
 
 const agent = await Agent.create({
   transport: Transport.mpp({ session: tempoProvider }),
-  thinking: "none",
+  thinking: "low",
   fastMode: true,
   tools,
 });
@@ -714,8 +748,8 @@ of its wallet adapter, and constructs both payment paths from that provider's
 adapter-neutral `getMppxParameters()` contract. The lower-level
 `createTempoProvider({ session, payment })` remains available when the
 application constructs MPPx itself. Both explicitly select Tempo provider mode.
-In that mode Nanocodex automatically adds its built-in Mercator MCP and wraps it
-with the same wallet and payment policy. The provider also exposes an MPP-aware
+In that mode Nanocodex automatically adds its built-in Mercator MCP at
+`https://mercator.sh/mcp` and wraps it with the same wallet and payment policy. The provider also exposes an MPP-aware
 `fetch`; Mercator's paid REST handoffs use that same method rather than a second
 wallet or payment configuration. Its MCP transport remains wrapped at the MCP
 protocol layer, so browser requests do not need an `Accept-Payment` CORS header.
@@ -1133,7 +1167,7 @@ package manager or build step:
 
 ```html
 <script type="module">
-  import { Agent, Transport } from "https://cdn.jsdelivr.net/npm/nanocodex@0.6.1/host/index.mjs";
+  import { Agent, Transport } from "https://cdn.jsdelivr.net/npm/nanocodex@0.6.5/host/index.mjs";
   const agent = await Agent.create({
     transport: Transport.hostManaged({
       websocketUrl: "/api/responses",
@@ -1183,3 +1217,133 @@ inspect `agent.configuration()`, `environment()`, `usage()`, `requests()`,
 `artifacts`, `webhook`, and `requiredActions`. See the
 [managed configuration and operations guide](../../docs/MANAGED_AGENT_CONFIGURATION.md)
 for examples, authorization, delivery semantics, and runtime limits.
+
+
+## Call connected services from your app
+
+After Nanocodex Connect login, the app and its agents share the same approved
+service capabilities and exact account selections. Request the services during
+login and call them directly without creating an agent or running a turn:
+
+```js
+const connection = await client.connection.connect({
+  capabilities: { cloudAccounts: { spotify: true, soundcloud: true } },
+});
+const response = await client.connectors.spotify.request({
+  path: "/v1/me/playlists?limit=20",
+  // Select an approved account when more than one is connected:
+  connectionId: connection.grant.connectorConnections.spotify[0],
+});
+if (!response.ok) throw new Error(`Spotify returned ${response.status}`);
+const playlists = await response.json();
+```
+
+`client` is a `Client.create(...)` instance from `nanocodex/connect`. For a dynamic service, use
+`client.connectors.request({ connector: "spotify", path: "/v1/me/playlists" })`.
+The standalone form is `Actions.connectors.request(client, options)`.
+Every API service has a scoped entry point, including `client.connectors.gmail`
+and `client.connectors.soundcloud`. The original singular `client.connector.request`
+and `Actions.connector.request` remain supported. Requests support a provider
+path, HTTP method, optional `connectionId`, JSON object `body`, and abort `signal`.
+The response preserves provider HTTP status, body, and pagination/rate-limit
+headers. Writes are never automatically retried.
+
+The underlying API is `POST /v1/connectors/:connector/request` at the configured
+Connect API origin, authenticated with the app's Connect grant bearer token and
+`X-Nanocodex-App-Id`. Browser calls must come from the grant's approved app origin.
+Its JSON body uses `path`, `method`, optional `connection_id`, and optional `body`.
+It requires no conversation or thread ID. Both this endpoint and agent egress
+check current grant revocation, expiry, approved service, and exact account IDs.
+Connecting an account alone does not grant it to every app; the user must approve
+that service in the app's Connect flow. Provider tokens remain in the broker.
+ChatGPT is a model connector and has no generic HTTP endpoint here.
+
+
+### Use a provider SDK with a custom base URL
+
+Native SDKs can use normal HTTP through
+`https://nanocodex.gakonst.workers.dev/connectors/<service>/<provider-path>`.
+All 13 API capabilities share this route. Append the provider's existing path:
+
+| Connector | Example route |
+| --- | --- |
+| Spotify | `/connectors/spotify/v1/me/playlists` |
+| SoundCloud | `/connectors/soundcloud/me/playlists` |
+| Gmail | `/connectors/gmail/gmail/v1/users/me/messages` |
+| Google Drive | `/connectors/gdrive/drive/v3/files` |
+| Google Calendar | `/connectors/gcalendar/calendar/v3/calendars/primary/events` |
+| Google Tasks | `/connectors/gtasks/tasks/v1/users/@me/lists` |
+| Google Docs | `/connectors/gdocs/v1/documents/{id}` |
+| Google Sheets | `/connectors/gsheets/v4/spreadsheets/{id}` |
+| Google Slides | `/connectors/gslides/v1/presentations/{id}` |
+| Google Contacts | `/connectors/gcontacts/v1/people/me/connections?personFields=names` |
+| GitHub | `/connectors/github/user` |
+| Slack | `/connectors/slack/api/auth.test` |
+| X | `/connectors/x/2/users/me` |
+
+Provider path restrictions and upstream OAuth permissions still apply. Google
+services are individually opted in even though they share a Google login.
+ChatGPT and remote MCP connections use their existing separate protocols.
+The same routes are available on the configured Connect API origin.
+
+Send the app's **Nanocodex Connect grant token** as the bearer token. Native
+requests need no extra app identity headers: the token identifies its approved
+app and user. SDK routes also accept `Authorization: OAuth <grant-token>`
+(SoundCloud) and `Authorization: token <grant-token>` (GitHub). Tokens must stay in
+headers, not query parameters. Browser Origins and any explicit app ID must match that grant.
+The grant must already include the requested service; this route cannot connect
+accounts or enlarge the grant. If multiple accounts were approved, set
+`X-Nanocodex-Connector-Connection` to the selected approved connection ID.
+
+For example, with [Spotipy](https://github.com/spotipy-dev/spotipy):
+
+```python
+import spotipy
+
+spotify = spotipy.Spotify(auth=nanocodex_grant_token, retries=0, status_retries=0)
+spotify.prefix = "https://nanocodex.gakonst.workers.dev/connectors/spotify/v1/"
+page = spotify.current_user_playlists(limit=20)
+next_page = spotify.next(page)
+```
+
+For Gmail with Google's [Python API client](https://github.com/googleapis/google-api-python-client):
+
+```python
+from google.oauth2.credentials import Credentials
+from googleapiclient.discovery import build
+
+gmail = build(
+    "gmail", "v1",
+    credentials=Credentials(token=nanocodex_grant_token),
+    client_options={
+        "api_endpoint": "https://nanocodex.gakonst.workers.dev/connectors/gmail/",
+    },
+    cache_discovery=False,
+)
+messages = gmail.users().messages().list(userId="me").execute(num_retries=0)
+```
+
+Use `userId="me"`; Gmail routes are restricted to the connected user. These
+credentials hold only the Connect grant; renew an expired grant through Nanocodex
+Connect instead of asking the provider SDK to refresh it with Google or Spotify.
+SoundCloud clients use `/connectors/soundcloud/` as their base URL and the same
+Connect grant, using [SoundCloud's OAuth header format](https://developers.soundcloud.com/docs).
+
+The proxy preserves request methods, query parameters, and body bytes. Provider
+status codes, JSON errors, rate-limit headers, and non-JSON bodies are preserved.
+API links in JSON, pagination Link headers, and same-provider redirects are
+rewritten through the proxy; artwork and public share URLs stay unchanged.
+Cross-provider redirects are rejected. JSON link rewriting is bounded to 16 MiB
+per response; use provider pagination for larger collections. Spotify GETs share
+one-second read results and the broker's registration-wide rate-limit cooldown.
+The broker retries a rate-limited Spotify GET at most twice within a ten-second
+cooldown-wait budget; longer limits return 429 with the remaining `Retry-After`.
+No writes are automatically retried. Disable SDK write retries to avoid repeating
+a successful write after an ambiguous network failure.
+
+See the runnable [Python example](../../examples/python/spotify_proxy.py).
+The integration test uses real Spotipy 2.26.0 and google-api-python-client 2.192.0
+against the Connect Worker with fixture provider responses, covering reads,
+writes, pagination, rate limits, and revoked grants. Worker tests cover routing
+and service denial for all 13 API connectors. SDKs that hardcode their API host need a custom transport instead of only
+a base URL setting.

package/browser/Agent.d.mts

@@ -33,7 +33,7 @@ export declare namespace create {
     transport: ManagedTransport;
     tools?: Tools | undefined;
   }>;
-  type Options = AgentOptions & WorkerToolExposureOptions & {
+  type Options = Omit<AgentOptions, "beforeCompaction"> & WorkerToolExposureOptions & {
     /** Precompiled browser module; WebAssembly modules are structured-clone-safe. */
     module?: WebAssembly.Module | undefined;
     /** Fixed browser workspace facts, including its AGENTS.md snapshot. */

package/browser/ElevenLabsPlayback.mjs

@@ -0,0 +1,119 @@
+/** Plays account-proxied PCM without exposing provider credentials to the browser. */
+export class ElevenLabsPlayback {
+  #synthesize;
+  #onError;
+  #context;
+  #abort = new AbortController();
+  #queue = Promise.resolve();
+  #sources = new Set();
+  #nextTime = 0;
+  #caption;
+  #offset = 0;
+  #suppressedThrough = -1;
+  #pending = 0;
+  #pendingChars = 0;
+  #closed = false;
+
+  constructor(synthesize, onError) {
+    this.#synthesize = synthesize;
+    this.#onError = onError;
+  }
+
+  prime() {
+    if (this.#closed) return;
+    this.#context ??= new AudioContext({ sampleRate: 24000 });
+    return this.#context.resume();
+  }
+
+  transcript(entry) {
+    if (this.#closed || entry.speaker !== "assistant" || entry.id <= this.#suppressedThrough) return;
+    if (this.#caption !== undefined && entry.id < this.#caption) return;
+    if (entry.id !== this.#caption) { this.#caption = entry.id; this.#offset = 0; }
+    const remaining = entry.text.slice(this.#offset);
+    // Buffer partial words; emit complete sentences before the turn finishes.
+    const boundary = entry.is_partial ? [...remaining.matchAll(/[.!?\n](?:\s|$)/g)].at(-1) : undefined;
+    const length = entry.is_partial ? (boundary ? boundary.index + boundary[0].length : 0) : remaining.length;
+    const text = remaining.slice(0, length).trim();
+    this.#offset += length;
+    if (!text) return;
+    if (this.#pending >= 32 || this.#pendingChars + text.length > 32768) {
+      this.interrupt();
+      this.#onError(new Error("ElevenLabs playback queue exceeded its limit"));
+      return;
+    }
+    this.#pending++;
+    this.#pendingChars += text.length;
+    const signal = this.#abort.signal;
+    this.#queue = this.#queue.then(async () => {
+      if (signal.aborted) return;
+      this.#context ??= new AudioContext({ sampleRate: 24000 });
+      await this.#context.resume();
+      if (signal.aborted) return;
+      const response = await this.#synthesize(text, signal);
+      if (!response.ok) throw new Error(`ElevenLabs synthesis failed (${response.status})`);
+      const reader = response.body?.getReader();
+      if (!reader) throw new Error("ElevenLabs returned no audio stream");
+      const cancel = () => { void reader.cancel().catch(() => {}); };
+      signal.addEventListener("abort", cancel, { once: true });
+      let carry;
+      try {
+        while (!signal.aborted) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          if (signal.aborted) break;
+          if (value.byteLength > 1024 * 1024) throw new Error("ElevenLabs audio chunk exceeded its limit");
+          const bytes = carry === undefined ? value : Uint8Array.from([carry, ...value]);
+          const size = bytes.length - bytes.length % 2;
+          carry = size < bytes.length ? bytes[size] : undefined;
+          if (!size) continue;
+          // Keep decoded/scheduled audio bounded even when synthesis outruns playback.
+          for (let offset = 0; offset < size && !signal.aborted; offset += 9600) {
+            while (!signal.aborted && (this.#nextTime - this.#context.currentTime > 2 || this.#sources.size >= 128)) {
+              await new Promise((resolve) => {
+                const done = () => { clearTimeout(timer); signal.removeEventListener("abort", done); resolve(); };
+                const timer = setTimeout(done, 25);
+                signal.addEventListener("abort", done, { once: true });
+              });
+            }
+            if (signal.aborted) break;
+            const length = Math.min(9600, size - offset);
+            const buffer = this.#context.createBuffer(1, length / 2, 24000);
+            const output = buffer.getChannelData(0);
+            const view = new DataView(bytes.buffer, bytes.byteOffset + offset, length);
+            for (let i = 0; i < output.length; i++) output[i] = view.getInt16(i * 2, true) / 32768;
+            const source = this.#context.createBufferSource();
+            source.buffer = buffer;
+            source.connect(this.#context.destination);
+            this.#sources.add(source);
+            source.onended = () => { this.#sources.delete(source); source.disconnect(); };
+            this.#nextTime = Math.max(this.#nextTime, this.#context.currentTime + 0.02);
+            source.start(this.#nextTime);
+            this.#nextTime += buffer.duration;
+          }
+        }
+      } finally { signal.removeEventListener("abort", cancel); await reader.cancel().catch(() => {}); reader.releaseLock(); }
+    }).catch((error) => { if (!signal.aborted) this.#onError(error); }).finally(() => {
+      if (!signal.aborted) { this.#pending--; this.#pendingChars -= text.length; }
+    });
+  }
+
+  interrupt() {
+    this.#suppressedThrough = Math.max(this.#suppressedThrough, this.#caption ?? -1);
+    this.#pending = 0;
+    this.#pendingChars = 0;
+    this.#abort.abort();
+    this.#abort = new AbortController();
+    this.#queue = Promise.resolve();
+    for (const source of this.#sources) { try { source.stop(); } catch {} source.disconnect(); }
+    this.#sources.clear();
+    this.#nextTime = 0;
+    // Caption IDs are monotonic: every late delta/final for this epoch stays silent.
+  }
+
+  close() {
+    this.#closed = true;
+    this.interrupt();
+    void this.#context?.close();
+    this.#context = undefined;
+  }
+}

package/browser/InlineAgent.mjs

@@ -16,6 +16,7 @@ import {
   registerDefinitionHost,
   releaseDefinitionHost,
   releaseHostSession,
+  releaseHostSessions,
   toWasmConfig,
 } from "../internal.mjs";
 import { createBrowserHost } from "./host.mjs";
@@ -45,8 +46,10 @@ export async function create(options = {}) {
     thinking,
     reasoningMode,
     fastMode,
+    rawApiEvents,
     instructions,
     additionalInstructions,
+    beforeCompaction,
     sessionId,
     workspace,
     resume,
@@ -75,8 +78,10 @@ export async function create(options = {}) {
     websocketPreconnect,
     apiBaseUrl,
     websocketWarmup,
+    stateless,
     WebSocketImpl,
     createWebSocket,
+    createResponse,
   } = resolveResponsesTransport(transport ?? defaultHostManagedTransport());
   const subagentsEnabled = internalRuntime?.subagentsEnabled;
   if (subagentsEnabled !== undefined && typeof subagentsEnabled !== "boolean") {
@@ -109,16 +114,20 @@ export async function create(options = {}) {
   const host = createBrowserHost({
     WebSocketImpl,
     createWebSocket,
+    createResponse,
     hostAuth: hostAuth === true
       || (apiKey === undefined && mpp === undefined && subscription === undefined),
     hostManagedProtocol,
     mpp,
     onEvent: events.emit,
+    beforeCompaction,
     filesystem,
     filesystemTools,
     tools: hostTools,
     toolProviders,
     subagentSessions,
+    subagentRouting: internalRuntime?.subagentRouting,
+    onSocketTiming: internalRuntime?.onSocketTiming,
     toolMode,
     mcp: mcp === false
       ? undefined
@@ -161,8 +170,11 @@ export async function create(options = {}) {
             : "wss://openai.mpp.tempo.xyz/v1/responses"),
           apiBaseUrl,
           websocketWarmup,
+          stateless,
           subagents: subagentConfig,
+          subagentRouting: internalRuntime?.subagentRouting !== undefined,
           hostDefinitionId,
+          beforeCompaction: beforeCompaction !== undefined,
           ...config,
           durabilityHostId: durabilityOwner?.id,
         }));
@@ -174,29 +186,19 @@ export async function create(options = {}) {
             );
         if (cloudflareReservation !== undefined) {
           activateCloudflareAgentSession(cloudflareReservation);
-          const restoredSubagents = subagentSessions?.restore?.() ?? [];
-          if (restoredSubagents.length > 0) {
-            const restoredHostContextRefs = Object.fromEntries(
-              restoredSubagents.map((descriptor) => {
-                const hostContextRef = subagentSessions?.hostContextRef?.(descriptor.sessionId);
-                return [descriptor.sessionId, hostContextRef ?? null];
-              }),
-            );
-            await raw.restoreSubagents(
-              JSON.stringify(restoredSubagents),
-              JSON.stringify(restoredHostContextRefs),
-            );
-          }
         }
         return raw;
       } catch (error) {
         const cleanupErrors = [];
         if (raw !== undefined) {
-          try { await raw.shutdown(); }
+          try {
+            await raw.shutdown();
+          }
           catch (cleanupError) { cleanupErrors.push(cleanupError); }
           try { raw.free(); }
           catch (cleanupError) { cleanupErrors.push(cleanupError); }
         }
+        releaseHostSessions(host);
         try { durabilityOwner?.abandon(); }
         catch (cleanupError) { cleanupErrors.push(cleanupError); }
         try { await host.dispose(); }
@@ -210,16 +212,20 @@ export async function create(options = {}) {
         throw error;
       }
     },
+    async shutdown(raw) {
+      await raw.shutdown();
+    },
     subscribe: events.subscribe,
     adopt(raw) {
       host.retain();
       try {
-        durabilityOwner?.retain();
+        // Adopted child handles are ephemeral and do not own the root store.
+        if (raw.sessionId === stableSessionId) durabilityOwner?.retain();
         bindHostSession(host, raw.sessionId, cloudflareReservation);
         events.addSource(raw);
       } catch (error) {
         events.removeSource(raw);
-        durabilityOwner?.release();
+        if (raw.sessionId === stableSessionId) durabilityOwner?.release();
         releaseHost(host);
         throw error;
       }
@@ -228,7 +234,7 @@ export async function create(options = {}) {
       events.removeSource(raw);
       host.releaseSession(raw.sessionId);
       releaseHostSession(host, raw.sessionId);
-      durabilityOwner?.release();
+      if (raw.sessionId === stableSessionId) durabilityOwner?.release();
       releaseHost(host);
     },
     decorate: (agent) => agent.extend(agentActions()),
@@ -240,6 +246,7 @@ export async function create(options = {}) {
       thinking,
       reasoningMode,
       fastMode,
+      rawApiEvents,
       instructions,
       additionalInstructions,
       sessionId: stableSessionId,

package/browser/Transport.d.mts

@@ -4,6 +4,7 @@ import type {
 } from "../types.mjs";
 import type { Options as ManagedClientOptions } from "../managed/Agent.mjs";
 import type {
+  BrowserHttpRequest,
   BrowserWebSocketConnection,
   BrowserWebSocketRequest,
 } from "./host.mjs";
@@ -25,6 +26,8 @@ export type WorkerTransport = ResponsesTransport & Readonly<{
 
 type SharedEndpointOptions = Readonly<{
   apiBaseUrl?: string | undefined;
+  /** Use HTTPS with full history replay, no stored responses, and no WebSocket warmup or preconnect. */
+  stateless?: boolean | undefined;
   websocketUrl?: string | undefined;
   /** Open the persistent socket as soon as Agent.create returns. Defaults to true for hostManaged. */
   websocketPreconnect?: boolean | undefined;
@@ -34,9 +37,11 @@ type SharedEndpointOptions = Readonly<{
 type WorkerEndpointOptions = SharedEndpointOptions & Readonly<{
   WebSocketImpl?: never;
   createWebSocket?: never;
+  createResponse?: never;
 }>;
 
 type EndpointOptions = SharedEndpointOptions & Readonly<{
+  createResponse?(endpoint: string, sessionId: string, request: BrowserHttpRequest): Promise<Response>;
   WebSocketImpl?: typeof WebSocket | undefined;
   createWebSocket?(
     endpoint: string,

package/browser/Transport.mjs

@@ -25,12 +25,12 @@ export function chatGpt(options) {
 
 export function hostManaged(options = {}) {
   const websocketUrl = options.websocketUrl
-    ?? (options.createWebSocket ? undefined : defaultHostManagedWebSocketUrl());
+    ?? (options.stateless === true || options.createWebSocket ? undefined : defaultHostManagedWebSocketUrl());
   return createResponsesTransport({
     hostAuth: true,
     hostManagedProtocol: true,
     ...connection({ ...options, websocketUrl }),
-    websocketPreconnect: options.websocketPreconnect ?? true,
+    websocketPreconnect: options.stateless === true ? false : options.websocketPreconnect ?? true,
   });
 }
 
@@ -53,7 +53,9 @@ function connection(options = {}) {
   return {
     WebSocketImpl: options.WebSocketImpl,
     apiBaseUrl: options.apiBaseUrl,
+    stateless: options.stateless,
     createWebSocket: options.createWebSocket,
+    createResponse: options.createResponse,
     websocketUrl: options.websocketUrl,
     websocketPreconnect: options.websocketPreconnect,
     websocketWarmup: options.websocketWarmup,

package/browser/Voice.d.mts

@@ -34,6 +34,7 @@ export type Snapshot = Readonly<{
   microphoneLevel: number;
   speakerLevel: number;
   error: Error | undefined;
+  /** Active means media and live control are ready; task admission may still be pending. */
   status: "idle" | "connecting" | "active" | "error";
   statusText: string | undefined;
   /** Latest 200 rows, retained across stop/start. Subscribe to events for longer history. */
@@ -50,6 +51,8 @@ export type Event =
   | Readonly<{ type: "stopped" }>;
 export type Settings = Readonly<{
   voice?: VoiceName | undefined;
+  outputProvider?: "openai" | "elevenlabs" | undefined;
+  elevenLabsVoiceId?: string | undefined;
   /** Additional speaking preferences; base assistant instructions are retained. */
   instructions?: string | undefined;
   pace?: "slow" | "natural" | "fast" | undefined;
@@ -58,6 +61,8 @@ export type Settings = Readonly<{
   acknowledgements?: boolean | undefined;
 }>;
 export type Options = Settings & Readonly<{
+  /** Authenticated synthesis transport returning mono signed 16-bit little-endian PCM at 24 kHz. */
+  synthesize?(text: string, signal: AbortSignal): Promise<Response>;
   callUrl?: string | URL | undefined;
   sidebandUrl?(callId: string, sessionId: string): string | URL | Promise<string | URL>;
   captureMicrophone?(): Promise<MediaStream>;
@@ -78,6 +83,7 @@ export type Voice = Readonly<{
   destroy(): Promise<void>;
   getSnapshot(): Snapshot;
   onEvent(listener: (event: Event) => void): () => void;
+  /** Resolves after media and task admission are ready. The active snapshot may arrive first. */
   start(options?: Settings): Promise<void>;
   stop(): Promise<void>;
   subscribe(listener: () => void): () => void;