From a6ef29c5ed56be466fe79c6248bde345cfb1bd98 Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Sat, 5 Sep 2026 06:19:48 +0000
Subject: [PATCH 1/5] feat: add typed MCP App client

---
 .changeset/typed-app-client.md                |   5 +
 docs/diagnostics.md                           |   8 +-
 docs/entry-conventions.md                     | 110 ++-
 examples/mcp-app/package.json                 |   1 -
 .../browser-app/status-panel.browser.test.ts  |  46 +-
 examples/mcp-app/views/status-panel.ts        |  76 ++-
 packages/agent-bundle/README.md               |  13 +
 packages/agent-bundle/package.json            |   4 +
 packages/agent-bundle/rslib.config.ts         |  17 +
 packages/agent-bundle/src/app/index.ts        | 645 ++++++++++++++++++
 .../agent-bundle/src/build/app-runtime.ts     |  18 +
 packages/agent-bundle/src/build/entries.ts    |  26 +-
 .../agent-bundle/src/build/entry-shell.ts     |   8 +-
 packages/agent-bundle/src/build/mcp-apps.ts   |  36 +-
 .../agent-bundle/src/build/runtime-path.ts    |  21 +
 packages/agent-bundle/src/config/normalize.ts |   3 +-
 packages/agent-bundle/src/config/validate.ts  |   3 +-
 .../agent-bundle/src/routes/cli-commands.ts   |   3 +-
 packages/agent-bundle/src/routes/layouts.ts   |  10 +-
 .../agent-bundle/src/routes/protocol-name.ts  |  63 ++
 packages/agent-bundle/src/routes/typegen.ts   |  59 ++
 packages/agent-bundle/src/test/contract.ts    |   3 +-
 packages/agent-bundle/src/test/mcp.ts         |   3 +-
 packages/agent-bundle/src/test/render.ts      |   9 +-
 .../agent-bundle/tests/app-client.test.ts     | 403 +++++++++++
 .../tests/check-declaration-imports.test.ts   |  24 +
 .../tests/mcp-apps-compile.test.ts            |  77 ++-
 .../agent-bundle/tests/public-api.test.ts     |   5 +-
 .../tests/route-framework-imports.test.ts     |   3 +-
 .../agent-bundle/tests/route-graph.test.ts    | 203 +++++-
 .../tests/route-protocol-name.test.ts         | 119 ++++
 .../tests/route-register-typegen.test.ts      |  34 +-
 .../tests/route-typegen-write.test.ts         |  41 ++
 pnpm-lock.yaml                                |   3 -
 website/docs/en/examples/mcp-app.mdx          |  13 +-
 website/docs/en/guide/authoring/mcp.mdx       | 136 +++-
 .../docs/en/guide/distribution/validation.mdx |   5 +-
 website/docs/en/reference/api.mdx             |   3 +
 website/docs/en/reference/security.mdx        |  17 +
 website/docs/zh/examples/mcp-app.mdx          |   8 +-
 website/docs/zh/guide/authoring/mcp.mdx       |  50 +-
 .../docs/zh/guide/distribution/validation.mdx |   6 +-
 website/docs/zh/reference/api.mdx             |   3 +
 website/docs/zh/reference/security.mdx        |   9 +
 website/rspress.config.ts                     |   1 +
 45 files changed, 2219 insertions(+), 134 deletions(-)
 create mode 100644 .changeset/typed-app-client.md
 create mode 100644 packages/agent-bundle/src/app/index.ts
 create mode 100644 packages/agent-bundle/src/build/app-runtime.ts
 create mode 100644 packages/agent-bundle/src/build/runtime-path.ts
 create mode 100644 packages/agent-bundle/src/routes/protocol-name.ts
 create mode 100644 packages/agent-bundle/tests/app-client.test.ts
 create mode 100644 packages/agent-bundle/tests/route-protocol-name.test.ts

diff --git a/.changeset/typed-app-client.md b/.changeset/typed-app-client.md
new file mode 100644
index 000000000..edcc8483a
--- /dev/null
+++ b/.changeset/typed-app-client.md
@@ -0,0 +1,5 @@
+---
+"agent-bundle": patch
+---
+
+Call typed MCP App routes through `agent-bundle/app` without triggering `AB4837` (#594)
diff --git a/docs/diagnostics.md b/docs/diagnostics.md
index 0908edd23..2e72db03d 100644
--- a/docs/diagnostics.md
+++ b/docs/diagnostics.md
@@ -309,8 +309,10 @@ entry citing the warning text it drops and why it is noise; it may be empty.
 
 Every App is measured after it is emitted: the UTF-8 bytes of the
 self-contained HTML and their gzip size, what a compressing transport would
-carry. `AB4772` is the size advisory, one **warning** per App. Any view that
-imports `@modelcontextprotocol/ext-apps` starts at about 437 kB (104 kB gzip)
+carry. `AB4772` is the size advisory, one **warning** per App. A view that
+reaches its host through `agent-bundle/app` carries the framework's client
+and nothing else from the protocol stack; one that imports
+`@modelcontextprotocol/ext-apps` instead starts at about 437 kB (104 kB gzip)
 — `zod` v3 and v4, `@modelcontextprotocol/sdk`, `zod-to-json-schema`, and
 `ext-apps` itself — so the advisory bound of 1 MiB (1,048,576 bytes) sits at
 roughly 2.4× that floor and at half the 2 MiB (2,097,152 bytes) bound above
@@ -905,7 +907,7 @@ schema constants), unions, nested objects, transforms, coercions — raises
 | `AB4834` | warning | `agent-bundle validate` published `.agent-bundle/routes.d.ts` (the project compiles routes or providers) but the root `tsconfig.json` program — resolved like `tsc -p`, including `extends` and one level of project `references` — does not compile it, so `renderRoute` / `renderRouteEvents` type-check route ids as `string` and `input` / `result` as `unknown`. Reported on `tsconfig.json`; never for a project without one. | Add `".agent-bundle/routes.d.ts"` to `tsconfig.json` `include` (not `files`: an `include` entry is inert until the first build publishes the file, while a missing `files` entry is a `tsc` error); `build`, `dev`, and `validate` keep the file current and it stays gitignored. |
 | `AB4835` | error | A route's static `config.render` (the render budget of one call, #454) is malformed: `render` is not an object, carries a key other than `maxElapsedMs`, `maxElapsedMs` is not a positive integer of milliseconds, or it exceeds the framework ceiling of `86400000` (24 hours) — or a plain `.ts` CLI command declares one, although it executes without a render session. Reported once per route: on an MCP tool, resource, or prompt route with its server (the tool's projected CLI command inherits the value), or on a `src/cli/**` command route; a route with a rejected budget compiles no command. Omit `render` to keep the runtime default (`60000`). Declare `config.render = { maxElapsedMs: <positive integer ≤ 86400000> }` on a rendered route, or remove it. The budget bounds the framework's render session only: Codex's `tool_timeout_sec` (60 s by default) and any per-server host timeout must be raised by the operator separately, while Claude Code's default per-call wall clock is about 28 hours and its idle timer is kept alive by the `notifications/progress` the projector forwards. |
 | `AB4836` | error | A route's static `config.execution` (MCP task support, #369) is malformed: `execution` is not an object, carries a key other than `taskSupport`, or `taskSupport` is not one of `forbidden`, `optional`, `required` — or a resource or prompt route declares it, although the `2025-11-25` Tasks utility augments `tools/call` only. Reported once per route with its server. Omit `execution` to keep the wire default (`forbidden`: every call is an ordinary request), or declare `config.execution = { taskSupport: 'optional' }` so a task-aware client may receive a `CreateTaskResult` and poll `tasks/get` / `tasks/result` while the render continues, or `'required'` to refuse ordinary calls with JSON-RPC `-32601`. The generated server advertises the value in `tools/list` and declares the `tasks` capability only when at least one tool opted in. |
-| `AB4837` | error | A route module of any kind except an App — a `src/cli/**` command, a `src/scripts/**` script, a tool, resource, or prompt route of a generated server, an event route — a layout, or a provider, or a module one of them reaches through relative value imports, imports `agent-bundle`, `agent-bundle/api`, `agent-bundle/config`, `agent-bundle/eval`, `agent-bundle/rstest`, `agent-bundle/test`, or `agent-bundle/test/browser` as a value (a static import whose binding is read at run time, `import 'agent-bundle/api'`, `import('agent-bundle/api')` with a literal specifier, or a non-type re-export). Those entries carry the compiler, and the generated executable is self-contained (#387): the bundler would inline the compiler and fail on the framework's runtime-relative module references (`Module not found: Can't resolve '../events'`), or the artifact validator would reject the inlined compiler's non-literal dynamic imports with `AB6005` — either way naming a generated file instead of the route (#558). Judged statically when the route graph compiles, so `inspect`, `validate`, `build`, and `dev` all report it, once per module, naming the route and the helper the import lives in. `import type`, `type`-qualified specifiers, and imports used only in type positions are elided by the bundler and never reported; routes of a server that is not generated (`custom`/`command`/`remote`, or an `AB4800` conflict) or of a CLI that is not generated (`conventional`, or an `AB4801` conflict) are never bundled, so they are not judged; likewise a layout that no bundled rendered route composes through (a worker imports only the layouts its routes reach: the tool, resource, and prompt routes of a generated server, the rendered `.tsx` commands of a generated CLI, and rendered `.tsx` scripts), and a provider in a project whose only executables are plain `.ts` scripts, which are bundled from their own source and mount none. Spawn the framework instead of importing it: serve an MCP App from a routed command with `spawnServeApp` from `agent-bundle/serve-app-command`, which runs `agent-bundle serve-app` as a child process; keep other framework calls in host processes (`package.json` scripts, a hand-written `.mjs` run from the checkout). The bundle-safe entries stay allowed: `agent-bundle/routes`, `agent-bundle/launch-env`, `agent-bundle/meta`, `agent-bundle/mcp-apps`, `agent-bundle/mcp-entry`, `agent-bundle/cli-entry`, `agent-bundle/terminal-capability`, and `agent-bundle/serve-app-command`. |
+| `AB4837` | error | A route module of any kind except an App — a `src/cli/**` command, a `src/scripts/**` script, a tool, resource, or prompt route of a generated server, an event route — a layout, or a provider, or a module one of them reaches through relative value imports, imports `agent-bundle`, `agent-bundle/api`, `agent-bundle/config`, `agent-bundle/eval`, `agent-bundle/rstest`, `agent-bundle/test`, or `agent-bundle/test/browser` as a value (a static import whose binding is read at run time, `import 'agent-bundle/api'`, `import('agent-bundle/api')` with a literal specifier, or a non-type re-export). Those entries carry the compiler, and the generated executable is self-contained (#387): the bundler would inline the compiler and fail on the framework's runtime-relative module references (`Module not found: Can't resolve '../events'`), or the artifact validator would reject the inlined compiler's non-literal dynamic imports with `AB6005` — either way naming a generated file instead of the route (#558). Judged statically when the route graph compiles, so `inspect`, `validate`, `build`, and `dev` all report it, once per module, naming the route and the helper the import lives in. `import type`, `type`-qualified specifiers, and imports used only in type positions are elided by the bundler and never reported; routes of a server that is not generated (`custom`/`command`/`remote`, or an `AB4800` conflict) or of a CLI that is not generated (`conventional`, or an `AB4801` conflict) are never bundled, so they are not judged; likewise a layout that no bundled rendered route composes through (a worker imports only the layouts its routes reach: the tool, resource, and prompt routes of a generated server, the rendered `.tsx` commands of a generated CLI, and rendered `.tsx` scripts), and a provider in a project whose only executables are plain `.ts` scripts, which are bundled from their own source and mount none. Spawn the framework instead of importing it: serve an MCP App from a routed command with `spawnServeApp` from `agent-bundle/serve-app-command`, which runs `agent-bundle serve-app` as a child process; keep other framework calls in host processes (`package.json` scripts, a hand-written `.mjs` run from the checkout). The bundle-safe entries stay allowed: `agent-bundle/app` (the browser MCP App client, a leaf with no Zod, Node, or compiler import), `agent-bundle/routes`, `agent-bundle/launch-env`, `agent-bundle/meta`, `agent-bundle/mcp-apps`, `agent-bundle/mcp-entry`, `agent-bundle/cli-entry`, `agent-bundle/terminal-capability`, and `agent-bundle/serve-app-command`. |
 | `AB4940` | error | A conventional provider module has no default export or its default export is not a function. Default-export a factory receiving `{ invocation, plugin, signal }`. |
 | `AB4941` | error | Two provider filenames derive the same camel-cased provider key. Rename one file so every provider key is unique. |
 | `AB4942` | error | A provider filename derives the reserved `processLifetime` key. Rename the file so its camel-cased key does not collide with the framework-owned provider. |
diff --git a/docs/entry-conventions.md b/docs/entry-conventions.md
index a90318a88..d5f0b2cec 100644
--- a/docs/entry-conventions.md
+++ b/docs/entry-conventions.md
@@ -76,7 +76,7 @@ entries carry `provenance.kind: 'conventional'` in the normalized model.
 | `src/index.ts` | Library output with declarations. | `lib: false` |
 | `src/mcp/<server-id>.ts` | Stdio entry for the declared MCP server `<server-id>` that names no `entry`, `command`, or `url`. | Declare `entry` explicitly |
 | `src/mcp/<server>/{tools,resources,prompts}/*.{ts,tsx}` | Generated MCP server routes; path supplies identity and each executable module supplies static `config`, schemas, and one async default Server Component. | Set `routes.servers.<server>` to `custom`, `command`, or `remote` |
-| `src/mcp/<server>/apps/*.{ts,tsx}` | Browser MCP App entry compiled to self-contained HTML and registered on the generated server; static `config.resourceUri` is required (`AB4812`), and two App routes of one server sharing a URI are `AB4829` (the same URI on different servers is not a collision). An optional `config.template` HTML shell resolves relative to the route module like its imports (`'./dashboard.html'`); the legacy project-root-relative form is accepted only while unambiguous (`AB4827` otherwise). Tools, resources, and prompts reference the App from their own static `config` with `appResourceUri('<app>')` from `agent-bundle/routes` or a shared `const` string literal instead of repeating the `ui://` literal. | Use a custom server or prefix the file with `_` |
+| `src/mcp/<server>/apps/*.{ts,tsx}` | Browser MCP App entry compiled to self-contained HTML and registered on the generated server; static `config.resourceUri` is required (`AB4812`), and two App routes of one server sharing a URI are `AB4829` (the same URI on different servers is not a collision). An optional `config.template` HTML shell resolves relative to the route module like its imports (`'./dashboard.html'`); the legacy project-root-relative form is accepted only while unambiguous (`AB4827` otherwise). Tools, resources, and prompts reference the App from their own static `config` with `appResourceUri('<app>')` from `agent-bundle/routes` or a shared `const` string literal instead of repeating the `ui://` literal. The view talks to its host through `createAppClient()` from the browser-safe `agent-bundle/app` (see [`agent-bundle/app`](#agent-bundleapp--the-app-side-bridge-client)), typed by the generated `AppRegister` augmentation. | Use a custom server or prefix the file with `_` |
 | `src/scripts/<name>.ts` | Plain script compiled to `scripts/<name>.mjs` in every selected target artifact — the same pipeline explicit `scripts` entries use, with ordinary Node stdout/stderr semantics. A `scripts` entry that references the file claims it. Nested modules are hard errors (`AB4808`). A `bin` entry that references the file does **not** claim it: the module ships as both the npm bin and the artifact script (see [Which config keys claim a conventional module](#which-config-keys-claim-a-conventional-module)); export `main` or make the module self-executing, because a `default`-only module would run as the bin but ship as an inert script (`AB4738`). | Prefix a path segment with `_`, or claim the file with an explicit `scripts` entry |
 | `src/scripts/<name>.tsx` | Rendered script: the async default component receives `{ argv, signal }` and renders through the Agent renderer with the CLI output contract (`--json`, `--ndjson`, TTY progress, piped Markdown). Compiles to `scripts/<name>.mjs` plus a `scripts/<name>-flight.mjs` react-server worker. The extension is the explicit, visible contract — plain `.ts` scripts are never wrapped in React behavior, and explicit `scripts` config entries stay plain regardless of extension. A `bin` entry that references a rendered script is `AB4737` unless the module exports both the default component (for the script) and a named `main` (for the bin envelope); with both, the module serves both surfaces. | Rename to `.ts`, prefix a path segment with `_`, or claim the file with an explicit `scripts` entry |
 | `src/cli/**/*.{ts,tsx}` | Routed CLI commands compiled into one collision-checked command graph and one generated package executable named after `plugin.name` (superseding the `src/cli.ts` bin convention for the project), plus the same executable as `bin/<plugin-name>.mjs` in every selected host artifact whose target publishes the `cli` capability (all built-in targets). Nesting is identity: `src/cli/library/audit.ts` runs as `<bin> library audit`. Plain `.ts` commands execute directly and print one canonical JSON line; `.tsx` commands render through the dispatcher with the four output modes. | `bin: false`, `routes.cli: 'conventional'`, or prefix a path segment with `_` |
@@ -1489,9 +1489,10 @@ resolve '../events'`). The route graph reports such an import first, as
 (`src/routes/framework-imports.ts`; the compiler-carrying entries are
 `agent-bundle`, `agent-bundle/api`, `agent-bundle/config`,
 `agent-bundle/eval`, `agent-bundle/rstest`, `agent-bundle/test`, and
-`agent-bundle/test/browser`, matched exactly; `import type` and type-only
-usage are not reported), while an external bare import (`AB6005 uses
-unsupported specifier`) or a non-literal `import(spec)` (`AB6005 has a
+`agent-bundle/test/browser`, matched exactly, so the bundle-safe entries —
+`agent-bundle/app` among them — are never reported; `import type` and
+type-only usage are not reported either), while an external bare import
+(`AB6005 uses unsupported specifier`) or a non-literal `import(spec)` (`AB6005 has a
 non-literal dynamic import`) still fails artifact validation. The sanctioned
 shape is `spawnServeApp` from `agent-bundle/serve-app-command`
 (`src/serve-app-command.ts`, #558) — plain Node with no dependencies, so the
@@ -1515,3 +1516,104 @@ sent; it is still running). It is a
 checkout command: an installed host pack has neither `node_modules/agent-bundle`
 nor the artifact, and the first two codes say so before anything is spawned.
 The worked example is in the MCP Apps guide, "Serving an App standalone".
+
+## `agent-bundle/app` — the App-side bridge client
+
+`agent-bundle/app` (`src/app/index.ts`, #594) is the half of the MCP Apps
+bridge that runs inside the App document. It is a browser-safe leaf of the
+package: its only imports are browser-safe strict-JSON and route-name helpers, so `dist/app.js` names no
+Zod, Node built-in, Effect, route module, or compiler code, and the App
+compile inlines it into the self-contained HTML from the installed package
+inside the document (`tests/mcp-apps-compile.test.ts` walks the runtime import
+graph and the emitted document for exactly that). It is a public package
+export and a compiler-reserved App import, so a consumer `paths` mapping cannot
+replace the framework runtime. It is not one of the compiler-carrying entries
+`AB4837` rejects.
+
+The other half stays where it is: the host page, sandbox proxy, frame relay
+(`McpAppFrameRelay` in the Workbench, the inline relay in `serve-app`),
+`/api/mcp/...` routes, consent authority, and `createMcpAppBridge`
+(`src/dev/mcp-apps/mcp-app-bridge.ts`) are host-side and owned by the
+Workbench, `serve-app`, and #564's production host. The `browser-app` proof
+level (`mountBrowserApp` in `agent-bundle/test/browser`, which hosts the
+compiled document over `createMcpAppBridge`) exercises the client against that
+host bridge — `examples/mcp-app/tests/browser-app` asserts the App-to-host
+traffic is exactly the client's `ui/initialize` and
+`ui/notifications/initialized` until the view acts — so there is one wire
+contract, not a second host bridge. The client never decides which server a
+call reaches or which capability needs consent.
+
+### Public surface
+
+`createAppClient(options?)` returns a frozen `AppClient`:
+
+| Member | Contract |
+| --- | --- |
+| `connect(options?)` | Performs the `ui/initialize` handshake once and resolves the validated `AppInitializeResult` (`protocolVersion` `2026-01-26` — `APP_PROTOCOL_VERSION` — plus `hostInfo`, `hostCapabilities`, `hostContext`), then sends `ui/notifications/initialized`. Idempotent: a connected client resolves the cached result, a connecting one returns the in-flight promise. |
+| `call(routeId, input, options?)` | `tools/call` for the tool a `tool:<server>/<name>` route id names — the wire name is the final segment, derived the way the generated server derives it (`src/routes/protocol-name.ts`); any other shape is a `TypeError`. `input` must be a finite strict-JSON object (`invalid-message` otherwise). Resolves the result's `structuredContent` **directly**; rejects a result with `isError: true` (`rpc`, whole result on `error.data`), one without an object `structuredContent`, or a malformed envelope (`invalid-message`). Only object-rooted `resultSchema`s produce `structuredContent` in the MCP projection, so scalar and array results are not typed App calls. |
+| `request(method, params?, options?)` | The typed JSON-RPC escape hatch for `resources/read` and supported `ui/*` methods; resolves the raw result. |
+| `onToolInput(routeId, listener)` / `onToolResult(routeId, listener)` | The opening call's `ui/notifications/tool-input` arguments and the decoded `structuredContent` of `ui/notifications/tool-result`. The notifications carry no tool name — they are always the call that opened the App — so the route id types the payload and does not filter; a result without an object `structuredContent` is dropped. Each returns its unsubscribe function. |
+| `onToolCancelled(listener)` | `ui/notifications/tool-cancelled` as `{ reason? }`; returns its unsubscribe function. |
+| `rebind({ parent?, targetOrigin?, window? })` | Rejects the previous generation's pending requests with `connection-rebound`, clears the pinned origin, moves the message listener when `window` changes, adopts the new parent and trusted origin, and runs `connect()` again. |
+| `dispose()` | Idempotent. Removes the message listener, rejects pending requests with `disposed`, drops every registration and the pin. A host `ui/resource-teardown` request is answered with `{}` and disposes the client; any other host request is answered `-32601`. |
+| `connected` / `disposed` | Read-only state. |
+
+`CreateAppClientOptions` are `appInfo` (`{ name, version }`, default
+`agent-bundle-app` / `1.0.0`), `appCapabilities` (a finite JSON object,
+default `{}`), `timeoutMs` (integer milliseconds, 1 to 2³¹ − 1, default
+15 000), and the connect options `parent`, `targetOrigin`, `window`. Every
+request takes `{ signal, timeoutMs }`; a request that times out or is aborted
+rejects with `timeout` / `aborted` and, once connected, sends
+`notifications/cancelled` to the host. `AppClientError` is the one error
+class: `code` is `timeout`, `aborted`, `disposed`, `connection-rebound`,
+`invalid-message`, `rpc`, `capability-unavailable`, or `consent-required`; a
+host JSON-RPC error maps `-32601` to `capability-unavailable`, `-32001` to
+`consent-required`, and anything else to `rpc`, keeping `rpcCode` and `data`.
+No AB diagnostic is involved: App-side failures are browser errors.
+
+### Opaque sandbox handshake
+
+The Workbench and `serve-app` render the App as `<iframe sandbox="allow-scripts"
+referrerpolicy="no-referrer" srcdoc=…>`, so the document has an opaque
+origin and no referrer to learn its host origin from. The client therefore
+sends exactly one frame to `'*'` — its own `ui/initialize` — and accepts a
+response only when `event.source` is the configured parent, the id is that
+bootstrap request's, and the result validates; it then pins `event.origin`
+(an empty or `'null'` origin is refused as `invalid-message`), posts
+`ui/notifications/initialized` and every later request to that exact origin,
+and ignores every message from another source or origin. A malformed message
+that still names a pending id rejects that request as `invalid-message`. A
+host that can name its origin passes `targetOrigin` — an exact `http:` or
+`https:` origin; `'*'`, `'null'`, and non-origin strings are a `TypeError` —
+and no wildcard frame is sent. Author code has no wildcard send path. The
+transport is DOM-shaped (`AppWindow`, `AppMessageTarget`) rather than bound to
+the global `window`, so `tests/app-client.test.ts` and non-DOM hosts drive the
+same core through injected ports.
+
+### Generated typing
+
+`generateRouteTypes` (`src/routes/typegen.ts`) emits, for a graph with at
+least one tool route, `AppToolRouteId` (the `tool:<server>/<name>` subset of
+`RouteId`), `AgentBundleAppRouteContracts` (one `{ input: RouteInput<Id>;
+result: RouteResult<Id> }` per tool from the module's own `inputSchema` and
+`resultSchema` output), and exactly one augmentation:
+
+```ts
+declare module 'agent-bundle/app' {
+  interface AppRegister {
+    readonly routes: AgentBundleAppRouteContracts;
+  }
+}
+```
+
+The route module imports behind it are type-only and erased from the App
+HTML. With `.agent-bundle/routes.d.ts` in the program, `call()` narrows its
+route id to the project's tools, `input` to that tool's input, and its
+resolved value to the tool's structured result; `AppRouteId`,
+`AppRouteInput<Id>`, and `AppRouteResult<Id>` expose the same narrowing.
+Without the augmentation (no tool routes, a handwritten server, a program that
+omits the file) the id is any `tool:<server>/<name>` string and input and
+result are `unknown`; a view may then augment `AppRegister` itself with a
+structural map, as `examples/mcp-app/views/status-panel.ts` does. There is no
+generated `agent-bundle/routes/client` value module: the wire name is
+derivable from the id, so a runtime table would duplicate it.
diff --git a/examples/mcp-app/package.json b/examples/mcp-app/package.json
index bee9f0615..c8815ee1f 100644
--- a/examples/mcp-app/package.json
+++ b/examples/mcp-app/package.json
@@ -12,7 +12,6 @@
     "validate": "agent-bundle validate"
   },
   "devDependencies": {
-    "@modelcontextprotocol/ext-apps": "1.7.5",
     "@modelcontextprotocol/server": "2.0.0",
     "@rstest/browser": "0.11.12",
     "@rstest/core": "0.11.12",
diff --git a/examples/mcp-app/tests/browser-app/status-panel.browser.test.ts b/examples/mcp-app/tests/browser-app/status-panel.browser.test.ts
index ccea8f80e..0d976f6f4 100644
--- a/examples/mcp-app/tests/browser-app/status-panel.browser.test.ts
+++ b/examples/mcp-app/tests/browser-app/status-panel.browser.test.ts
@@ -68,6 +68,18 @@ const mountStatus = async (overrides: Partial<Parameters<typeof mountBrowserApp>
   return app;
 };
 
+const appToHostMethods = (app: MountedBrowserApp): readonly string[] =>
+  app.traffic
+    .filter((entry) => entry.direction === 'app-to-host')
+    .map((entry) => entry.message.method)
+    .filter((method): method is string => typeof method === 'string');
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const messageParam = (message: { readonly params?: unknown }, key: string): unknown =>
+  isRecord(message.params) ? message.params[key] : undefined;
+
 it('mounts the compiled panel, initializes the bridge, and renders the published result accessibly', async () => {
   const app = await mountStatus();
   await waitFor(() => app.document.querySelector('#status')?.textContent === 'degraded');
@@ -75,12 +87,33 @@ it('mounts the compiled panel, initializes the bridge, and renders the published
   expect(app.bridge.lifecycle).toBe('initialized');
   expect(app.document.querySelector('main')).not.toBeNull();
   expect(app.document.querySelector('h1')?.textContent).toBe('payments-api');
+  expect(app.document.querySelector('#summary')?.textContent).toBe(
+    'Payment latency is above the release threshold.',
+  );
   expect(app.document.querySelector('[aria-label="Service checks"]')).not.toBeNull();
-  expect(app.document.querySelectorAll('#checks li')).toHaveLength(2);
+  expect([...app.document.querySelectorAll('#checks li')].map((item) => item.textContent)).toEqual([
+    'Availabilitypassing',
+    'P95 latencyfailing',
+  ]);
   expect(app.provenance).toMatchObject({ proofLevel: 'browser-app', target: 'portable' });
+  expect(app.traffic.some(({ message }) => message.method === 'ui/notifications/tool-input')).toBe(true);
   expect(app.traffic.some(({ message }) => message.method === 'ui/notifications/tool-result')).toBe(true);
 });
 
+it('uses the public App client without author wildcard or ext-apps plumbing', async () => {
+  const app = await mountStatus();
+  await waitFor(() => app.document.querySelector('#status')?.textContent === 'degraded');
+
+  const html = app.iframe.srcdoc ?? '';
+  expect(html).not.toContain('@modelcontextprotocol/ext-apps');
+  expect(html).not.toContain('PostMessageTransport');
+  expect(html).not.toContain('window.parent.postMessage');
+  expect(appToHostMethods(app)).toEqual([
+    'ui/initialize',
+    'ui/notifications/initialized',
+  ]);
+});
+
 it('round-trips a resource read from the real App through binding operations', async () => {
   const reads: string[] = [];
   const app = await mountStatus({ operations: operations({ reads }) });
@@ -89,7 +122,11 @@ it('round-trips a resource read from the real App through binding operations', a
   await waitFor(() => app.document.querySelector('#bridge-outcome')?.textContent?.includes('passing checks') === true);
 
   expect(reads).toEqual(['ui://mcp-app-example/readiness-policy']);
-  expect(app.traffic.some(({ message }) => message.method === 'resources/read')).toBe(true);
+  expect(appToHostMethods(app)).toContain('resources/read');
+  expect(app.traffic.some(({ message }) => (
+    message.method === 'resources/read'
+    && messageParam(message, 'uri') === 'ui://mcp-app-example/readiness-policy'
+  ))).toBe(true);
 });
 
 it('holds a tool call for consent, resumes approval once, and denies without calling the binding', async () => {
@@ -104,6 +141,11 @@ it('holds a tool call for consent, resumes approval once, and denies without cal
   await expect(approved.decideConsent(challenge.id, true)).resolves.toBe(true);
   await waitFor(() => approved.document.querySelector('#bridge-outcome')?.textContent === 'Status refreshed.');
   expect(approvedCalls).toEqual(['refresh-status']);
+  expect(appToHostMethods(approved)).toContain('tools/call');
+  expect(approved.traffic.some(({ message }) => (
+    message.method === 'tools/call'
+    && messageParam(message, 'name') === 'refresh-status'
+  ))).toBe(true);
 
   const deniedCalls: string[] = [];
   const denied = await mountStatus({ operations: operations({ calls: deniedCalls }) });
diff --git a/examples/mcp-app/views/status-panel.ts b/examples/mcp-app/views/status-panel.ts
index c1fb9d678..62c8a9829 100644
--- a/examples/mcp-app/views/status-panel.ts
+++ b/examples/mcp-app/views/status-panel.ts
@@ -1,7 +1,6 @@
-import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
+import { createAppClient } from 'agent-bundle/app';
 import { name, version } from 'agent-bundle/meta';
 
-const app = new App({ name, version }, {});
 const serviceHeading = document.querySelector<HTMLHeadingElement>('#service')!;
 const statusIndicator = document.querySelector<HTMLElement>('#status-indicator')!;
 const status = document.querySelector<HTMLElement>('#status')!;
@@ -23,6 +22,44 @@ interface ServiceStatus {
   readonly summary?: string;
 }
 
+interface StatusToolInput {
+  readonly service: string;
+}
+
+/**
+ * Config-declared Apps have no generated `AgentBundleRoutes`. This structural
+ * map types `createAppClient` through the public `AppRegister` seam.
+ */
+type StatusPanelRouteContracts = {
+  readonly 'tool:status/show-status': {
+    readonly input: StatusToolInput;
+    readonly result: ServiceStatus;
+  };
+  readonly 'tool:status/refresh-status': {
+    readonly input: StatusToolInput;
+    readonly result: ServiceStatus;
+  };
+};
+
+declare module 'agent-bundle/app' {
+  interface AppRegister {
+    readonly routes: StatusPanelRouteContracts;
+  }
+}
+
+const showStatusRoute = 'tool:status/show-status';
+const refreshStatusRoute = 'tool:status/refresh-status';
+const readinessPolicyUri = 'ui://mcp-app-example/readiness-policy';
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const resourceText = (value: unknown): string | undefined => {
+  if (!isRecord(value) || !Array.isArray(value.contents)) return undefined;
+  const content = value.contents[0];
+  return isRecord(content) && typeof content.text === 'string' ? content.text : undefined;
+};
+
 const statusState = (value: string | undefined): StatusState => {
   if (value === 'checking' || value === 'healthy' || value === 'degraded') return value;
   return 'unknown';
@@ -53,20 +90,23 @@ const renderChecks = (items: readonly ServiceCheck[]) => {
   }));
 };
 
-app.addEventListener('toolinput', ({ arguments: toolArguments }) => {
-  const service = typeof toolArguments?.service === 'string' ? toolArguments.service : 'service';
+const client = createAppClient({
+  appInfo: { name, version },
+});
+
+client.onToolInput(showStatusRoute, (input) => {
+  const service = typeof input.service === 'string' ? input.service : 'service';
   serviceHeading.textContent = service;
   setStatus('checking');
   summary.textContent = `Checking readiness for ${service}.`;
   renderChecks([]);
 });
 
-app.addEventListener('toolresult', (result) => {
-  const content = result.structuredContent as ServiceStatus | undefined;
-  serviceHeading.textContent = content?.service ?? 'No service selected';
-  setStatus(content?.status);
-  summary.textContent = content?.summary ?? 'No readiness summary was returned.';
-  renderChecks(content?.checks ?? []);
+client.onToolResult(showStatusRoute, (result) => {
+  serviceHeading.textContent = result.service ?? 'No service selected';
+  setStatus(result.status);
+  summary.textContent = result.summary ?? 'No readiness summary was returned.';
+  renderChecks(result.checks ?? []);
 });
 
 document.querySelector('#toggle-details')!.addEventListener('click', () => {
@@ -75,11 +115,8 @@ document.querySelector('#toggle-details')!.addEventListener('click', () => {
 
 document.querySelector('#read-policy')!.addEventListener('click', async () => {
   try {
-    const result = await app.readServerResource({ uri: 'ui://mcp-app-example/readiness-policy' });
-    const content = result.contents[0];
-    bridgeOutcome.textContent = content !== undefined && 'text' in content
-      ? content.text
-      : 'Readiness policy unavailable.';
+    const text = resourceText(await client.request('resources/read', { uri: readinessPolicyUri }));
+    bridgeOutcome.textContent = text ?? 'Readiness policy unavailable.';
   } catch {
     bridgeOutcome.textContent = 'Readiness policy unavailable.';
   }
@@ -87,14 +124,13 @@ document.querySelector('#read-policy')!.addEventListener('click', async () => {
 
 document.querySelector('#refresh-status')!.addEventListener('click', async () => {
   try {
-    const result = await app.callServerTool({
-      arguments: { service: serviceHeading.textContent ?? 'service' },
-      name: 'refresh-status',
+    await client.call(refreshStatusRoute, {
+      service: serviceHeading.textContent ?? 'service',
     });
-    bridgeOutcome.textContent = result.isError === true ? 'Refresh unavailable.' : 'Status refreshed.';
+    bridgeOutcome.textContent = 'Status refreshed.';
   } catch {
     bridgeOutcome.textContent = 'Refresh unavailable.';
   }
 });
 
-await app.connect(new PostMessageTransport(window.parent, window.parent));
+await client.connect();
diff --git a/packages/agent-bundle/README.md b/packages/agent-bundle/README.md
index 9b47d5e52..5e820c465 100644
--- a/packages/agent-bundle/README.md
+++ b/packages/agent-bundle/README.md
@@ -103,6 +103,19 @@ stdin-EOF exit 0, bounded shutdown, heartbeat), also available directly from
 `agent-bundle/mcp-entry`. `tools.rsbuild` / `tools.rspack` is the single bundler escape hatch,
 merged last into every synthesized config and bounded by the artifact invariant assertions.
 
+MCP App views (`src/mcp/<server>/apps/*` or `mcp.servers.<id>.apps`) compile to one self-contained
+HTML resource each and talk to their host through `createAppClient()` from the browser-safe
+`agent-bundle/app` — the MCP Apps handshake, request ids, timeouts and cancellation, JSON-RPC and
+result decoding, and exact parent source/origin pinning are framework-owned, so a view never
+hand-writes `postMessage` frames. `call('tool:<server>/<name>', input)` resolves the tool's
+structured result object directly, `onToolInput` / `onToolResult` / `onToolCancelled` observe the
+opening call, `request()` covers `resources/read` and supported `ui/*` methods, and every failure
+is an `AppClientError` with a discriminated `code`. The generated `.agent-bundle/routes.d.ts`
+augments `AppRegister` with the project's tool contracts, so route ids, inputs, and results are
+typed from the routes' own schemas without a route module, Zod, or Node entering the App bundle.
+The entry is bundle-safe (never `AB4837`); the host-side relay, sandbox, and consent authority stay
+with the Workbench, `agent-bundle serve-app`, and embedding hosts.
+
 Projects that own their compilation entirely declare prebuilt payloads instead: the top-level
 `payload` block names already-built directory trees the build packages byte-for-byte at stable
 paths, and `entry: { prebuilt: './dist/…' }` (MCP servers) or
diff --git a/packages/agent-bundle/package.json b/packages/agent-bundle/package.json
index faa28694e..f351c5f99 100644
--- a/packages/agent-bundle/package.json
+++ b/packages/agent-bundle/package.json
@@ -47,6 +47,10 @@
       "types": "./dist/api.d.ts",
       "import": "./dist/api.js"
     },
+    "./app": {
+      "types": "./dist/app.d.ts",
+      "import": "./dist/app.js"
+    },
     "./cli-entry": {
       "types": "./dist/cli-entry.d.ts",
       "import": "./dist/cli-entry.js"
diff --git a/packages/agent-bundle/rslib.config.ts b/packages/agent-bundle/rslib.config.ts
index 799143b50..2972dab11 100644
--- a/packages/agent-bundle/rslib.config.ts
+++ b/packages/agent-bundle/rslib.config.ts
@@ -31,6 +31,21 @@ const esmNodeGlobalsPlugin: RsbuildPlugin = {
   },
 };
 
+/**
+ * Rslib's per-source declaration mode preserves `src/app/index.ts` as
+ * `dist/app/index.d.ts`. The public browser entry is intentionally the flat
+ * `dist/app.js`, so emit the matching declaration entry as a redirect while
+ * retaining the shared per-module declarations and strict import graph.
+ */
+const appDeclarationEntrypointPlugin: RsbuildPlugin = {
+  name: 'agent-bundle:app-declaration-entrypoint',
+  setup(api) {
+    api.processAssets({ stage: 'additions' }, ({ compilation, sources }) => {
+      compilation.emitAsset('app.d.ts', new sources.RawSource("export * from './app/index.js';\n"));
+    });
+  },
+};
+
 /**
  * Rslib enables Rspack's persistent build cache by default and keys its
  * directory by this config's root (`node_modules/.cache/rspack`), never by
@@ -88,6 +103,7 @@ export default defineConfig({
   plugins: [
     // Suggestions stay informational; errors and warnings block publishing.
     pluginPublint({ throwOn: 'warning' }),
+    appDeclarationEntrypointPlugin,
     // The bundled TypeScript 5 parser's eager `getNodeSystem()` reads the
     // CommonJS `__filename`/`__dirname` globals, which the ESM output does
     // not define and which Rspack's `node-module` rewrite (disabled below)
@@ -126,6 +142,7 @@ export default defineConfig({
     },
     entry: {
       api: './src/api.ts',
+      app: './src/app/index.ts',
       cli: './src/cli.ts',
       'cli-entry': './src/cli-entry.ts',
       config: './src/config/index.ts',
diff --git a/packages/agent-bundle/src/app/index.ts b/packages/agent-bundle/src/app/index.ts
new file mode 100644
index 000000000..a4ae533da
--- /dev/null
+++ b/packages/agent-bundle/src/app/index.ts
@@ -0,0 +1,645 @@
+import {
+  type JsonObject,
+  type JsonValue,
+  isPlainDataRecord,
+  ownDataValue,
+  snapshotStrictJsonValue,
+} from '../core/strict-json.ts';
+import { parseMcpRouteProtocolId } from '../routes/protocol-name.ts';
+
+export const APP_PROTOCOL_VERSION = '2026-01-26';
+
+export type AppClientErrorCode =
+  | 'timeout'
+  | 'aborted'
+  | 'disposed'
+  | 'connection-rebound'
+  | 'invalid-message'
+  | 'rpc'
+  | 'capability-unavailable'
+  | 'consent-required';
+
+export class AppClientError extends Error {
+  readonly code: AppClientErrorCode;
+  readonly data?: JsonValue;
+  readonly rpcCode?: number;
+
+  constructor(
+    code: AppClientErrorCode,
+    message: string,
+    options: Readonly<{ data?: JsonValue; rpcCode?: number }> = {},
+  ) {
+    super(message);
+    this.name = 'AppClientError';
+    this.code = code;
+    this.data = options.data;
+    this.rpcCode = options.rpcCode;
+  }
+}
+
+export interface AppRouteContract {
+  readonly input: unknown;
+  readonly result: unknown;
+}
+
+/** Project-generated declarations augment this interface with `routes`. */
+// rslint-disable-next-line @typescript-eslint/no-empty-object-type -- declaration-merge extension point
+export interface AppRegister {}
+
+export type AppRoutes = AppRegister extends {
+  readonly routes: infer Routes extends Record<string, AppRouteContract>;
+} ? Routes : unknown;
+
+export type AppRouteId = unknown extends AppRoutes
+  ? `tool:${string}/${string}`
+  : Extract<keyof AppRoutes, `tool:${string}/${string}`> & string;
+
+export type AppRouteInput<Id extends string> = Id extends keyof AppRoutes
+  ? AppRoutes[Id] extends AppRouteContract ? AppRoutes[Id]['input'] : unknown
+  : unknown;
+
+export type AppRouteResult<Id extends string> = Id extends keyof AppRoutes
+  ? AppRoutes[Id] extends AppRouteContract ? AppRoutes[Id]['result'] : unknown
+  : unknown;
+
+export interface AppImplementation {
+  readonly name: string;
+  readonly version: string;
+}
+
+export interface AppMessageEvent {
+  readonly data: unknown;
+  readonly origin: string;
+  readonly source: unknown;
+}
+
+export interface AppMessageTarget {
+  postMessage(message: JsonObject, targetOrigin: string): void;
+}
+
+export interface AppWindow {
+  readonly parent: AppMessageTarget;
+  addEventListener(type: 'message', listener: (event: AppMessageEvent) => void): void;
+  removeEventListener(type: 'message', listener: (event: AppMessageEvent) => void): void;
+}
+
+export interface AppConnectOptions {
+  readonly parent?: AppMessageTarget;
+  readonly targetOrigin?: string;
+  readonly window?: AppWindow;
+}
+
+export interface CreateAppClientOptions extends AppConnectOptions {
+  readonly appCapabilities?: JsonObject;
+  readonly appInfo?: AppImplementation;
+  readonly timeoutMs?: number;
+}
+
+export interface AppRequestOptions {
+  readonly signal?: AbortSignal;
+  readonly timeoutMs?: number;
+}
+
+export interface AppInitializeResult extends JsonObject {
+  readonly hostCapabilities: JsonObject;
+  readonly hostContext: JsonObject;
+  readonly hostInfo: JsonObject;
+  readonly protocolVersion: typeof APP_PROTOCOL_VERSION;
+}
+
+export type AppToolInputListener<Id extends string> = (
+  input: AppRouteInput<Id>,
+) => Promise<void> | void;
+
+export type AppToolResultListener<Id extends string> = (
+  result: AppRouteResult<Id>,
+) => Promise<void> | void;
+
+export type AppToolCancelledListener = (
+  event: Readonly<{ reason?: string }>,
+) => Promise<void> | void;
+
+export interface AppClient {
+  readonly connected: boolean;
+  readonly disposed: boolean;
+  connect(options?: AppRequestOptions): Promise<AppInitializeResult>;
+  request<Result extends JsonValue = JsonValue>(
+    method: string,
+    params?: JsonObject,
+    options?: AppRequestOptions,
+  ): Promise<Result>;
+  call<Id extends AppRouteId>(
+    routeId: Id,
+    input: AppRouteInput<Id>,
+    options?: AppRequestOptions,
+  ): Promise<AppRouteResult<Id>>;
+  onToolInput<Id extends AppRouteId>(
+    routeId: Id,
+    listener: AppToolInputListener<Id>,
+  ): () => void;
+  onToolResult<Id extends AppRouteId>(
+    routeId: Id,
+    listener: AppToolResultListener<Id>,
+  ): () => void;
+  onToolCancelled(listener: AppToolCancelledListener): () => void;
+  rebind(options?: AppConnectOptions): Promise<AppInitializeResult>;
+  dispose(): void;
+}
+
+interface RpcError {
+  readonly code: number;
+  readonly data?: JsonValue;
+  readonly message: string;
+}
+
+interface RpcMessage {
+  readonly error?: RpcError;
+  readonly id?: null | number | string;
+  readonly jsonrpc: '2.0';
+  readonly method?: string;
+  readonly params?: JsonValue;
+  readonly result?: JsonValue;
+}
+
+interface PendingRequest {
+  readonly initialize: boolean;
+  readonly reject: (error: AppClientError) => void;
+  readonly resolve: (value: JsonValue) => void;
+  readonly signal?: AbortSignal;
+  readonly timeout: ReturnType<typeof setTimeout>;
+  readonly abort?: () => void;
+}
+
+type AnyListener = (value: unknown) => Promise<void> | void;
+
+const allowedMessageKeys = Object.freeze(['error', 'id', 'jsonrpc', 'method', 'params', 'result']);
+const allowedErrorKeys = Object.freeze(['code', 'data', 'message']);
+const defaultTimeoutMs = 15_000;
+const maximumTimeoutMs = 2_147_483_647;
+
+const hasOwn = (value: object, key: string): boolean => Object.hasOwn(value, key);
+
+const nonempty = (value: unknown): value is string =>
+  typeof value === 'string' && value.trim().length > 0;
+
+const requestId = (value: unknown): value is null | number | string =>
+  value === null || typeof value === 'string' ||
+  (typeof value === 'number' && Number.isFinite(value));
+
+const timeoutValue = (value: number | undefined, fallback: number): number => {
+  const timeout = value ?? fallback;
+  if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > maximumTimeoutMs) {
+    throw new RangeError(`App client timeout must be an integer from 1 to ${String(maximumTimeoutMs)} ms.`);
+  }
+  return timeout;
+};
+
+const trustedOrigin = (value: string | undefined): string | undefined => {
+  if (value === undefined) return undefined;
+  if (value === '*' || value === 'null' || !nonempty(value)) {
+    throw new TypeError('App client targetOrigin must be an exact trusted origin.');
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new TypeError('App client targetOrigin must be an exact trusted origin.');
+  }
+  if (parsed.origin !== value || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+    throw new TypeError('App client targetOrigin must be an exact trusted http: or https: origin.');
+  }
+  return value;
+};
+
+const currentWindow = (): AppWindow => {
+  const candidate = (globalThis as { readonly window?: AppWindow }).window;
+  if (candidate === undefined) {
+    throw new TypeError('App client requires a browser window or an injected window option.');
+  }
+  return candidate;
+};
+
+const rpcMessage = (value: unknown): RpcMessage | undefined => {
+  let snapshot: JsonValue;
+  try {
+    snapshot = snapshotStrictJsonValue(value);
+  } catch {
+    return undefined;
+  }
+  if (!isPlainDataRecord(snapshot) || snapshot.jsonrpc !== '2.0') return undefined;
+  const keys = Object.keys(snapshot);
+  if (keys.some((key) => !allowedMessageKeys.includes(key))) return undefined;
+  const hasMethod = hasOwn(snapshot, 'method');
+  const hasResult = hasOwn(snapshot, 'result');
+  const hasError = hasOwn(snapshot, 'error');
+  if (Number(hasMethod) + Number(hasResult) + Number(hasError) !== 1) return undefined;
+  if (hasOwn(snapshot, 'id') && !requestId(snapshot.id)) return undefined;
+  if (hasMethod) {
+    if (!nonempty(snapshot.method) || hasResult || hasError) return undefined;
+    if (hasOwn(snapshot, 'params') && !isPlainDataRecord(snapshot.params)) return undefined;
+    return snapshot as unknown as RpcMessage;
+  }
+  if (!hasOwn(snapshot, 'id') || hasOwn(snapshot, 'params')) return undefined;
+  if (hasError) {
+    if (!isPlainDataRecord(snapshot.error)) return undefined;
+    if (
+      Object.keys(snapshot.error).some((key) => !allowedErrorKeys.includes(key)) ||
+      typeof snapshot.error.code !== 'number' ||
+      !Number.isFinite(snapshot.error.code) ||
+      !nonempty(snapshot.error.message)
+    ) {
+      return undefined;
+    }
+  }
+  return snapshot as unknown as RpcMessage;
+};
+
+const candidateId = (value: unknown): null | number | string | undefined => {
+  if (!isPlainDataRecord(value)) return undefined;
+  const jsonrpc = ownDataValue(value, 'jsonrpc');
+  const id = ownDataValue(value, 'id');
+  if (jsonrpc?.found !== true || jsonrpc.value !== '2.0' || id?.found !== true || !requestId(id.value)) {
+    return undefined;
+  }
+  return id.value;
+};
+
+const initializeResult = (value: JsonValue): AppInitializeResult | undefined => {
+  if (!isPlainDataRecord(value) || value.protocolVersion !== APP_PROTOCOL_VERSION) return undefined;
+  if (
+    !isPlainDataRecord(value.hostCapabilities) ||
+    !isPlainDataRecord(value.hostContext) ||
+    !isPlainDataRecord(value.hostInfo) ||
+    !nonempty(value.hostInfo.name) ||
+    !nonempty(value.hostInfo.version)
+  ) {
+    return undefined;
+  }
+  return value as AppInitializeResult;
+};
+
+const toolResult = (value: JsonValue): JsonObject | undefined => {
+  if (!isPlainDataRecord(value) || !Array.isArray(value.content)) return undefined;
+  if (!value.content.every((block) => isPlainDataRecord(block) && nonempty(block.type))) return undefined;
+  if (value.isError !== undefined && typeof value.isError !== 'boolean') return undefined;
+  if (value._meta !== undefined && !isPlainDataRecord(value._meta)) return undefined;
+  if (!isPlainDataRecord(value.structuredContent)) return undefined;
+  return value;
+};
+
+const errorFromRpc = (error: RpcError): AppClientError => {
+  const code: AppClientErrorCode = error.code === -32601
+    ? 'capability-unavailable'
+    : error.code === -32001 ? 'consent-required' : 'rpc';
+  return new AppClientError(code, error.message, {
+    ...(error.data === undefined ? {} : { data: error.data }),
+    rpcCode: error.code,
+  });
+};
+
+const routeToolName = (routeId: string): string => {
+  const identity = parseMcpRouteProtocolId(routeId);
+  if (identity?.kind !== 'tool') {
+    throw new TypeError(`App client route id ${JSON.stringify(routeId)} must use tool:<server>/<name>.`);
+  }
+  return identity.name;
+};
+
+const invokeListener = (listener: AnyListener, value: unknown): void => {
+  void Promise.resolve().then(() => listener(value)).catch(() => undefined);
+};
+
+export const createAppClient = (options: CreateAppClientOptions = {}): AppClient => {
+  let boundWindow = options.window ?? currentWindow();
+  let parent = options.parent ?? boundWindow.parent;
+  let configuredOrigin = trustedOrigin(options.targetOrigin);
+  let pinnedOrigin = configuredOrigin;
+  let nextId = 0;
+  let connection: Promise<AppInitializeResult> | undefined;
+  let connectedResult: AppInitializeResult | undefined;
+  let isDisposed = false;
+  const timeoutMs = timeoutValue(options.timeoutMs, defaultTimeoutMs);
+  const appInfo = snapshotStrictJsonValue(options.appInfo ?? { name: 'agent-bundle-app', version: '1.0.0' });
+  const appCapabilities = snapshotStrictJsonValue(options.appCapabilities ?? {});
+  if (
+    !isPlainDataRecord(appInfo) ||
+    !nonempty(appInfo.name) ||
+    !nonempty(appInfo.version) ||
+    !isPlainDataRecord(appCapabilities)
+  ) {
+    throw new TypeError('App client appInfo and appCapabilities must be finite JSON objects.');
+  }
+
+  const pending = new Map<null | number | string, PendingRequest>();
+  const inputListeners = new Map<string, Set<AnyListener>>();
+  const resultListeners = new Map<string, Set<AnyListener>>();
+  const cancelledListeners = new Set<AnyListener>();
+
+  const post = (message: JsonObject, targetOrigin: string): void => {
+    try {
+      parent.postMessage(message, targetOrigin);
+    } catch {
+      throw new AppClientError('invalid-message', 'The App host rejected a JSON-RPC message.');
+    }
+  };
+
+  const clearPending = (id: null | number | string): PendingRequest | undefined => {
+    const request = pending.get(id);
+    if (request === undefined) return undefined;
+    pending.delete(id);
+    clearTimeout(request.timeout);
+    if (request.abort !== undefined && request.signal !== undefined) {
+      request.signal.removeEventListener('abort', request.abort);
+    }
+    return request;
+  };
+
+  const notifyCancelled = (id: null | number | string, reason: string): void => {
+    if (connectedResult === undefined || pinnedOrigin === undefined || isDisposed) return;
+    try {
+      post({
+        jsonrpc: '2.0',
+        method: 'notifications/cancelled',
+        params: { reason, requestId: id },
+      }, pinnedOrigin);
+    } catch {
+      // The original timeout or abort remains the observable request failure.
+    }
+  };
+
+  const rejectPending = (code: AppClientErrorCode, message: string): void => {
+    for (const id of [...pending.keys()]) {
+      clearPending(id)?.reject(new AppClientError(code, message));
+    }
+  };
+
+  const sendResponse = (id: null | number | string, result: JsonObject): void => {
+    if (pinnedOrigin === undefined) return;
+    post({ id, jsonrpc: '2.0', result }, pinnedOrigin);
+  };
+
+  const publish = (listeners: Map<string, Set<AnyListener>>, value: unknown): void => {
+    for (const registered of listeners.values()) {
+      for (const listener of [...registered]) invokeListener(listener, value);
+    }
+  };
+
+  const dispose = (): void => {
+    if (isDisposed) return;
+    isDisposed = true;
+    boundWindow.removeEventListener('message', receive);
+    rejectPending('disposed', 'The App client was disposed.');
+    connection = undefined;
+    connectedResult = undefined;
+    pinnedOrigin = undefined;
+    inputListeners.clear();
+    resultListeners.clear();
+    cancelledListeners.clear();
+  };
+
+  const receive = (event: AppMessageEvent): void => {
+    if (isDisposed || event.source !== parent) return;
+    if (pinnedOrigin !== undefined && event.origin !== pinnedOrigin) return;
+    const message = rpcMessage(event.data);
+    if (message === undefined) {
+      const id = candidateId(event.data);
+      if (id !== undefined && pending.has(id)) {
+        clearPending(id)?.reject(new AppClientError('invalid-message', 'The App host returned an invalid JSON-RPC response.'));
+      }
+      return;
+    }
+
+    if (message.method === undefined) {
+      const request = message.id === undefined ? undefined : clearPending(message.id);
+      if (request === undefined) return;
+      let responseOrigin: string | undefined;
+      if (request.initialize && configuredOrigin === undefined) {
+        if (!nonempty(event.origin) || event.origin === 'null') {
+          request.reject(new AppClientError('invalid-message', 'The App host returned an unpinnable origin.'));
+          return;
+        }
+        responseOrigin = event.origin;
+      }
+      if (message.error !== undefined) {
+        request.reject(errorFromRpc(message.error));
+        return;
+      }
+      if (message.result === undefined) {
+        request.reject(new AppClientError('invalid-message', 'The App host response did not contain a result.'));
+        return;
+      }
+      if (request.initialize && initializeResult(message.result) === undefined) {
+        request.reject(new AppClientError('invalid-message', `The App host did not negotiate protocol ${APP_PROTOCOL_VERSION}.`));
+        return;
+      }
+      if (responseOrigin !== undefined) pinnedOrigin = responseOrigin;
+      request.resolve(message.result);
+      return;
+    }
+
+    if (pinnedOrigin === undefined || connectedResult === undefined) return;
+    if (message.id !== undefined) {
+      if (message.method === 'ui/resource-teardown') {
+        try {
+          sendResponse(message.id, {});
+        } finally {
+          dispose();
+        }
+        return;
+      }
+      post({
+        error: { code: -32601, message: `${message.method} is not supported by this App client.` },
+        id: message.id,
+        jsonrpc: '2.0',
+      }, pinnedOrigin);
+      return;
+    }
+    if (message.method === 'ui/notifications/tool-input') {
+      const params = isPlainDataRecord(message.params) ? message.params : undefined;
+      if (params !== undefined && isPlainDataRecord(params.arguments)) publish(inputListeners, params.arguments);
+      return;
+    }
+    if (message.method === 'ui/notifications/tool-result') {
+      const result = message.params === undefined ? undefined : toolResult(message.params);
+      if (result !== undefined) publish(resultListeners, result.structuredContent);
+      return;
+    }
+    if (message.method === 'ui/notifications/tool-cancelled') {
+      const params = message.params === undefined ? {} : message.params;
+      if (!isPlainDataRecord(params) || (params.reason !== undefined && typeof params.reason !== 'string')) return;
+      const eventValue = params.reason === undefined ? {} : { reason: params.reason };
+      for (const listener of [...cancelledListeners]) invokeListener(listener, eventValue);
+    }
+  };
+
+  boundWindow.addEventListener('message', receive);
+
+  const sendRequest = (
+    method: string,
+    params: JsonObject | undefined,
+    requestOptions: AppRequestOptions,
+    initialize: boolean,
+  ): Promise<JsonValue> => {
+    if (isDisposed) return Promise.reject(new AppClientError('disposed', 'The App client was disposed.'));
+    if (!nonempty(method)) return Promise.reject(new TypeError('App client request method must be nonempty.'));
+    if (requestOptions.signal?.aborted === true) {
+      return Promise.reject(new AppClientError('aborted', 'The App client request was aborted.'));
+    }
+    let snapshot: JsonObject | undefined;
+    try {
+      snapshot = params === undefined ? undefined : snapshotStrictJsonValue(params) as JsonObject;
+    } catch {
+      return Promise.reject(new AppClientError('invalid-message', 'App client request params must be finite strict JSON.'));
+    }
+    const id = ++nextId;
+    const targetOrigin = initialize ? configuredOrigin ?? '*' : pinnedOrigin;
+    if (targetOrigin === undefined) {
+      return Promise.reject(new AppClientError('capability-unavailable', 'The App client is not connected.'));
+    }
+    return new Promise<JsonValue>((resolvePromise, rejectPromise) => {
+      const timeout = setTimeout(() => {
+        if (clearPending(id) === undefined) return;
+        notifyCancelled(id, 'timeout');
+        rejectPromise(new AppClientError('timeout', `App client request ${method} timed out.`));
+      }, timeoutValue(requestOptions.timeoutMs, timeoutMs));
+      const abort = requestOptions.signal === undefined ? undefined : (): void => {
+        if (clearPending(id) === undefined) return;
+        notifyCancelled(id, 'aborted');
+        rejectPromise(new AppClientError('aborted', `App client request ${method} was aborted.`));
+      };
+      pending.set(id, {
+        initialize,
+        reject: rejectPromise,
+        resolve: resolvePromise,
+        signal: requestOptions.signal,
+        timeout,
+        ...(abort === undefined ? {} : { abort }),
+      });
+      requestOptions.signal?.addEventListener('abort', abort!, { once: true });
+      try {
+        post({
+          id,
+          jsonrpc: '2.0',
+          method,
+          ...(snapshot === undefined ? {} : { params: snapshot }),
+        }, targetOrigin);
+      } catch (error) {
+        clearPending(id);
+        rejectPromise(error instanceof AppClientError
+          ? error
+          : new AppClientError('invalid-message', 'The App request could not be sent.'));
+      }
+    });
+  };
+
+  const connect = (requestOptions: AppRequestOptions = {}): Promise<AppInitializeResult> => {
+    if (isDisposed) return Promise.reject(new AppClientError('disposed', 'The App client was disposed.'));
+    if (connectedResult !== undefined) return Promise.resolve(connectedResult);
+    if (connection !== undefined) return connection;
+    connection = sendRequest('ui/initialize', {
+      appCapabilities,
+      appInfo,
+      protocolVersion: APP_PROTOCOL_VERSION,
+    }, requestOptions, true).then((result) => {
+      const initialized = initializeResult(result);
+      if (initialized === undefined || pinnedOrigin === undefined) {
+        throw new AppClientError('invalid-message', 'The App host returned an invalid initialize result.');
+      }
+      post({ jsonrpc: '2.0', method: 'ui/notifications/initialized' }, pinnedOrigin);
+      connectedResult = initialized;
+      return initialized;
+    }).catch((error: unknown) => {
+      connection = undefined;
+      throw error;
+    });
+    return connection;
+  };
+
+  const request = <Result extends JsonValue = JsonValue>(
+    method: string,
+    params?: JsonObject,
+    requestOptions: AppRequestOptions = {},
+  ): Promise<Result> => {
+    if (connectedResult !== undefined) {
+      return sendRequest(method, params, requestOptions, false) as Promise<Result>;
+    }
+    return connect(requestOptions).then(
+      () => sendRequest(method, params, requestOptions, false) as Promise<Result>,
+    );
+  };
+
+  const call = async <Id extends AppRouteId>(
+    routeId: Id,
+    input: AppRouteInput<Id>,
+    requestOptions: AppRequestOptions = {},
+  ): Promise<AppRouteResult<Id>> => {
+    const name = routeToolName(routeId);
+    let argumentsValue: JsonObject;
+    try {
+      const snapshot = snapshotStrictJsonValue(input);
+      if (!isPlainDataRecord(snapshot)) throw new TypeError();
+      argumentsValue = snapshot;
+    } catch {
+      throw new AppClientError('invalid-message', `Input for ${routeId} must be a finite strict JSON object.`);
+    }
+    const response = await request<JsonValue>('tools/call', { arguments: argumentsValue, name }, requestOptions);
+    const result = toolResult(response);
+    if (result === undefined) {
+      throw new AppClientError('invalid-message', `Tool ${routeId} returned an invalid structured result.`);
+    }
+    if (result.isError === true) {
+      throw new AppClientError('rpc', `Tool ${routeId} returned an error.`, { data: result });
+    }
+    return result.structuredContent as AppRouteResult<Id>;
+  };
+
+  const register = (
+    listeners: Map<string, Set<AnyListener>>,
+    routeId: string,
+    listener: AnyListener,
+  ): (() => void) => {
+    routeToolName(routeId);
+    if (typeof listener !== 'function') throw new TypeError('App client listener must be a function.');
+    const registered = listeners.get(routeId) ?? new Set<AnyListener>();
+    registered.add(listener);
+    listeners.set(routeId, registered);
+    return (): void => {
+      registered.delete(listener);
+      if (registered.size === 0) listeners.delete(routeId);
+    };
+  };
+
+  const client: AppClient = {
+    get connected() { return connectedResult !== undefined; },
+    get disposed() { return isDisposed; },
+    connect,
+    request,
+    call,
+    onToolInput: (routeId, listener) => register(inputListeners, routeId, listener as AnyListener),
+    onToolResult: (routeId, listener) => register(resultListeners, routeId, listener as AnyListener),
+    onToolCancelled: (listener) => {
+      if (typeof listener !== 'function') throw new TypeError('App client listener must be a function.');
+      cancelledListeners.add(listener as AnyListener);
+      return (): void => { cancelledListeners.delete(listener as AnyListener); };
+    },
+    async rebind(rebindOptions: AppConnectOptions = {}): Promise<AppInitializeResult> {
+      if (isDisposed) throw new AppClientError('disposed', 'The App client was disposed.');
+      rejectPending('connection-rebound', 'The App client connection was rebound.');
+      connection = undefined;
+      connectedResult = undefined;
+      pinnedOrigin = undefined;
+      const replacementWindow = rebindOptions.window ?? boundWindow;
+      if (replacementWindow !== boundWindow) {
+        boundWindow.removeEventListener('message', receive);
+        boundWindow = replacementWindow;
+        boundWindow.addEventListener('message', receive);
+      }
+      parent = rebindOptions.parent ?? boundWindow.parent;
+      configuredOrigin = trustedOrigin(rebindOptions.targetOrigin);
+      pinnedOrigin = configuredOrigin;
+      return await connect();
+    },
+    dispose,
+  };
+  return Object.freeze(client);
+};
diff --git a/packages/agent-bundle/src/build/app-runtime.ts b/packages/agent-bundle/src/build/app-runtime.ts
new file mode 100644
index 000000000..493d46018
--- /dev/null
+++ b/packages/agent-bundle/src/build/app-runtime.ts
@@ -0,0 +1,18 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const appRuntimeSpecifier = 'agent-bundle/app';
+
+/** Resolves the browser runtime from source and from the packed compiler. */
+export const appRuntimePath = (): string => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  for (const candidate of [
+    join(here, 'app.js'),
+    join(here, '..', '..', 'dist', 'app.js'),
+    join(here, '..', 'app', 'index.ts'),
+  ]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error('Unable to locate the compiler-owned MCP App client runtime.');
+};
diff --git a/packages/agent-bundle/src/build/entries.ts b/packages/agent-bundle/src/build/entries.ts
index 937e2f048..9cc1929c7 100644
--- a/packages/agent-bundle/src/build/entries.ts
+++ b/packages/agent-bundle/src/build/entries.ts
@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import { readFile, stat } from 'node:fs/promises';
-import { basename, dirname, extname, join, relative, resolve } from 'node:path';
+import { dirname, extname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import type { NoticeDeliveryAdvertisement } from '../adapters/notice-delivery.ts';
@@ -48,6 +48,9 @@ import { emptyRouteConfig, type CompiledLayout, type CompiledProvider } from '..
 import type { CompiledMcpApp } from './mcp-apps.ts';
 import type { ArtifactOutputKind } from './provenance.ts';
 import type { RslibEntry, RslibSurfacePlan } from './rslib.ts';
+import { runtimeIgnoredRoot } from './runtime-path.ts';
+
+export { runtimeIgnoredRoot } from './runtime-path.ts';
 
 /**
  * Spelled as paths, not `new URL(…, import.meta.url)`: the package's own
@@ -66,27 +69,6 @@ const eventRuntimeModulePath = (module: 'ipc' | 'project'): string => {
   throw new Error(`Unable to locate the compiler-owned event ${module} runtime module.`);
 };
 
-/**
- * The package root owning one compiler-provided runtime module. Provenance
- * collects consumer sources, and a runtime module reaches its own siblings
- * (`routes/public.ts`, `core/*`) as it is inlined, so the whole owning package
- * is what has to be ignored rather than the single aliased file.
- */
-export const runtimeIgnoredRoot = (path: string): string => {
-  const normalized = path.replaceAll('\\', '/');
-  let directory = dirname(normalized);
-  while (true) {
-    if (basename(directory) === 'dist' || basename(directory) === 'src') {
-      return resolve(dirname(directory));
-    }
-    const parent = dirname(directory);
-    if (parent === directory) {
-      throw new Error(`Runtime module is not under an owning package src or dist directory: ${JSON.stringify(path)}.`);
-    }
-    directory = parent;
-  }
-};
-
 export interface CompiledEntry {
   readonly name: string;
   readonly output: string;
diff --git a/packages/agent-bundle/src/build/entry-shell.ts b/packages/agent-bundle/src/build/entry-shell.ts
index b4ab4899c..43fe4944a 100644
--- a/packages/agent-bundle/src/build/entry-shell.ts
+++ b/packages/agent-bundle/src/build/entry-shell.ts
@@ -9,6 +9,7 @@ import { stableJson } from '../core/digest.ts';
 import type { NormalizedHook, NormalizedNoticeRetentionPolicy, NormalizedStateDefinition } from '../core/types.ts';
 import { orderedProviders } from '../routes/provider-execution.ts';
 import { layoutChainFor, layoutRouteName } from '../routes/layouts.ts';
+import { mcpRouteProtocolName } from '../routes/protocol-name.ts';
 import { providerKeyFromName } from '../routes/providers.ts';
 import type { CompiledAgentRoute, CompiledCliCommand, CompiledLayout, CompiledProvider } from '../routes/types.ts';
 
@@ -755,9 +756,6 @@ export const generatedRouteArtifactEpoch = (plugin: {
   readonly version: string;
 }): string => `${plugin.name}@${plugin.version}`;
 
-const routeProtocolName = (route: CompiledAgentRoute): string =>
-  route.id.slice(route.id.lastIndexOf('/') + 1);
-
 const executableMcpRoutes = (routes: readonly CompiledAgentRoute[]): readonly CompiledAgentRoute[] =>
   routes.filter((route) => route.kind !== 'app');
 
@@ -776,7 +774,7 @@ const routeRecords = (
   routes.map((route, index) => {
     const layoutFields = worker === undefined ? '' : layoutChainField(route, worker.layouts);
     const serverField = worker === undefined || route.serverId === undefined ? '' : `, serverId: ${JSON.stringify(route.serverId)}`;
-    return `  ${JSON.stringify(route.id)}: Object.freeze({ config: ${stableJson(route.config)}, id: ${JSON.stringify(route.id)}, kind: ${JSON.stringify(route.kind)}${layoutFields}, module: route${String(index)}, name: ${JSON.stringify(routeProtocolName(route))}${serverField} }),`;
+    return `  ${JSON.stringify(route.id)}: Object.freeze({ config: ${stableJson(route.config)}, id: ${JSON.stringify(route.id)}, kind: ${JSON.stringify(route.kind)}${layoutFields}, module: route${String(index)}, name: ${JSON.stringify(mcpRouteProtocolName(route.id))}${serverField} }),`;
   });
 
 const noticeInboxImport = (wired: boolean): readonly string[] =>
@@ -1042,7 +1040,7 @@ const assertRegistrableMcpRoutes = (
   injectNoticeInbox: boolean,
 ): void => {
   for (const route of routes) {
-    if (injectNoticeInbox && routeProtocolName(route) === 'notice-inbox') {
+    if (injectNoticeInbox && mcpRouteProtocolName(route.id) === 'notice-inbox') {
       throw new Error(
         `Generated MCP route ${JSON.stringify(route.id)} uses the reserved protocol name "notice-inbox".`,
       );
diff --git a/packages/agent-bundle/src/build/mcp-apps.ts b/packages/agent-bundle/src/build/mcp-apps.ts
index b42140c84..6b40679ad 100644
--- a/packages/agent-bundle/src/build/mcp-apps.ts
+++ b/packages/agent-bundle/src/build/mcp-apps.ts
@@ -18,6 +18,7 @@ import { stableJson } from '../core/digest.ts';
 import { MAX_APP_HTML_BYTES } from '../core/mcp-app-limits.ts';
 import { escapeRegExp } from '../core/strings.ts';
 import type { AgentBundleMeta } from '../meta.ts';
+import { appRuntimePath, appRuntimeSpecifier } from './app-runtime.ts';
 import { composeToolsLayers, frameworkInvariantLayer } from './compose-layers.ts';
 import { listArtifactFiles, resolveArtifactDestination } from './emit.ts';
 import {
@@ -39,6 +40,7 @@ import {
   virtualModulesPluginConstructor,
 } from './meta.ts';
 import { collectBundledOutputEvidence } from './provenance.ts';
+import { runtimeIgnoredRoot } from './runtime-path.ts';
 
 export type { McpAppCompileMode, McpAppOutputSize } from './mcp-app-diagnostics.ts';
 
@@ -178,11 +180,20 @@ const isMetaModuleReplacement = (plugin: unknown, metaModulePath: string): boole
   && plugin._args[0].test(metaModuleSpecifier)
   && plugin._args[1] === metaModulePath;
 
+const appRuntimeReplacement = (runtimePath: string): InstanceType<typeof rspack.NormalModuleReplacementPlugin> =>
+  new rspack.NormalModuleReplacementPlugin(new RegExp(`^${escapeRegExp(appRuntimeSpecifier)}$`, 'u'), runtimePath);
+
+const isAppRuntimeReplacement = (plugin: unknown, runtimePath: string): boolean =>
+  plugin instanceof rspack.NormalModuleReplacementPlugin
+  && plugin._args[0].test(appRuntimeSpecifier)
+  && plugin._args[1] === runtimePath;
+
 const assertResolvedViewConfig = (
   inspection: Awaited<ReturnType<Awaited<ReturnType<typeof createRsbuild>>['inspectConfig']>>,
   appNames: readonly string[],
   outputRoot: string,
   metaModulePath: string,
+  runtimePath: string,
 ): void => {
   const environments = inspection.origin.environmentConfigs;
   const bundlers = inspection.origin.bundlerConfigs;
@@ -212,7 +223,8 @@ const assertResolvedViewConfig = (
       bundler.output.path !== outputRoot ||
       // The reserved `agent-bundle/meta` specifier must beat a consumer
       // tsconfig `paths` entry that shadows it (see `metaModuleReplacement`).
-      !(bundler.plugins ?? []).some((plugin) => isMetaModuleReplacement(plugin, metaModulePath))
+      !(bundler.plugins ?? []).some((plugin) => isMetaModuleReplacement(plugin, metaModulePath)) ||
+      !(bundler.plugins ?? []).some((plugin) => isAppRuntimeReplacement(plugin, runtimePath))
     ) {
       throw new Error('Rsbuild resolved an invalid self-contained MCP App configuration.');
     }
@@ -340,6 +352,7 @@ export const composeMcpAppsRsbuildConfig = (
   },
 ): RsbuildConfig => {
   const metaModulePath = generatedMetaModulePath(options.cwd);
+  const runtimePath = appRuntimePath();
   const profile: RsbuildConfig = {
     environments: Object.fromEntries(sources.map((source) => [source.name, {
       // Every view carries the React plugin, whatever its entry extension: a
@@ -389,13 +402,18 @@ export const composeMcpAppsRsbuildConfig = (
     // imports exactly this specifier, never subpaths beneath it.
     config.resolve = {
       ...config.resolve,
-      alias: { ...config.resolve?.alias, [`${metaModuleSpecifier}$`]: metaModulePath },
+      alias: {
+        ...config.resolve?.alias,
+        [`${appRuntimeSpecifier}$`]: runtimePath,
+        [`${metaModuleSpecifier}$`]: metaModulePath,
+      },
     };
     // Added after the hatch mutator (this hook is merged last), so a consumer
     // cannot strip the generated identity module out of the compiler.
     const VirtualModulesPlugin = rsbuildVirtualModulesPlugin();
     config.plugins = [
       ...(config.plugins ?? []),
+      appRuntimeReplacement(runtimePath),
       metaModuleReplacement(metaModulePath),
       new VirtualModulesPlugin({ [metaModulePath]: generatedMetaModuleSource(options.meta) }),
     ];
@@ -456,7 +474,14 @@ export const compileMcpApps = async (
   const collectedStats = new Map<string, Rspack.StatsCompilation>();
   rsbuild.addPlugins([mcpAppStatsCollectorPlugin(collectedStats), mcpAppHtmlDefaultsPlugin()]);
   const inspection = await rsbuild.inspectConfig({ mode: 'production' });
-  assertResolvedViewConfig(inspection, compiled.map((app) => app.name), options.outDir, generatedMetaModulePath(options.cwd));
+  const runtimePath = appRuntimePath();
+  assertResolvedViewConfig(
+    inspection,
+    compiled.map((app) => app.name),
+    options.outDir,
+    generatedMetaModulePath(options.cwd),
+    runtimePath,
+  );
   const contexts: readonly McpAppDiagnosticContext[] = compiled.map((app) => ({
     appName: app.name,
     entrySource: app.source,
@@ -493,7 +518,10 @@ export const compileMcpApps = async (
       })),
       // The generated identity module is virtual, but it still surfaces in
       // stats as a module under this reserved namespace.
-      ignoredSourcePaths: [resolve(generatedModulesRoot(options.cwd))],
+      ignoredSourcePaths: [
+        resolve(generatedModulesRoot(options.cwd)),
+        runtimeIgnoredRoot(runtimePath),
+      ],
       projectRoot: options.cwd,
       stats: result.stats,
     });
diff --git a/packages/agent-bundle/src/build/runtime-path.ts b/packages/agent-bundle/src/build/runtime-path.ts
new file mode 100644
index 000000000..4a71438b9
--- /dev/null
+++ b/packages/agent-bundle/src/build/runtime-path.ts
@@ -0,0 +1,21 @@
+import { basename, dirname, resolve } from 'node:path';
+
+/**
+ * The package root owning one compiler-provided runtime module. Provenance
+ * records consumer-authored sources, not framework runtime modules and their
+ * shared chunks.
+ */
+export const runtimeIgnoredRoot = (path: string): string => {
+  const normalized = path.replaceAll('\\', '/');
+  let directory = dirname(normalized);
+  while (true) {
+    if (basename(directory) === 'dist' || basename(directory) === 'src') {
+      return resolve(dirname(directory));
+    }
+    const parent = dirname(directory);
+    if (parent === directory) {
+      throw new Error(`Runtime module is not under an owning package src or dist directory: ${JSON.stringify(path)}.`);
+    }
+    directory = parent;
+  }
+};
diff --git a/packages/agent-bundle/src/config/normalize.ts b/packages/agent-bundle/src/config/normalize.ts
index 7e56ca929..70e85af9b 100644
--- a/packages/agent-bundle/src/config/normalize.ts
+++ b/packages/agent-bundle/src/config/normalize.ts
@@ -64,6 +64,7 @@ import type {
   SourceProvenance,
 } from '../core/types.ts';
 import { appRouteTemplatePath, resolveAppRouteTemplate } from '../routes/app-template.ts';
+import { mcpRouteProtocolName } from '../routes/protocol-name.ts';
 import type { CompiledCliSurface } from '../routes/types.ts';
 import { type DiscoveredProject, payloadDeclarationSource } from './discover.ts';
 import type { LoadedConfig } from './load.ts';
@@ -864,7 +865,7 @@ const normalizeMcpApps = (
       if (route.kind !== 'app') continue;
       const resourceUri = route.config['resourceUri'];
       if (typeof resourceUri !== 'string' || resourceUri.trim() === '') continue;
-      const name = route.id.slice(route.id.lastIndexOf('/') + 1);
+      const name = mcpRouteProtocolName(route.id);
       const declaredTargets = route.config['targets'];
       const targets = Array.isArray(declaredTargets) && declaredTargets.every((target) => typeof target === 'string')
         ? declaredTargets
diff --git a/packages/agent-bundle/src/config/validate.ts b/packages/agent-bundle/src/config/validate.ts
index 9a6fe1560..fe0313a8f 100644
--- a/packages/agent-bundle/src/config/validate.ts
+++ b/packages/agent-bundle/src/config/validate.ts
@@ -22,6 +22,7 @@ import {
 } from '../core/runtime.ts';
 import { canonicalHookEvents, isPrebuiltEntryInput, parseNativeHookToolSelector } from '../core/types.ts';
 import { type RouteModuleExports, scanRouteModuleExports } from '../routes/contract.ts';
+import { mcpRouteProtocolName } from '../routes/protocol-name.ts';
 import { featureCapabilityName } from '../core/components.ts';
 import type {
   AgentBundleBinEntry,
@@ -925,7 +926,7 @@ const validateMcp = (
   for (const server of generatedServers) {
     for (const route of server.routes) {
       if (route.kind !== 'app') continue;
-      const appName = route.id.slice(route.id.lastIndexOf('/') + 1);
+      const appName = mcpRouteProtocolName(route.id);
       if (!names.has(appName)) names.set(appName, undefined);
       const resourceUri = route.config['resourceUri'];
       if (typeof resourceUri === 'string' && !uris.has(resourceUri)) uris.set(resourceUri, appName);
diff --git a/packages/agent-bundle/src/routes/cli-commands.ts b/packages/agent-bundle/src/routes/cli-commands.ts
index 62d44c72b..9e4a03747 100644
--- a/packages/agent-bundle/src/routes/cli-commands.ts
+++ b/packages/agent-bundle/src/routes/cli-commands.ts
@@ -2,6 +2,7 @@ import { extname } from 'node:path';
 
 import { extractCliArgv } from './cli-argv.ts';
 import { scanRouteModuleExports } from './contract.ts';
+import { mcpRouteProtocolName } from './protocol-name.ts';
 import type { Diagnostic } from '../core/diagnostics.ts';
 import { deepFreeze } from '../core/freeze.ts';
 import { isRecord } from '../core/strict-json.ts';
@@ -280,7 +281,7 @@ export const compileMcpCliCommands = (
     .flatMap((server) => server.routes
       .filter((route) => route.kind === 'tool')
       .map((route) => {
-        const tool = route.id.slice(route.id.lastIndexOf('/') + 1);
+        const tool = mcpRouteProtocolName(route.id);
         return { identity: `${server.name}:${tool}`, route, server: server.name, tool };
       }))
     .sort((left, right) => left.identity.localeCompare(right.identity));
diff --git a/packages/agent-bundle/src/routes/layouts.ts b/packages/agent-bundle/src/routes/layouts.ts
index adf69bb2b..8562c370f 100644
--- a/packages/agent-bundle/src/routes/layouts.ts
+++ b/packages/agent-bundle/src/routes/layouts.ts
@@ -1,3 +1,4 @@
+import { mcpRouteProtocolName } from './protocol-name.ts';
 import type { AgentLayoutRouteKind } from './public.ts';
 import type { CompiledAgentRoute, CompiledLayout, CompiledRouteKind } from './types.ts';
 
@@ -60,18 +61,19 @@ export const isLayoutRouteKind = (kind: CompiledRouteKind): kind is AgentLayoutR
  * or prompt name, the space-joined CLI command path, or the script name.
  */
 export const layoutRouteName = (route: Pick<LayoutRouteTarget, 'id' | 'kind'>): string => {
-  const identity = route.id.slice(route.id.indexOf(':') + 1);
   switch (route.kind) {
     case 'tool':
     case 'resource':
     case 'prompt':
     case 'app':
-      return identity.slice(identity.lastIndexOf('/') + 1);
-    case 'cli':
+      return mcpRouteProtocolName(route.id);
+    case 'cli': {
+      const identity = route.id.slice(route.id.indexOf(':') + 1);
       return identity.split('/').join(' ');
+    }
     case 'script':
     case 'event-route':
-      return identity;
+      return route.id.slice(route.id.indexOf(':') + 1);
     default: {
       const unreachable: never = route.kind;
       throw new TypeError(`Unhandled route kind ${String(unreachable)}.`);
diff --git a/packages/agent-bundle/src/routes/protocol-name.ts b/packages/agent-bundle/src/routes/protocol-name.ts
new file mode 100644
index 000000000..0ae2e8806
--- /dev/null
+++ b/packages/agent-bundle/src/routes/protocol-name.ts
@@ -0,0 +1,63 @@
+/**
+ * Canonical generated MCP route ids are `<kind>:<server>/<name>`
+ * (`tool:hauler/hauler_status`). Generated servers register the final segment
+ * as the wire name and have no name override.
+ *
+ * Zero-import leaf so compiler, test harness, and a browser App client share
+ * one derivation without pulling Node, Zod, or the route graph.
+ */
+
+/** MCP route kinds whose generated id is `<kind>:<server>/<name>`. */
+export const mcpRouteProtocolKinds = Object.freeze(['app', 'prompt', 'resource', 'tool'] as const);
+
+export type McpRouteProtocolKind = (typeof mcpRouteProtocolKinds)[number];
+
+export interface McpRouteProtocolIdentity {
+  readonly kind: McpRouteProtocolKind;
+  readonly name: string;
+  readonly server: string;
+}
+
+const isMcpRouteProtocolKind = (value: string): value is McpRouteProtocolKind => {
+  switch (value) {
+    case 'app':
+    case 'prompt':
+    case 'resource':
+    case 'tool':
+      return true;
+    default:
+      return false;
+  }
+};
+
+/**
+ * Parse a canonical generated MCP route id (`<kind>:<server>/<name>`).
+ * Returns `undefined` when the id is not that shape.
+ */
+export const parseMcpRouteProtocolId = (routeId: string): McpRouteProtocolIdentity | undefined => {
+  const colon = routeId.indexOf(':');
+  if (colon <= 0 || routeId.indexOf(':', colon + 1) !== -1) return undefined;
+  const kind = routeId.slice(0, colon);
+  if (!isMcpRouteProtocolKind(kind)) return undefined;
+  const rest = routeId.slice(colon + 1);
+  const slash = rest.indexOf('/');
+  if (slash <= 0 || rest.indexOf('/', slash + 1) !== -1) return undefined;
+  const server = rest.slice(0, slash);
+  const name = rest.slice(slash + 1);
+  if (name === '') return undefined;
+  return { kind, name, server };
+};
+
+/**
+ * The protocol name a generated MCP server registers — the final id segment.
+ * Throws when `routeId` is not a canonical generated MCP route id.
+ */
+export const mcpRouteProtocolName = (routeId: string): string => {
+  const parsed = parseMcpRouteProtocolId(routeId);
+  if (parsed === undefined) {
+    throw new TypeError(
+      `Expected a canonical MCP route id (<kind>:<server>/<name>); got ${JSON.stringify(routeId)}.`,
+    );
+  }
+  return parsed.name;
+};
diff --git a/packages/agent-bundle/src/routes/typegen.ts b/packages/agent-bundle/src/routes/typegen.ts
index 9fa0f001d..a99635f89 100644
--- a/packages/agent-bundle/src/routes/typegen.ts
+++ b/packages/agent-bundle/src/routes/typegen.ts
@@ -61,6 +61,63 @@ const providerDeclarations = (providers: readonly CompiledProvider[]): readonly
       '',
     ];
 
+/**
+ * Whether the graph has a route an MCP App can call: the generated servers'
+ * tool routes. Prompts, resources, Apps, CLI commands, and event routes are
+ * not `tools/call` targets, so a graph with only those registers nothing on
+ * `agent-bundle/app`.
+ */
+const hasToolRoutes = (routes: readonly CompiledAgentRoute[]): boolean =>
+  routes.some((route) => route.kind === 'tool');
+
+/**
+ * The App half of the generated declarations: `AgentBundleAppRouteContracts`
+ * is the MCP tool subset of `AgentBundleRoutes` — the `tool:<server>/<name>`
+ * ids filtered at the type level, so every route id is spelled once and the
+ * contracts reuse the same type-only route module imports — one
+ * `{ input, result }` per tool from the module's own `inputSchema` and
+ * `resultSchema` output. The filter is inlined in the mapped type rather than
+ * named first so `keyof` the map (what an App client's route-id parameter
+ * resolves to) prints as the tool ids in a rejection, not as an alias name.
+ * Omitted for graphs without a tool route.
+ */
+const appDeclarations = (routes: readonly CompiledAgentRoute[]): readonly string[] =>
+  hasToolRoutes(routes)
+    ? [
+      '/** The registered App contract map: one `{ input, result }` per MCP tool route id, for `agent-bundle/app`\'s `AppRegister`. */',
+      'export type AgentBundleAppRouteContracts = {',
+      '  readonly [Id in Extract<RouteId, `tool:${string}/${string}`>]: Readonly<{ input: RouteInput<Id>; result: RouteResult<Id> }>;',
+      '};',
+      '/** The MCP tool route ids: the routes an MCP App calls through `agent-bundle/app`. */',
+      'export type AppToolRouteId = keyof AgentBundleAppRouteContracts;',
+      '',
+    ]
+    : [];
+
+/**
+ * The single `agent-bundle/app` augmentation: `AppRegister.routes` registers
+ * the tool contract map (the same `Register` pattern as the runtime
+ * augmentation below), so `createAppClient().call(id, input)` narrows its
+ * route id to the project's tools, `input` to that tool's `inputSchema`
+ * output, and its resolved value to the `resultSchema` output. Type-only:
+ * the App bundle never loads a route module, Zod, or Node through it.
+ * Omitted with the contract map for graphs without a tool route, so the
+ * augmentation never references a module the project has no reason to
+ * depend on; where `agent-bundle/app` is not resolvable, TypeScript drops an
+ * ambient augmentation of it silently.
+ */
+const appAugmentation = (routes: readonly CompiledAgentRoute[]): readonly string[] =>
+  hasToolRoutes(routes)
+    ? [
+      "declare module 'agent-bundle/app' {",
+      '  interface AppRegister {',
+      '    readonly routes: AgentBundleAppRouteContracts;',
+      '  }',
+      '}',
+      '',
+    ]
+    : [];
+
 /**
  * The single `@agent-bundle/runtime` augmentation. Its `Register.routes`
  * member registers the thin `{ input, result }` contract map (TanStack
@@ -154,8 +211,10 @@ export const generateRouteTypes = (graph: CompiledRouteGraph): string => {
     '  readonly [Id in RouteId]: Readonly<{ input: HarnessInput<AgentBundleRoutes[Id]>; result: HarnessResult<AgentBundleRoutes[Id]> }>;',
     '};',
     '',
+    ...appDeclarations(routes),
     ...providerDeclarations(providers),
     ...runtimeAugmentation(routes, providers),
+    ...appAugmentation(routes),
   ].join('\n');
 };
 
diff --git a/packages/agent-bundle/src/test/contract.ts b/packages/agent-bundle/src/test/contract.ts
index 49f3193d2..9a748636b 100644
--- a/packages/agent-bundle/src/test/contract.ts
+++ b/packages/agent-bundle/src/test/contract.ts
@@ -58,6 +58,7 @@ import {
   requestEventRuntimeStatus,
   type EventRuntimeStatusResult,
 } from '../events/ipc.ts';
+import { mcpRouteProtocolName } from '../routes/protocol-name.ts';
 import { AgentTestError, captured } from './errors.ts';
 import {
   DEV_EPOCH_PROOF_LEVEL,
@@ -472,7 +473,7 @@ interface LiveSurface {
 }
 
 const routeProtocolName = (descriptor: TestableRouteDescriptor): string =>
-  descriptor.id.slice(descriptor.id.lastIndexOf('/') + 1);
+  mcpRouteProtocolName(descriptor.id);
 
 const routeResourceUri = (descriptor: TestableRouteDescriptor): string | undefined => {
   const uri = descriptor.config.uri;
diff --git a/packages/agent-bundle/src/test/mcp.ts b/packages/agent-bundle/src/test/mcp.ts
index 36c0a3219..4b4cd0f34 100644
--- a/packages/agent-bundle/src/test/mcp.ts
+++ b/packages/agent-bundle/src/test/mcp.ts
@@ -36,6 +36,7 @@ import type { ReactNode } from 'react';
 import type { NoticeDeliveryAdvertisement } from '../adapters/notice-delivery.ts';
 import type { NormalizedNoticeRetentionPolicy } from '../core/types.ts';
 import type { GeneratedNoticeDeliveryBinding, GeneratedNoticePrincipal } from '../mcp-server-runtime.ts';
+import { mcpRouteProtocolName } from '../routes/protocol-name.ts';
 import { createProviderProcessLifetime } from '../routes/provider-execution.ts';
 import { AgentTestError, captured } from './errors.ts';
 import { composeLayouts, loadLayoutChain, type LoadedLayout } from './layouts.ts';
@@ -425,7 +426,7 @@ export const openInMemoryMcpServer = async <
       id: descriptor.id,
       kind: descriptor.kind,
       module: { ...module, resultSchema: module.resultSchema },
-      name: descriptor.id.slice(descriptor.id.lastIndexOf('/') + 1),
+      name: mcpRouteProtocolName(descriptor.id),
     };
     layoutsByRoute.set(
       descriptor.id,
diff --git a/packages/agent-bundle/src/test/render.ts b/packages/agent-bundle/src/test/render.ts
index fb5ed6ea9..802160415 100644
--- a/packages/agent-bundle/src/test/render.ts
+++ b/packages/agent-bundle/src/test/render.ts
@@ -31,6 +31,7 @@ import type {
   GeneratedCliRenderContext,
   GeneratedCliRenderSession,
 } from '../cli-entry.ts';
+import { parseMcpRouteProtocolId } from '../routes/protocol-name.ts';
 import { createProviderProcessLifetime, type ProviderProcessLifetime } from '../routes/provider-execution.ts';
 import { routeRenderLimits, type RouteRenderBudget } from '../routes/render-budget.ts';
 import type { CompiledCliCommand } from '../routes/types.ts';
@@ -357,8 +358,12 @@ interface ResolvedTarget {
   readonly render?: RouteRenderBudget;
 }
 
-/** The protocol name a generated server registers, and the request surface it records. */
-const protocolName = (routeId: string): string => routeId.slice(routeId.lastIndexOf('/') + 1);
+/**
+ * The protocol name a generated server registers, and the request surface it
+ * records. Module-direct renders may omit a canonical id (`(module passed to
+ * renderRoute)`); those keep the id itself as the surface name.
+ */
+const protocolName = (routeId: string): string => parseMcpRouteProtocolId(routeId)?.name ?? routeId;
 
 /**
  * Props the route component receives. MCP route kinds get exactly the public
diff --git a/packages/agent-bundle/tests/app-client.test.ts b/packages/agent-bundle/tests/app-client.test.ts
new file mode 100644
index 000000000..19bd53d96
--- /dev/null
+++ b/packages/agent-bundle/tests/app-client.test.ts
@@ -0,0 +1,403 @@
+import { expect, it } from '@rstest/core';
+
+import {
+  APP_PROTOCOL_VERSION,
+  AppClientError,
+  type AppMessageEvent,
+  type AppMessageTarget,
+  type AppRouteId,
+  type AppRouteInput,
+  type AppRouteResult,
+  type AppWindow,
+  createAppClient,
+} from '../src/app/index.ts';
+import type { JsonObject } from '../src/core/strict-json.ts';
+
+declare module '../src/app/index.ts' {
+  interface AppRegister {
+    readonly routes: {
+      readonly 'tool:hauler/hauler_status': {
+        readonly input: { readonly limit: number };
+        readonly result: { readonly active: number; readonly status: string };
+      };
+      readonly 'tool:server/status': {
+        readonly input: Readonly<Record<string, unknown>>;
+        readonly result: { readonly count?: number };
+      };
+    };
+  }
+}
+
+type Equals<Left, Right> =
+  (<Value>() => Value extends Left ? 1 : 2) extends
+    (<Value>() => Value extends Right ? 1 : 2) ? true : false;
+type Assert<Value extends true> = Value;
+type RouteIdProof = Assert<Equals<
+  AppRouteId,
+  'tool:hauler/hauler_status' | 'tool:server/status'
+>>;
+type RouteInputProof = Assert<Equals<
+  AppRouteInput<'tool:hauler/hauler_status'>,
+  { readonly limit: number }
+>>;
+type RouteResultProof = Assert<Equals<
+  AppRouteResult<'tool:hauler/hauler_status'>,
+  { readonly active: number; readonly status: string }
+>>;
+
+interface PostedMessage {
+  readonly message: JsonObject;
+  readonly targetOrigin: string;
+}
+
+const hostOrigin = 'https://host.example';
+const typeProofs: readonly [RouteIdProof, RouteInputProof, RouteResultProof] = [true, true, true];
+
+const initializeResult = {
+  hostCapabilities: { serverTools: {} },
+  hostContext: {},
+  hostInfo: { name: 'test-host', version: '1.0.0' },
+  protocolVersion: APP_PROTOCOL_VERSION,
+} as const;
+
+const harness = () => {
+  const posts: PostedMessage[] = [];
+  const listeners = new Set<(event: AppMessageEvent) => void>();
+  const parent: AppMessageTarget = {
+    postMessage(message, targetOrigin) {
+      posts.push({ message, targetOrigin });
+    },
+  };
+  const window: AppWindow = {
+    parent,
+    addEventListener(_type, listener) {
+      listeners.add(listener);
+    },
+    removeEventListener(_type, listener) {
+      listeners.delete(listener);
+    },
+  };
+  return {
+    emit(
+      data: unknown,
+      origin = hostOrigin,
+      source: unknown = parent,
+    ): void {
+      for (const listener of [...listeners]) listener({ data, origin, source });
+    },
+    listenerCount: (): number => listeners.size,
+    parent,
+    posts,
+    window,
+  };
+};
+
+const responseId = (entry: PostedMessage): null | number | string => {
+  const id = entry.message.id;
+  if (id === null || typeof id === 'string' || typeof id === 'number') return id;
+  throw new Error('Posted request did not contain an id.');
+};
+
+const connect = async (
+  client: ReturnType<typeof createAppClient>,
+  target: ReturnType<typeof harness>,
+  origin = hostOrigin,
+): Promise<void> => {
+  const connecting = client.connect();
+  const request = target.posts.at(-1)!;
+  target.emit({
+    id: responseId(request),
+    jsonrpc: '2.0',
+    result: initializeResult,
+  }, origin);
+  await connecting;
+};
+
+const flushListeners = async (): Promise<void> => {
+  await Promise.resolve();
+  await Promise.resolve();
+};
+
+it('bootstraps an opaque sandbox only through a matching parent initialize response and pins its origin', async () => {
+  expect(typeProofs).toEqual([true, true, true]);
+  const target = harness();
+  const foreignParent = {};
+  const client = createAppClient({
+    appInfo: { name: 'dashboard', version: '2.0.0' },
+    window: target.window,
+  });
+
+  const connecting = client.connect();
+  expect(target.posts).toEqual([{
+    message: {
+      id: 1,
+      jsonrpc: '2.0',
+      method: 'ui/initialize',
+      params: {
+        appCapabilities: {},
+        appInfo: { name: 'dashboard', version: '2.0.0' },
+        protocolVersion: APP_PROTOCOL_VERSION,
+      },
+    },
+    targetOrigin: '*',
+  }]);
+
+  target.emit({ id: 1, jsonrpc: '2.0', result: initializeResult }, 'https://attacker.example', foreignParent);
+  target.emit({ id: 99, jsonrpc: '2.0', result: initializeResult });
+  expect(client.connected).toBe(false);
+
+  target.emit({ id: 1, jsonrpc: '2.0', result: initializeResult });
+  await expect(connecting).resolves.toEqual(initializeResult);
+  expect(client.connected).toBe(true);
+  expect(target.posts.at(-1)).toEqual({
+    message: { jsonrpc: '2.0', method: 'ui/notifications/initialized' },
+    targetOrigin: hostOrigin,
+  });
+
+  const request = client.request('ping', {});
+  expect(target.posts.at(-1)?.targetOrigin).toBe(hostOrigin);
+  const pingId = responseId(target.posts.at(-1)!);
+  target.emit({ id: pingId, jsonrpc: '2.0', result: {} }, 'https://attacker.example');
+  expect(target.posts).toHaveLength(3);
+  target.emit({ id: pingId, jsonrpc: '2.0', result: {} });
+  await expect(request).resolves.toEqual({});
+});
+
+it('uses an exact trusted targetOrigin from the first message and rejects a mismatched response origin', async () => {
+  const target = harness();
+  const client = createAppClient({
+    parent: target.parent,
+    targetOrigin: hostOrigin,
+    window: target.window,
+  });
+  const connecting = client.connect({ timeoutMs: 20 });
+  expect(target.posts[0]?.targetOrigin).toBe(hostOrigin);
+  target.emit({ id: 1, jsonrpc: '2.0', result: initializeResult }, 'https://other.example');
+  expect(client.connected).toBe(false);
+  target.emit({ id: 1, jsonrpc: '2.0', result: initializeResult });
+  await expect(connecting).resolves.toEqual(initializeResult);
+
+  expect(() => createAppClient({
+    targetOrigin: '*',
+    window: target.window,
+  })).toThrow(/exact trusted origin/u);
+});
+
+it('calls a route by its protocol tool name and returns structuredContent directly', async () => {
+  const target = harness();
+  const client = createAppClient({ window: target.window });
+  await connect(client, target);
+
+  const called = client.call('tool:hauler/hauler_status', { limit: 40 });
+  const request = target.posts.at(-1)!;
+  expect(request).toEqual({
+    message: {
+      id: 2,
+      jsonrpc: '2.0',
+      method: 'tools/call',
+      params: { arguments: { limit: 40 }, name: 'hauler_status' },
+    },
+    targetOrigin: hostOrigin,
+  });
+  target.emit({
+    id: responseId(request),
+    jsonrpc: '2.0',
+    result: {
+      content: [{ text: 'healthy', type: 'text' }],
+      structuredContent: { active: 3, status: 'healthy' },
+    },
+  });
+  await expect(called).resolves.toEqual({ active: 3, status: 'healthy' });
+});
+
+it('maps RPC capability, consent, and general failures to the single AppClientError class', async () => {
+  const cases = [
+    [-32601, 'capability-unavailable'],
+    [-32001, 'consent-required'],
+    [-32000, 'rpc'],
+  ] as const;
+  for (const [rpcCode, code] of cases) {
+    const target = harness();
+    const client = createAppClient({ window: target.window });
+    await connect(client, target);
+    const request = client.request('tools/call', { name: 'status' });
+    const id = responseId(target.posts.at(-1)!);
+    target.emit({
+      error: { code: rpcCode, data: { reason: code }, message: `failed: ${code}` },
+      id,
+      jsonrpc: '2.0',
+    });
+    await expect(request).rejects.toMatchObject({
+      code,
+      data: { reason: code },
+      name: 'AppClientError',
+      rpcCode,
+    });
+    client.dispose();
+  }
+});
+
+it('rejects malformed envelopes and tool results without retaining hostile values', async () => {
+  const target = harness();
+  const client = createAppClient({ window: target.window });
+  const connecting = client.connect();
+  target.emit({
+    extra: true,
+    id: 1,
+    jsonrpc: '2.0',
+    result: initializeResult,
+  });
+  await expect(connecting).rejects.toMatchObject({ code: 'invalid-message' });
+
+  const retry = client.connect();
+  target.emit({ id: 2, jsonrpc: '2.0', result: initializeResult });
+  await retry;
+  const called = client.call('tool:server/status', {});
+  target.emit({
+    id: 3,
+    jsonrpc: '2.0',
+    result: {
+      content: [{ text: 'missing structured data', type: 'text' }],
+    },
+  });
+  await expect(called).rejects.toMatchObject({ code: 'invalid-message' });
+
+  const cyclic: Record<string, unknown> = {};
+  cyclic.self = cyclic;
+  await expect(client.call('tool:server/status', cyclic)).rejects.toMatchObject({
+    code: 'invalid-message',
+  });
+  await expect(client.call('prompt:server/status' as AppRouteId, {}))
+    .rejects.toThrow(/tool:<server>\/<name>/u);
+});
+
+it('times out and aborts pending connected requests while notifying the host of cancellation', async () => {
+  const target = harness();
+  const client = createAppClient({ timeoutMs: 50, window: target.window });
+  await connect(client, target);
+
+  const timedOut = client.request('slow', {}, { timeoutMs: 5 });
+  await expect(timedOut).rejects.toMatchObject({ code: 'timeout' });
+  expect(target.posts.at(-1)).toEqual({
+    message: {
+      jsonrpc: '2.0',
+      method: 'notifications/cancelled',
+      params: { reason: 'timeout', requestId: 2 },
+    },
+    targetOrigin: hostOrigin,
+  });
+
+  const controller = new AbortController();
+  const aborted = client.request('slower', {}, { signal: controller.signal });
+  controller.abort();
+  await expect(aborted).rejects.toMatchObject({ code: 'aborted' });
+  expect(target.posts.at(-1)).toEqual({
+    message: {
+      jsonrpc: '2.0',
+      method: 'notifications/cancelled',
+      params: { reason: 'aborted', requestId: 3 },
+    },
+    targetOrigin: hostOrigin,
+  });
+
+  const alreadyAborted = new AbortController();
+  alreadyAborted.abort();
+  const before = target.posts.length;
+  await expect(client.request('never-sent', {}, { signal: alreadyAborted.signal }))
+    .rejects.toMatchObject({ code: 'aborted' });
+  expect(target.posts).toHaveLength(before);
+});
+
+it('delivers typed tool lifecycle notifications and supports listener removal', async () => {
+  const target = harness();
+  const client = createAppClient({ window: target.window });
+  await connect(client, target);
+  const inputs: unknown[] = [];
+  const results: unknown[] = [];
+  const cancellations: unknown[] = [];
+  const offInput = client.onToolInput('tool:server/status', (input) => { inputs.push(input); });
+  client.onToolResult('tool:server/status', (result) => { results.push(result); });
+  client.onToolCancelled((event) => { cancellations.push(event); });
+
+  target.emit({
+    jsonrpc: '2.0',
+    method: 'ui/notifications/tool-input',
+    params: { arguments: { limit: 2 } },
+  });
+  target.emit({
+    jsonrpc: '2.0',
+    method: 'ui/notifications/tool-result',
+    params: {
+      content: [{ text: 'done', type: 'text' }],
+      structuredContent: { count: 2 },
+    },
+  });
+  target.emit({
+    jsonrpc: '2.0',
+    method: 'ui/notifications/tool-cancelled',
+    params: { reason: 'host stopped' },
+  });
+  await flushListeners();
+  expect(inputs).toEqual([{ limit: 2 }]);
+  expect(results).toEqual([{ count: 2 }]);
+  expect(cancellations).toEqual([{ reason: 'host stopped' }]);
+
+  offInput();
+  target.emit({
+    jsonrpc: '2.0',
+    method: 'ui/notifications/tool-input',
+    params: { arguments: { limit: 3 } },
+  });
+  await flushListeners();
+  expect(inputs).toEqual([{ limit: 2 }]);
+});
+
+it('rejects old pending work on rebind and establishes a fresh exact-origin connection', async () => {
+  const first = harness();
+  const second = harness();
+  const secondOrigin = 'https://replacement.example';
+  const client = createAppClient({ window: first.window });
+  await connect(client, first);
+  const oldRequest = client.request('slow', {});
+  const oldFailure = expect(oldRequest).rejects.toMatchObject({ code: 'connection-rebound' });
+
+  const rebound = client.rebind({
+    parent: second.parent,
+    targetOrigin: secondOrigin,
+    window: second.window,
+  });
+  expect(first.listenerCount()).toBe(0);
+  expect(second.listenerCount()).toBe(1);
+  expect(second.posts[0]?.targetOrigin).toBe(secondOrigin);
+  second.emit({
+    id: responseId(second.posts[0]!),
+    jsonrpc: '2.0',
+    result: initializeResult,
+  }, secondOrigin);
+  await expect(rebound).resolves.toEqual(initializeResult);
+  await oldFailure;
+  expect(client.connected).toBe(true);
+});
+
+it('acknowledges host teardown before disposing and makes disposal idempotent', async () => {
+  const target = harness();
+  const client = createAppClient({ window: target.window });
+  await connect(client, target);
+
+  target.emit({
+    id: 'close-1',
+    jsonrpc: '2.0',
+    method: 'ui/resource-teardown',
+    params: {},
+  });
+  expect(target.posts.at(-1)).toEqual({
+    message: { id: 'close-1', jsonrpc: '2.0', result: {} },
+    targetOrigin: hostOrigin,
+  });
+  expect(client.disposed).toBe(true);
+  expect(client.connected).toBe(false);
+  expect(target.listenerCount()).toBe(0);
+  client.dispose();
+  await expect(client.connect()).rejects.toBeInstanceOf(AppClientError);
+  await expect(client.connect()).rejects.toMatchObject({ code: 'disposed' });
+});
diff --git a/packages/agent-bundle/tests/check-declaration-imports.test.ts b/packages/agent-bundle/tests/check-declaration-imports.test.ts
index c75bc1d00..014d35f39 100644
--- a/packages/agent-bundle/tests/check-declaration-imports.test.ts
+++ b/packages/agent-bundle/tests/check-declaration-imports.test.ts
@@ -167,6 +167,30 @@ describe('declarationImportViolations', () => {
     }]);
   });
 
+  it('treats the browser App declaration as a strict public root', () => {
+    const report = declarationImportViolations({
+      manifest: {
+        name: 'agent-bundle',
+        devDependencies: { zod: '4.5.4' },
+        exports: { './app': { types: './dist/app.d.ts', import: './dist/app.js' } },
+      },
+      packedPaths: ['dist/app.d.ts', 'dist/app.js'],
+      declarations: [{
+        path: 'dist/app.d.ts',
+        text: "import type { z } from 'zod';\nexport type BrowserContract = z.ZodType;\n",
+      }],
+    });
+
+    expect(report.errors).toEqual([expect.objectContaining({
+      path: 'dist/app.d.ts',
+      reachableFrom: './app',
+      reason: 'dev-dependency',
+      specifier: 'zod',
+    })]);
+    expect(report.warnings).toEqual([]);
+    expect(report.roots).toEqual([{ entry: './app', path: 'dist/app.d.ts' }]);
+  });
+
   it('follows `#` imports mapped to packed files when computing reachability', () => {
     const report = declarationImportViolations({
       manifest: { ...manifest, imports: { '#events/*': './dist/events/*.js' } },
diff --git a/packages/agent-bundle/tests/mcp-apps-compile.test.ts b/packages/agent-bundle/tests/mcp-apps-compile.test.ts
index 8df2928fd..5666bbff2 100644
--- a/packages/agent-bundle/tests/mcp-apps-compile.test.ts
+++ b/packages/agent-bundle/tests/mcp-apps-compile.test.ts
@@ -1,8 +1,9 @@
 import { mkdir, mkdtemp, readdir, readFile, realpath, rm, symlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 
 import { afterEach, describe, expect, it } from '@rstest/core';
+import { init, parse } from 'es-module-lexer';
 
 import { MCP_APP_HTML_ADVISORY_BYTES } from '../src/build/mcp-app-diagnostics.ts';
 import { compileMcpApps, composeMcpAppsRsbuildConfig, type McpAppCompileMode } from '../src/build/mcp-apps.ts';
@@ -10,7 +11,7 @@ import { DiagnosticError, type Diagnostic } from '../src/core/diagnostics.ts';
 import { MAX_APP_HTML_BYTES } from '../src/core/mcp-app-limits.ts';
 import type { AgentBundleToolsConfig, NormalizedMcpApp } from '../src/core/types.ts';
 import type { AgentBundleMeta } from '../src/meta.ts';
-import { workbenchNodeModules } from './helpers/workspace-paths.ts';
+import { agentBundlePackageRoot, workbenchNodeModules } from './helpers/workspace-paths.ts';
 
 const roots: string[] = [];
 
@@ -82,6 +83,33 @@ const compileFailure = async (promise: Promise<unknown>): Promise<readonly Diagn
 
 const compileErrorShape = { code: 'AB4770', severity: 'error' } as const;
 
+const runtimeImportGraph = async (
+  entry: string,
+): Promise<{ readonly externalSpecifiers: readonly string[]; readonly files: ReadonlyMap<string, string> }> => {
+  await init;
+  const files = new Map<string, string>();
+  const externalSpecifiers: string[] = [];
+  const queue = [entry];
+  while (queue.length > 0) {
+    const file = queue.shift()!;
+    if (files.has(file)) continue;
+    const source = await readFile(file, 'utf8');
+    files.set(file, source);
+    const [imports] = parse(source);
+    for (const record of imports) {
+      if (record.d === -2) continue;
+      if (record.n === undefined) {
+        externalSpecifiers.push('<non-literal dynamic import>');
+      } else if (record.n.startsWith('.')) {
+        queue.push(join(dirname(file), record.n));
+      } else {
+        externalSpecifiers.push(record.n);
+      }
+    }
+  }
+  return { externalSpecifiers: Object.freeze(externalSpecifiers), files };
+};
+
 const reactView = {
   'views/StatusPanel.tsx': 'export const Panel = () => <strong className="w">panel-ready</strong>;\n',
   'views/status.ts': [
@@ -93,6 +121,51 @@ const reactView = {
 };
 
 describe('compileMcpApps', () => {
+  it('bundles agent-bundle/app into one browser-only inline document', async () => {
+    const root = await createProject({
+      'views/status.ts': [
+        "import { createAppClient } from 'agent-bundle/app';",
+        "(globalThis as Record<string, unknown>)['createAppClient'] = createAppClient;",
+        '',
+      ].join('\n'),
+    });
+    await rm(join(root, 'node_modules'));
+    const graph = await runtimeImportGraph(join(agentBundlePackageRoot, 'dist', 'app.js'));
+    expect(graph.externalSpecifiers).toEqual([]);
+    expect([...graph.files.keys()]).toContain(join(agentBundlePackageRoot, 'dist', 'app.js'));
+    const runtimeBytes = [...graph.files.values()].join('\n');
+    const forbiddenRuntimeBytes = [
+      /\bnode:/u,
+      /["']effect(?:\/|["'])/u,
+      /["']zod(?:\/|["'])/u,
+      /typescript-5|source-map-support/u,
+      /mcp-server-runtime|mcp-schema-projection|mcp-tasks/u,
+      /routes\/framework-imports|routes\/public|build\/mcp-apps/u,
+    ];
+    expect(forbiddenRuntimeBytes.filter((pattern) => pattern.test(runtimeBytes))).toEqual([]);
+
+    const installedPackage = join(root, 'node_modules', 'agent-bundle');
+    await mkdir(installedPackage, { recursive: true });
+    await writeFile(join(installedPackage, 'package.json'), await readFile(join(agentBundlePackageRoot, 'package.json')));
+    for (const [file, source] of graph.files) {
+      const installedFile = join(installedPackage, relative(agentBundlePackageRoot, file));
+      await mkdir(dirname(installedFile), { recursive: true });
+      await writeFile(installedFile, source);
+    }
+
+    const { outDir, result } = await compile(root, [app(root)]);
+    const html = await emittedHtml(outDir);
+    expect(html).toContain('2026-01-26');
+    expect(result.apps[0]!.sourceInputs.filter((source) =>
+      /(?:^|\/)node_modules\/(?:effect|zod|typescript-5)(?:\/|$)|\/agent-bundle\/src\/(?:build|routes)\//u.test(source),
+    )).toEqual([]);
+    expect(await readdir(outDir)).toEqual(['mcp-apps']);
+    expect(await readdir(join(outDir, 'mcp-apps'))).toEqual(['status.html']);
+    expect(html).toMatch(/<script\b(?![^>]*\bsrc=)[^>]*>/u);
+    expect(html).not.toMatch(/<(?:script\b[^>]*\bsrc|link\b[^>]*\bhref)=?/u);
+    expect(forbiddenRuntimeBytes.filter((pattern) => pattern.test(html))).toEqual([]);
+  }, 60_000);
+
   it('compiles a .ts entry that imports a .tsx component to the automatic JSX runtime and measures the view', async () => {
     const root = await createProject(reactView);
     const { outDir, result } = await compile(root, [app(root)]);
diff --git a/packages/agent-bundle/tests/public-api.test.ts b/packages/agent-bundle/tests/public-api.test.ts
index 2f65ab57a..48f9b1e80 100644
--- a/packages/agent-bundle/tests/public-api.test.ts
+++ b/packages/agent-bundle/tests/public-api.test.ts
@@ -101,7 +101,8 @@ const producerFrom = async (output: string): Promise<{ readonly name: string; re
 
 it('keeps package output filenames stable', async () => {
   const config = (await import('../rslib.config.ts')).default;
-  expect(config).toMatchObject({ output: { filenameHash: false } });
+  expect(config).toMatchObject({ output: { filenameHash: false, target: 'node' } });
+  expect(config.output).not.toHaveProperty('autoExternal');
   expect(config.output).not.toHaveProperty('externals');
 });
 
@@ -191,6 +192,7 @@ it('exposes the dev.runtime.provider protocol from the advanced API (#485)', ()
 
 it('loads every public subpath and reports the package version', async () => {
   await expect(import('../src/api.ts')).resolves.toBeDefined();
+  await expect(import('../src/app/index.ts')).resolves.toBeDefined();
   await expect(import('../src/config/index.ts')).resolves.toBeDefined();
   await expect(import('../src/eval/index.ts')).resolves.toBeDefined();
   await expect(runCli(['--version'])).resolves.toBe(0);
@@ -216,6 +218,7 @@ it('publishes directly executable built entrypoints with declarations', async ()
 
   const rootEntrypoint = await import('agent-bundle');
   await expect(import('agent-bundle/api')).resolves.toBeDefined();
+  await expect(import('agent-bundle/app')).resolves.toBeDefined();
   const configEntrypoint = await import('agent-bundle/config');
   await expect(import('agent-bundle/eval')).resolves.toBeDefined();
   expect(configEntrypoint.defineConfig).toBe(rootEntrypoint.defineConfig);
diff --git a/packages/agent-bundle/tests/route-framework-imports.test.ts b/packages/agent-bundle/tests/route-framework-imports.test.ts
index 0a9dfc329..d5779b441 100644
--- a/packages/agent-bundle/tests/route-framework-imports.test.ts
+++ b/packages/agent-bundle/tests/route-framework-imports.test.ts
@@ -49,6 +49,7 @@ describe('compilerCarryingSpecifiers', () => {
 
   it('matches specifiers exactly and leaves bundle-safe entries and other packages alone', () => {
     const clean = scan(lines(
+      "import { createAppClient } from 'agent-bundle/app';",
       "import 'agent-bundle/routes';",
       "import { appResourceUri } from 'agent-bundle/routes';",
       "import { launchEnv } from 'agent-bundle/launch-env';",
@@ -58,7 +59,7 @@ describe('compilerCarryingSpecifiers', () => {
       "import { local } from './local';",
       "export * from 'agent-bundle/meta';",
       "const later = await import('agent-bundle/mcp-entry');",
-      'export default async () => [appResourceUri, launchEnv, spawnServeApp, deeper, z, local, later];',
+      'export default async () => [createAppClient, appResourceUri, launchEnv, spawnServeApp, deeper, z, local, later];',
     ));
     expect(clean).toEqual([]);
     expect(Object.isFrozen(clean)).toBe(true);
diff --git a/packages/agent-bundle/tests/route-graph.test.ts b/packages/agent-bundle/tests/route-graph.test.ts
index 6d19fcef3..4f2c205f6 100644
--- a/packages/agent-bundle/tests/route-graph.test.ts
+++ b/packages/agent-bundle/tests/route-graph.test.ts
@@ -12,7 +12,7 @@ import { discoverProject } from '../src/config/discover.ts';
 import type { AgentBundleConfig } from '../src/core/types.ts';
 import { compileRouteGraph, emptyCompiledRouteGraph, isEmptyRouteGraph } from '../src/routes/graph.ts';
 import * as routesModule from '../src/routes/index.ts';
-import { emptyRouteConfig, type CompiledRouteGraph } from '../src/routes/types.ts';
+import { emptyRouteConfig, type CompiledAgentRoute, type CompiledRouteGraph } from '../src/routes/types.ts';
 
 const roots: string[] = [];
 
@@ -1350,6 +1350,105 @@ it('generates deterministic route-specific types from the compiled graph', () =>
   expect(first).not.toContain('AgentBundleProviders');
   expect(first).not.toContain('AgentProviderValues');
   expect(first).toContain("declare module '@agent-bundle/runtime' {\n  interface Register {\n    readonly routes: AgentBundleRouteContracts;\n  }\n}");
+  // The App contract map is the MCP tool subset of the same registration, filtered at the type level so every
+  // route id is spelled once; its one `agent-bundle/app` augmentation registers it on `AppRegister` (#594).
+  expect(first).toContain('export type AgentBundleAppRouteContracts = {\n  readonly [Id in Extract<RouteId, `tool:${string}/${string}`>]: Readonly<{ input: RouteInput<Id>; result: RouteResult<Id> }>;\n};');
+  expect(first).toContain('/** The MCP tool route ids: the routes an MCP App calls through `agent-bundle/app`. */\nexport type AppToolRouteId = keyof AgentBundleAppRouteContracts;');
+  expect(first).toContain("declare module 'agent-bundle/app' {\n  interface AppRegister {\n    readonly routes: AgentBundleAppRouteContracts;\n  }\n}");
+  expect(first.match(/declare module 'agent-bundle\/app'/gu)).toHaveLength(1);
+  expect(first.match(/declare module '@agent-bundle\/runtime'/gu)).toHaveLength(1);
+  expect(first.match(/"tool:curator\/inspect"/gu)).toHaveLength(1);
+  expect(first.match(/"event:workspace\/open"/gu)).toHaveLength(1);
+  // Declarations only: every import is type-only, so nothing here reaches an App bundle at runtime.
+  expect(first.split('\n').filter((line) => line.startsWith('import'))).toEqual([
+    'import type * as route0 from "../src/events/workspace/open.js";',
+    'import type * as route1 from "../src/mcp/curator/tools/inspect.js";',
+  ]);
+  expect(first).not.toMatch(/from ["'](?:zod|node:|agent-bundle|@agent-bundle)/u);
+});
+
+it('omits the App registration for graphs without an MCP tool route', () => {
+  const server = (routes: readonly CompiledAgentRoute[]): CompiledRouteGraph['servers'] => [{
+    id: 'mcp:curator',
+    mode: 'generated',
+    name: 'curator',
+    routes,
+  }];
+  const mcpRoute = (kind: 'app' | 'prompt' | 'resource' | 'tool', collection: string, name: string): CompiledAgentRoute => ({
+    config: emptyRouteConfig,
+    id: `${kind}:curator/${name}`,
+    kind,
+    provenance: { kind: 'conventional', relativePath: `src/mcp/curator/${collection}/${name}.ts` },
+    serverId: 'mcp:curator',
+    source: `/workspace/project/src/mcp/curator/${collection}/${name}.ts`,
+  });
+  // Every executable route kind but a tool: CLI commands, event routes, prompts, resources, plus an App
+  // route (never typed) and a provider.
+  const toolFree: CompiledRouteGraph = {
+    cli: {
+      mode: 'generated',
+      routes: [{
+        config: emptyRouteConfig,
+        id: 'cli:report',
+        kind: 'cli',
+        provenance: { kind: 'conventional', relativePath: 'src/cli/report.ts' },
+        source: '/workspace/project/src/cli/report.ts',
+      }],
+    },
+    diagnostics: [],
+    digest: 'tool-free-typegen-digest',
+    events: [{
+      config: emptyRouteConfig,
+      event: 'workspace/open',
+      id: 'event:workspace/open',
+      kind: 'event-route',
+      provenance: { kind: 'conventional', relativePath: 'src/events/workspace/open.tsx' },
+      source: '/workspace/project/src/events/workspace/open.tsx',
+    }],
+    providers: [{
+      id: 'provider:git-worktree',
+      name: 'git-worktree',
+      provenance: { kind: 'conventional', relativePath: 'src/providers/git-worktree.ts' },
+      source: '/workspace/project/src/providers/git-worktree.ts',
+    }],
+    scripts: [],
+    servers: server([
+      mcpRoute('app', 'apps', 'dashboard'),
+      mcpRoute('prompt', 'prompts', 'brief'),
+      mcpRoute('resource', 'resources', 'catalog'),
+    ]),
+  };
+
+  const declarations = routesModule.generateRouteTypes(toolFree);
+  expect(routesModule.generateRouteTypes(structuredClone(toolFree))).toBe(declarations);
+  // The harness registration and provider surface are unchanged by the absence of tools...
+  expect(declarations).toContain('"cli:report": RouteContract<typeof route0.inputSchema, typeof route0.resultSchema>;');
+  expect(declarations).toContain('"event:workspace/open": EventRouteContract<typeof route1.default, "workspace/open">;');
+  expect(declarations).toContain('"prompt:curator/brief": RouteContract<typeof route2.inputSchema, typeof route2.resultSchema>;');
+  expect(declarations).toContain('"resource:curator/catalog": RouteContract<typeof route3.inputSchema, typeof route3.resultSchema>;');
+  expect(declarations).not.toContain('app:curator/dashboard');
+  expect(declarations).toContain("declare module '@agent-bundle/runtime' {\n  interface Register {\n    readonly routes: AgentBundleRouteContracts;\n  }\n  interface AgentProviderValues {\n    readonly \"gitWorktree\": ProviderValueOf<typeof provider0.default>;\n  }\n}");
+  // ...while nothing registers on `agent-bundle/app`: none of these routes is a `tools/call` target.
+  expect(declarations).not.toContain('agent-bundle/app');
+  expect(declarations).not.toContain('AppRegister');
+  expect(declarations).not.toContain('AgentBundleAppRouteContracts');
+  expect(declarations).not.toContain('AppToolRouteId');
+  expect(declarations.endsWith('}\n')).toBe(true);
+
+  // One tool beside them brings the map and exactly one augmentation, whatever else the graph holds.
+  const withTool: CompiledRouteGraph = {
+    ...toolFree,
+    servers: server([...toolFree.servers[0]!.routes, mcpRoute('tool', 'tools', 'inspect')]),
+  };
+  const registered = routesModule.generateRouteTypes(withTool);
+  expect(registered.match(/declare module 'agent-bundle\/app'/gu)).toHaveLength(1);
+  expect(registered.match(/"tool:curator\/inspect"/gu)).toHaveLength(1);
+  expect(registered.match(/"prompt:curator\/brief"/gu)).toHaveLength(1);
+  expect(registered).toContain('export type AgentBundleAppRouteContracts = {\n  readonly [Id in Extract<RouteId, `tool:${string}/${string}`>]: Readonly<{ input: RouteInput<Id>; result: RouteResult<Id> }>;\n};');
+  // The runtime augmentation is byte-identical with and without the App registration.
+  const runtimeBlock = /declare module '@agent-bundle\/runtime' \{[\s\S]*?\n\}\n/u;
+  expect(registered.match(runtimeBlock)?.[0]).toBe(declarations.match(runtimeBlock)?.[0]);
+  expect(registered.indexOf("declare module '@agent-bundle/runtime'")).toBeLessThan(registered.indexOf("declare module 'agent-bundle/app'"));
 });
 
 it('generates provider declarations and the runtime augmentation in execution order', () => {
@@ -1404,7 +1503,7 @@ it('generates provider declarations and the runtime augmentation in execution or
   expect(first.indexOf('AgentBundleRoutes')).toBeLessThan(first.indexOf('AgentBundleProviders'));
 });
 
-it('resolves generated helper types for schema and event route contracts', async () => {
+it('resolves generated helper types for schema and event route contracts and the App tool registration', async () => {
   const root = await createRoot();
   await writeTree(root, {
     'package.json': '{"type":"module"}\n',
@@ -1420,6 +1519,14 @@ it('resolves generated helper types for schema and event route contracts', async
       '}',
       '',
     ].join('\n'),
+    'src/mcp/curator/prompts/brief.ts': [
+      'export interface BriefInput { readonly topic: string; }',
+      'export interface BriefResult { readonly messages: readonly string[]; }',
+      'export const inputSchema = {} as { readonly _output: BriefInput };',
+      'export const resultSchema = {} as { readonly _output: BriefResult };',
+      'export default async function Brief() { return undefined; }',
+      '',
+    ].join('\n'),
     'src/mcp/curator/tools/inspect.ts': [
       'export interface InspectInput { readonly source: string; }',
       'export interface InspectResult { readonly accepted: boolean; }',
@@ -1432,49 +1539,101 @@ it('resolves generated helper types for schema and event route contracts', async
 
   const graph = await compileRouteGraph(root, fixtureConfig());
   expect(graph.diagnostics).toEqual([]);
+  // The same project without its tool: the App registration must vanish with it while everything else stays.
+  const toolFree: CompiledRouteGraph = {
+    ...graph,
+    servers: graph.servers.map((server) => ({ ...server, routes: server.routes.filter((route) => route.kind !== 'tool') })),
+  };
+  const equalityHelpers = [
+    'type Equal<Left, Right> =',
+    '  (<Value>() => Value extends Left ? 1 : 2) extends',
+    '  (<Value>() => Value extends Right ? 1 : 2) ? true : false;',
+    'type Assert<Value extends true> = Value;',
+  ];
   await writeTree(root, {
     '.agent-bundle/routes.d.ts': routesModule.generateRouteTypes(graph),
-    // A stand-in for the runtime's empty `Register`, so the augmentation has a declaration to merge into.
+    // Published from a sibling directory so its `../src/...` imports resolve the same way.
+    'tool-free/routes.d.ts': routesModule.generateRouteTypes(toolFree),
+    // Stand-ins for the runtime's empty `Register` and `agent-bundle/app`'s empty `AppRegister`, so each
+    // augmentation has a declaration to merge into.
     'runtime-stub.d.ts': 'export interface Register {}\n',
+    'app-stub.d.ts': 'export interface AppRegister {}\n',
     'assertions.ts': [
       "import type { Register } from '@agent-bundle/runtime';",
-      "import type { RouteId, RouteInput, RouteResult } from './.agent-bundle/routes.js';",
+      "import type { AppRegister } from 'agent-bundle/app';",
+      "import type { AgentBundleAppRouteContracts, AppToolRouteId, RouteId, RouteInput, RouteResult } from './.agent-bundle/routes.js';",
       "import type { WorkspaceOpenInput, WorkspaceOpenResult } from './src/events/workspace/open.js';",
+      "import type { BriefInput, BriefResult } from './src/mcp/curator/prompts/brief.js';",
       "import type { InspectInput, InspectResult } from './src/mcp/curator/tools/inspect.js';",
       '',
-      'type Equal<Left, Right> =',
-      '  (<Value>() => Value extends Left ? 1 : 2) extends',
-      '  (<Value>() => Value extends Right ? 1 : 2) ? true : false;',
-      'type Assert<Value extends true> = Value;',
+      ...equalityHelpers,
       '',
+      "export type Ids = Assert<Equal<RouteId, 'event:workspace/open' | 'prompt:curator/brief' | 'tool:curator/inspect'>>;",
       "export type SchemaInput = Assert<Equal<RouteInput<'tool:curator/inspect'>, InspectInput>>;",
       "export type SchemaResult = Assert<Equal<RouteResult<'tool:curator/inspect'>, InspectResult>>;",
       "export type EventInput = Assert<Equal<RouteInput<'event:workspace/open'>, WorkspaceOpenInput>>;",
       "export type EventResult = Assert<Equal<RouteResult<'event:workspace/open'>, WorkspaceOpenResult>>;",
-      'export type AllInputs = Assert<Equal<RouteInput<RouteId>, InspectInput | WorkspaceOpenInput>>;',
-      'export type AllResults = Assert<Equal<RouteResult<RouteId>, InspectResult | WorkspaceOpenResult>>;',
+      'export type AllInputs = Assert<Equal<RouteInput<RouteId>, BriefInput | InspectInput | WorkspaceOpenInput>>;',
+      'export type AllResults = Assert<Equal<RouteResult<RouteId>, BriefResult | InspectResult | WorkspaceOpenResult>>;',
       '// The augmentation registers the same contracts on the runtime, keyed by route id.',
       "export type RegisteredIds = Assert<Equal<keyof Register['routes'], RouteId>>;",
       "export type RegisteredInspect = Assert<Equal<Register['routes']['tool:curator/inspect'], Readonly<{ input: InspectInput; result: InspectResult }>>>;",
       '// An event route registers the harness payload (props without the signal the harness injects) and no result.',
       "export type RegisteredEvent = Assert<Equal<Register['routes']['event:workspace/open'], Readonly<{ input: Omit<WorkspaceOpenInput, 'signal'>; result: undefined }>>>;",
       "export type RegisteredEventInput = Assert<Equal<keyof Register['routes']['event:workspace/open']['input'], 'canonical' | 'native'>>;",
+      '// The App registration is the MCP tool subset of the same contracts: the prompt and event routes are not',
+      '// `tools/call` targets, so an App client cannot name them; the tool keeps its own schema types.',
+      "export type AppIds = Assert<Equal<AppToolRouteId, 'tool:curator/inspect'>>;",
+      "export type AppRegisteredIds = Assert<Equal<keyof AppRegister['routes'], 'tool:curator/inspect'>>;",
+      "export type AppRegisteredContracts = Assert<Equal<AppRegister['routes'], AgentBundleAppRouteContracts>>;",
+      "export type AppRegisteredInspect = Assert<Equal<AppRegister['routes']['tool:curator/inspect'], Readonly<{ input: InspectInput; result: InspectResult }>>>;",
+      "export type AppRegisteredInput = Assert<Equal<AppRegister['routes'][AppToolRouteId]['input'], InspectInput>>;",
+      "export type AppRegisteredResult = Assert<Equal<AppRegister['routes'][AppToolRouteId]['result'], InspectResult>>;",
+      '',
+    ].join('\n'),
+    'wrong-app-id.ts': [
+      "import type { AppRegister } from 'agent-bundle/app';",
+      "export const prompt: keyof AppRegister['routes'] = 'prompt:curator/brief';",
+      '',
+    ].join('\n'),
+    'tool-free.ts': [
+      "import type { Register } from '@agent-bundle/runtime';",
+      "import type { AppRegister } from 'agent-bundle/app';",
+      "import type { RouteId } from './tool-free/routes.js';",
+      '',
+      ...equalityHelpers,
+      '',
+      "export type Ids = Assert<Equal<RouteId, 'event:workspace/open' | 'prompt:curator/brief'>>;",
+      "export type RegisteredIds = Assert<Equal<keyof Register['routes'], RouteId>>;",
+      '// Without a tool route the generated file registers nothing on `agent-bundle/app`: `AppRegister` stays empty.',
+      'export type NoAppRegistration = Assert<Equal<keyof AppRegister, never>>;',
       '',
     ].join('\n'),
   });
 
-  const program = ts.createProgram([join(root, 'assertions.ts')], {
-    module: ts.ModuleKind.NodeNext,
-    moduleResolution: ts.ModuleResolutionKind.NodeNext,
-    noEmit: true,
-    paths: { '@agent-bundle/runtime': [join(root, 'runtime-stub.d.ts')] },
-    skipLibCheck: false,
-    strict: true,
-    target: ts.ScriptTarget.ES2022,
-  });
-  const diagnostics = ts.getPreEmitDiagnostics(program)
-    .map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
-  expect(diagnostics).toEqual([]);
+  // `declarations` joins the program the way a project's `tsconfig.json` `include` would.
+  const typecheck = (entry: string, ...declarations: readonly string[]): readonly string[] => {
+    const program = ts.createProgram([entry, ...declarations].map((file) => join(root, file)), {
+      module: ts.ModuleKind.NodeNext,
+      moduleResolution: ts.ModuleResolutionKind.NodeNext,
+      noEmit: true,
+      paths: {
+        '@agent-bundle/runtime': [join(root, 'runtime-stub.d.ts')],
+        'agent-bundle/app': [join(root, 'app-stub.d.ts')],
+      },
+      skipLibCheck: false,
+      strict: true,
+      target: ts.ScriptTarget.ES2022,
+    });
+    return ts.getPreEmitDiagnostics(program)
+      .map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
+  };
+  expect(typecheck('assertions.ts')).toEqual([]);
+  // The rejection names the registered tool, not `never`, and admits no prompt id.
+  expect(typecheck('wrong-app-id.ts', '.agent-bundle/routes.d.ts')).toEqual([
+    'Type \'"prompt:curator/brief"\' is not assignable to type \'"tool:curator/inspect"\'.',
+  ]);
+  expect(typecheck('tool-free.ts', 'tool-free/routes.d.ts')).toEqual([]);
 });
 
 it('validates the single async route-module authoring contract statically', async () => {
diff --git a/packages/agent-bundle/tests/route-protocol-name.test.ts b/packages/agent-bundle/tests/route-protocol-name.test.ts
new file mode 100644
index 000000000..4becb506f
--- /dev/null
+++ b/packages/agent-bundle/tests/route-protocol-name.test.ts
@@ -0,0 +1,119 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { describe, expect, it } from '@rstest/core';
+
+import { layoutRouteName } from '../src/routes/layouts.ts';
+import {
+  mcpRouteProtocolKinds,
+  mcpRouteProtocolName,
+  parseMcpRouteProtocolId,
+  type McpRouteProtocolKind,
+} from '../src/routes/protocol-name.ts';
+
+const namesByKind = {
+  app: 'dashboard',
+  prompt: 'brief',
+  resource: 'notes',
+  tool: 'hauler_status',
+} as const satisfies Record<McpRouteProtocolKind, string>;
+
+describe('mcpRouteProtocolKinds', () => {
+  it('names every generated MCP route kind whose id is <kind>:<server>/<name>', () => {
+    expect([...mcpRouteProtocolKinds]).toEqual(['app', 'prompt', 'resource', 'tool']);
+    expect(Object.isFrozen(mcpRouteProtocolKinds)).toBe(true);
+  });
+});
+
+describe('parseMcpRouteProtocolId', () => {
+  it('parses every MCP kind into kind, server, and protocol name', () => {
+    for (const kind of mcpRouteProtocolKinds) {
+      expect(parseMcpRouteProtocolId(`${kind}:hauler/${namesByKind[kind]}`)).toEqual({
+        kind,
+        name: namesByKind[kind],
+        server: 'hauler',
+      });
+    }
+  });
+
+  it('accepts inner ".", "_", and "-" in both identity segments', () => {
+    expect(parseMcpRouteProtocolId('tool:notice-inbox/read_item.v2')).toEqual({
+      kind: 'tool',
+      name: 'read_item.v2',
+      server: 'notice-inbox',
+    });
+  });
+
+  it('accepts harness module-direct ids that keep a canonical shape', () => {
+    expect(parseMcpRouteProtocolId('tool:harness/echo (module)')).toEqual({
+      kind: 'tool',
+      name: 'echo (module)',
+      server: 'harness',
+    });
+  });
+
+  it('rejects missing, extra, or empty id segments', () => {
+    const rejected = [
+      '',
+      'inspect',
+      'tool:inspect',
+      'tool:/inspect',
+      'tool:hauler/',
+      'tool:hauler/inspect/extra',
+      'tool:mcp:hauler/inspect',
+      ':hauler/inspect',
+      'cli:library/audit',
+      'event:tool/after',
+      'script:tooling-summary',
+      'layout:mcp:hauler',
+      '(module passed to renderRoute)',
+    ];
+    for (const routeId of rejected) {
+      expect(parseMcpRouteProtocolId(routeId), routeId).toBeUndefined();
+    }
+  });
+});
+
+describe('mcpRouteProtocolName', () => {
+  it('derives the wire name for every MCP kind', () => {
+    for (const kind of mcpRouteProtocolKinds) {
+      expect(mcpRouteProtocolName(`${kind}:hauler/${namesByKind[kind]}`)).toBe(namesByKind[kind]);
+    }
+  });
+
+  it('derives reserved and hyphenated protocol names', () => {
+    expect(mcpRouteProtocolName('tool:curator/notice-inbox')).toBe('notice-inbox');
+    expect(mcpRouteProtocolName('app:curator/dashboard')).toBe('dashboard');
+  });
+
+  it('throws TypeError for a non-canonical id', () => {
+    expect(() => mcpRouteProtocolName('cli:library/audit')).toThrow(TypeError);
+    expect(() => mcpRouteProtocolName('tool:inspect')).toThrow(
+      'Expected a canonical MCP route id (<kind>:<server>/<name>); got "tool:inspect".',
+    );
+    expect(() => mcpRouteProtocolName('(module passed to renderRoute)')).toThrow(TypeError);
+  });
+});
+
+describe('layoutRouteName', () => {
+  it('uses the MCP protocol name for tool, resource, prompt, and app routes', () => {
+    expect(layoutRouteName({ id: 'tool:hauler/hauler_status', kind: 'tool' })).toBe('hauler_status');
+    expect(layoutRouteName({ id: 'resource:hauler/notes', kind: 'resource' })).toBe('notes');
+    expect(layoutRouteName({ id: 'prompt:hauler/brief', kind: 'prompt' })).toBe('brief');
+    expect(layoutRouteName({ id: 'app:hauler/dashboard', kind: 'app' })).toBe('dashboard');
+  });
+
+  it('keeps CLI, script, and event identity rules off the MCP helper', () => {
+    expect(layoutRouteName({ id: 'cli:library/audit', kind: 'cli' })).toBe('library audit');
+    expect(layoutRouteName({ id: 'script:tooling-summary', kind: 'script' })).toBe('tooling-summary');
+    expect(layoutRouteName({ id: 'event:tool/after', kind: 'event-route' })).toBe('tool/after');
+  });
+});
+
+it('is a zero-import browser-safe leaf', async () => {
+  const source = await readFile(
+    join(process.cwd(), 'packages/agent-bundle/src/routes/protocol-name.ts'),
+    'utf8',
+  );
+  expect(source).not.toMatch(/^import\b/mu);
+});
diff --git a/packages/agent-bundle/tests/route-register-typegen.test.ts b/packages/agent-bundle/tests/route-register-typegen.test.ts
index 97690be41..339cca46f 100644
--- a/packages/agent-bundle/tests/route-register-typegen.test.ts
+++ b/packages/agent-bundle/tests/route-register-typegen.test.ts
@@ -67,6 +67,9 @@ const registeredIds = [
  * `expectMcpCall` — narrows its id or name, `input`, and `result` from the
  * route modules' own schemas with no per-route declaration file — and the
  * same program without the generated file degrades to `string` / `unknown`.
+ * The same file registers the tool subset on `agent-bundle/app`'s
+ * `AppRegister` (#594), which is what `createAppClient().call` narrows from;
+ * without it `AppRegister` stays empty.
  */
 it('types every route-aware public surface from the generated route registration', { timeout: 60_000 }, async () => {
   const root = await mkdtemp(join(tmpdir(), 'agent-bundle-route-register-'));
@@ -135,6 +138,7 @@ it('types every route-aware public surface from the generated route registration
     ].join('\n')),
     writeProjectFile(root, 'assertions.ts', [
       "import type { AgentEventCanonicalIdentity, AgentEventNativePayload, AgentEventPayload } from 'agent-bundle';",
+      "import type { AppRegister } from 'agent-bundle/app';",
       "import { expectMcpCall, expectNoMcpCall } from 'agent-bundle/eval';",
       'import type {',
       '  RegisteredMcpRouteId,',
@@ -187,6 +191,14 @@ it('types every route-aware public surface from the generated route registration
       "export type FindWireInput = Assert<Equal<McpRouteInput<'find', 'tool'>, { query: string } | { isbn: string }>>;",
       "export type ShelfFindWireInput = Assert<Equal<McpRouteInput<'find', 'tool', 'shelf'>, { isbn: string }>>;",
       "export type DynamicWireInput = Assert<Equal<McpRouteInput<string, 'tool'>, unknown>>;",
+      '// The same file registers the MCP tool subset on `agent-bundle/app` (#594): the ids an App client may call,',
+      '// each with its own schema-inferred `{ input, result }`; the CLI, event, and prompt routes are not among them.',
+      `export type AppIds = Assert<Equal<keyof AppRegister['routes'], ${registeredIds.filter((id) => id.startsWith('tool:')).map((id) => `'${id}'`).join(' | ')}>>;`,
+      "export type AppFind = Assert<Equal<AppRegister['routes']['tool:curator/find'], Readonly<{ input: { query: string }; result: { hits: number } }>>>;",
+      "export type AppShelfFind = Assert<Equal<AppRegister['routes']['tool:shelf/find'], Readonly<{ input: { isbn: string }; result: { shelved: boolean } }>>>;",
+      '// Both registrations read the same schemas, so an App call and the harness agree on a tool\'s contract.',
+      "export type AppStatusInput = Assert<Equal<AppRegister['routes']['tool:curator/status']['input'], RegisteredRouteInput<'tool:curator/status'>>>;",
+      "export type AppStatusResult = Assert<Equal<AppRegister['routes']['tool:curator/status']['result'], RegisteredRouteResult<'tool:curator/status'>>>;",
       '',
       "export const typed = async (canonical: AgentEventCanonicalIdentity<'tool/after'>, native: AgentEventNativePayload): Promise<void> => {",
       "  const found = await renderRoute('tool:curator/find', { input: { query: 'dune' } });",
@@ -254,6 +266,11 @@ it('types every route-aware public surface from the generated route registration
       '};',
       '',
     ].join('\n')),
+    writeProjectFile(root, 'wrong-app-id.ts', [
+      "import type { AppRegister } from 'agent-bundle/app';",
+      "export const prompt: keyof AppRegister['routes'] = 'prompt:curator/brief';",
+      '',
+    ].join('\n')),
     writeProjectFile(root, 'wrong-tool-name.ts', [
       "import { invokeMcpTool } from 'agent-bundle/test';",
       "export const missing = invokeMcpTool('missing');",
@@ -346,14 +363,17 @@ it('types every route-aware public surface from the generated route registration
       '',
     ].join('\n')),
     writeProjectFile(root, 'unregistered.ts', [
+      "import type { AppRegister } from 'agent-bundle/app';",
       "import { expectMcpCall } from 'agent-bundle/eval';",
       "import type { RegisteredMcpRouteName, RegisteredMcpServerName, RegisteredRouteId, RegisteredRouteResult } from '@agent-bundle/runtime';",
       "import { getMcpPrompt, invokeCli, invokeMcpTool, renderRoute, runContractMatrix, type McpRouteInput } from 'agent-bundle/test';",
       '',
       ...equalityHelpers,
       '',
-      '// Without the generated file in the program, ids and names are string and contracts are unknown.',
+      '// Without the generated file in the program, ids and names are string, contracts are unknown, and',
+      '// `agent-bundle/app` has no registration at all.',
       'export type Ids = Assert<Equal<RegisteredRouteId, string>>;',
+      'export type NoAppRoutes = Assert<Equal<keyof AppRegister, never>>;',
       "export type Result = Assert<Equal<RegisteredRouteResult<'tool:curator/find'>, unknown>>;",
       'export type Servers = Assert<Equal<RegisteredMcpServerName, string>>;',
       "export type ToolNames = Assert<Equal<RegisteredMcpRouteName<'tool'>, string>>;",
@@ -373,8 +393,20 @@ it('types every route-aware public surface from the generated route registration
   expect(result.state).toBe('ready');
   const declarations = await readFile(join(root, '.agent-bundle', 'routes.d.ts'), 'utf8');
   expect(declarations).toContain("declare module '@agent-bundle/runtime' {\n  interface Register {\n    readonly routes: AgentBundleRouteContracts;\n  }\n}");
+  // One App augmentation beside it, registering the type-level tool subset: no route id is spelled twice.
+  expect(declarations).toContain("declare module 'agent-bundle/app' {\n  interface AppRegister {\n    readonly routes: AgentBundleAppRouteContracts;\n  }\n}");
+  expect(declarations.match(/declare module 'agent-bundle\/app'/gu)).toHaveLength(1);
+  for (const id of registeredIds) {
+    expect(declarations.match(new RegExp(`"${id}"`, 'gu')), id).toHaveLength(1);
+  }
+  // Declarations only: the file's imports are all type-only, so it can never pull a route module or Zod into an App bundle.
+  expect(declarations.split('\n').filter((line) => line.startsWith('import')).every((line) => line.startsWith('import type * as '))).toBe(true);
 
   expect(typecheck(root, 'assertions.ts', true)).toEqual([]);
+  // An App client's route id is checked against the registered tools only, naming them, not `never`.
+  const wrongAppId = typecheck(root, 'wrong-app-id.ts', true);
+  expect(wrongAppId).toHaveLength(1);
+  expect(wrongAppId[0]).toContain(`Type '"prompt:curator/brief"' is not assignable to type '${registeredIds.filter((id) => id.startsWith('tool:')).map((id) => `"${id}"`).join(' | ')}'`);
   const wrongId = typecheck(root, 'wrong-id.ts', true);
   expect(wrongId).toHaveLength(1);
   // The rejection names the registered ids, not `never`.
diff --git a/packages/agent-bundle/tests/route-typegen-write.test.ts b/packages/agent-bundle/tests/route-typegen-write.test.ts
index 132e54113..851e9e025 100644
--- a/packages/agent-bundle/tests/route-typegen-write.test.ts
+++ b/packages/agent-bundle/tests/route-typegen-write.test.ts
@@ -55,6 +55,47 @@ describe('writeRouteTypes', () => {
     expect(await readdir(join(root, '.agent-bundle'))).toEqual(['routes.d.ts']);
   });
 
+  it('publishes declarations only, registering the App tool subset exactly when a tool route exists', async () => {
+    const root = await scratchRoot();
+    await writeRouteTypes(root, oneRouteGraph(root));
+    const withTool = await readFile(join(root, routeTypesRelativePath), 'utf8');
+    // Every import is type-only, so the published file can never load a route module, Zod, or Node.
+    expect(withTool.split('\n').filter((line) => line.startsWith('import'))).toEqual([
+      'import type * as route0 from "../src/mcp/curator/tools/inspect.js";',
+    ]);
+    expect(withTool).toContain("declare module '@agent-bundle/runtime' {\n  interface Register {\n    readonly routes: AgentBundleRouteContracts;\n  }\n}");
+    expect(withTool).toContain("declare module 'agent-bundle/app' {\n  interface AppRegister {\n    readonly routes: AgentBundleAppRouteContracts;\n  }\n}");
+    expect(withTool.match(/declare module 'agent-bundle\/app'/gu)).toHaveLength(1);
+    expect(withTool.match(/"tool:curator\/inspect"/gu)).toHaveLength(1);
+
+    // A prompt is executable, so the file stays published, but it is not a `tools/call` target: the App
+    // registration is gone while the runtime registration remains.
+    const promptOnly: CompiledRouteGraph = {
+      ...emptyCompiledRouteGraph,
+      servers: [{
+        id: 'mcp:curator',
+        mode: 'generated',
+        name: 'curator',
+        routes: [{
+          config: {},
+          id: 'prompt:curator/brief',
+          kind: 'prompt',
+          provenance: { kind: 'conventional', relativePath: 'src/mcp/curator/prompts/brief.ts' },
+          serverId: 'mcp:curator',
+          source: join(root, 'src/mcp/curator/prompts/brief.ts'),
+        }],
+      }],
+    };
+    await expect(writeRouteTypes(root, promptOnly)).resolves.toBe(routeTypesRelativePath);
+    const withoutTool = await readFile(join(root, routeTypesRelativePath), 'utf8');
+    expect(withoutTool).toBe(generateRouteTypes(promptOnly));
+    expect(withoutTool).toContain('"prompt:curator/brief": RouteContract<typeof route0.inputSchema, typeof route0.resultSchema>;');
+    expect(withoutTool).toContain("declare module '@agent-bundle/runtime'");
+    expect(withoutTool).not.toContain('agent-bundle/app');
+    expect(withoutTool).not.toContain('AgentBundleAppRouteContracts');
+    expect(await readdir(join(root, '.agent-bundle'))).toEqual(['routes.d.ts']);
+  });
+
   it('removes a stale declaration file when the graph has nothing to type', async () => {
     const root = await scratchRoot();
     await writeRouteTypes(root, oneRouteGraph(root));
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index f7158a67d..49c2df6bb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -129,9 +129,6 @@ importers:
 
   examples/mcp-app:
     devDependencies:
-      '@modelcontextprotocol/ext-apps':
-        specifier: 1.7.5
-        version: 1.7.5(@modelcontextprotocol/sdk@1.30.0(supports-color@7.2.0)(zod@4.5.4))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.5.4)
       '@modelcontextprotocol/server':
         specifier: 2.0.0
         version: 2.0.0
diff --git a/website/docs/en/examples/mcp-app.mdx b/website/docs/en/examples/mcp-app.mdx
index 1cb5db9f8..5dd9b1b98 100644
--- a/website/docs/en/examples/mcp-app.mdx
+++ b/website/docs/en/examples/mcp-app.mdx
@@ -12,8 +12,8 @@ to see how the surfaces fit together instead of studying one of them alone.
 - **Run from the repository root:** `pnpm example:mcp-app`
 - **Package:** `@agent-bundle-example/mcp-app`
 - **Public dependencies:** `agent-bundle` (`workspace:*`), `@modelcontextprotocol/server`,
-  `@modelcontextprotocol/ext-apps`, `zod`; `@rstest/browser`, `@rstest/core`,
-  `@rstest/playwright`, and `playwright` for the browser-app test
+  `zod`; `@rstest/browser`, `@rstest/core`, `@rstest/playwright`, and `playwright` for the
+  browser-app test
 - **Targets:** `portable`, `codex`, `claude` — the MCP App resource stays portable
 - **Credentials:** none — the eval and the fixture check read only checked-in data
 - **Source:** [`examples/mcp-app`](https://github.com/ScriptedAlchemy/agent-bundle/tree/main/examples/mcp-app)
@@ -37,6 +37,15 @@ to see how the surfaces fit together instead of studying one of them alone.
   mounts the production-compiled App HTML over the product bridge through
   `agent-bundle/test/browser` — the `browser-app` level in
   [Testing](../guide/development/testing.mdx).
+- **The App is a client of the bridge, not a transport of its own.** `views/status-panel.ts`
+  creates its client with `createAppClient` from `agent-bundle/app`, receives the opening
+  `show-status` input and structured result through `onToolInput` / `onToolResult`, refreshes
+  through `call('tool:status/refresh-status', …)`, and reads the readiness policy through
+  `request('resources/read', …)`. The `status` server is handwritten, so no generated route
+  contracts exist; the view types its two tools itself with a structural `AppRegister`
+  augmentation. No JSON-RPC ids, pending maps, `postMessage('*')`, or `structuredContent`
+  unwrapping remain in the view. See
+  [The typed App client](../guide/authoring/mcp.mdx#the-typed-app-client).
 
 ## What is authored
 
diff --git a/website/docs/en/guide/authoring/mcp.mdx b/website/docs/en/guide/authoring/mcp.mdx
index 79645850b..fe21c2c8e 100644
--- a/website/docs/en/guide/authoring/mcp.mdx
+++ b/website/docs/en/guide/authoring/mcp.mdx
@@ -744,15 +744,125 @@ a `.ts` entry as behind a `.tsx` one — never to a `React.createElement` call t
 `React` import in scope. JSX syntax itself still belongs in `.tsx`/`.jsx` files, because the
 bundler detects a module's syntax from its extension.
 
+### The typed App client
+
+A view talks to its host through `agent-bundle/app`, a browser-safe leaf of the package that
+imports no Zod, Node built-in, Effect, or compiler code. `createAppClient()` owns the MCP Apps
+handshake, request ids, pending requests, timeouts and cancellation, JSON-RPC and result-envelope
+decoding, and the parent-window transport, so a view never hand-writes a `postMessage` frame or a
+`structuredContent` reader:
+
+```ts
+// src/mcp/hauler/apps/dashboard.ts
+import { createAppClient } from 'agent-bundle/app';
+
+const client = createAppClient({
+  appInfo: { name: 'hauler-dashboard', version: '1' },
+  timeoutMs: 15_000,
+});
+
+await client.connect();
+// The route's structured result object, typed from its `resultSchema`.
+const status = await client.call('tool:hauler/hauler_status', { limit: 40 });
+
+const stop = client.onToolResult('tool:hauler/hauler_status', (opening) => { /* typed */ });
+client.onToolInput('tool:hauler/hauler_status', (input) => { /* typed */ });
+client.onToolCancelled(({ reason }) => { /* the opening call ended without a result */ });
+
+stop();
+client.dispose();
+```
+
+**Route ids and types.** A tool is addressed by its route id, `tool:<server>/<name>`. The client
+derives the wire tool name from the final segment, exactly as the generated server does, and any
+other shape is a `TypeError`. The types come from the compiler: when the route graph has at least
+one tool route, the generated `.agent-bundle/routes.d.ts` adds exactly one augmentation on
+`agent-bundle/app`,
+
+```ts
+declare module 'agent-bundle/app' {
+  interface AppRegister {
+    readonly routes: AgentBundleAppRouteContracts;
+  }
+}
+```
+
+whose members are the project's generated MCP **tool** routes (`AppToolRouteId` in the same
+file) — `input` inferred from each route's `inputSchema`, `result` from its `resultSchema`. Once
+that file is in the project's TypeScript program (the templates list `".agent-bundle/routes.d.ts"`
+in `tsconfig.json` `include`; `AB4834` when a routed project leaves it out), a literal route id is
+checked against the compiled tools, `input` is typed from that route, and the result is that
+route's structured object. The declaration imports the route modules type-only, so no route
+module, schema, or server code enters the App document. Without the augmentation — a handwritten
+server, or a program that omits the file — `call()` still works with `unknown` input and result,
+and a view may declare its own contract map through the same `AppRegister` seam, as the
+[MCP App example](../../examples/mcp-app.mdx) does for its handwritten `status` server.
+`AppRouteId`, `AppRouteInput<Id>`, and `AppRouteResult<Id>` name the same surface for wrappers.
+
+**Calls and results.** `call()` returns the structured result **directly**; the MCP `content`,
+`_meta`, and `isError` envelope is transport data. It rejects with an `AppClientError` when the
+tool result carries `isError: true` (`code: 'rpc'`, the whole result on `error.data`), has no
+object `structuredContent`, or is not a well-formed result (`invalid-message`). This matches the
+generated MCP projection: only an object-rooted `resultSchema` produces `structuredContent`, so a
+scalar or array result is not a typed App call. `request(method, params?)` is the lower-level
+escape hatch for `resources/read` and the `ui/*` methods the host supports, resolving to the
+JSON-RPC result as is. Both connect first when `connect()` has not been awaited. Every request
+takes `{ signal, timeoutMs }`; the client default is 15 seconds (`timeoutMs` on
+`createAppClient`), and a request that times out or is aborted rejects with `timeout` or
+`aborted` and sends `notifications/cancelled` to the host.
+
+**Opening notifications.** `onToolInput` and `onToolResult` observe the tool call that opened the
+App (`ui/notifications/tool-input` and `ui/notifications/tool-result`); `onToolResult` delivers
+the decoded `structuredContent`, not the envelope. Those notifications name no tool — they are
+always the opening call — so the route id you register with supplies the payload type, not a
+filter. `onToolCancelled` reports the terminal `ui/notifications/tool-cancelled` with its optional
+`reason`. Each registration returns its unsubscribe function.
+
+**Errors.** One class, `AppClientError`, with a discriminated `code`: `timeout`, `aborted`,
+`disposed`, `connection-rebound`, `invalid-message`, `rpc`, `capability-unavailable`, or
+`consent-required`. A JSON-RPC error from the host maps by its code — `-32601` to
+`capability-unavailable`, `-32001` to `consent-required`, anything else to `rpc` — with `rpcCode`
+and `data` preserved. None of this is an `AB` diagnostic: App-side failures are browser errors,
+not build output.
+
+**Lifecycle and origin pinning.** The Workbench and `serve-app` render the App as an opaque,
+no-referrer `srcdoc` sandbox, so the document cannot know its host's origin up front. `connect()`
+therefore sends exactly one frame to `'*'` — the framework-owned `ui/initialize` — and accepts a
+response only from the configured parent window (`event.source`), with that request's id and a
+valid initialize result (protocol version `2026-01-26`, `hostInfo`, `hostCapabilities`,
+`hostContext`). It pins the responding `event.origin` (an opaque `null` origin is refused), sends
+`ui/notifications/initialized` and every later request to that exact origin, and ignores every
+message from any other source or origin. A host that can supply a trusted origin passes
+`targetOrigin` — an exact `http:`/`https:` origin; `'*'` is rejected — and no wildcard frame is
+sent at all. `connect()` is idempotent. `rebind({ parent?, targetOrigin?, window? })` rejects the
+previous generation's pending requests with `connection-rebound`, clears the pin, and performs the
+handshake again against the new parent. `dispose()`, also idempotent, removes the listener,
+rejects pending requests with `disposed`, and drops every registration; a host's
+`ui/resource-teardown` request is acknowledged and disposes the client. The transport is
+DOM-shaped rather than bound to the global `window`: `window` and `parent` are injectable, which
+is how tests and non-DOM hosts drive the same client.
+
+**The host-side boundary.** The client is the App-inside-the-iframe half of the bridge. The other
+half — the frame relay, sandbox proxy, host page, `/api/mcp/...` routes, and consent authority —
+belongs to the host: the Workbench MCP page, `agent-bundle serve-app`, an MCP host embedding the
+App, and the standalone production host of
+[#564](https://github.com/ScriptedAlchemy/agent-bundle/issues/564) all serve this one client over
+the same wire contract (`McpAppBridge`), and the host, never the App, decides which server a call
+reaches and which capabilities need consent. An App reaches no foreground server or MCP backend
+except through its relay.
+
+`agent-bundle/app` is bundle-safe: it is not one of the compiler-carrying entries `AB4837`
+rejects, and the compiler inlines it into the App document from the installed package like any
+other dependency.
+
 ### Reserved specifiers win
 
 Your `tsconfig.json` `paths` work inside a view (`@lib/*`, `@/components/*`, and so on):
-Rsbuild hands them to the bundler as usual, where they resolve ahead of every alias. The one
-specifier that escapes them is `agent-bundle/meta`: the compiler rewrites that exact import to
-the generated identity module before resolution starts, so a `paths` mapping for
-`agent-bundle/meta` has no effect inside a compiled view — the framework's identity is what the
-App imports, in every build, with every tsconfig. The resolved-config assertion refuses a build
-where a `tools` hatch removed that rewrite.
+Rsbuild hands them to the bundler as usual, where they resolve ahead of every alias. The
+specifiers that escape them are `agent-bundle/meta` and `agent-bundle/app`: the compiler rewrites
+those exact imports before resolution starts, so a `paths` mapping cannot replace the generated
+identity or the framework's browser runtime. The resolved-config assertion refuses a build where
+a `tools` hatch removed either rewrite.
 
 ### Compile errors and size
 
@@ -777,14 +887,16 @@ the emitted size and its gzip size (`build.compiledMcpApps[].size.bytes` and `.g
 `--json`):
 
 ```text
-Built mcp-app-example to …/mcp-app-example/artifact
-MCP App status (portable): mcp-apps/status.html 427.1 KiB (102.1 KiB gzip)
+Built <plugin> to …/<plugin>/artifact
+MCP App <name> (<target>): mcp-apps/<name>.html <size> (<gzip size> gzip)
 ```
 
-That example is close to the floor. Any view that imports `@modelcontextprotocol/ext-apps`
-carries `zod` (v3 and v4), `@modelcontextprotocol/sdk`, `zod-to-json-schema`, and `ext-apps`
-itself — about 437 kB (104 kB gzip) before the first line of your own code — so a healthy view
-sits well under 1 MiB. A production build that emits 1 MiB or more reports the `AB4772`
+The figures are that build's own measurement, not a contract. A view that reaches its host
+through `agent-bundle/app` carries the framework's client and nothing else from the protocol
+stack; one that imports `@modelcontextprotocol/ext-apps` instead carries `zod` (v3 and v4),
+`@modelcontextprotocol/sdk`, `zod-to-json-schema`, and `ext-apps` itself — about 437 kB (104 kB
+gzip) before the first line of your own code — and even that view sits well under 1 MiB. A
+production build that emits 1 MiB or more reports the `AB4772`
 advisory naming the five largest modules; any build over 2 MiB reports it too, because 2 MiB is
 the bound above which the Workbench and `serve-app` hosts refuse the resource and the view stops
 rendering there. The thresholds are fixed; no config key moves them.
diff --git a/website/docs/en/guide/distribution/validation.mdx b/website/docs/en/guide/distribution/validation.mdx
index bd63e3d2d..f4011268e 100644
--- a/website/docs/en/guide/distribution/validation.mdx
+++ b/website/docs/en/guide/distribution/validation.mdx
@@ -45,8 +45,9 @@ them reaches through relative imports — that value-imports a compiler-carrying
 (`agent-bundle`, `agent-bundle/api`, `agent-bundle/config`, `agent-bundle/eval`,
 `agent-bundle/rstest`, `agent-bundle/test`, `agent-bundle/test/browser`) is reported as `AB4837`
 from `inspect`, `validate`, `build`, and `dev`, naming the file and the specifier, instead of
-failing inside the bundler; `import type` and imports used only as types are not reported, and a
-routed command that needs the framework serves an App through
+failing inside the bundler. The browser-safe `agent-bundle/app` carries no compiler and is not on
+that list, so a value import of it is never `AB4837`; `import type` and imports used only as types
+are not reported either, and a routed command that needs the framework serves an App through
 [`spawnServeApp`](../authoring/mcp.mdx#serving-an-app-standalone) instead.
 
 Every diagnostic is one structured record: a stable `AB` code, a severity, a message, and usually
diff --git a/website/docs/en/reference/api.mdx b/website/docs/en/reference/api.mdx
index 3f4423758..314f79860 100644
--- a/website/docs/en/reference/api.mdx
+++ b/website/docs/en/reference/api.mdx
@@ -15,6 +15,7 @@ Every public entry point is documented from its declarations:
 | --- | --- |
 | `agent-bundle` | The authoring and orchestration surface: `defineSkill`, `canonicalAgentEvents`, `startDevServer`, `runEvals`, `compareEvals`, the eval harness factories, and the artifact-manifest helpers. |
 | `agent-bundle/api` | The programmatic compiler: `build`, `validate`, `inspect`, `prepack`, their option and result types, the `AgentComponentKind` / `componentKindCapability` component-kind helpers, and the artifact operations `listMcp`, `invokeMcp`, `runMcp`, `serveApp` (a built MCP App served standalone in a browser — a host-process API for scripts and tests; a routed CLI command inside the artifact uses `spawnServeApp` from `agent-bundle/serve-app-command` instead, see [Serving an App standalone](../guide/authoring/mcp.mdx#serving-an-app-standalone)), `listHooks`, and `simulateHook`; plus the Rspack stats formatters `rspackStatsErrors`, `describeRspackStatsError`, and `formatRspackStatsError`, which render a compile error as the same `<file>:<line>:<column>: <message>` line the compiler's `AB4770` carries, for tools that drive their own Rsbuild compile. |
+| `agent-bundle/app` | The browser-safe MCP App client: `createAppClient`, the `AppClient` lifecycle (`connect`, `call`, `request`, `onToolInput`, `onToolResult`, `onToolCancelled`, `rebind`, `dispose`), `AppClientError` and its `code` union, the `AppRegister` interface the generated `.agent-bundle/routes.d.ts` augments with the project's `tool:<server>/<name>` contracts, `AppRouteId` / `AppRouteInput` / `AppRouteResult`, the injectable `AppWindow` / `AppMessageTarget` ports, and `APP_PROTOCOL_VERSION`. Imports nothing from Zod, Node, or the compiler; for App views only. |
 | `agent-bundle/config` | `defineConfig` and the configuration types. |
 | `agent-bundle/test` | The route-testing harness, matchers, and contract matrices. |
 | `agent-bundle/test/browser` | The MCP App bridge harness for browser-rendered views. |
@@ -47,5 +48,7 @@ this Reference — are complete translations.
 ## Where to start
 
 - Compiling from a script: `build` and `validate` in `agent-bundle/api`.
+- Calling typed tools from an MCP App: `createAppClient` in `agent-bundle/app`, explained in
+  [The typed App client](../guide/authoring/mcp.mdx#the-typed-app-client).
 - Writing tests: `renderRoute`, `expectDocument`, and the matrices in `agent-bundle/test`, explained in [Testing](../guide/development/testing.mdx).
 - Writing evals: `defineEvalSuite` and the assertions in `agent-bundle/eval`, explained in [Evaluations](../guide/development/evaluations.mdx).
diff --git a/website/docs/en/reference/security.mdx b/website/docs/en/reference/security.mdx
index 36d570c52..9ff4bbc0b 100644
--- a/website/docs/en/reference/security.mdx
+++ b/website/docs/en/reference/security.mdx
@@ -60,6 +60,23 @@ loopback origin inside the framework sandbox, and every App action still crosses
 authority as in the Workbench (`--allow` pre-approves named capabilities on the operator's behalf).
 It is a local preview host, not a deployment target.
 
+Inside the App document, the `agent-bundle/app` client trusts no arbitrary `postMessage` sender.
+The sandbox is an opaque, no-referrer `srcdoc`, so the document cannot know its host's origin
+before the first frame: `connect()` sends exactly one framework-owned `ui/initialize` request to
+`'*'`, accepts a response only from the configured parent window with that request's id and a
+valid initialize result, pins the responding origin — an opaque `null` origin is refused — and
+from then on sends to and accepts from that exact `source` and `origin` only. A host that can
+name its origin passes `targetOrigin` (an exact `http:`/`https:` origin; `'*'` is rejected) and no
+wildcard frame is ever sent. `rebind()` and `dispose()` revoke the pin and reject every request
+still pending, so a stale generation cannot receive a later host's messages. Author code has no
+wildcard send path.
+
+The host relay is the security boundary. The App client speaks only to its expected parent; the
+Workbench, `serve-app`, or an embedding MCP host forwards permitted requests to the one server the
+frame is bound to and applies its own authentication, capability, and consent policy. An App never
+reaches the foreground routes or an MCP backend around the relay, and the relay never merges in
+the permissions of another App, server, or browser origin.
+
 ## The Agent API
 
 The Agent API is off by default. When enabled it is an authenticated Streamable HTTP MCP endpoint
diff --git a/website/docs/zh/examples/mcp-app.mdx b/website/docs/zh/examples/mcp-app.mdx
index cc23f6499..462628df8 100644
--- a/website/docs/zh/examples/mcp-app.mdx
+++ b/website/docs/zh/examples/mcp-app.mdx
@@ -10,9 +10,8 @@ description: 'MCP App 示例：把一条服务就绪度工作流表达为生成
 
 - **在仓库根目录运行：** `pnpm example:mcp-app`
 - **包名：** `@agent-bundle-example/mcp-app`
-- **公开依赖：** `agent-bundle`（`workspace:*`）、`@modelcontextprotocol/server`、
-  `@modelcontextprotocol/ext-apps`、`zod`；浏览器端 App 测试还用到 `@rstest/browser`、`@rstest/core`、
-  `@rstest/playwright` 与 `playwright`
+- **公开依赖：** `agent-bundle`（`workspace:*`）、`@modelcontextprotocol/server`、`zod`；浏览器端 App
+  测试还用到 `@rstest/browser`、`@rstest/core`、`@rstest/playwright` 与 `playwright`
 - **Target：** `portable`、`codex`、`claude`——MCP App 资源仅保留在 portable
 - **凭据：** 不需要——eval 与夹具检查只读取签入的数据
 - **源码：** [`examples/mcp-app`](https://github.com/ScriptedAlchemy/agent-bundle/tree/main/examples/mcp-app)
@@ -32,6 +31,9 @@ description: 'MCP App 示例：把一条服务就绪度工作流表达为生成
 - **浏览器表面自成一个证明级别。** `tests/browser-app/status-panel.browser.test.ts` 通过
   `agent-bundle/test/browser` 把生产编译出的 App HTML 挂载到产品桥接之上——也就是
   [测试](../guide/development/testing.mdx)中的 `browser-app` 级别。
+- **App 使用生成的路由契约。** 状态面板从 `agent-bundle/app` 创建客户端，以
+  `tool:status/show-status` 调用同一条工具路由，并直接接收其带类型的结构化对象；它不再自行维护
+  `postMessage` transport 或解包 MCP 结果 envelope。
 
 ## 编写了什么
 
diff --git a/website/docs/zh/guide/authoring/mcp.mdx b/website/docs/zh/guide/authoring/mcp.mdx
index 576b881d3..028cc6ae4 100644
--- a/website/docs/zh/guide/authoring/mcp.mdx
+++ b/website/docs/zh/guide/authoring/mcp.mdx
@@ -664,13 +664,45 @@ refresh）的 `@rsbuild/plugin-react` 注册在每个 App 环境上，因此 `St
 有 `React` 导入的 `React.createElement` 调用。JSX 语法本身仍然只能写在 `.tsx`/`.jsx` 文件里，因为
 打包器按扩展名识别模块的语法。
 
+### 带类型的 App 客户端
+
+App 视图通过浏览器安全的 `agent-bundle/app` 入口调用自己的路由，不需要自行实现 JSON-RPC id、pending
+request、超时、结果 envelope 或 `window.parent.postMessage('*')`：
+
+```ts
+import { createAppClient } from 'agent-bundle/app';
+
+const client = createAppClient();
+await client.connect();
+
+const status = await client.call('tool:status/show-status', {
+  service: 'payments-api',
+});
+```
+
+编译器会在 `.agent-bundle/routes.d.ts` 中生成对 `AppRegister` 的 module augmentation。它从同一份
+Application IR 推导每个工具的输入与结构化输出，因此 App 只导入浏览器安全的声明与运行时，不会把服务器
+路由模块、Zod 或 Node 代码带进视图 bundle。工具路由 id 的规范形式是
+`tool:<server>/<name>`；上例中的 `status` 变量直接是该路由 `resultSchema` 所描述的对象，而不是要求
+App 再从 `structuredContent` 中解包的 MCP 结果 envelope。
+
+同一个客户端拥有宿主桥接的完整生命周期：`connect` 建立连接，`call` 调用已注册工具，`request` 发送
+受支持的桥接请求；`onToolInput`、`onToolResult` 与 `onToolCancelled` 监听包括开场调用在内的宿主
+notification，并各自返回移除 listener 的函数。`rebind` 在宿主换代后绑定新的 parent/origin，`dispose`
+则取消 pending 工作、移除 listener 并关闭客户端。
+
+连接、调用与能力失败会抛出 `AppClientError`，调用方可直接判断其稳定 `code`：`timeout`、`aborted`、
+`disposed`、`connection-rebound`、`invalid-message`、`rpc`、`capability-unavailable` 或
+`consent-required`，不需要解析错误文案。`agent-bundle/app` 不携带编译器，因此 App 中的值导入不会触发
+保护自包含可执行文件的 `AB4837`。
+
 ### 保留标识符优先
 
 你的 `tsconfig.json` `paths` 在视图内照常生效（`@lib/*`、`@/components/*` 等）：Rsbuild 会像往常
-一样把它们交给打包器，并在所有别名之前解析。唯一不受它们影响的标识符是 `agent-bundle/meta`：编译器
-会在解析开始之前就把这个精确的导入改写为生成的身份模块，因此针对 `agent-bundle/meta` 的 `paths`
-映射在编译出的视图内不起作用——无论哪次构建、无论哪份 tsconfig，App 导入的都是框架的身份模块。
-若某个 `tools` 逃生舱移除了这一改写，已解析配置断言会拒绝该构建。
+一样把它们交给打包器，并在所有别名之前解析。不受它们影响的标识符是 `agent-bundle/meta` 与
+`agent-bundle/app`：编译器会在解析开始之前改写这两个精确导入，因此 `paths` 映射既不能替换生成的
+身份模块，也不能替换框架的浏览器运行时。若某个 `tools` 逃生舱移除了任一改写，已解析配置断言会拒绝
+该构建。
 
 ### 编译错误与体积
 
@@ -689,14 +721,10 @@ MCP App "status" failed to compile: views/status.ts:1:10: Module build failed
 包括 `tsconfig.json` 问题那种不带位置的形式。
 
 成功的构建会在 `Built …` 之后为每个 App 打印一行，按 target 与 App 名称排序，给出输出体积及其
-gzip 体积（`--json` 中为 `build.compiledMcpApps[].size.bytes` 与 `.gzipBytes`）：
-
-```text
-Built mcp-app-example to …/mcp-app-example/artifact
-MCP App status (portable): mcp-apps/status.html 427.1 KiB (102.1 KiB gzip)
-```
+gzip 体积（`--json` 中为 `build.compiledMcpApps[].size.bytes` 与 `.gzipBytes`）。数字来自当次实际
+输出；不要把某次示例构建的体积当作固定契约。
 
-这个例子已接近下限。任何导入 `@modelcontextprotocol/ext-apps` 的视图都会带上 `zod`（v3 与 v4）、
+任何导入 `@modelcontextprotocol/ext-apps` 的视图都会带上 `zod`（v3 与 v4）、
 `@modelcontextprotocol/sdk`、`zod-to-json-schema` 以及 `ext-apps` 本身——在你写下第一行自己的代码
 之前就约有 437 kB（gzip 后 104 kB）——因此一个健康的视图远在 1 MiB 以下。生产构建的输出达到或超过
 1 MiB 时会报告 `AB4772` 建议性诊断并点名最大的五个模块；任何超过 2 MiB 的构建也会报告它，因为
diff --git a/website/docs/zh/guide/distribution/validation.mdx b/website/docs/zh/guide/distribution/validation.mdx
index 4cdad9f31..21f47711d 100644
--- a/website/docs/zh/guide/distribution/validation.mdx
+++ b/website/docs/zh/guide/distribution/validation.mdx
@@ -35,8 +35,10 @@ npx agent-bundle validate --artifact artifact --strict    # 已构建字节，
 路由模块、布局或 provider——或它们之一通过相对导入触达的模块——若值导入了携带编译器的框架入口
 （`agent-bundle`、`agent-bundle/api`、`agent-bundle/config`、`agent-bundle/eval`、`agent-bundle/rstest`、
 `agent-bundle/test`、`agent-bundle/test/browser`），会由 `inspect`、`validate`、`build` 与 `dev` 报告为
-`AB4837`，点名文件与说明符，而不是在打包器内部失败；`import type` 以及仅作为类型使用的导入不会被报告，
-需要框架的路由式命令则改为通过 [`spawnServeApp`](../authoring/mcp.mdx#独立提供-app) 提供 App。
+`AB4837`，点名文件与说明符，而不是在打包器内部失败。浏览器安全且不携带编译器的
+`agent-bundle/app` 不在这份列表中，值导入不会触发 `AB4837`。`import type` 以及仅作为类型使用的导入
+不会被报告，需要框架的路由式命令则改为通过
+[`spawnServeApp`](../authoring/mcp.mdx#独立提供-app) 提供 App。
 
 每条诊断都是一份结构化记录：稳定的 `AB` 代码、一个严重级别、一条消息，通常还有 `sourcePath` 与一条
 `recovery` 提示。由诊断把关的命令——`build`、`prepack`、`validate`、`doctor`、`install` 与 `dev`——只有
diff --git a/website/docs/zh/reference/api.mdx b/website/docs/zh/reference/api.mdx
index a2fde7f2b..b9440a452 100644
--- a/website/docs/zh/reference/api.mdx
+++ b/website/docs/zh/reference/api.mdx
@@ -14,6 +14,7 @@ description: '生成的 agent-bundle 类型 API：它覆盖哪些入口点、如
 | --- | --- |
 | `agent-bundle` | 编写与编排表面：`defineSkill`、`canonicalAgentEvents`、`startDevServer`、`runEvals`、`compareEvals`、eval harness 工厂，以及产物清单辅助函数。 |
 | `agent-bundle/api` | 程序化编译器：`build`、`validate`、`inspect`、`prepack`，及其选项与结果类型，`AgentComponentKind` / `componentKindCapability` 组件类型辅助，以及产物操作 `listMcp`、`invokeMcp`、`runMcp`、`serveApp`（在浏览器里独立提供一个已构建的 MCP App——面向脚本与测试的宿主进程 API；产物内部的路由式 CLI 命令则改用 `agent-bundle/serve-app-command` 中的 `spawnServeApp`，见[独立提供 App](../guide/authoring/mcp.mdx#独立提供-app)）、`listHooks` 与 `simulateHook`；另有 Rspack stats 格式化工具 `rspackStatsErrors`、`describeRspackStatsError` 与 `formatRspackStatsError`，把一条编译错误渲染成与编译器 `AB4770` 相同的 `<file>:<line>:<column>: <message>` 行，供自行驱动 Rsbuild 编译的工具使用。 |
+| `agent-bundle/app` | 浏览器安全且不携带编译器的 MCP App 客户端：`createAppClient`、`AppRegister`、`AppClientError`，以及 `connect`、`call`、`request`、`onToolInput`、`onToolResult`、`onToolCancelled`、`rebind` 与 `dispose` 生命周期。编译器通过 `.agent-bundle/routes.d.ts` augmentation 提供 `tool:<server>/<name>` 路由的输入与结构化输出类型。 |
 | `agent-bundle/config` | `defineConfig` 与配置类型。 |
 | `agent-bundle/test` | 路由测试 harness、匹配器与契约矩阵。 |
 | `agent-bundle/test/browser` | 面向浏览器渲染视图的 MCP App bridge harness。 |
@@ -41,5 +42,7 @@ description: '生成的 agent-bundle 类型 API：它覆盖哪些入口点、如
 ## 从哪里开始
 
 - 从脚本中编译：`agent-bundle/api` 中的 `build` 与 `validate`。
+- 在 MCP App 中调用带类型的工具：`agent-bundle/app` 中的 `createAppClient`，详见
+  [带类型的 App 客户端](../guide/authoring/mcp.mdx#带类型的-app-客户端)。
 - 编写测试：`agent-bundle/test` 中的 `renderRoute`、`expectDocument` 与那些矩阵，在[测试](../guide/development/testing.mdx)中介绍。
 - 编写 eval：`agent-bundle/eval` 中的 `defineEvalSuite` 与那些断言，在[评测](../guide/development/evaluations.mdx)中介绍。
diff --git a/website/docs/zh/reference/security.mdx b/website/docs/zh/reference/security.mdx
index 0840a7aab..de0b44431 100644
--- a/website/docs/zh/reference/security.mdx
+++ b/website/docs/zh/reference/security.mdx
@@ -49,6 +49,15 @@ Skill Markdown 中的原始 HTML、JSX/MDX 与 Mermaid 在 Workbench 渲染器
 检查；App 文档运行在框架沙箱内的第二个 loopback origin 上，并且每一个 App 动作仍与 Workbench 一样经过同一
 个同意授权（`--allow` 代操作者预先批准指定能力）。它是本地预览宿主，不是部署目标。
 
+`agent-bundle/app` 的浏览器传输也不会信任任意 `postMessage` 发送者。沙箱先以 opaque-origin `srcdoc`
+引导，因此框架只用通配目标发送第一次 `ui/initialize`；客户端仅接受预期 parent `Window` 以匹配请求 id
+返回的有效初始化响应，并从该响应固定明确的 `origin`。此后每条消息都必须同时匹配该 `source` 与
+`origin`。关闭或由 App 显式 `rebind` 会撤销旧 pin 并取消仍在等待的请求。
+
+这条桥接以宿主 relay 为安全边界：App 客户端只与预期 parent 通信；Workbench、`serve-app` 或嵌入式 MCP
+宿主负责把允许的请求转发到所绑定的那一个服务器，并继续执行各自的认证、能力与同意策略。App 不会绕过
+relay 直接访问前台路由或 MCP 后端，relay 也不会把另一个 App、服务器或浏览器 origin 的权限合并进来。
+
 ## Agent API
 
 Agent API 默认关闭。启用时，它是挂载在同一个 loopback 前台服务器 `/mcp` 路径上、经过认证的 Streamable
diff --git a/website/rspress.config.ts b/website/rspress.config.ts
index 48014aa69..b3e304e1f 100644
--- a/website/rspress.config.ts
+++ b/website/rspress.config.ts
@@ -22,6 +22,7 @@ const packageSource = path.join(repoRoot, 'packages', 'agent-bundle', 'src');
 const publicApiEntryPoints = [
   'index.ts',
   'api.ts',
+  'app/index.ts',
   'cli-entry.ts',
   'config/index.ts',
   'eval/index.ts',

From f83ef3f7b0f42612fbb01d811138498131ae5b10 Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Sat, 5 Sep 2026 07:18:37 +0000
Subject: [PATCH 2/5] fix: address typed App client review

---
 .changeset/typed-app-client.md                |   2 +-
 docs/entry-conventions.md                     | 163 ++++--
 .../browser-app/status-panel.browser.test.ts  | 115 +++-
 examples/mcp-app/views/status-panel.ts        |  34 +-
 packages/agent-bundle/README.md               |  19 +-
 packages/agent-bundle/src/app/index.ts        | 125 +++-
 packages/agent-bundle/src/build/cli-bins.ts   |   3 +-
 packages/agent-bundle/src/build/entries.ts    |   2 -
 .../agent-bundle/src/build/package-build.ts   |   2 +-
 .../src/contracts/mcp-app-protocol.ts         |   2 +
 .../src/dev/mcp-app-profile-descriptors.ts    |   3 +-
 .../dev/mcp-apps/mcp-app-binding-service.ts   |  40 +-
 .../src/dev/mcp-apps/mcp-app-bridge.ts        | 236 +++++---
 .../dev/mcp-session/mcp-session-service.ts    |  22 +-
 packages/agent-bundle/src/test/render.ts      |  10 +-
 .../agent-bundle/tests/app-client.test.ts     | 213 ++++++-
 packages/agent-bundle/tests/entries.test.ts   |   2 +-
 .../tests/generated-route-server.test.ts      | 144 +++++
 .../tests/mcp-app-binding-service.test.ts     | 128 ++++-
 .../tests/mcp-app-bridge-cancellation.test.ts | 533 ++++++++++++++++++
 .../tests/mcp-apps-compile.test.ts            |  46 +-
 .../tests/route-unit/render-route.test.ts     |  20 +
 packages/agent-bundle/tests/serve-app.test.ts | 121 ++--
 .../workbench/tests/mcp-app-real.e2e.test.ts  |  50 +-
 website/docs/en/examples/mcp-app.mdx          |  14 +-
 website/docs/en/guide/authoring/mcp.mdx       | 114 ++--
 website/docs/en/reference/api.mdx             |   2 +-
 website/docs/en/reference/security.mdx        |  19 +-
 website/docs/zh/examples/mcp-app.mdx          |  11 +-
 website/docs/zh/guide/authoring/mcp.mdx       | 118 +++-
 website/docs/zh/reference/api.mdx             |   2 +-
 website/docs/zh/reference/security.mdx        |  12 +-
 32 files changed, 2015 insertions(+), 312 deletions(-)
 create mode 100644 packages/agent-bundle/src/contracts/mcp-app-protocol.ts
 create mode 100644 packages/agent-bundle/tests/mcp-app-bridge-cancellation.test.ts

diff --git a/.changeset/typed-app-client.md b/.changeset/typed-app-client.md
index edcc8483a..6b063dd59 100644
--- a/.changeset/typed-app-client.md
+++ b/.changeset/typed-app-client.md
@@ -2,4 +2,4 @@
 "agent-bundle": patch
 ---
 
-Call typed MCP App routes through `agent-bundle/app` without triggering `AB4837` (#594)
+Export `createAppClient` from `agent-bundle/app` so MCP App views call typed host routes without importing the compiler, and reword `AB4837` to name Apps as the exception. (#601)
diff --git a/docs/entry-conventions.md b/docs/entry-conventions.md
index d5f0b2cec..16e51e824 100644
--- a/docs/entry-conventions.md
+++ b/docs/entry-conventions.md
@@ -1521,27 +1521,45 @@ The worked example is in the MCP Apps guide, "Serving an App standalone".
 
 `agent-bundle/app` (`src/app/index.ts`, #594) is the half of the MCP Apps
 bridge that runs inside the App document. It is a browser-safe leaf of the
-package: its only imports are browser-safe strict-JSON and route-name helpers, so `dist/app.js` names no
-Zod, Node built-in, Effect, route module, or compiler code, and the App
-compile inlines it into the self-contained HTML from the installed package
-inside the document (`tests/mcp-apps-compile.test.ts` walks the runtime import
-graph and the emitted document for exactly that). It is a public package
-export and a compiler-reserved App import, so a consumer `paths` mapping cannot
-replace the framework runtime. It is not one of the compiler-carrying entries
-`AB4837` rejects.
+package: its only imports are the shared protocol-version constant
+(`src/contracts/mcp-app-protocol.ts`, which
+`src/dev/mcp-app-profile-descriptors.ts` re-exports for the host side, so
+`APP_PROTOCOL_VERSION` and the host's `MCP_APP_PROTOCOL_VERSION` are one value
+— `tests/app-client.test.ts` asserts it), the browser-safe strict-JSON
+helpers, and the route-name parser, so `dist/app.js` names no Zod, Node
+built-in, Effect, route module, or compiler code, and the App compile inlines
+it into the self-contained HTML from the installed package inside the document
+(`tests/mcp-apps-compile.test.ts` walks the runtime import graph of
+`dist/app.js` and the emitted document for exactly that). It is a public
+package export and a compiler-reserved App import, so a consumer `paths`
+mapping cannot replace the framework runtime. It is not one of the
+compiler-carrying entries `AB4837` rejects.
 
 The other half stays where it is: the host page, sandbox proxy, frame relay
 (`McpAppFrameRelay` in the Workbench, the inline relay in `serve-app`),
 `/api/mcp/...` routes, consent authority, and `createMcpAppBridge`
 (`src/dev/mcp-apps/mcp-app-bridge.ts`) are host-side and owned by the
-Workbench, `serve-app`, and #564's production host. The `browser-app` proof
-level (`mountBrowserApp` in `agent-bundle/test/browser`, which hosts the
-compiled document over `createMcpAppBridge`) exercises the client against that
-host bridge — `examples/mcp-app/tests/browser-app` asserts the App-to-host
-traffic is exactly the client's `ui/initialize` and
+Workbench, `serve-app`, and #564's production host; #594 adds no host bridge
+and moves none of those modules. The one host-side behavior it adds is
+cancellation: `createMcpAppBridge` now honors the client's
+`notifications/cancelled` and threads the abort through the binding service
+and session lease (below). The `browser-app` proof level
+(`mountBrowserApp` in `agent-bundle/test/browser`, which hosts the compiled
+document over `createMcpAppBridge`) is where the client meets that host bridge
+in a real browser — `examples/mcp-app/tests/browser-app` asserts the
+App-to-host traffic is exactly the client's `ui/initialize` and
 `ui/notifications/initialized` until the view acts — so there is one wire
-contract, not a second host bridge. The client never decides which server a
-call reaches or which capability needs consent.
+contract, not a second host bridge. The checkout hosts are driven by the same
+client rather than by hand-written frames: `tests/serve-app.test.ts` connects
+`createAppClient` to the served example App over injected ports whose
+`postMessage` relays each frame through the `/api/mcp/...` routes the sandbox
+relay uses, and the Workbench real-App E2E
+(`packages/workbench/tests/mcp-app-real.e2e.test.ts`) compiles a fixture view
+on `createAppClient` and reads its `call()` result through the relay. The
+client's own contract — envelopes, handshake, pinning, dispatch, cancellation,
+rebind, disposal — is proven in `tests/app-client.test.ts` over injected
+ports. The client never decides which server a call reaches or which
+capability needs consent.
 
 ### Public surface
 
@@ -1549,12 +1567,12 @@ call reaches or which capability needs consent.
 
 | Member | Contract |
 | --- | --- |
-| `connect(options?)` | Performs the `ui/initialize` handshake once and resolves the validated `AppInitializeResult` (`protocolVersion` `2026-01-26` — `APP_PROTOCOL_VERSION` — plus `hostInfo`, `hostCapabilities`, `hostContext`), then sends `ui/notifications/initialized`. Idempotent: a connected client resolves the cached result, a connecting one returns the in-flight promise. |
-| `call(routeId, input, options?)` | `tools/call` for the tool a `tool:<server>/<name>` route id names — the wire name is the final segment, derived the way the generated server derives it (`src/routes/protocol-name.ts`); any other shape is a `TypeError`. `input` must be a finite strict-JSON object (`invalid-message` otherwise). Resolves the result's `structuredContent` **directly**; rejects a result with `isError: true` (`rpc`, whole result on `error.data`), one without an object `structuredContent`, or a malformed envelope (`invalid-message`). Only object-rooted `resultSchema`s produce `structuredContent` in the MCP projection, so scalar and array results are not typed App calls. |
-| `request(method, params?, options?)` | The typed JSON-RPC escape hatch for `resources/read` and supported `ui/*` methods; resolves the raw result. |
-| `onToolInput(routeId, listener)` / `onToolResult(routeId, listener)` | The opening call's `ui/notifications/tool-input` arguments and the decoded `structuredContent` of `ui/notifications/tool-result`. The notifications carry no tool name — they are always the call that opened the App — so the route id types the payload and does not filter; a result without an object `structuredContent` is dropped. Each returns its unsubscribe function. |
-| `onToolCancelled(listener)` | `ui/notifications/tool-cancelled` as `{ reason? }`; returns its unsubscribe function. |
-| `rebind({ parent?, targetOrigin?, window? })` | Rejects the previous generation's pending requests with `connection-rebound`, clears the pinned origin, moves the message listener when `window` changes, adopts the new parent and trusted origin, and runs `connect()` again. |
+| `connect(options?)` | Performs the `ui/initialize` handshake once and resolves the validated `AppInitializeResult` (`protocolVersion` `2026-01-26` — `APP_PROTOCOL_VERSION` — plus `hostInfo`, `hostCapabilities`, `hostContext`), then sends `ui/notifications/initialized` and records the opening tool name from `hostContext.toolInfo.tool.name` for the opening-notification listeners. Idempotent: a connected client resolves the cached result, a connecting one returns the in-flight promise; a handshake that `rebind()` overtakes rejects with `connection-rebound`. |
+| `call(routeId, input, options?)` | `tools/call` for the tool a `tool:<server>/<name>` route id names — the wire name is the final segment, derived the way the generated server derives it (`src/routes/protocol-name.ts`); any other shape rejects with a `TypeError`. The server segment is not on the wire: `tools/call` carries `name` alone and the host dispatches it to the server the App is bound to, so an id naming another server's tool reaches the bound server's tool of that name, or fails there. `input` must be a finite strict-JSON object (`invalid-message` otherwise). Resolves the result's `structuredContent` **directly**; rejects a result with `isError: true` (`rpc`, whole result on `error.data`), one without an object `structuredContent`, or a malformed envelope (`invalid-message`). The MCP projection emits `structuredContent` for object-valued results only (`advertisedOutputSchema` in `src/mcp-server-runtime.ts`), so a tool whose `resultSchema` is scalar- or array-rooted is typed by the generated map but never resolves through `call()`. |
+| `request(method, params?, options?)` | The typed JSON-RPC escape hatch for `resources/read` and supported `ui/*` methods; resolves the raw result. An empty method rejects with a `TypeError`. |
+| `onToolInput(routeId, listener)` / `onToolResult(routeId, listener)` / `onToolError(routeId, listener)` | The opening call's `ui/notifications/tool-input` arguments, the decoded `structuredContent` of a successful `ui/notifications/tool-result`, and that notification's failures as an `AppClientError` — `isError: true` is `rpc` with the whole result on `data`; a malformed envelope or one without an object `structuredContent` is `invalid-message`; a failed result never reaches `onToolResult`. The notifications carry no tool name, so dispatch keys on the tool the handshake named: `hostContext.toolInfo.tool.name` from the initialize result, matched against the final segment of each registered route id. Listeners for other tools stay silent; when the initialize result names no tool, `tool-input` and `tool-result` reach no listener. Listeners run on a microtask, exceptions dropped. Each returns its unsubscribe function. |
+| `onToolCancelled(listener)` | `ui/notifications/tool-cancelled` as `{ reason? }`, unfiltered; returns its unsubscribe function. |
+| `rebind({ parent?, targetOrigin?, window? })` | Bumps the connection generation and rejects the previous generation's pending requests with `connection-rebound` — a `connect()` still in flight included; its late response can never become the live connection — clears the pinned origin and the opening tool name, moves the message listener when `window` changes, adopts the new parent, keeps the configured `targetOrigin` unless the call names the key, and runs `connect()` again. |
 | `dispose()` | Idempotent. Removes the message listener, rejects pending requests with `disposed`, drops every registration and the pin. A host `ui/resource-teardown` request is answered with `{}` and disposes the client; any other host request is answered `-32601`. |
 | `connected` / `disposed` | Read-only state. |
 
@@ -1562,14 +1580,54 @@ call reaches or which capability needs consent.
 `agent-bundle-app` / `1.0.0`), `appCapabilities` (a finite JSON object,
 default `{}`), `timeoutMs` (integer milliseconds, 1 to 2³¹ − 1, default
 15 000), and the connect options `parent`, `targetOrigin`, `window`. Every
-request takes `{ signal, timeoutMs }`; a request that times out or is aborted
-rejects with `timeout` / `aborted` and, once connected, sends
-`notifications/cancelled` to the host. `AppClientError` is the one error
-class: `code` is `timeout`, `aborted`, `disposed`, `connection-rebound`,
-`invalid-message`, `rpc`, `capability-unavailable`, or `consent-required`; a
-host JSON-RPC error maps `-32601` to `capability-unavailable`, `-32001` to
-`consent-required`, and anything else to `rpc`, keeping `rpcCode` and `data`.
-No AB diagnostic is involved: App-side failures are browser errors.
+request takes `{ signal, timeoutMs }`. `signal` is typed as the ambient
+`AbortSignal` of whichever `lib` the App program compiles against (DOM in a
+view, Node in the unit tests) and is used structurally: the client reads
+`aborted`, adds one `abort` listener, and removes it when the request settles.
+A request that times out or is aborted rejects with `timeout` / `aborted` and,
+once connected, sends `notifications/cancelled` with the request id and the
+reason; the client does not wait to learn whether the host stopped anything.
+
+Two error kinds, deliberately. Everything asynchronous — wire, host, and
+lifecycle — rejects with the one `AppClientError` class: `code` is `timeout`,
+`aborted`, `disposed`, `connection-rebound`, `invalid-message`, `rpc`,
+`capability-unavailable`, or `consent-required`; a host JSON-RPC error maps
+`-32601` to `capability-unavailable`, `-32001` to `consent-required`, and
+anything else to `rpc`, keeping `rpcCode` and `data`. Option misuse is a
+plain `TypeError` or `RangeError`, never an `AppClientError`:
+`createAppClient()` throws synchronously for a `targetOrigin` that is not an
+exact `http:`/`https:` origin, for `appInfo`/`appCapabilities` that are not
+finite JSON objects with nonempty `name`/`version`, for a missing `window`
+with no injected port (`TypeError`), and for a `timeoutMs` that is not an
+integer in 1 to 2³¹ − 1 (`RangeError`); the `on*` registrations throw a
+`TypeError` for a non-`tool:` route id or a non-function listener; `call()`,
+`request()`, and `connect()` surface the same `TypeError`/`RangeError` as their
+rejection when the misuse is in their own arguments (a malformed route id, an
+empty method, an out-of-range per-request `timeoutMs`). No AB diagnostic is
+involved: App-side failures are browser errors.
+
+### Host-side cancellation
+
+The client's `notifications/cancelled` is honored by `createMcpAppBridge`
+(`src/dev/mcp-apps/mcp-app-bridge.ts`), which the Workbench, `serve-app`, and
+`mountBrowserApp` run. Every operation request the bridge accepts —
+`tools/call`, `resources/read`, and the `ui/*` requests; `ping` is answered
+inline — is tracked in flight under its JSON-RPC id with an `AbortController`;
+a well-formed cancellation for an in-flight id aborts that controller, drops
+the request's pending consent challenge (resolving it as denied, so a later
+approval cannot run the action), and suppresses the late response — a
+cancelled request gets neither a result nor an error. The abort signal is
+threaded through `McpAppBindingService.callTool`/`readResource` and the
+`McpAppSessionLease` into `McpSession`, which composes it into the SDK request
+with `AbortSignal.any`, so the bound MCP session's request is cancelled too. A
+cancellation for an unknown or finished id is a no-op; one arriving before the
+App is initialized is ignored; one carrying an `id` is rejected as malformed;
+and a duplicate in-flight request id is rejected `-32602` without touching the
+original. Re-initialization and close abort every in-flight request.
+`tests/mcp-app-bridge-cancellation.test.ts` covers each of those, including
+that cancellation cannot bypass consent or reach a request the App did not
+start. Hosts outside the framework apply their own policy; the client's
+behavior is the same either way.
 
 ### Opaque sandbox handshake
 
@@ -1578,17 +1636,21 @@ referrerpolicy="no-referrer" srcdoc=…>`, so the document has an opaque
 origin and no referrer to learn its host origin from. The client therefore
 sends exactly one frame to `'*'` — its own `ui/initialize` — and accepts a
 response only when `event.source` is the configured parent, the id is that
-bootstrap request's, and the result validates; it then pins `event.origin`
-(an empty or `'null'` origin is refused as `invalid-message`), posts
-`ui/notifications/initialized` and every later request to that exact origin,
-and ignores every message from another source or origin. A malformed message
-that still names a pending id rejects that request as `invalid-message`. A
-host that can name its origin passes `targetOrigin` — an exact `http:` or
-`https:` origin; `'*'`, `'null'`, and non-origin strings are a `TypeError` —
-and no wildcard frame is sent. Author code has no wildcard send path. The
-transport is DOM-shaped (`AppWindow`, `AppMessageTarget`) rather than bound to
-the global `window`, so `tests/app-client.test.ts` and non-DOM hosts drive the
-same core through injected ports.
+bootstrap request's, and the result validates; it then pins `event.origin`,
+held to the same rule as `targetOrigin` — an exact `http:` or `https:` origin;
+an empty, `'null'`, or other-scheme origin fails the handshake as
+`invalid-message` — posts `ui/notifications/initialized` and every later
+request to that exact origin, and ignores every message from another source or
+origin. The initialize result also names the opening tool
+(`hostContext.toolInfo.tool.name`), which is what the opening-notification
+listeners dispatch on. A malformed message that still names a pending id
+rejects that request as `invalid-message`. A host that can name its origin
+passes `targetOrigin` — an exact `http:` or `https:` origin; `'*'`, `'null'`,
+other schemes, and non-origin strings are a `TypeError` — and no wildcard frame
+is sent. Author code has no wildcard send path. The transport is DOM-shaped
+(`AppWindow`, `AppMessageTarget`) rather than bound to the global `window`, so
+`tests/app-client.test.ts` and non-DOM hosts drive the same core through
+injected ports.
 
 ### Generated typing
 
@@ -1611,9 +1673,18 @@ HTML. With `.agent-bundle/routes.d.ts` in the program, `call()` narrows its
 route id to the project's tools, `input` to that tool's input, and its
 resolved value to the tool's structured result; `AppRouteId`,
 `AppRouteInput<Id>`, and `AppRouteResult<Id>` expose the same narrowing.
-Without the augmentation (no tool routes, a handwritten server, a program that
-omits the file) the id is any `tool:<server>/<name>` string and input and
-result are `unknown`; a view may then augment `AppRegister` itself with a
-structural map, as `examples/mcp-app/views/status-panel.ts` does. There is no
-generated `agent-bundle/routes/client` value module: the wire name is
-derivable from the id, so a runtime table would duplicate it.
+Two limits of the map are worth knowing. It is filtered by route kind, not by
+result shape: a tool whose `resultSchema` is scalar- or array-rooted is in it
+with that scalar or array as its `result`, although the projection never emits
+`structuredContent` for it and `call()` on it always rejects
+`invalid-message`. And it spans every generated server of the project, while
+an App is bound to one: the type system accepts `call('tool:shelf/find', …)`
+from an App the `curator` server registered, but the wire carries only `find`
+and the host runs the bound server's `find`, or fails. Neither is a compiler
+diagnostic today. Without the augmentation (no tool routes, a handwritten
+server, a program that omits the file) the id is any `tool:<server>/<name>`
+string and input and result are `unknown`; a view may then augment
+`AppRegister` itself with a structural map, as
+`examples/mcp-app/views/status-panel.ts` does. There is no generated
+`agent-bundle/routes/client` value module: the wire name is derivable from the
+id, so a runtime table would duplicate it.
diff --git a/examples/mcp-app/tests/browser-app/status-panel.browser.test.ts b/examples/mcp-app/tests/browser-app/status-panel.browser.test.ts
index 0d976f6f4..8a03649a5 100644
--- a/examples/mcp-app/tests/browser-app/status-panel.browser.test.ts
+++ b/examples/mcp-app/tests/browser-app/status-panel.browser.test.ts
@@ -1,10 +1,43 @@
 import { afterEach, expect, it } from '@rstest/core';
 
-import { mountBrowserApp, type MountBrowserAppOptions, type MountedBrowserApp } from 'agent-bundle/test/browser';
+import {
+  type BrowserAppTraffic,
+  mountBrowserApp,
+  type MountBrowserAppOptions,
+  type MountedBrowserApp,
+} from 'agent-bundle/test/browser';
 
 type BindingOperations = MountBrowserAppOptions['operations'];
 type ToolCallResult = Awaited<ReturnType<BindingOperations['callTool']>>;
 
+/**
+ * The opening tool as `src/mcp/status.ts` registers it. Framework hosts put
+ * the leased tool definition in the initialize `hostContext.toolInfo`, and the
+ * App client delivers `onToolInput`/`onToolResult` only to listeners on that
+ * tool's route, so the harness has to open the panel with `show-status` for
+ * the populated-state tests to go through the `tool:status/show-status`
+ * listeners.
+ */
+const showStatusTool = Object.freeze({
+  _meta: Object.freeze({ ui: Object.freeze({ resourceUri: 'ui://mcp-app-example/status.html' }) }),
+  description: 'Show the health of one example service.',
+  inputSchema: Object.freeze({
+    properties: Object.freeze({
+      service: Object.freeze({ enum: Object.freeze(['compiler', 'payments-api']), type: 'string' }),
+    }),
+    required: Object.freeze(['service']),
+    type: 'object',
+  }),
+  name: 'show-status',
+});
+
+const openingHostContext = Object.freeze({
+  availableDisplayModes: Object.freeze(['inline']),
+  displayMode: 'inline',
+  platform: 'desktop',
+  toolInfo: Object.freeze({ tool: showStatusTool }),
+});
+
 const statusResult = Object.freeze({
   content: Object.freeze([Object.freeze({
     text: 'Payment latency is above the release threshold.',
@@ -21,6 +54,32 @@ const statusResult = Object.freeze({
   }),
 });
 
+/**
+ * An opening `show-status` call that failed. The bridge forwards an `isError`
+ * result unchanged and the App client hands it to `onToolError`, never to the
+ * typed `onToolResult` listener. The structured payload is deliberately
+ * healthy-shaped: it is the tripwire that would paint the panel `healthy` with
+ * a passing check if the success listener ran on an error result.
+ */
+const failedStatusResult = Object.freeze({
+  content: Object.freeze([Object.freeze({
+    text: 'payments-api is not reachable from this host.',
+    type: 'text',
+  })]),
+  isError: true,
+  structuredContent: Object.freeze({
+    checks: Object.freeze([Object.freeze({ label: 'Availability', status: 'passing' })]),
+    service: 'payments-api',
+    status: 'healthy',
+    summary: 'Every check is passing.',
+  }),
+});
+
+/** A result the bridge accepts but the App client cannot type: no `structuredContent`. */
+const unstructuredStatusResult = Object.freeze({
+  content: Object.freeze([Object.freeze({ text: 'payments-api looks fine.', type: 'text' })]),
+});
+
 const mounted: MountedBrowserApp[] = [];
 
 afterEach(async () => {
@@ -59,8 +118,11 @@ const operations = (options: {
 
 const mountStatus = async (overrides: Partial<Parameters<typeof mountBrowserApp>[1]> = {}) => {
   const app = await mountBrowserApp('status', {
+    host: { context: openingHostContext },
     operations: operations(),
+    toolDefinition: showStatusTool,
     toolInput: { service: 'payments-api' },
+    toolName: showStatusTool.name,
     toolResult: statusResult,
     ...overrides,
   });
@@ -80,6 +142,13 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>
 const messageParam = (message: { readonly params?: unknown }, key: string): unknown =>
   isRecord(message.params) ? message.params[key] : undefined;
 
+const initializeResult = (app: MountedBrowserApp): unknown => {
+  const requestId = app.traffic.find(({ message }) => message.method === 'ui/initialize')?.message.id;
+  if (requestId === undefined) return undefined;
+  return app.traffic.find(({ direction, message }) => direction === 'host-to-app' && message.id === requestId)
+    ?.message.result;
+};
+
 it('mounts the compiled panel, initializes the bridge, and renders the published result accessibly', async () => {
   const app = await mountStatus();
   await waitFor(() => app.document.querySelector('#status')?.textContent === 'degraded');
@@ -96,6 +165,7 @@ it('mounts the compiled panel, initializes the bridge, and renders the published
     'P95 latencyfailing',
   ]);
   expect(app.provenance).toMatchObject({ proofLevel: 'browser-app', target: 'portable' });
+  expect(initializeResult(app)).toMatchObject({ hostContext: { toolInfo: { tool: { name: 'show-status' } } } });
   expect(app.traffic.some(({ message }) => message.method === 'ui/notifications/tool-input')).toBe(true);
   expect(app.traffic.some(({ message }) => message.method === 'ui/notifications/tool-result')).toBe(true);
 });
@@ -177,3 +247,46 @@ it('fails closed when a consented binding operation is unavailable', async () =>
   expect(app.traffic.some(({ message }) => message.error?.code === -32000)).toBe(true);
   expect(app.document.querySelector('#bridge-outcome')?.textContent).not.toBe('Status refreshed.');
 });
+
+const openingToolResults = (app: MountedBrowserApp): readonly BrowserAppTraffic[] =>
+  app.traffic.filter(({ direction, message }) => (
+    direction === 'host-to-app' && message.method === 'ui/notifications/tool-result'
+  ));
+
+it('exits checking and renders an unavailable outcome when the opening result is an error', async () => {
+  const app = await mountStatus({ toolResult: failedStatusResult });
+  await waitFor(() => app.document.querySelector('#status')?.textContent === 'unavailable');
+
+  expect(app.bridge.lifecycle).toBe('initialized');
+  expect(app.traffic.some(({ message }) => message.method === 'ui/notifications/tool-input')).toBe(true);
+  const results = openingToolResults(app);
+  expect(results).toHaveLength(1);
+  expect(messageParam(results[0]!.message, 'isError')).toBe(true);
+  expect(messageParam(results[0]!.message, 'structuredContent')).toMatchObject({ status: 'healthy' });
+
+  // The requested service stays in the heading; the verdict is the panel's own.
+  expect(app.document.querySelector('h1')?.textContent).toBe('payments-api');
+  expect(app.document.querySelector<HTMLElement>('#status-indicator')?.dataset.state).toBe('unavailable');
+  expect(app.document.querySelector('#summary')?.textContent).toBe(
+    'Readiness is unavailable: payments-api is not reachable from this host.',
+  );
+
+  // Nothing from the healthy-shaped payload behind `isError` reached the DOM:
+  // the typed `onToolResult` listener never ran.
+  expect(app.document.querySelector('#status')?.textContent).not.toBe('healthy');
+  expect(app.document.querySelector('#summary')?.textContent).not.toBe('Every check is passing.');
+  expect(app.document.querySelectorAll('#checks li')).toHaveLength(0);
+});
+
+it('renders the unavailable outcome when the opening result has no structured content', async () => {
+  const app = await mountStatus({ toolResult: unstructuredStatusResult });
+  await waitFor(() => app.document.querySelector('#status')?.textContent === 'unavailable');
+
+  expect(openingToolResults(app)).toHaveLength(1);
+  expect(app.document.querySelector('h1')?.textContent).toBe('payments-api');
+  expect(app.document.querySelector<HTMLElement>('#status-indicator')?.dataset.state).toBe('unavailable');
+  expect(app.document.querySelector('#summary')?.textContent).toBe(
+    'Readiness is unavailable: The opening tool did not return structured content.',
+  );
+  expect(app.document.querySelectorAll('#checks li')).toHaveLength(0);
+});
diff --git a/examples/mcp-app/views/status-panel.ts b/examples/mcp-app/views/status-panel.ts
index 62c8a9829..c23ae4dff 100644
--- a/examples/mcp-app/views/status-panel.ts
+++ b/examples/mcp-app/views/status-panel.ts
@@ -1,4 +1,4 @@
-import { createAppClient } from 'agent-bundle/app';
+import { type AppClientError, createAppClient } from 'agent-bundle/app';
 import { name, version } from 'agent-bundle/meta';
 
 const serviceHeading = document.querySelector<HTMLHeadingElement>('#service')!;
@@ -8,7 +8,11 @@ const summary = document.querySelector<HTMLParagraphElement>('#summary')!;
 const checks = document.querySelector<HTMLUListElement>('#checks')!;
 const bridgeOutcome = document.querySelector<HTMLParagraphElement>('#bridge-outcome')!;
 
-type StatusState = 'checking' | 'healthy' | 'degraded' | 'unknown';
+/**
+ * `checking`, `healthy`, and `degraded` come from the tool; `unavailable` is
+ * the panel's own verdict when the opening call fails to produce a status.
+ */
+type StatusState = 'checking' | 'healthy' | 'degraded' | 'unavailable' | 'unknown';
 
 interface ServiceCheck {
   readonly label?: string;
@@ -71,12 +75,23 @@ const checkState = (value: string | undefined): StatusState => {
   return 'unknown';
 };
 
-const setStatus = (value: string | undefined) => {
-  const state = statusState(value);
+const setStatus = (state: StatusState) => {
   statusIndicator.dataset.state = state;
   status.textContent = state;
 };
 
+/**
+ * The detail behind a failed opening call. An `isError` result carries the
+ * whole tool result on `error.data`, so its text block explains the failure
+ * in the tool's words; a malformed result or one without structured content
+ * has no data, and the client's own message is the detail.
+ */
+const toolErrorDetail = (error: AppClientError): string => {
+  const content = isRecord(error.data) && Array.isArray(error.data.content) ? error.data.content : [];
+  const block: unknown = content.find((entry: unknown) => isRecord(entry) && entry.type === 'text');
+  return isRecord(block) && typeof block.text === 'string' ? block.text : error.message;
+};
+
 const renderChecks = (items: readonly ServiceCheck[]) => {
   checks.replaceChildren(...items.map((check) => {
     const item = document.createElement('li');
@@ -104,11 +119,20 @@ client.onToolInput(showStatusRoute, (input) => {
 
 client.onToolResult(showStatusRoute, (result) => {
   serviceHeading.textContent = result.service ?? 'No service selected';
-  setStatus(result.status);
+  setStatus(statusState(result.status));
   summary.textContent = result.summary ?? 'No readiness summary was returned.';
   renderChecks(result.checks ?? []);
 });
 
+// A failed opening call — `isError: true`, a malformed result, or one without
+// structured content — never reaches `onToolResult`. Leave the requested
+// service in the heading, exit `checking`, and say why there is no status.
+client.onToolError(showStatusRoute, (error) => {
+  setStatus('unavailable');
+  summary.textContent = `Readiness is unavailable: ${toolErrorDetail(error)}`;
+  renderChecks([]);
+});
+
 document.querySelector('#toggle-details')!.addEventListener('click', () => {
   document.querySelector('#details')!.toggleAttribute('hidden');
 });
diff --git a/packages/agent-bundle/README.md b/packages/agent-bundle/README.md
index 5e820c465..62407cc58 100644
--- a/packages/agent-bundle/README.md
+++ b/packages/agent-bundle/README.md
@@ -108,13 +108,18 @@ HTML resource each and talk to their host through `createAppClient()` from the b
 `agent-bundle/app` — the MCP Apps handshake, request ids, timeouts and cancellation, JSON-RPC and
 result decoding, and exact parent source/origin pinning are framework-owned, so a view never
 hand-writes `postMessage` frames. `call('tool:<server>/<name>', input)` resolves the tool's
-structured result object directly, `onToolInput` / `onToolResult` / `onToolCancelled` observe the
-opening call, `request()` covers `resources/read` and supported `ui/*` methods, and every failure
-is an `AppClientError` with a discriminated `code`. The generated `.agent-bundle/routes.d.ts`
-augments `AppRegister` with the project's tool contracts, so route ids, inputs, and results are
-typed from the routes' own schemas without a route module, Zod, or Node entering the App bundle.
-The entry is bundle-safe (never `AB4837`); the host-side relay, sandbox, and consent authority stay
-with the Workbench, `agent-bundle serve-app`, and embedding hosts.
+structured result object directly (an object-rooted `resultSchema` is what makes a tool callable
+from an App), `onToolInput` / `onToolResult` / `onToolError` observe the opening call — dispatched
+to the listeners registered for the tool the host's initialize result names, with a failed or
+malformed opening result arriving on `onToolError` — `onToolCancelled` reports its cancellation,
+`request()` covers `resources/read` and supported `ui/*` methods, and every wire or lifecycle
+failure is an `AppClientError` with a discriminated `code` (option misuse is a plain `TypeError` or
+`RangeError`). A request that times out or is aborted sends `notifications/cancelled`, which the
+framework's host bridge honors by aborting that one in-flight operation. The generated
+`.agent-bundle/routes.d.ts` augments `AppRegister` with the project's tool contracts, so route ids,
+inputs, and results are typed from the routes' own schemas without a route module, Zod, or Node
+entering the App bundle. The entry is bundle-safe (never `AB4837`); the host-side relay, sandbox,
+and consent authority stay with the Workbench, `agent-bundle serve-app`, and embedding hosts.
 
 Projects that own their compilation entirely declare prebuilt payloads instead: the top-level
 `payload` block names already-built directory trees the build packages byte-for-byte at stable
diff --git a/packages/agent-bundle/src/app/index.ts b/packages/agent-bundle/src/app/index.ts
index a4ae533da..bb7bd307d 100644
--- a/packages/agent-bundle/src/app/index.ts
+++ b/packages/agent-bundle/src/app/index.ts
@@ -1,3 +1,4 @@
+import { MCP_APP_PROTOCOL_VERSION } from '../contracts/mcp-app-protocol.ts';
 import {
   type JsonObject,
   type JsonValue,
@@ -7,7 +8,7 @@ import {
 } from '../core/strict-json.ts';
 import { parseMcpRouteProtocolId } from '../routes/protocol-name.ts';
 
-export const APP_PROTOCOL_VERSION = '2026-01-26';
+export const APP_PROTOCOL_VERSION = MCP_APP_PROTOCOL_VERSION;
 
 export type AppClientErrorCode =
   | 'timeout'
@@ -47,8 +48,12 @@ export interface AppRouteContract {
 export interface AppRegister {}
 
 export type AppRoutes = AppRegister extends {
-  readonly routes: infer Routes extends Record<string, AppRouteContract>;
-} ? Routes : unknown;
+  readonly routes: infer Routes;
+}
+  ? Routes extends { readonly [Id in keyof Routes]: AppRouteContract }
+    ? Routes
+    : never
+  : unknown;
 
 export type AppRouteId = unknown extends AppRoutes
   ? `tool:${string}/${string}`
@@ -95,8 +100,18 @@ export interface CreateAppClientOptions extends AppConnectOptions {
   readonly timeoutMs?: number;
 }
 
+export interface AppAbortSignal {
+  readonly aborted: boolean;
+  addEventListener(
+    type: 'abort',
+    listener: () => void,
+    options?: Readonly<{ once?: boolean }>,
+  ): void;
+  removeEventListener(type: 'abort', listener: () => void): void;
+}
+
 export interface AppRequestOptions {
-  readonly signal?: AbortSignal;
+  readonly signal?: AppAbortSignal;
   readonly timeoutMs?: number;
 }
 
@@ -115,6 +130,10 @@ export type AppToolResultListener<Id extends string> = (
   result: AppRouteResult<Id>,
 ) => Promise<void> | void;
 
+export type AppToolErrorListener = (
+  error: AppClientError,
+) => Promise<void> | void;
+
 export type AppToolCancelledListener = (
   event: Readonly<{ reason?: string }>,
 ) => Promise<void> | void;
@@ -141,6 +160,10 @@ export interface AppClient {
     routeId: Id,
     listener: AppToolResultListener<Id>,
   ): () => void;
+  onToolError<Id extends AppRouteId>(
+    routeId: Id,
+    listener: AppToolErrorListener,
+  ): () => void;
   onToolCancelled(listener: AppToolCancelledListener): () => void;
   rebind(options?: AppConnectOptions): Promise<AppInitializeResult>;
   dispose(): void;
@@ -165,7 +188,7 @@ interface PendingRequest {
   readonly initialize: boolean;
   readonly reject: (error: AppClientError) => void;
   readonly resolve: (value: JsonValue) => void;
-  readonly signal?: AbortSignal;
+  readonly signal?: AppAbortSignal;
   readonly timeout: ReturnType<typeof setTimeout>;
   readonly abort?: () => void;
 }
@@ -278,15 +301,19 @@ const initializeResult = (value: JsonValue): AppInitializeResult | undefined =>
   return value as AppInitializeResult;
 };
 
-const toolResult = (value: JsonValue): JsonObject | undefined => {
+const toolResultEnvelope = (value: JsonValue): JsonObject | undefined => {
   if (!isPlainDataRecord(value) || !Array.isArray(value.content)) return undefined;
   if (!value.content.every((block) => isPlainDataRecord(block) && nonempty(block.type))) return undefined;
   if (value.isError !== undefined && typeof value.isError !== 'boolean') return undefined;
   if (value._meta !== undefined && !isPlainDataRecord(value._meta)) return undefined;
-  if (!isPlainDataRecord(value.structuredContent)) return undefined;
   return value;
 };
 
+const toolResult = (value: JsonValue): JsonObject | undefined => {
+  const result = toolResultEnvelope(value);
+  return result !== undefined && isPlainDataRecord(result.structuredContent) ? result : undefined;
+};
+
 const errorFromRpc = (error: RpcError): AppClientError => {
   const code: AppClientErrorCode = error.code === -32601
     ? 'capability-unavailable'
@@ -315,8 +342,10 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
   let configuredOrigin = trustedOrigin(options.targetOrigin);
   let pinnedOrigin = configuredOrigin;
   let nextId = 0;
+  let connectionGeneration = 0;
   let connection: Promise<AppInitializeResult> | undefined;
   let connectedResult: AppInitializeResult | undefined;
+  let openingToolName: string | undefined;
   let isDisposed = false;
   const timeoutMs = timeoutValue(options.timeoutMs, defaultTimeoutMs);
   const appInfo = snapshotStrictJsonValue(options.appInfo ?? { name: 'agent-bundle-app', version: '1.0.0' });
@@ -333,6 +362,7 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
   const pending = new Map<null | number | string, PendingRequest>();
   const inputListeners = new Map<string, Set<AnyListener>>();
   const resultListeners = new Map<string, Set<AnyListener>>();
+  const errorListeners = new Map<string, Set<AnyListener>>();
   const cancelledListeners = new Set<AnyListener>();
 
   const post = (message: JsonObject, targetOrigin: string): void => {
@@ -355,7 +385,7 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
   };
 
   const notifyCancelled = (id: null | number | string, reason: string): void => {
-    if (connectedResult === undefined || pinnedOrigin === undefined || isDisposed) return;
+    if (connectedResult === undefined || pinnedOrigin === undefined) return;
     try {
       post({
         jsonrpc: '2.0',
@@ -367,8 +397,13 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
     }
   };
 
-  const rejectPending = (code: AppClientErrorCode, message: string): void => {
+  const rejectPending = (
+    code: AppClientErrorCode,
+    message: string,
+    cancellationReason?: string,
+  ): void => {
     for (const id of [...pending.keys()]) {
+      if (cancellationReason !== undefined) notifyCancelled(id, cancellationReason);
       clearPending(id)?.reject(new AppClientError(code, message));
     }
   };
@@ -378,8 +413,10 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
     post({ id, jsonrpc: '2.0', result }, pinnedOrigin);
   };
 
-  const publish = (listeners: Map<string, Set<AnyListener>>, value: unknown): void => {
-    for (const registered of listeners.values()) {
+  const publishOpening = (listeners: Map<string, Set<AnyListener>>, value: unknown): void => {
+    if (openingToolName === undefined) return;
+    for (const [routeId, registered] of listeners) {
+      if (routeToolName(routeId) !== openingToolName) continue;
       for (const listener of [...registered]) invokeListener(listener, value);
     }
   };
@@ -387,13 +424,16 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
   const dispose = (): void => {
     if (isDisposed) return;
     isDisposed = true;
+    connectionGeneration += 1;
     boundWindow.removeEventListener('message', receive);
-    rejectPending('disposed', 'The App client was disposed.');
+    rejectPending('disposed', 'The App client was disposed.', 'disposed');
     connection = undefined;
     connectedResult = undefined;
+    openingToolName = undefined;
     pinnedOrigin = undefined;
     inputListeners.clear();
     resultListeners.clear();
+    errorListeners.clear();
     cancelledListeners.clear();
   };
 
@@ -414,11 +454,12 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
       if (request === undefined) return;
       let responseOrigin: string | undefined;
       if (request.initialize && configuredOrigin === undefined) {
-        if (!nonempty(event.origin) || event.origin === 'null') {
+        try {
+          responseOrigin = trustedOrigin(event.origin);
+        } catch {
           request.reject(new AppClientError('invalid-message', 'The App host returned an unpinnable origin.'));
           return;
         }
-        responseOrigin = event.origin;
       }
       if (message.error !== undefined) {
         request.reject(errorFromRpc(message.error));
@@ -456,12 +497,31 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
     }
     if (message.method === 'ui/notifications/tool-input') {
       const params = isPlainDataRecord(message.params) ? message.params : undefined;
-      if (params !== undefined && isPlainDataRecord(params.arguments)) publish(inputListeners, params.arguments);
+      if (params !== undefined && isPlainDataRecord(params.arguments)) {
+        publishOpening(inputListeners, params.arguments);
+      }
       return;
     }
     if (message.method === 'ui/notifications/tool-result') {
-      const result = message.params === undefined ? undefined : toolResult(message.params);
-      if (result !== undefined) publish(resultListeners, result.structuredContent);
+      const result = message.params === undefined ? undefined : toolResultEnvelope(message.params);
+      if (result === undefined) {
+        publishOpening(
+          errorListeners,
+          new AppClientError('invalid-message', 'The opening tool returned an invalid result.'),
+        );
+      } else if (result.isError === true) {
+        publishOpening(
+          errorListeners,
+          new AppClientError('rpc', 'The opening tool returned an error.', { data: result }),
+        );
+      } else if (!isPlainDataRecord(result.structuredContent)) {
+        publishOpening(
+          errorListeners,
+          new AppClientError('invalid-message', 'The opening tool did not return structured content.'),
+        );
+      } else {
+        publishOpening(resultListeners, result.structuredContent);
+      }
       return;
     }
     if (message.method === 'ui/notifications/tool-cancelled') {
@@ -536,23 +596,35 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
     if (isDisposed) return Promise.reject(new AppClientError('disposed', 'The App client was disposed.'));
     if (connectedResult !== undefined) return Promise.resolve(connectedResult);
     if (connection !== undefined) return connection;
-    connection = sendRequest('ui/initialize', {
+    const generation = connectionGeneration;
+    const connecting = sendRequest('ui/initialize', {
       appCapabilities,
       appInfo,
       protocolVersion: APP_PROTOCOL_VERSION,
     }, requestOptions, true).then((result) => {
+      if (generation !== connectionGeneration || connection !== connecting) {
+        throw new AppClientError('connection-rebound', 'The App client connection was rebound.');
+      }
       const initialized = initializeResult(result);
       if (initialized === undefined || pinnedOrigin === undefined) {
         throw new AppClientError('invalid-message', 'The App host returned an invalid initialize result.');
       }
       post({ jsonrpc: '2.0', method: 'ui/notifications/initialized' }, pinnedOrigin);
       connectedResult = initialized;
+      const toolInfo = isPlainDataRecord(initialized.hostContext.toolInfo)
+        ? initialized.hostContext.toolInfo
+        : undefined;
+      const tool = toolInfo !== undefined && isPlainDataRecord(toolInfo.tool)
+        ? toolInfo.tool
+        : undefined;
+      openingToolName = tool !== undefined && nonempty(tool.name) ? tool.name : undefined;
       return initialized;
     }).catch((error: unknown) => {
-      connection = undefined;
+      if (connection === connecting) connection = undefined;
       throw error;
     });
-    return connection;
+    connection = connecting;
+    return connecting;
   };
 
   const request = <Result extends JsonValue = JsonValue>(
@@ -617,6 +689,7 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
     call,
     onToolInput: (routeId, listener) => register(inputListeners, routeId, listener as AnyListener),
     onToolResult: (routeId, listener) => register(resultListeners, routeId, listener as AnyListener),
+    onToolError: (routeId, listener) => register(errorListeners, routeId, listener as AnyListener),
     onToolCancelled: (listener) => {
       if (typeof listener !== 'function') throw new TypeError('App client listener must be a function.');
       cancelledListeners.add(listener as AnyListener);
@@ -624,9 +697,15 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
     },
     async rebind(rebindOptions: AppConnectOptions = {}): Promise<AppInitializeResult> {
       if (isDisposed) throw new AppClientError('disposed', 'The App client was disposed.');
-      rejectPending('connection-rebound', 'The App client connection was rebound.');
+      connectionGeneration += 1;
+      rejectPending(
+        'connection-rebound',
+        'The App client connection was rebound.',
+        'connection-rebound',
+      );
       connection = undefined;
       connectedResult = undefined;
+      openingToolName = undefined;
       pinnedOrigin = undefined;
       const replacementWindow = rebindOptions.window ?? boundWindow;
       if (replacementWindow !== boundWindow) {
@@ -635,7 +714,9 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
         boundWindow.addEventListener('message', receive);
       }
       parent = rebindOptions.parent ?? boundWindow.parent;
-      configuredOrigin = trustedOrigin(rebindOptions.targetOrigin);
+      if (hasOwn(rebindOptions, 'targetOrigin')) {
+        configuredOrigin = trustedOrigin(rebindOptions.targetOrigin);
+      }
       pinnedOrigin = configuredOrigin;
       return await connect();
     },
diff --git a/packages/agent-bundle/src/build/cli-bins.ts b/packages/agent-bundle/src/build/cli-bins.ts
index 079feede4..29022a38c 100644
--- a/packages/agent-bundle/src/build/cli-bins.ts
+++ b/packages/agent-bundle/src/build/cli-bins.ts
@@ -6,7 +6,7 @@ import { routedCliBinLayout, type TargetArtifactEntry } from '../adapters/types.
 import type { Diagnostic } from '../core/diagnostics.ts';
 import type { NormalizedBinEntry, NormalizedPlugin } from '../core/types.ts';
 import { resolveArtifactDestination } from './emit.ts';
-import { runtimeIgnoredRoot, type CompiledEntry } from './entries.ts';
+import type { CompiledEntry } from './entries.ts';
 import { launchEnvRuntimeSpecifier, operatorEnvLayerVirtualModule } from './launch-env-shell.ts';
 import {
   cliEntryRuntimePath,
@@ -16,6 +16,7 @@ import {
   launchEnvRuntimePath,
 } from './entry-shell.ts';
 import type { RslibEntry, RslibSurfacePlan } from './rslib.ts';
+import { runtimeIgnoredRoot } from './runtime-path.ts';
 
 /**
  * The artifact-hosted routed CLI (#387). A generated-mode `src/cli/**`
diff --git a/packages/agent-bundle/src/build/entries.ts b/packages/agent-bundle/src/build/entries.ts
index 9cc1929c7..00b7878bb 100644
--- a/packages/agent-bundle/src/build/entries.ts
+++ b/packages/agent-bundle/src/build/entries.ts
@@ -50,8 +50,6 @@ import type { ArtifactOutputKind } from './provenance.ts';
 import type { RslibEntry, RslibSurfacePlan } from './rslib.ts';
 import { runtimeIgnoredRoot } from './runtime-path.ts';
 
-export { runtimeIgnoredRoot } from './runtime-path.ts';
-
 /**
  * Spelled as paths, not `new URL(…, import.meta.url)`: the package's own
  * Rslib build would otherwise read the template as a directory context and
diff --git a/packages/agent-bundle/src/build/package-build.ts b/packages/agent-bundle/src/build/package-build.ts
index 15f0f1f03..370bb059f 100644
--- a/packages/agent-bundle/src/build/package-build.ts
+++ b/packages/agent-bundle/src/build/package-build.ts
@@ -8,7 +8,6 @@ import { assertInside, toPosixRelative } from '../core/paths.ts';
 import { declarationBuildDiagnostics, replayDeclarationEmit } from './declaration-diagnostics.ts';
 import { listArtifactFiles, publishArtifact, resolveArtifactDestination } from './emit.ts';
 import { scanEntryExports } from './entry-exports.ts';
-import { runtimeIgnoredRoot } from './entries.ts';
 import {
   cliEntryRuntimePath,
   cliEntryRuntimeSpecifier,
@@ -25,6 +24,7 @@ import { projectMeta } from './meta.ts';
 import { bundleSyntaxCheckFor } from './module-imports.ts';
 import type { BundledOutputEvidence } from './provenance.ts';
 import { buildWithRslib, isDeclarationGenerationFailure, type RslibEntry } from './rslib.ts';
+import { runtimeIgnoredRoot } from './runtime-path.ts';
 import { validateJavaScriptModules } from './validate-artifact-modules.ts';
 
 /**
diff --git a/packages/agent-bundle/src/contracts/mcp-app-protocol.ts b/packages/agent-bundle/src/contracts/mcp-app-protocol.ts
new file mode 100644
index 000000000..47dec2a57
--- /dev/null
+++ b/packages/agent-bundle/src/contracts/mcp-app-protocol.ts
@@ -0,0 +1,2 @@
+/** Protocol version shared by MCP App hosts and clients. */
+export const MCP_APP_PROTOCOL_VERSION = '2026-01-26';
diff --git a/packages/agent-bundle/src/dev/mcp-app-profile-descriptors.ts b/packages/agent-bundle/src/dev/mcp-app-profile-descriptors.ts
index ed9135e76..4477b41f7 100644
--- a/packages/agent-bundle/src/dev/mcp-app-profile-descriptors.ts
+++ b/packages/agent-bundle/src/dev/mcp-app-profile-descriptors.ts
@@ -1,7 +1,8 @@
+import { MCP_APP_PROTOCOL_VERSION } from '../contracts/mcp-app-protocol.ts';
 import { deepFreeze } from '../core/freeze.ts';
 
 /** Browser-safe MCP App profile identity and descriptor registry. */
-export const MCP_APP_PROTOCOL_VERSION = '2026-01-26';
+export { MCP_APP_PROTOCOL_VERSION };
 
 export type McpAppProfileId = 'chatgpt' | 'claude' | 'portable';
 
diff --git a/packages/agent-bundle/src/dev/mcp-apps/mcp-app-binding-service.ts b/packages/agent-bundle/src/dev/mcp-apps/mcp-app-binding-service.ts
index a244d809b..e66f76d07 100644
--- a/packages/agent-bundle/src/dev/mcp-apps/mcp-app-binding-service.ts
+++ b/packages/agent-bundle/src/dev/mcp-apps/mcp-app-binding-service.ts
@@ -37,10 +37,14 @@ export interface McpAppBridgeResource {
 
 export interface McpAppBridgeSession {
   readonly identity: McpAppSessionIdentity;
-  callTool(options: { readonly arguments: McpAppJsonValue | undefined; readonly name: string }): Promise<McpAppJsonValue>;
+  callTool(options: {
+    readonly arguments: McpAppJsonValue | undefined;
+    readonly name: string;
+    readonly signal?: AbortSignal;
+  }): Promise<McpAppJsonValue>;
   listBridgeResources(): Promise<readonly McpAppBridgeResource[]>;
   listBridgeTools(): Promise<readonly McpAppBridgeTool[]>;
-  readResource(options: { readonly uri: string }): Promise<McpAppJsonValue>;
+  readResource(options: { readonly signal?: AbortSignal; readonly uri: string }): Promise<McpAppJsonValue>;
 }
 
 export interface McpAppSessionLease {
@@ -154,6 +158,11 @@ const requireTeardownTimeout = (value: number | undefined): number => {
   return timeout;
 };
 
+const throwIfAborted = (signal: AbortSignal | undefined, label: string): void => {
+  if (signal === undefined || !signal.aborted) return;
+  throw signal.reason instanceof Error ? signal.reason : new Error(label);
+};
+
 export const selectMcpAppResourceUri = (tool: McpAppToolDefinition): string | undefined => {
   const metadata = tool._meta;
   if (!isRecord(metadata) || !isRecord(metadata.ui) || typeof metadata.ui.resourceUri !== 'string') return undefined;
@@ -255,27 +264,46 @@ export class McpAppBindingService {
     }
   }
 
-  async callTool(bindingId: string, request: McpAppToolCall): Promise<McpAppJsonValue> {
+  async callTool(bindingId: string, request: McpAppToolCall, signal?: AbortSignal): Promise<McpAppJsonValue> {
+    throwIfAborted(signal, 'MCP App bridge tool call was aborted.');
     const entry = this.#entry(bindingId);
     const name = requireNonempty(request.name, 'MCP App bridge tool name');
     const tools = await entry.lease.session.listBridgeTools();
+    throwIfAborted(signal, 'MCP App bridge tool call was aborted.');
     this.#assertActive(entry);
     if (!tools.some((tool) => tool.name === name && tool.appVisible)) {
       throw new Error(`MCP App bridge tool ${JSON.stringify(name)} is not app-visible for this binding.`);
     }
     const argumentsValue = request.arguments === undefined ? undefined : requireJson(request.arguments, 'MCP App bridge tool arguments');
-    return requireJson(await entry.lease.session.callTool({ arguments: argumentsValue, name }), 'MCP App bridge tool result');
+    throwIfAborted(signal, 'MCP App bridge tool call was aborted.');
+    return requireJson(
+      await entry.lease.session.callTool({
+        arguments: argumentsValue,
+        name,
+        ...(signal === undefined ? {} : { signal }),
+      }),
+      'MCP App bridge tool result',
+    );
   }
 
-  async readResource(bindingId: string, request: McpAppResourceRead): Promise<McpAppJsonValue> {
+  async readResource(bindingId: string, request: McpAppResourceRead, signal?: AbortSignal): Promise<McpAppJsonValue> {
+    throwIfAborted(signal, 'MCP App bridge resource read was aborted.');
     const entry = this.#entry(bindingId);
     const uri = requireNonempty(request.uri, 'MCP App bridge resource URI');
     const resources = await entry.lease.session.listBridgeResources();
+    throwIfAborted(signal, 'MCP App bridge resource read was aborted.');
     this.#assertActive(entry);
     if (!resources.some((resource) => resource.uri === uri && resource.appVisible)) {
       throw new Error(`MCP App bridge resource ${JSON.stringify(uri)} is not app-visible for this binding.`);
     }
-    return requireJson(await entry.lease.session.readResource({ uri }), 'MCP App bridge resource result');
+    throwIfAborted(signal, 'MCP App bridge resource read was aborted.');
+    return requireJson(
+      await entry.lease.session.readResource({
+        uri,
+        ...(signal === undefined ? {} : { signal }),
+      }),
+      'MCP App bridge resource result',
+    );
   }
 
   async closeBinding(bindingId: string): Promise<boolean> {
diff --git a/packages/agent-bundle/src/dev/mcp-apps/mcp-app-bridge.ts b/packages/agent-bundle/src/dev/mcp-apps/mcp-app-bridge.ts
index 0ef426f9a..35e4e0891 100644
--- a/packages/agent-bundle/src/dev/mcp-apps/mcp-app-bridge.ts
+++ b/packages/agent-bundle/src/dev/mcp-apps/mcp-app-bridge.ts
@@ -82,9 +82,9 @@ export interface McpAppBridgeResourceRead {
  * access, restart, or close a shared MCP session directly.
  */
 export interface McpAppBridgeBindingOperations {
-  callTool(bindingId: string, request: McpAppBridgeToolCall): Promise<McpAppJsonValue>;
+  callTool(bindingId: string, request: McpAppBridgeToolCall, signal?: AbortSignal): Promise<McpAppJsonValue>;
   closeBinding(bindingId: string): Promise<boolean>;
-  readResource(bindingId: string, request: McpAppBridgeResourceRead): Promise<McpAppJsonValue>;
+  readResource(bindingId: string, request: McpAppBridgeResourceRead, signal?: AbortSignal): Promise<McpAppJsonValue>;
 }
 
 export interface McpAppBridgeHostInfo {
@@ -224,6 +224,11 @@ interface PendingConsentAction {
   run(): Promise<boolean>;
 }
 
+interface InFlightRequest {
+  challengeId?: string;
+  readonly controller: AbortController;
+}
+
 const defaultTeardownTimeoutMs = 1_000;
 const maximumTeardownTimeoutMs = 30_000;
 const defaultMaximumQueuedHostMessageBytes = 1_048_576;
@@ -639,6 +644,19 @@ const validResourceRead = (params: McpAppJsonValue | undefined): McpAppBridgeRes
   return record === undefined || !nonempty(record.uri) ? undefined : Object.freeze({ uri: record.uri });
 };
 
+const validCancelled = (params: McpAppJsonValue | undefined): Readonly<{
+  readonly reason?: string;
+  readonly requestId: McpAppBridgeRequestId;
+}> | undefined => {
+  const record = jsonRecord(params);
+  if (record === undefined || !hasOwn(record, 'requestId') || !isRequestId(record.requestId)) return undefined;
+  if (record.reason !== undefined && !nonempty(record.reason)) return undefined;
+  return Object.freeze({
+    requestId: record.requestId,
+    ...(record.reason === undefined ? {} : { reason: record.reason }),
+  });
+};
+
 const validOpenLink = (params: McpAppJsonValue | undefined): string | undefined => validateMcpAppExternalLink(params)?.url;
 
 const validMessage = (params: McpAppJsonValue | undefined): McpAppBridgeMessageEvent | undefined => {
@@ -880,8 +898,53 @@ export const createMcpAppBridge = (options: CreateMcpAppBridgeOptions): McpAppBr
   let appDisplayModes: ReadonlySet<McpAppBridgeDisplayMode> | undefined;
   let hostDisplayModes = validDisplayModeList(host.context?.availableDisplayModes);
   const pendingConsentActions = new Map<string, PendingConsentAction>();
+  const inFlight = new Map<McpAppBridgeRequestId, InFlightRequest>();
   const isClosed = (): boolean => lifecycle === 'closing' || lifecycle === 'closed';
 
+  const beginInFlight = (id: McpAppBridgeRequestId): AbortController | undefined => {
+    if (inFlight.has(id)) return undefined;
+    const controller = new AbortController();
+    inFlight.set(id, { controller });
+    return controller;
+  };
+
+  const stillCurrent = (id: McpAppBridgeRequestId): boolean => {
+    const entry = inFlight.get(id);
+    return entry !== undefined && !entry.controller.signal.aborted && lifecycle === 'initialized';
+  };
+
+  const completeInFlight = (id: McpAppBridgeRequestId, finish: () => boolean): boolean => {
+    if (!stillCurrent(id)) {
+      inFlight.delete(id);
+      return false;
+    }
+    inFlight.delete(id);
+    return finish();
+  };
+
+  const cancelInFlight = (requestId: McpAppBridgeRequestId, reason?: string): boolean => {
+    const entry = inFlight.get(requestId);
+    if (entry === undefined) return true;
+    inFlight.delete(requestId);
+    if (entry.challengeId !== undefined) {
+      pendingConsentActions.delete(entry.challengeId);
+      options.consentAuthority?.resolve(entry.challengeId, false);
+    }
+    if (!entry.controller.signal.aborted) {
+      entry.controller.abort(reason === undefined ? new Error('MCP App request was cancelled.') : new Error(reason));
+    }
+    return true;
+  };
+
+  const abortAllInFlight = (reason?: string): void => {
+    for (const requestId of [...inFlight.keys()]) cancelInFlight(requestId, reason);
+  };
+
+  const rejectDuplicateInFlight = (id: McpAppBridgeRequestId): boolean => {
+    cancelInFlight(id, 'MCP App request id is already in flight.');
+    return fail(id, -32602, 'MCP App request id is already in flight.');
+  };
+
   const hostMessageByteLength = (message: McpAppBridgeMessage): number => utf8ByteLength(JSON.stringify(message));
 
   const enqueueHostMessage = (message: McpAppBridgeMessage): boolean => {
@@ -978,6 +1041,7 @@ export const createMcpAppBridge = (options: CreateMcpAppBridgeOptions): McpAppBr
       (released) => {
         if (!released) throw new McpAppBridgeCloseError('binding-close-rejected');
         lifecycle = 'closed';
+        abortAllInFlight();
         pendingConsentActions.clear();
         queuedHostMessages.length = 0;
         queuedHostMessageBytes = 0;
@@ -1006,6 +1070,7 @@ export const createMcpAppBridge = (options: CreateMcpAppBridgeOptions): McpAppBr
 
   const failClosedHostTraffic = (): void => {
     lifecycle = 'closing';
+    abortAllInFlight();
     pendingConsentActions.clear();
     queuedHostMessages.length = 0;
     queuedHostMessageBytes = 0;
@@ -1022,17 +1087,52 @@ export const createMcpAppBridge = (options: CreateMcpAppBridgeOptions): McpAppBr
     return lifecycle === 'initialized' ? emitHost(response) : send(response);
   };
 
+  const acceptInitialize = (message: McpAppBridgeMessage, resetOpeningFrames: boolean): boolean => {
+    if (!validInitialize(message.params)) {
+      return fail(message.id!, -32602, `ui/initialize requires protocol version ${MCP_APP_PROTOCOL_VERSION}.`);
+    }
+    const sent = respond(message.id!, {
+      hostCapabilities: host.capabilities!,
+      hostContext: host.context!,
+      hostInfo: { name: host.info.name, version: host.info.version },
+      protocolVersion: MCP_APP_PROTOCOL_VERSION,
+    });
+    if (!sent) return false;
+    const initializedParams = jsonRecord(message.params)!;
+    const capabilities = jsonRecord(initializedParams.appCapabilities)!;
+    appDisplayModes = Array.isArray(capabilities.availableDisplayModes)
+      ? new Set(capabilities.availableDisplayModes as readonly McpAppBridgeDisplayMode[])
+      : undefined;
+    if (resetOpeningFrames) {
+      abortAllInFlight();
+      queuedHostMessages.length = 0;
+      queuedHostMessageBytes = 0;
+      hostTrafficBlocked = false;
+      inputQueued = false;
+      terminalQueued = false;
+    }
+    lifecycle = 'initializing';
+    return true;
+  };
+
   const requestActionConsent = (
     capability: McpAppConsentCapability,
     details: McpAppJsonValue,
     pending: Omit<PendingConsentAction, 'actionDigest' | 'capability'>,
+    requestId: McpAppBridgeRequestId,
   ): Promise<boolean> | boolean => {
     if (options.consentAuthority === undefined) return pending.run();
     if (options.profile === undefined) return pending.deny();
     const actionDigest = createMcpAppConsentActionDigest(capability, details);
     const challenge = options.consentAuthority.challenge({ actionDigest, bindingId: binding.id, capability, details, profile: options.profile });
     if (challenge === undefined) return pending.deny();
+    const entry = inFlight.get(requestId);
+    if (entry === undefined || entry.controller.signal.aborted) {
+      options.consentAuthority.resolve(challenge.id, false);
+      return false;
+    }
     pendingConsentActions.set(challenge.id, Object.freeze({ ...pending, actionDigest, capability }));
+    entry.challengeId = challenge.id;
     return true;
   };
 
@@ -1045,29 +1145,36 @@ export const createMcpAppBridge = (options: CreateMcpAppBridgeOptions): McpAppBr
       case 'tools/call': {
         const request = validToolCall(message.params);
         if (request === undefined) return fail(id, -32602, 'tools/call requires a name and finite JSON arguments.');
+        const controller = beginInFlight(id);
+        if (controller === undefined) return rejectDuplicateInFlight(id);
         const details = Object.freeze({ ...(request.arguments === undefined ? {} : { arguments: request.arguments }), name: request.name });
         return requestActionConsent('call-tool', details, {
-          deny: () => lifecycle === 'initialized' ? fail(id, -32001, 'tools/call requires an approved consent grant.') : false,
+          deny: () => completeInFlight(id, () => fail(id, -32001, 'tools/call requires an approved consent grant.')),
           run: async () => {
+            if (controller.signal.aborted) return completeInFlight(id, () => false);
             try {
-              const result = validToolResult(await options.operations.callTool(binding.id, request));
-              if (result === undefined) return lifecycle === 'initialized' ? fail(id, -32000, 'MCP App tool call returned an invalid result.') : false;
-              return lifecycle === 'initialized' ? respond(id, result) : false;
+              const result = validToolResult(await options.operations.callTool(binding.id, request, controller.signal));
+              if (result === undefined) return completeInFlight(id, () => fail(id, -32000, 'MCP App tool call returned an invalid result.'));
+              return completeInFlight(id, () => respond(id, result));
             } catch {
-              return lifecycle === 'initialized' ? fail(id, -32000, 'MCP App tool call failed.') : false;
+              if (controller.signal.aborted) return completeInFlight(id, () => false);
+              return completeInFlight(id, () => fail(id, -32000, 'MCP App tool call failed.'));
             }
           },
-        });
+        }, id);
       }
       case 'resources/read': {
         const request = validResourceRead(message.params);
         if (request === undefined) return fail(id, -32602, 'resources/read requires a nonempty URI.');
+        const controller = beginInFlight(id);
+        if (controller === undefined) return rejectDuplicateInFlight(id);
         try {
-          const result = validResourceReadResult(await options.operations.readResource(binding.id, request));
-          if (result === undefined) return lifecycle === 'initialized' ? fail(id, -32000, 'MCP App resource read returned an invalid result.') : false;
-          return lifecycle === 'initialized' ? respond(id, result) : false;
+          const result = validResourceReadResult(await options.operations.readResource(binding.id, request, controller.signal));
+          if (result === undefined) return completeInFlight(id, () => fail(id, -32000, 'MCP App resource read returned an invalid result.'));
+          return completeInFlight(id, () => respond(id, result));
         } catch {
-          return lifecycle === 'initialized' ? fail(id, -32000, 'MCP App resource read failed.') : false;
+          if (controller.signal.aborted) return completeInFlight(id, () => false);
+          return completeInFlight(id, () => fail(id, -32000, 'MCP App resource read failed.'));
         }
       }
       case 'ui/open-link': {
@@ -1075,46 +1182,57 @@ export const createMcpAppBridge = (options: CreateMcpAppBridgeOptions): McpAppBr
         if (url === undefined) return fail(id, -32602, 'ui/open-link requires an http: or https: URL.');
         const onOpenLink = host.onOpenLink;
         if (onOpenLink === undefined) return fail(id, -32601, 'ui/open-link is not supported by this host.');
+        const controller = beginInFlight(id);
+        if (controller === undefined) return rejectDuplicateInFlight(id);
         return requestActionConsent('open-external-link', Object.freeze({ url }), {
-          deny: () => lifecycle === 'initialized' ? fail(id, -32001, 'ui/open-link requires an approved consent grant.') : false,
+          deny: () => completeInFlight(id, () => fail(id, -32001, 'ui/open-link requires an approved consent grant.')),
           run: async () => {
+            if (controller.signal.aborted) return completeInFlight(id, () => false);
             try {
               await onOpenLink(url);
-              return lifecycle === 'initialized' ? respond(id, {}) : false;
+              return completeInFlight(id, () => respond(id, {}));
             } catch {
-              return lifecycle === 'initialized' ? fail(id, -32000, 'ui/open-link was denied by this host.') : false;
+              if (controller.signal.aborted) return completeInFlight(id, () => false);
+              return completeInFlight(id, () => fail(id, -32000, 'ui/open-link was denied by this host.'));
             }
           },
-        });
+        }, id);
       }
       case 'ui/download-file': {
         const download = validateMcpAppDownloadRequest(message.params);
         if (download === undefined) return fail(id, -32602, 'ui/download-file requires bounded valid MCP content blocks.');
         const onDownload = host.onDownload;
         if (onDownload === undefined) return fail(id, -32601, 'ui/download-file is not supported by this host.');
+        const controller = beginInFlight(id);
+        if (controller === undefined) return rejectDuplicateInFlight(id);
         return requestActionConsent('download-file', Object.freeze({ contents: download.contents }), {
-          deny: () => lifecycle === 'initialized' ? fail(id, -32001, 'ui/download-file requires an approved consent grant.') : false,
+          deny: () => completeInFlight(id, () => fail(id, -32001, 'ui/download-file requires an approved consent grant.')),
           run: async () => {
+            if (controller.signal.aborted) return completeInFlight(id, () => false);
             try {
               await onDownload(download);
-              return lifecycle === 'initialized' ? respond(id, {}) : false;
+              return completeInFlight(id, () => respond(id, {}));
             } catch {
-              return lifecycle === 'initialized' ? fail(id, -32000, 'ui/download-file was denied by this host.') : false;
+              if (controller.signal.aborted) return completeInFlight(id, () => false);
+              return completeInFlight(id, () => fail(id, -32000, 'ui/download-file was denied by this host.'));
             }
           },
-        });
+        }, id);
       }
       case 'ui/message': {
         const event = validMessage(message.params);
         if (event === undefined) return fail(id, -32602, 'ui/message requires a user role and valid MCP content blocks.');
         if (host.onMessage === undefined) return fail(id, -32601, 'ui/message is not supported by this host.');
+        const controller = beginInFlight(id);
+        if (controller === undefined) return rejectDuplicateInFlight(id);
         try {
           const result = await host.onMessage(event);
           const messageResult = result === undefined ? {} : validMessageResult(result);
-          if (messageResult === undefined) return lifecycle === 'initialized' ? fail(id, -32000, 'Host returned an invalid ui/message result.') : false;
-          return lifecycle === 'initialized' ? respond(id, messageResult) : false;
+          if (messageResult === undefined) return completeInFlight(id, () => fail(id, -32000, 'Host returned an invalid ui/message result.'));
+          return completeInFlight(id, () => respond(id, messageResult));
         } catch {
-          return lifecycle === 'initialized' ? fail(id, -32000, 'ui/message was denied by this host.') : false;
+          if (controller.signal.aborted) return completeInFlight(id, () => false);
+          return completeInFlight(id, () => fail(id, -32000, 'ui/message was denied by this host.'));
         }
       }
       case 'ui/request-display-mode': {
@@ -1126,31 +1244,37 @@ export const createMcpAppBridge = (options: CreateMcpAppBridgeOptions): McpAppBr
         if (supportedByApp === undefined || !supportedByApp.has(mode)) return fail(id, -32602, 'ui/request-display-mode must be declared by the App.');
         if (supportedByHost === undefined || !supportedByHost.includes(mode)) return fail(id, -32602, 'ui/request-display-mode is not available from this host.');
         if (onDisplayMode === undefined) return fail(id, -32601, 'ui/request-display-mode is not supported by this host.');
+        const controller = beginInFlight(id);
+        if (controller === undefined) return rejectDuplicateInFlight(id);
         return requestActionConsent('request-display-mode', Object.freeze({ mode }), {
-          deny: () => lifecycle === 'initialized' ? fail(id, -32001, 'ui/request-display-mode requires an approved consent grant.') : false,
+          deny: () => completeInFlight(id, () => fail(id, -32001, 'ui/request-display-mode requires an approved consent grant.')),
           run: async () => {
+            if (controller.signal.aborted) return completeInFlight(id, () => false);
             try {
               const actual = await onDisplayMode(mode);
-              if (lifecycle !== 'initialized') return false;
               if (!supportedByApp.has(actual) || !supportedByHost.includes(actual)) {
-                return fail(id, -32000, 'Host returned a display mode outside the negotiated declarations.');
+                return completeInFlight(id, () => fail(id, -32000, 'Host returned a display mode outside the negotiated declarations.'));
               }
-              return respond(id, { mode: actual });
+              return completeInFlight(id, () => respond(id, { mode: actual }));
             } catch {
-              return lifecycle === 'initialized' ? fail(id, -32000, 'ui/request-display-mode was denied by this host.') : false;
+              if (controller.signal.aborted) return completeInFlight(id, () => false);
+              return completeInFlight(id, () => fail(id, -32000, 'ui/request-display-mode was denied by this host.'));
             }
           },
-        });
+        }, id);
       }
       case 'ui/update-model-context': {
         const context = validModelContext(message.params);
         if (context === undefined) return fail(id, -32602, 'ui/update-model-context requires finite JSON content.');
         if (host.onModelContext === undefined) return fail(id, -32601, 'ui/update-model-context is not supported by this host.');
+        const controller = beginInFlight(id);
+        if (controller === undefined) return rejectDuplicateInFlight(id);
         try {
           await host.onModelContext(context);
-          return lifecycle === 'initialized' ? respond(id, {}) : false;
+          return completeInFlight(id, () => respond(id, {}));
         } catch {
-          return lifecycle === 'initialized' ? fail(id, -32000, 'ui/update-model-context was denied by this host.') : false;
+          if (controller.signal.aborted) return completeInFlight(id, () => false);
+          return completeInFlight(id, () => fail(id, -32000, 'ui/update-model-context was denied by this host.'));
         }
       }
       default:
@@ -1189,10 +1313,12 @@ export const createMcpAppBridge = (options: CreateMcpAppBridgeOptions): McpAppBr
       }
       if (lifecycle !== 'initialized') {
         lifecycle = 'closing';
+        abortAllInFlight();
         pendingConsentActions.clear();
         return rememberClose(releaseBinding());
       }
       lifecycle = 'closing';
+      abortAllInFlight();
       pendingConsentActions.clear();
       hasTeardownId = true;
       teardownId = closeOptions.id;
@@ -1216,6 +1342,7 @@ export const createMcpAppBridge = (options: CreateMcpAppBridgeOptions): McpAppBr
         return closePromise;
       }
       lifecycle = 'closing';
+      abortAllInFlight();
       pendingConsentActions.clear();
       return rememberClose(releaseBinding());
     },
@@ -1295,26 +1422,11 @@ export const createMcpAppBridge = (options: CreateMcpAppBridgeOptions): McpAppBr
       }
       if (lifecycle === 'closed') return false;
       if (lifecycle === 'created') {
-        if (!isInitialize(message) || !validInitialize(message.params)) {
-          return isInitialize(message) ? fail(message.id!, -32602, `ui/initialize requires protocol version ${MCP_APP_PROTOCOL_VERSION}.`) : false;
-        }
-        const sent = respond(message.id!, {
-          hostCapabilities: host.capabilities!,
-          hostContext: host.context!,
-          hostInfo: { name: host.info.name, version: host.info.version },
-          protocolVersion: MCP_APP_PROTOCOL_VERSION,
-        });
-        if (sent) {
-          const initializedParams = jsonRecord(message.params)!;
-          const capabilities = jsonRecord(initializedParams.appCapabilities)!;
-          appDisplayModes = Array.isArray(capabilities.availableDisplayModes)
-            ? new Set(capabilities.availableDisplayModes as readonly McpAppBridgeDisplayMode[])
-            : undefined;
-          lifecycle = 'initializing';
-        }
-        return sent;
+        if (!isInitialize(message)) return false;
+        return acceptInitialize(message, false);
       }
       if (lifecycle === 'initializing') {
+        if (isInitialize(message)) return acceptInitialize(message, true);
         if (!initializedNotification(message)) return false;
         lifecycle = 'initialized';
         const originalInput = jsonRecord(binding.input);
@@ -1352,28 +1464,14 @@ export const createMcpAppBridge = (options: CreateMcpAppBridgeOptions): McpAppBr
         return true;
       }
       if (isInitialize(message)) {
-        if (!validInitialize(message.params)) return fail(message.id!, -32602, `ui/initialize requires protocol version ${MCP_APP_PROTOCOL_VERSION}.`);
-        const sent = respond(message.id!, {
-          hostCapabilities: host.capabilities!,
-          hostContext: host.context!,
-          hostInfo: { name: host.info.name, version: host.info.version },
-          protocolVersion: MCP_APP_PROTOCOL_VERSION,
-        });
-        if (!sent) return false;
-        const initializedParams = jsonRecord(message.params)!;
-        const capabilities = jsonRecord(initializedParams.appCapabilities)!;
-        appDisplayModes = Array.isArray(capabilities.availableDisplayModes)
-          ? new Set(capabilities.availableDisplayModes as readonly McpAppBridgeDisplayMode[])
-          : undefined;
         // A document-policy revision replaces the sandbox document.  Its
         // first data frames must belong solely to that newly initialized App.
-        queuedHostMessages.length = 0;
-        queuedHostMessageBytes = 0;
-        hostTrafficBlocked = false;
-        inputQueued = false;
-        terminalQueued = false;
-        lifecycle = 'initializing';
-        return true;
+        return acceptInitialize(message, true);
+      }
+      if (message.method === 'notifications/cancelled') {
+        if (hasOwn(message, 'id')) return false;
+        const cancelled = validCancelled(message.params);
+        return cancelled === undefined ? false : cancelInFlight(cancelled.requestId, cancelled.reason);
       }
       if (message.method === 'notifications/message') {
         if (hasOwn(message, 'id')) return false;
diff --git a/packages/agent-bundle/src/dev/mcp-session/mcp-session-service.ts b/packages/agent-bundle/src/dev/mcp-session/mcp-session-service.ts
index 81ae6369d..f88327670 100644
--- a/packages/agent-bundle/src/dev/mcp-session/mcp-session-service.ts
+++ b/packages/agent-bundle/src/dev/mcp-session/mcp-session-service.ts
@@ -163,14 +163,22 @@ const createMcpAppSessionLease = (entry: ActiveSession): McpAppSessionLease => {
     if (entry.closed) throw new Error('MCP App session is closed.');
   };
   const bridgeSession: McpAppBridgeSession = Object.freeze({
-    callTool: async ({ arguments: toolArguments, name }: {
+    callTool: async ({ arguments: toolArguments, name, signal }: {
       readonly arguments: McpAppJsonValue | undefined;
       readonly name: string;
+      readonly signal?: AbortSignal;
     }) => {
       assertActive();
+      if (signal?.aborted) {
+        throw signal.reason instanceof Error ? signal.reason : new Error('MCP App tool call was aborted.');
+      }
       const argumentsSnapshot = canonicalMcpAppJson(toolArguments ?? {}, 'MCP App tool arguments');
       if (!isRecord(argumentsSnapshot)) throw new TypeError('MCP App tool arguments must be a JSON object.');
-      const result = await entry.session.callTool({ arguments: argumentsSnapshot, name });
+      const result = await entry.session.callTool({
+        arguments: argumentsSnapshot,
+        name,
+        ...(signal === undefined ? {} : { signal }),
+      });
       assertActive();
       return canonicalMcpAppJson(
         result,
@@ -193,9 +201,15 @@ const createMcpAppSessionLease = (entry: ActiveSession): McpAppSessionLease => {
       assertActive();
       return tools;
     },
-    readResource: async ({ uri }: { readonly uri: string }) => {
+    readResource: async ({ uri, signal }: { readonly signal?: AbortSignal; readonly uri: string }) => {
       assertActive();
-      const result = await entry.session.readResource({ uri });
+      if (signal?.aborted) {
+        throw signal.reason instanceof Error ? signal.reason : new Error('MCP App resource read was aborted.');
+      }
+      const result = await entry.session.readResource({
+        uri,
+        ...(signal === undefined ? {} : { signal }),
+      });
       assertActive();
       return canonicalMcpAppJson(result, 'MCP App resource result');
     },
diff --git a/packages/agent-bundle/src/test/render.ts b/packages/agent-bundle/src/test/render.ts
index 802160415..4957f7100 100644
--- a/packages/agent-bundle/src/test/render.ts
+++ b/packages/agent-bundle/src/test/render.ts
@@ -360,10 +360,14 @@ interface ResolvedTarget {
 
 /**
  * The protocol name a generated server registers, and the request surface it
- * records. Module-direct renders may omit a canonical id (`(module passed to
- * renderRoute)`); those keep the id itself as the surface name.
+ * records: the shared derivation for a canonical MCP route id
+ * (`tool:harness/echo` -> `echo`). A module rendered directly may carry any
+ * `routeId` — `custom/group/name`, or the `(module passed to renderRoute)`
+ * placeholder — and keeps the harness's own fallback for it: the id's final
+ * slash segment, the whole id when it has none.
  */
-const protocolName = (routeId: string): string => parseMcpRouteProtocolId(routeId)?.name ?? routeId;
+const protocolName = (routeId: string): string =>
+  parseMcpRouteProtocolId(routeId)?.name ?? routeId.slice(routeId.lastIndexOf('/') + 1);
 
 /**
  * Props the route component receives. MCP route kinds get exactly the public
diff --git a/packages/agent-bundle/tests/app-client.test.ts b/packages/agent-bundle/tests/app-client.test.ts
index 19bd53d96..77ffbdbd4 100644
--- a/packages/agent-bundle/tests/app-client.test.ts
+++ b/packages/agent-bundle/tests/app-client.test.ts
@@ -2,9 +2,12 @@ import { expect, it } from '@rstest/core';
 
 import {
   APP_PROTOCOL_VERSION,
+  type AppAbortSignal,
   AppClientError,
   type AppMessageEvent,
   type AppMessageTarget,
+  type AppRequestOptions,
+  type AppRouteContract,
   type AppRouteId,
   type AppRouteInput,
   type AppRouteResult,
@@ -12,6 +15,7 @@ import {
   createAppClient,
 } from '../src/app/index.ts';
 import type { JsonObject } from '../src/core/strict-json.ts';
+import { MCP_APP_PROTOCOL_VERSION } from '../src/dev/mcp-app-profile-descriptors.ts';
 
 declare module '../src/app/index.ts' {
   interface AppRegister {
@@ -24,6 +28,10 @@ declare module '../src/app/index.ts' {
         readonly input: Readonly<Record<string, unknown>>;
         readonly result: { readonly count?: number };
       };
+      readonly 'tool:status/show-status': {
+        readonly input: { readonly service: string };
+        readonly result: { readonly service: string; readonly status: string };
+      };
     };
   }
 }
@@ -34,7 +42,7 @@ type Equals<Left, Right> =
 type Assert<Value extends true> = Value;
 type RouteIdProof = Assert<Equals<
   AppRouteId,
-  'tool:hauler/hauler_status' | 'tool:server/status'
+  'tool:hauler/hauler_status' | 'tool:server/status' | 'tool:status/show-status'
 >>;
 type RouteInputProof = Assert<Equals<
   AppRouteInput<'tool:hauler/hauler_status'>,
@@ -44,6 +52,20 @@ type RouteResultProof = Assert<Equals<
   AppRouteResult<'tool:hauler/hauler_status'>,
   { readonly active: number; readonly status: string }
 >>;
+type UnknownRouteInputProof = Assert<Equals<
+  AppRouteInput<'tool:missing/route'>,
+  unknown
+>>;
+type AbortSignalProof = Assert<AbortSignal extends AppAbortSignal ? true : false>;
+type MalformedRoutes = {
+  readonly 'tool:broken/route': { readonly input: unknown };
+};
+type MalformedRegistrationProof = Assert<Equals<
+  MalformedRoutes extends {
+    readonly [Id in keyof MalformedRoutes]: AppRouteContract;
+  } ? MalformedRoutes : never,
+  never
+>>;
 
 interface PostedMessage {
   readonly message: JsonObject;
@@ -51,11 +73,18 @@ interface PostedMessage {
 }
 
 const hostOrigin = 'https://host.example';
-const typeProofs: readonly [RouteIdProof, RouteInputProof, RouteResultProof] = [true, true, true];
+const typeProofs: readonly [
+  RouteIdProof,
+  RouteInputProof,
+  RouteResultProof,
+  UnknownRouteInputProof,
+  AbortSignalProof,
+  MalformedRegistrationProof,
+] = [true, true, true, true, true, true];
 
 const initializeResult = {
   hostCapabilities: { serverTools: {} },
-  hostContext: {},
+  hostContext: { toolInfo: { tool: { name: 'status' } } },
   hostInfo: { name: 'test-host', version: '1.0.0' },
   protocolVersion: APP_PROTOCOL_VERSION,
 } as const;
@@ -118,8 +147,18 @@ const flushListeners = async (): Promise<void> => {
   await Promise.resolve();
 };
 
+it('uses one shared protocol version for the App client and MCP App profile', () => {
+  expect(APP_PROTOCOL_VERSION).toBe(MCP_APP_PROTOCOL_VERSION);
+});
+
+it('accepts AbortController signals through the structural app contract', () => {
+  const signal: AppAbortSignal = new AbortController().signal;
+  const options: AppRequestOptions = { signal };
+  expect(options.signal?.aborted).toBe(false);
+});
+
 it('bootstraps an opaque sandbox only through a matching parent initialize response and pins its origin', async () => {
-  expect(typeProofs).toEqual([true, true, true]);
+  expect(typeProofs).toEqual([true, true, true, true, true, true]);
   const target = harness();
   const foreignParent = {};
   const client = createAppClient({
@@ -181,6 +220,18 @@ it('uses an exact trusted targetOrigin from the first message and rejects a mism
     targetOrigin: '*',
     window: target.window,
   })).toThrow(/exact trusted origin/u);
+  expect(() => createAppClient({
+    targetOrigin: 'file:///tmp/host.html',
+    window: target.window,
+  })).toThrow(/exact trusted http/u);
+});
+
+it('rejects a bootstrap response whose origin is not an exact supported web origin', async () => {
+  const target = harness();
+  const client = createAppClient({ window: target.window });
+  const connecting = client.connect();
+  target.emit({ id: 1, jsonrpc: '2.0', result: initializeResult }, 'file://');
+  await expect(connecting).rejects.toMatchObject({ code: 'invalid-message' });
 });
 
 it('calls a route by its protocol tool name and returns structuredContent directly', async () => {
@@ -262,6 +313,18 @@ it('rejects malformed envelopes and tool results without retaining hostile value
   });
   await expect(called).rejects.toMatchObject({ code: 'invalid-message' });
 
+  const failed = client.call('tool:server/status', {});
+  target.emit({
+    id: 4,
+    jsonrpc: '2.0',
+    result: {
+      content: [{ text: 'failed', type: 'text' }],
+      isError: true,
+      structuredContent: { reason: 'unavailable' },
+    },
+  });
+  await expect(failed).rejects.toMatchObject({ code: 'rpc' });
+
   const cyclic: Record<string, unknown> = {};
   cyclic.self = cyclic;
   await expect(client.call('tool:server/status', cyclic)).rejects.toMatchObject({
@@ -314,9 +377,13 @@ it('delivers typed tool lifecycle notifications and supports listener removal',
   await connect(client, target);
   const inputs: unknown[] = [];
   const results: unknown[] = [];
+  const otherInputs: unknown[] = [];
+  const otherResults: unknown[] = [];
   const cancellations: unknown[] = [];
   const offInput = client.onToolInput('tool:server/status', (input) => { inputs.push(input); });
   client.onToolResult('tool:server/status', (result) => { results.push(result); });
+  client.onToolInput('tool:hauler/hauler_status', (input) => { otherInputs.push(input); });
+  client.onToolResult('tool:hauler/hauler_status', (result) => { otherResults.push(result); });
   client.onToolCancelled((event) => { cancellations.push(event); });
 
   target.emit({
@@ -340,6 +407,8 @@ it('delivers typed tool lifecycle notifications and supports listener removal',
   await flushListeners();
   expect(inputs).toEqual([{ limit: 2 }]);
   expect(results).toEqual([{ count: 2 }]);
+  expect(otherInputs).toEqual([]);
+  expect(otherResults).toEqual([]);
   expect(cancellations).toEqual([{ reason: 'host stopped' }]);
 
   offInput();
@@ -352,6 +421,62 @@ it('delivers typed tool lifecycle notifications and supports listener removal',
   expect(inputs).toEqual([{ limit: 2 }]);
 });
 
+it('delivers opening tool failures only through the matching route error listener', async () => {
+  const target = harness();
+  const client = createAppClient({ window: target.window });
+  await connect(client, target);
+  const errors: AppClientError[] = [];
+  const otherErrors: AppClientError[] = [];
+  const results: unknown[] = [];
+  client.onToolError('tool:server/status', (error) => { errors.push(error); });
+  client.onToolError('tool:hauler/hauler_status', (error) => { otherErrors.push(error); });
+  client.onToolResult('tool:server/status', (result) => { results.push(result); });
+
+  target.emit({
+    jsonrpc: '2.0',
+    method: 'ui/notifications/tool-result',
+    params: {
+      content: [{ text: 'failed with details', type: 'text' }],
+      isError: true,
+      structuredContent: { reason: 'failed' },
+    },
+  });
+  target.emit({
+    jsonrpc: '2.0',
+    method: 'ui/notifications/tool-result',
+    params: {
+      content: [{ text: 'failed without details', type: 'text' }],
+      isError: true,
+    },
+  });
+  target.emit({
+    jsonrpc: '2.0',
+    method: 'ui/notifications/tool-result',
+    params: {
+      content: [{ text: 'missing structured result', type: 'text' }],
+    },
+  });
+  target.emit({
+    jsonrpc: '2.0',
+    method: 'ui/notifications/tool-result',
+    params: {
+      content: [{ text: 'malformed structured result', type: 'text' }],
+      structuredContent: [],
+    },
+  });
+  await flushListeners();
+
+  expect(errors.map((error) => error.code)).toEqual([
+    'rpc',
+    'rpc',
+    'invalid-message',
+    'invalid-message',
+  ]);
+  expect(errors.every((error) => error instanceof AppClientError)).toBe(true);
+  expect(otherErrors).toEqual([]);
+  expect(results).toEqual([]);
+});
+
 it('rejects old pending work on rebind and establishes a fresh exact-origin connection', async () => {
   const first = harness();
   const second = harness();
@@ -359,6 +484,7 @@ it('rejects old pending work on rebind and establishes a fresh exact-origin conn
   const client = createAppClient({ window: first.window });
   await connect(client, first);
   const oldRequest = client.request('slow', {});
+  const oldRequestId = responseId(first.posts.at(-1)!);
   const oldFailure = expect(oldRequest).rejects.toMatchObject({ code: 'connection-rebound' });
 
   const rebound = client.rebind({
@@ -368,6 +494,15 @@ it('rejects old pending work on rebind and establishes a fresh exact-origin conn
   });
   expect(first.listenerCount()).toBe(0);
   expect(second.listenerCount()).toBe(1);
+  expect(first.posts.at(-1)).toEqual({
+    message: {
+      jsonrpc: '2.0',
+      method: 'notifications/cancelled',
+      params: { reason: 'connection-rebound', requestId: oldRequestId },
+    },
+    targetOrigin: hostOrigin,
+  });
+  expect(first.posts.at(-1)?.targetOrigin).not.toBe('*');
   expect(second.posts[0]?.targetOrigin).toBe(secondOrigin);
   second.emit({
     id: responseId(second.posts[0]!),
@@ -379,10 +514,58 @@ it('rejects old pending work on rebind and establishes a fresh exact-origin conn
   expect(client.connected).toBe(true);
 });
 
+it('keeps one fresh handshake when rebinding during connect and inherits targetOrigin', async () => {
+  const first = harness();
+  const second = harness();
+  const client = createAppClient({
+    targetOrigin: hostOrigin,
+    window: first.window,
+  });
+  const stale = client.connect();
+  const staleFailure = expect(stale).rejects.toMatchObject({ code: 'connection-rebound' });
+
+  const rebound = client.rebind({ window: second.window });
+  expect(second.posts).toHaveLength(1);
+  expect(second.posts[0]?.targetOrigin).toBe(hostOrigin);
+  await staleFailure;
+
+  const sameConnection = client.connect();
+  expect(second.posts).toHaveLength(1);
+  second.emit({
+    id: responseId(second.posts[0]!),
+    jsonrpc: '2.0',
+    result: initializeResult,
+  });
+  await expect(Promise.all([rebound, sameConnection])).resolves.toEqual([
+    initializeResult,
+    initializeResult,
+  ]);
+  expect(second.posts.filter((entry) => entry.message.method === 'ui/initialize')).toHaveLength(1);
+  expect(second.posts.filter(
+    (entry) => entry.message.method === 'ui/notifications/initialized',
+  )).toHaveLength(1);
+});
+
+it('keeps wildcard initialization cancellation local on dispose', async () => {
+  const target = harness();
+  const client = createAppClient({ window: target.window });
+  const connecting = client.connect();
+  const failure = expect(connecting).rejects.toMatchObject({ code: 'disposed' });
+  expect(target.posts).toHaveLength(1);
+  expect(target.posts[0]?.targetOrigin).toBe('*');
+
+  client.dispose();
+  await failure;
+  expect(target.posts).toHaveLength(1);
+});
+
 it('acknowledges host teardown before disposing and makes disposal idempotent', async () => {
   const target = harness();
   const client = createAppClient({ window: target.window });
   await connect(client, target);
+  const pending = client.request('slow', {});
+  const pendingId = responseId(target.posts.at(-1)!);
+  const pendingFailure = expect(pending).rejects.toMatchObject({ code: 'disposed' });
 
   target.emit({
     id: 'close-1',
@@ -390,14 +573,28 @@ it('acknowledges host teardown before disposing and makes disposal idempotent',
     method: 'ui/resource-teardown',
     params: {},
   });
-  expect(target.posts.at(-1)).toEqual({
-    message: { id: 'close-1', jsonrpc: '2.0', result: {} },
-    targetOrigin: hostOrigin,
-  });
+  expect(target.posts.slice(-2)).toEqual([
+    {
+      message: { id: 'close-1', jsonrpc: '2.0', result: {} },
+      targetOrigin: hostOrigin,
+    },
+    {
+      message: {
+        jsonrpc: '2.0',
+        method: 'notifications/cancelled',
+        params: { reason: 'disposed', requestId: pendingId },
+      },
+      targetOrigin: hostOrigin,
+    },
+  ]);
+  expect(target.posts.at(-1)?.targetOrigin).not.toBe('*');
+  await pendingFailure;
   expect(client.disposed).toBe(true);
   expect(client.connected).toBe(false);
   expect(target.listenerCount()).toBe(0);
+  const postCount = target.posts.length;
   client.dispose();
+  expect(target.posts).toHaveLength(postCount);
   await expect(client.connect()).rejects.toBeInstanceOf(AppClientError);
   await expect(client.connect()).rejects.toMatchObject({ code: 'disposed' });
 });
diff --git a/packages/agent-bundle/tests/entries.test.ts b/packages/agent-bundle/tests/entries.test.ts
index 8f5e5638c..1401d6e4c 100644
--- a/packages/agent-bundle/tests/entries.test.ts
+++ b/packages/agent-bundle/tests/entries.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from '@rstest/core';
 
-import { runtimeIgnoredRoot } from '../src/build/entries.ts';
+import { runtimeIgnoredRoot } from '../src/build/runtime-path.ts';
 
 describe('runtime ignored root', () => {
   it('anchors a source runtime to its package when the checkout is under dist', () => {
diff --git a/packages/agent-bundle/tests/generated-route-server.test.ts b/packages/agent-bundle/tests/generated-route-server.test.ts
index 2baf377e5..14d5b37ba 100644
--- a/packages/agent-bundle/tests/generated-route-server.test.ts
+++ b/packages/agent-bundle/tests/generated-route-server.test.ts
@@ -6,6 +6,7 @@ import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 
 import { afterEach, expect, it } from '@rstest/core';
+import ts from 'typescript-5';
 
 import { build } from '../src/api.ts';
 import {
@@ -220,6 +221,7 @@ const writeGeneratedProject = async (
     writeProjectFile(root, 'package.json', JSON.stringify({
       dependencies: {
         '@agent-bundle/runtime': 'workspace:*',
+        'agent-bundle': 'workspace:*',
         '@modelcontextprotocol/server': '2.0.0',
         react: '19.2.8',
         zod: '4.4.3',
@@ -309,6 +311,65 @@ const expectFailClosed = (outcome: unknown, message: RegExp): void => {
   expect(JSON.stringify(outcome)).toMatch(message);
 };
 
+/**
+ * Type-checks one generated-route App entry against the project's own
+ * `.agent-bundle/routes.d.ts` — the `AppRegister` augmentation
+ * `createAppClient().call` consumes. No manual `declare module`.
+ */
+const typecheckGeneratedApp = (root: string, entry: string): readonly string[] => {
+  const program = ts.createProgram(
+    [join(root, entry), join(root, '.agent-bundle', 'routes.d.ts')],
+    {
+      exactOptionalPropertyTypes: true,
+      module: ts.ModuleKind.NodeNext,
+      moduleResolution: ts.ModuleResolutionKind.NodeNext,
+      noEmit: true,
+      skipLibCheck: true,
+      strict: true,
+      target: ts.ScriptTarget.ES2022,
+    },
+  );
+  return ts.getPreEmitDiagnostics(program)
+    .map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
+};
+
+const appRegisterEquality = [
+  'type Equal<Left, Right> =',
+  '  (<Value>() => Value extends Left ? 1 : 2) extends',
+  '  (<Value>() => Value extends Right ? 1 : 2) ? true : false;',
+  'type Assert<Value extends true> = Value;',
+];
+
+const generatedAppClientSource = [
+  "import { createAppClient } from 'agent-bundle/app';",
+  "export const config = { resourceUri: 'ui://generated-routes-fixture/dashboard.html', template: './dashboard.html' };",
+  "const state = document.querySelector('#state')!;",
+  "const client = createAppClient({ appInfo: { name: 'generated-app-client', version: '1.0.0' } });",
+  "client.onToolResult('tool:curator/ping', (result) => {",
+  "  state.dataset.opened = result.note;",
+  '});',
+  'await client.connect();',
+  "const called = await client.call('tool:curator/ping', { note: 'from-app' });",
+  'state.textContent = JSON.stringify(called);',
+  '',
+].join('\n');
+
+const generatedAppClientHtml = '<!doctype html><html><body><pre id="state">waiting</pre></body></html>\n';
+
+const generatedPingTool = [
+  "import { Agent } from '@agent-bundle/runtime';",
+  "import { appResourceUri } from 'agent-bundle/routes';",
+  "import { createElement } from 'react';",
+  "import { z } from 'zod';",
+  "export const config = { _meta: { ui: { resourceUri: appResourceUri('dashboard') } }, description: 'Ping from the App.' };",
+  'export const inputSchema = z.object({ note: z.string() }).strict();',
+  'export const resultSchema = z.object({ note: z.string() }).strict();',
+  'export default async function Ping({ input }: { input: z.infer<typeof inputSchema> }) {',
+  "  return createElement(Agent.Result, { value: { note: input.note } }, createElement(Agent.Text, null, input.note));",
+  '}',
+  '',
+].join('\n');
+
 it('augments a generated server from config and projects result _meta and text-only tools to the wire', { retry: 2, timeout: 60_000 }, async () => {
   const root = await mkdtemp(join(tmpdir(), 'agent-bundle-generated-augment-'));
   roots.push(root);
@@ -519,6 +580,89 @@ it('compiles appResourceUri() and imported-const references to the App route res
   }
 });
 
+it('compiles createAppClient().call against generated AppRegister contracts without a manual augmentation', { retry: 2, timeout: 60_000 }, async () => {
+  const root = await mkdtemp(join(tmpdir(), 'agent-bundle-generated-app-client-'));
+  roots.push(root);
+  await writeGeneratedProject(root, {
+    'src/mcp/curator/apps/dashboard.html': generatedAppClientHtml,
+    'src/mcp/curator/apps/dashboard.ts': generatedAppClientSource,
+    'src/mcp/curator/tools/ping.ts': generatedPingTool,
+    'src/app-client-call.ts': [
+      "import { createAppClient, type AppRegister } from 'agent-bundle/app';",
+      ...appRegisterEquality,
+      "export type AppIds = Assert<Equal<keyof AppRegister['routes'], 'tool:curator/ping'>>;",
+      "export type AppPing = Assert<Equal<AppRegister['routes']['tool:curator/ping'], Readonly<{ input: { note: string }; result: { note: string } }>>>;",
+      'const client = createAppClient();',
+      "export const called = client.call('tool:curator/ping', { note: 'from-app' });",
+      '',
+    ].join('\n'),
+    'src/wrong-app-id.ts': [
+      "import { createAppClient } from 'agent-bundle/app';",
+      'const client = createAppClient();',
+      "void client.call('tool:curator/missing', { note: 'from-app' });",
+      '',
+    ].join('\n'),
+    'src/wrong-app-input.ts': [
+      "import { createAppClient } from 'agent-bundle/app';",
+      'const client = createAppClient();',
+      "void client.call('tool:curator/ping', { note: 1 });",
+      '',
+    ].join('\n'),
+  });
+
+  const output = join(root, 'artifact');
+  const compiled = await build({ output, root, targets: ['portable'] });
+  const generatedTypes = await readFile(join(root, '.agent-bundle', 'routes.d.ts'), 'utf8');
+  expect(generatedTypes).toContain('tool:curator/ping');
+  expect(generatedTypes).toContain("declare module 'agent-bundle/app' {\n  interface AppRegister {\n    readonly routes: AgentBundleAppRouteContracts;\n  }\n}");
+  expect(generatedAppClientSource).not.toContain('declare module');
+  expect(generatedAppClientSource).not.toMatch(/\bzod\b/u);
+  expect(generatedAppClientSource).not.toMatch(/@modelcontextprotocol\/server/u);
+  expect(generatedTypes.split('\n').filter((line) => line.startsWith('import')).every((line) => line.startsWith('import type * as '))).toBe(true);
+
+  expect(typecheckGeneratedApp(root, 'src/app-client-call.ts')).toEqual([]);
+  const wrongId = typecheckGeneratedApp(root, 'src/wrong-app-id.ts');
+  expect(wrongId).toHaveLength(1);
+  expect(wrongId[0]).toMatch(/tool:curator\/missing/u);
+  const wrongInput = typecheckGeneratedApp(root, 'src/wrong-app-input.ts');
+  expect(wrongInput).toHaveLength(1);
+  expect(wrongInput[0]).toMatch(/Type 'number' is not assignable to type 'string'/u);
+
+  const html = await readFile(join(output, 'portable', 'mcp-apps', 'dashboard.html'), 'utf8');
+  expect(html).toContain('2026-01-26');
+  expect(html).toContain('from-app');
+  expect([
+    /\bnode:/u,
+    /["']effect(?:\/|["'])/u,
+    /["']zod(?:\/|["'])/u,
+    /mcp-server-runtime|mcp-schema-projection/u,
+  ].filter((pattern) => pattern.test(html))).toEqual([]);
+
+  const server = compiled.model.mcpServers[0]!;
+  const client = new Client({ name: 'generated-app-client-test', version: '0.0.0' });
+  const transport = new StdioClientTransport({
+    args: [join(output, 'portable', server.args![0]!)],
+    command: process.execPath,
+    stderr: 'pipe',
+  });
+  let diagnostics = '';
+  transport.stderr?.on('data', (chunk) => { diagnostics += String(chunk); });
+  try {
+    try {
+      await client.connect(transport);
+    } catch (error) {
+      throw new Error(`Generated App client fixture failed to connect: ${diagnostics}`, { cause: error });
+    }
+    await expect(client.callTool({ arguments: { note: 'from-stdio' }, name: 'ping' }, { signal: AbortSignal.timeout(10_000) }))
+      .resolves.toMatchObject({ structuredContent: { note: 'from-stdio' } });
+    await expect(client.readResource({ uri: 'ui://generated-routes-fixture/dashboard.html' })).resolves.toMatchObject({
+      contents: [{ text: expect.stringContaining('from-app'), uri: 'ui://generated-routes-fixture/dashboard.html' }],
+    });
+  } finally {
+    await client.close();
+  }
+});
+
 it('observes one process-lifetime provider across consecutive generated tool calls', { retry: 2, timeout: 60_000 }, async () => {
   const root = await mkdtemp(join(tmpdir(), 'agent-bundle-generated-warm-'));
   roots.push(root);
diff --git a/packages/agent-bundle/tests/mcp-app-binding-service.test.ts b/packages/agent-bundle/tests/mcp-app-binding-service.test.ts
index 85f0d22c3..ee7e66fed 100644
--- a/packages/agent-bundle/tests/mcp-app-binding-service.test.ts
+++ b/packages/agent-bundle/tests/mcp-app-binding-service.test.ts
@@ -10,7 +10,9 @@ import {
 } from '../src/dev/mcp-apps/mcp-app-binding-service.ts';
 
 interface SessionFixture {
+  readonly callSignals: Array<AbortSignal | undefined>;
   readonly calls: Array<{ readonly arguments: McpAppJsonValue | undefined; readonly name: string }>;
+  readonly readSignals: Array<AbortSignal | undefined>;
   readonly reads: string[];
   readonly releases: number[];
   readonly sessionCloseCalls: number[];
@@ -36,7 +38,9 @@ const createSessionFixture = (
   options: { readonly closeBeforeObservation?: boolean; readonly releaseFailures?: number } = {},
 ): SessionFixture => {
   const closeListeners = new Set<(reason?: unknown) => Promise<void> | void>();
+  const callSignals: Array<AbortSignal | undefined> = [];
   const calls: Array<{ readonly arguments: McpAppJsonValue | undefined; readonly name: string }> = [];
+  const readSignals: Array<AbortSignal | undefined> = [];
   const reads: string[] = [];
   const releases: number[] = [];
   const sessionCloseCalls: number[] = [];
@@ -45,7 +49,9 @@ const createSessionFixture = (
   let sessionClosed = false;
 
   return {
+    callSignals,
     calls,
+    readSignals,
     reads,
     releases,
     sessionCloseCalls,
@@ -63,8 +69,12 @@ const createSessionFixture = (
           }
         },
         session: {
-          callTool: async ({ arguments: toolArguments, name }) => {
+          callTool: async ({ arguments: toolArguments, name, signal }) => {
+            callSignals.push(signal);
             calls.push({ arguments: toolArguments, name });
+            if (signal?.aborted) {
+              throw signal.reason instanceof Error ? signal.reason : new Error('fixture tool call was aborted');
+            }
             if (name === 'round-trip') return toolArguments ?? null;
             return { content: [{ text: `called ${name}`, type: 'text' }] };
           },
@@ -84,8 +94,12 @@ const createSessionFixture = (
             { appVisible: true, definition: { name: 'round-trip' }, name: 'round-trip' },
             { appVisible: false, definition: { name: 'delete-weather' }, name: 'delete-weather' },
           ],
-          readResource: async ({ uri }) => {
+          readResource: async ({ uri, signal }) => {
+            readSignals.push(signal);
             reads.push(uri);
+            if (signal?.aborted) {
+              throw signal.reason instanceof Error ? signal.reason : new Error('fixture resource read was aborted');
+            }
             return { contents: [{ text: uri, type: 'text' }] };
           },
         },
@@ -312,3 +326,113 @@ it('keeps a failed session-close release retryable while bridge calls stay inval
   expect(teardownEvents).toEqual([{ bindingPresent: false, reason: 'session-closed' }]);
   expect(fixture.watcherOrder).toEqual(['watch', 'unsubscribe', 'release', 'release']);
 });
+
+it('threads an AbortSignal through app-visible session tool and resource calls', async () => {
+  const fixture = createSessionFixture();
+  const service = new McpAppBindingService({ sessionAuthority: authorityFor(fixture) });
+  const binding = await service.createBinding({
+    input: {},
+    previewProfile: 'portable',
+    result: {},
+    sessionId: 'session-weather',
+    tool: appTool,
+  });
+  const controller = new AbortController();
+
+  await expect(service.callTool(binding.id, { arguments: { force: true }, name: 'refresh-weather' }, controller.signal))
+    .resolves.toEqual({ content: [{ text: 'called refresh-weather', type: 'text' }] });
+  await expect(service.readResource(binding.id, { uri: 'resource://weather/forecast' }, controller.signal))
+    .resolves.toEqual({ contents: [{ text: 'resource://weather/forecast', type: 'text' }] });
+  expect(fixture.callSignals).toEqual([controller.signal]);
+  expect(fixture.readSignals).toEqual([controller.signal]);
+  expect(fixture.calls).toEqual([{ arguments: { force: true }, name: 'refresh-weather' }]);
+  expect(fixture.reads).toEqual(['resource://weather/forecast']);
+});
+
+it('rejects an already-aborted signal before listing or invoking the session', async () => {
+  const fixture = createSessionFixture();
+  const service = new McpAppBindingService({ sessionAuthority: authorityFor(fixture) });
+  const binding = await service.createBinding({
+    input: {},
+    previewProfile: 'portable',
+    result: {},
+    sessionId: 'session-weather',
+    tool: appTool,
+  });
+  const controller = new AbortController();
+  controller.abort(new Error('already cancelled'));
+
+  await expect(service.callTool(binding.id, { arguments: {}, name: 'refresh-weather' }, controller.signal))
+    .rejects.toThrow('already cancelled');
+  await expect(service.readResource(binding.id, { uri: 'resource://weather/forecast' }, controller.signal))
+    .rejects.toThrow('already cancelled');
+  expect(fixture.calls).toEqual([]);
+  expect(fixture.reads).toEqual([]);
+  expect(fixture.callSignals).toEqual([]);
+  expect(fixture.readSignals).toEqual([]);
+});
+
+it('does not invoke the session tool when the signal aborts during capability listing', async () => {
+  const fixture = createSessionFixture();
+  const toolController = new AbortController();
+  const readController = new AbortController();
+  let abortOnList = false;
+  const listingAuthority: McpAppSessionAuthority = {
+    acquireAppLease: async (sessionId) => {
+      if (sessionId !== 'session-weather') throw new Error(`Unknown session ${sessionId}.`);
+      const lease = fixture.createLease();
+      return {
+        ...lease,
+        session: {
+          ...lease.session,
+          listBridgeTools: async () => {
+            if (abortOnList) toolController.abort(new Error('cancelled during list'));
+            return lease.session.listBridgeTools();
+          },
+          listBridgeResources: async () => {
+            if (abortOnList) readController.abort(new Error('cancelled during list'));
+            return lease.session.listBridgeResources();
+          },
+        },
+      };
+    },
+  };
+  const service = new McpAppBindingService({ sessionAuthority: listingAuthority });
+  const binding = await service.createBinding({
+    input: {},
+    previewProfile: 'portable',
+    result: {},
+    sessionId: 'session-weather',
+    tool: appTool,
+  });
+  abortOnList = true;
+
+  await expect(service.callTool(binding.id, { name: 'refresh-weather' }, toolController.signal))
+    .rejects.toThrow('cancelled during list');
+  await expect(service.readResource(binding.id, { uri: 'resource://weather/forecast' }, readController.signal))
+    .rejects.toThrow('cancelled during list');
+  expect(fixture.calls).toEqual([]);
+  expect(fixture.reads).toEqual([]);
+});
+
+it('still refuses hidden tools and resources when a live AbortSignal is supplied', async () => {
+  const fixture = createSessionFixture();
+  const service = new McpAppBindingService({ sessionAuthority: authorityFor(fixture) });
+  const binding = await service.createBinding({
+    input: {},
+    previewProfile: 'portable',
+    result: {},
+    sessionId: 'session-weather',
+    tool: appTool,
+  });
+  const controller = new AbortController();
+
+  await expect(service.callTool(binding.id, { arguments: {}, name: 'delete-weather' }, controller.signal))
+    .rejects.toThrow('not app-visible');
+  await expect(service.readResource(binding.id, { uri: 'resource://weather/private' }, controller.signal))
+    .rejects.toThrow('not app-visible');
+  expect(fixture.calls).toEqual([]);
+  expect(fixture.reads).toEqual([]);
+  expect(fixture.callSignals).toEqual([]);
+  expect(fixture.readSignals).toEqual([]);
+});
diff --git a/packages/agent-bundle/tests/mcp-app-bridge-cancellation.test.ts b/packages/agent-bundle/tests/mcp-app-bridge-cancellation.test.ts
new file mode 100644
index 000000000..133f1348f
--- /dev/null
+++ b/packages/agent-bundle/tests/mcp-app-bridge-cancellation.test.ts
@@ -0,0 +1,533 @@
+import { expect, it } from '@rstest/core';
+
+import { createMcpAppConsentAuthority } from '../src/dev/mcp-apps/mcp-app-sandbox.ts';
+import {
+  createMcpAppBridge,
+  type McpAppBridgeBindingOperations,
+  type McpAppBridgeHost,
+  type McpAppBridgeMessage,
+  type McpAppBridgeRequestId,
+} from '../src/dev/mcp-apps/mcp-app-bridge.ts';
+import type { McpAppBinding, McpAppJsonValue } from '../src/dev/mcp-apps/mcp-app-binding-service.ts';
+
+interface HeldOperation {
+  readonly signal: AbortSignal | undefined;
+  reject(error: Error): void;
+  resolve(value: McpAppJsonValue): void;
+}
+
+interface BridgeFixture {
+  readonly binding: McpAppBinding;
+  readonly calls: Array<{
+    readonly arguments: McpAppJsonValue | undefined;
+    readonly bindingId: string;
+    readonly name: string;
+    readonly signal: AbortSignal | undefined;
+  }>;
+  readonly heldCalls: HeldOperation[];
+  readonly heldReads: HeldOperation[];
+  readonly host: McpAppBridgeHost;
+  readonly operations: McpAppBridgeBindingOperations;
+  readonly reads: Array<{
+    readonly bindingId: string;
+    readonly signal: AbortSignal | undefined;
+    readonly uri: string;
+  }>;
+  readonly sent: McpAppBridgeMessage[];
+}
+
+const bindingFor = (): McpAppBinding => ({
+  epochId: 'epoch-app',
+  id: 'binding-app',
+  input: { city: 'Paris', units: 'metric' },
+  previewProfile: 'portable',
+  resourceUri: 'ui://weather/forecast.html',
+  result: { content: [{ text: 'Sunny', type: 'text' }], structuredContent: { temperature: 21 } },
+  serverName: 'weather',
+  sessionId: 'session-weather',
+  target: 'portable',
+  toolDefinition: {
+    _meta: { ui: { resourceUri: 'ui://weather/forecast.html' } },
+    inputSchema: { type: 'object' },
+    name: 'show-weather',
+  },
+  toolName: 'show-weather',
+});
+
+const fixtureFor = (options: {
+  readonly host?: Partial<McpAppBridgeHost>;
+  readonly holdCalls?: boolean;
+  readonly holdReads?: boolean;
+} = {}): BridgeFixture => {
+  const calls: BridgeFixture['calls'] = [];
+  const heldCalls: HeldOperation[] = [];
+  const heldReads: HeldOperation[] = [];
+  const reads: BridgeFixture['reads'] = [];
+  const sent: McpAppBridgeMessage[] = [];
+  const defaultResource: McpAppJsonValue = {
+    contents: [{
+      mimeType: 'text/html;profile=mcp-app',
+      text: '<main>forecast</main>',
+      uri: 'ui://weather/forecast.html',
+    }],
+  };
+  const hold = (bucket: HeldOperation[], signal: AbortSignal | undefined): Promise<McpAppJsonValue> =>
+    new Promise<McpAppJsonValue>((resolve, reject) => {
+      bucket.push({ reject, resolve, signal });
+    });
+  const host: McpAppBridgeHost = {
+    capabilities: { openLinks: {}, serverResources: {}, serverTools: {} },
+    context: { availableDisplayModes: ['inline', 'fullscreen'], displayMode: 'inline', theme: 'light' },
+    info: { name: 'agent-bundle', version: '0.1.0' },
+    onDisplayMode: async (mode) => mode,
+    onDownload: async () => undefined,
+    onMessage: async () => ({ isError: false }),
+    onModelContext: async () => undefined,
+    onOpenLink: async () => undefined,
+    ...options.host,
+  };
+  const operations: McpAppBridgeBindingOperations = {
+    callTool: async (bindingId, request, signal) => {
+      calls.push({ arguments: request.arguments, bindingId, name: request.name, signal });
+      if (options.holdCalls) return hold(heldCalls, signal);
+      return { content: [{ text: `called ${request.name}`, type: 'text' }] };
+    },
+    closeBinding: async () => true,
+    readResource: async (bindingId, request, signal) => {
+      reads.push({ bindingId, signal, uri: request.uri });
+      if (options.holdReads) return hold(heldReads, signal);
+      return defaultResource;
+    },
+  };
+  return { binding: bindingFor(), calls, heldCalls, heldReads, host, operations, reads, sent };
+};
+
+const initialize = (id: McpAppBridgeRequestId): McpAppBridgeMessage => ({
+  id,
+  jsonrpc: '2.0',
+  method: 'ui/initialize',
+  params: {
+    appCapabilities: { availableDisplayModes: ['inline', 'fullscreen'] },
+    appInfo: { name: 'weather-view', version: '1.0.0' },
+    protocolVersion: '2026-01-26',
+  },
+});
+
+const initialized = (): McpAppBridgeMessage => ({
+  jsonrpc: '2.0',
+  method: 'ui/notifications/initialized',
+});
+
+const cancelled = (
+  requestId: McpAppBridgeRequestId,
+  reason?: string,
+): McpAppBridgeMessage => ({
+  jsonrpc: '2.0',
+  method: 'notifications/cancelled',
+  params: reason === undefined ? { requestId } : { reason, requestId },
+});
+
+const readyBridge = async (fixture: BridgeFixture) => {
+  const bridge = createMcpAppBridge({
+    binding: fixture.binding,
+    host: fixture.host,
+    operations: fixture.operations,
+    send: (message) => {
+      fixture.sent.push(message);
+      return true;
+    },
+  });
+  expect(await bridge.receive(initialize('init:ready'))).toBe(true);
+  expect(await bridge.receive(initialized())).toBe(true);
+  return bridge;
+};
+
+const responsesFor = (fixture: BridgeFixture, id: McpAppBridgeRequestId): readonly McpAppBridgeMessage[] =>
+  fixture.sent.filter((message) => message.id === id);
+
+it('accepts a valid repeated ui/initialize while initializing and resets queued opening frames', async () => {
+  const fixture = fixtureFor();
+  const bridge = createMcpAppBridge({
+    binding: fixture.binding,
+    host: fixture.host,
+    operations: fixture.operations,
+    send: (message) => (fixture.sent.push(message), true),
+  });
+
+  expect(bridge.publishToolInputPartial({ city: 'Par' })).toBe(true);
+  expect(await bridge.receive(initialize('init:first'))).toBe(true);
+  expect(bridge.lifecycle).toBe('initializing');
+  expect(bridge.publishToolInputPartial({ city: 'Pari' })).toBe(true);
+  expect(await bridge.receive(initialize('init:retry'))).toBe(true);
+  expect(bridge.lifecycle).toBe('initializing');
+  expect(fixture.sent.at(-1)).toEqual({
+    id: 'init:retry',
+    jsonrpc: '2.0',
+    result: {
+      hostCapabilities: { openLinks: {}, serverResources: {}, serverTools: {} },
+      hostContext: { availableDisplayModes: ['inline', 'fullscreen'], displayMode: 'inline', theme: 'light' },
+      hostInfo: { name: 'agent-bundle', version: '0.1.0' },
+      protocolVersion: '2026-01-26',
+    },
+  });
+
+  expect(await bridge.receive(initialized())).toBe(true);
+  expect(bridge.lifecycle).toBe('initialized');
+  expect(fixture.sent.filter((message) => message.method === 'ui/notifications/tool-input-partial')).toEqual([]);
+  expect(fixture.sent.slice(-2)).toEqual([
+    { jsonrpc: '2.0', method: 'ui/notifications/tool-input', params: { arguments: { city: 'Paris', units: 'metric' } } },
+    {
+      jsonrpc: '2.0',
+      method: 'ui/notifications/tool-result',
+      params: { content: [{ text: 'Sunny', type: 'text' }], structuredContent: { temperature: 21 } },
+    },
+  ]);
+});
+
+it('rejects an invalid repeated ui/initialize during initializing without leaving the handshake', async () => {
+  const fixture = fixtureFor();
+  const bridge = createMcpAppBridge({
+    binding: fixture.binding,
+    host: fixture.host,
+    operations: fixture.operations,
+    send: (message) => (fixture.sent.push(message), true),
+  });
+  expect(await bridge.receive(initialize('init:valid'))).toBe(true);
+  expect(await bridge.receive({
+    id: 'init:bad',
+    jsonrpc: '2.0',
+    method: 'ui/initialize',
+    params: { appCapabilities: {}, appInfo: { name: 'weather-view', version: '1.0.0' }, protocolVersion: '1999-01-01' },
+  })).toBe(true);
+  expect(bridge.lifecycle).toBe('initializing');
+  expect(fixture.sent.at(-1)).toEqual({
+    error: { code: -32602, message: 'ui/initialize requires protocol version 2026-01-26.' },
+    id: 'init:bad',
+    jsonrpc: '2.0',
+  });
+  expect(await bridge.receive(initialized())).toBe(true);
+  expect(bridge.lifecycle).toBe('initialized');
+});
+
+it('resets queued opening frames on initialized re-init the same way as an initializing retry', async () => {
+  const fixture = fixtureFor();
+  const bridge = createMcpAppBridge({
+    binding: fixture.binding,
+    host: fixture.host,
+    operations: fixture.operations,
+    send: (message) => (fixture.sent.push(message), true),
+  });
+  expect(await bridge.receive(initialize('init:first'))).toBe(true);
+  expect(await bridge.receive(initialized())).toBe(true);
+  expect(bridge.publishHostContextChanged({ theme: 'dark' })).toBe(true);
+  expect(await bridge.receive(initialize('init:rebind'))).toBe(true);
+  expect(bridge.lifecycle).toBe('initializing');
+  expect(await bridge.receive(initialized())).toBe(true);
+  expect(fixture.sent.filter((message) => message.method === 'ui/notifications/host-context-changed')).toEqual([
+    { jsonrpc: '2.0', method: 'ui/notifications/host-context-changed', params: { theme: 'dark' } },
+  ]);
+  expect(fixture.sent.filter((message) => message.method === 'ui/notifications/tool-input')).toHaveLength(2);
+  expect(fixture.sent.filter((message) => message.method === 'ui/notifications/tool-result')).toHaveLength(2);
+});
+
+it('ignores cancellation before the App is initialized and never treats cancelled as a request', async () => {
+  const fixture = fixtureFor();
+  const bridge = createMcpAppBridge({
+    binding: fixture.binding,
+    host: fixture.host,
+    operations: fixture.operations,
+    send: (message) => (fixture.sent.push(message), true),
+  });
+  expect(await bridge.receive(cancelled('never-started', 'aborted'))).toBe(false);
+  expect(await bridge.receive(initialize('init:cancel-early'))).toBe(true);
+  expect(await bridge.receive(cancelled('init:cancel-early'))).toBe(false);
+  expect(await bridge.receive({
+    id: 'cancelled-as-request',
+    jsonrpc: '2.0',
+    method: 'notifications/cancelled',
+    params: { requestId: 'cancelled-as-request' },
+  })).toBe(false);
+  expect(await bridge.receive(initialized())).toBe(true);
+  expect(fixture.sent.some((message) => message.error !== undefined)).toBe(false);
+});
+
+it('rejects malformed cancelled notifications without aborting a live request', async () => {
+  const fixture = fixtureFor({ holdCalls: true });
+  const bridge = await readyBridge(fixture);
+  const pending = bridge.receive({
+    id: 'call:live',
+    jsonrpc: '2.0',
+    method: 'tools/call',
+    params: { name: 'refresh-weather' },
+  });
+  expect(await bridge.receive({ jsonrpc: '2.0', method: 'notifications/cancelled' })).toBe(false);
+  expect(await bridge.receive({ jsonrpc: '2.0', method: 'notifications/cancelled', params: {} })).toBe(false);
+  expect(await bridge.receive({ jsonrpc: '2.0', method: 'notifications/cancelled', params: { requestId: { forged: true } } })).toBe(false);
+  expect(await bridge.receive({ jsonrpc: '2.0', method: 'notifications/cancelled', params: { reason: ' ', requestId: 'call:live' } })).toBe(false);
+  expect(await bridge.receive({ jsonrpc: '2.0', method: 'notifications/cancelled', params: { reason: 1, requestId: 'call:live' } })).toBe(false);
+  expect(fixture.heldCalls).toHaveLength(1);
+  expect(fixture.heldCalls[0]?.signal?.aborted).toBe(false);
+  fixture.heldCalls[0]?.resolve({ content: [{ text: 'survived', type: 'text' }] });
+  expect(await pending).toBe(true);
+  expect(responsesFor(fixture, 'call:live')).toEqual([
+    { id: 'call:live', jsonrpc: '2.0', result: { content: [{ text: 'survived', type: 'text' }] } },
+  ]);
+});
+
+it('accepts a well-formed cancelled notification for an unknown request id as a no-op', async () => {
+  const fixture = fixtureFor();
+  const bridge = await readyBridge(fixture);
+  const before = fixture.sent.length;
+  expect(await bridge.receive(cancelled(null))).toBe(true);
+  expect(await bridge.receive(cancelled(0, 'aborted'))).toBe(true);
+  expect(await bridge.receive(cancelled('missing', 'timeout'))).toBe(true);
+  expect(fixture.sent).toHaveLength(before);
+  expect(fixture.calls).toEqual([]);
+});
+
+it('cancels a running tools/call, aborts the binding signal, and drops a late result', async () => {
+  const fixture = fixtureFor({ holdCalls: true });
+  const bridge = await readyBridge(fixture);
+  const pending = bridge.receive({
+    id: 7,
+    jsonrpc: '2.0',
+    method: 'tools/call',
+    params: { arguments: { city: 'Lyon' }, name: 'refresh-weather' },
+  });
+  expect(fixture.heldCalls).toHaveLength(1);
+  expect(await bridge.receive(cancelled(7, 'timeout'))).toBe(true);
+  expect(fixture.heldCalls[0]?.signal?.aborted).toBe(true);
+  expect(fixture.heldCalls[0]?.signal?.reason).toEqual(new Error('timeout'));
+  fixture.heldCalls[0]?.resolve({ content: [{ text: 'late', type: 'text' }] });
+  expect(await pending).toBe(false);
+  expect(responsesFor(fixture, 7)).toEqual([]);
+  expect(await bridge.receive({ id: 8, jsonrpc: '2.0', method: 'ping' })).toBe(true);
+  expect(responsesFor(fixture, 8)).toEqual([{ id: 8, jsonrpc: '2.0', result: {} }]);
+});
+
+it('cancels a running resources/read and does not respond after a late resource body', async () => {
+  const fixture = fixtureFor({ holdReads: true });
+  const bridge = await readyBridge(fixture);
+  const pending = bridge.receive({
+    id: 'read:live',
+    jsonrpc: '2.0',
+    method: 'resources/read',
+    params: { uri: 'ui://weather/forecast.html' },
+  });
+  expect(await bridge.receive(cancelled('read:live', 'aborted'))).toBe(true);
+  expect(fixture.heldReads[0]?.signal?.aborted).toBe(true);
+  fixture.heldReads[0]?.resolve({
+    contents: [{ mimeType: 'text/html;profile=mcp-app', text: '<main>late</main>', uri: 'ui://weather/forecast.html' }],
+  });
+  expect(await pending).toBe(false);
+  expect(responsesFor(fixture, 'read:live')).toEqual([]);
+});
+
+it('cancels a tools/call before consent so a later approval cannot execute it', async () => {
+  const fixture = fixtureFor({ holdCalls: true });
+  const authority = createMcpAppConsentAuthority({ now: () => 1_000 });
+  const bridge = createMcpAppBridge({
+    binding: fixture.binding,
+    consentAuthority: authority,
+    host: fixture.host,
+    operations: fixture.operations,
+    profile: 'portable',
+    send: (message) => (fixture.sent.push(message), true),
+  });
+  await bridge.receive(initialize('init:consent-cancel'));
+  await bridge.receive(initialized());
+  expect(await bridge.receive({
+    id: 'tool:consent',
+    jsonrpc: '2.0',
+    method: 'tools/call',
+    params: { arguments: { city: 'Paris' }, name: 'refresh-weather' },
+  })).toBe(true);
+  const challenge = authority.pending().find((candidate) => candidate.request.capability === 'call-tool');
+  expect(challenge).toBeDefined();
+  expect(fixture.calls).toEqual([]);
+  expect(await bridge.receive(cancelled('tool:consent', 'aborted'))).toBe(true);
+  expect(authority.pending()).toEqual([]);
+  expect(await bridge.decideConsent(challenge?.id ?? '', true)).toBe(false);
+  expect(fixture.calls).toEqual([]);
+  expect(responsesFor(fixture, 'tool:consent')).toEqual([]);
+});
+
+it('cancels a privileged host action while its consent challenge is pending', async () => {
+  const links: string[] = [];
+  const fixture = fixtureFor({
+    host: {
+      onOpenLink: async (url) => {
+        links.push(url);
+      },
+    },
+  });
+  const authority = createMcpAppConsentAuthority({ now: () => 1_000 });
+  const bridge = createMcpAppBridge({
+    binding: fixture.binding,
+    consentAuthority: authority,
+    host: fixture.host,
+    operations: fixture.operations,
+    profile: 'portable',
+    send: (message) => (fixture.sent.push(message), true),
+  });
+  await bridge.receive(initialize('init:link-cancel'));
+  await bridge.receive(initialized());
+  await bridge.receive({
+    id: 'link:pending',
+    jsonrpc: '2.0',
+    method: 'ui/open-link',
+    params: { url: 'https://weather.example.test/forecast' },
+  });
+  const challenge = authority.pending().find((candidate) => candidate.request.capability === 'open-external-link');
+  expect(await bridge.receive(cancelled('link:pending'))).toBe(true);
+  expect(authority.pending()).toEqual([]);
+  expect(await bridge.decideConsent(challenge?.id ?? '', true)).toBe(false);
+  expect(links).toEqual([]);
+  expect(responsesFor(fixture, 'link:pending')).toEqual([]);
+});
+
+it('does not let a cancelled consent denial produce an RPC error after the request is gone', async () => {
+  const fixture = fixtureFor();
+  const authority = createMcpAppConsentAuthority({ now: () => 1_000 });
+  const bridge = createMcpAppBridge({
+    binding: fixture.binding,
+    consentAuthority: authority,
+    host: fixture.host,
+    operations: fixture.operations,
+    profile: 'portable',
+    send: (message) => (fixture.sent.push(message), true),
+  });
+  await bridge.receive(initialize('init:deny-after-cancel'));
+  await bridge.receive(initialized());
+  await bridge.receive({
+    id: 'download:cancel',
+    jsonrpc: '2.0',
+    method: 'ui/download-file',
+    params: { contents: [{ text: 'forecast', type: 'text' }] },
+  });
+  const challenge = authority.pending().find((candidate) => candidate.request.capability === 'download-file');
+  expect(await bridge.receive(cancelled('download:cancel', 'aborted'))).toBe(true);
+  expect(await bridge.decideConsent(challenge?.id ?? '', false)).toBe(false);
+  expect(responsesFor(fixture, 'download:cancel')).toEqual([]);
+});
+
+it('cancels only the named in-flight request and keeps a sibling request runnable', async () => {
+  const fixture = fixtureFor({ holdCalls: true });
+  const bridge = await readyBridge(fixture);
+  const first = bridge.receive({ id: 'call:a', jsonrpc: '2.0', method: 'tools/call', params: { name: 'refresh-weather' } });
+  const second = bridge.receive({ id: 'call:b', jsonrpc: '2.0', method: 'tools/call', params: { name: 'refresh-weather' } });
+  expect(fixture.heldCalls).toHaveLength(2);
+  expect(await bridge.receive(cancelled('call:a', 'aborted'))).toBe(true);
+  expect(fixture.heldCalls[0]?.signal?.aborted).toBe(true);
+  expect(fixture.heldCalls[1]?.signal?.aborted).toBe(false);
+  fixture.heldCalls[0]?.resolve({ content: [{ text: 'late-a', type: 'text' }] });
+  fixture.heldCalls[1]?.resolve({ content: [{ text: 'kept-b', type: 'text' }] });
+  expect(await first).toBe(false);
+  expect(await second).toBe(true);
+  expect(responsesFor(fixture, 'call:a')).toEqual([]);
+  expect(responsesFor(fixture, 'call:b')).toEqual([
+    { id: 'call:b', jsonrpc: '2.0', result: { content: [{ text: 'kept-b', type: 'text' }] } },
+  ]);
+});
+
+it('rejects a duplicate running request id with one -32602 and suppresses the original result', async () => {
+  const fixture = fixtureFor({ holdCalls: true });
+  const bridge = await readyBridge(fixture);
+  const pending = bridge.receive({ id: 'shared', jsonrpc: '2.0', method: 'tools/call', params: { name: 'refresh-weather' } });
+  expect(await bridge.receive({ id: 'shared', jsonrpc: '2.0', method: 'tools/call', params: { name: 'refresh-weather' } })).toBe(true);
+  expect(fixture.heldCalls).toHaveLength(1);
+  expect(fixture.heldCalls[0]?.signal?.aborted).toBe(true);
+  expect(fixture.calls).toHaveLength(1);
+  expect(responsesFor(fixture, 'shared')).toEqual([
+    { error: { code: -32602, message: 'MCP App request id is already in flight.' }, id: 'shared', jsonrpc: '2.0' },
+  ]);
+  fixture.heldCalls[0]?.resolve({ content: [{ text: 'original', type: 'text' }] });
+  expect(await pending).toBe(false);
+  expect(responsesFor(fixture, 'shared')).toEqual([
+    { error: { code: -32602, message: 'MCP App request id is already in flight.' }, id: 'shared', jsonrpc: '2.0' },
+  ]);
+});
+
+it('rejects a duplicate consent-pending request id with one -32602 and drops the original challenge', async () => {
+  const fixture = fixtureFor({ holdCalls: true });
+  const authority = createMcpAppConsentAuthority({ now: () => 1_000 });
+  const bridge = createMcpAppBridge({
+    binding: fixture.binding,
+    consentAuthority: authority,
+    host: fixture.host,
+    operations: fixture.operations,
+    profile: 'portable',
+    send: (message) => (fixture.sent.push(message), true),
+  });
+  await bridge.receive(initialize('init:duplicate-consent'));
+  await bridge.receive(initialized());
+  expect(await bridge.receive({
+    id: 'shared-consent',
+    jsonrpc: '2.0',
+    method: 'tools/call',
+    params: { arguments: { city: 'Paris' }, name: 'refresh-weather' },
+  })).toBe(true);
+  const challenge = authority.pending().find((candidate) => candidate.request.capability === 'call-tool');
+  expect(challenge).toBeDefined();
+  expect(fixture.calls).toEqual([]);
+  expect(await bridge.receive({
+    id: 'shared-consent',
+    jsonrpc: '2.0',
+    method: 'tools/call',
+    params: { arguments: { city: 'Lyon' }, name: 'refresh-weather' },
+  })).toBe(true);
+  expect(authority.pending()).toEqual([]);
+  expect(await bridge.decideConsent(challenge?.id ?? '', true)).toBe(false);
+  expect(fixture.calls).toEqual([]);
+  expect(responsesFor(fixture, 'shared-consent')).toEqual([
+    { error: { code: -32602, message: 'MCP App request id is already in flight.' }, id: 'shared-consent', jsonrpc: '2.0' },
+  ]);
+});
+
+it('aborts in-flight work on re-init so a late result cannot answer the rebound App', async () => {
+  const fixture = fixtureFor({ holdCalls: true });
+  const bridge = await readyBridge(fixture);
+  const pending = bridge.receive({ id: 'call:stale', jsonrpc: '2.0', method: 'tools/call', params: { name: 'refresh-weather' } });
+  expect(await bridge.receive(initialize('init:rebound'))).toBe(true);
+  expect(bridge.lifecycle).toBe('initializing');
+  expect(fixture.heldCalls[0]?.signal?.aborted).toBe(true);
+  fixture.heldCalls[0]?.resolve({ content: [{ text: 'stale', type: 'text' }] });
+  expect(await pending).toBe(false);
+  expect(responsesFor(fixture, 'call:stale')).toEqual([]);
+  expect(await bridge.receive(initialized())).toBe(true);
+  expect(responsesFor(fixture, 'call:stale')).toEqual([]);
+});
+
+it('aborts in-flight requests on force close and still suppresses their late replies', async () => {
+  const fixture = fixtureFor({ holdCalls: true });
+  const bridge = await readyBridge(fixture);
+  const pending = bridge.receive({ id: 'call:closing', jsonrpc: '2.0', method: 'tools/call', params: { name: 'refresh-weather' } });
+  const closing = bridge.forceClose();
+  expect(fixture.heldCalls[0]?.signal?.aborted).toBe(true);
+  fixture.heldCalls[0]?.resolve({ content: [{ text: 'after-close', type: 'text' }] });
+  expect(await pending).toBe(false);
+  await closing;
+  expect(responsesFor(fixture, 'call:closing')).toEqual([]);
+});
+
+it('does not let cancellation bypass host security or execute a tool the App did not start', async () => {
+  const fixture = fixtureFor();
+  const bridge = await readyBridge(fixture);
+  expect(await bridge.receive(cancelled('binding-app'))).toBe(true);
+  expect(await bridge.receive({
+    jsonrpc: '2.0',
+    method: 'notifications/cancelled',
+    params: { requestId: 'tools/call', reason: 'aborted' },
+  })).toBe(true);
+  expect(fixture.calls).toEqual([]);
+  expect(await bridge.receive({
+    id: 'scalar-tool',
+    jsonrpc: '2.0',
+    method: 'tools/call',
+    params: { arguments: 'Paris', name: 'refresh-weather' },
+  })).toBe(true);
+  expect(fixture.calls).toEqual([]);
+  expect(responsesFor(fixture, 'scalar-tool')).toEqual([
+    { error: { code: -32602, message: 'tools/call requires a name and finite JSON arguments.' }, id: 'scalar-tool', jsonrpc: '2.0' },
+  ]);
+});
diff --git a/packages/agent-bundle/tests/mcp-apps-compile.test.ts b/packages/agent-bundle/tests/mcp-apps-compile.test.ts
index 5666bbff2..66fd02987 100644
--- a/packages/agent-bundle/tests/mcp-apps-compile.test.ts
+++ b/packages/agent-bundle/tests/mcp-apps-compile.test.ts
@@ -133,8 +133,12 @@ describe('compileMcpApps', () => {
     const graph = await runtimeImportGraph(join(agentBundlePackageRoot, 'dist', 'app.js'));
     expect(graph.externalSpecifiers).toEqual([]);
     expect([...graph.files.keys()]).toContain(join(agentBundlePackageRoot, 'dist', 'app.js'));
+    expect(graph.files.size).toBeGreaterThan(1);
+    expect([...graph.files.keys()].every((file) =>
+      file.startsWith(join(agentBundlePackageRoot, 'dist')),
+    )).toBe(true);
     const runtimeBytes = [...graph.files.values()].join('\n');
-    const forbiddenRuntimeBytes = [
+    const forbiddenSharedBytes = [
       /\bnode:/u,
       /["']effect(?:\/|["'])/u,
       /["']zod(?:\/|["'])/u,
@@ -142,7 +146,16 @@ describe('compileMcpApps', () => {
       /mcp-server-runtime|mcp-schema-projection|mcp-tasks/u,
       /routes\/framework-imports|routes\/public|build\/mcp-apps/u,
     ];
+    const forbiddenRuntimeBytes = [
+      ...forbiddenSharedBytes,
+      /\bprocess\b/u,
+      /\brequire\b/u,
+      /__webpack_require__/u,
+      /\bBuffer\b/u,
+      /\bimport\.meta\b/u,
+    ];
     expect(forbiddenRuntimeBytes.filter((pattern) => pattern.test(runtimeBytes))).toEqual([]);
+    expect(runtimeBytes).toContain('APP_PROTOCOL_VERSION');
 
     const installedPackage = join(root, 'node_modules', 'agent-bundle');
     await mkdir(installedPackage, { recursive: true });
@@ -156,14 +169,15 @@ describe('compileMcpApps', () => {
     const { outDir, result } = await compile(root, [app(root)]);
     const html = await emittedHtml(outDir);
     expect(html).toContain('2026-01-26');
-    expect(result.apps[0]!.sourceInputs.filter((source) =>
-      /(?:^|\/)node_modules\/(?:effect|zod|typescript-5)(?:\/|$)|\/agent-bundle\/src\/(?:build|routes)\//u.test(source),
-    )).toEqual([]);
+    expect(result.apps[0]!.sourceInputs).toEqual([
+      join(root, 'agent-bundle.config.ts'),
+      join(root, 'views', 'status.ts'),
+    ]);
     expect(await readdir(outDir)).toEqual(['mcp-apps']);
     expect(await readdir(join(outDir, 'mcp-apps'))).toEqual(['status.html']);
     expect(html).toMatch(/<script\b(?![^>]*\bsrc=)[^>]*>/u);
     expect(html).not.toMatch(/<(?:script\b[^>]*\bsrc|link\b[^>]*\bhref)=?/u);
-    expect(forbiddenRuntimeBytes.filter((pattern) => pattern.test(html))).toEqual([]);
+    expect(forbiddenSharedBytes.filter((pattern) => pattern.test(html))).toEqual([]);
   }, 60_000);
 
   it('compiles a .ts entry that imports a .tsx component to the automatic JSX runtime and measures the view', async () => {
@@ -252,6 +266,28 @@ describe('compileMcpApps', () => {
     expect(html).not.toContain('SHADOWED');
   }, 60_000);
 
+  it('resolves the reserved agent-bundle/app specifier ahead of a consumer tsconfig paths entry that shadows it', async () => {
+    const root = await createProject({
+      'stub-app.ts': "export const createAppClient = (): string => 'SHADOWED_APP_RUNTIME';\n",
+      'tsconfig.json': `${JSON.stringify({
+        compilerOptions: { baseUrl: '.', paths: { 'agent-bundle/app': ['./stub-app.ts'] } },
+      })}\n`,
+      'views/status.ts': [
+        "import { createAppClient } from 'agent-bundle/app';",
+        'document.body.dataset.client = String(createAppClient);',
+        '',
+      ].join('\n'),
+    });
+    const { outDir, result } = await compile(root, [app(root)]);
+    const html = await emittedHtml(outDir);
+    expect(html).toContain('2026-01-26');
+    expect(html).not.toContain('SHADOWED_APP_RUNTIME');
+    expect(result.apps[0]!.sourceInputs).toEqual([
+      join(root, 'agent-bundle.config.ts'),
+      join(root, 'views', 'status.ts'),
+    ]);
+  }, 60_000);
+
   it('still resolves the author’s own tsconfig paths inside a view', async () => {
     // Winning the reserved specifier must not cost the author their `paths`:
     // Rsbuild's `prefer-alias` strategy would drop them from the view compiler.
diff --git a/packages/agent-bundle/tests/route-unit/render-route.test.ts b/packages/agent-bundle/tests/route-unit/render-route.test.ts
index cc27bc0c3..6499ae838 100644
--- a/packages/agent-bundle/tests/route-unit/render-route.test.ts
+++ b/packages/agent-bundle/tests/route-unit/render-route.test.ts
@@ -506,6 +506,26 @@ describe('renderRoute through the real renderer', () => {
     expect(rendered.provenance.source).toBe('module');
     expect(rendered.provenance.manifestDigest).toBeUndefined();
   });
+
+  it('derives the request surface of a module rendered directly from its route id, canonical or not', async () => {
+    // What the route reads back as `invocation.surface`: the protocol name the
+    // harness records for the request, as a generated server would.
+    const Surface = (): unknown => {
+      const { invocation } = useAgent();
+      return createElement(Agent.Result, {
+        value: { operationId: invocation.operationId ?? null, surface: invocation.surface ?? null },
+      }, createElement(Agent.Text, null, 'surface observed'));
+    };
+
+    // A canonical MCP id resolves through the shared derivation: its final segment.
+    const canonical = await renderRoute({ default: Surface as never }, { routeId: 'tool:harness/echo' });
+    expectDocument(canonical).toHaveValue({ operationId: 'tool:harness/echo', surface: 'echo' });
+
+    // Any other id keeps the module-direct fallback — its final slash segment —
+    // rather than becoming the whole id.
+    const custom = await renderRoute({ default: Surface as never }, { routeId: 'custom/group/name' });
+    expectDocument(custom).toHaveValue({ operationId: 'custom/group/name', surface: 'name' });
+  });
 });
 
 describe('layout composition at the route-unit level', () => {
diff --git a/packages/agent-bundle/tests/serve-app.test.ts b/packages/agent-bundle/tests/serve-app.test.ts
index a3459e1bd..1ba6fa3a7 100644
--- a/packages/agent-bundle/tests/serve-app.test.ts
+++ b/packages/agent-bundle/tests/serve-app.test.ts
@@ -6,14 +6,21 @@ import { join } from 'node:path';
 import { afterAll, beforeAll, expect, it } from '@rstest/core';
 
 import { build, serveApp } from '../src/api.ts';
+import {
+  AppClientError,
+  type AppMessageEvent,
+  type AppMessageTarget,
+  type AppWindow,
+  createAppClient,
+} from '../src/app/index.ts';
 import { MCP_APP_PROTOCOL_VERSION } from '../src/dev/mcp-apps/mcp-app-bridge.ts';
 import { SERVE_APP_TOKEN_HEADER } from '../src/serve-app/serve-app-page.ts';
 import { timeScale } from './support/time-scale.ts';
 
 /**
  * `agent-bundle serve-app` end to end over a real packed server: build the
- * public MCP App example, serve its App, and drive the host document's
- * protocol by hand — the same `/api/mcp/...` routes the Workbench relay
+ * public MCP App example, serve its App, and drive the host through
+ * `createAppClient` — the same `/api/mcp/...` routes the Workbench relay
  * uses — from the initialize handshake through a consented `tools/call`,
  * then close and verify every listener is gone.
  */
@@ -220,46 +227,88 @@ it('serves the MCP App example standalone over its packed server and relays the
     expect(await sandboxDocument.text()).toContain('MCP App sandbox');
 
     const messagesPath = `/api/mcp/apps/${encodeURIComponent(preview.bindingId)}/messages`;
-    const relay = async (message: JsonRpc): Promise<{ readonly lifecycle: string; readonly messages: readonly JsonRpc[] }> =>
-      await api('POST', messagesPath, { message }) as { readonly lifecycle: string; readonly messages: readonly JsonRpc[] };
+    const consentPath = `/api/mcp/apps/${encodeURIComponent(preview.bindingId)}/consent`;
+    const hostMethods: string[] = [];
+    const openingInputs: unknown[] = [];
+    let approveCalls = true;
+
+    const decideConsent = async (approved: boolean): Promise<readonly JsonRpc[]> => {
+      for (let attempt = 0; attempt < 50; attempt += 1) {
+        const listed = await api('GET', consentPath);
+        const challenges = listed.challenges as readonly { readonly id: string }[];
+        const challenge = challenges[0];
+        if (challenge !== undefined) {
+          const decided = await api('POST', consentPath, { approved, challengeId: challenge.id });
+          return (decided.messages ?? []) as readonly JsonRpc[];
+        }
+        await new Promise((resolve) => setTimeout(resolve, 20));
+      }
+      throw new Error('The serve-app host did not publish a consent challenge.');
+    };
 
-    // The MCP Apps handshake the App performs from inside the sandbox.
-    const initialized = await relay({
-      id: 1,
-      jsonrpc: '2.0',
-      method: 'ui/initialize',
-      params: {
-        appCapabilities: { availableDisplayModes: ['inline'] },
-        appInfo: { name: 'mcp-app-example', version: '1.0.0' },
-        protocolVersion: MCP_APP_PROTOCOL_VERSION,
+    const listeners = new Set<(event: AppMessageEvent) => void>();
+    const parent: AppMessageTarget = {
+      postMessage(message) {
+        void (async () => {
+          try {
+            const relayed = await api('POST', messagesPath, { message }) as {
+              readonly messages: readonly JsonRpc[];
+            };
+            let incoming = relayed.messages;
+            if (
+              incoming.length === 0
+              && typeof message === 'object'
+              && message !== null
+              && 'method' in message
+              && message.method === 'tools/call'
+            ) {
+              incoming = await decideConsent(approveCalls);
+            }
+            for (const data of incoming) {
+              if (typeof data === 'object' && data !== null && typeof data.method === 'string') {
+                hostMethods.push(data.method);
+              }
+              for (const listener of [...listeners]) {
+                listener({ data, origin, source: parent });
+              }
+            }
+          } catch {
+            // The client's pending request keeps its own timeout.
+          }
+        })();
       },
+    };
+    const window: AppWindow = {
+      parent,
+      addEventListener(_type, listener) { listeners.add(listener); },
+      removeEventListener(_type, listener) { listeners.delete(listener); },
+    };
+
+    const client = createAppClient({
+      appInfo: { name: 'mcp-app-example', version: '1.0.0' },
+      window,
     });
-    expect(initialized.lifecycle).toBe('initializing');
-    expect(initialized.messages).toMatchObject([{
-      id: 1,
-      result: { hostInfo: { name: 'agent-bundle' }, protocolVersion: MCP_APP_PROTOCOL_VERSION },
-    }]);
-    const opening = await relay({ jsonrpc: '2.0', method: 'ui/notifications/initialized' });
-    expect(opening.lifecycle).toBe('initialized');
-    expect(opening.messages).toMatchObject([
-      { method: 'ui/notifications/tool-input', params: { arguments: { service: 'compiler' } } },
-      { method: 'ui/notifications/tool-result', params: { structuredContent: { service: 'compiler', status: 'healthy' } } },
-    ]);
+    client.onToolInput('tool:status/show-status', (input) => { openingInputs.push(input); });
 
-    // A tools/call from the App reaches the packed server only through consent, as in the Workbench.
-    const pending = await relay({ id: 2, jsonrpc: '2.0', method: 'tools/call', params: { arguments: { service: 'payments-api' }, name: 'show-status' } });
-    expect(pending.messages).toEqual([]);
-    const consentPath = `/api/mcp/apps/${encodeURIComponent(preview.bindingId)}/consent`;
-    const challenges = (await api('GET', consentPath)).challenges as readonly { readonly id: string; readonly request: { readonly capability: string } }[];
-    expect(challenges).toMatchObject([{ request: { capability: 'call-tool', details: { arguments: { service: 'payments-api' }, name: 'show-status' } } }]);
-    const decided = await api('POST', consentPath, { approved: true, challengeId: challenges[0]!.id });
-    expect(decided.approved).toBe(true);
-    expect(decided.messages).toMatchObject([{
-      id: 2,
-      result: { structuredContent: { service: 'payments-api', status: 'degraded' } },
-    }]);
+    const initialized = await client.connect();
+    expect(initialized).toMatchObject({
+      hostInfo: { name: 'agent-bundle' },
+      protocolVersion: MCP_APP_PROTOCOL_VERSION,
+    });
+    expect(client.connected).toBe(true);
+    await expect.poll(() => openingInputs, { timeout: 5_000 * timeScale }).toEqual([{ service: 'compiler' }]);
+    await expect.poll(() => hostMethods.includes('ui/notifications/tool-result'), { timeout: 5_000 * timeScale }).toBe(true);
+
+    await expect(client.call('tool:status/show-status', { service: 'payments-api' }))
+      .resolves.toMatchObject({ service: 'payments-api', status: 'degraded' });
     expect(await api('GET', consentPath)).toMatchObject({ challenges: [] });
+
+    approveCalls = false;
+    const denied = client.call('tool:status/show-status', { service: 'payments-api' });
+    await expect(denied).rejects.toBeInstanceOf(AppClientError);
+    await expect(denied).rejects.toMatchObject({ code: 'consent-required' });
     expect(closed).toBe(false);
+    client.dispose();
   } finally {
     await served.close();
   }
diff --git a/packages/workbench/tests/mcp-app-real.e2e.test.ts b/packages/workbench/tests/mcp-app-real.e2e.test.ts
index 5adf93c13..4b6f971b9 100644
--- a/packages/workbench/tests/mcp-app-real.e2e.test.ts
+++ b/packages/workbench/tests/mcp-app-real.e2e.test.ts
@@ -117,20 +117,39 @@ const writeBundledAppProject = async (root: string): Promise<void> => {
     mkdir(join(root, 'src'), { recursive: true }),
     mkdir(join(root, 'views'), { recursive: true }),
     symlink(join(agentBundleNodeModules, '@modelcontextprotocol'), join(root, 'node_modules', '@modelcontextprotocol'), 'dir'),
+    symlink(join(workbenchNodeModules, 'zod'), join(root, 'node_modules', 'zod'), 'dir'),
   ]);
   await Promise.all([
     writeFile(join(root, 'package.json'), '{"type":"module"}\n'),
     writeFile(join(root, 'views', 'dashboard.css'), '#view { color: rgb(18, 52, 86); font-weight: 700; }\n'),
     writeFile(join(root, 'views', 'dashboard.ts'), [
+      "import { createAppClient } from 'agent-bundle/app';",
       "import './dashboard.css';",
-      "document.querySelector('#view')!.textContent = 'packed release dashboard';",
+      '',
+      "const view = document.querySelector('#view')!;",
+      "view.textContent = 'connecting';",
+      'const client = createAppClient({',
+      "  appInfo: { name: 'bundled-app-fixture', version: '1.0.0' },",
+      '});',
+      'const run = async () => {',
+      '  await client.connect();',
+      "  view.textContent = 'connected';",
+      '  try {',
+      "    const called = await client.call('tool:fixture/inner-echo', { message: 'from-compiled-app' });",
+      '    view.textContent = JSON.stringify(called);',
+      '  } catch (error) {',
+      "    view.textContent = error instanceof Error ? error.message : 'call failed';",
+      '  }',
+      '};',
+      'void run();',
       '',
     ].join('\n')),
-    writeFile(join(root, 'views', 'shell.html'), '<!doctype html><html><body><main id="view"></main></body></html>\n'),
+    writeFile(join(root, 'views', 'shell.html'), '<!doctype html><html><body><main id="view">waiting</main></body></html>\n'),
     writeFile(join(root, 'src', 'server.ts'), [
       "import { McpServer } from '@modelcontextprotocol/server';",
       "import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';",
       "import apps from 'agent-bundle/mcp-apps';",
+      "import { z } from 'zod';",
       '',
       "const server = new McpServer({ name: 'bundled-app-fixture', version: '1.0.0' });",
       'for (const app of apps) {',
@@ -142,6 +161,11 @@ const writeBundledAppProject = async (root: string): Promise<void> => {
       "if (app === undefined) throw new Error('Expected one bundled MCP App.');",
       "server.registerTool('show-dashboard', { _meta: { ui: { resourceUri: app.resourceUri } } }, async () => ({",
       "  content: [{ text: 'Packed release dashboard.', type: 'text' }],",
+      "  structuredContent: { source: 'packed-release' },",
+      '}));',
+      "server.registerTool('inner-echo', { inputSchema: z.object({ message: z.string() }) }, async ({ message }) => ({",
+      "  content: [{ text: `Inner echo: ${message}`, type: 'text' }],",
+      '  structuredContent: { echo: message },',
       '}));',
       'await server.connect(new StdioServerTransport());',
       '',
@@ -1715,7 +1739,7 @@ e2e('keeps Portable, ChatGPT, and Claude simulated App profiles isolated over on
   }
 });
 
-e2e('renders a compiler-bundled App template through the canonical sandbox URL', { timeout: 90_000 * timeScale }, async ({ page }) => {
+e2e('renders a compiler-bundled App that calls the host through createAppClient', { timeout: 90_000 * timeScale }, async ({ page }) => {
   let project: Awaited<ReturnType<typeof createProjectFixture>> | undefined;
   let server: Awaited<ReturnType<typeof startDevServer>> | undefined;
   let testFailure: unknown;
@@ -1761,21 +1785,29 @@ e2e('renders a compiler-bundled App template through the canonical sandbox URL',
     const source = await outerFrame.getAttribute('src');
     if (source === null) throw new Error('Expected the bundled App preview iframe to have a source.');
     expect(new URL(source).origin).not.toBe(foregroundOrigin);
+    await expect(outerFrame).toHaveAttribute('data-mcp-app-relay-state', 'ready', { timeout: browserTimeout });
     await expect.poll(() => page.frames().filter((frame) => frame.url() === 'about:blank').length, { timeout: browserTimeout }).toBe(1);
     const appFrame = page.frames().find((frame) => frame.url() === 'about:blank');
     if (appFrame === undefined) throw new Error('Expected the sandbox proxy to create the bundled App srcdoc frame.');
-    await expect(appFrame.locator('#view')).toHaveText('packed release dashboard', { timeout: browserTimeout });
+    await expect.poll(() => appRequests.some((request) => request.method === 'POST' && request.path.endsWith('/messages')), {
+      timeout: browserTimeout,
+    }).toBe(true);
+    const consent = page.getByLabel('MCP App consent');
+    await expect(consent).toContainText('Tool: inner-echo', { timeout: browserTimeout });
+    const allowCallTool = page.getByRole('button', { name: 'Allow call tool' });
+    await expect(allowCallTool).toBeEnabled({ timeout: browserTimeout });
+    await allowCallTool.click();
+    await expect(appFrame.locator('#view')).toHaveText('{"echo":"from-compiled-app"}', { timeout: browserTimeout });
     await expect(appFrame.locator('#view')).toHaveCSS('color', 'rgb(18, 52, 86)', { timeout: browserTimeout });
     await expect(appFrame.locator('#view')).toHaveCSS('font-weight', '700', { timeout: browserTimeout });
     expect(appRequests.some((request) => request.method === 'GET' && /^\/api\/mcp\/apps\/[^/]+$/u.test(request.path))).toBe(false);
 
-    const fallbackClosed = page.waitForResponse((response) => {
-      const request = response.request();
-      const url = new URL(response.url());
-      return request.method() === 'DELETE' && url.origin === foregroundOrigin && /^\/api\/mcp\/apps\/[^/]+$/u.test(url.pathname);
+    const closed = page.waitForRequest((request) => {
+      const url = new URL(request.url());
+      return url.origin === foregroundOrigin && request.url().startsWith(`${foregroundOrigin}/api/mcp/apps/`) && request.url().endsWith('/close');
     }, { timeout: 30_000 * timeScale });
     await page.getByRole('button', { name: 'Close App preview' }).click();
-    expect((await fallbackClosed).status()).toBe(200);
+    await closed;
     await expect(outerFrame).toBeHidden({ timeout: browserTimeout });
     expect(consoleErrors).toEqual([]);
     expect(pageErrors).toEqual([]);
diff --git a/website/docs/en/examples/mcp-app.mdx b/website/docs/en/examples/mcp-app.mdx
index 5dd9b1b98..cfdeaa743 100644
--- a/website/docs/en/examples/mcp-app.mdx
+++ b/website/docs/en/examples/mcp-app.mdx
@@ -39,12 +39,14 @@ to see how the surfaces fit together instead of studying one of them alone.
   [Testing](../guide/development/testing.mdx).
 - **The App is a client of the bridge, not a transport of its own.** `views/status-panel.ts`
   creates its client with `createAppClient` from `agent-bundle/app`, receives the opening
-  `show-status` input and structured result through `onToolInput` / `onToolResult`, refreshes
-  through `call('tool:status/refresh-status', …)`, and reads the readiness policy through
-  `request('resources/read', …)`. The `status` server is handwritten, so no generated route
-  contracts exist; the view types its two tools itself with a structural `AppRegister`
-  augmentation. No JSON-RPC ids, pending maps, `postMessage('*')`, or `structuredContent`
-  unwrapping remain in the view. See
+  `show-status` call's input and structured result through `onToolInput` / `onToolResult`, and
+  surfaces failed or unstructured opening results through `onToolError`
+  registered on `tool:status/show-status` (delivered when the host's initialize result names
+  `show-status` as the opening tool), refreshes through `call('tool:status/refresh-status', …)`,
+  and reads the readiness policy through `request('resources/read', …)`. The `status` server is
+  handwritten, so no generated route contracts exist; the view types its two tools itself with a
+  structural `AppRegister` augmentation. No JSON-RPC ids, pending maps, `postMessage('*')`, or
+  `structuredContent` unwrapping remain in the view. See
   [The typed App client](../guide/authoring/mcp.mdx#the-typed-app-client).
 
 ## What is authored
diff --git a/website/docs/en/guide/authoring/mcp.mdx b/website/docs/en/guide/authoring/mcp.mdx
index fe21c2c8e..7d752bf3b 100644
--- a/website/docs/en/guide/authoring/mcp.mdx
+++ b/website/docs/en/guide/authoring/mcp.mdx
@@ -767,6 +767,7 @@ const status = await client.call('tool:hauler/hauler_status', { limit: 40 });
 
 const stop = client.onToolResult('tool:hauler/hauler_status', (opening) => { /* typed */ });
 client.onToolInput('tool:hauler/hauler_status', (input) => { /* typed */ });
+client.onToolError('tool:hauler/hauler_status', (error) => { /* the opening call failed */ });
 client.onToolCancelled(({ reason }) => { /* the opening call ended without a result */ });
 
 stop();
@@ -775,9 +776,11 @@ client.dispose();
 
 **Route ids and types.** A tool is addressed by its route id, `tool:<server>/<name>`. The client
 derives the wire tool name from the final segment, exactly as the generated server does, and any
-other shape is a `TypeError`. The types come from the compiler: when the route graph has at least
-one tool route, the generated `.agent-bundle/routes.d.ts` adds exactly one augmentation on
-`agent-bundle/app`,
+other shape is a `TypeError`. The server segment never reaches the wire: `tools/call` carries the
+tool name alone, and the host dispatches it to the one server the App is bound to, so address the
+tools of the server that registered the App. The types come from the compiler: when the route
+graph has at least one tool route, the generated `.agent-bundle/routes.d.ts` adds exactly one
+augmentation on `agent-bundle/app`,
 
 ```ts
 declare module 'agent-bundle/app' {
@@ -802,54 +805,87 @@ and a view may declare its own contract map through the same `AppRegister` seam,
 **Calls and results.** `call()` returns the structured result **directly**; the MCP `content`,
 `_meta`, and `isError` envelope is transport data. It rejects with an `AppClientError` when the
 tool result carries `isError: true` (`code: 'rpc'`, the whole result on `error.data`), has no
-object `structuredContent`, or is not a well-formed result (`invalid-message`). This matches the
-generated MCP projection: only an object-rooted `resultSchema` produces `structuredContent`, so a
-scalar or array result is not a typed App call. `request(method, params?)` is the lower-level
-escape hatch for `resources/read` and the `ui/*` methods the host supports, resolving to the
-JSON-RPC result as is. Both connect first when `connect()` has not been awaited. Every request
-takes `{ signal, timeoutMs }`; the client default is 15 seconds (`timeoutMs` on
-`createAppClient`), and a request that times out or is aborted rejects with `timeout` or
-`aborted` and sends `notifications/cancelled` to the host.
-
-**Opening notifications.** `onToolInput` and `onToolResult` observe the tool call that opened the
-App (`ui/notifications/tool-input` and `ui/notifications/tool-result`); `onToolResult` delivers
-the decoded `structuredContent`, not the envelope. Those notifications name no tool — they are
-always the opening call — so the route id you register with supplies the payload type, not a
-filter. `onToolCancelled` reports the terminal `ui/notifications/tool-cancelled` with its optional
-`reason`. Each registration returns its unsubscribe function.
-
-**Errors.** One class, `AppClientError`, with a discriminated `code`: `timeout`, `aborted`,
-`disposed`, `connection-rebound`, `invalid-message`, `rpc`, `capability-unavailable`, or
-`consent-required`. A JSON-RPC error from the host maps by its code — `-32601` to
-`capability-unavailable`, `-32001` to `consent-required`, anything else to `rpc` — with `rpcCode`
-and `data` preserved. None of this is an `AB` diagnostic: App-side failures are browser errors,
-not build output.
+object `structuredContent`, or is not a well-formed result (`invalid-message`). Give a tool an App
+calls an object-rooted `resultSchema`: the generated MCP projection emits `structuredContent` for
+object-valued results only, while the contract map types every tool route whatever its root, so a
+tool whose `resultSchema` is a scalar or an array is typed but never resolves — `call()` on it
+rejects with `invalid-message` every time. `request(method, params?)` is the lower-level escape
+hatch for `resources/read` and the `ui/*` methods the host supports, resolving to the JSON-RPC
+result as is. Both connect first when `connect()` has not been awaited.
+
+**Timeouts and cancellation.** Every request takes `{ signal, timeoutMs }`. `signal` is an
+`AbortSignal` — the client reads `aborted` and listens for `abort`, nothing more — and the
+deadline defaults to the client's `timeoutMs` (15 seconds). A request that times out or is
+aborted rejects at once with `timeout` or `aborted` and, once the client is connected, sends
+`notifications/cancelled` naming the request id and the reason. The client does not wait to learn
+whether the tool stopped; that is the host's decision. The framework's host bridge
+(`createMcpAppBridge`, which the Workbench, `agent-bundle serve-app`, and the `browser-app` test
+harness run) honors it for a request that App started and that is still in flight: it aborts the
+`tools/call` or `resources/read` so the abort reaches the bound MCP session's request, denies a
+consent challenge still pending for that request so a later approval cannot run it, and sends no
+late response. A cancellation for an unknown or finished id is a no-op, and one sent before the
+handshake completes is ignored. Other hosts apply their own policy.
+
+**Opening notifications.** `onToolInput`, `onToolResult`, and `onToolError` observe the tool call
+that opened the App (`ui/notifications/tool-input` and `ui/notifications/tool-result`). Those
+notifications name no tool, so the client learns which tool opened it from the handshake:
+`hostContext.toolInfo.tool.name` in the initialize result. A listener fires only when the tool
+name of the route id it registered with — the final segment — is that opening tool's; listeners
+registered for other tools stay silent, and when the initialize result names no tool, `tool-input`
+and `tool-result` reach no listener at all. `onToolInput` receives the notification's `arguments`,
+`onToolResult` the decoded `structuredContent` of a successful result, not the envelope.
+`onToolError` receives the same notification's failures as an `AppClientError`: a result with
+`isError: true` is `rpc` with the whole result on `data`; a malformed envelope, or one without an
+object `structuredContent`, is `invalid-message`. A failed opening result never reaches
+`onToolResult`. `onToolCancelled` reports the terminal `ui/notifications/tool-cancelled` with its
+optional `reason`. Each registration returns its unsubscribe function; listeners run
+asynchronously, and an exception a listener throws is dropped.
+
+**Errors.** Two kinds. Everything that happens on the wire or in the lifecycle rejects with one
+class, `AppClientError`, with a discriminated `code`: `timeout`, `aborted`, `disposed`,
+`connection-rebound`, `invalid-message`, `rpc`, `capability-unavailable`, or `consent-required`.
+A JSON-RPC error from the host maps by its code — `-32601` to `capability-unavailable`, `-32001`
+to `consent-required`, anything else to `rpc` — with `rpcCode` and `data` preserved. Misusing the
+API is not an `AppClientError`: `createAppClient()` throws a `TypeError` synchronously for a
+`targetOrigin` that is not an exact `http:`/`https:` origin, for `appInfo` or `appCapabilities`
+that are not finite JSON objects, and when there is no `window` and none is injected, and a
+`RangeError` for a `timeoutMs` that is not an integer from 1 to 2³¹ − 1 milliseconds; the `on*`
+registrations throw a `TypeError` for a route id that is not `tool:<server>/<name>` or a listener
+that is not a function; `call()` rejects with that `TypeError` for a malformed route id,
+`request()` for an empty method, and any request with a `RangeError` for an out-of-range
+per-request `timeoutMs`. None of this is an `AB` diagnostic: App-side failures are browser
+errors, not build output.
 
 **Lifecycle and origin pinning.** The Workbench and `serve-app` render the App as an opaque,
 no-referrer `srcdoc` sandbox, so the document cannot know its host's origin up front. `connect()`
 therefore sends exactly one frame to `'*'` — the framework-owned `ui/initialize` — and accepts a
 response only from the configured parent window (`event.source`), with that request's id and a
 valid initialize result (protocol version `2026-01-26`, `hostInfo`, `hostCapabilities`,
-`hostContext`). It pins the responding `event.origin` (an opaque `null` origin is refused), sends
-`ui/notifications/initialized` and every later request to that exact origin, and ignores every
-message from any other source or origin. A host that can supply a trusted origin passes
-`targetOrigin` — an exact `http:`/`https:` origin; `'*'` is rejected — and no wildcard frame is
-sent at all. `connect()` is idempotent. `rebind({ parent?, targetOrigin?, window? })` rejects the
-previous generation's pending requests with `connection-rebound`, clears the pin, and performs the
-handshake again against the new parent. `dispose()`, also idempotent, removes the listener,
-rejects pending requests with `disposed`, and drops every registration; a host's
+`hostContext`). It pins the responding `event.origin`, which must itself be an exact
+`http:`/`https:` origin — an opaque `null`, empty, or other-scheme origin fails the handshake with
+`invalid-message` — then sends `ui/notifications/initialized` and every later request to that
+exact origin, and ignores every message from any other source or origin. A host that can supply a
+trusted origin passes `targetOrigin` — an exact `http:`/`https:` origin; `'*'` is rejected — and
+no wildcard frame is sent at all. `connect()` is idempotent: a connected client resolves the
+cached result, a connecting one returns the in-flight handshake.
+`rebind({ parent?, targetOrigin?, window? })` rejects the previous generation's pending requests
+with `connection-rebound` — a `connect()` still in flight included, which never becomes the live
+connection — clears the pin, keeps the configured `targetOrigin` unless the call names one, and
+performs the handshake again against the new parent. `dispose()`, also idempotent, removes the
+listener, rejects pending requests with `disposed`, and drops every registration; a host's
 `ui/resource-teardown` request is acknowledged and disposes the client. The transport is
 DOM-shaped rather than bound to the global `window`: `window` and `parent` are injectable, which
 is how tests and non-DOM hosts drive the same client.
 
 **The host-side boundary.** The client is the App-inside-the-iframe half of the bridge. The other
 half — the frame relay, sandbox proxy, host page, `/api/mcp/...` routes, and consent authority —
-belongs to the host: the Workbench MCP page, `agent-bundle serve-app`, an MCP host embedding the
-App, and the standalone production host of
-[#564](https://github.com/ScriptedAlchemy/agent-bundle/issues/564) all serve this one client over
-the same wire contract (`McpAppBridge`), and the host, never the App, decides which server a call
-reaches and which capabilities need consent. An App reaches no foreground server or MCP backend
-except through its relay.
+belongs to the host. The Workbench MCP page and `agent-bundle serve-app` run the framework's host
+bridge (`createMcpAppBridge`); an MCP host embedding the App runs its own. All of them speak the
+standard MCP Apps wire the client implements, and the standalone production host
+[#564](https://github.com/ScriptedAlchemy/agent-bundle/issues/564) proposes is specified against
+that same wire; the host, never the App, decides which server a call reaches and which
+capabilities need consent. An App reaches no foreground server or MCP backend except through its
+relay.
 
 `agent-bundle/app` is bundle-safe: it is not one of the compiler-carrying entries `AB4837`
 rejects, and the compiler inlines it into the App document from the installed package like any
diff --git a/website/docs/en/reference/api.mdx b/website/docs/en/reference/api.mdx
index 314f79860..31c29c070 100644
--- a/website/docs/en/reference/api.mdx
+++ b/website/docs/en/reference/api.mdx
@@ -15,7 +15,7 @@ Every public entry point is documented from its declarations:
 | --- | --- |
 | `agent-bundle` | The authoring and orchestration surface: `defineSkill`, `canonicalAgentEvents`, `startDevServer`, `runEvals`, `compareEvals`, the eval harness factories, and the artifact-manifest helpers. |
 | `agent-bundle/api` | The programmatic compiler: `build`, `validate`, `inspect`, `prepack`, their option and result types, the `AgentComponentKind` / `componentKindCapability` component-kind helpers, and the artifact operations `listMcp`, `invokeMcp`, `runMcp`, `serveApp` (a built MCP App served standalone in a browser — a host-process API for scripts and tests; a routed CLI command inside the artifact uses `spawnServeApp` from `agent-bundle/serve-app-command` instead, see [Serving an App standalone](../guide/authoring/mcp.mdx#serving-an-app-standalone)), `listHooks`, and `simulateHook`; plus the Rspack stats formatters `rspackStatsErrors`, `describeRspackStatsError`, and `formatRspackStatsError`, which render a compile error as the same `<file>:<line>:<column>: <message>` line the compiler's `AB4770` carries, for tools that drive their own Rsbuild compile. |
-| `agent-bundle/app` | The browser-safe MCP App client: `createAppClient`, the `AppClient` lifecycle (`connect`, `call`, `request`, `onToolInput`, `onToolResult`, `onToolCancelled`, `rebind`, `dispose`), `AppClientError` and its `code` union, the `AppRegister` interface the generated `.agent-bundle/routes.d.ts` augments with the project's `tool:<server>/<name>` contracts, `AppRouteId` / `AppRouteInput` / `AppRouteResult`, the injectable `AppWindow` / `AppMessageTarget` ports, and `APP_PROTOCOL_VERSION`. Imports nothing from Zod, Node, or the compiler; for App views only. |
+| `agent-bundle/app` | The browser-safe MCP App client: `createAppClient`, the `AppClient` lifecycle (`connect`, `call`, `request`, `onToolInput`, `onToolResult`, `onToolError`, `onToolCancelled`, `rebind`, `dispose`), `AppClientError` and its `code` union for every wire and lifecycle failure (option misuse is a plain `TypeError` or `RangeError`), the `AppRegister` interface the generated `.agent-bundle/routes.d.ts` augments with the project's `tool:<server>/<name>` contracts, `AppRouteId` / `AppRouteInput` / `AppRouteResult`, the injectable `AppWindow` / `AppMessageTarget` ports, and `APP_PROTOCOL_VERSION`. Imports nothing from Zod, Node, or the compiler; for App views only. |
 | `agent-bundle/config` | `defineConfig` and the configuration types. |
 | `agent-bundle/test` | The route-testing harness, matchers, and contract matrices. |
 | `agent-bundle/test/browser` | The MCP App bridge harness for browser-rendered views. |
diff --git a/website/docs/en/reference/security.mdx b/website/docs/en/reference/security.mdx
index 9ff4bbc0b..833976352 100644
--- a/website/docs/en/reference/security.mdx
+++ b/website/docs/en/reference/security.mdx
@@ -64,18 +64,23 @@ Inside the App document, the `agent-bundle/app` client trusts no arbitrary `post
 The sandbox is an opaque, no-referrer `srcdoc`, so the document cannot know its host's origin
 before the first frame: `connect()` sends exactly one framework-owned `ui/initialize` request to
 `'*'`, accepts a response only from the configured parent window with that request's id and a
-valid initialize result, pins the responding origin — an opaque `null` origin is refused — and
-from then on sends to and accepts from that exact `source` and `origin` only. A host that can
-name its origin passes `targetOrigin` (an exact `http:`/`https:` origin; `'*'` is rejected) and no
-wildcard frame is ever sent. `rebind()` and `dispose()` revoke the pin and reject every request
-still pending, so a stale generation cannot receive a later host's messages. Author code has no
-wildcard send path.
+valid initialize result, pins the responding origin — it must be an exact `http:`/`https:`
+origin; an opaque `null`, empty, or other-scheme origin fails the handshake — and from then on
+sends to and accepts from that exact `source` and `origin` only. A host that can name its origin
+passes `targetOrigin` (an exact `http:`/`https:` origin; `'*'` is rejected) and no wildcard frame
+is ever sent. `rebind()` and `dispose()` revoke the pin and reject every request still pending, a
+handshake still in flight included, so a stale generation cannot receive a later host's messages.
+Author code has no wildcard send path.
 
 The host relay is the security boundary. The App client speaks only to its expected parent; the
 Workbench, `serve-app`, or an embedding MCP host forwards permitted requests to the one server the
 frame is bound to and applies its own authentication, capability, and consent policy. An App never
 reaches the foreground routes or an MCP backend around the relay, and the relay never merges in
-the permissions of another App, server, or browser origin.
+the permissions of another App, server, or browser origin. The same holds for cancellation: the
+framework's host bridge honors an App's `notifications/cancelled` only for a request that App
+itself started and that is still in flight — aborting that one operation and denying its pending
+consent challenge — so cancelling can neither reach around consent nor touch a request the App
+did not make.
 
 ## The Agent API
 
diff --git a/website/docs/zh/examples/mcp-app.mdx b/website/docs/zh/examples/mcp-app.mdx
index 462628df8..bb94aea1c 100644
--- a/website/docs/zh/examples/mcp-app.mdx
+++ b/website/docs/zh/examples/mcp-app.mdx
@@ -31,9 +31,14 @@ description: 'MCP App 示例：把一条服务就绪度工作流表达为生成
 - **浏览器表面自成一个证明级别。** `tests/browser-app/status-panel.browser.test.ts` 通过
   `agent-bundle/test/browser` 把生产编译出的 App HTML 挂载到产品桥接之上——也就是
   [测试](../guide/development/testing.mdx)中的 `browser-app` 级别。
-- **App 使用生成的路由契约。** 状态面板从 `agent-bundle/app` 创建客户端，以
-  `tool:status/show-status` 调用同一条工具路由，并直接接收其带类型的结构化对象；它不再自行维护
-  `postMessage` transport 或解包 MCP 结果 envelope。
+- **App 是桥接的客户端，而不是自带 transport。** `views/status-panel.ts` 从 `agent-bundle/app`
+  创建客户端，通过 `onToolInput` / `onToolResult` 接收打开 App 的 `show-status` 输入与结构化结果，并用
+  `onToolError` 展示失败或缺少结构化数据的打开结果，
+  通过 `call('tool:status/refresh-status', …)` 刷新状态，并通过
+  `request('resources/read', …)` 读取就绪度策略。`status` 服务器是手写的，因此不存在生成的路由
+  契约；视图通过结构化的 `AppRegister` augmentation 自行为两条工具声明类型。视图中不再保留
+  JSON-RPC id、pending map、`postMessage('*')` 或 `structuredContent` 解包逻辑。详见
+  [带类型的 App 客户端](../guide/authoring/mcp.mdx#带类型的-app-客户端)。
 
 ## 编写了什么
 
diff --git a/website/docs/zh/guide/authoring/mcp.mdx b/website/docs/zh/guide/authoring/mcp.mdx
index 028cc6ae4..a4559f154 100644
--- a/website/docs/zh/guide/authoring/mcp.mdx
+++ b/website/docs/zh/guide/authoring/mcp.mdx
@@ -666,35 +666,111 @@ refresh）的 `@rsbuild/plugin-react` 注册在每个 App 环境上，因此 `St
 
 ### 带类型的 App 客户端
 
-App 视图通过浏览器安全的 `agent-bundle/app` 入口调用自己的路由，不需要自行实现 JSON-RPC id、pending
-request、超时、结果 envelope 或 `window.parent.postMessage('*')`：
+`agent-bundle/app` 是只面向浏览器的入口，不导入 Zod、Node built-in、Effect 或编译器代码。
+`createAppClient()` 负责 MCP Apps 握手、request id、pending request、超时与取消、JSON-RPC 与结果
+envelope 解码，以及 parent-window transport，因此视图不需要手写 `postMessage` frame 或
+`structuredContent` reader：
 
 ```ts
+// src/mcp/hauler/apps/dashboard.ts
 import { createAppClient } from 'agent-bundle/app';
 
-const client = createAppClient();
+const client = createAppClient({
+  appInfo: { name: 'hauler-dashboard', version: '1' },
+  timeoutMs: 15_000,
+});
+
 await client.connect();
 
-const status = await client.call('tool:status/show-status', {
-  service: 'payments-api',
-});
+// 直接得到由 resultSchema 定型的结构化结果对象。
+const status = await client.call('tool:hauler/hauler_status', { limit: 40 });
+
+const stop = client.onToolResult('tool:hauler/hauler_status', (opening) => { /* 已定型 */ });
+client.onToolInput('tool:hauler/hauler_status', (input) => { /* 已定型 */ });
+client.onToolError('tool:hauler/hauler_status', (error) => { /* opening tool 失败 */ });
+client.onToolCancelled(({ reason }) => { /* opening call 未产生结果便结束 */ });
+
+stop();
+client.dispose();
+```
+
+**路由 id 与类型。** 工具以 `tool:<server>/<name>` 路由 id 寻址。客户端与生成的服务器一样从最后一段
+推导 wire tool name；其他形状属于调用方误用，会抛出 `TypeError`。当路由图至少包含一条工具路由时，
+生成的 `.agent-bundle/routes.d.ts` 会为 `agent-bundle/app` 恰好添加一次 augmentation：
+
+```ts
+declare module 'agent-bundle/app' {
+  interface AppRegister {
+    readonly routes: AgentBundleAppRouteContracts;
+  }
+}
 ```
 
-编译器会在 `.agent-bundle/routes.d.ts` 中生成对 `AppRegister` 的 module augmentation。它从同一份
-Application IR 推导每个工具的输入与结构化输出，因此 App 只导入浏览器安全的声明与运行时，不会把服务器
-路由模块、Zod 或 Node 代码带进视图 bundle。工具路由 id 的规范形式是
-`tool:<server>/<name>`；上例中的 `status` 变量直接是该路由 `resultSchema` 所描述的对象，而不是要求
-App 再从 `structuredContent` 中解包的 MCP 结果 envelope。
-
-同一个客户端拥有宿主桥接的完整生命周期：`connect` 建立连接，`call` 调用已注册工具，`request` 发送
-受支持的桥接请求；`onToolInput`、`onToolResult` 与 `onToolCancelled` 监听包括开场调用在内的宿主
-notification，并各自返回移除 listener 的函数。`rebind` 在宿主换代后绑定新的 parent/origin，`dispose`
-则取消 pending 工作、移除 listener 并关闭客户端。
-
-连接、调用与能力失败会抛出 `AppClientError`，调用方可直接判断其稳定 `code`：`timeout`、`aborted`、
-`disposed`、`connection-rebound`、`invalid-message`、`rpc`、`capability-unavailable` 或
-`consent-required`，不需要解析错误文案。`agent-bundle/app` 不携带编译器，因此 App 中的值导入不会触发
-保护自包含可执行文件的 `AB4837`。
+成员就是项目生成的 MCP **工具**路由：`input` 来自各路由的 `inputSchema`，`result` 来自
+`resultSchema`。该声明以 type-only 方式导入路由模块，所以不会把路由模块、schema 或服务器代码带入 App
+文档。没有 augmentation 时——例如手写服务器——`call()` 仍能以 `unknown` 输入与结果工作，视图也可以
+通过同一个结构化 `AppRegister` seam 声明自己的本地契约 map；[MCP App 示例](../../examples/mcp-app.mdx)
+就为手写的 `status` 服务器这样声明 `show-status` 与 `refresh-status`。`AppRouteId`、
+`AppRouteInput<Id>` 与 `AppRouteResult<Id>` 为 wrapper 命名同一套类型表面。
+
+**调用与结果。** `call()` 直接返回结构化结果对象；MCP 的 `content`、`_meta` 与 `isError` envelope
+只是 transport 数据。工具结果带有 `isError: true` 时，它会以 `code: 'rpc'` 拒绝，并把完整结果保存在
+`error.data`；没有 object `structuredContent` 或结果格式不合法时则以 `invalid-message` 拒绝。只有根为
+对象的 `resultSchema` 才会产生 `structuredContent`，因此 scalar 或 array 结果不是带类型的 App call。
+`request(method, params?)` 是读取 `resources/read` 及宿主支持的 `ui/*` method 的底层逃生舱，按原样返回
+JSON-RPC result。两者都会在尚未 `connect()` 时先连接；每个请求都接受
+`{ signal?: AbortSignal, timeoutMs?: number }`。客户端默认超时为 15 秒，也可在
+`createAppClient({ timeoutMs })` 或单次请求上覆盖。超时或中止分别以 `timeout`、`aborted` 拒绝，并向
+宿主发送带 request id 与原因的 `notifications/cancelled`。
+
+**打开时的 notification。** `onToolInput(routeId, listener)` 与
+`onToolResult(routeId, listener)` 观察打开 App 的工具调用；宿主所带的工具名会按注册路由 id 的最后一段
+筛选，因此其他工具的 opening notification 不会送到该 listener。`onToolResult` 交付解码后的
+`structuredContent`，而不是 envelope。`onToolCancelled(listener)` 接收终止性的
+`ui/notifications/tool-cancelled` 及可选 `reason`。`onToolError(routeId, listener)` 以同样的路由名
+筛选 opening tool failure：`isError: true` 交付 `code: 'rpc'` 的 `AppClientError`，无效 envelope 或
+缺少 object `structuredContent` 则交付 `invalid-message`；错误不会同时送到 `onToolResult`。每次注册
+都返回 unsubscribe 函数。
+
+**完整公开表面。** 该入口导出 `createAppClient`、`AppClient`、`AppRegister`、
+`AppRouteContract`、`AppRoutes`、`AppRouteId`、`AppRouteInput`、`AppRouteResult`、
+`AppClientError`、`AppClientErrorCode`、`AppConnectOptions`、`CreateAppClientOptions`、
+`AppRequestOptions`、`AppImplementation`、`AppInitializeResult`、`AppMessageEvent`、
+`AppToolInputListener`、`AppToolResultListener`、`AppToolErrorListener`、
+`AppToolCancelledListener`、可注入的 `AppWindow` / `AppMessageTarget` port，以及
+`APP_PROTOCOL_VERSION`。`AppClient` 提供只读 `connected` / `disposed` 状态与 `connect`、
+`request`、`call`、`onToolInput`、`onToolResult`、`onToolError`、`onToolCancelled`、`rebind`、
+`dispose`。
+
+**错误与调用方误用。** 运行时、连接与能力失败统一使用 `AppClientError`，其 `code` 恰好是八种：
+`timeout`、`aborted`、`disposed`、`connection-rebound`、`invalid-message`、`rpc`、
+`capability-unavailable`、`consent-required`。宿主 JSON-RPC 的 `-32601` 映射为
+`capability-unavailable`，`-32001` 映射为 `consent-required`，其他 code 映射为 `rpc`，同时保留
+`rpcCode` 与 `data`。参数种类或契约形状的同步误用——例如错误的 route id、非函数 listener、非精确
+`targetOrigin`、缺少浏览器 window，或非法的 `appInfo` / `appCapabilities`——抛出 `TypeError`；
+超时不是 1 到 2,147,483,647 毫秒之间的安全整数则抛出 `RangeError`。这些都不是 `AB` 诊断。
+
+**生命周期与 origin pin。** Workbench 与 `serve-app` 把 App 渲染为 opaque、no-referrer 的 `srcdoc`
+sandbox，所以文档事先不知道宿主 origin。`connect()` 只向 `'*'` 发送一帧——框架拥有的
+`ui/initialize`——并且只接受 configured parent window（`event.source`）以同一 request id 返回的有效
+initialize result（协议版本 `2026-01-26`，以及 `hostInfo`、`hostCapabilities`、`hostContext`）。
+客户端拒绝 opaque `null` origin，固定响应的 `event.origin`，发送
+`ui/notifications/initialized`，之后只向该精确 origin 发送并只接受同时匹配 source 与 origin 的消息。
+能预先给出可信 origin 的宿主可传入精确的 `http:` / `https:` `targetOrigin`；`'*'` 会被拒绝，且不会有
+任何 wildcard frame。`connect()` 幂等。`rebind({ parent?, targetOrigin?, window? })` 以
+`connection-rebound` 拒绝旧 generation 的 pending request、撤销 pin，再对新 parent 握手。
+`dispose()` 同样幂等：移除 listener，以 `disposed` 拒绝 pending request，并丢弃所有注册；宿主发来的
+`ui/resource-teardown` request 会先得到确认，再 dispose 客户端。可注入的 `window` 与 `parent` 让测试
+及非 DOM 宿主能驱动同一个客户端。
+
+**宿主侧边界。** 客户端只是 iframe 内的半座桥。frame relay、sandbox proxy、宿主页面、
+`/api/mcp/...` 路由与 consent authority 都属于宿主；Workbench MCP 页面、`agent-bundle serve-app`、
+嵌入 App 的 MCP 宿主，以及 [#564](https://github.com/ScriptedAlchemy/agent-bundle/issues/564)
+计划的独立生产宿主，都会通过同一份 wire contract（`McpAppBridge`）服务这个客户端。由宿主而不是 App
+决定 call 到达哪台服务器、哪些能力需要同意；App 不能绕过 relay 访问前台服务器或 MCP backend。
+
+`agent-bundle/app` 不携带编译器，编译器会像其他依赖一样从已安装的包把它内联进 App 文档，因此 App 中的
+值导入不会触发保护自包含可执行文件的 `AB4837`。
 
 ### 保留标识符优先
 
diff --git a/website/docs/zh/reference/api.mdx b/website/docs/zh/reference/api.mdx
index b9440a452..d50c7c093 100644
--- a/website/docs/zh/reference/api.mdx
+++ b/website/docs/zh/reference/api.mdx
@@ -14,7 +14,7 @@ description: '生成的 agent-bundle 类型 API：它覆盖哪些入口点、如
 | --- | --- |
 | `agent-bundle` | 编写与编排表面：`defineSkill`、`canonicalAgentEvents`、`startDevServer`、`runEvals`、`compareEvals`、eval harness 工厂，以及产物清单辅助函数。 |
 | `agent-bundle/api` | 程序化编译器：`build`、`validate`、`inspect`、`prepack`，及其选项与结果类型，`AgentComponentKind` / `componentKindCapability` 组件类型辅助，以及产物操作 `listMcp`、`invokeMcp`、`runMcp`、`serveApp`（在浏览器里独立提供一个已构建的 MCP App——面向脚本与测试的宿主进程 API；产物内部的路由式 CLI 命令则改用 `agent-bundle/serve-app-command` 中的 `spawnServeApp`，见[独立提供 App](../guide/authoring/mcp.mdx#独立提供-app)）、`listHooks` 与 `simulateHook`；另有 Rspack stats 格式化工具 `rspackStatsErrors`、`describeRspackStatsError` 与 `formatRspackStatsError`，把一条编译错误渲染成与编译器 `AB4770` 相同的 `<file>:<line>:<column>: <message>` 行，供自行驱动 Rsbuild 编译的工具使用。 |
-| `agent-bundle/app` | 浏览器安全且不携带编译器的 MCP App 客户端：`createAppClient`、`AppRegister`、`AppClientError`，以及 `connect`、`call`、`request`、`onToolInput`、`onToolResult`、`onToolCancelled`、`rebind` 与 `dispose` 生命周期。编译器通过 `.agent-bundle/routes.d.ts` augmentation 提供 `tool:<server>/<name>` 路由的输入与结构化输出类型。 |
+| `agent-bundle/app` | 浏览器安全且不携带编译器的 MCP App 客户端：`createAppClient`；`AppClient` 的 `connect`、`call`、`request`、`onToolInput`、`onToolResult`、`onToolError`、`onToolCancelled`、`rebind` 与 `dispose` 生命周期；`AppClientError` 与恰好八种 `code`；由 `.agent-bundle/routes.d.ts` 使用项目 `tool:<server>/<name>` 契约扩充的 `AppRegister`；`AppRouteContract` / `AppRoutes` / `AppRouteId` / `AppRouteInput` / `AppRouteResult`；连接、请求、初始化、实现与 listener 类型；可注入的 `AppWindow` / `AppMessageTarget` port；以及 `APP_PROTOCOL_VERSION`。该入口不导入 Zod、Node 或编译器，只用于 App 视图。 |
 | `agent-bundle/config` | `defineConfig` 与配置类型。 |
 | `agent-bundle/test` | 路由测试 harness、匹配器与契约矩阵。 |
 | `agent-bundle/test/browser` | 面向浏览器渲染视图的 MCP App bridge harness。 |
diff --git a/website/docs/zh/reference/security.mdx b/website/docs/zh/reference/security.mdx
index de0b44431..7f3869ae7 100644
--- a/website/docs/zh/reference/security.mdx
+++ b/website/docs/zh/reference/security.mdx
@@ -49,10 +49,14 @@ Skill Markdown 中的原始 HTML、JSX/MDX 与 Mermaid 在 Workbench 渲染器
 检查；App 文档运行在框架沙箱内的第二个 loopback origin 上，并且每一个 App 动作仍与 Workbench 一样经过同一
 个同意授权（`--allow` 代操作者预先批准指定能力）。它是本地预览宿主，不是部署目标。
 
-`agent-bundle/app` 的浏览器传输也不会信任任意 `postMessage` 发送者。沙箱先以 opaque-origin `srcdoc`
-引导，因此框架只用通配目标发送第一次 `ui/initialize`；客户端仅接受预期 parent `Window` 以匹配请求 id
-返回的有效初始化响应，并从该响应固定明确的 `origin`。此后每条消息都必须同时匹配该 `source` 与
-`origin`。关闭或由 App 显式 `rebind` 会撤销旧 pin 并取消仍在等待的请求。
+App 文档内的 `agent-bundle/app` 客户端也不会信任任意 `postMessage` 发送者。sandbox 是 opaque、
+no-referrer 的 `srcdoc`，所以文档在第一帧前不知道宿主 origin：`connect()` 恰好只向 `'*'` 发送一条
+框架拥有的 `ui/initialize` request，仅接受 configured parent window 以该 request id 返回的有效
+initialize result，并固定响应 origin——opaque 的 `null` origin 会被拒绝。此后发送与接收都只允许同时
+匹配该精确 `source` 与 `origin`。能给出宿主 origin 的调用方传入精确的 `http:` / `https:`
+`targetOrigin`；`'*'` 会被拒绝，且不会发送任何 wildcard frame。`rebind()` 与 `dispose()` 都撤销 pin
+并拒绝所有 pending request，旧 generation 因此不可能收到后续宿主的消息；author code 没有 wildcard
+发送路径。
 
 这条桥接以宿主 relay 为安全边界：App 客户端只与预期 parent 通信；Workbench、`serve-app` 或嵌入式 MCP
 宿主负责把允许的请求转发到所绑定的那一个服务器，并继续执行各自的认证、能力与同意策略。App 不会绕过

From e85b9550496f54e8289777119d4dc02d4952689c Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Sat, 5 Sep 2026 07:23:43 +0000
Subject: [PATCH 3/5] docs: restore MCP authoring locale parity

---
 website/docs/zh/guide/authoring/mcp.mdx | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/website/docs/zh/guide/authoring/mcp.mdx b/website/docs/zh/guide/authoring/mcp.mdx
index 2796c242c..8c45416a8 100644
--- a/website/docs/zh/guide/authoring/mcp.mdx
+++ b/website/docs/zh/guide/authoring/mcp.mdx
@@ -732,7 +732,8 @@ declare module 'agent-bundle/app' {
 
 成员就是项目生成的 MCP **工具**路由：`input` 来自各路由的 `inputSchema`，`result` 来自
 `resultSchema`。该声明以 type-only 方式导入路由模块，所以不会把路由模块、schema 或服务器代码带入 App
-文档。没有 augmentation 时——例如手写服务器——`call()` 仍能以 `unknown` 输入与结果工作，视图也可以
+文档。模板已经在 `tsconfig.json` 的 `include` 中列出 `".agent-bundle/routes.d.ts"`；路由项目漏掉它时
+会收到 `AB4834`。没有 augmentation 时——例如手写服务器——`call()` 仍能以 `unknown` 输入与结果工作，视图也可以
 通过同一个结构化 `AppRegister` seam 声明自己的本地契约 map；[MCP App 示例](../../examples/mcp-app.mdx)
 就为手写的 `status` 服务器这样声明 `show-status` 与 `refresh-status`。`AppRouteId`、
 `AppRouteInput<Id>` 与 `AppRouteResult<Id>` 为 wrapper 命名同一套类型表面。
@@ -740,7 +741,8 @@ declare module 'agent-bundle/app' {
 **调用与结果。** `call()` 直接返回结构化结果对象；MCP 的 `content`、`_meta` 与 `isError` envelope
 只是 transport 数据。工具结果带有 `isError: true` 时，它会以 `code: 'rpc'` 拒绝，并把完整结果保存在
 `error.data`；没有 object `structuredContent` 或结果格式不合法时则以 `invalid-message` 拒绝。只有根为
-对象的 `resultSchema` 才会产生 `structuredContent`，因此 scalar 或 array 结果不是带类型的 App call。
+对象的 `resultSchema` 才会产生 `structuredContent`；契约表仍会定型 scalar 或 array 路由，但对它们的
+`call()` 每次都会以 `invalid-message` 拒绝。
 `request(method, params?)` 是读取 `resources/read` 及宿主支持的 `ui/*` method 的底层逃生舱，按原样返回
 JSON-RPC result。两者都会在尚未 `connect()` 时先连接；每个请求都接受
 `{ signal?: AbortSignal, timeoutMs?: number }`。客户端默认超时为 15 秒，也可在
@@ -759,7 +761,7 @@ JSON-RPC result。两者都会在尚未 `connect()` 时先连接；每个请求
 **完整公开表面。** 该入口导出 `createAppClient`、`AppClient`、`AppRegister`、
 `AppRouteContract`、`AppRoutes`、`AppRouteId`、`AppRouteInput`、`AppRouteResult`、
 `AppClientError`、`AppClientErrorCode`、`AppConnectOptions`、`CreateAppClientOptions`、
-`AppRequestOptions`、`AppImplementation`、`AppInitializeResult`、`AppMessageEvent`、
+`AppRequestOptions`、`AppAbortSignal`、`AppImplementation`、`AppInitializeResult`、`AppMessageEvent`、
 `AppToolInputListener`、`AppToolResultListener`、`AppToolErrorListener`、
 `AppToolCancelledListener`、可注入的 `AppWindow` / `AppMessageTarget` port，以及
 `APP_PROTOCOL_VERSION`。`AppClient` 提供只读 `connected` / `disposed` 状态与 `connect`、
@@ -821,7 +823,14 @@ MCP App "status" failed to compile: views/status.ts:1:10: Module build failed
 包括 `tsconfig.json` 问题那种不带位置的形式。
 
 成功的构建会在 `Built …` 之后为每个 App 打印一行，按 target 与 App 名称排序，给出输出体积及其
-gzip 体积（`--json` 中为 `build.compiledMcpApps[].size.bytes` 与 `.gzipBytes`）。数字来自当次实际
+gzip 体积（`--json` 中为 `build.compiledMcpApps[].size.bytes` 与 `.gzipBytes`）：
+
+```text
+Built <plugin> to …/<plugin>/artifact
+MCP App <name> (<target>): mcp-apps/<name>.html <size> (<gzip size> gzip)
+```
+
+数字来自当次实际
 输出；不要把某次示例构建的体积当作固定契约。
 
 任何导入 `@modelcontextprotocol/ext-apps` 的视图都会带上 `zod`（v3 与 v4）、

From 1f7858063ae3ff543a2ef7bbf171d038e4fa4973 Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Sat, 5 Sep 2026 07:35:34 +0000
Subject: [PATCH 4/5] fix: preserve App bridge error semantics

---
 .changeset/typed-app-client.md                |  2 +-
 packages/agent-bundle/src/app/index.ts        | 19 +++++++-------
 .../agent-bundle/tests/app-client.test.ts     | 25 +++++++++++++++++--
 website/docs/en/reference/security.mdx        |  4 +--
 website/docs/zh/reference/security.mdx        |  7 ++++--
 5 files changed, 40 insertions(+), 17 deletions(-)

diff --git a/.changeset/typed-app-client.md b/.changeset/typed-app-client.md
index 6b063dd59..eaf5dd737 100644
--- a/.changeset/typed-app-client.md
+++ b/.changeset/typed-app-client.md
@@ -2,4 +2,4 @@
 "agent-bundle": patch
 ---
 
-Export `createAppClient` from `agent-bundle/app` so MCP App views call typed host routes without importing the compiler, and reword `AB4837` to name Apps as the exception. (#601)
+Export `createAppClient` from `agent-bundle/app` with generated `AppRegister` route contracts, make `createMcpAppBridge` cancel App-owned requests and reject duplicate request ids, and reword `AB4837` to name Apps as the bundle-safe exception. (#601)
diff --git a/packages/agent-bundle/src/app/index.ts b/packages/agent-bundle/src/app/index.ts
index bb7bd307d..2873c0420 100644
--- a/packages/agent-bundle/src/app/index.ts
+++ b/packages/agent-bundle/src/app/index.ts
@@ -309,11 +309,6 @@ const toolResultEnvelope = (value: JsonValue): JsonObject | undefined => {
   return value;
 };
 
-const toolResult = (value: JsonValue): JsonObject | undefined => {
-  const result = toolResultEnvelope(value);
-  return result !== undefined && isPlainDataRecord(result.structuredContent) ? result : undefined;
-};
-
 const errorFromRpc = (error: RpcError): AppClientError => {
   const code: AppClientErrorCode = error.code === -32601
     ? 'capability-unavailable'
@@ -655,13 +650,16 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
       throw new AppClientError('invalid-message', `Input for ${routeId} must be a finite strict JSON object.`);
     }
     const response = await request<JsonValue>('tools/call', { arguments: argumentsValue, name }, requestOptions);
-    const result = toolResult(response);
+    const result = toolResultEnvelope(response);
     if (result === undefined) {
-      throw new AppClientError('invalid-message', `Tool ${routeId} returned an invalid structured result.`);
+      throw new AppClientError('invalid-message', `Tool ${routeId} returned an invalid result envelope.`);
     }
     if (result.isError === true) {
       throw new AppClientError('rpc', `Tool ${routeId} returned an error.`, { data: result });
     }
+    if (!isPlainDataRecord(result.structuredContent)) {
+      throw new AppClientError('invalid-message', `Tool ${routeId} returned an invalid structured result.`);
+    }
     return result.structuredContent as AppRouteResult<Id>;
   };
 
@@ -697,6 +695,9 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
     },
     async rebind(rebindOptions: AppConnectOptions = {}): Promise<AppInitializeResult> {
       if (isDisposed) throw new AppClientError('disposed', 'The App client was disposed.');
+      const nextOrigin = hasOwn(rebindOptions, 'targetOrigin')
+        ? trustedOrigin(rebindOptions.targetOrigin)
+        : configuredOrigin;
       connectionGeneration += 1;
       rejectPending(
         'connection-rebound',
@@ -714,9 +715,7 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
         boundWindow.addEventListener('message', receive);
       }
       parent = rebindOptions.parent ?? boundWindow.parent;
-      if (hasOwn(rebindOptions, 'targetOrigin')) {
-        configuredOrigin = trustedOrigin(rebindOptions.targetOrigin);
-      }
+      configuredOrigin = nextOrigin;
       pinnedOrigin = configuredOrigin;
       return await connect();
     },
diff --git a/packages/agent-bundle/tests/app-client.test.ts b/packages/agent-bundle/tests/app-client.test.ts
index 77ffbdbd4..3dde18aa8 100644
--- a/packages/agent-bundle/tests/app-client.test.ts
+++ b/packages/agent-bundle/tests/app-client.test.ts
@@ -320,10 +320,15 @@ it('rejects malformed envelopes and tool results without retaining hostile value
     result: {
       content: [{ text: 'failed', type: 'text' }],
       isError: true,
-      structuredContent: { reason: 'unavailable' },
     },
   });
-  await expect(failed).rejects.toMatchObject({ code: 'rpc' });
+  await expect(failed).rejects.toMatchObject({
+    code: 'rpc',
+    data: {
+      content: [{ text: 'failed', type: 'text' }],
+      isError: true,
+    },
+  });
 
   const cyclic: Record<string, unknown> = {};
   cyclic.self = cyclic;
@@ -514,6 +519,22 @@ it('rejects old pending work on rebind and establishes a fresh exact-origin conn
   expect(client.connected).toBe(true);
 });
 
+it('validates a rebind origin before changing the live connection', async () => {
+  const target = harness();
+  const client = createAppClient({ window: target.window });
+  await connect(client, target);
+  const pending = client.request('slow', {});
+  const pendingId = responseId(target.posts.at(-1)!);
+  const postCount = target.posts.length;
+
+  await expect(client.rebind({ targetOrigin: '*' })).rejects.toThrow(/exact trusted origin/u);
+  expect(client.connected).toBe(true);
+  expect(target.posts).toHaveLength(postCount);
+
+  target.emit({ id: pendingId, jsonrpc: '2.0', result: { kept: true } });
+  await expect(pending).resolves.toEqual({ kept: true });
+});
+
 it('keeps one fresh handshake when rebinding during connect and inherits targetOrigin', async () => {
   const first = harness();
   const second = harness();
diff --git a/website/docs/en/reference/security.mdx b/website/docs/en/reference/security.mdx
index 28cb6b292..5c9ea1b2c 100644
--- a/website/docs/en/reference/security.mdx
+++ b/website/docs/en/reference/security.mdx
@@ -62,8 +62,8 @@ It is a local preview host, not a deployment target.
 
 Inside the App document, the `agent-bundle/app` client trusts no arbitrary `postMessage` sender.
 The sandbox is an opaque, no-referrer `srcdoc`, so the document cannot know its host's origin
-before the first frame: `connect()` sends exactly one framework-owned `ui/initialize` request to
-`'*'`, accepts a response only from the configured parent window with that request's id and a
+before the first frame: each `connect()` handshake attempt sends one framework-owned
+`ui/initialize` request to `'*'`, accepts a response only from the configured parent window with that request's id and a
 valid initialize result, pins the responding origin — it must be an exact `http:`/`https:`
 origin; an opaque `null`, empty, or other-scheme origin fails the handshake — and from then on
 sends to and accepts from that exact `source` and `origin` only. A host that can name its origin
diff --git a/website/docs/zh/reference/security.mdx b/website/docs/zh/reference/security.mdx
index 7f3869ae7..5f18d84e1 100644
--- a/website/docs/zh/reference/security.mdx
+++ b/website/docs/zh/reference/security.mdx
@@ -50,8 +50,8 @@ Skill Markdown 中的原始 HTML、JSX/MDX 与 Mermaid 在 Workbench 渲染器
 个同意授权（`--allow` 代操作者预先批准指定能力）。它是本地预览宿主，不是部署目标。
 
 App 文档内的 `agent-bundle/app` 客户端也不会信任任意 `postMessage` 发送者。sandbox 是 opaque、
-no-referrer 的 `srcdoc`，所以文档在第一帧前不知道宿主 origin：`connect()` 恰好只向 `'*'` 发送一条
-框架拥有的 `ui/initialize` request，仅接受 configured parent window 以该 request id 返回的有效
+no-referrer 的 `srcdoc`，所以文档在第一帧前不知道宿主 origin：每次 `connect()` 握手尝试只向 `'*'`
+发送一条框架拥有的 `ui/initialize` request，仅接受 configured parent window 以该 request id 返回的有效
 initialize result，并固定响应 origin——opaque 的 `null` origin 会被拒绝。此后发送与接收都只允许同时
 匹配该精确 `source` 与 `origin`。能给出宿主 origin 的调用方传入精确的 `http:` / `https:`
 `targetOrigin`；`'*'` 会被拒绝，且不会发送任何 wildcard frame。`rebind()` 与 `dispose()` 都撤销 pin
@@ -61,6 +61,9 @@ initialize result，并固定响应 origin——opaque 的 `null` origin 会被
 这条桥接以宿主 relay 为安全边界：App 客户端只与预期 parent 通信；Workbench、`serve-app` 或嵌入式 MCP
 宿主负责把允许的请求转发到所绑定的那一个服务器，并继续执行各自的认证、能力与同意策略。App 不会绕过
 relay 直接访问前台路由或 MCP 后端，relay 也不会把另一个 App、服务器或浏览器 origin 的权限合并进来。
+取消也遵循同一边界：框架宿主桥只处理 App 自己发起且仍在进行中的 request 所对应的
+`notifications/cancelled`——中止这一项操作并拒绝其仍待决定的同意挑战——因此取消既不能绕过同意，也不能
+触碰不是该 App 发起的 request。
 
 ## Agent API
 

From e5f3fe49b60debdec355fb873b778bc8036f4141 Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Sat, 5 Sep 2026 08:01:11 +0000
Subject: [PATCH 5/5] fix: bind typed App calls to their server

---
 .changeset/typed-app-client.md                |  2 +-
 docs/entry-conventions.md                     | 12 ++---
 packages/agent-bundle/src/app/index.ts        | 11 ++++-
 .../src/contracts/mcp-app-protocol.ts         |  3 ++
 .../src/dev/mcp-apps/mcp-app-bridge.ts        | 24 +++++++++-
 packages/agent-bundle/src/test/browser.ts     | 11 ++++-
 .../agent-bundle/tests/app-client.test.ts     |  6 ++-
 .../tests/generated-route-server.test.ts      |  4 +-
 .../agent-bundle/tests/mcp-app-bridge.test.ts | 46 +++++++++++++++++++
 website/docs/en/guide/authoring/mcp.mdx       |  8 ++--
 website/docs/zh/guide/authoring/mcp.mdx       |  5 +-
 11 files changed, 113 insertions(+), 19 deletions(-)

diff --git a/.changeset/typed-app-client.md b/.changeset/typed-app-client.md
index eaf5dd737..789586f39 100644
--- a/.changeset/typed-app-client.md
+++ b/.changeset/typed-app-client.md
@@ -2,4 +2,4 @@
 "agent-bundle": patch
 ---
 
-Export `createAppClient` from `agent-bundle/app` with generated `AppRegister` route contracts, make `createMcpAppBridge` cancel App-owned requests and reject duplicate request ids, and reword `AB4837` to name Apps as the bundle-safe exception. (#601)
+Export `createAppClient` from `agent-bundle/app` with generated `AppRegister` route contracts, make `createMcpAppBridge` validate bound route ids, cancel App-owned requests, and reject duplicate request ids, and reword `AB4837` to name Apps as the bundle-safe exception. (#601)
diff --git a/docs/entry-conventions.md b/docs/entry-conventions.md
index 1e4025456..2521403b2 100644
--- a/docs/entry-conventions.md
+++ b/docs/entry-conventions.md
@@ -1581,7 +1581,7 @@ capability needs consent.
 | Member | Contract |
 | --- | --- |
 | `connect(options?)` | Performs the `ui/initialize` handshake once and resolves the validated `AppInitializeResult` (`protocolVersion` `2026-01-26` — `APP_PROTOCOL_VERSION` — plus `hostInfo`, `hostCapabilities`, `hostContext`), then sends `ui/notifications/initialized` and records the opening tool name from `hostContext.toolInfo.tool.name` for the opening-notification listeners. Idempotent: a connected client resolves the cached result, a connecting one returns the in-flight promise; a handshake that `rebind()` overtakes rejects with `connection-rebound`. |
-| `call(routeId, input, options?)` | `tools/call` for the tool a `tool:<server>/<name>` route id names — the wire name is the final segment, derived the way the generated server derives it (`src/routes/protocol-name.ts`); any other shape rejects with a `TypeError`. The server segment is not on the wire: `tools/call` carries `name` alone and the host dispatches it to the server the App is bound to, so an id naming another server's tool reaches the bound server's tool of that name, or fails there. `input` must be a finite strict-JSON object (`invalid-message` otherwise). Resolves the result's `structuredContent` **directly**; rejects a result with `isError: true` (`rpc`, whole result on `error.data`), one without an object `structuredContent`, or a malformed envelope (`invalid-message`). The MCP projection emits `structuredContent` for object-valued results only (`advertisedOutputSchema` in `src/mcp-server-runtime.ts`), so a tool whose `resultSchema` is scalar- or array-rooted is typed by the generated map but never resolves through `call()`. |
+| `call(routeId, input, options?)` | `tools/call` for the tool a `tool:<server>/<name>` route id names — the standard wire name is the final segment, derived the way the generated server derives it (`src/routes/protocol-name.ts`); any other shape rejects with a `TypeError`. The client also carries the canonical id in framework-private `_meta`, and `createMcpAppBridge` rejects it with `-32602` unless both server and tool match the bound server before dispatch. `input` must be a finite strict-JSON object (`invalid-message` otherwise). Resolves the result's `structuredContent` **directly**; rejects a result with `isError: true` (`rpc`, whole result on `error.data`), one without an object `structuredContent`, or a malformed envelope (`invalid-message`). The MCP projection emits `structuredContent` for object-valued results only (`advertisedOutputSchema` in `src/mcp-server-runtime.ts`), so a tool whose `resultSchema` is scalar- or array-rooted is typed by the generated map but never resolves through `call()`. |
 | `request(method, params?, options?)` | The typed JSON-RPC escape hatch for `resources/read` and supported `ui/*` methods; resolves the raw result. An empty method rejects with a `TypeError`. |
 | `onToolInput(routeId, listener)` / `onToolResult(routeId, listener)` / `onToolError(routeId, listener)` | The opening call's `ui/notifications/tool-input` arguments, the decoded `structuredContent` of a successful `ui/notifications/tool-result`, and that notification's failures as an `AppClientError` — `isError: true` is `rpc` with the whole result on `data`; a malformed envelope or one without an object `structuredContent` is `invalid-message`; a failed result never reaches `onToolResult`. The notifications carry no tool name, so dispatch keys on the tool the handshake named: `hostContext.toolInfo.tool.name` from the initialize result, matched against the final segment of each registered route id. Listeners for other tools stay silent; when the initialize result names no tool, `tool-input` and `tool-result` reach no listener. Listeners run on a microtask, exceptions dropped. Each returns its unsubscribe function. |
 | `onToolCancelled(listener)` | `ui/notifications/tool-cancelled` as `{ reason? }`, unfiltered; returns its unsubscribe function. |
@@ -1593,9 +1593,9 @@ capability needs consent.
 `agent-bundle-app` / `1.0.0`), `appCapabilities` (a finite JSON object,
 default `{}`), `timeoutMs` (integer milliseconds, 1 to 2³¹ − 1, default
 15 000), and the connect options `parent`, `targetOrigin`, `window`. Every
-request takes `{ signal, timeoutMs }`. `signal` is typed as the ambient
-`AbortSignal` of whichever `lib` the App program compiles against (DOM in a
-view, Node in the unit tests) and is used structurally: the client reads
+request takes `{ signal, timeoutMs }`. `signal` uses the exported structural
+`AppAbortSignal` contract, which the ambient DOM or Node `AbortSignal`
+satisfies: the client reads
 `aborted`, adds one `abort` listener, and removes it when the request settles.
 A request that times out or is aborted rejects with `timeout` / `aborted` and,
 once connected, sends `notifications/cancelled` with the request id and the
@@ -1635,8 +1635,8 @@ threaded through `McpAppBindingService.callTool`/`readResource` and the
 with `AbortSignal.any`, so the bound MCP session's request is cancelled too. A
 cancellation for an unknown or finished id is a no-op; one arriving before the
 App is initialized is ignored; one carrying an `id` is rejected as malformed;
-and a duplicate in-flight request id is rejected `-32602` without touching the
-original. Re-initialization and close abort every in-flight request.
+and a duplicate in-flight request id aborts the ambiguous original operation
+and is rejected `-32602`. Re-initialization and close abort every in-flight request.
 `tests/mcp-app-bridge-cancellation.test.ts` covers each of those, including
 that cancellation cannot bypass consent or reach a request the App did not
 start. Hosts outside the framework apply their own policy; the client's
diff --git a/packages/agent-bundle/src/app/index.ts b/packages/agent-bundle/src/app/index.ts
index 2873c0420..cd707c2ad 100644
--- a/packages/agent-bundle/src/app/index.ts
+++ b/packages/agent-bundle/src/app/index.ts
@@ -1,4 +1,7 @@
-import { MCP_APP_PROTOCOL_VERSION } from '../contracts/mcp-app-protocol.ts';
+import {
+  MCP_APP_PROTOCOL_VERSION,
+  MCP_APP_ROUTE_ID_META_KEY,
+} from '../contracts/mcp-app-protocol.ts';
 import {
   type JsonObject,
   type JsonValue,
@@ -649,7 +652,11 @@ export const createAppClient = (options: CreateAppClientOptions = {}): AppClient
     } catch {
       throw new AppClientError('invalid-message', `Input for ${routeId} must be a finite strict JSON object.`);
     }
-    const response = await request<JsonValue>('tools/call', { arguments: argumentsValue, name }, requestOptions);
+    const response = await request<JsonValue>('tools/call', {
+      _meta: { [MCP_APP_ROUTE_ID_META_KEY]: routeId },
+      arguments: argumentsValue,
+      name,
+    }, requestOptions);
     const result = toolResultEnvelope(response);
     if (result === undefined) {
       throw new AppClientError('invalid-message', `Tool ${routeId} returned an invalid result envelope.`);
diff --git a/packages/agent-bundle/src/contracts/mcp-app-protocol.ts b/packages/agent-bundle/src/contracts/mcp-app-protocol.ts
index 47dec2a57..baaf4660d 100644
--- a/packages/agent-bundle/src/contracts/mcp-app-protocol.ts
+++ b/packages/agent-bundle/src/contracts/mcp-app-protocol.ts
@@ -1,2 +1,5 @@
 /** Protocol version shared by MCP App hosts and clients. */
 export const MCP_APP_PROTOCOL_VERSION = '2026-01-26';
+
+/** Private `tools/call` metadata key carrying the canonical generated route id. */
+export const MCP_APP_ROUTE_ID_META_KEY = 'io.agent-bundle/route-id';
diff --git a/packages/agent-bundle/src/dev/mcp-apps/mcp-app-bridge.ts b/packages/agent-bundle/src/dev/mcp-apps/mcp-app-bridge.ts
index 35e4e0891..d26fe2dcb 100644
--- a/packages/agent-bundle/src/dev/mcp-apps/mcp-app-bridge.ts
+++ b/packages/agent-bundle/src/dev/mcp-apps/mcp-app-bridge.ts
@@ -1,3 +1,4 @@
+import { MCP_APP_ROUTE_ID_META_KEY } from '../../contracts/mcp-app-protocol.ts';
 import { MAX_APP_HTML_BYTES } from '../../core/mcp-app-limits.ts';
 import {
   validateMcpAppDownloadRequest,
@@ -71,6 +72,7 @@ export class McpAppBridgeCloseError extends Error {
 export interface McpAppBridgeToolCall {
   readonly arguments?: McpAppJsonValue;
   readonly name: string;
+  readonly routeId?: string;
 }
 
 export interface McpAppBridgeResourceRead {
@@ -198,6 +200,7 @@ interface BridgeBindingSnapshot {
   readonly input: McpAppJsonValue;
   readonly resourceUri: string;
   readonly result: McpAppJsonValue;
+  readonly serverName: string;
   readonly toolDefinition: McpAppBinding['toolDefinition'];
 }
 
@@ -296,7 +299,9 @@ const normalizedQueuedHostMessageBytes = (value: number | undefined): number =>
 };
 
 const snapshotBinding = (value: McpAppBinding): BridgeBindingSnapshot => {
-  if (!nonempty(value.id) || !nonempty(value.resourceUri)) throw new TypeError('MCP App bridge binding must contain nonempty id and resource URI values.');
+  if (!nonempty(value.id) || !nonempty(value.resourceUri) || !nonempty(value.serverName)) {
+    throw new TypeError('MCP App bridge binding must contain nonempty id, resource URI, and server name values.');
+  }
   const input = jsonRecord(value.input);
   const result = validToolResult(value.result);
   const toolDefinition = jsonRecord(value.toolDefinition);
@@ -306,6 +311,7 @@ const snapshotBinding = (value: McpAppBinding): BridgeBindingSnapshot => {
     input,
     resourceUri: value.resourceUri,
     result,
+    serverName: value.serverName,
     toolDefinition: toolDefinition as McpAppBinding['toolDefinition'],
   });
 };
@@ -636,7 +642,15 @@ const validToolCall = (params: McpAppJsonValue | undefined): McpAppBridgeToolCal
   const record = jsonRecord(params);
   if (record === undefined || !nonempty(record.name)) return undefined;
   if (record.arguments !== undefined && jsonRecord(record.arguments) === undefined) return undefined;
-  return Object.freeze({ ...(record.arguments === undefined ? {} : { arguments: cloneJson(record.arguments) }), name: record.name });
+  const meta = record._meta === undefined ? undefined : jsonRecord(record._meta);
+  if (record._meta !== undefined && meta === undefined) return undefined;
+  const routeId = meta?.[MCP_APP_ROUTE_ID_META_KEY];
+  if (routeId !== undefined && !nonempty(routeId)) return undefined;
+  return Object.freeze({
+    ...(record.arguments === undefined ? {} : { arguments: cloneJson(record.arguments) }),
+    name: record.name,
+    ...(routeId === undefined ? {} : { routeId }),
+  });
 };
 
 const validResourceRead = (params: McpAppJsonValue | undefined): McpAppBridgeResourceRead | undefined => {
@@ -1145,6 +1159,12 @@ export const createMcpAppBridge = (options: CreateMcpAppBridgeOptions): McpAppBr
       case 'tools/call': {
         const request = validToolCall(message.params);
         if (request === undefined) return fail(id, -32602, 'tools/call requires a name and finite JSON arguments.');
+        if (
+          request.routeId !== undefined
+          && request.routeId !== `tool:${binding.serverName}/${request.name}`
+        ) {
+          return fail(id, -32602, 'tools/call route id does not match the bound MCP server and tool.');
+        }
         const controller = beginInFlight(id);
         if (controller === undefined) return rejectDuplicateInFlight(id);
         const details = Object.freeze({ ...(request.arguments === undefined ? {} : { arguments: request.arguments }), name: request.name });
diff --git a/packages/agent-bundle/src/test/browser.ts b/packages/agent-bundle/src/test/browser.ts
index 3395e5e1a..864e8ffb9 100644
--- a/packages/agent-bundle/src/test/browser.ts
+++ b/packages/agent-bundle/src/test/browser.ts
@@ -68,6 +68,8 @@ export interface MountBrowserAppOptions {
   readonly operations: McpAppBridgeBindingOperations;
   readonly profile?: McpAppProfileId;
   readonly scriptedConsent?: BrowserAppScriptedConsent;
+  /** MCP server to bind when one compiled App is shared by several servers. */
+  readonly serverName?: string;
   readonly timeoutMs?: number;
   readonly toolDefinition?: McpAppToolDefinition;
   readonly toolInput?: McpAppBridgeJsonRecord;
@@ -235,6 +237,13 @@ const bindingFor = (
   options: MountBrowserAppOptions,
 ): McpAppBinding => {
   const toolName = options.toolName ?? `show-${app.name}`;
+  const serverNames = app.serverIds.map((id) => id.startsWith('mcp:') ? id.slice('mcp:'.length) : id);
+  const serverName = options.serverName ?? (serverNames.length === 1 ? serverNames[0] : undefined);
+  if (serverName === undefined || !serverNames.includes(serverName)) {
+    throw new TypeError(
+      `Browser App ${JSON.stringify(app.name)} requires one serverName from ${JSON.stringify(serverNames)}.`,
+    );
+  }
   return Object.freeze({
     epochId: `browser-app:${app.name}`,
     id: `browser-app-binding-${String(nextBindingId++)}`,
@@ -242,7 +251,7 @@ const bindingFor = (
     previewProfile: selectedProfile(app, options.profile),
     resourceUri: app.resourceUri,
     result: options.toolResult,
-    serverName: app.serverIds.join(','),
+    serverName,
     sessionId: `browser-app-session:${app.name}`,
     target: app.target,
     toolDefinition: options.toolDefinition ?? Object.freeze({
diff --git a/packages/agent-bundle/tests/app-client.test.ts b/packages/agent-bundle/tests/app-client.test.ts
index 3dde18aa8..80147eaab 100644
--- a/packages/agent-bundle/tests/app-client.test.ts
+++ b/packages/agent-bundle/tests/app-client.test.ts
@@ -246,7 +246,11 @@ it('calls a route by its protocol tool name and returns structuredContent direct
       id: 2,
       jsonrpc: '2.0',
       method: 'tools/call',
-      params: { arguments: { limit: 40 }, name: 'hauler_status' },
+      params: {
+        _meta: { 'io.agent-bundle/route-id': 'tool:hauler/hauler_status' },
+        arguments: { limit: 40 },
+        name: 'hauler_status',
+      },
     },
     targetOrigin: hostOrigin,
   });
diff --git a/packages/agent-bundle/tests/generated-route-server.test.ts b/packages/agent-bundle/tests/generated-route-server.test.ts
index 7718d0850..ef51e4898 100644
--- a/packages/agent-bundle/tests/generated-route-server.test.ts
+++ b/packages/agent-bundle/tests/generated-route-server.test.ts
@@ -628,7 +628,7 @@ it('compiles createAppClient().call against generated AppRegister contracts with
   expect(wrongInput).toHaveLength(1);
   expect(wrongInput[0]).toMatch(/Type 'number' is not assignable to type 'string'/u);
 
-  const html = await readFile(join(output, 'portable', 'mcp-apps', 'dashboard.html'), 'utf8');
+  const html = await readFile(join(output, 'mcp-apps', 'dashboard.html'), 'utf8');
   expect(html).toContain('2026-01-26');
   expect(html).toContain('from-app');
   expect([
@@ -641,7 +641,7 @@ it('compiles createAppClient().call against generated AppRegister contracts with
   const server = compiled.model.mcpServers[0]!;
   const client = new Client({ name: 'generated-app-client-test', version: '0.0.0' });
   const transport = new StdioClientTransport({
-    args: [join(output, 'portable', server.args![0]!)],
+    args: [join(output, server.args![0]!)],
     command: process.execPath,
     stderr: 'pipe',
   });
diff --git a/packages/agent-bundle/tests/mcp-app-bridge.test.ts b/packages/agent-bundle/tests/mcp-app-bridge.test.ts
index cb0bdf357..a23022ec6 100644
--- a/packages/agent-bundle/tests/mcp-app-bridge.test.ts
+++ b/packages/agent-bundle/tests/mcp-app-bridge.test.ts
@@ -352,6 +352,52 @@ it('forwards only same-binding app-visible tools and resources while retaining r
   ]);
 });
 
+it('validates a typed client route id against the bound server before dispatch', async () => {
+  const fixture = fixtureFor();
+  const bridge = createMcpAppBridge({
+    binding: fixture.binding,
+    host: fixture.host,
+    operations: fixture.operations,
+    send: (message) => (fixture.sent.push(message), true),
+  });
+  await bridge.receive(initialize('init:route-id'));
+  await bridge.receive(initialized());
+
+  await bridge.receive({
+    id: 'wrong-server',
+    jsonrpc: '2.0',
+    method: 'tools/call',
+    params: {
+      _meta: { 'io.agent-bundle/route-id': 'tool:shelf/refresh-weather' },
+      name: 'refresh-weather',
+    },
+  });
+  expect(fixture.calls).toEqual([]);
+  expect(fixture.sent.at(-1)).toEqual({
+    error: {
+      code: -32602,
+      message: 'tools/call route id does not match the bound MCP server and tool.',
+    },
+    id: 'wrong-server',
+    jsonrpc: '2.0',
+  });
+
+  await bridge.receive({
+    id: 'bound-server',
+    jsonrpc: '2.0',
+    method: 'tools/call',
+    params: {
+      _meta: { 'io.agent-bundle/route-id': 'tool:weather/refresh-weather' },
+      name: 'refresh-weather',
+    },
+  });
+  expect(fixture.calls).toEqual([{
+    arguments: undefined,
+    bindingId: 'binding-app',
+    name: 'refresh-weather',
+  }]);
+});
+
 it('handles standard host actions and rejects malformed app requests without forwarding them', async () => {
   const seen: string[] = [];
   const fixture = fixtureFor({
diff --git a/website/docs/en/guide/authoring/mcp.mdx b/website/docs/en/guide/authoring/mcp.mdx
index 9f1245fd8..f5e51f72c 100644
--- a/website/docs/en/guide/authoring/mcp.mdx
+++ b/website/docs/en/guide/authoring/mcp.mdx
@@ -806,9 +806,11 @@ client.dispose();
 
 **Route ids and types.** A tool is addressed by its route id, `tool:<server>/<name>`. The client
 derives the wire tool name from the final segment, exactly as the generated server does, and any
-other shape is a `TypeError`. The server segment never reaches the wire: `tools/call` carries the
-tool name alone, and the host dispatches it to the one server the App is bound to, so address the
-tools of the server that registered the App. The types come from the compiler: when the route
+other shape is a `TypeError`. `tools/call` carries the final segment as its standard `name` and
+the canonical route id in framework-private `_meta`; `createMcpAppBridge` rejects a route whose
+server segment or name does not match the bound server before dispatch. Other MCP App hosts may
+ignore that private metadata, so address the tools of the server that registered the App. The
+types come from the compiler: when the route
 graph has at least one tool route, the generated `.agent-bundle/routes.d.ts` adds exactly one
 augmentation on `agent-bundle/app`,
 
diff --git a/website/docs/zh/guide/authoring/mcp.mdx b/website/docs/zh/guide/authoring/mcp.mdx
index 8c45416a8..8aaf45668 100644
--- a/website/docs/zh/guide/authoring/mcp.mdx
+++ b/website/docs/zh/guide/authoring/mcp.mdx
@@ -719,7 +719,10 @@ client.dispose();
 ```
 
 **路由 id 与类型。** 工具以 `tool:<server>/<name>` 路由 id 寻址。客户端与生成的服务器一样从最后一段
-推导 wire tool name；其他形状属于调用方误用，会抛出 `TypeError`。当路由图至少包含一条工具路由时，
+推导 wire tool name；其他形状属于调用方误用，会抛出 `TypeError`。`tools/call` 以最后一段作为标准
+`name`，并在框架私有 `_meta` 中携带规范路由 id；`createMcpAppBridge` 会在分派之前拒绝 server 段或
+工具名与当前绑定服务器不符的路由。其他 MCP App 宿主可以忽略这项私有 metadata，因此仍应只寻址注册该
+App 的服务器工具。当路由图至少包含一条工具路由时，
 生成的 `.agent-bundle/routes.d.ts` 会为 `agent-bundle/app` 恰好添加一次 augmentation：
 
 ```ts