feat(events): define v1 semantic route descriptors

.changeset/semantic-event-route-descriptors.md

@@ -0,0 +1,7 @@
+---
+"agent-bundle": minor
+"@agent-bundle/runtime": minor
+---
+
+Add the seven v1 semantic event-route descriptors and the `Agent.Context`
+document vocabulary used for immediate host guidance.

packages/agent-bundle/src/api.ts

@@ -12,7 +12,25 @@ import { emptyCompiledRouteGraph } from './routes/graph.ts';
 import { inspectRouteGraph, type RouteGraphInspection } from './routes/inspect.ts';
 import { mcpServerStateDirectory, runMcpForeground } from './services/mcp-run.ts';
 export { compileRouteGraph, emptyCompiledRouteGraph, isEmptyRouteGraph } from './routes/graph.ts';
-export type { AppRouteConfig, PromptConfig, ResourceConfig, RouteSchema, RouteSchemaOutput, ToolConfig, ToolRouteProps } from './routes/public.ts';
+export { canonicalAgentEvents } from './routes/public.ts';
+export type {
+  AgentEventCanonicalIdentity,
+  AgentEventDelivery,
+  AgentEventFallbackMode,
+  AgentEventNativePayload,
+  AgentEventProvenance,
+  AgentEventRouteConfig,
+  AgentEventRouteProps,
+  AgentEventRuntimeMode,
+  AppRouteConfig,
+  CanonicalAgentEvent,
+  PromptConfig,
+  ResourceConfig,
+  RouteSchema,
+  RouteSchemaOutput,
+  ToolConfig,
+  ToolRouteProps,
+} from './routes/public.ts';
 export { inspectRouteGraph } from './routes/inspect.ts';
 export type { RouteGraphInspection } from './routes/inspect.ts';
 export { emptyRouteConfig } from './routes/types.ts';

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

