refactor(dev)!: delete the callerless runtime App preview path

.changeset/remove-runtime-app-routes.md

@@ -0,0 +1,5 @@
+---
+"agent-bundle": minor
+---
+
+Remove the Workbench runtime App preview path. The dev server no longer serves `/api/runtime/apps/**` or `/api/runtime/mcp/sessions/**`, `DevServerSession` (from `agent-bundle` and `agent-bundle/api`) drops `openRuntimeClientSurface`, and `DevRuntimeEventInput` no longer accepts `runtime.app.updated`, `runtime.hmr.client-connected`, or `runtime.hmr.client-disconnected`. The `AB8022` 410 and `AB8023` 413 runtime App responses are gone; both codes keep their other meanings. Runtime runs, status, surfaces, and MCP App previews for artifact sessions are unchanged. (#852)

docs/architecture/rsc-runtime-workbench.md

@@ -29,8 +29,6 @@ packages/
     src/core/types.ts
     src/dev/foreground-server.ts
     src/dev/mcp-app-action-validation.ts
-    src/dev/mcp-app-runtime-binding-service.ts
-    src/dev/mcp-app-runtime-preview-service.ts
     src/dev/mcp-apps/mcp-app-binding-service.ts
     src/dev/mcp-apps/mcp-app-preview-service.ts
     src/dev/mcp-apps/mcp-app-routes.ts
@@ -39,11 +37,9 @@ packages/
     src/dev/playground/playground-store.ts
     src/dev/project-service.ts
     src/dev/runtime-app-message-limits.ts
-    src/dev/runtime-client-surface-proxy.ts
     src/dev/runtime-controller.ts
     src/dev/runtime-generation-store.ts
     src/dev/runtime-mcp-registry.ts
-    src/dev/runtime-mcp-routes.ts
     src/dev/runtime-provider-loader.ts
     src/dev/runtime-provider.ts
     src/dev/runtime-routes.ts
@@ -69,8 +65,6 @@ packages/
     tests/mcp-app-metadata.test.ts
     tests/mcp-app-preview-service.test.ts
     tests/mcp-app-routes.test.ts
-    tests/mcp-app-runtime-binding-service.test.ts
-    tests/mcp-app-runtime-preview-service.test.ts
     tests/mcp-app-sandbox.test.ts
     tests/mcp-apps-compile.test.ts
     tests/mcp-session-routes.test.ts
@@ -85,15 +79,12 @@ packages/
     tests/public-api.test.ts
     tests/rsc-runtime-optional-packaging.test.ts
     tests/rsc-runtime-topology-script.test.ts
-    tests/runtime-client-surface-proxy.test.ts
     tests/runtime-generation-store.test.ts
     tests/runtime-mcp-registry.test.ts
-    tests/runtime-mcp-routes.test.ts
     tests/runtime-provider.test.ts
     tests/runtime-routes.test.ts
   workbench/
     rsbuild.config.ts
-    scripts/capture-runtime-playground.mjs
     src/main.tsx
     src/mcp/mcp-app-client.ts
     src/mcp/mcp-app-preview.tsx
@@ -104,7 +95,6 @@ packages/
     src/runtime-client.ts
     src/runtime-model.ts
     src/styles.css
-    tests/helpers/runtime-playground-fixture.ts
     tests/mcp-app-client.test.ts
     tests/mcp-app-frame.test.ts
     tests/mcp-app-preview-browser.test.ts

docs/diagnostics.md

@@ -39,7 +39,7 @@ even when no error diagnostic was reported.
 | `AB7200`–`AB7202`, `AB7210`–`AB7211` | Development rebuilds and live host surfaces: rebuild admission and phase failures, development host install sync, and the dev-epoch contract gate (see below). |
 | `AB7xxx` | Project preparation and development rebuilds (`AB7100`–`AB7102`: a development rebuild's compilation, publication, and cleanup; `AB7101` is also the one-shot `build` / `build()` refusal when source changes during compilation; `AB7103`: the development package build; see below). |
 | `AB7300`–`AB7333` | Read-only install Doctor: host probes, installed inventory, bundle comparison and registration proof, runtime endpoint health and identity, durable-state inventory, static bytes-at-rest validation, foreign-install detection (`AB7321`; see below), Cursor plugin hook registration / marketplace staging (`AB7322`–`AB7324`; see below), host load refusal (`AB7325`; see below), the Cursor Agent Plugins launch proof (`AB7326`; see below), a disabled Claude install (`AB7327`; see below), lifecycle receipts and activation states (`AB7328`–`AB7330`; see below), the operator `.env` layer of an installed pack (`AB7331`; see below), the retired `AB7332` (see below), and dangling receipt-owned marketplaces (`AB7333`; see below). `AB7311` and `AB7325` are also emitted by `build` and `validate --artifact` from the Claude load check (see "Claude Code host validation"). |
-| `AB8200`–`AB8209` | Workbench development runtime routes (`/api/runtime/**`): `AB8200` development runtime provider configuration, load, or lifecycle failure, `AB8201` runtime/session/run not available, `AB8202` invalid route path, `AB8203` invalid request shape, `AB8204` stale runtime generation or MCP session revision (409), `AB8205` runtime request could not be completed, `AB8206` Workbench runtime client failure, `AB8207` Agent Document decoding needs the optional `@agent-bundle/runtime` peer (503), `AB8208` stored Flight could not be decoded as an Agent Document (409), `AB8209` decoded Agent Document over the 16 MiB budget (413) or an invalid document response. |
+| `AB8200`–`AB8209` | Workbench development runtime routes (`/api/runtime/**`): `AB8200` development runtime provider configuration, load, or lifecycle failure, `AB8201` runtime/session/run not available, `AB8202` invalid route path, `AB8203` invalid request shape, `AB8204` stale runtime generation (409), `AB8205` runtime request could not be completed, `AB8206` Workbench runtime client failure, `AB8207` Agent Document decoding needs the optional `@agent-bundle/runtime` peer (503), `AB8208` stored Flight could not be decoded as an Agent Document (409), `AB8209` decoded Agent Document over the 16 MiB budget (413) or an invalid document response. |
 | `AB8210`–`AB8214` | Workbench semantic lifecycle replay routes (`/api/lifecycles`, `/api/lifecycles/replays`): `AB8210` invalid path, `AB8211` malformed replay request or native envelope (400, carries the shared validator message), `AB8212` replay unavailable or could not be completed, `AB8213` stale manifest binding (409; the page repairs it with refresh → explicit re-run), `AB8214` replay over the 16 MiB budget (413). |
 | `AB8215`–`AB8218` | Workbench read-only host discovery route (`/api/discovery`): `AB8215` invalid path, `AB8216` query string or non-`GET` method (400/405), `AB8217` report over the 16 MiB response limit (413), `AB8218` discovery not available (503). |
 | `AB8219`–`AB8223` | Workbench live MCP probe route (user-initiated, read-only initialize + tools/list): `AB8219` invalid path, `AB8220` invalid request/method, `AB8221` probe target not found, `AB8222` response over the 16 MiB budget, `AB8223` probe unavailable. |
@@ -1863,7 +1863,7 @@ foreground server accepts.
 | `AB8007` | 404 / 405 / 500 | `Route was not found.`, no asset at the path, or `/mcp` when the Agent API is not composed; `Route does not accept this method.`, a route received a method it does not serve; `Request could not be completed.`, a handler threw something other than a request diagnostic. | Check the method and path; for a 500, read the dev-server log for the underlying error. |
 | `AB8008` | 400 | `Request host is not this foreground server.`, the `Host` header does not name this server's loopback URL. | Address the server by the URL `agent-bundle dev` printed. |
 | `AB8009` | 415 | `Request body must use application/json.`, a JSON route received a body without an `application/json` content type. | Send `content-type: application/json`. |
-| `AB8010` | 413 | `Request body exceeds 64 KiB.`, the default `readBody` bound; the runtime MCP routes apply the same bound. Playground routes raise a 1 MiB bound under `AB8085`. | Send a smaller body. |
+| `AB8010` | 413 | `Request body exceeds 64 KiB.`, the default `readBody` bound. Playground routes raise a 1 MiB bound under `AB8085`. | Send a smaller body. |
 | `AB8011` | 404 | `Skill workbench service is not available.`, a `/api/skills/**` route was requested but the server was composed without the Skill document service. | Nothing to fix in the project; the Skill pages need a server composed with the Skill service. |
 | `AB8012` | 400 | `Skill route path is not valid.`, a `/api/skills/**` path does not match the source or generated Skill tree, document, or resource shapes, or a segment does not decode. | Use the Skill links the Workbench renders. |
 
@@ -1879,14 +1879,14 @@ foreground server accepts.
 | `AB8018` | 409 | `MCP session epoch is no longer available; the project changed underneath the session.`, the epoch the session was opened against is no longer available after the project changed. | Open a new session against the current epoch. |
 | `AB8019` | 400 / 502 | `MCP session could not be opened.` (400, on create) or `MCP session operation could not be completed.` (502), the service threw something the route does not map to a more specific code. | Read the dev-server log for the underlying error, then retry. |
 
-### MCP App previews (`/api/mcp/apps/**`, `/api/mcp/sessions/<id>/apps`, `/api/runtime/apps/**`)
+### MCP App previews (`/api/mcp/apps/**`, `/api/mcp/sessions/<id>/apps`)
 
 | Code | Status | Trigger | Recovery |
 | --- | --- | --- | --- |
 | `AB8020` | 400 / 404 | `MCP App route path is not valid.`, an App route whose binding id or operation segment is missing or does not decode, or an unknown operation under `/api/mcp/apps/<binding>/`. `agent-bundle serve-app` answers unknown paths with `Not found.` (404) under the same code. | Use the App routes the Workbench MCP page issues. |
 | `AB8021` | 400 | `MCP App request has an invalid shape.`, the request body does not match the operation's expected fields. | Send the fields the operation defines. |
-| `AB8022` | 404 / 410 / 503 | `MCP App routes are not available.`, 404 without the preview service, 503 after shutdown; `MCP App preview is not available.` (404), the binding id is unknown; `Runtime MCP App preview was revoked.` (410), the runtime binding has been revoked. `agent-bundle serve-app` reports `MCP App host is not ready.` (503) before its host finishes starting. | Re-open the App preview; after 410 the page must create a new binding. |
-| `AB8023` | 404 / 409 / 413 / 502 | `MCP App operation could not be completed.` (502), an unmapped service failure; `Runtime MCP App operation exceeded its 30 second deadline.` (502); `Runtime MCP App operation response could not be encoded.` (502) or `… exceeds its transport bound.` (413), the result of a runtime App operation could not cross the bounded host-to-App channel. On `/web/<server>/<app>`: `MCP App could not be opened.` (502), the launch, opening call, or page render failed; `Target "…" is not a declared projection that launches MCP server …` (404), an invalid `?target=`, never a fallback; `No declared projection of this artifact launches MCP server …` (404); `The declared projections launch MCP server … differently; pick one explicitly with ?target=<…>.` (409). | Read the dev-server log; shrink or split the App operation result if the bound was hit; on `/web`, pass a `?target=` the message names. |
+| `AB8022` | 404 / 503 | `MCP App routes are not available.`, 404 without the preview service, 503 after shutdown; `MCP App preview is not available.` (404), the binding id is unknown. `agent-bundle serve-app` reports `MCP App host is not ready.` (503) before its host finishes starting. | Re-open the App preview. |
+| `AB8023` | 404 / 409 / 502 | `MCP App operation could not be completed.` (502), an unmapped service failure. On `/web/<server>/<app>`: `MCP App could not be opened.` (502), the launch, opening call, or page render failed; `Target "…" is not a declared projection that launches MCP server …` (404), an invalid `?target=`, never a fallback; `No declared projection of this artifact launches MCP server …` (404); `The declared projections launch MCP server … differently; pick one explicitly with ?target=<…>.` (409). | Read the dev-server log; on `/web`, pass a `?target=` the message names. |
 
 ### Hook playground (`/api/hooks/**`)
 

docs/effect-conventions.md

@@ -128,7 +128,7 @@ moves into one of these positions moves back:
   `DevRuntimeUnavailableError` / `DevRuntimeGenerationConflictError`,
   `PlaygroundService*Error` / `PlaygroundSessionCloseError`,
   `HookPlaygroundCloseError`, `McpProbeTargetNotFoundError`,
-  `McpAppRuntimePreviewError`, `SkillDocumentError`,
+  `SkillDocumentError`,
   `InspectorLauncherError`, `EvalRunEvent*Error`, and
   `EvalServiceBackgroundFailureOverflowError`). The `@agent-bundle/runtime`
   `plugin` entry also has no `effect` import today.
@@ -802,19 +802,18 @@ resolved the current repo practice stands, and new code follows it.
   helpers like `isRecord` and to use the `Predicate` module. The repo's
   shared guards are `core/strict-json.ts` `isRecord` / `isJsonRecord` /
   `isPlainRecord` and `workbench/src/client-helpers.ts` `isRecord`, but the
-  divergence is wider than two helpers: fifteen modules define their own
+  divergence is wider than two helpers: fourteen modules define their own
   private `isRecord` with the same `typeof === 'object' && !== null &&
   !Array.isArray` body (`mcp-server-runtime.ts`, `build/pack-inventory.ts`,
   `install/{install,doctor,cursor-agent-plugins-launch}.ts`,
   `host-contracts/{claude,cursor,portable}-plugin-validation.ts`,
   `adapters/portable-mcp-rules.ts`, `dev/host-install-manager.ts`,
-  `dev/mcp-app-runtime-binding-service.ts`,
   `dev/mcp-apps/{mcp-app-bridge,mcp-app-host-profiles,mcp-app-routes}.ts`,
   `workbench/src/mcp/mcp-app-preview.tsx`), seven more alias a shared guard
-  under the local name, and five emit the same one-liner as a string into
+  under the local name, and four emit the same one-liner as a string into
   generated hook / proxy / sandbox source that intentionally imports nothing
   (`adapters/hook-contract.ts`, `install/surface.ts`,
-  `dev/runtime-client-surface-proxy.ts`, `dev/mcp-apps/mcp-app-sandbox.ts`).
+  `dev/mcp-apps/mcp-app-sandbox.ts`).
   Roughly 400 call sites in total, against about a dozen
   `Predicate.isObject` uses (the install lane). rc.117 `Predicate` has no
   `isRecord`; `Predicate.isObject` is the closest match (`{}`-typed, excludes

examples/rsc-agent-runtime/README.md

@@ -56,21 +56,8 @@ pnpm --filter @agent-bundle/rsc-agent-runtime-demo capture:widget -- --output /t
 pnpm docs:runtime-topology
 ```
 
-For contributor Workbench/HMR evidence, use the repository fixture rather than
-the published package:
-
-```bash
-node packages/workbench/scripts/capture-runtime-playground.mjs \
-  --desktop "$PWD/docs/assets/rsc-runtime-workbench/desktop.png" \
-  --hmr-before "$PWD/docs/assets/rsc-runtime-workbench/hmr-before.png" \
-  --hmr-after "$PWD/docs/assets/rsc-runtime-workbench/hmr-after.png" \
-  --compile-error "$PWD/docs/assets/rsc-runtime-workbench/compile-error.png" \
-  --recovered "$PWD/docs/assets/rsc-runtime-workbench/recovered.png" \
-  --evidence /tmp/rsc-runtime-delivery/evidence.json
-```
-
-The `--compile-error` capture shows the Workbench diagnostic the provider
-publishes when a source change fails to compile: code `AB8206`, phase
+When a source change fails to compile, the provider publishes a Workbench
+diagnostic with code `AB8206`, phase
 `source/build`, and a message that carries the Rspack errors themselves, one
 `file:line:col: message` line per error, with the path relative to the example
 root, ANSI colour and the SWC code frame stripped. Breaking `src/rsc/worker.tsx`

packages/agent-bundle/src/contracts/mcp-apps.ts

@@ -1,7 +1,7 @@
 import type { McpAppJsonValue } from '../dev/mcp-app-metadata.ts';
 import type { McpAppBridgeLifecycle } from '../dev/mcp-apps/mcp-app-bridge.ts';
 
-/** Browser-safe MCP App and Runtime App wire contracts used by Workbench. */
+/** Browser-safe MCP App wire contracts used by Workbench. */
 export { MCP_APP_PROFILE_DESCRIPTORS } from '../dev/mcp-app-profile-descriptors.ts';
 export type { McpAppProfileId } from '../dev/mcp-app-profile-descriptors.ts';
 export {
@@ -17,27 +17,13 @@ export {
 export type { McpAppBridgeMessage } from '../dev/mcp-apps/mcp-app-bridge.ts';
 export type { McpAppBridgeLifecycle } from '../dev/mcp-apps/mcp-app-bridge.ts';
 export type { McpAppJsonValue } from '../dev/mcp-app-metadata.ts';
-export type {
-  McpAppBoundOperationResult,
-  McpAppPublicRuntimeVector,
-  McpAppRuntimeBindingSnapshot,
-} from '../dev/mcp-app-runtime-binding-service.ts';
-export type {
-  CreateMcpAppPreviewRequest,
-  McpAppBindingOperation,
-  McpAppConsentCreatedResponse,
-  McpAppConsentDecisionResponse,
-  McpAppPreviewAppsSnapshot,
-  McpAppPreviewSnapshot,
-  McpAppRuntimeInvalidationDetails,
-} from '../dev/mcp-app-runtime-preview-service.ts';
 export { isMcpAppConsentCapability } from '../dev/mcp-apps/mcp-app-consent.ts';
 export type { McpAppConsentCapability } from '../dev/mcp-apps/mcp-app-consent.ts';
 export type {
   McpAppConsentChallenge,
   McpAppConsentRequest,
   McpAppDocumentPolicySnapshot,
-} from '../dev/mcp-apps/mcp-app-sandbox.ts';
+} from '../dev/mcp-apps/mcp-app-sandbox-types.ts';
 
 export interface McpAppRelayFrame {
   readonly allow: string;

packages/agent-bundle/src/dev/foreground-server.ts

@@ -22,7 +22,6 @@ import { McpProbeRoutes, type McpProbeRouteService } from './playground/mcp-prob
 import { McpAppRoutes, type McpAppRoutePreviewService } from './mcp-apps/mcp-app-routes.ts';
 import { McpSessionRoutes } from './mcp-session/mcp-session-routes.ts';
 import type { McpSessionService } from './mcp-session/mcp-session-service.ts';
-import { RuntimeMcpRoutes } from './runtime-mcp-routes.ts';
 import { RuntimeRoutes, type AgentDocumentRuntimeModule } from './runtime-routes.ts';
 import type { DevRuntimeSession } from './runtime-provider.ts';
 import { PlaygroundRoutes, type PlaygroundRouteService } from './playground/playground-routes.ts';
@@ -426,7 +425,6 @@ export class ForegroundServer {
   readonly #mcpAppPreviews: McpAppRoutePreviewService | undefined;
   readonly #mcpAppRoutes: McpAppRoutes;
   readonly #mcpProbeRoutes: McpProbeRoutes;
-  readonly #runtimeMcpRoutes: RuntimeMcpRoutes;
   readonly #mcpSessionRoutes: McpSessionRoutes;
   readonly #runtimeRoutes: RuntimeRoutes;
   readonly #now: () => Date;
@@ -522,18 +520,6 @@ export class ForegroundServer {
       authorize: (request) => this.#assertMutationSession(request),
       ...(options.mcpSessions === undefined ? {} : { service: options.mcpSessions }),
     });
-    this.#runtimeMcpRoutes = new RuntimeMcpRoutes({
-      authorize: (request) => this.#assertMutationSession(request),
-      ...(options.mcpAppPreviews === undefined
-        ? {}
-        : {
-            awaitRegistryMutation: async () => { await options.mcpAppPreviews?.runtime?.flushRegistry?.(); },
-            awaitSessionClose: async ({ expectedSessionRevision, sessionId }) => {
-              await options.mcpAppPreviews?.runtime?.closeSession?.(sessionId, expectedSessionRevision);
-            },
-          }),
-      ...(options.runtime === undefined ? {} : { runtime: options.runtime }),
-    });
     this.#runtimeRoutes = new RuntimeRoutes({
       authorize: (request) => this.#assertMutationSession(request),
       ...(options.testing?.loadAgentDocumentRuntime === undefined
@@ -715,7 +701,6 @@ export class ForegroundServer {
     this.#mcpAppRoutes.close();
     this.#hostMcpRoutes?.close();
     this.#mcpSessionRoutes.close();
-    this.#runtimeMcpRoutes.close();
     this.#runtimeRoutes.close();
     // Publish the hook playground drain before awaiting App tombstones. Its
     // abort callbacks may synchronously re-enter foreground shutdown, and
@@ -828,7 +813,6 @@ export class ForegroundServer {
     }
     if (await this.#mcpAppRoutes.handle(request, response)) return;
     if (await this.#mcpSessionRoutes.handle(request, response)) return;
-    if (await this.#runtimeMcpRoutes.handle(request, response)) return;
     if (await this.#runtimeRoutes.handle(request, response)) return;
     if (await this.#hookPlaygroundRoutes.handle(request, response)) return;
     if (await this.#mcpProbeRoutes.handle(request, response)) return;