fix(adapters): keep the notice delivery shape local to the compiler and gate the inbox route on its own advertisement

Codex P1/P2 on #412:
- TargetAdapter.noticeDelivery and every build-side signature now use a local
  NoticeDeliveryAdvertisement (adapters/notice-delivery.ts) so no public
  declaration of agent-bundle resolves through the optional
  @agent-bundle/runtime peer; a test asserts mutual assignability with the
  runtime's AgentNoticeDeliveryAdvertisement and route list.
- The agent-bundle://notices/inbox resource is registered in the server and
  mounted in its Flight worker only where the host advertises mcp-inbox;
  mcp-resource-updated additionally requires the inbox. The worker still
  mounts the ledger so routes can publish, and the reserved name stays
  reserved.

Author: ScriptedAlchemy

.changeset/notice-delivery-adapter-surface.md

@@ -2,4 +2,4 @@
 "agent-bundle": patch
 ---
 
-Expose each host's #99 notice delivery advertisement through the adapter API and consume it when generating MCP entries. `TargetAdapter` gains `noticeDelivery` (typed as the runtime's `AgentNoticeDeliveryAdvertisement`), `TargetRegistry` gains `noticeDelivery(target)`, and `adapters/capability-state` gains `noticeDeliveryAdvertisementFrom()` plus `intersectNoticeDeliveryAdvertisements()`. The built-in `claude`, `codex`, `cursor`, and `portable` adapters read the advertisement from their pinned capability tables and the unified `plugin` adapter advertises the three-host intersection; the registry re-validates JavaScript adapter declarations and fails closed on unknown route states or undated unavailability. `build` and `inspect --bundler` now pass the target's advertisement to the generated route MCP entry, which wires `resources/subscribe` and `notifications/resources/updated` for the notice inbox only where the host advertises `mcp-resource-updated` (in addition to requiring workspace-durable state); a target with no advertisement wires no cross-request route.
+Expose each host's #99 notice delivery advertisement through the adapter API and select cross-request notice routes from it when generating MCP entries. `TargetAdapter` gains `noticeDelivery` (a local `NoticeDeliveryAdvertisement` shape, structurally identical to the runtime's `AgentNoticeDeliveryAdvertisement` so public declarations never resolve through the optional `@agent-bundle/runtime` peer), `TargetRegistry` gains `noticeDelivery(target)`, and `adapters/capability-state` gains `noticeDeliveryAdvertisementFrom()` plus `intersectNoticeDeliveryAdvertisements()`. The built-in `claude`, `codex`, `cursor`, and `portable` adapters read the advertisement from their pinned capability tables and the unified `plugin` adapter advertises the three-host intersection; the registry re-validates JavaScript adapter declarations and fails closed on unknown route states or undated unavailability. `build` and `inspect --bundler` pass the target's advertisement to the generated route MCP entry and its Flight worker: the `agent-bundle://notices/inbox` resource is registered and mounted only where the host advertises `mcp-inbox`, and `resources/subscribe` plus `notifications/resources/updated` are wired only where the host additionally advertises `mcp-resource-updated` and the state is workspace-durable. A target with no advertisement wires no cross-request route; all built-in hosts advertise `mcp-inbox`, so their artifacts are unchanged.

docs/entry-conventions.md

@@ -126,20 +126,27 @@ directory. Routed CLI bins and rendered scripts use
 in generated mounting v1 (`authorized`); recipient/principal matching remains
 enforced by the ledger, while application authorization policy is deferred.
 
