feat(manifest): authoritative agent-bundle.manifest.json v2 — consumers read the composite root through the manifest (#592 step 3, #555 W2/S3)

.changeset/592-authoritative-manifest.md

@@ -0,0 +1,5 @@
+---
+"agent-bundle": minor
+---
+
+Make `agent-bundle.manifest.json` (`manifestVersion: 2`) the authoritative index of the composite plugin root: it gains `application`, `projections[]` (one row per selected host with its `builtInHost` adapter identity, `documents` pointers, and `marketplace` name), the compiled `routes` graph (CLI commands carry their `<tool>.cli.ts` `projection` and option `aliases`, and `routes.events[].execution` records preflight, provider, fallback, and runtime metadata), `executables` (`bins[]`, `hooks[]`, `mcpServers[]`, `scripts[]`), and `distribution` (`channels`, `install` pointers, and `payloads[]` — each `definePrebuilt` directory with its hosts and `runtimeDependencies`), while operational compiler facts move to a `compiler` record versioned independently by `recordVersion`. `targets[]` is renamed to `projections[]` and the `agent-bundle.hooks.json` sidecar is removed. The contract ships as `agent-bundle/schemas/agent-bundle.manifest.schema.json`, exported as `artifactManifestSchema` and `validateArtifactManifestSchema` beside `readArtifactManifest`, `parseArtifactManifest`, `artifactManifestName`, `artifactManifestVersion`, and `artifactCompilerRecordVersion`; every path-valued field must be root-relative. `install`, `uninstall`, and `doctor --from` take identity, the host plugin document, the copy set, and the content hash from the manifest instead of probing host files, so `AB7001` now covers a missing or non-canonical manifest, a host without a built-in projection, a missing pointer, or a missing or digest-mismatched `files[]` row; `serve-app` and `mcp list|invoke|run` resolve servers from `executables.mcpServers[]` (`--target` optional when one projection runs the server); `hooks list`, `hooks simulate`, and `AB6018` read `executables.hooks[]`; `AB6010` verifies each projection's adapter identity; `inspect --json` adds `output.manifest`, the new `inspect --artifact <root>` prints the application view of a bare composite root, and each compiled or prebuilt `executables.mcpServers[]` row carries one `launch` record (`entry`, `worker?`, `args[]` as `artifact` paths or `literal` values, `env`) that `<plugin> web` and the host MCP documents start from — `web.apps[]` no longer copies `entry`, `args`, or `env` and instead names its server (#604)

docs/canvases/agent-bundle-walkthrough.canvas.tsx

@@ -569,13 +569,13 @@ export default function AgentBundleWalkthrough() {
             <Text size="small" tone="secondary">
               agent-bundle.manifest.json records, per emitted file, its sha256 and the exact
               source inputs that produced it, plus the project revision (the artifact epoch),
-              each target's adapter revision, and the sha256 of every
-              pinned host schema it was validated against. agent-bundle.hooks.json is the
-              canonical hook index across targets.
+              each projection's adapter revision, and the sha256 of every
+              pinned host schema it was validated against. Its executables.hooks[] rows are the
+              canonical hook inventory across hosts (no separate hook index file).
             </Text>
             <Text size="small" tone="tertiary">
               Source: dist/agent-bundle.manifest.json fields files[].sha256, files[].sourceInputs,
-              project.revision, targets[].schemas[].
+              project.revision, projections[].schemas[], executables.hooks[].
             </Text>
           </Stack>
         </Grid>

docs/entry-conventions.md

@@ -1266,7 +1266,8 @@ export default defineConfig({
   remain hash-locked to the manifest. Declaration provenance is recorded as
   `kind: 'prebuilt'`. Hooks with prebuilt handlers are packaged like native
   hook documents: they do not compile wrappers and do not appear in the
-  simulatable hook index. MCP Apps declared on a prebuilt server stay a
+  manifest's `executables.hooks[]` rows, so `hooks list` and `hooks simulate`
+  do not see them. MCP Apps declared on a prebuilt server stay a
   development surface (the Workbench compiles them live); the build assumes
   the payload already serves the resource.
 - **Declare what the payload loads.** Because payload trees are opaque,

packages/agent-bundle/README.md

@@ -228,9 +228,12 @@ the shipped document in the install receipt (`cursorExpansion`), and
 itself stays spec-conformant for other Agent Plugins clients.
 
 Cursor installation is user-scoped. Claude also accepts `--scope project` and
-`--scope local`; Codex is user-scoped. `--from` names the plugin root itself —
-the directory that holds the selected host's manifest — and a source-free copy
-of that root is accepted.
+`--scope local`; Codex is user-scoped. `--from` names the composite root itself —
+the directory that holds `agent-bundle.manifest.json` — and a source-free copy
+of that root is accepted. Identity (name, version, marketplace) and the host
+plugin document come from that manifest's `application` and `projections[]`
+rows, never from probing host files; a root whose manifest is missing, not
+canonical, or has no projection for the host is refused with `AB7001`.
 
 ### Reinstall after a same-version rebuild
 

packages/agent-bundle/fixtures/web-surface/agent-bundle.config.ts

@@ -11,9 +11,15 @@ export default {
             template: './views/status.html',
           },
         },
+        // One artifact-path argument (the packaged payload file) beside a
+        // literal, and env carrying a plugin-data token: the launch record
+        // must carry all three for <plugin> web to start the server with them.
+        args: ['--config', 'agent-bundle:path:plugin-root/config/status.json'],
+        env: { STATUS_CACHE: 'agent-bundle:path:plugin-data/cache', STATUS_MODE: 'packed' },
       },
     },
   },
+  payload: { config: './payload/config' },
   plugin: {
     description: 'A plugin whose MCP App is exposed through web.apps and opened with <plugin> web.',
     name: 'web-surface-fixture',

packages/agent-bundle/fixtures/web-surface/payload/config/status.json

@@ -0,0 +1 @@
+{ "status": "packed" }

packages/agent-bundle/fixtures/web-surface/src/mcp/status.ts

@@ -21,7 +21,15 @@ export default function createStatusServer(): McpServer {
   }, async () => ({
     _meta: { ui: { resourceUri: app.resourceUri } },
     content: [{ text: 'status: healthy', type: 'text' }],
-    structuredContent: { status: 'healthy' },
+    // Echoes the launch so the packed proof can read what the host started.
+    structuredContent: {
+      launch: {
+        args: process.argv.slice(2),
+        cache: process.env['STATUS_CACHE'] ?? null,
+        mode: process.env['STATUS_MODE'] ?? null,
+      },
+      status: 'healthy',
+    },
   }));
 
   return server;

packages/agent-bundle/package.json

@@ -32,6 +32,7 @@
   "files": [
     "bin",
     "dist",
+    "schemas",
     "LICENSE",
     "NOTICE",
     "README.md"
@@ -96,6 +97,7 @@
       "types": "./dist/test/browser.d.ts",
       "import": "./dist/test/browser.js"
     },
+    "./schemas/agent-bundle.manifest.schema.json": "./schemas/agent-bundle.manifest.schema.json",
     "./web-host": {
       "types": "./dist/web-host.d.ts",
       "import": "./dist/web-host.js"