feat: select event routes by capability (#679)

* feat: select event routes by capability

* docs: link capability projection changeset

Author: ScriptedAlchemy

.changeset/event-route-requires.md

@@ -0,0 +1,5 @@
+---
+'agent-bundle': minor
+---
+
+Add event-route `config.requires` capability selection with `AB4824` and `AB4825` diagnostics for unsupported rows or incompatible selectors (#679).

docs/diagnostics.md

@@ -1299,8 +1299,8 @@ resolving a provider set the author did not write.
 | `AB4821` | error | A project state definition uses the reserved notice-ledger id `@agent-bundle/runtime/agent-notice-ledger/v1`; generated runtimes own that id for the co-mounted notice store. |
 | `AB4822` | error | A `routes.mcpCommands.include` or `.exclude` pattern matches no eligible tool, or `include: []` explicitly selects none. Correct the pattern using an available `<server>:<tool>` identity listed by the diagnostic. |
 | `AB4823` | error | An event route declares an event outside the v1 event vocabulary. |
-| `AB4824` | error | An event route selects an unknown target or requires an event capability that the selected target does not support. |
-| `AB4825` | error | An event route's `config.targets` is not a nonempty array of nonempty target names. |
+| `AB4824` | error | An event route selects an unknown target, requires an event the selected target does not support, or declares a capability row in `config.requires` that no selected host supports. An unmet requirement names the row and every selected host considered. |
+| `AB4825` | error | An event route declares both `config.targets` and `config.requires`, or either selector is not a nonempty array of nonempty target names or capability row ids. |
 | `AB4826` | error | A route's static `config` calls `appResourceUri('<app>')` with a reference that matches no App route of the route's own generated server with a static `config.resourceUri`: an unknown name, another server's App (a generated server registers only its own Apps), or a reference from a non-MCP route. The message names the cause and lists the server's known App route ids; reference the App as `'<app>'`, `'<server>/<app>'`, `'app:<server>/<app>'`, or a relative module path. |
 | `AB4827` | error | An MCP App route's `config.template` is ambiguous or missing: both the route-relative and the project-root-relative interpretation name different existing files, or neither exists. The message names both candidate paths; templates resolve relative to the route module, so rewrite the path as `'./<file>.html'` beside the route. |
 | `AB4828` | error | A generated MCP route advertises `_meta.ui.resourceUri` of an App on its server (through `appResourceUri()` or a literal) that is not built for every target the server ships to, because the App's `config.targets` (or a config-declared App's `targets`) is narrower. Widen the App's targets or restrict `mcp.servers.<server>.targets`. |

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

@@ -80,6 +80,16 @@ export interface EventRouteCapabilityTableEntry {
   readonly state: string;
 }
 
+const eventRouteRequirementFeatures: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  'session/start': Object.freeze(['context']),
+  stop: Object.freeze(['deny']),
+  'tool/after': Object.freeze(['context']),
+  'tool/before': Object.freeze(['deny']),
+});
+
+const eventRequirementName = (event: string): string =>
+  `events.${event.replace(/\/(.)/gu, (_, character: string) => character.toUpperCase())}`;
+
 /**
  * Converts a pinned host table's semantic-event rows into the shared
  * capability-state namespace consumed by route validation and inspect.
@@ -88,18 +98,23 @@ export const eventRouteCapabilitiesFrom = (
   routes: Readonly<Record<string, EventRouteCapabilityTableEntry>>,
   evidence: CapabilityEvidence,
 ): Readonly<Record<string, CapabilityState>> => Object.freeze(Object.fromEntries(
-  Object.entries(routes).sort(([left], [right]) => left.localeCompare(right)).map(([event, capability]) => {
+  Object.entries(routes).sort(([left], [right]) => left.localeCompare(right)).flatMap(([event, capability]) => {
+    let state: CapabilityState;
     switch (capability.state) {
       case 'supported':
-        return [`event:${event}`, supportedCapability(evidence)];
+        state = supportedCapability(evidence);
+        break;
       case 'unavailable':
-        return [
-          `event:${event}`,
-          unavailableCapability(capability.reason ?? `The pinned ${evidence.target} contract does not support ${event}.`),
-        ];
+        state = unavailableCapability(capability.reason ?? `The pinned ${evidence.target} contract does not support ${event}.`);
+        break;
       default:
         throw new TypeError(`Unsupported event-route capability state ${JSON.stringify(capability.state)} for ${event}.`);
     }
+    const requirement = eventRequirementName(event);
+    return [
+      [`event:${event}`, state],
+      ...(eventRouteRequirementFeatures[event] ?? []).map((feature) => [`${requirement}.${feature}`, state] as const),
+    ];
   }),
 ));
 

packages/agent-bundle/src/config/normalize.ts

@@ -66,6 +66,7 @@ import type {
 } from '../core/types.ts';
 import { appRouteTemplatePath, resolveAppRouteTemplate } from '../routes/app-template.ts';
 import { eventRouteExecutionFor } from '../routes/event-execution.ts';
+import { targetsSatisfyingEventRequirements } from '../routes/event-requirements.ts';
 import { mcpRouteProtocolName } from '../routes/protocol-name.ts';
 import type { CompiledCliSurface } from '../routes/types.ts';
 import { type DiscoveredProject, payloadDeclarationSource } from './discover.ts';
@@ -535,9 +536,14 @@ const normalizeHooks = (
   for (const route of discovered.routeGraph?.events ?? []) {
     const event = route.event!;
     const selected = route.config['targets'];
+    const requires = route.config['requires'];
     const targets = sortedUnique(
-      (Array.isArray(selected) ? selected.filter((target): target is string => typeof target === 'string') : targetNames)
-        .filter((target) => targetNames.includes(target)),
+      targetsSatisfyingEventRequirements(
+        requires,
+        (Array.isArray(selected) ? selected.filter((target): target is string => typeof target === 'string') : targetNames)
+          .filter((target) => targetNames.includes(target)),
+        registry,
+      ),
     );
     const tools = (Array.isArray(route.config['tools']) ? route.config['tools'] : [])
       .filter((tool): tool is CanonicalHookTool =>

packages/agent-bundle/src/config/validate.ts

@@ -26,6 +26,7 @@ import {
 } from '../core/runtime.ts';
 import { canonicalHookEvents, isPrebuiltEntryInput, parseNativeHookToolSelector } from '../core/types.ts';
 import { type RouteModuleExports, scanRouteModuleExports } from '../routes/contract.ts';
+import { targetsSatisfyingEventRequirements } from '../routes/event-requirements.ts';
 import { mcpRouteProtocolName } from '../routes/protocol-name.ts';
 import { featureCapabilityName } from '../core/components.ts';
 import { isServeAppAllowCapability } from '../core/mcp-app-allow.ts';
@@ -1429,6 +1430,15 @@ const validateEventRoutes = (
 
   for (const route of discovered.routeGraph?.events ?? []) {
     const declaredTargets = route.config['targets'];
+    const declaredRequirements = route.config['requires'];
+    if (declaredTargets !== undefined && declaredRequirements !== undefined) {
+      diagnostics.push(sourceDiagnostic(
+        'AB4825',
+        `Event route ${route.provenance.relativePath} declares both config.targets and config.requires; choose one projection selector.`,
+        route.source,
+      ));
+      continue;
+    }
     if (
       declaredTargets !== undefined &&
       (!Array.isArray(declaredTargets) ||
@@ -1442,8 +1452,36 @@ const validateEventRoutes = (
       ));
       continue;
     }
+    if (
+      declaredRequirements !== undefined &&
+      (!Array.isArray(declaredRequirements) ||
+        declaredRequirements.length === 0 ||
+        declaredRequirements.some((requirement) => typeof requirement !== 'string' || requirement.trim().length === 0))
+    ) {
+      diagnostics.push(sourceDiagnostic(
+        'AB4825',
+        `Event route ${route.provenance.relativePath} config.requires must be a nonempty array of capability row ids.`,
+        route.source,
+      ));
+      continue;
+    }
+    const requirements = declaredRequirements === undefined
+      ? []
+      : [...new Set(declaredRequirements as readonly string[])];
+    for (const requirement of requirements) {
+      if (selectedTargets.some((target) => registry.supports(target, requirement))) continue;
+      for (const target of selectedTargets) {
+        diagnostics.push({
+          code: 'AB4824',
+          message: `Event route ${route.provenance.relativePath} requires capability row ${requirement}, unsupported on ${target}.`,
+          severity: 'error',
+          sourcePath: route.source,
+          target,
+        });
+      }
+    }
     const targets = declaredTargets === undefined
-      ? selectedTargets
+      ? targetsSatisfyingEventRequirements(requirements, selectedTargets, registry)
       : [...new Set(declaredTargets as readonly string[])];
     for (const target of targets) {
       if (!registry.has(target)) {

packages/agent-bundle/src/dev/playground/lifecycle-replay-service.ts

@@ -30,6 +30,7 @@ import {
   canonicalAgentEvents,
   type CanonicalAgentEvent,
 } from '../../routes/public.ts';
+import { targetsSatisfyingEventRequirements } from '../../routes/event-requirements.ts';
 import type { CompiledAgentRoute, CompiledRouteGraph } from '../../routes/types.ts';
 import type { RenderRouteContext, renderRouteEvents } from '../../test/render.ts';
 import type { AgentRouteModule } from '../../test/types.ts';
@@ -479,10 +480,15 @@ export class LifecycleReplayService {
     projectTargets: readonly string[],
   ): Readonly<{ readonly diagnostics: readonly LifecycleDiagnostic[]; readonly targets: readonly LifecycleTarget[] }> {
     const configured = route.config['targets'];
+    const requirements = route.config['requires'];
     const selected = expandedTargets(
-      Array.isArray(configured)
-        ? configured.filter((target): target is string => typeof target === 'string')
-        : projectTargets,
+      targetsSatisfyingEventRequirements(
+        requirements,
+        Array.isArray(configured)
+          ? configured.filter((target): target is string => typeof target === 'string')
+          : projectTargets,
+        this.#registry,
+      ),
     );
     const available = expandedTargets(projectTargets);
     const diagnostics: LifecycleDiagnostic[] = [];

packages/agent-bundle/src/routes/event-requirements.ts

@@ -0,0 +1,11 @@
+import type { NormalizationTargetRegistry } from '../core/types.ts';
+
+export const targetsSatisfyingEventRequirements = (
+  requirements: unknown,
+  targets: readonly string[],
+  registry: Pick<NormalizationTargetRegistry, 'supports'>,
+): readonly string[] =>
+  !Array.isArray(requirements)
+    ? targets
+    : targets.filter((target) => requirements.every((requirement) =>
+      typeof requirement === 'string' && registry.supports(target, requirement)));

packages/agent-bundle/src/routes/public.ts

@@ -361,6 +361,8 @@ export interface AgentEventRouteConfig {
    * compatibility behavior of resolving all providers; use `[]` for none.
    */
   readonly providers?: readonly string[];
