nanocodex 0.6.4 → 0.6.6

package/cloudflare/Agent.mjs

@@ -1,7 +1,12 @@
+import { steerInputKey } from "../runtime/steer-receipt.mjs";
+export { steerInputKey };
+import { createGatewayResponses } from "./gateway-responses.mjs";
+import { createWorkersAiResponses } from "./workers-ai-responses.mjs";
 import { responseControlsBody, responseControlsSocket } from "../runtime/response-controls.mjs";
 import * as HostAgent from "../host/Agent.mjs";
 import {
   CLOUDFLARE_SESSION_RESERVATION,
+  checkpoint as checkpointAgent,
   commitCloudflareAgentSession,
   installHostBridge,
   loadDurabilityRuntime,
@@ -12,7 +17,7 @@ import {
   releaseAgentSession,
   routePrompt,
 } from "../internal.mjs";
-import { pruneDurableReceipts as pruneWasmDurableReceipts, managedBootstrapPlan } from "../pkg-web/nanocodex.js";
+import { pruneDurableReceipts as pruneWasmDurableReceipts } from "../pkg-web/nanocodex.js";
 import * as Transport from "../browser/Transport.mjs";
 import { initializeBrowserEngine } from "../browser/engine.mjs";
 import { createCloudflareDurabilityStore } from "../runtime/cloudflare-durability-store.mjs";
@@ -24,6 +29,7 @@ import {
   importDurabilityState as importPortableState,
 } from "../runtime/durability-store.mjs";
 import { cloudflareEgress } from "./egress.mjs";
+import { prepareConnection } from "./prepared-connection.mjs";
 import { scopeCloudflareEgress } from "./egress-subject.mjs";
 import {
   clearCloudflareEventSocket,
@@ -33,7 +39,9 @@ import {
 const STARTUP_TIMEOUT_MS = 10_000;
 const INTERNAL_RUNTIME = Symbol.for("nanocodex.cloudflare.internalRuntime");
 const INTERNAL_CONFIGURATION = Symbol.for("nanocodex.cloudflare.internalConfiguration");
+const INTERNAL_FORK_RESUME = Symbol.for("nanocodex.cloudflare.internalForkResume");
 const EPHEMERAL_APPLICATION_OPTIONS = new Set([
+  "beforeCompaction",
   "additionalInstructions",
   "fastMode",
   "instructions",
@@ -46,6 +54,7 @@ const EPHEMERAL_APPLICATION_OPTIONS = new Set([
   "workspace",
 ]);
 const APPLICATION_OPTIONS = new Set([
+  "beforeCompaction",
   "additionalInstructions",
   "durabilityId",
   "eventPersistence",
@@ -58,13 +67,12 @@ const lifecycles = new WeakMap();
 /** @internal Binds the package-owned module to the public Cloudflare namespace. */
 export function bindAgent(module, hostAgent = HostAgent) {
   return Object.freeze({
-    bootstrapPlan: async (input) => {
-      await initializeBrowserEngine({ module });
-      return JSON.parse(managedBootstrapPlan(input));
-    },
+    steerReceipt,
+    steerInputKey,
     pruneDurableReceipts: (owner, options) => pruneDurableReceipts(module, owner, options),
     create: (owner, options) => create(module, owner, options, hostAgent),
     createEphemeral: (owner, options) => createEphemeral(module, owner, options),
+    checkpoint,
     destroy,
     exportDurabilityState,
     exportDurabilityHead,
@@ -73,6 +81,11 @@ export function bindAgent(module, hostAgent = HostAgent) {
   });
 }
 
+/** Copies the latest safe committed boundary as a resumable SessionSnapshot. */
+export function checkpoint(agent) {
+  return checkpointAgent(agent);
+}
+
 /** Atomically steers an active Cloudflare Agent turn or starts a new turn. */
 export function route(agent, options) {
   return routePrompt(agent, options);
@@ -117,7 +130,7 @@ export function destroy(owner) {
         stateId,
       );
     }
-    storage.sql.exec("DELETE FROM nanocodex_cloudflare_subagents");
+    storage.sql.exec("DROP TABLE IF EXISTS nanocodex_cloudflare_fork_resume");
     clearCloudflareEventSocket(context);
   });
 }
@@ -274,13 +287,111 @@ export async function create(module, owner, options = {}, hostAgent = HostAgent)
   }
   lifecycle.creating = true;
   try {
-    return await createOwned(module, resolved, options, hostAgent, lifecycle);
+    const prepare = options?.[INTERNAL_RUNTIME]?.prepare;
+    if (prepare === undefined) return await createOwned(module, resolved, options, hostAgent, lifecycle);
+    return await createPrepared(module, resolved, options, hostAgent, lifecycle, prepare);
   } finally {
     lifecycle.creating = false;
   }
 }
 
-async function createOwned(module, resolved, options, hostAgent, lifecycle) {
+// Private managed construction barrier. The adapter retains lifecycle, identity,
+// endpoint and socket ownership throughout tool discovery; callers receive only
+// a single-use continuation, never a transport or a session identity.
+async function createPrepared(module, resolved, options, hostAgent, lifecycle, prepare) {
+  applicationOptions(options);
+  if (typeof prepare !== "function") throw new TypeError("Cloudflare Agent preparation must be a function");
+  const configuration = options[INTERNAL_CONFIGURATION];
+  validateInternalConfiguration(configuration);
+  if (!configuration || !["gpt-6-astra", "gpt-6.1-sol", "gpt-6-luna"].includes(configuration.model)) {
+    throw new Error("Cloudflare Agent preparation requires a native root configuration");
+  }
+  const runtime = options[INTERNAL_RUNTIME];
+  if (Object.keys(runtime).some(key => !["prepare", "preparationSignal"].includes(key))) {
+    throw new TypeError("Cloudflare Agent preparation owns its native transport policy");
+  }
+  const signal = runtime.preparationSignal;
+  signal?.throwIfAborted();
+  createCloudflareDurabilityStore(resolved.context.storage);
+  initializeAgentStorage(resolved.context.storage);
+  const pristineAtStart = storedSessionId(resolved.context.storage) === undefined
+    && storedStateId(resolved.context.storage) === undefined;
+  const initialForkResume = options?.[INTERNAL_FORK_RESUME];
+  let initialForkDigest;
+  if (initialForkResume !== undefined) {
+    if (!initialForkResume || typeof initialForkResume !== "object" || Array.isArray(initialForkResume))
+      throw new TypeError("Cloudflare Agent fork resume must be a SessionSnapshot");
+    const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256",
+      new TextEncoder().encode(JSON.stringify(initialForkResume))));
+    initialForkDigest = [...bytes].map(byte => byte.toString(16).padStart(2, "0")).join("");
+  }
+  const { sessionId, stateId } = durableIdentity(resolved.context.storage, options.durabilityId);
+  if (initialForkDigest !== undefined) {
+    // Pin the seed before optional tool discovery/transport preparation. A
+    // failed preparation can reopen the exact fork with the same snapshot.
+    resolved.context.storage.sql.exec(`CREATE TABLE IF NOT EXISTS nanocodex_cloudflare_fork_resume (
+      singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+      state_id TEXT NOT NULL, digest TEXT NOT NULL
+    )`);
+    const previous = resolved.context.storage.sql.exec(
+      "SELECT state_id, digest FROM nanocodex_cloudflare_fork_resume WHERE singleton = 1",
+    ).toArray()[0];
+    if ((!pristineAtStart && !previous) || (previous
+      && (previous.state_id !== stateId || previous.digest !== initialForkDigest))) {
+      throw new Error("Cloudflare Agent fork resume conflicts with its retained seed");
+    }
+    resolved.context.storage.sql.exec(
+      "INSERT OR IGNORE INTO nanocodex_cloudflare_fork_resume(singleton,state_id,digest) VALUES (1,?,?)",
+      stateId, initialForkDigest);
+  }
+  const endpoint = cloudflareEgress({ binding: scopeCloudflareEgress(resolved.egress, resolved.subject) });
+  const connection = prepareConnection(endpoint, sessionId, signal);
+  let completing;
+  let accepting = true;
+  let attempted = false;
+  try {
+    // Share the realm's engine initialization while the socket and tool metadata
+    // load. No Agent or durable runtime owner exists until preparation finishes.
+    installHostBridge();
+    const initializing = initializeBrowserEngine({ module });
+    void initializing.catch(() => {});
+    const result = await prepare((prepared) => {
+      if (!accepting || attempted) throw new Error("Cloudflare Agent preparation was already completed");
+      attempted = true;
+      signal?.throwIfAborted();
+      completing = initializing.then(() => {
+        signal?.throwIfAborted();
+        const runtime = prepared?.[INTERNAL_RUNTIME];
+        const pinned = prepared?.[INTERNAL_CONFIGURATION];
+        validateInternalConfiguration(pinned);
+        if (prepared?.durabilityId !== stateId
+          || ["model", "reasoning_mode"].some(key => pinned?.[key] !== configuration[key])
+          || runtime?.prepare !== undefined || runtime?.workersAi !== undefined || runtime?.gateway !== undefined
+          || (runtime?.inferenceForSession !== undefined && runtime?.preserveRootTransport !== true)
+          || (initialForkDigest !== undefined && JSON.stringify(prepared?.[INTERNAL_FORK_RESUME]) !== JSON.stringify(initialForkResume))) {
+          throw new Error("Cloudflare Agent preparation changed its pinned transport or configuration");
+        }
+        return createOwned(module, resolved, prepared, hostAgent, lifecycle, connection,
+          pristineAtStart ? { sessionId, stateId } : undefined);
+      });
+      void completing.catch(() => {});
+      return completing;
+    });
+    if (completing === undefined || result !== await completing) {
+      throw new Error("Cloudflare Agent preparation must return its completed Agent");
+    }
+    return result;
+  } catch (error) {
+    const agent = await completing?.catch(() => undefined);
+    if (agent !== undefined) await agent.session.shutdown();
+    throw error;
+  } finally {
+    accepting = false;
+    await connection.dispose();
+  }
+}
+
+async function createOwned(module, resolved, options, hostAgent, lifecycle, preparedConnection, pristinePreparedIdentity) {
   const { context, egress, subject } = resolved;
   const configured = applicationOptions(options);
   const {
@@ -288,12 +399,25 @@ async function createOwned(module, resolved, options, hostAgent, lifecycle) {
     eventPersistence = "durable",
     [INTERNAL_RUNTIME]: internalRuntime,
     [INTERNAL_CONFIGURATION]: internalConfiguration,
+    [INTERNAL_FORK_RESUME]: forkResume,
     ...agentOptions
   } = configured;
   if (internalRuntime !== undefined
     && (!internalRuntime || typeof internalRuntime !== "object" || Array.isArray(internalRuntime))) {
     throw new TypeError("Cloudflare Agent internal runtime options must be an object");
   }
+  if (internalRuntime?.onSocketTiming !== undefined
+    && typeof internalRuntime.onSocketTiming !== "function") {
+    throw new TypeError("Cloudflare Agent socket timing hook must be a function");
+  }
+  if (internalRuntime?.onResponseCreateSent !== undefined
+    && typeof internalRuntime.onResponseCreateSent !== "function") {
+    throw new TypeError("Cloudflare Agent response.create sent hook must be a function");
+  }
+  if (internalRuntime?.onRequestShape !== undefined
+    && typeof internalRuntime.onRequestShape !== "function") {
+    throw new TypeError("Cloudflare Agent request shape hook must be a function");
+  }
   if (internalRuntime?.subagentLifecycle !== undefined
     && typeof internalRuntime.subagentLifecycle !== "function") {
     throw new TypeError("Cloudflare Agent subagent lifecycle hook must be a function");
@@ -302,31 +426,174 @@ async function createOwned(module, resolved, options, hostAgent, lifecycle) {
     && typeof internalRuntime.waitForPreconnect !== "boolean") {
     throw new TypeError("Cloudflare Agent internal waitForPreconnect must be a boolean");
   }
+  if (internalRuntime?.preserveRootTransport !== undefined
+    && typeof internalRuntime.preserveRootTransport !== "boolean") {
+    throw new TypeError("Cloudflare Agent root transport policy must be a boolean");
+  }
+  if (internalRuntime?.inferenceForSession !== undefined
+    && typeof internalRuntime.inferenceForSession !== "function") {
+    throw new TypeError("Cloudflare Agent inference routing must be a function");
+  }
+  if (internalRuntime?.subagentRouting !== undefined && internalRuntime?.inferenceForSession === undefined) {
+    throw new TypeError("Subagent routing requires session-specific inference routing");
+  }
   validateInternalConfiguration(internalConfiguration);
   const eventSocket = eventPersistence === "durable"
     ? createCloudflareEventSocket(context)
     : undefined;
   if (eventPersistence === "caller") clearCloudflareEventSocket(context);
   const durability = createCloudflareDurabilityStore(context.storage);
+  let resumeDigest;
+  if (forkResume !== undefined) {
+    if (!forkResume || typeof forkResume !== "object" || Array.isArray(forkResume)) {
+      throw new TypeError("Cloudflare Agent fork resume must be a SessionSnapshot");
+    }
+    initializeAgentStorage(context.storage);
+    context.storage.sql.exec(`CREATE TABLE IF NOT EXISTS nanocodex_cloudflare_fork_resume (
+      singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+      state_id TEXT NOT NULL, digest TEXT NOT NULL
+    )`);
+    const digestBytes = new Uint8Array(await crypto.subtle.digest("SHA-256",
+      new TextEncoder().encode(JSON.stringify(forkResume))));
+    resumeDigest = [...digestBytes].map(byte => byte.toString(16).padStart(2, "0")).join("");
+    const recordedSeed = context.storage.sql.exec(
+      "SELECT state_id, digest FROM nanocodex_cloudflare_fork_resume WHERE singleton = 1",
+    ).toArray()[0];
+    const existingSessionId = storedSessionId(context.storage);
+    const existingStateId = storedStateId(context.storage);
+    // The preparation barrier may have installed the new identity already. A
+    // failed/restarted child construction may retain that identity and a
+    // revision-zero owner fence, but still has no executed checkpoint. The
+    // durable seed is unchanged; allow that cold retry and reject any real head.
+    if ((existingSessionId !== undefined || existingStateId !== undefined)
+      && !((pristinePreparedIdentity?.sessionId === existingSessionId
+          && pristinePreparedIdentity?.stateId === existingStateId)
+        || (existingSessionId !== undefined && existingStateId !== undefined
+          && (durabilityId === undefined || existingStateId === durabilityId)
+          && recordedSeed?.state_id === existingStateId
+          && recordedSeed?.digest === resumeDigest))) {
+      throw new Error("Cloudflare Agent fork resume requires a pristine Durable Object");
+    }
+    if (recordedSeed && (recordedSeed.digest !== resumeDigest
+      || (existingStateId !== undefined && recordedSeed.state_id !== existingStateId))) {
+      throw new Error("Cloudflare Agent fork resume conflicts with its retained seed");
+    }
+    const checkStateId = existingStateId ?? durabilityId;
+    if (checkStateId !== undefined && context.storage.sql.exec(
+      "SELECT revision, payload FROM nanocodex_durable_states WHERE state_id = ?", checkStateId,
+    ).toArray().some(row => row.revision !== "0" || row.payload !== null)) {
+      throw new Error("Cloudflare Agent fork resume requires pristine durability state");
+    }
+  }
   const { sessionId, stateId } = durableIdentity(context.storage, durabilityId);
-  const endpoint = cloudflareEgress({
+  if (resumeDigest !== undefined) {
+    context.storage.sql.exec(
+      "INSERT OR IGNORE INTO nanocodex_cloudflare_fork_resume(singleton,state_id,digest) VALUES (1,?,?)",
+      stateId, resumeDigest);
+  }
+  const workersAi = internalRuntime?.workersAi;
+  const gateway = internalRuntime?.gateway;
+  if (gateway !== undefined && (workersAi !== undefined
+    || gateway.model !== internalConfiguration?.model
+    || gateway.reasoningEffort !== internalConfiguration?.thinking)) {
+    throw new TypeError("Gateway profile must match the pinned model and thinking, with one transport only");
+  }
+  const routedInference = internalRuntime?.inferenceForSession !== undefined;
+  const directInference = workersAi !== undefined || gateway !== undefined
+    || (routedInference && internalRuntime?.preserveRootTransport !== true);
+  if (workersAi !== undefined && (internalConfiguration?.model !== "@cf/zai-org/glm-5.3"
+    || workersAi.model !== internalConfiguration.model || workersAi.thinking !== internalConfiguration.thinking)) {
+    throw new TypeError("Workers AI profile must match the pinned model and thinking");
+  }
+  if (["@cf/zai-org/glm-5.3", "kimi-k3", "mimo-v2.6-pro"].includes(internalConfiguration?.model) && !directInference) {
+    throw new TypeError("GLM-5.3 requires a Workers AI or gateway transport binding");
+  }
+  const endpoint = gateway !== undefined ? createGatewayResponses(gateway) : workersAi === undefined ? cloudflareEgress({
     binding: scopeCloudflareEgress(egress, subject),
-  });
+  }) : createWorkersAiResponses(workersAi.ai);
+  const frontierEndpoint = routedInference ? cloudflareEgress({ binding: scopeCloudflareEgress(egress, subject) }) : undefined;
   const startup = deferred();
   const transport = Transport.hostManaged({
     ...endpoint,
-    websocketPreconnect: true,
-    createResponse(url, id, request) {
-      return endpoint.createResponse(url, id, {
-        ...request,
-        body: responseControlsBody(request.body, internalRuntime?.responseControls),
-      });
+    stateless: directInference,
+    websocketPreconnect: !directInference,
+    async createResponse(url, id, request) {
+      let selected = endpoint;
+      const body = responseControlsBody(request.body, internalRuntime?.responseControls);
+      if (routedInference) {
+        // This callback rechecks retained authority on EVERY request, including
+        // the root. Never inherit the root provider when a child pin is missing.
+        // The transport session is the shared lineage; threadId identifies the
+        // actual root/child branch registered by the Rust host bridge.
+        const routedSessionId = request.threadId ?? id;
+        const profile = await internalRuntime.inferenceForSession(routedSessionId);
+        if (profile?.native === true) {
+          if (internalRuntime?.preserveRootTransport !== true || profile.gateway !== undefined || profile.workersAi !== undefined) {
+            throw new Error("Native inference cannot replace a routed transport");
+          }
+          const parsed = JSON.parse(body);
+          if (!["gpt-6-astra", "gpt-6.1-sol", "gpt-6-luna"].includes(parsed.model)
+            || !["none", "low", "medium", "high", "xhigh", "max"].includes(parsed.reasoning?.effort)) {
+            throw new Error("Native inference requires a supported GPT model and thinking");
+          }
+          // Native roots and children retain Rust-owned live defaults/overrides.
+          // Only routed sessions have immutable model/thinking pins.
+          selected = frontierEndpoint;
+        } else {
+          if (!profile || typeof profile.model !== "string" || !["low", "medium", "high"].includes(profile.thinking)) {
+            throw new Error("Session inference route is missing or invalid");
+          }
+          if (routedSessionId === sessionId && (profile.model !== internalConfiguration?.model
+            || profile.thinking !== internalConfiguration?.thinking)) {
+            throw new Error("Root inference route conflicts with its pinned configuration");
+          }
+          const parsed = JSON.parse(body);
+          if (parsed.model !== profile.model || parsed.reasoning?.effort !== profile.thinking) {
+            throw new Error("Inference request conflicts with the session model or thinking pin");
+          }
+          if (profile.workersAi !== undefined && profile.gateway !== undefined) {
+            throw new Error("Session inference route has multiple transports");
+          }
+          if (profile.gateway !== undefined) {
+            if (profile.gateway.model !== profile.model || profile.gateway.reasoningEffort !== profile.thinking) {
+              throw new Error("Gateway profile conflicts with the session pin");
+            }
+            selected = createGatewayResponses(profile.gateway);
+          } else if (profile.workersAi !== undefined) {
+            if (profile.model !== "@cf/zai-org/glm-5.3" || profile.workersAi.model !== profile.model
+              || profile.workersAi.thinking !== profile.thinking) {
+              throw new Error("Workers AI profile conflicts with the session pin");
+            }
+            selected = createWorkersAiResponses(profile.workersAi.ai);
+          } else {
+            if (!["gpt-6-astra", "gpt-6.1-sol", "gpt-6-luna"].includes(profile.model)) {
+              throw new Error("Session model requires an explicit inference binding");
+            }
+            selected = frontierEndpoint;
+          }
+          if (url !== `${endpoint.apiBaseUrl}/responses`) {
+            throw new Error("Routed inference supports only full-history Responses requests");
+          }
+          url = `${selected.apiBaseUrl}/responses`;
+        }
+      }
+      return selected.createResponse(url, id, { ...request, body });
     },
     async createWebSocket(url, id, request) {
+      if (directInference) throw new Error("Direct inference threads require HTTP Responses transport");
+      if (routedInference && (request.threadId ?? id) !== sessionId) {
+        const profile = await internalRuntime.inferenceForSession(request.threadId ?? id);
+        if (profile?.native !== true || profile.gateway !== undefined || profile.workersAi !== undefined) {
+          throw new Error("Routed children require full-history HTTP Responses transport");
+        }
+      }
       try {
-        const opened = await endpoint.createWebSocket(url, id, request);
+        const preparation = request.authorization === "preconnect" ? preparedConnection : undefined;
+        if (preparation !== undefined) preparedConnection = undefined;
+        const opened = await (preparation === undefined
+          ? endpoint.createWebSocket(url, id, request) : preparation.take(url, id, request));
         if (request.authorization === "preconnect") startup.resolve();
-        return { ...opened, socket: responseControlsSocket(opened.socket, internalRuntime?.responseControls) };
+        return { ...opened, socket: responseControlsSocket(opened.socket, internalRuntime?.responseControls, internalRuntime?.onRequestShape, internalRuntime?.onResponseCreateSent) };
       } catch (error) {
         if (request.authorization === "preconnect") startup.reject(error);
         throw error;
@@ -336,7 +603,6 @@ async function createOwned(module, resolved, options, hostAgent, lifecycle) {
 
   const sessionReservation = prepareCloudflareAgentSession(sessionId, subject);
   const subagentSessions = cloudflareSubagentSessions(
-    context.storage,
     sessionReservation,
     internalRuntime?.subagentLifecycle,
   );
@@ -353,6 +619,7 @@ async function createOwned(module, resolved, options, hostAgent, lifecycle) {
         fastMode: internalConfiguration.fast_mode,
       }),
       module,
+      rawApiEvents: internalRuntime?.rawApiEvents,
       toolMode: internalRuntime?.toolMode ?? "direct",
       codeEvaluator: internalRuntime?.codeEvaluator,
       [Symbol.for("nanocodex.browser.internalRuntime")]: {
@@ -360,17 +627,20 @@ async function createOwned(module, resolved, options, hostAgent, lifecycle) {
         subagentsEnabled: internalRuntime?.subagentsEnabled,
         subagentMaxConcurrency: internalRuntime?.subagentMaxConcurrency,
         subagentSessions,
+        subagentRouting: internalRuntime?.subagentRouting,
+        onSocketTiming: internalRuntime?.onSocketTiming,
         [CLOUDFLARE_SESSION_RESERVATION]: sessionReservation,
       },
       transport,
       sessionId,
       durability,
       durabilityId: stateId,
+      ...(forkResume === undefined ? {} : { resume: forkResume }),
     });
     // Managed voice needs the durable session before the separate Responses
     // relay is ready. Its preconnection remains owned by the host and a later
     // text turn consumes it through the same credential-checked transport.
-    if (internalRuntime?.waitForPreconnect !== false) {
+    if (!directInference && internalRuntime?.waitForPreconnect !== false) {
       await withTimeout(
         startup.promise,
         STARTUP_TIMEOUT_MS,
@@ -554,12 +824,14 @@ function validateInternalConfiguration(configuration) {
       "reasoning_mode",
       "fast_mode",
     ].includes(key))
-    || !["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-6-astra"]
+    || !["gpt-6.1-sol", "gpt-6-luna", "gpt-6-astra", "@cf/zai-org/glm-5.3", "kimi-k3", "mimo-v2.6-pro"]
       .includes(configuration.model)
     || !["none", "low", "medium", "high", "xhigh", "max"].includes(configuration.thinking)
     || !["standard", "pro"].includes(configuration.reasoning_mode)
     || typeof configuration.fast_mode !== "boolean"
-    || (configuration.model === "gpt-6-astra" && configuration.thinking === "none")) {
+    || (["@cf/zai-org/glm-5.3", "kimi-k3", "mimo-v2.6-pro"].includes(configuration.model)
+      && (!(configuration.model === "kimi-k3" ? ["low", "high"] : ["low", "medium", "high"]).includes(configuration.thinking) || configuration.reasoning_mode !== "standard"))
+    || (["gpt-6-astra", "gpt-6.1-sol"].includes(configuration.model) && configuration.thinking === "none")) {
     throw new TypeError("Cloudflare Agent internal configuration is invalid");
   }
 }
@@ -629,42 +901,28 @@ function initializeAgentStorage(storage) {
       state_id TEXT NOT NULL UNIQUE
     )
   `);
-  storage.sql.exec(`
-    CREATE TABLE IF NOT EXISTS nanocodex_cloudflare_subagents (
-      session_id TEXT PRIMARY KEY,
-      agent_id TEXT NOT NULL UNIQUE,
-      descriptor_json TEXT NOT NULL,
-      host_context_ref TEXT
-    )
-  `);
-  const subagentColumns = storage.sql.exec(
-    "PRAGMA table_info('nanocodex_cloudflare_subagents')",
-  ).toArray();
-  if (!subagentColumns.some(({ name }) => name === "host_context_ref")) {
-    storage.sql.exec(
-      "ALTER TABLE nanocodex_cloudflare_subagents ADD COLUMN host_context_ref TEXT",
-    );
-  }
+  // These tables belonged to durable children. Root records and identity remain
+  // untouched; obsolete child data must never restore a task tree on startup.
+  storage.sql.exec("DROP TABLE IF EXISTS nanocodex_cloudflare_subagents");
+  storage.sql.exec("DROP TABLE IF EXISTS nanocodex_cloudflare_subagent_checkpoints");
 }
 
-function cloudflareSubagentSessions(storage, reservation, lifecycle) {
-  const restoredHostContextRefs = new Map();
+function cloudflareSubagentSessions(reservation, lifecycle) {
+  const bindings = new Map();
   return Object.freeze({
-    restore() {
-      const restored = storage.sql.exec(
-        "SELECT descriptor_json, host_context_ref FROM nanocodex_cloudflare_subagents",
-      ).toArray().map(({ descriptor_json, host_context_ref }) => {
-        const descriptor = Object.freeze(JSON.parse(descriptor_json));
-        restoredHostContextRefs.set(
-          descriptor.sessionId,
-          host_context_ref === null ? undefined : host_context_ref,
-        );
-        return descriptor;
-      });
-      return Object.freeze(restored);
-    },
-    hostContextRef(sessionId) {
-      return restoredHostContextRefs.get(sessionId);
+    bindingDescriptor(sessionId, descriptor, hostContextRef) {
+      const retained = bindings.get(sessionId);
+      if (retained === undefined) return descriptor;
+      const original = retained.descriptor;
+      const attachesInitialProvenance = retained.hostContextRef === undefined
+        && typeof hostContextRef === "string" && descriptor.task === original.task;
+      if (original.sessionId !== descriptor.sessionId || original.agentId !== descriptor.agentId
+        || original.parentAgentId !== descriptor.parentAgentId || original.role !== descriptor.role
+        || (retained.hostContextRef !== hostContextRef && !attachesInitialProvenance)) {
+        throw new Error("Subagent binding identity or host context changed");
+      }
+      // Delegation replaces the Rust task, not its spawning-turn authority.
+      return original;
     },
     bind(sessionId, descriptor, hostContextRef) {
       if (!mayBindCloudflareSubagentSession(reservation)) return;
@@ -672,53 +930,36 @@ function cloudflareSubagentSessions(storage, reservation, lifecycle) {
         && (typeof hostContextRef !== "string" || hostContextRef.length === 0)) {
         throw new TypeError("subagent host context ref must be a non-empty string when supplied");
       }
-      const type = restoredHostContextRefs.has(sessionId) ? "reconstruct" : "bind";
-      storage.transactionSync(() => {
-        storage.sql.exec(
-          `INSERT INTO nanocodex_cloudflare_subagents
-             (session_id, agent_id, descriptor_json, host_context_ref) VALUES (?, ?, ?, ?)
-           ON CONFLICT (session_id) DO UPDATE SET
-             agent_id = excluded.agent_id,
-             descriptor_json = excluded.descriptor_json,
-             host_context_ref = excluded.host_context_ref`,
-          sessionId,
-          descriptor.agentId,
-          JSON.stringify(descriptor),
-          hostContextRef ?? null,
-        );
-        notifySubagentLifecycle(lifecycle, {
-          type,
-          rootSessionId: reservation.sessionId,
-          sessionId,
-          descriptor,
-          hostContextRef,
-        });
+      notifySubagentLifecycle(lifecycle, {
+        type: "bind", rootSessionId: reservation.sessionId,
+        sessionId, descriptor, hostContextRef,
       });
-      restoredHostContextRefs.delete(sessionId);
+      bindings.set(sessionId, { descriptor, hostContextRef });
     },
     release(sessionId, hostContextRef) {
       if (!mayReleaseCloudflareSubagentSession(reservation)) return;
-      storage.transactionSync(() => {
-        const retained = storage.sql.exec(
-          `SELECT 1 AS retained FROM nanocodex_cloudflare_subagents
-           WHERE session_id = ? AND host_context_ref IS ?`,
-          sessionId,
-          hostContextRef ?? null,
-        ).toArray();
-        if (retained.length === 0) return;
+      const retained = bindings.get(sessionId);
+      if (retained === undefined || retained.hostContextRef !== hostContextRef) return;
+      // Closing a parent releases its complete live subtree.
+      const removed = new Set([retained.descriptor.agentId]);
+      let changed;
+      do {
+        changed = false;
+        for (const { descriptor } of bindings.values()) {
+          if (removed.has(descriptor.parentAgentId) && !removed.has(descriptor.agentId)) {
+            removed.add(descriptor.agentId);
+            changed = true;
+          }
+        }
+      } while (changed);
+      for (const { descriptor, hostContextRef: context } of bindings.values()) {
+        if (!removed.has(descriptor.agentId)) continue;
         notifySubagentLifecycle(lifecycle, {
-          type: "release",
-          rootSessionId: reservation.sessionId,
-          sessionId,
-          hostContextRef,
+          type: "release", rootSessionId: reservation.sessionId,
+          sessionId: descriptor.sessionId, hostContextRef: context,
         });
-        storage.sql.exec(
-          `DELETE FROM nanocodex_cloudflare_subagents
-           WHERE session_id = ? AND host_context_ref IS ?`,
-          sessionId,
-          hostContextRef ?? null,
-        );
-      });
+        bindings.delete(descriptor.sessionId);
+      }
     },
   });
 }
@@ -788,3 +1029,20 @@ async function withTimeout(promise, timeoutMs, message) {
     clearTimeout(timer);
   }
 }
+
+/** Read a single Rust-owned receipt without loading/fencing the execution. */
+export function steerReceipt(owner, operationId, messageId) {
+  const { storage } = resolveContext(owner);
+  const tables = storage.sql.exec("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('nanocodex_cloudflare_durability', 'nanocodex_durable_states')").toArray();
+  if (tables.length !== 2) return null;
+  const stateId = storedStateId(storage);
+  if (stateId === undefined) return null;
+  const path = `$.nanocodex_durable_state.operations.${JSON.stringify(operationId)}.steer_receipts.${JSON.stringify(messageId)}`;
+  const row = storage.sql.exec("SELECT json_extract(payload, ?) AS receipt FROM nanocodex_durable_states WHERE state_id = ?", path, stateId).toArray()[0];
+  if (row?.receipt == null) return null;
+  const receipt = JSON.parse(row.receipt);
+  if (!/^[a-f0-9]{64}$/.test(receipt.input_key) || !Number.isSafeInteger(receipt.index) || receipt.index < 1 || typeof receipt.withdrawn !== "boolean") {
+    throw new Error("invalid durable steer receipt");
+  }
+  return Object.freeze(receipt);
+}

package/cloudflare/agent-settings.d.mts

@@ -0,0 +1,15 @@
+export const AGENT_MODELS: readonly ["gpt-6.1-sol", "gpt-6-luna", "gpt-6-astra", "@cf/zai-org/glm-5.3", "kimi-k3", "mimo-v2.6-pro"];
+export const AGENT_THINKING: readonly ["none", "low", "medium", "high", "xhigh", "max"];
+export const AGENT_REASONING_MODES: readonly ["standard", "pro"];
+export type ManagedAgentSettings = Readonly<{ model: typeof AGENT_MODELS[number]; thinking: typeof AGENT_THINKING[number]; reasoning_mode: typeof AGENT_REASONING_MODES[number]; fast_mode: boolean }>;
+export type ManagedAgentSettingsPatch = Partial<ManagedAgentSettings>;
+export const DEFAULT_AGENT_SETTINGS: ManagedAgentSettings;
+export function parseAgentSettingsQuery(search: URLSearchParams): ManagedAgentSettings;
+export function agentSettingsQuery(settings: ManagedAgentSettings): URLSearchParams;
+export function parseAgentSettingsPatch(value: unknown): ManagedAgentSettingsPatch;
+export function parseCompleteAgentSettings(value: unknown): ManagedAgentSettings;
+export function validateAgentSettings(settings: ManagedAgentSettings): ManagedAgentSettings;
+export function validateAgentAdmissionSettings(settings: ManagedAgentSettings): ManagedAgentSettings;
+export function isAgentModel(value: unknown): value is ManagedAgentSettings["model"];
+export function isAgentThinking(value: unknown): value is ManagedAgentSettings["thinking"];
+export function isAgentReasoningMode(value: unknown): value is ManagedAgentSettings["reasoning_mode"];