@@ -275,6 +275,7 @@ export const generatedRouteMcpEntrySource = (options: GeneratedRouteMcpEntryOpti
     'const appendNode = (node, content) => {',
     '  switch (node.kind) {',
     "    case 'result': for (const child of node.children) appendNode(child, content); break;",
+    "    case 'context':",
     "    case 'markdown':",
     "    case 'text': content.push({ text: node.text, type: 'text' }); break;",
     "    case 'json': content.push({ text: JSON.stringify(node.value), type: 'text' }); break;",

packages/agent-bundle/src/index.ts

@@ -4,7 +4,25 @@ import type { PortableConfigExtension } from './adapters/portable.ts';
 import type { AgentBundleConfig as CoreAgentBundleConfig } from './core/types.ts';
 
 export { defineConfig, pathTokens, pluginRootEnvAnchor } from './core/types.ts';
-export type { AppRouteConfig, PromptConfig, ResourceConfig, RouteSchema, RouteSchemaOutput, ToolConfig, ToolRouteProps } from './routes/public.ts';
+export { canonicalAgentEvents } from './routes/public.ts';
+export type {
+  AgentEventCanonicalIdentity,
+  AgentEventDelivery,
+  AgentEventFallbackMode,
+  AgentEventNativePayload,
+  AgentEventProvenance,
+  AgentEventRouteConfig,
+  AgentEventRouteProps,
+  AgentEventRuntimeMode,
+  AppRouteConfig,
+  CanonicalAgentEvent,
+  PromptConfig,
+  ResourceConfig,
+  RouteSchema,
+  RouteSchemaOutput,
+  ToolConfig,
+  ToolRouteProps,
+} from './routes/public.ts';
 export { compareEvals, runEvals, startDevServer } from './api.ts';
 export {
   createCodexEvalHarness,

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

@@ -28,12 +28,16 @@ const diagnostic = (
   recovery: string,
 ): Diagnostic => ({ code, message, recovery, severity: 'error', sourcePath });
 
-/** Validates G8's one executable route contract without evaluating the module. */
-export const validateRouteModuleContract = (
+interface RouteModuleShape {
+  readonly asyncDefault: boolean;
+  readonly named: ReadonlySet<string>;
+  readonly splitExport: boolean;
+}
+
+const inspectRouteModule = (
   moduleText: string,
   relativePath: string,
-  sourcePath: string,
-): readonly Diagnostic[] => {
+): RouteModuleShape => {
   const sourceFile = ts.createSourceFile(relativePath, moduleText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
   const named = new Set<string>();
   let asyncDefault = false;
@@ -71,6 +75,16 @@ export const validateRouteModuleContract = (
     }
   }
 
+  return { asyncDefault, named, splitExport };
+};
+
+/** Validates G8's one executable MCP route contract without evaluating the module. */
+export const validateRouteModuleContract = (
+  moduleText: string,
+  relativePath: string,
+  sourcePath: string,
+): readonly Diagnostic[] => {
+  const { asyncDefault, named, splitExport } = inspectRouteModule(moduleText, relativePath);
   const missing = ['inputSchema', 'resultSchema'].filter((name) => !named.has(name));
   const diagnostics: Diagnostic[] = [];
   if (missing.length > 0 || !asyncDefault) {
@@ -95,3 +109,30 @@ export const validateRouteModuleContract = (
   }
   return Object.freeze(diagnostics);
 };
+
+/** Validates an event route's single async component contract without requiring MCP schemas. */
+export const validateEventRouteModuleContract = (
+  moduleText: string,
+  relativePath: string,
+  sourcePath: string,
+): readonly Diagnostic[] => {
+  const { asyncDefault, splitExport } = inspectRouteModule(moduleText, relativePath);
+  const diagnostics: Diagnostic[] = [];
+  if (!asyncDefault) {
+    diagnostics.push(diagnostic(
+      'AB4810',
+      `Event route module ${relativePath} does not satisfy the public route contract: default export is not an async function component.`,
+      sourcePath,
+      'Export one async default Server Component receiving { canonical, native, signal }.',
+    ));
+  }
+  if (splitExport) {
+    diagnostics.push(diagnostic(
+      'AB4811',
+      `Event route module ${relativePath} exports execute or render; routed modules use one async default Server Component instead of an execute/render split.`,
+      sourcePath,
+      'Move execution into the async default component and render Agent.* elements from that component.',
+    ));
+  }
+  return Object.freeze(diagnostics);
+};

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

@@ -6,12 +6,13 @@ import fastGlob from 'fast-glob';
 
 import { isProjectPathIgnored, readProjectIgnoreRules, toPosixPath } from '../config/ignore.ts';
 import { extractRouteConfig } from './config-extract.ts';
-import { validateRouteModuleContract } from './contract.ts';
+import { validateEventRouteModuleContract, validateRouteModuleContract } from './contract.ts';
 import type { Diagnostic } from '../core/diagnostics.ts';
 import { digest } from '../core/digest.ts';
 import { deepFreeze } from '../core/freeze.ts';
 import { isRecord } from '../core/strict-json.ts';
 import type { AgentBundleConfig } from '../core/types.ts';
+import { canonicalAgentEvents, type CanonicalAgentEvent } from './public.ts';
 import {
   emptyRouteConfig,
   type CompiledAgentRoute,
@@ -35,6 +36,7 @@ type ProjectIgnoreRules = Awaited<ReturnType<typeof readProjectIgnoreRules>>;
 const routeGlobs = [
   'src/mcp/*/{tools,resources,prompts,apps}/*.{ts,tsx}',
   'src/events/*/*.{ts,tsx}',
+  'src/events/stop.{ts,tsx}',
   'src/providers/*.{ts,tsx}',
   'src/cli/**/*.{ts,tsx}',
   // Scripts also discover .jsx: the stage-1 script gate judges rendered
@@ -105,6 +107,7 @@ interface DiscoveredProviderModule {
 }
 
 interface DiscoveredRouteModule {
+  readonly event?: CanonicalAgentEvent;
   readonly id: string;
   /** The path-derived name segments; each must satisfy the safe-identity rule. */
   readonly identitySegments: readonly string[];
@@ -138,10 +141,11 @@ const classifyModule = (source: string, relativePath: string): DiscoveredModule
     };
   }
   if (collection === 'events') {
-    const family = segments[2]!;
+    const event = segments.length === 3 ? stem : `${segments[2]!}/${stem}`;
     return {
-      id: `event:${family}/${stem}`,
-      identitySegments: [family, stem],
+      event: event as CanonicalAgentEvent,
+      id: `event:${event}`,
+      identitySegments: event.split('/'),
       kind: 'event-route',
       relativePath,
       source,
@@ -302,6 +306,7 @@ const compiledRoute = (
   config: Readonly<Record<string, unknown>>,
 ): CompiledAgentRoute => ({
   config,
+  ...(module.event === undefined ? {} : { event: module.event }),
   id: module.id,
   kind: module.kind,
   provenance: { kind: 'conventional', relativePath: module.relativePath },
@@ -331,6 +336,7 @@ const extractedModuleConfig = async (
 
 const routeIdentity = (route: CompiledAgentRoute): Readonly<Record<string, unknown>> => ({
   config: route.config,
+  ...(route.event === undefined ? {} : { event: route.event }),
   id: route.id,
   kind: route.kind,
   relativePath: route.provenance.relativePath,
@@ -392,6 +398,19 @@ export const compileRouteGraph = async (
     const relativePath = toPosixPath(relative(projectRoot, source));
     if (isPrivateRoutePath(relativePath) || isProjectPathIgnored(rules, projectRoot, source)) continue;
     const module = classifyModule(source, relativePath);
+    if (
+      module.surface === 'route' &&
+      module.kind === 'event-route' &&
+      !canonicalAgentEvents.includes(module.event!)
+    ) {
+      diagnostics.push(routeError(
+        'AB4813',
+        `Event route ${relativePath} declares ${JSON.stringify(module.event)}, which is outside the #97 v1 event vocabulary.`,
+        `Use one of: ${canonicalAgentEvents.join(', ')}.`,
+        source,
+      ));
+      continue;
+    }
     const unsafeSegment = module.identitySegments.find((segment) => !safeIdentitySegment.test(segment));
     if (unsafeSegment !== undefined) {
       diagnostics.push(routeError(
@@ -432,6 +451,17 @@ export const compileRouteGraph = async (
       continue;
     }
     const route = compiledRoute(module, await extractedModuleConfig(module, diagnostics));
+    if (route.kind === 'event-route') {
+      try {
+        diagnostics.push(...validateEventRouteModuleContract(
+          await readFile(route.source, 'utf8'),
+          route.provenance.relativePath,
+          route.source,
+        ));
+      } catch {
+        // Racing deletion is handled by the next source snapshot.
+      }
+    }
     switch (route.kind) {
       case 'tool':
       case 'resource':

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

@@ -18,5 +18,23 @@ export type {
   RouteProvenance,
 } from './types.ts';
 export { generateRouteTypes, routeTypesRelativePath, writeRouteTypes } from './typegen.ts';
-export { validateRouteModuleContract } from './contract.ts';
-export type { AppRouteConfig, PromptConfig, ResourceConfig, RouteSchema, RouteSchemaOutput, ToolConfig, ToolRouteProps } from './public.ts';
+export { validateEventRouteModuleContract, validateRouteModuleContract } from './contract.ts';
+export { canonicalAgentEvents } from './public.ts';
+export type {
+  AgentEventCanonicalIdentity,
+  AgentEventDelivery,
+  AgentEventFallbackMode,
+  AgentEventNativePayload,
+  AgentEventProvenance,
+  AgentEventRouteConfig,
+  AgentEventRouteProps,
+  AgentEventRuntimeMode,
+  AppRouteConfig,
+  CanonicalAgentEvent,
+  PromptConfig,
+  ResourceConfig,
+  RouteSchema,
+  RouteSchemaOutput,
+  ToolConfig,
+  ToolRouteProps,
+} from './public.ts';

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

@@ -5,6 +5,61 @@ export interface RouteSchema<Output = unknown> {
 
 export type RouteSchemaOutput<Schema> = Schema extends RouteSchema<infer Output> ? Output : never;
 
+/** The event-route families admitted by the recorded #97 v1/G10 decision. */
+export const canonicalAgentEvents = Object.freeze([
+  'session/start',
+  'tool/before',
+  'tool/after',
+  'stop',
+  'agent/start',
+  'agent/stop',
+  'workspace/open',
+] as const);
+
+export type CanonicalAgentEvent = (typeof canonicalAgentEvents)[number];
+
+export interface AgentEventProvenance {
+  readonly host: string;
+  readonly hostContractRevision: string;
+  readonly nativeEvent: string;
+  readonly source: 'native';
+}
+
+/** Cross-host identity supplied to an event route without fabricated host fields. */
+export interface AgentEventCanonicalIdentity {
+  readonly event: CanonicalAgentEvent;
+  readonly idempotencyKey: string;
+  readonly observedAt: string;
+  readonly provenance: AgentEventProvenance;
+  readonly sequence: number;
+}
+
+/** Complete host envelope after the adapter's schema and byte-bound validation. */
+export type AgentEventNativePayload = Readonly<Record<string, unknown>>;
+
+/** Props received by an event route's async default Server Component. */
+export interface AgentEventRouteProps {
+  readonly canonical: AgentEventCanonicalIdentity;
+  readonly native: AgentEventNativePayload;
+  readonly signal: AbortSignal;
+}
+
+export type AgentEventDelivery = 'immediate';
+export type AgentEventRuntimeMode = 'shared' | 'standalone';
+export type AgentEventFallbackMode = 'none' | 'standalone';
+
+/** Statically extractable event-route configuration. */
+export interface AgentEventRouteConfig {
+  readonly delivery?: readonly AgentEventDelivery[];
+  readonly fallback?: AgentEventFallbackMode;
+  readonly runtime?: AgentEventRuntimeMode;
+  readonly targets?: readonly string[];
+  /** Route budget within the adapter's stricter native-host deadline. */
+  readonly timeoutMs?: number;
+  /** Canonical tool selectors for tool/before and tool/after routes. */
+  readonly tools?: readonly string[];
+}
+
 /** Props received by every executable MCP route's async default Server Component. */
 export interface ToolRouteProps<InputSchema extends RouteSchema> {
   readonly input: RouteSchemaOutput<InputSchema>;

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

@@ -31,10 +31,16 @@ export const generateRouteTypes = (graph: CompiledRouteGraph): string => {
     '  input: SchemaOutput<InputSchema>;',
     '  result: SchemaOutput<ResultSchema>;',
     '}>;',
+    'export type EventRouteContract<Component, Event extends string> = Readonly<{',
+    '  component: Component;',
+    '  event: Event;',
+    '}>;',
     '',
     'export interface AgentBundleRoutes {',
     ...routes.map((route, index) =>
-      `  ${JSON.stringify(route.id)}: RouteContract<typeof route${String(index)}.inputSchema, typeof route${String(index)}.resultSchema>;`),
+      route.kind === 'event-route'
+        ? `  ${JSON.stringify(route.id)}: EventRouteContract<typeof route${String(index)}.default, ${JSON.stringify(route.event)}>;`
+        : `  ${JSON.stringify(route.id)}: RouteContract<typeof route${String(index)}.inputSchema, typeof route${String(index)}.resultSchema>;`),
     '}',
     '',
     'export type RouteId = keyof AgentBundleRoutes;',

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

@@ -1,4 +1,5 @@
 import type { Diagnostic } from '../core/diagnostics.ts';
+import type { CanonicalAgentEvent } from './public.ts';
 
 /**
  * Every route kind the conventional source tree can declare. Context
@@ -39,6 +40,8 @@ export const emptyRouteConfig: Readonly<Record<string, unknown>> = Object.freeze
 export interface CompiledAgentRoute {
   /** Statically extracted from the module's `export const config` declaration; {@link emptyRouteConfig} when absent or rejected. */
   readonly config: Readonly<Record<string, unknown>>;
+  /** Canonical event identity; present only when {@link kind} is `event-route`. */
+  readonly event?: CanonicalAgentEvent;
   readonly id: string;
   readonly kind: CompiledRouteKind;
   readonly provenance: RouteProvenance;