+  /** Capability rows every projected host must support; mutually exclusive with `targets`. */
+  readonly requires?: readonly string[];
   readonly runtime?: AgentEventRuntimeMode;
   readonly targets?: readonly string[];
   /** Route budget within the adapter's stricter native-host deadline. */

packages/agent-bundle/tests/adapter-capability-states.test.ts

@@ -1057,6 +1057,26 @@ it('reports the evidence-backed G10 event family matrix without inferred support
       state: 'unavailable',
     });
   }
+  const requirementRows = [
+    'events.sessionStart.context',
+    'events.stop.deny',
+    'events.toolAfter.context',
+    'events.toolBefore.deny',
+  ];
+  for (const target of ['claude', 'codex', 'cursor'] as const) {
+    for (const capability of requirementRows) {
+      expect(registry.get(target).capabilities[capability]).toMatchObject({
+        evidence: { target },
+        state: 'supported',
+      });
+    }
+  }
+  for (const capability of requirementRows) {
+    expect(registry.get('portable').capabilities[capability]).toMatchObject({
+      state: 'unavailable',
+    });
+  }
+  expect(registry.get('cursor').capabilities['events.toolBefore.context']).toBeUndefined();
 });
 
 it('reports evidence-backed installation support only for real host targets', () => {

packages/agent-bundle/tests/build-compose.test.ts

@@ -546,6 +546,35 @@ describe('composite plugin root (#555)', () => {
     }
   });
 
+  it('normalizes the same event projections for requires as explicit targets', async () => {
+    const eventRouteTargets = async (selection: string): Promise<readonly string[]> => {
+      const root = await mkdtemp(join(tmpdir(), 'agent-bundle-event-projections-'));
+      roots.push(root);
+      await Promise.all([
+        writeProjectFile(root, 'package.json', '{"name":"event-projections","type":"module","version":"1.0.0"}\n'),
+        writeProjectFile(root, 'agent-bundle.config.ts', [
+          'export default {',
+          "  plugin: { name: 'event-projections', version: '1.0.0' },",
+          "  targets: ['claude', 'codex', 'cursor', 'portable'],",
+          '};',
+          '',
+        ].join('\n')),
+        writeProjectFile(root, 'src/events/tool/before.tsx', [
+          `export const config = { ${selection}, runtime: 'standalone' };`,
+          'export default async function ToolBefore() { return undefined; }',
+          '',
+        ].join('\n')),
+      ]);
+      const result = await validate({ root });
+      expect(result.diagnostics).toEqual([]);
+      return result.model?.hooks.find((hook) => hook.eventRoute?.event === 'tool/before')?.targets ?? [];
+    };
+
+    expect(await eventRouteTargets("requires: ['events.toolBefore.deny']")).toEqual(
+      await eventRouteTargets("targets: ['claude', 'codex', 'cursor']"),
+    );
+  });
+
   it('refuses one path planned with different bytes by two selected projections (AB4103)', { timeout: 120_000 }, async () => {
     // A Claude-only frontmatter extension lowers the skill to different
     // Markdown for Claude Code than for Codex, yet both hosts read