nanocodex 0.6.6 → 0.6.7

package/README.md

@@ -80,6 +80,15 @@ 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`.
 
+### Explicit Claude runtime
+
+`Claude.create` is an additive Messages backend with explicit host-owned auth
+and a Claude-only tool array, using the existing durability store contract.
+It does not silently switch managed providers, install Codex tools, or supply
+a subscription sign-in screen. Managed account connection is documented in the
+[managed Claude guide](../../docs/CLAUDE_MANAGED.md). See the [Claude JavaScript guide](../../docs/CLAUDE_JAVASCRIPT.md)
+for durable reopen, replay, and placement boundaries.
+
 ### Personal memories and caller context
 
 Managed agents can keep user preferences separate from team knowledge:
@@ -317,10 +326,17 @@ membership, room, quota, or application routing policy. Event frames are
 `1013`, then continues by reconnecting with that pause cursor as
 `?cursor=<decimal>`.
 
+`toolMode: "code-only"` exposes only `exec` and `wait` to the model. Workspace,
+application, discovery (`tools.tool_search`) and local subagent tools are callable
+inside Code Mode. Discovery returns tool information as cell output; it does not
+add direct schemas. Newly discovered tools are available in the next cell. The
+existing `"code"` mode retains direct workspace/subagent controls, and `"direct"`
+continues to expose function tools without requiring an evaluator.
+
 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
+evaluator. Select `toolMode: "code"` or `toolMode: "code-only"` only when also
+supplying an evaluator explicitly compatible with the deployed Worker runtime. Runtime-owned
 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
@@ -602,7 +618,7 @@ shared registry and installs fresh tools for every root, spawn, and fork:
 ```rust,ignore
 let (registry, control, updates) = nanocodex_subagents::channel(max_concurrency);
 let tools = Tools::builder().without_defaults().build()?;
