nanocodex 0.6.4 → 0.6.6

package/browser/host.mjs

@@ -1,3 +1,4 @@
+import { createBeforeCompaction } from "../runtime/before-compaction.mjs";
 import { createResponsesHttp, responsesHttpHeaders } from "../runtime/responses-http.mjs";
 import { createCodeRuntime, toolResult } from "../runtime/code-runtime.mjs";
 import {
@@ -12,10 +13,17 @@ import { openHostManagedWebSocket } from "./hostManagedWebSocket.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 SEND_BUFFER_WAIT_MS = 5_000;
+const SEND_BUFFER_POLL_MS = 10;
 const MPP_CLIENT_PROTOCOL_ERROR_CLOSE_CODE = 3008;
 const WEBSOCKET_OPEN = 1;
 
 export function createBrowserHost(options = {}) {
+  const onSocketTiming = options.onSocketTiming;
+  if (onSocketTiming !== undefined && typeof onSocketTiming !== "function") {
+    throw new TypeError("host socket timing hook must be a function");
+  }
+  const preservation = createBeforeCompaction(options.beforeCompaction);
   const toolMode = options.toolMode ?? "code";
   if (toolMode !== "code" && toolMode !== "direct") {
     throw new TypeError("toolMode must be code or direct");
@@ -190,6 +198,7 @@ export function createBrowserHost(options = {}) {
       let settled = false;
       const connection = {
         socket,
+        timing: socketTiming(),
         queue: [],
         queuedBytes: 0,
         waiter: undefined,
@@ -200,6 +209,7 @@ export function createBrowserHost(options = {}) {
         if (settled) return;
         settled = true;
         connectingConnections.delete(connection);
+        finishSocketTiming(connection);
         reject(error);
       };
       connection.reject = rejectConnection;
@@ -234,6 +244,7 @@ export function createBrowserHost(options = {}) {
           : { kind: "binary" });
       });
       socket.addEventListener("close", (event) => {
+        connection.wakeSend?.();
         if (!settled) {
           rejectConnection(new Error(`WebSocket closed during connection with code ${event.code}`));
         } else if (!connection.intentionallyClosed && !connection.overflowed) {
@@ -267,6 +278,7 @@ export function createBrowserHost(options = {}) {
     const handle = nextHandle++;
     const connection = {
       socket,
+      timing: socketTiming(),
       queue: [],
       queuedBytes: 0,
       waiter: undefined,
@@ -300,37 +312,66 @@ export function createBrowserHost(options = {}) {
     return JSON.stringify({ handle, status: 101, reasoning_included: false });
   }
 
-  function send(handle, message) {
+  async function send(handle, message) {
     const connection = connections.get(handle);
-    if (!connection || connection.socket.readyState !== WEBSOCKET_OPEN) {
-      return Promise.resolve(JSON.stringify({
-        ok: false,
-        reconnectable: true,
-        error: "WebSocket is no longer open",
-      }));
+    const closed = () => disposal || !connection || connections.get(handle) !== connection
+      || connection.socket.readyState !== WEBSOCKET_OPEN;
+    const closedResult = () => JSON.stringify({
+      ok: false,
+      reconnectable: true,
+      error: "WebSocket is no longer open",
+    });
+    if (closed()) return closedResult();
+    // The runtime sends one request at a time. Do not retain an unbounded queue
+    // of request bodies while the underlying socket is under pressure.
+    if (connection.sending) {
+      return JSON.stringify({ ok: false, reconnectable: false,
+        error: "concurrent WebSocket sends are unsupported" });
     }
+    connection.sending = true;
     try {
       if (connection.managed) {
         connection.socket.send(JSON.stringify({ mpp: "message", data: message }));
-        return Promise.resolve(JSON.stringify({ ok: true }));
+        return JSON.stringify({ ok: true });
       }
       const frameBytes = utf8ByteLength(message);
-      if (frameBytes > maxBufferedSendBytes
-        || connection.socket.bufferedAmount + frameBytes > maxBufferedSendBytes) {
-        return Promise.resolve(JSON.stringify({
+      if (frameBytes > maxBufferedSendBytes) {
+        return JSON.stringify({
           ok: false,
           reconnectable: false,
-          error: `buffered WebSocket sends exceeded ${maxBufferedSendBytes} bytes`,
-        }));
+          error: `WebSocket frame size ${frameBytes} bytes exceeds ${maxBufferedSendBytes} bytes (buffered ${connection.socket.bufferedAmount} bytes)`,
+        });
+      }
+      const deadline = Date.now() + SEND_BUFFER_WAIT_MS;
+      while (connection.socket.bufferedAmount + frameBytes > maxBufferedSendBytes) {
+        if (closed()) return closedResult();
+        if (Date.now() >= deadline) {
+          // Nothing was sent. The transport may reconnect, but this invocation
+          // must never send later after reporting a retryable failure.
+          return JSON.stringify({ ok: false, reconnectable: true,
+            error: `WebSocket send buffer did not drain within ${SEND_BUFFER_WAIT_MS} ms (frame ${frameBytes} bytes, buffered ${connection.socket.bufferedAmount} bytes, limit ${maxBufferedSendBytes} bytes)` });
+        }
+        await new Promise((resolve) => {
+          const timer = setTimeout(wake, SEND_BUFFER_POLL_MS);
+          function wake() {
+            clearTimeout(timer);
+            connection.wakeSend = undefined;
+            resolve();
+          }
+          connection.wakeSend = wake;
+        });
       }
+      if (closed()) return closedResult();
       connection.socket.send(message);
-      return Promise.resolve(JSON.stringify({ ok: true }));
+      return JSON.stringify({ ok: true });
     } catch (error) {
-      return Promise.resolve(JSON.stringify({
+      return JSON.stringify({
         ok: false,
         reconnectable: connection.socket.readyState !== WEBSOCKET_OPEN,
         error: error instanceof Error ? error.message : String(error),
-      }));
+      });
+    } finally {
+      connection.sending = false;
     }
   }
 
@@ -342,6 +383,13 @@ export function createBrowserHost(options = {}) {
     if (connection.queue.length) {
       const entry = connection.queue.shift();
       connection.queuedBytes -= entry.bytes;
+      if (entry.enqueuedAt !== undefined && connection.timing) {
+        const metrics = connection.timing.metrics;
+        const residenceMs = Math.max(0, performance.now() - entry.enqueuedAt);
+        metrics.delivered_message_count += 1;
+        metrics.queue_residence_total_ms += residenceMs;
+        metrics.queue_residence_max_ms = Math.max(metrics.queue_residence_max_ms, residenceMs);
+      }
       return Promise.resolve(JSON.stringify(entry.message));
     }
     if (connection.waiter) return Promise.reject(new Error("concurrent reads are unsupported"));
@@ -358,13 +406,32 @@ export function createBrowserHost(options = {}) {
     if (!connection) return;
     connections.delete(handle);
     connection.intentionallyClosed = true;
+    connection.wakeSend?.();
     connection.waiter?.({ kind: "closed", detail: "by the WASM runtime" });
+    finishSocketTiming(connection);
+    connection.queue.length = 0;
+    connection.queuedBytes = 0;
     return connection.socket.close();
   }
 
   function enqueue(connection, message) {
-    if (connection.overflowed) return;
+    if (connection.overflowed || connection.intentionallyClosed) return;
+    const timing = connection.timing;
+    const dataMessage = message.kind === "text" || message.kind === "binary";
+    const enqueuedAt = timing && dataMessage && !connection.waiter ? performance.now() : undefined;
+    if (timing && dataMessage) {
+      timing.metrics.message_count += 1;
+      // Only the exact metadata event can produce diagnostics; deltas stay opaque.
+      if (message.kind === "text" && timing.provider.size < 32) {
+        const metadata = providerSocketTiming(message.text);
+        if (metadata) {
+          const key = metadata.response_id ?? timing.provider.size;
+          if (!timing.provider.has(key)) timing.provider.set(key, metadata);
+        }
+      }
+    }
     if (connection.waiter) {
+      if (timing && dataMessage) timing.metrics.delivered_message_count += 1;
       connection.waiter(message);
       return;
     }
@@ -383,12 +450,50 @@ export function createBrowserHost(options = {}) {
       connection.socket.close(1009, "receive queue exceeded configured bounds");
       return;
     }
-    connection.queue.push({ message, bytes });
+    const entry = { message, bytes };
+    if (enqueuedAt !== undefined) {
+      entry.enqueuedAt = enqueuedAt;
+      timing.metrics.buffered_message_count += 1;
+    }
+    connection.queue.push(entry);
     connection.queuedBytes += bytes;
   }
 
+  // No counters, timestamps, metadata parsing or observations without the internal hook.
+  function socketTiming() {
+    return onSocketTiming === undefined ? undefined : {
+      metrics: {
+        message_count: 0,
+        delivered_message_count: 0,
+        buffered_message_count: 0,
+        queue_residence_total_ms: 0,
+        queue_residence_max_ms: 0,
+      },
+      provider: new Map(),
+    };
+  }
+
+  function finishSocketTiming(connection) {
+    const timing = connection.timing;
+    if (!timing) return;
+    // Finalize owned consumption, not the remote close event: buffered frames may
+    // still be drained after that event. Clear first for reentrant close/dispose.
+    connection.timing = undefined;
+    const metrics = timing.metrics;
+    try {
+      const result = onSocketTiming({
+        ...metrics,
+        discarded_message_count: metrics.message_count - metrics.delivered_message_count,
+        provider_timings: [...timing.provider.values()],
+      });
+      // Diagnostics must never fail transport cleanup, including an async hook.
+      if (result?.then) void Promise.resolve(result).catch(() => {});
+    } catch { /* Passive observations cannot fail transport cleanup. */ }
+  }
+
   function dispose() {
     if (disposal) return disposal;
+    preservation.dispose();
     http.dispose();
     disposalError = new Error("Nanocodex host was disposed during WebSocket connection");
     disposal = Promise.resolve().then(async () => {
@@ -495,6 +600,8 @@ export function createBrowserHost(options = {}) {
       if (references > 0) references -= 1;
       return references === 0 ? dispose() : Promise.resolve();
     },
+    beforeCompaction: preservation.preserve,
+    cancelBeforeCompaction: preservation.cancel,
     httpOpen: http.httpOpen,
     httpReady: http.httpReady,
     httpNext: http.httpNext,
@@ -511,6 +618,14 @@ export function createBrowserHost(options = {}) {
     cancelCodeTurn: code.cancelTurn,
     nextCodeUpdate: code.nextCodeUpdate,
     executeTool: code.executeTool,
+    routeSubagent: (request) => {
+      if (!options.subagentRouting) throw new Error("subagent routing is not configured");
+      return options.subagentRouting.resolve(request);
+    },
+    bindSubagentRoute: (request) => {
+      if (!options.subagentRouting) throw new Error("subagent routing is not configured");
+      return options.subagentRouting.bind(request);
+    },
     bindSubagentSession: code.bindSubagentSession,
     cancelCode: code.cancel,
     readWorkspaceFile: async (path) => {
@@ -554,3 +669,26 @@ function normalizeWebSocketConnection(opened) {
   }
   return { socket: opened };
 }
+
+// Provider-reported fields are nested spans, not additive measurements. Bound the
+// diagnostic parser and retain only three finite durations plus a response ID.
+function providerSocketTiming(text) {
+  if (text.length > 16_384 || !text.includes('"responsesapi.websocket_timing"')) return;
+  let event;
+  try { event = JSON.parse(text); } catch { return; }
+  if (event?.type !== "responsesapi.websocket_timing"
+    || (event.response_id !== undefined && (typeof event.response_id !== "string"
+      || !/^resp_[A-Za-z0-9_-]{1,128}$/.test(event.response_id)))
+    || !event.timing_metrics || typeof event.timing_metrics !== "object"
+    || Array.isArray(event.timing_metrics)) return;
+  const timing = {};
+  for (const key of ["pre_inference_ms", "engine_queue_max_ms", "engine_service_ttft_total_ms"]) {
+    const value = event.timing_metrics[key];
+    if (typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 86_400_000) {
+      timing[key] = value;
+    }
+  }
+  if (Object.keys(timing).length) return {
+    ...(event.response_id === undefined ? {} : { response_id: event.response_id }), ...timing,
+  };
+}

package/cloud/types.d.mts

@@ -22,6 +22,7 @@ export type ConnectorConnection = Readonly<{
   label: string;
   accountId?: string | undefined;
   capabilities?: readonly CloudAccount[] | undefined;
+  scopes?: readonly string[] | undefined;
 }>;
 
 /** Provider-neutral status for a connector service capability. */

package/cloudflare/Agent.d.mts

@@ -5,6 +5,7 @@ import type {
   AgentEvent,
   DefaultAgent,
   ToolConfiguration,
+  SessionSnapshot,
 } from "../types.mjs";
 import type { CloudflareDurableObjectStorage } from "../runtime/cloudflare-durability-store.mjs";
 import type { Tool as SubagentTool } from "../runtime/subagents.mjs";
@@ -24,14 +25,6 @@ export type DurableObjectContext = Readonly<{
 /** The owning Cloudflare Durable Object instance. Runtime fields remain adapter-private. */
 export type DurableObjectOwner = object;
 
-/** Rust-owned first-prompt retrieval policy; the host owns authenticated execution. */
-export type BootstrapPlan = Readonly<{
-  query: string;
-  voice_bootstrap: boolean;
-  calls: readonly Readonly<{ name: "find_session" | "memory"; arguments: unknown }>[];
-}>;
-export function bootstrapPlan(input: string): Promise<BootstrapPlan>;
-
 export type EventFrame = Readonly<{
   cursor: string;
   event: AgentEvent;
@@ -60,6 +53,9 @@ export type Agent<extended extends object = {}> =
     ): Agent<extended & extension>;
   }>;
 
+/** Copies the exact latest committed model boundary; rejects before the first safe boundary. */
+export function checkpoint(agent: Agent): Promise<SessionSnapshot>;
+
 /** Removes the package-owned durable history for one Cloudflare Agent. */
 export function destroy(owner: DurableObjectOwner): void;
 
@@ -100,6 +96,8 @@ export function create(owner: create.Owner, options?: create.Options): Promise<c
 export declare namespace create {
   type Owner = DurableObjectOwner;
   type Options = Readonly<{
+    /** Awaited host preservation barrier; scoped to this root, never inherited by children. */
+    beforeCompaction?: AgentOptions["beforeCompaction"];
     /** Stable portable state identity. It cannot change after first construction or import. */
     durabilityId?: string | undefined;
     /**
@@ -115,7 +113,7 @@ export declare namespace create {
      * The caller must preserve older exact-ID results before selecting this.
      */
     terminalReceiptRetention?: number | undefined;
-    /** Live child execution is in-memory; interrupted descriptors survive reconstruction. */
+    /** Children exist only in memory and are discarded when the root runtime shuts down. */
     tools?: ToolConfiguration<SubagentTool> | undefined;
   }>;
   type ReturnType = Agent;
@@ -134,3 +132,10 @@ export declare namespace createEphemeral {
   }>;
   type ReturnType = DefaultAgent;
 }
+
+/** Reads a correlated receipt without acquiring or restoring the agent. */
+export function steerReceipt(owner: DurableObjectOwner, operationId: string, messageId: string): Readonly<{
+  input_key: string; index: number; withdrawn: boolean;
+}> | null;
+/** Fingerprint of the exact browser Prompt serialization retained by Rust. */
+export function steerInputKey(input: import("../types.mjs").PromptInput): Promise<string>;