-For workspace-durable state only, and only when the target host advertises the
-`mcp-resource-updated` route, the generated MCP server process also opens its
-own SQLite handle on the notice ledger (`createGeneratedNoticeRuntime` over
-the same anchor) and advertises `resources.subscribe`: a client that
-subscribes to `agent-bundle://notices/inbox` receives one
-`notifications/resources/updated` after a render leaves it newly eligible
-pending notices, recorded on the ledger as an availability receipt. The
-advertisement is the host's pinned `noticeDelivery` table, exposed as
-`TargetAdapter.noticeDelivery` / `TargetRegistry.noticeDelivery(target)` and
-typed for `selectNoticeDeliveryRoutes`; the unified `plugin` target advertises
-the intersection of its three hosts. Volatile lifetimes keep the store in the
-worker's heap, and a host whose table marks the route unavailable has no
-consumer for the signal, so those servers register no subscription handlers
-and advertise no subscribe capability.
+Each cross-request notice route is selected from the target host's pinned
+`noticeDelivery` table, exposed as `TargetAdapter.noticeDelivery` /
+`TargetRegistry.noticeDelivery(target)` (a local `NoticeDeliveryAdvertisement`
+shape, structurally identical to the runtime's so it types for
+`selectNoticeDeliveryRoutes` without making the optional `@agent-bundle/runtime`
+peer a declaration dependency); the unified `plugin` target advertises the
+intersection of its three hosts, and a target with no advertisement wires no
+cross-request route. The `agent-bundle://notices/inbox` resource is registered
+in the server and mounted in its worker only for stateful projects whose host
+advertises `mcp-inbox` (the worker still mounts the ledger so routes can
+publish; only the unadvertised read surface is withheld, and the reserved name
+stays reserved). For workspace-durable state only, and only when the host also
+advertises `mcp-resource-updated`, the server process opens its own SQLite
+handle on the notice ledger (`createGeneratedNoticeRuntime` over the same
+anchor) and advertises `resources.subscribe`: a client that subscribes to the
+inbox receives one `notifications/resources/updated` after a render leaves it
+newly eligible pending notices, recorded on the ledger as an availability
+receipt. Volatile lifetimes keep the store in the worker's heap, and a host
+whose table marks the route unavailable has no consumer for the signal, so
+those servers register no subscription handlers and advertise no subscribe
+capability.
 
 #### State mutation budgets
 

packages/agent-bundle/src/adapters/capability-state.ts

@@ -1,12 +1,12 @@
-import type {
-  AgentNoticeDeliveryAdvertisement,
-  AgentNoticeDeliveryRoute,
-  AgentNoticeDeliveryRouteState,
-} from '@agent-bundle/runtime/notices';
-
 import { stableJson } from '../core/digest.ts';
 import { CapabilityStateError, unknownCapabilityStateError } from '../core/capabilities.ts';
 import type { CapabilityEvidence, CapabilityState } from '../core/capabilities.ts';
+import {
+  NOTICE_DELIVERY_ROUTES,
+  type NoticeDeliveryAdvertisement,
+  type NoticeDeliveryRoute,
+  type NoticeDeliveryRouteState,
+} from './notice-delivery.ts';
 import type { TargetAdapterMetadata } from './types.ts';
 
 /** Builds immutable evidence from a target's pinned capability-table metadata. */
@@ -72,25 +72,6 @@ export interface NoticeDeliveryCapabilityTableEntry {
   readonly state: string;
 }
 
