First-class `web` surface (production): ship a browser host for the plugin's MCP Apps inside the artifact, openable from the installed CLI (`<plugin> web`); `/web` in dev for parity

[ScriptedAlchemy]

Problem

A plugin built with agent-bundle can ship an MCP server, hooks, skills, a routed CLI, and MCP Apps — but the only ways to look at one of those Apps in a browser are:

• the developer Workbench (agent-bundle dev, checkout only), and
• agent-bundle serve-app / serveApp (Serve a built MCP App standalone in a browser (agent-bundle serve-app / runtime helper) so plugins can offer "open the dashboard" commands #514, feat(cli): serve a built MCP App standalone — agent-bundle serve-app and serveApp in agent-bundle/api (#514) #537), which needs the framework installed next to the project and the built artifact/ on disk — a checkout capability. Let a plugin CLI route serve its own MCP App without bundling the framework #558 sanctions spawning it from a routed CLI, and its option (b) names the gap: nothing that ships inside the artifact can host an App, because the host stack is the Workbench's Effect-based bridge.

cargo-hauler is the concrete case (ScriptedAlchemy/cargo-hauler#83): hauler dashboard exists, but the README has to tell users it does not work from the npm package or an installed host pack — the exact places a user would type it. The same shape recurs for any plugin whose MCP App is also a reasonable web page: a build dashboard, an eval viewer, a notice inbox. Authors want to ship "MCP + CLI + agent plugins, and a web page that opens in a browser pane when you need it", with one component library and one data path (the App already renders from the tool result).

Scope: production first. This is not a dev-server nicety: the web page has to work from the shipped plugin — the npm package, an installed Claude/Codex/Cursor host pack, or a checked-out artifact/ — with no framework on the machine, exactly like the MCP server and CLI already do. Dev parity (/web on the Workbench) is the secondary requirement.

Proposal: a first-class web surface

1. Artifact-resident browser host. Emit into the root (Emit one composite plugin artifact; use targets to select the host projections inside it #555 layout) a dependency-free, bundleable host — web/index.html + web/host.mjs (Node built-ins only, like agent-bundle/launch-env) — that spawns the plugin's own packed mcp/<server>.mjs over stdio, serves the App resource(s) on 127.0.0.1:<port> with the same sandbox/consent/token rules as serve-app, and speaks the MCP Apps ui/* bridge. No Effect, no Workbench, no framework at runtime; every module satisfies AB6005.
2. A generated web command on the routed CLI. <plugin> web [<server>/<app>] [--port N] [--open] [--tool T --input JSON] — the framework owns the argv, the ready signal (url in the JSON result), teardown on the route signal, and the "which App" default (the only App, else required). Plugins stop hand-writing what cargo-hauler wrote 180 lines for.
3. Config/convention. web: { apps: ['<server>/<app>'], open?: 'browser' | 'never' } (or src/web/ for an authored landing page listing the plugin's Apps) selects what the surface exposes; omit it and nothing is emitted. Capability tables record web per host as "browser, host-independent".
4. Dev parity. agent-bundle dev serves the same host at /web/<server>/<app> so the URL a plugin documents is the URL the Workbench shows; serve-app becomes a thin wrapper over the same host.
5. Diagnostics/docs. A named diagnostic when web names an App no tool advertises; en + zh pages for the surface, the command, and the /web path; one minor changeset if the artifact layout gains web/.

Acceptance

• examples/mcp-app gains web.apps; after agent-bundle build, node artifact/bin/<plugin>.mjs web --no-open prints a 127.0.0.1 URL whose page renders the App (not the fallback) populated from the opening tool call, from an installed host pack with no node_modules and no framework on the machine.
• Results larger than 64 KiB render (depends on serve-app: App falls back to the JSON dump when the opening tool result exceeds 64 KiB (AB8010) — host page re-uploads a result the server already has #562); tuple schemas validate in Cursor (independent, outputSchema tuples (prefixItems + items:false) fail Cursor's structured-content validation ("boolean schema is false") — emit an interoperable projection #563).
• agent-bundle dev serves /web/<server>/<app> with the same page.
• Artifact validation passes for all four hosts and the composite root; doctor reports the surface.
• Docs (en + zh), capability tables, docs/entry-conventions.md, changeset.

Relationship to existing issues

• Serve a built MCP App standalone in a browser (agent-bundle serve-app / runtime helper) so plugins can offer "open the dashboard" commands #514 / feat(cli): serve a built MCP App standalone — agent-bundle serve-app and serveApp in agent-bundle/api (#514) #537: the host stack to reuse; serve-app stays as the checkout-time form.
• Let a plugin CLI route serve its own MCP App without bundling the framework #558: option (c) (spawn helper) is the interim; this issue is option (b) done properly, and closes the "checkout only" caveat.
• serve-app: App falls back to the JSON dump when the opening tool result exceeds 64 KiB (AB8010) — host page re-uploads a result the server already has #562 (64 KiB rebind) and outputSchema tuples (prefixItems + items:false) fail Cursor's structured-content validation ("boolean schema is false") — emit an interoperable projection #563 (tuple schema) are the two defects that currently keep the cargo-hauler dashboard from rendering anywhere but an MCP host that tolerates them.

[ScriptedAlchemy]

Source audit of cargo-hauler master (395cee0), for whoever picks this up — facts that shape the design:

• The App (src/mcp/hauler/apps/dashboard.tsx) has no standalone path: it blocks on ui/initialize from a parent (:1653–1663, failure → Retry :1694–1702), takes the opening result from ui/notifications/tool-result, then polls tools/call hauler_status {limit: 40} every 5 s (:305–323) and hauler_result for the drawer (:331–337, 3 s). RPC is window.parent.postMessage(…, '*') with a 15 s timeout (:254–265). So an artifact-resident web host only has to be an MCP Apps host — the App already does the rest.
• App route config is { resourceUri, template } only (:71–74); dashboard.html is a CSS shell with <div id="root"> and no scripts/CSP (src/mcp/hauler/apps/dashboard.html:377) — the framework injects the bundle at build time.
• hauler dashboard (src/cli/dashboard.ts:63–96,152–169) walks up to node_modules/agent-bundle/package.json, reads bin, spawns serve-app hauler/dashboard --tool hauler_status --allow call-tool …, relays the child's stdout to stderr, and parses the at <url> line. The process entry (src/scripts/hauler.ts:254–285) only forwards argv to the routed CLI. README §86 documents it as checkout-only; the skill (src/skills/hauler-dashboard/SKILL.tsx:29–40) tells users "MCP host → call hauler_status; plain browser → hauler dashboard or pnpm run dev".
• Tests never render the App: tests/dashboard.test.ts checks the built mcp-apps/dashboard.html for strings and unit-tests src/dashboard/lib.ts; tests/route-unit/packed-contract.test.ts:199–202 asserts the ui://… resource is listed; the Workbench surface test covers Routes/Lifecycles pages only. A web surface should come with a real render check (the fallback panel in serve-app: App falls back to the JSON dump when the opening tool result exceeds 64 KiB (AB8010) — host page re-uploads a result the server already has #562 went unnoticed for the same reason).

[ScriptedAlchemy]

Architecture alignment with #592: keep the production browser capability, but avoid creating a second routing/registration framework for web.

The preferred direction is:

existing App/page route
  -> shared browser runtime/bridge
  -> MCP-host embedding | Workbench | serve-app | <plugin> web

Concretely, I would narrow item 3 of this issue: web: { apps: [...] } may be acceptable as exposure/policy config, but src/web/** should not become an independent route graph unless a browser-only use case cannot be represented by the canonical application graph. The browser host should consume compiled route/App metadata from the manifest rather than rediscovering Apps or maintaining another registry.

The artifact-resident host, generated CLI command, installed-artifact requirement, sandbox/consent behavior, and dev parity all remain aligned. This is an implementation slice of #592's shared browser projection/runtime.

[ScriptedAlchemy]

cargo-hauler deep-dive strengthens this issue and narrows the desired API.

cargo-hauler/src/cli/dashboard.ts is currently ~150 lines of framework integration glue solely because the production browser host does not ship with the plugin: it locates the checkout/artifact by relative path, crawls node_modules for Agent Bundle's own bin, spawns agent-bundle serve-app, regex-parses the human URL line from stdout, relays abort as SIGTERM, and explicitly fails from npm/installed-host contexts.

That code should disappear completely when this lands. The app-level input should be only "expose hauler/dashboard, open with hauler_status, allow call-tool"; Agent Bundle should own the generated CLI command, ready/result protocol, browser opening, process lifecycle, and artifact-resident bridge.

Also link #594: the standalone host and embedded MCP App should use the same generated typed App client/bridge. Do not make the production web host emulate one transport while Apps hand-write another.

[ScriptedAlchemy]

Design note — the web surface as a slice of #592's shared browser projection

Read-only design, written against main @ 23d129e94 and the head of #578 (e55007332). Six code-reading lanes covered the serve-app stack, the Workbench browser bridge, build/compose/manifest/CLI bins (on the #578 tree), config + MCP runtime + response boundary, install/doctor/tests/docs, and the dev server. Every path below is packages/agent-bundle/src/… unless stated.

What exists today (facts that shape the design)

• The server half of the browser runtime is already one stack, shared by the Workbench and agent-bundle serve-app: dev/mcp-apps/{mcp-app-bridge,mcp-app-sandbox,mcp-app-preview-service,mcp-app-routes,mcp-app-binding-service,mcp-app-host-profiles,mcp-app-consent,mcp-app-preview-host}.ts, plus dev/mcp-app-metadata.ts, dev/mcp-app-action-validation.ts, dev/runtime-app-message-limits.ts, dev/http.ts. It is Effect-free end to end (plain classes: McpAppRoutes, McpAppPreviewService, McpAppBindingService, createMcpAppSandboxProxy) and its only npm import is isCallToolResult from @modelcontextprotocol/client (dev/mcp-app-metadata.ts:1). serve-app/serve-mcp-app.ts:45-63 documents that it is "the Workbench's MCP App preview stack without the Workbench".
• The browser half is duplicated. The Workbench's McpAppFrameRelay (packages/workbench/src/mcp/mcp-app-frame.tsx:156-396, a React-free class) and the hand-written JS string HOST_SCRIPT in serve-app/serve-app-page.ts:43-274 implement the same relay (proxy-ready → resource-ready handshake, source/origin/size gate, queue + POST /api/mcp/apps/<id>/messages, consent polling, document-policy revision remount, close). These are the "two bridges".
• serve-mcp-app.ts needs the framework for three things only: Effect scoping of resources (serveProgram, makeScopedEffectRuntime), the launch resolver services/mcp-run.ts#resolveMcpLaunchEnvironment (Effect + @rsbuild/core loadEnv + validate-artifact), and a throwaway build. The MCP client is the SDK (@modelcontextprotocol/client + /stdio).
• Generated executables already bundle the MCP SDK. examples/mcp-app/dist/*/mcp/mcp-status-*.mjs ≈ 1.1 MB, inlines @modelcontextprotocol/server, contains no Effect. App HTML is inlined into the server via the virtual agent-bundle/mcp-apps module (build/entries.ts:387-401 → mcp-server-runtime.ts:477-491 serves resources/read from memory); mcp-apps/<name>.html on disk is the same bytes.
• agent-bundle.manifest.json is provenance only (build/manifest.ts:83-91, closed schema via requireExactKeys): agentSkills, files[], producer, project, runtime, targets[], validation. No servers/tools/Apps/bins. The compiled App inventory exists at build time (build/mcp-apps.ts CompiledMcpApp: name, resourceUri, serverIds, output; config/normalize.ts#mcpEntryName gives mcp/mcp-<slug>-<hash>.mjs).
• Routed CLI bins: bin/<plugin>.mjs exists only when src/cli/** compiled ≥ 1 command (config/normalize.ts#generatedCliBinEntry). The virtual entry (build/entry-shell.ts#generatedCliBinEntrySource) imports agent-bundle/cli-entry; cli-entry.ts#runGeneratedCliEntry handles --help/--version/--json before the command tree and hands every command the process AbortSignal. Plugin root at runtime: AGENT_BUNDLE_PLUGIN_ROOT else .. of import.meta.url (entry-shell.ts:207-229).
• Dev server: plain node:http ForegroundServer with an ordered handler table; one McpAppRoutes + one sandbox proxy per session (dev/foreground-server.ts:463-466,737-802; dev/workbench-server.ts:952-983); no SPA path fallback (Workbench routes are #hash), so GET /web/... inserted before #serveAsset collides with nothing. Dev's McpAppRoutes has no openingCall (the Workbench posts input+result in the create body); serve-app's does (serve-app: App falls back to the JSON dump when the opening tool result exceeds 64 KiB (AB8010) — host page re-uploads a result the server already has #562).
• Config: no web key; Apps live under mcp.servers.<id>.apps → model.mcpApps (core/types.ts:113-122, normalize.ts:825-895). Unknown top-level keys are silently accepted today. Free codes: AB4341 (MCP config), AB4838 (route graph), AB8026 (dev/HTTP), AB6039 (artifact). AB4837 (feat(serve-app): add agent-bundle/serve-app-command and AB4837 for compiler imports in routed executables (#558) #582) blocks compiler-carrying entries in routed executables; serve-app-command, launch-env, cli-entry, mcp-entry, mcp-apps, routes, meta, terminal-capability are the allowed leaf entries.

Decisions

D1 — The shared browser runtime is the existing dev/mcp-apps/* stack plus ONE browser relay module and ONE host page, all living in a new framework directory web-host/ (framework source; not an authoring convention). Extract and rewire in the same change:

New module (web-host/)	Comes from	Consumers after the change
browser/frame-relay.ts (browser-safe TS)	packages/workbench/src/mcp/mcp-app-frame.tsx McpAppFrameRelay (moved, not copied)	Workbench mcp-app-frame.tsx (imports it by relative path, as it already imports contracts/mcp-apps.ts); the host page bundle
browser/main.ts (browser-safe TS)	serve-app/serve-app-page.ts HOST_SCRIPT (rewritten on top of the relay: create binding, consent panel, fallback panel, pagehide)	the host page bundle — HOST_SCRIPT is deleted
page.ts — renderWebHostPage(seed)	serve-app/serve-app-page.ts shell/CSS; the <script> body is the compiled browser/main.ts bundle imported ?raw at framework build time (Rsbuild web build → dist/web-host/page.js, like build:workbench precedes rslib build)	serve-app, dev /web, <plugin> web
session.ts — openStdioAppSession, sessionAuthorityFor	serve-mcp-app.ts:165-349 (StandaloneSession, openSession)	serve-app, <plugin> web
select-app.ts — parseAppSelector, selectApp (written against McpAppBridgeSession, not the SDK Client)	serve-mcp-app.ts:123-330	serve-app, dev /web, <plugin> web
host-server.ts — startWebHost({ session, selection, port, profile, autoApprove, authorize, openBrowser }) → { url, sandboxOrigin, close }	serve-mcp-app.ts#serveProgram HTTP server, token, CSP (frame-ancestors 'none', frame-src <sandbox>), loopback/origin checks, McpAppBindingService → McpAppPreviewService → McpAppRoutes, sandbox proxy, openingCall — de-Effected into plain async acquire/close	serve-app, <plugin> web (dev mounts the same routes/page on its own server)

serve-app/serve-mcp-app.ts shrinks to: resolve artifact + launch (Effect, framework) → openStdioAppSession → selectApp → startWebHost, inside its existing scope. serve-app/serve-app-page.ts is deleted; packages/workbench/src/mcp/mcp-app-frame.tsx keeps only the React McpAppFrame component and applyMcpAppFramePolicy. Not shared: the Workbench Runtime lane (runtime-app-bridge.ts + vendored AppRenderer, in-page AppBridge over /api/runtime/apps) — a different product (in-process runtime preview); it stays as is.

D2 — The artifact-resident host bundles the MCP client SDK; it does not hand-roll JSON-RPC and it does not bundle Effect. The issue proposed "Node built-ins only". The self-containment rule (AGENTS.md "Generated plugin output") is satisfied by bundling, exactly as mcp/<server>.mjs inlines the server SDK today; a third hand-written MCP client (beside dev/mcp-session/mcp-session.ts and the SDK) would be the parallel path #592 forbids. Effect is not needed: serve-mcp-app.ts used it only for scoped teardown. resolveMcpLaunchEnvironment is replaced for the production host by web-host/launch.ts: plugin root (AGENT_BUNDLE_PLUGIN_ROOT else parent of bin/), node <root>/<entry> from the manifest, AGENT_BUNDLE_PLUGIN_ROOT + the server's static env (tokens expanded against the root), operator .env left to the server shell's own launch-env handling — the same precedence mcp run applies, with no compiler modules.

D3 — No web/ directory in the artifact. The host ships inside bin/<plugin>.mjs as a framework-owned web command. The generated CLI entry (entry-shell.ts#generatedCliBinEntrySource) imports agent-bundle/web-host only when web.apps is configured, so plugins without the surface pay nothing; cli-entry.ts#runGeneratedCliEntry dispatches web before the authored command tree (where --version is handled), lists it in --help, and passes the process AbortSignal as teardown. config/normalize.ts#generatedCliBinEntry emits the bin when web.apps is set even if src/cli/** has no commands (the acceptance is node artifact/bin/<plugin>.mjs web --no-open). The page is a string inside the bin (like App HTML inside the server), so the layout, AB6014 ownership, pack-inventory.ts, and the exhaustive listing in tests/build-compose.test.ts are untouched; AB6005 walks the bin as it walks every .mjs in manifest.files.

D4 — agent-bundle.manifest.json gains a web section and is the only thing the host consults (#592 §11, and the 04:58 alignment comment). Written by build/manifest.ts (manifestFor) from CompiledMcpApp + mcpEntryName + normalized config; absent when web is not configured:

"web": {
  "open": "never",
  "apps": [{ "app": "status/status", "server": "status", "name": "status",
             "resourceUri": "ui://mcp-app-example/status.html",
             "entry": "mcp/mcp-status-073c1634.mjs", "env": {},
             "tool": "show-status", "allow": ["call-tool"] }]
}

web-host/manifest.ts owns the type + reader, used by the build writer, the web command (reads <root>/agent-bundle.manifest.json next to bin/; missing → coded error "run from the built artifact or the installed plugin"), dev /web (reads the active epoch's manifest), and doctor. The App list is never rediscovered from src/** or from tools/list; the opening tool is confirmed against the live server exactly as serve-app does (_meta.ui.resourceUri), because hand-written server factories (e.g. examples/mcp-app/src/mcp/status.ts:36-37) only advertise at runtime.

D5 — Config is exposure/policy only. core/types.ts gains

web?: { apps: ReadonlyArray<string | { app: string; tool?: string; input?: Record<string, unknown>; allow?: ServeAppAllowCapability[] }>; open?: 'browser' | 'never' }

('status/status' is shorthand for { app: 'status/status' }; open defaults to 'never', matching serve-app; --open/--no-open override.) No src/web/**, no landing page, no second route graph. Validation in config/validate.ts: AB4341 (error) — web.apps names an App that no mcp.servers.<id>.apps declares, or a tool that does not exist / does not advertise that App's resourceUri (checked statically for generated route servers via the route graph's _meta.ui.resourceUri; for hand-written factories the runtime check in select-app.ts is the authority, same message as serve-app). Also open enum and allow vocabulary (serve-app/command-contract.ts#serveAppAllowCapabilities).

D6 — Dev parity. dev/foreground-server.ts gains GET /web/<server>/<app> immediately before #serveAsset: resolve against the epoch manifest's web.apps, open/reuse the server's epoch stdio session through McpSessionService, selectApp on its McpAppBridgeSession, register the openingCall with the session's McpAppRoutes (new small registry so #562's large-result binding works in dev too), and serve renderWebHostPage with { tokenHeader: 'x-agent-bundle-session', token } and the dev sandbox origin in frame-src. Same page, same relay, same routes, same sandbox proxy; only authorize differs (Workbench session header vs per-launch token), which is a parameter of the seed.

D7 — agent-bundle/serve-app-command (#582, spawnServeApp) is deleted. #564 names it "the interim" for #558 option (c); with <plugin> web generated by the framework there is nothing left for a routed command to spawn, and keeping it would be the dual path the owner ruled out. serve-app/command-contract.ts stays: formatServeAppReadyLine/parseServeAppReadyLine become the shared ready-line contract printed by both agent-bundle serve-app and <plugin> web (human mode); --json prints { app, server, tool, url, port, resourceUri, sandboxOrigin } on one line and keeps running until the signal. docs/entry-conventions.md, the website CLI/authoring pages, tests/packed-serve-app-command.test.ts and fixtures/serve-app-command follow. If the owner wants spawnServeApp kept, say so on this issue; everything else stands.

D8 — Capability tables and doctor. Each adapters/capabilities/*.json gains a web row (state: supported, reason "browser, host-independent: <plugin> web runs from the installed root on any host") rendered by website/plugins/generated-reference.ts#renderHosts; adapters publish a web capability the same way they publish cli. install/doctor.ts prints one web: <n> App(s) — <plugin> web line from the bundle root's manifest section.

Mapping #564's numbered items

#	Item	Where it lands
1	Artifact-resident browser host, self-contained, AB6005 holds	web-host/{host-server,session,select-app,launch,page,manifest,command}.ts compiled into bin/<plugin>.mjs by build/cli-bins.ts + entry-shell.ts (same composeEntryLibConfig profile: autoExternal:false, no externals); no new executable, no web/ dir
2	Generated web command	cli-entry.ts dispatch + help; web-host/command.ts argv (`[/] [--port N] [--open
3	Config/convention	core/types.ts, config/normalize.ts, config/validate.ts (AB4341), build/manifest.ts web section; capability JSON web rows
4	Dev parity + serve-app as thin wrapper	dev/foreground-server.ts /web/<server>/<app>; serve-app/serve-mcp-app.ts rewired onto web-host/*
5	Diagnostics/docs	docs/diagnostics.md (AB4341, plus the command's runtime error codes); website/docs/{en,zh}/reference/{cli,configuration,targets-artifacts}.mdx, guide/authoring/mcp.mdx, guide/development/workbench.mdx, guide/start/project-structure.mdx, examples/mcp-app.mdx; docs/entry-conventions.md; hosts page regenerates from the JSON

How each #592 constraint is honored

1. No src/web/** routing universe. Nothing is discovered from a new directory; web.apps selects among Apps already declared under mcp.servers.<id>.apps and compiled by build/mcp-apps.ts; the host reads the manifest's web section and never keeps a registry of its own (D4, D5).
2. One browser runtime/bridge. Server half: unchanged dev/mcp-apps/*. Browser half: McpAppFrameRelay moves out of the Workbench into web-host/browser/frame-relay.ts and the serve-app HOST_SCRIPT is deleted in the same change; Workbench preview, serve-app, dev /web, and <plugin> web all run web-host/browser/main.ts + renderWebHostPage over the same McpAppRoutes (D1, D6). The Workbench Runtime lane is a different product and is not touched.
3. Artifact-resident, self-contained, CLI-reachable, installed-artifact-only, same sandbox/consent, dev parity. The host is compiled into bin/<plugin>.mjs by the existing self-contained profile and walked by AB6005; it requires agent-bundle.manifest.json beside bin/; sandbox (second loopback origin, server-issued CSP), consent (McpAppBridge challenges, --allow for the four action capabilities only, hardware/clipboard always interactive), token + origin + loopback checks, and the serve-app: App falls back to the JSON dump when the opening tool result exceeds 64 KiB (AB8010) — host page re-uploads a result the server already has #562 openingCall binding are the same modules serve-app uses today; dev serves /web from the same modules (D2, D3, D6).
4. Response boundary. The App is opened with the live CallToolResult from tools/call (lowered by documentToCallToolResult / attachMcpStructuredContent in the generated server) bound through openingCall; the page's fallback panel shows that same result. No Agent Document decoding, no second rendering path.

Tests

• Unit: web config normalize/validate (AB4341), manifest web section round-trip, generatedCliBinEntry with web and no src/cli, web-host/select-app and command argv against a fake bridge session, renderWebHostPage seed escaping, dev /web route (404 for unexposed Apps, page CSP).
• Integration/packed (Playwright 1440×900, @rstest/playwright as workbench-e2e.ts): build examples/mcp-app with the installed tarball, spawn node artifact/bin/mcp-app-example.mjs web --no-open as a real process (packed-deleted-source style), parse the ready line, open the URL, wait until the status is Serving … (never while binding), assert the App rendered (not the fallback) with the opening tool's structured result, call a tool through the App, Ctrl-C tears down the server. pnpm test:packed keeps passing (packed-serve-app-command is replaced by the web journey).
• examples/mcp-app gains web: { apps: [{ app: 'status/status', tool: 'show-status', allow: ['call-tool'] }] } (and thereby a bin).

PR split (branch feat/564-web-surface, worktree agent-bundle-wt/i564-web, after #578 merges)

1. PR A — one browser host. web-host/{browser,page,session,select-app,host-server}.ts extracted; Workbench relay moved; serve-app rewired; serve-app-page.ts deleted; framework build gains the page bundle step. No user-facing change beyond serve-app internals → patch changeset.
2. PR B — the web surface. Config, manifest section, generated web command + bin emission, web-host/{launch,manifest,command}.ts, dev /web, AB4341, capability rows, doctor line, serve-app-command deletion, example, docs en/zh, packed e2e → minor changeset for agent-bundle.

If B exceeds ~1,500 changed lines, dev parity + doctor/capabilities split into a PR C with the reason stated in the body.

Out of scope / deferred

• MCP Apps: generated typed client + shared bridge runtime from route contracts #594 (generated typed App client) — the standalone host and embedded Apps already share the same ui/* bridge server-side; the App-side client is MCP Apps: generated typed client + shared bridge runtime from route contracts #594's slice.
• serve-app: App falls back to the JSON dump when the opening tool result exceeds 64 KiB (AB8010) — host page re-uploads a result the server already has #562 (64 KiB) is honored by openingCall; outputSchema tuples (prefixItems + items:false) fail Cursor's structured-content validation ("boolean schema is false") — emit an interoperable projection #563 (tuple schemas) is independent.

[ScriptedAlchemy]

#594 implementation design is posted: #594 (comment)

Boundary for the #564 lane: #594 owns the App-side createAppClient/request runtime (ui/initialize, ids, timeouts/abort, typed tools/call, decoding, source+origin checks, dispose/rebind). #564 can keep its design-note ownership of the host-side extracted McpAppFrameRelay, host page, HTTP routes, and artifact process. The shared seam is the standard MCP Apps frame protocol; please consume agent-bundle/app wire types rather than adding another App-side request engine. I’ll reread this issue before freezing the rebind surface.

[ScriptedAlchemy]

#594 security correction: the App-side bridge must account for your existing opaque sandbox="allow-scripts" + no-referrer srcdoc. It will use one wildcard ui/initialize bootstrap, validate exact parent source + request id + initialize shape, pin the response origin, then use only that exact origin. This needs no #564 host-page change and preserves your host-side relay boundary. Full note: #594 (comment)