-let tools = nanocodex_tools::embedded::bind_host(tools, javascript_host);
+let tools = nanocodex_oai_tools::embedded::bind_host(tools, javascript_host);
 let (agent, events) = Nanocodex::builder(openai)
     .tools_factory(move |handle| {
         nanocodex_subagents::install_tools(tools.clone(), handle, registry.clone())
@@ -669,8 +685,17 @@ 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.
 
+Tempo/MPP helpers live in `nanocodex/tempo`, whose optional peer dependencies
+`mppx` and `viem` are needed only when you import it; the core entry points
+never reference them.
+
+```sh
+npm install nanocodex mppx viem
+```
+
 ```js
-import { Agent, createTempoProviderFromAccounts, Transport } from "nanocodex/node";
+import { Agent, Transport } from "nanocodex/node";
+import { createTempoProviderFromAccounts } from "nanocodex/tempo";
 import { Expiry } from "accounts";
 import { Provider } from "accounts/cli";
 import { parseUnits } from "viem";
@@ -773,6 +798,22 @@ the relay preserves MPP challenges, credentials, and receipts but never signs.
 Passing a generic `MppSession`, an OpenAI key, or ChatGPT host auth does not
 initialize Mercator. Pass `mcp: false` to opt out explicitly.
 
+Trusted hosts can set a server's `privateResult` policy to intercept raw MCP
+results before model output, Code Mode values, and tool-result tracing.
+`beforeCall({ name, arguments }, context)` runs after payment context validation
+and before remote dispatch. It may reject the call or return `{ privateContext }`. An own
+`result` property instead supplies an already-safe receipt and bypasses both
+remote dispatch and `transformResult`, allowing durable policies to replay a
+receipt without repeating an effect.
+`transformResult({ name, arguments, result, privateContext }, context)` receives
+that invocation's `privateContext` and must return only safe MCP content. State stays local
+to each call, including concurrent calls; it is `undefined` without `beforeCall`.
+Both hooks run within the tool deadline. Failed private requests return a fixed
+failure receipt without the original error or cause. Discovery failures also use
+a fixed message. Callbacks and caller-owned clients remain trusted: they must
+not independently log private payloads or return private state. No notification
+consumer is configured by this policy.
+
 Remote Streamable HTTP MCP servers are configured directly on the agent. The
 JavaScript binding uses the official MCP SDK transport, keeps remote tools
 deferred, and mirrors native Nanocodex exposure: the initial Responses request
@@ -789,6 +830,9 @@ supports Tempo charge and session challenges, so paid services composed behind
 Mercator use the same signer and spending policy as the model:
 
 ```js
+import { tempo } from "mppx/client";
+import { createTempoProvider } from "nanocodex/tempo";
+
 const mcpMethod = tempo({
   account,
   channelStore,
@@ -809,6 +853,17 @@ const agent = await Agent.create({
 
 Explicit `mcp` entries are merged over the Tempo defaults, so an application
 can replace `mercator` or add other servers without rebuilding the provider.
+A paid server configured directly must wrap its options with `mcpPayment()` from
+`nanocodex/tempo`, which loads `mppx/mcp/client` on first connection; a plain
+`payment` object is rejected with a `TypeError`:
+
+```js
+import { mcpPayment } from "nanocodex/tempo";
+
+const mcp = {
+  paid: { url: "https://paid.example/mcp", payment: mcpPayment({ methods: [mcpMethod] }) },
+};
+```
 
 Each server also accepts `headers`, `fetch`, allow/deny tool lists, a timeout,
 or an already initialized MCP SDK-compatible `client`. Nanocodex closes clients
@@ -824,6 +879,80 @@ session and are invalidated when the host shuts down; a persisted `wait` never
 restarts missing work. Embedded cells retain ownership of all nested tool calls
 until they finish or are cancelled.
 
+Opt into observer-only instant steering with `instantToolSteering: true` in
+Node/browser or Cloudflare Agent creation. Managed creation uses
+`configuration: { instant_tool_steering: true }`. The default is false. Accepted
+steering yields a foreground `exec`/`wait` with its output and live cell ID,
+without cancelling evaluation or nested effects. Later `wait` resumes that
+same cell. Model streams are not interrupted by this option; see
+[the runtime boundaries](../../docs/codex-code-mode.md#observer-only-instant-steering).
+
+Owned `nanocodex/node` and `nanocodex/host` agents may opt into
+`codeEffectJournal` alongside their durability store. This trusted host adapter
+must durably acknowledge `begin(context)` before dispatch, validate the original
+session/call identity plus source/tool/input fingerprint, and fence stale owners.
+Journal keys must include
+`[sessionId, operationId ?? "", modelCallIndex ?? 0, parentCallId, callId]`.
+Owned SDK hosts synchronously observe original Rust request/idempotency identity
+and model-call ordinal before dispatch; missing canonical metadata interrupts
+rather than falling back to a projected turn/run ID. Provider call IDs may repeat
+across model responses within one operation and across operations. Use an explicit
+prompt operation `id` with a durable owned journal. Deliberately non-durable
+prompts (including ephemeral child tasks) emit an explicit null Rust operation
+ID; the host scopes those invocations to the unique trusted accepted input item.
+That scope does not promise cold replay of a non-durable task. Absent or malformed
+metadata still interrupts before effects. Generic explicit runtimes without
+an identity resolver retain their existing session/parent identity semantics.
+`turnId` is diagnostic metadata, not the effect replay key.
+Child event forwarding may race the host invocation. The owned SDK rendezvous
+with the exact accepted session/turn and fresh tool-call metadata before journal
+admission (one-second deadline, at most 128 waiters, abort/release/dispose cleanup).
+It never derives effect authority from a parent correlation envelope or reuses
+consumed model-call metadata. Parallel nested calls share one identity promise;
+missing or conflicting metadata fails closed without effect dispatch.
+This covers direct application tools (`toolMode: "direct"`) as well as tools
+invoked by Code Mode. Direct contexts use `parentCallId = callId` and
+`source = "host-tool:" + name`; nested contexts use the exact guest source
+and a stable cell/ordinal.
+Adapters can additionally implement `beginCell(context)` and
+`commitStore(context, writes)` together to persist Code Mode `store()` state.
+Before evaluation, `beginCell` durably pins the cell's immutable starting entries;
+recovery returns those same entries even when later cells changed session state.
+The context has `name: "code-cell"`, `callId: parentCallId`, and `input: null`.
+`commitStore` atomically merges only the cell's writes, once per original cell
+identity. A completed-cell replay must not overwrite newer committed writes.
+Completed failed scripts also commit their writes; interrupted/aborted cells do
+not. Session stores remain isolated and entry snapshots are bounded to 8 MiB and
+32,768 nodes. Hosts must fail closed when prior effects exist but their original
+starting snapshot is missing, corrupt, or cannot be proved during an upgrade.
+Without these optional methods, stores remain local to a runtime instance.
+
+Deterministic adapter conflicts and corruption should throw an error with
+`code: "CODE_EFFECT_UNKNOWN"`. These errors and invalid replay receipts settle
+as failed unknown outcomes, without admitting further effects. Storage/transport
+exceptions remain host interruptions so genuinely transient failures can recover.
+
+Return `execute` for a new retained intent, `replay` with its exact completed
+receipt, or `unknown` for an intent without a durable outcome. `complete` must
+acknowledge storage before either direct tool output or a nested guest result is
+returned. Direct receipts use `value: null` and `thrown: false` (handler failures
+remain failed encoded tool outputs, not guest throws). Unknown direct intents
+return an explicit failed tool result with `outcome: "unknown"` without dispatch.
+Unknown nested effects fail the recovered cell even if guest code catches the error; they are never silently
+rerun. Reconcile external state using the original operation identity.
+
+Receipts must contain plain JSON data and are bounded to an aggregate 8 MiB
+and 32,768 entries before output/value copies. Undefined results and raw undefined
+rejections have explicit markers. Identical output/structured/value payloads use
+receipt-local references (or derived JSON text), so ordinary inline media does
+not consume three copies. An oversized or unretainable post-effect receipt interrupts the host and
+leaves its original intent unknown, rather than granting permission to redispatch. Route larger media through a bounded
+artifact/reference tool instead of embedding it in the replay receipt.
+The journal is opt-in for generic SDK hosts; durability alone does not make
+direct or nested application effects safe to rerun after abrupt owner loss.
+It does not journal arbitrary native JavaScript/evaluator effects, built-in
+provider-native tools, or external operations outside the application-tool router.
+
 Custom evaluators receive `audio`, `notify`, `yield_control`, `setTimeout`, and
 `clearTimeout` alongside the existing globals in `CodeEvaluatorEnvironment`.
 Forward those helpers into the guest environment to preserve the model-visible
@@ -838,7 +967,7 @@ keeps deferred MCP plus Code Mode functional in Cloudflare Workers:
 
 ```js
 import asyncVariant from "@jitl/quickjs-wasmfile-release-asyncify";
-import { Agent, createQuickJsEvaluator, createTempoProvider, Transport } from "nanocodex/host";
+import { Agent, createQuickJsEvaluator, Transport } from "nanocodex/host";
 import { newQuickJSAsyncWASMModuleFromVariant } from "quickjs-emscripten-core";
 
 const quickJs = await newQuickJSAsyncWASMModuleFromVariant(asyncVariant);
@@ -1181,7 +1310,7 @@ package manager or build step:
 
 ```html
 <script type="module">
-  import { Agent, Transport } from "https://cdn.jsdelivr.net/npm/nanocodex@0.6.6/host/index.mjs";
+  import { Agent, Transport } from "https://cdn.jsdelivr.net/npm/nanocodex@0.6.7/host/index.mjs";
   const agent = await Agent.create({
     transport: Transport.hostManaged({
       websocketUrl: "/api/responses",
@@ -1361,3 +1490,165 @@ 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.
+
+
+## Connect dialog appearance
+
+Pass visual tokens when creating an embedded or popup Connect dialog:
+
+```js
+import { Client, Dialog } from "nanocodex/connect";
+
+const appearance = {
+  theme: "system",
+  accentColor: "#635bff",
+  fontFamily: '"Open Sans", system-ui, sans-serif',
+  borderRadius: 12,
+};
+const client = Client.create({
+  appId: "your-app-id",
+  dialog: Dialog.iframe({ appearance }),
+});
+// Dialog.popup({ appearance }) accepts the same options for account authorization.
+```
+
+All fields are optional. `theme` accepts `light`, `dark`, or `system`;
+`accentColor` requires six hex digits; `fontFamily` accepts an installed or
+self-hosted font list of at most 160 characters; `borderRadius` is a number from
+0 to 24 pixels. Arbitrary CSS, CSS functions, and unknown options are rejected.
+The SDK snapshots the configuration when the dialog is created and carries it
+in the `nanocodex_appearance` URL parameter to wallet and funding iframes or the
+account popup. The hosted dialog limits the JSON value to 1,024 characters and
+uses native defaults for malformed values. Omit `appearance` for native defaults.
+
+### Standalone account services
+
+`nanocodex/services` accesses Vault and dedicated SMS numbers without an agent,
+thread, model, or WASM runtime. Keep direct account API keys on your server:
+
+```js
+import { createServicesClient } from "nanocodex/services";
+
+const services = createServicesClient({ apiKey: process.env.NANOCODEX_API_KEY });
+const { vault } = await services.vault.list();
+const { status, ok } = await services.vault.request({
+  vault_id: vault[0].id,
+  url: "https://example.com/verify",
+  method: "POST",
+  body_encoding: "json",
+  body: '{"code":"{{NANOCODEX_VAULT_TOTP}}"}',
+});
+```
+
+Direct calls use `https://nanocodex.gakonst.workers.dev/v1/services`. Reads require
+`data:read`, Vault requests require `tools:use`, and phone intents require
+`data:write` plus `tools:use`. Vault returns metadata and destination HTTP status
+only. TOTP seeds and generated codes stay in the broker; the saved exact HTTPS
+origin bounds code injection. There is no code-export method.
+
+Browser apps use an existing Connect client and exact signed service capabilities:
+
+```js
+import { Client } from "nanocodex/connect";
+import { createServicesClient } from "nanocodex/services";
+
+const connect = Client.create({ appId: "example-app" });
+const connection = await connect.connection.connect({
+  capabilities: {
+    services: {
+      vault: { ids: ["selected-vault-id"], origins: ["https://example.com"], request: true },
+      phone: { numberIds: [], read: false, provision: true, release: false },
+    },
+  },
+});
+const services = createServicesClient({ connect, grantId: connection.grant.id });
+```
+
+Service-only connections default to `services.use` and hosted authorization.
+They contain no `agentId`, access key, or MPP budget. Scope is bound into the
+signed approval and checked against the returned grant. Reconnect with the same
+`capabilities.services` to require that exact scope. Service requests use
+`/v1/grants/:grantId/services/...` and the Connect session. Number and Vault IDs
+are explicit; they never expand to the entire account.
+
+Use `phone.available({ country: "US", area_code: "202" })`, `phone.list()`,
+`phone.get(id)`, and `phone.messages(id, { limit: 20, cursor })` for reads. SMS
+messages expire according to the service's retention policy; support for
+verification messages depends on the sender and carrier.
+
+Provisioning and release create requests for human review:
+
+```js
+import { createHostedRequest, openHostedPopup } from "nanocodex/services";
+
+// Persist this UUID before sending; keep it when reconciling an uncertain request.
+const operation_id = crypto.randomUUID();
+const { request } = await services.phone.provision({
+  operation_id, phone_number: "+12025550101", country: "US",
+});
+const approval = createHostedRequest({
+  service: "phone", operationId: request.approval_request_id ?? request.operation_id, appOrigin: location.origin,
+});
+// Open from a separate click handler after the request is ready.
+await openHostedPopup(approval);
+const result = await services.phone.requests.get(request.operation_id);
+```
+
+`phone.release(numberId, { operation_id })` also requires hosted human approval.
+Poll with the **original** caller UUID, including after a dropped intent response.
+Connect returns an additional `request.approval_request_id` for the hosted owner
+approval; use `request.approval_request_id ?? request.operation_id` for its link.
+Any deliberate identical intent replay must retain the original caller UUID.
+A newly provisioned number needs a fresh exact-ID Connect approval before inbox
+access. The SDK never automatically retries a write. `ServiceError` exposes
+`status`, `code`, and `outcomeUnknown`; an unknown outcome requires reconciliation,
+not a new operation ID. No SDK method approves purchases or releases.
+
+TOTP enrollment uses a private hosted form:
+
+```js
+const enrollment = createHostedRequest({ appOrigin: location.origin });
+// Call from a user click. Inputs stay on the account origin.
+const metadata = await openHostedPopup(enrollment);
+if (metadata.service === "vault") console.log(metadata.vault_id);
+```
+
+The popup helper checks the sender window, exact hosted origin, and a unique
+state. Only fixed metadata fields reach the caller. `createHostedRequest`
+also accepts `host` for a trusted HTTPS account deployment and `state` for a
+caller-managed unique nonce. Secret entry and approvals require a top-level window; embedded frames cannot
+perform them. React applications can open the same request with
+`HostedServiceButton` from `nanocodex-react/services`.
+
+To use an existing Vault item before granting access, open the account picker
+from a user click. No service client or Connect grant is needed:
+
+```js
+const selection = createHostedRequest({
+  service: "vault", action: "select", appOrigin: location.origin,
+});
+const selected = await openHostedPopup(selection);
+if (selected.service === "vault" && selected.action === "select") {
+  // The user sees the recipient origin and explicitly chooses this item.
+  // Only its opaque vault_id, kind, and name are shared.
+  const connection = await connect.connection.connect({
+    capabilities: { services: { vault: {
+      ids: [selected.vault_id], origins: ["https://example.com"], request: true,
+    } } },
+  });
+}
+```
+
+The picker does not create or expand a grant and does not enroll the item again.
+The separate Connect approval authorizes the exact selected ID and destination
+origins. Closing the popup or aborting its `signal` cancels the local wait;
+closing a phone approval window does not cancel a server-side operation. Poll
+that operation with its original caller UUID to learn its outcome.
+
+Account management is available through `createServicesClient({ apiKey }).account`
+without an agent or WASM. Use `client.links({ connect: 'google', add: 'login' })`
+for ordinary Connections/Vault URLs, or
+`client.hosted({ service: 'vault', kind: 'card' })` for a private enrollment link.
+OAuth, Cloudflare, MCP, model sign-in, Vault/SSH management, and captured-card
+save/balance methods share the account REST contracts. See the
+[REST, JavaScript and Rust guide](../../docs/STANDALONE_SERVICES.md#account-management-and-browser-links).

package/THIRD-PARTY-LICENSES

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+Copyright (c) 2025-2026 Can Bölük
+Copyright (c) 2026 Stencil Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/browser/Agent.d.mts

@@ -22,10 +22,11 @@ type WorkerMcpServer = Readonly<{
 }>;
 type WorkerMcpServers = Readonly<Record<string, string | URL | WorkerMcpServer>>;
 type WorkerToolExposureOptions =
-  | { mcp?: false | undefined; toolMode?: "code" | "direct" | undefined }
-  | { mcp: WorkerMcpServers; toolMode?: "code" | undefined };
+  | { mcp?: false | undefined; toolMode?: "code" | "code-only" | "direct" | undefined }
+  | { mcp: WorkerMcpServers; toolMode?: "code" | "code-only" | undefined };
 
 /** Creates a Rust/WASM Agent in a package-owned browser module Worker. */
+export function create(options: import('../runtime/claude.mjs').Options & { harness: 'claude' }): Promise<import('../runtime/claude.mjs').Agent>;
 export function create(options: create.ManagedOptions): Promise<AgentLifecycle>;
 export function create(options?: create.Options): Promise<create.ReturnType>;
 export declare namespace create {
@@ -33,7 +34,7 @@ export declare namespace create {
     transport: ManagedTransport;
     tools?: Tools | undefined;
   }>;
-  type Options = Omit<AgentOptions, "beforeCompaction"> & WorkerToolExposureOptions & {
+  type Options = Omit<AgentOptions, "beforeCompaction" | "harness"> & WorkerToolExposureOptions & {
     /** Precompiled browser module; WebAssembly modules are structured-clone-safe. */
     module?: WebAssembly.Module | undefined;
     /** Fixed browser workspace facts, including its AGENTS.md snapshot. */
@@ -47,7 +48,7 @@ export declare namespace create {
     /** Set false to keep this browser session out of the IndexedDB durability store. */
     durability?: false | undefined;
     /** Set false to omit the default OPFS, shell, web, image, plan, and artifact tools. */
-    harness?: false | undefined;
+    harness?: false | 'codex' | undefined;
   };
   type ReturnType = Agent;
 }

package/browser/Agent.mjs

@@ -5,6 +5,10 @@ import {
 
 /** Create the browser Agent in its package-owned module Worker. */
 export function create(options = {}) {
+  if (options.harness === 'claude') return import('./Claude.mjs').then(({ create }) => create(options));
+  if (options.harness !== undefined && options.harness !== false && options.harness !== 'codex') throw new TypeError('unsupported harness family');
+  if (options.harnesses !== undefined) return import('./InlineAgent.mjs').then(({ create }) =>
+    create(options.harness === false ? { ...options, harness: 'codex' } : options));
   if (managedTransportOptions(options?.transport)) return createManagedAgent(options);
   return import("./WorkerAgent.mjs").then(({ createWorkerAgent }) =>
     createWorkerAgent(options));

package/browser/Claude.d.mts

@@ -0,0 +1,4 @@
+import type { Agent, Options } from '../runtime/claude.mjs';
+export type { Agent, Auth, Options, NativeToolResult, Result, Tool, ToolContent, ToolResult, Turn } from '../runtime/claude.mjs';
+/** Creates the actual Claude Rust/WASM backend with explicit host-owned authentication and tools. */
+export function create(options: Options): Promise<Agent>;

package/browser/Claude.mjs

@@ -0,0 +1,11 @@
+import { createClaude } from '../runtime/claude.mjs';
+import { initializeBrowserEngine } from './engine.mjs';
+
+/** Runs inline in this browser isolate; not the Codex Agent module Worker. */
+export function create(options) {
+  return createClaude(options, async (module) => {
+    const wasm = await import('../pkg-web/nanocodex.js');
+    await initializeBrowserEngine({ module });
+    return wasm.Nanoclaude;
+  }, 'browser');
+}

package/browser/InlineAgent.mjs

@@ -1,3 +1,5 @@
+import { prepareHarnesses } from '../runtime/harnesses.mjs';
+import { create as createClaude } from './Claude.mjs';
 import { applyBrowserPatch, Nanocodex } from "../pkg-web/nanocodex.js";
 
 import { agentActions } from "../actions/index.mjs";
@@ -33,6 +35,8 @@ import {
 
 /** Creates the Rust/WASM Agent in the current Web API host isolate. */
 export async function create(options = {}) {
+  if (options.harness === 'claude') return createClaude(options);
+  if (options.harness !== undefined && options.harness !== 'codex') throw new TypeError('unsupported harness family');
   if (managedTransportOptions(options?.transport)) return createManagedAgent(options);
   const internalRuntime = options[Symbol.for("nanocodex.browser.internalRuntime")];
   if (internalRuntime !== undefined
@@ -46,6 +50,7 @@ export async function create(options = {}) {
     thinking,
     reasoningMode,
     fastMode,
+    instantToolSteering,
     rawApiEvents,
     instructions,
     additionalInstructions,
@@ -63,6 +68,7 @@ export async function create(options = {}) {
     mcp,
     executionEnvironment,
     codeEvaluator,
+    codeEffectJournal,
   } = options;
   const toolProviders = internalRuntime?.toolProviders;
   const subagentSessions = internalRuntime?.subagentSessions;
@@ -109,9 +115,12 @@ export async function create(options = {}) {
     throw new TypeError("workspace must match filesystem.root when both are provided");
   }
   const events = createEventChannel();
+  // Host lifecycle observers need terminal events even without a public watcher.
+  events.subscribe(() => {});
   const tempoMcp = mpp?.[Symbol.for("nanocodex.tempo.mcp")];
   let hostDefinitionId;
   const host = createBrowserHost({
+    [Symbol.for("nanocodex.browser.internalRuntime")]: { traceTool: internalRuntime?.traceTool },
     WebSocketImpl,
     createWebSocket,
     createResponse,
@@ -128,16 +137,19 @@ export async function create(options = {}) {
     subagentSessions,
     subagentRouting: internalRuntime?.subagentRouting,
     onSocketTiming: internalRuntime?.onSocketTiming,
+    onSocketEvent: internalRuntime?.onSocketEvent,
     toolMode,
     mcp: mcp === false
       ? undefined
       : tempoMcp ? { ...tempoMcp, ...mcp } : mcp,
     codeEvaluator,
+    codeEffectJournal: internalRuntime?.codeEffectJournal ?? codeEffectJournal,
     applyPatch: applyBrowserPatch,
     websocketPreconnect,
     websocketUrl,
-    onDispose: () => releaseDefinitionHost(hostDefinitionId),
+    onDispose: () => { releaseDefinitionHost(hostDefinitionId); void harnesses?.close(); },
   });
+  let harnesses;
   let durabilityOwner;
   let creationStarted = false;
   hostDefinitionId = registerDefinitionHost(host, cloudflareReservation);
@@ -157,6 +169,9 @@ export async function create(options = {}) {
             durabilityId,
           );
         }
+        harnesses = await prepareHarnesses(options.harnesses, events.emit, {
+          subagentSessions, subagentRouting: internalRuntime?.subagentRouting,
+        });
         activateHost(host);
         await host.ready();
         await initializeBrowserEngine({ module });
@@ -172,9 +187,11 @@ export async function create(options = {}) {
           websocketWarmup,
           stateless,
           subagents: subagentConfig,
+          claudeHarness: harnesses?.claude,
           subagentRouting: internalRuntime?.subagentRouting !== undefined,
           hostDefinitionId,
           beforeCompaction: beforeCompaction !== undefined,
+          promptCacheKey: internalRuntime?.promptCacheKey,
           ...config,
           durabilityHostId: durabilityOwner?.id,
         }));
@@ -246,6 +263,7 @@ export async function create(options = {}) {
       thinking,
       reasoningMode,
       fastMode,
+      instantToolSteering,
       rawApiEvents,
       instructions,
       additionalInstructions,

package/browser/host.d.mts

@@ -1,5 +1,6 @@
 import type {
   CodeEvaluator,
+  CodeEffectJournal,
   McpServers,
   MppSession,
   SubagentToolContext,
@@ -51,12 +52,60 @@ export type BrowserWebSocketConnection = {
   socket: WebSocket;
   status?: number | undefined;
   requestId?: string | undefined;
+  /** @internal Correlation with the separately deployed credential egress. */
+  egressRequestId?: string | undefined;
   serverModel?: string | undefined;
   reasoningIncluded?: boolean | undefined;
   turnState?: string | undefined;
 };
 
+/** @internal Passive lifecycle metadata; never provider frames or request content. */
+export type BrowserSocketObservation = {
+  event: "socket.connecting" | "socket.connect_waiting" | "socket.opened" | "socket.closed" | "socket.error"
+    | "request.send_started" | "request.send_waiting" | "request.sent" | "request.waiting" | "request.first_message"
+    | "request.first_output" | "request.first_reasoning_delta" | "request.first_answer_delta" | "request.first_tool_delta" | "request.finished" | "provider.timing";
+  socket_id: string;
+  request_id: string;
+  egress_request_id?: string;
+  provider_request_id?: string;
+  response_id?: string;
+  socket_request_index?: number;
+  model_call_index?: number;
+  phase?: "generation" | "compaction" | "warmup";
+  outcome?: "completed" | "failed" | "send_failed" | "superseded";
+  elapsed_ms?: number;
+  send_wait_ms?: number;
+  first_message_ms?: number;
+  first_output_ms?: number;
+  first_reasoning_delta_ms?: number;
+  first_answer_delta_ms?: number;
+  first_tool_delta_ms?: number;
+  /** Fixed protocol name, or unclassified for oversized/unknown envelopes. */
+  provider_event_type?: string;
+  output_kind?: "item" | "reasoning" | "answer" | "tool";
+  last_message_age_ms?: number;
+  received_message_count?: number;
+  queued_message_count?: number;
+  socket_delivered_message_count?: number;
+  socket_queue_residence_max_ms?: number;
+  buffered_send_bytes?: number;
+  close_code?: number;
+  close_clean?: boolean;
+  intentional?: boolean;
+  pre_inference_ms?: number;
+  engine_queue_max_ms?: number;
+  engine_service_ttft_total_ms?: number;
+};
+
 export function createBrowserHost(options?: {
+  /** @internal Trusted runtime configuration carried by nanocodex.browser.internalRuntime. */
+  [key: symbol]: {
+    traceTool?: <T>(
+      name: string,
+      context: { sessionId: string; callId: string; parentCallId?: string; turnId?: string },
+      run: () => Promise<T>,
+    ) => Promise<T>;
+  } | undefined;
   WebSocketImpl?: typeof WebSocket;
   hostAuth?: boolean;
   hostManagedProtocol?: boolean;
@@ -74,7 +123,9 @@ export function createBrowserHost(options?: {
   /** Remote MCP servers exposed through native and Code Mode tool_search plus deferred tools. */
   mcp?: McpServers;
   codeEvaluator?: CodeEvaluator;
-  toolMode?: "code" | "direct";
+  /** @internal Trusted durable effect receipts, not available inside guest code. */
+  codeEffectJournal?: CodeEffectJournal;
+  toolMode?: "code" | "code-only" | "direct";
   /** @internal Live host lifecycle for ephemeral Rust-owned subagents. */
   subagentRouting?: Pick<import('../runtime/subagent-routing.mjs').SubagentRouting, 'resolve' | 'bind'>;
   subagentSessions?: {
@@ -97,6 +148,8 @@ export function createBrowserHost(options?: {
       engine_service_ttft_total_ms?: number;
     }>;
   }) => void;
+  /** @internal Live observations while an owned request waits; does not cancel it. */
+  onSocketEvent?: (event: BrowserSocketObservation) => void;
   maxQueuedMessages?: number;
   maxQueuedBytes?: number;
   maxBufferedSendBytes?: number;