-/**
- * The #99 route taxonomy, spelled locally because `@agent-bundle/runtime` is
- * an optional peer of the compiler core and may only be imported for types
- * here. The `satisfies` clause plus the exhaustiveness check below fail the
- * build if the runtime's vocabulary ever diverges from this list.
- */
-const noticeDeliveryRoutes = Object.freeze([
-  'current-response',
-  'next-event',
-  'mcp-inbox',
-  'mcp-resource-updated',
-  'directed-push',
-  'host-toast',
-] as const satisfies readonly AgentNoticeDeliveryRoute[]);
-
-type MissingNoticeDeliveryRoute = Exclude<AgentNoticeDeliveryRoute, (typeof noticeDeliveryRoutes)[number]>;
-const noticeDeliveryRoutesAreExhaustive: MissingNoticeDeliveryRoute extends never ? true : never = true;
-void noticeDeliveryRoutesAreExhaustive;
-
 /**
  * Converts a pinned host table's `noticeDelivery` rows into the typed
  * advertisement the notice router consumes (#99 stage 4). Every route in the
@@ -101,8 +82,8 @@ void noticeDeliveryRoutesAreExhaustive;
 export const noticeDeliveryAdvertisementFrom = (
   target: string,
   rows: Readonly<Record<string, NoticeDeliveryCapabilityTableEntry>>,
-): AgentNoticeDeliveryAdvertisement => {
-  const entries = noticeDeliveryRoutes.map((route): [AgentNoticeDeliveryRoute, AgentNoticeDeliveryRouteState] => {
+): NoticeDeliveryAdvertisement => {
+  const entries = NOTICE_DELIVERY_ROUTES.map((route): [NoticeDeliveryRoute, NoticeDeliveryRouteState] => {
     const row = rows[route];
     if (row === undefined) {
       throw new CapabilityStateError(`The pinned ${target} table advertises no notice delivery route ${route}.`);
@@ -123,7 +104,7 @@ export const noticeDeliveryAdvertisementFrom = (
         );
     }
   });
-  return Object.freeze(Object.fromEntries(entries)) as AgentNoticeDeliveryAdvertisement;
+  return Object.freeze(Object.fromEntries(entries)) as NoticeDeliveryAdvertisement;
 };
 
 /**
@@ -132,10 +113,10 @@ export const noticeDeliveryAdvertisementFrom = (
  * hosts that do not are kept so the composite stays as honest as its parts.
  */
 export const intersectNoticeDeliveryAdvertisements = (
-  left: AgentNoticeDeliveryAdvertisement,
-  right: AgentNoticeDeliveryAdvertisement,
-): AgentNoticeDeliveryAdvertisement => Object.freeze(Object.fromEntries(
-  noticeDeliveryRoutes.map((route): [AgentNoticeDeliveryRoute, AgentNoticeDeliveryRouteState] => {
+  left: NoticeDeliveryAdvertisement,
+  right: NoticeDeliveryAdvertisement,
+): NoticeDeliveryAdvertisement => Object.freeze(Object.fromEntries(
+  NOTICE_DELIVERY_ROUTES.map((route): [NoticeDeliveryRoute, NoticeDeliveryRouteState] => {
     const reasons = [left[route], right[route]]
       .flatMap((entry) => (entry.state === 'unavailable' ? [entry.reason] : []));
     return reasons.length === 0
@@ -145,7 +126,7 @@ export const intersectNoticeDeliveryAdvertisements = (
         state: 'unavailable',
       })];
   }),
-)) as AgentNoticeDeliveryAdvertisement;
+)) as NoticeDeliveryAdvertisement;
 
 export const capabilityStateFromSupport = (
   supported: boolean,

packages/agent-bundle/src/adapters/notice-delivery.ts

@@ -0,0 +1,26 @@
+/**
+ * The #99 notice delivery route taxonomy, spelled in the compiler package so
+ * that public declarations such as `TargetAdapter` never resolve through
+ * `@agent-bundle/runtime`, which is an optional peer of `agent-bundle`. The
+ * shape is structurally identical to the runtime's
+ * `AgentNoticeDeliveryAdvertisement`; `adapter-capability-states.test.ts`
+ * asserts the two are mutually assignable so a vocabulary change on either
+ * side fails the build.
+ */
+export const NOTICE_DELIVERY_ROUTES = Object.freeze([
+  'current-response',
+  'next-event',
+  'mcp-inbox',
+  'mcp-resource-updated',
+  'directed-push',
+  'host-toast',
+] as const);
+
+export type NoticeDeliveryRoute = (typeof NOTICE_DELIVERY_ROUTES)[number];
+
+export type NoticeDeliveryRouteState =
+  | { readonly state: 'supported' }
+  | { readonly reason: string; readonly state: 'unavailable' };
+
+/** A host's honest, dated advertisement of which notice delivery routes it can carry. */
+export type NoticeDeliveryAdvertisement = Readonly<Record<NoticeDeliveryRoute, NoticeDeliveryRouteState>>;

packages/agent-bundle/src/adapters/registry.ts

@@ -33,7 +33,7 @@ import type {
 } from './types.ts';
 import type { TargetMcpRuntimeContract } from '../services/mcp-runtime.ts';
 import { deepFreeze } from '../core/freeze.ts';
-import type { AgentNoticeDeliveryAdvertisement } from '@agent-bundle/runtime/notices';
+import type { NoticeDeliveryAdvertisement } from './notice-delivery.ts';
 
 
 const sha256Pattern = /^[0-9a-f]{64}$/;
@@ -412,7 +412,7 @@ const snapshotMcpRuntime = (adapter: TargetAdapter): TargetMcpRuntimeContract |
  * boundary so a JavaScript adapter cannot smuggle an unknown route state into
  * the generated MCP entry's route selection.
  */
-const snapshotNoticeDelivery = (adapter: TargetAdapter): AgentNoticeDeliveryAdvertisement | undefined => {
+const snapshotNoticeDelivery = (adapter: TargetAdapter): NoticeDeliveryAdvertisement | undefined => {
   const declared = adapter.noticeDelivery;
   if (declared === undefined) return undefined;
   const rows = record(declared);
@@ -478,7 +478,7 @@ export class TargetRegistry implements NormalizationTargetRegistry {
   readonly #metadata = new Map<string, TargetAdapterMetadata>();
   readonly #mcpRuntimes = new Map<string, TargetMcpRuntimeContract>();
   readonly #nativeHookSources = new Map<string, NativeHookSource>();
-  readonly #noticeDeliveries = new Map<string, AgentNoticeDeliveryAdvertisement>();
+  readonly #noticeDeliveries = new Map<string, NoticeDeliveryAdvertisement>();
   readonly #outputStylesSources = new Map<string, OutputStylesSource>();
   readonly #workflowsSources = new Map<string, WorkflowsSource>();
 
@@ -592,7 +592,7 @@ export class TargetRegistry implements NormalizationTargetRegistry {
   }
 
   /** The validated notice delivery advertisement, or undefined for a host that declares none. */
-  noticeDelivery(name: string): AgentNoticeDeliveryAdvertisement | undefined {
+  noticeDelivery(name: string): NoticeDeliveryAdvertisement | undefined {
     if (!this.#adapters.has(name)) {
       throw new Error(`Unknown target adapter "${name}".`);
     }

packages/agent-bundle/src/adapters/types.ts

@@ -2,8 +2,6 @@ import { Ajv } from 'ajv/dist/ajv.js';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 
-import type { AgentNoticeDeliveryAdvertisement } from '@agent-bundle/runtime/notices';
-
 import type { CapabilityState } from '../core/capabilities.ts';
 import type { Diagnostic } from '../core/diagnostics.ts';
 import { stableJson } from '../core/digest.ts';
@@ -16,11 +14,17 @@ import {
   type NormalizedPlugin,
 } from '../core/types.ts';
 import type { TargetHookContract, TargetHookEntry } from './hook-contract.ts';
+import type { NoticeDeliveryAdvertisement } from './notice-delivery.ts';
 import type { TargetMcpRuntimeContract } from '../services/mcp-runtime.ts';
 import { deepFreeze } from '../core/freeze.ts';
 
 
 export type { TargetHookEntry, TargetHookWrapper } from './hook-contract.ts';
+export type {
+  NoticeDeliveryAdvertisement,
+  NoticeDeliveryRoute,
+  NoticeDeliveryRouteState,
+} from './notice-delivery.ts';
 
 export interface TargetArtifactWrite {
   readonly content: string;
@@ -516,7 +520,7 @@ export interface TargetAdapter {
    * cross-request delivery routes from this; an adapter that declares none
    * advertises no cross-request route and its artifacts wire none.
    */
-  readonly noticeDelivery?: AgentNoticeDeliveryAdvertisement;
+  readonly noticeDelivery?: NoticeDeliveryAdvertisement;
   binSource?(config: Readonly<AgentBundleConfig>): string | undefined;
   nativeHookSource?(config: Readonly<AgentBundleConfig>): string | undefined;
   outputStylesSource?(config: Readonly<AgentBundleConfig>): string | undefined;

packages/agent-bundle/src/api.ts

@@ -191,6 +191,9 @@ export type { HookListOptions, HookSimulationOptions } from './services/hook-ser
 export { createDefaultRegistry, TargetRegistry } from './adapters/registry.ts';
 export { CapabilityStateError, capabilityStateNames, isCapabilityState } from './core/capabilities.ts';
 export type {
+  NoticeDeliveryAdvertisement,
+  NoticeDeliveryRoute,
+  NoticeDeliveryRouteState,
   TargetAdapter,
   TargetAdapterMetadata,
   TargetArtifactCopy,

packages/agent-bundle/src/build/build.ts

@@ -377,17 +377,18 @@ export const build = async (options: BuildOptions): Promise<BuildResult> => {
           },
         )),
       );
+      const noticeDelivery = options.registry.noticeDelivery(target.name);
       compiledHooks.push(...(await compileHooks(target.hookEntries, {
         artifactEpoch: options.projectContext.revision,
         cwd: options.projectRoot,
         meta,
+        ...(noticeDelivery === undefined ? {} : { noticeDelivery }),
         outDir: target.root,
         plugin: { name: options.model.metadata.name, version: options.model.metadata.version },
         providers: options.model.providers ?? [],
         ...(options.model.state === undefined ? {} : { state: options.model.state }),
         ...tools,
       })));
-      const noticeDelivery = options.registry.noticeDelivery(target.name);
       compiledMcpEntries.push(...(await compileMcpEntries(options.model.mcpServers, {
         apps: targetMcpApps,
         artifactEpoch: options.projectContext.revision,

packages/agent-bundle/src/build/entries.ts

@@ -3,8 +3,7 @@ import { readFile, stat } from 'node:fs/promises';
 import { basename, dirname, extname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import type { AgentNoticeDeliveryAdvertisement } from '@agent-bundle/runtime/notices';
-
+import type { NoticeDeliveryAdvertisement } from '../adapters/notice-delivery.ts';
 import {
   eventArtifactEpochToken,
   eventFlightArtifactEpochToken,
@@ -321,7 +320,7 @@ export const compileMcpEntries = async (
     readonly eventHooks: readonly NormalizedHook[];
     readonly meta: AgentBundleMeta;
     /** The target adapter's notice delivery advertisement; absent wires no cross-request route. */
-    readonly noticeDelivery?: AgentNoticeDeliveryAdvertisement;
+    readonly noticeDelivery?: NoticeDeliveryAdvertisement;
     readonly outDir: string;
     readonly plugin: { readonly name: string; readonly version: string };
     readonly providers?: readonly CompiledProvider[];
@@ -374,6 +373,7 @@ export const compileMcpEntries = async (
       : generatedRouteFlightWorkerSource({
         artifactEpoch: generatedRouteArtifactEpoch(options.plugin),
         eventRoutes: entry.id === eventHostId ? options.eventHooks : [],
+        ...(options.noticeDelivery === undefined ? {} : { noticeDelivery: options.noticeDelivery }),
         providers: options.providers ?? [],
         routes: server.generatedRoutes,
         serverName: server.name,
@@ -516,6 +516,7 @@ export const compileHooks = async (
     readonly artifactEpoch: string;
     readonly cwd: string;
     readonly meta: AgentBundleMeta;
+    readonly noticeDelivery?: NoticeDeliveryAdvertisement;
     readonly outDir: string;
     readonly plugin: { readonly name: string; readonly version: string };
     readonly providers?: readonly CompiledProvider[];
@@ -550,6 +551,7 @@ export const compileHooks = async (
       virtualSource: generatedRouteFlightWorkerSource({
         artifactEpoch: workerArtifactEpoch,
         eventRoutes: standaloneEventRoutes,
+        ...(options.noticeDelivery === undefined ? {} : { noticeDelivery: options.noticeDelivery }),
         providers: options.providers ?? [],
         routes: [],
         serverName: 'hooks',