@uppercut-labs/agent-native 0.0.0-stage → 1.1.0

package/docs/harness-codex.md

@@ -0,0 +1,117 @@
+# Codex local harness
+
+The isolated `@uppercut-labs/agent-native/harness/codex` export controls an installed
+Codex CLI app-server over stdio. It needs Node 22+ built-ins and a caller-installed
+Codex executable, with no provider SDK dependency. Importing the export or creating
+the adapter starts no process or inference. These additions require version 0.1.1. Use the versioned installation route in
+[installation](installation.md); 0.1.0 does not include this adapter.
+
+## Authentication and model selection
+
+Use `codex login` and complete Codex's managed ChatGPT sign-in. The adapter checks
+`account/read` with `refreshToken: false` before creating/resuming a thread and
+requires account type `chatgpt` and the provider's `requiresOpenaiAuth` flag. Codex owns credential storage and renewal. Do not
+pass a token, copy authentication files, or log account responses.
+
+This route uses the eligible ChatGPT-plan Codex path. It does not require an OpenAI
+Platform API key, use the OpenAI Agents API, or implement external OAuth token
+injection. API-key accounts are rejected with `authentication-required`; there is
+no automatic API-billed fallback. Account eligibility, usage limits and model
+availability still belong to the provider. See [official authentication guidance](https://developers.openai.com/codex/auth/).
+
+Select `model` explicitly; the adapter never substitutes another model. `effort`
+defaults to `low` and may be `low`, `medium`, `high`, `xhigh`, or `max` when the selected
+model supports it. The real acceptance fixture used the installed runtime's
+`gpt-5.6-luna` catalog entry; this is tested evidence, not a latest-model claim.
+
+## Lifecycle
+
+```ts
+import { createCodexHarnessAdapter } from '@uppercut-labs/agent-native/harness/codex';
+
+const adapter = createCodexHarnessAdapter({ model: 'gpt-5.6-luna' });
+const workspace = '/absolute/path/to/disposable-workspace';
+const session = await adapter.openSession({ target: 'local', workspace });
+try {
+  for await (const event of adapter.runTurn({ session, prompt: 'Create a small example.' })) {
+    // Render normalized events; do not publish the opaque session/turn IDs.
+  }
+} finally {
+  await adapter.closeSession({ session });
+}
+```
+
+`describe()` advertises local-only support with `resume`, `cancel`, and `usage`.
+Cloud open/resume is rejected. Local workspaces must be existing absolute directories;
+the adapter canonicalizes them and rejects resume into a different directory.
+The app-server's `thread.id` is preserved as the opaque session ID. Resume reads
+the persisted thread's workspace before `thread/resume`, checks the returned ID
+and directory, and can reattach through a new adapter/process after close.
+
+Each session owns one app-server process. It initializes the protocol connection,
+acknowledges `initialized`, checks managed login, and starts/resumes the thread
+with the explicitly selected model and `openai` provider. The sandbox defaults
+to `workspace-write`; `read-only` is also supported. No full-access option is exposed.
+Noninteractive approval policy is `never`; unexpected command/file approval requests
+are explicitly declined, MCP elicitations are declined, and other interactive
+requests receive a fixed unsupported response. The adapter never grants extra
+permissions. Codex's existing user/project configuration, skills, plugins, rules,
+and MCP settings still apply; this is not an empty provider configuration.
+
+`runTurn` sends one text input to `turn/start`, yields `turn-started`, then streams
+normalized tool/usage events and a terminal result. Only provider status `completed`
+produces `completed`; `interrupted` becomes `cancelled`, and failed/unknown terminal
+status becomes `failed`. Unauthorized terminal failures map to
+`authentication-required`. Raw model deltas, arguments, commands, diffs, reasoning,
+account details, stderr and provider exceptions are never forwarded.
+
+Token usage events project `tokenUsage.last.totalTokens` as nonnegative safe-integer
+snapshots. Several updates can occur in one turn; do not sum snapshots as a cost
+estimate. Missing usage remains unavailable. A session allows only one active turn;
+resume and overlapping turns are rejected until its stream is consumed/closed.
+`cancelTurn` checks the exact active turn ID and sends `turn/interrupt`.
+
+## Bounds and cleanup
+
+`requestTimeoutMs` defaults to 30000 (1-300000). `turnTimeoutMs` defaults to 180000
+(1-3600000) and stops on the provider's terminal notification, even if a consumer
+is still rendering queued events. Prompt size is limited to 65536 characters.
+The transport bounds its unparsed buffer to 2,097,152 UTF-16 code units and the normalized queue to 256
+events. Malformed protocol, process exit and exhausted bounds cannot imply success.
+
+`closeSession` is idempotent for a known session. It closes only the adapter-owned
+stdin/process, waits `shutdownTimeoutMs` (default 2000, range 1-10000), then signals
+that child PID with SIGTERM and finally SIGKILL if needed. Each wait is bounded;
+cleanup failure is surfaced. No process-name search or unrelated-process kill is
+used. Close releases runtime resources; it does not erase Codex's persisted thread.
+Abandoning a turn stream also closes its owned runtime. Consume streams and close
+sessions in `finally` so resources are released promptly.
+
+`executable` defaults to `codex` on the caller's PATH; `executableArgs` optionally
+selects a trusted launcher prefix. The adapter does not install a CLI or change
+global configuration. A missing executable raises `CodexHarnessError` with
+`provider-unavailable` and fixed installation guidance; missing/alternate auth has
+fixed `codex login` guidance. Other failures use the neutral stable reasons.
+
+## MCP boundary and acceptance
+
+Capability execution remains a separate authorized application plane. This adapter
+does not expose a programmatic MCP-configuration API and does not advertise `mcp`.
+Existing Codex MCP configuration follows the application's own authorization.
+The [loopback helper](harness-mcp-bridge.md) does not grant application permissions
+and cannot serve cloud agents through an implicit public tunnel.
+
+Provider-free tests cover thread mapping, cross-process resume, unavailable runtime,
+wrong auth, malformed/timeout responses, stream failures, targeted interrupt, concurrent
+turns, workspace mismatch, permission rejection and bounded owned cleanup.
+To deliberately opt into real inference in a disposable workspace:
+
+```sh
+npm run proof:codex -- --model gpt-5.6-luna
+```
+
+The proof verifies `hello world`, closes the first process, resumes the same thread
+in a new process, then verifies `hello Codex`. It prints only normalized evidence
+and removes its temporary workspace. Regular checks never launch real inference.
+See [version evidence](evidence/codex-harness.md) and the
+[official app-server protocol](https://developers.openai.com/codex/app-server/).

package/docs/harness-mcp-bridge.md

@@ -0,0 +1,30 @@
+# Local harness MCP bridge
+
+Import `startHarnessMcpBridge` from `@uppercut-labs/agent-native/harness/mcp-bridge`
+in Node 22+. It serves an application-supplied Web Request/Response MCP handler
+on `127.0.0.1` at `/mcp`, using an ephemeral port by default. It refuses public
+binds and validates Host/Origin, preserving handler authentication and capability
+authorization. It does not import the MCP SDK or mint credentials.
+
+```ts
+const bridge = await startHarnessMcpBridge({ handler: applicationMcpHandler });
+try {
+  // Configure the local provider to connect to bridge.url.
+} finally {
+  await bridge.close();
+}
+```
+
+`port` may be 0-65535. `maxRequestBytes` defaults to 32768 (1-1048576), and
+`deadlineMs` defaults to 30000 (1-300000), including response streaming. Oversized
+requests receive 413; deadlines abort the request and return 504 before headers
+or close an already streaming response. Handler errors produce a fixed diagnostic
+and 500 or stream closure. Handlers must honor AbortSignal to release their own work.
+Idempotent `close()` aborts active requests and closes only owned connections.
+
+Loopback is reachable by local processes and is not an authorization grant.
+Anonymous MCP initialization may succeed while protected calls stay denied.
+Application policy remains authoritative at discovery and execution. Cloud agents
+need a caller-supplied reachable authenticated endpoint; this helper never creates
+a public bind or tunnel. See [MCP policy](mcp.md) and
+[harness contracts](programmatic-harness.md).

package/docs/http.md

@@ -0,0 +1,80 @@
+# HTTP and OpenAPI adapter
+
+Import the HTTP adapter from its separate package entrypoint:
+
+```ts
+import { createHttpHandler } from '@uppercut-labs/agent-native/http';
+```
+
+`createHttpHandler(registry, options)` returns a handler from the standard Web `Request` API to
+`Response`. Mount that function in a framework or server of your choice. The core contract and
+executor remain independent of HTTP, Node, and framework modules.
+
+The default base path is `/agent-native/v1`. Public, read-only capabilities receive a deterministic
+`POST /agent-native/v1/capabilities/{namespace}/{name}/v{major}/invoke` route. The endpoint is a
+generic capability invocation, not a generated REST resource API. By default there is no GET
+invocation route; a GET to a visible invocation path receives `405` with `Allow: POST`.
+
+A definition may preserve an established read route with a contract-level override:
+
+E10 keeps its existing search route with this override in the tested capability definition:
+
+<!-- source:examples/e10-existing-functions-retrofit/project/src/capability.mjs#http-get-override -->
+~~~js
+http: {
+  path: '/api/content/search',
+  method: 'GET',
+  query: { query: 'q' },
+},
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e10-existing-functions-retrofit/project/src/capability.mjs#L33)
+<!-- /source -->
+
+The `query` map runs from input property to query parameter. GET conversion supports string,
+number, integer, boolean, string enum, and arrays of those scalar values; nested objects and other
+lossy conversions fail when the HTTP adapter is created. GET overrides are rejected for write or
+destructive capabilities. Paths must be absolute and unique across visible definitions. The same
+override drives routing and OpenAPI parameters.
+
+The adapter uses the shared executor for schema validation, authorization, binding selection, and
+output validation. Its default authorization policy permits only definitions explicitly marked as
+public reads. Supply `resolveExecutionContext` to adapt a trusted authentication boundary; this
+does not replace authorization in the executor. Hidden/protected definitions are omitted from the
+public OpenAPI document and route map, and unknown paths return the same `404` shape.
+
+OpenAPI 3.1 is generated directly from the public definitions' input/output `SchemaPort` values.
+The same document is available at `GET /agent-native/v1/openapi.json`. A health observation at
+`GET /agent-native/v1/health` records an actual protocol request as `UAN-003.http-protocol`.
+
+The default request body limit is 32 KiB and can be set from 1 byte to 1 MiB with
+`maxRequestBytes`. The default execution deadline is 10 seconds and the configurable maximum is
+300 seconds. At a deadline the handler returns `504` and sets `context.signal.aborted`. Bindings
+must observe that signal to stop their work; JavaScript cannot forcibly stop a handler that ignores
+cooperative cancellation.
+
+| Result | HTTP status |
+| --- | ---: |
+| Validated capability result | 200 |
+| Visible capability path with an unsupported method | 405 (Allow: POST) |
+| Malformed JSON | 400 |
+| Capability missing or hidden | 404 |
+| Body exceeds limit | 413 |
+| Unsupported content type | 415 |
+| Input schema failure | 422 |
+| Handler or output schema failure | 500 |
+| Binding/auth context unavailable | 503 |
+| Execution deadline reached | 504 |
+
+This slice has no framework-specific route installer or authenticated OpenAPI projection,
+rate limiter, or provider deployment integration. A host remains responsible for transport security,
+authentication, rate limiting, and deployment.
+
+## Reproduce the GET override
+
+With Node.js 22 or newer, run `npm ci` and `npm run example:e10` at the root.
+In the exported E10 project, start `npm start`, then request
+`http://127.0.0.1:8788/api/content/search?q=night&limit=1`; the response contains
+the existing first search match. Missing `q` or a fractional `limit` returns
+`invalid_input` without invoking the source function. Supply a valid query and
+integer limit, then retry. See [E10 setup](https://github.com/uppercut-labs/agent-native/blob/main/examples/e10-existing-functions-retrofit/project/README.md).

package/docs/installation.md

@@ -0,0 +1,95 @@
+# Installing only the surfaces you use
+
+To wrap a working site’s existing operation, follow [adopt an existing site](adopt-existing-site.md).
+
+Agent Native `1.0.1` requires Node.js 22 or newer. Install the package and only the peers your application imports:
+
+```sh
+npm install @uppercut-labs/agent-native@1.0.1
+```
+
+If 1.0.1 is not available from your npm registry, use its public GitHub release
+archive. In a disposable directory, download and verify the release files before
+installing the archive into the intended project:
+
+```sh
+curl --fail --location --output uppercut-labs-agent-native-1.0.1.tgz \
+  https://github.com/uppercut-labs/agent-native/releases/download/v1.0.1/uppercut-labs-agent-native-1.0.1.tgz
+curl --fail --location --output uppercut-labs-agent-native-1.0.1.tgz.sha256 \
+  https://github.com/uppercut-labs/agent-native/releases/download/v1.0.1/uppercut-labs-agent-native-1.0.1.tgz.sha256
+shasum -a 256 -c uppercut-labs-agent-native-1.0.1.tgz.sha256
+npm install ./uppercut-labs-agent-native-1.0.1.tgz
+```
+
+On Linux, `sha256sum -c` can replace `shasum -a 256 -c`. Stop if verification
+fails. The checksum detects an altered download; it is not an npm provenance
+attestation. Both release files are hosted with the tagged public source.
+
+The public package has no global `agent-native` executable. Applications call its APIs or expose their own CLI runner. The repository examples independently install local tarballs so their checks stay tied to a source commit.
+
+## First local capability
+
+Add Zod for the schema adapter, then save the following as `quickstart.mjs` in your application:
+
+```sh
+npm install zod@4.6.5
+```
+
+```js
+import { bindCapability, createCapabilityRegistry, defineCapability, executeCapability } from '@uppercut-labs/agent-native';
+import { fromZod } from '@uppercut-labs/agent-native/schema/zod';
+import * as z from 'zod';
+
+const greet = defineCapability({
+  identity: { namespace: 'demo', name: 'greet', majorVersion: 1 },
+  description: 'Greet one person.',
+  input: fromZod(z.object({ name: z.string().min(1) })),
+  output: fromZod(z.object({ message: z.string() })),
+  risk: 'read',
+  access: { kind: 'public' },
+});
+const registry = createCapabilityRegistry(
+  [greet],
+  [bindCapability(greet, {
+    id: 'local-greet',
+    targets: ['local'],
+    execute: async ({ name }) => ({ message: 'Hello, ' + name + '!' }),
+  })],
+);
+const result = await executeCapability(registry, {
+  identity: greet.identity,
+  runtime: 'local',
+  input: { name: 'World' },
+  caller: { kind: 'anonymous' },
+  authorization: { authorize: ({ access, risk }) => access.kind === 'public' && risk === 'read' },
+});
+if (result.kind !== 'success') throw new Error(result.reason);
+console.log(result.value);
+```
+
+Run `node quickstart.mjs`; it prints `{ message: 'Hello, World!' }`. Every invocation supplies an authorization port, including public reads.
+
+The root, contracts, composition, registry, executor, browser, HTTP, CLI and init subpaths need no runtime dependency from the package. Optional integrations are explicit:
+
+| Imported subpath | Install alongside Agent Native |
+| --- | --- |
+| harness | No runtime dependency; neutral contracts only |
+| harness/mcp-bridge | Node 22+ built-ins; no MCP SDK dependency |
+| harness/codex | Node 22+ and an installed Codex CLI with ChatGPT sign-in; no provider SDK dependency |
+| schema/zod | zod 4.6.x (4.6.5 or later patch; tested with 4.6.5 and 4.6.6) |
+| mcp or next | @modelcontextprotocol/server@2.3.0 |
+| mcp-apps | @modelcontextprotocol/server@2.3.0 and @modelcontextprotocol/ext-apps@2.0.3 |
+| astro | astro in the documented supported range |
+
+The package does not install optional peers automatically. Application-owned routes, client libraries, framework adapters and deployment hosts remain separate. For example, the Astro on-demand fixture also installs @astrojs/node; the Next fixture installs Next and React. The browser-only E06 fixture installs Zod for its own schema and has no MCP server dependency.
+
+Run npm run check:portability from this repository to build, pack, install in a fresh core/browser consumer, verify that optional adapters are absent, and smoke-test the application-owned CLI adapter. See the [UAN-022 measured evidence](evidence/UAN-022-package-portability.md) for the environment, sizes and Worker fixture result.
+
+## Check a fresh consumer
+
+Use Node.js 22 or newer. From the repository root, run `npm ci` followed by
+`npm run check:portability`. The check packs the current source, installs
+a core/browser consumer without optional peers, verifies imports and the packed
+CLI, and checks every declared export in the tarball. A missing
+`@modelcontextprotocol/server` error from `/mcp` means the application needs
+that peer; install it only for that server integration. The independent repository examples continue to use local tarballs.

package/docs/mcp-apps.md

@@ -0,0 +1,57 @@
+# MCP Apps adapter
+
+MCP Apps is an optional presentation layer for an existing MCP capability. Install the official SDK when using this adapter:
+
+~~~sh
+npm install @modelcontextprotocol/server@2.3.0 @modelcontextprotocol/ext-apps@2.0.3
+~~~
+
+Import the isolated subpath only in the server application:
+
+~~~ts
+import { createMcpAppsHandler } from '@uppercut-labs/agent-native/mcp-apps';
+
+const handler = createMcpAppsHandler(registry, {
+  ...mcpOptions,
+  resources: [{
+    capabilityId: 'example.catalog:album.lookup@1',
+    uri: 'ui://catalog/album-explorer.html',
+    name: 'Album explorer',
+    html: bundledHtml,
+  }],
+});
+~~~
+
+Each resource maps to one capability already present in the registry. The adapter checks canonical capability IDs, unique mappings, bounded resource size and an exact ui:// resource URI. UI metadata is attached only after the ordinary MCP discovery rules expose the bound capability. Resource reads are registered only for those visible app tools. Tool execution still uses the same shared executor, schemas, authorization and per-surface exposure policy. The resource does not create a second API.
+
+Resources use the official ext-apps server helpers and MIME type text/html;profile=mcp-app. CSP metadata closes connect, resource, frame and base-URI origins by default. Resource HTML is capped at 1 MiB; external resource-bearing elements and CSS origins are rejected. The view should use the official App host bridge for follow-up calls. It must not fetch the MCP endpoint directly or embed credentials. Hosts remain responsible for sandbox enforcement and identity.
+
+Provide both content text and structuredContent on tool results. Text-only MCP clients still receive the ordinary result. Views validate structured data against the existing capability output schema and can parse the text JSON fallback. The E09 view shows loading, found, missing, denied and unavailable states, including malformed host input.
+
+Run the standalone fixture with npm run example:e09. Its conformance fixture pairs the official ext-apps App and AppBridge classes through a deterministic in-memory channel; the outer tool calls use the official MCP client/server SDK over a real loopback HTTP socket. It verifies initial tool-result delivery, a host-mediated follow-up lookup, a missing album, authorization denial before binding effects, malformed UI input, text fallback, MIME type and undeclared resource/origin rejection.
+
+This fixture is SDK-level evidence, not browser iframe or commercial-host acceptance. No real MCP Apps host was exercised. Verify actual host rendering, sandbox/CSP enforcement, host confirmation behavior, and authentication in UAN-023. Core and browser-only imports do not import ext-apps; the adapter requires the optional peer only when its subpath is loaded.
+
+Official API references: [quickstart](https://github.com/modelcontextprotocol/ext-apps/blob/main/docs/quickstart.md) and [overview](https://github.com/modelcontextprotocol/ext-apps/blob/main/docs/overview.md).
+
+## Verify host-mediated follow-up
+
+With Node.js 22 or newer, run `npm ci` and `npm run example:e09` from the package root.
+The E09 controller calls the host bridge for a follow-up lookup:
+
+<!-- source:examples/e09-album-explorer/project/src/view-controller.mjs#host-mediated-lookup -->
+~~~js
+const result = await app.callServerTool({ name: toolName, arguments: { slug } });
+const outcome = decodeResult(result, outputSchema);
+show(outcome);
+return outcome;
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e09-album-explorer/project/src/view-controller.mjs#L52)
+<!-- /source -->
+
+The SDK fixture checks found, missing, denied, malformed, and text-only fallback states.
+If the host supplies malformed input or denies a call, the view shows an explicit
+unavailable or denied state; it never fetches MCP credentials itself. See the
+[E09 project instructions](https://github.com/uppercut-labs/agent-native/blob/main/examples/e09-album-explorer/project/README.md).
+A rendered browser host remains a separate compatibility check.

package/docs/mcp.md

@@ -0,0 +1,178 @@
+# Remote MCP over Streamable HTTP
+
+For an application-owned local harness endpoint, see the
+[loopback bridge](harness-mcp-bridge.md). Harness control does not grant capability
+permissions; discovery and execution still use the policies below.
+
+The MCP subpath needs the official server SDK as an explicit optional peer in the host project:
+
+~~~sh
+npm install @modelcontextprotocol/server@2.3.0
+~~~
+
+Import the adapter from its isolated package subpath:
+
+~~~ts
+import { createMcpHandler } from '@uppercut-labs/agent-native/mcp';
+
+const handler = createMcpHandler(registry, {
+  resolveExecutionContext(request) {
+    // Return a caller and AuthorizationPort from the application's trusted auth boundary.
+    return { caller, authorization };
+  },
+});
+~~~
+
+Mount the Web-standard Request-to-Response function at /mcp. The adapter delegates protocol
+handling, version negotiation, tool registration and Streamable HTTP transport to the official
+MCP server SDK. It does not implement MCP wire messages itself. The root contract and executor
+entrypoints remain free of MCP SDK imports.
+
+By default, the adapter registers only capabilities whose access is explicitly public and whose
+risk is read. The optional `canDiscover` callback can narrow that set; it cannot reveal protected
+capabilities. Protected discovery requires an explicit `discoverProtected` callback, official SDK
+bearer verification, trusted principal resolution, and grant authorization. Destructive capabilities
+also require an exact per-app MCP exposure entry:
+
+~~~ts
+surfaceExposure: { mcp: { destructive: ['account:delete@1'] } }
+~~~
+
+The server factory applies discovery on every protocol request, and the shared executor rechecks
+authorization for each `tools/call`. Granting a scope alone never exposes a destructive tool. A direct call to a hidden or filtered tool name receives the SDK's normal
+unknown-tool protocol error without running a binding. See
+[permissions and discovery](permissions-and-discovery.md) and the
+[E07 playlist fixture](https://github.com/uppercut-labs/agent-native/blob/main/examples/e07-playlist-permissions/README.md).
+
+The SDK receives JSON Schema generated by each capability's SchemaPort. The shared executor
+validates input and output again. Successful tool results place the canonical output under
+structuredContent.result so object and scalar capability results use one predictable shape.
+The text content carries the same JSON value. Error text is bounded and omits raw inputs, scopes,
+handler exceptions and output values.
+
+The default request body limit is 32 KiB and can be configured from 1 byte through 1 MiB with
+maxRequestBytes. Tool execution defaults to a 10-second deadline, configurable up to 300 seconds.
+A timed-out call receives an MCP tool error and its binding receives an aborted signal; bindings
+must observe that signal to stop their work. For a write or destructive capability, the error says
+that the write may have completed. The adapter does not retry; callers must check state before any
+retry unless the application defines an idempotency contract. Host code remains responsible for
+identity-provider configuration, transport security, grant persistence and rate limiting.
+
+### Reconcile an uncertain write
+
+The [E07 recovery recipe](https://github.com/uppercut-labs/agent-native/blob/main/examples/e07-playlist-permissions/project/src/recovery-demo.mjs)
+connects an application-owned idempotency key to a protected status capability. Run
+`npm run example:e07` from the repository root to build, install and execute it. To repeat
+only the demo, run `npm run recovery` in `examples/e07-playlist-permissions/.exported`.
+
+The original write reserves the caller's key in a file journal, deliberately ignores abort,
+and waits on a deferred commit. After the MCP deadline warning, status returns `pending`.
+The application then completes the original operation; the next status returns `committed`
+with one commit. Reopening the journal preserves the outcome. No automatic retry occurs.
+
+<!-- source:examples/e07-playlist-permissions/project/src/recovery-demo.mjs#reconcile-write -->
+~~~js
+const pending = await fixture.call('status', { key: 'operation-1' });
+assert.deepEqual(pending.structuredContent.result, { state: 'pending', commits: 0 });
+// The fixture now allows the original operation to finish; do not submit another write.
+fixture.release.resolve();
+await fixture.completed.promise;
+const committed = await fixture.call('status', { key: 'operation-1' });
+assert.deepEqual(committed.structuredContent.result, { state: 'committed', commits: 1 });
+assert.equal(fixture.counts().writes, 1);
+assert.equal(fixture.counts().invocations, 1);
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e07-playlist-permissions/project/src/recovery-demo.mjs#L19)
+<!-- /source -->
+
+Keep the same key and value while reconciling. A pending operation must remain pending until
+the application can establish its outcome. A missing record is not proof that a remote write
+never happened: investigate the application's persistence and recovery contract before
+resubmitting. The fixture separately verifies that an explicit duplicate with the same value
+does not start a second write, a different value conflicts, and an unauthorized status reader
+receives no protected state. Status requires its own current grant and ownership check.
+
+The file journal demonstrates single-process persistence, not production crash safety or
+cross-process locking. A production application must atomically reserve the caller-scoped key
+and persist the mutation and outcome, or reconcile with its downstream provider. Define key
+retention and recovery for abandoned pending operations. Agent Native supplies no durable
+operation ledger, rollback-on-timeout or exactly-once guarantee. The deterministic test advances
+the deadline with Node's mock timers and controls commit with a deferred promise; it uses no
+wall-clock sleeps to decide correctness.
+
+A real local HTTP socket fixture uses the official client and server packages, both pinned to
+version 2.3.0. The observed client session negotiated protocol version 2025-11-25. It discovers
+and invokes the sample album capability, checks the structured result against the canonical output
+schema, and exercises malformed transport input, oversized input, invalid tool arguments, hidden
+definitions and a request-specific discovery filter. This is fixture-tested protocol evidence; it
+does not establish support for every commercial MCP client or a deployed host.
+
+Destructive definitions require an exact app surface entry, in addition to a current grant:
+
+~~~ts
+surfaceExposure: { mcp: { destructive: ['account:delete@1'] } }
+~~~
+
+The adapter filters out definitions without one unique server binding and requires current token scopes plus a matching, unexpired, unrevoked grant before consulting `discoverProtected`; that callback only narrows discovery. The shared executor still checks every call. Exposure is also checked at the call boundary so a stale listing cannot retain destructive access.
+
+For the optional interactive MCP Apps presentation, use the isolated [/mcp-apps](mcp-apps.md) adapter and its E09 SDK conformance fixture. It keeps the regular text/structured tool result for hosts without MCP Apps rendering.
+
+## Protected-only servers
+
+When `bearerAuth` is configured and no capability is a public read with a server binding, a request without an `Authorization` header receives the SDK's 401 challenge with `WWW-Authenticate: Bearer`. Hosts then ask for credentials instead of connecting and seeing an empty tool list. Set `bearerAuth.required` to `true` to require a token even when public reads exist, or to `false` to keep anonymous handshakes.
+
+## Caller identity in bindings
+
+Every binding receives the caller the executor authorized as `context.caller`. For a verified MCP principal, `context.caller.identity` carries its `issuer`, `subject`, `tenantId` and `clientId`, so a binding can scope records to the caller without rebuilding the registry per request. Authorization still happens first: `authorizeResource` must enforce ownership before the binding runs.
+
+## Operator failure hook
+
+Tool errors returned to the client are deliberately generic. To see why a call failed, pass `onToolFailure`. It receives the capability ID, the tool name, a reason (an executor failure kind, or `context-unavailable`, `not-exposed`, `result-not-serializable` or `adapter-error`) and the executor's `DiagnosticObservation`. It never receives input, output, credentials or exception text. Errors thrown by the hook are ignored. To log a binding exception, catch it inside the binding.
+
+The [E11 executor and operator recipe](https://github.com/uppercut-labs/agent-native/blob/main/examples/e11-diagnostics-fault-lab/project/src/executor-selection.mjs)
+runs with `npm run example:e11`; repeat it with `npm run selection` in the exported project.
+It receives `handler-failed` and `invalid-output` privately while clients receive the same
+bounded error. Sentinel checks reject input, output, credential or exception disclosure in
+both client results and operator events. Hidden tools remain undiscoverable and uncallable.
+
+<!-- source:examples/e11-diagnostics-fault-lab/project/src/executor-selection.mjs#operator-hook -->
+~~~js
+const handler = createMcpHandler(registry, {
+  resolveExecutionContext: () => ({ caller: { kind: 'anonymous' }, authorization: publicRead }),
+  onToolFailure: (failure) => {
+    // Store only the bounded diagnostic in the application's private operator sink.
+    failures.push(failure);
+  },
+});
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e11-diagnostics-fault-lab/project/src/executor-selection.mjs#L110)
+<!-- /source -->
+
+## Tool names
+
+The default name, from `mcpToolName`, is collision-free but long, for example `cap_7_example_6_lookup_v1`. The `toolName` option can return shorter names. Each must be 1 to 128 characters of `A-Z a-z 0-9 _ - .` and unique within the registry; otherwise the handler is not created.
+
+## Cloudflare Workers: keep request resources open until the response ends
+
+A Streamable HTTP response is a stream. For a tool call, the SDK returns the `Response` first and runs the binding while the body is being written. Anything the binding uses that is scoped to the request, such as a database pool, must stay open until the body ends, not merely until the handler returns:
+
+~~~ts
+const response = await handler(request);
+if (!response.body) return response;
+const { readable, writable } = new TransformStream();
+ctx.waitUntil(response.body.pipeTo(writable).finally(() => pool.end()));
+return new Response(readable, response);
+~~~
+
+Closing the pool in a `finally` around `await handler(request)` makes every tool call fail as `handler-failed`, while discovery still works.
+
+## Reproduce a local protocol call
+
+Use Node.js 22 or newer, `npm ci`, then `npm run example:e04` from the repository
+root. The exported Worker starts locally under Wrangler and the official SDK client
+discovers and calls the public album tool through `/mcp`. A wrong configured
+`SIDECAR_HOST` yields a 421 response; set it to the local request host before
+retesting. The [E04 Worker instructions](https://github.com/uppercut-labs/agent-native/blob/main/examples/e04-worker-sidecar/project/README.md)
+give the exact local settings and cleanup. This is loopback protocol evidence.

package/docs/next.md

@@ -0,0 +1,73 @@
+# Next.js App Router
+
+The experimental Next.js integration targets Next 16.3.8 App Router routes on the Node runtime. It
+does not import Next itself: App Router supplies standard Web `Request` objects, and the adapter
+returns standard `Response` objects from the existing HTTP and official MCP handlers.
+
+For a public read, install the server peer and the server-boundary marker, and install the
+client in development for protocol verification:
+
+```sh
+npm install @modelcontextprotocol/server@2.3.0 server-only@0.0.1
+npm install --save-dev @modelcontextprotocol/client@2.3.0
+```
+
+The app-owned server registry module exports its public-read-only authorizer, such as the
+checked policy in [adopt an existing site](adopt-existing-site.md). Supply it in the route:
+
+```js
+// app/mcp/route.js
+import { createNextMcpRoute } from '@uppercut-labs/agent-native/next';
+import { registry, publicReadAuthorization } from '../../lib/server-registry.js';
+
+export const runtime = 'nodejs';
+export const { GET, POST, DELETE } = createNextMcpRoute(registry, {
+  resolveExecutionContext: () => ({
+    caller: { kind: 'anonymous' },
+    authorization: publicReadAuthorization,
+  }),
+});
+```
+
+This policy permits explicitly public reads. Protected tools require the request-specific
+verified identity and grants described in [permissions](permissions-and-discovery.md).
+
+Mount `createNextHttpRoute` from a catch-all route covering `/agent-native/v1`. Keep server registry
+modules marked `server-only`. The two route factories share the existing registry/executor behavior,
+including schema checks, authorization, discovery, request bounds, and deadlines.
+
+Browser support is isolated at `@uppercut-labs/agent-native/next/browser`. Call `sync()` from a
+client component when `usePathname()` changes because Next exposes no stable DOM navigation event.
+Registration remains feature-detected through the underlying WebMCP adapter. A normal page must
+remain useful when that API is absent.
+
+The init inspector recognizes Next from dependency and filesystem evidence without importing config
+or application modules. It proposes manual integration and never rewrites existing Next auth,
+layout, config, or routes. An existing `/mcp` route is a conflict for same-origin MCP mode and yields
+no proposed edits.
+
+See the [E03 fixture](https://github.com/uppercut-labs/agent-native/blob/main/examples/e03-next-reading-list/project/README.md) and
+[UAN-014 local verification evidence](evidence/UAN-014-next.md).
+
+## Verify the ownership boundary
+
+With Node.js 22 or newer, run `npm ci` and `npm run example:e03` from the package root.
+The fresh export installs Next, tests routes and the official MCP client, builds the production
+app, and scans browser assets for a fake server-only sentinel. A cross-user save is denied
+before mutation by this checked owner guard:
+
+<!-- source:examples/e03-next-reading-list/project/lib/saved-list.js#saved-list-owner-check -->
+~~~js
+function authorizeOwner(identity, ownerUserId) {
+  assertFixtureIdentity(identity);
+  if (identity.userId !== ownerUserId) {
+    throw new SavedListAuthorizationError();
+  }
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e03-next-reading-list/project/lib/saved-list.js#L41)
+<!-- /source -->
+
+If the browser scan finds the sentinel, keep `server-only` modules out of client imports and
+rerun the export. The [E03 project](https://github.com/uppercut-labs/agent-native/blob/main/examples/e03-next-reading-list/project/README.md)
+lists the expected final smoke lines and fixture limits.