feat: add typed MCP App client

[ScriptedAlchemy]

Summary

• add browser-safe agent-bundle/app with createAppClient(): secure opaque-sandbox initialization, exact source/origin pinning, request ids, timeout/abort cancellation, JSON-RPC decoding, structured results, typed opening notifications, rebind, and disposal
• generate AppRegister tool contracts from canonical route typegen; carry each canonical route id in private _meta so the shared host bridge rejects calls for a server/tool other than the bound one
• make createMcpAppBridge honor App-owned cancellation, reject duplicate in-flight ids, and recover repeated initialization; thread abort signals through the MCP session
• reserve and inline the framework App runtime in MCP App compilation, aligned with feat(build): emit one composite plugin root; targets select host projections; remove the plugin target (#555 W1) #578's composite plugin root; migrate the public MCP App example off @modelcontextprotocol/ext-apps
• document the client and security model in English and Chinese; update AB4837; add one patch changeset

Design: #594 (comment)
Host boundary pointer: #564 (comment)

API

import { createAppClient } from 'agent-bundle/app';

const client = createAppClient({
  appInfo: { name: 'dashboard', version: '1.0.0' },
  timeoutMs: 15_000,
});
await client.connect();
const status = await client.call('tool:hauler/hauler_status', { limit: 40 });
client.onToolInput('tool:hauler/hauler_status', (input) => {});
client.onToolResult('tool:hauler/hauler_status', (result) => {});
client.onToolError('tool:hauler/hauler_status', (error) => {});
client.onToolCancelled((event) => {});
await client.rebind();
client.dispose();

Generated .agent-bundle/routes.d.ts augments AppRegister.routes with tool-only { input, result } contracts inferred from canonical schema exports. call() returns object structuredContent directly and rejects malformed, missing, or isError results. request() is the lower-level JSON-RPC escape hatch.

#564 can mount the existing shared createMcpAppBridge host core and speak this standard MCP Apps wire. This PR does not own <plugin> web, the standalone host page/process, frame relay extraction, sandbox proxy, or host HTTP routes.

Tests

• App client unit coverage: envelopes, opaque-origin bootstrap, source/origin checks, structured decode, timeout, abort/cancellation, consent/capability mapping, typed notifications, invalid and in-flight rebind, teardown/dispose
• host bridge coverage: bound route-id validation, cancellation before/during consent and execution, duplicate in-flight ids, initialize retry
• typegen coverage: one App augmentation, tool-only filtering, input/result inference, tool-free absence, declaration writes
• compiler coverage: reserved runtime beats path shadowing, fully inline output, no external imports, and no Node/Zod/Effect/compiler/server-route bytes
• public example browser-App, serve-app, Workbench real App, and host-embedding journeys exercise the same contract
• feat(build): emit one composite plugin root; targets select host projections; remove the plugin target (#555 W1) #578 composite-root integration uses root mcp-apps/ and shared MCP entry paths

Final local gates after merging latest origin/main (including #578):

• pnpm build
• pnpm typecheck ∥ pnpm lint ∥ pnpm test:unit ∥ pnpm test:route-unit
• focused typed-client integration suite
• pnpm docs:site:build
• pnpm lint:release
• browser-App + Workbench real E2E suites

All pass.

cargo-hauler dry-run

Read-only origin: /fast/projects/agent-plugins/cargo-conductor; disposable proof: /tmp/issue-594-scratch.

• dashboard: 1,984 → 1,911 lines (−73)
• removed local JsonRpcMessage, ToolCallResult, PendingRequest, request-id allocator, pending map, 15 s timers, wildcard postMessage, response router, manual initialize/initialized frames, and pending cleanup
• scratch portable build and pnpm typecheck pass against the packed tarball and generated AppRegister
• dist/app.js graph: three local files, zero external specifiers, no Node/Zod/Effect/compiler/server-route bytes
• generated dashboard HTML: one inline script, no external script/import specifiers, no Node/Zod/server-route imports, no deleted plumbing symbols

This unblocks cargo-hauler #107 §3.

Self-review

Reviewer: Claude Fable 5.1 Thinking Max (change-risk-reviewer). No Grok model was used for any recorded self-review pass.

Actionable findings and disposition:

1. call() classified conventional isError results without structuredContent as malformed — fixed by checking the error envelope first and preserving full data; regression test added.
2. invalid rebind({ targetOrigin }) mutated a live connection before validation — fixed by pre-validating; regression test proves pending work and connection remain live.
3. generated contracts exposed all project servers while wire dispatch originally discarded the route server — fixed at e5f3fe49b: the typed client carries canonical route id in private _meta, and the bridge validates it against the immutable bound server/tool before consent or dispatch; standard clients without the extension remain compatible.
4. Chinese security docs omitted cancellation boundaries and scalar-result wording drifted — translated and parity restored.
5. changeset omitted generated contracts and host-bridge behavior — expanded.

After the fixes and the #578 merge, the reviewer reran on the complete final diff through e5f3fe49b and reported no remaining actionable defect, breaking change, security issue, missed test, or doc/changeset gap.

Closes #594

[changeset-bot]

🦋 Changeset detected

Latest commit: e5f3fe4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
agent-bundle	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-05T06:27:42.487004Z	a6ef29c	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[pkg-pr-new]

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle@601

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@601

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/rsc-markdown-stream@601

npm i https://pkg.pr.new/ScriptedAlchemy/agent-bundle/@agent-bundle/runtime@601

commit: e5f3fe4

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a6ef29c5ed

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".