fix(events): freeze the exported payload tables through and mark the required canonical.payload a minor bump (review)

Author: ScriptedAlchemy

.changeset/466-canonical-event-payload.md

@@ -1,5 +1,5 @@
 ---
-"agent-bundle": patch
+"agent-bundle": minor
 ---
 
-Give every event route a canonical, per-family `canonical.payload` beside the raw `native` envelope (`AgentEventRouteProps<E>`): the fields at least two hosts report — `toolName`, `toolInput`, `toolUseId`, `toolResponse`, `sessionId` (Claude and Codex `session_id`, Cursor `conversation_id`), `transcriptPath`, `cwd`, `model`, `permissionMode`, `agentId`/`agentType`, `agentTranscriptPath`, `prompt`, `reason`, `source`, `trigger`, `error`/`isInterrupt`, `lastAssistantMessage`, and `reentry` (Claude and Codex `stop_hook_active`, Cursor `loop_count > 0`) — each delivered as `{ value, nativeKey }` naming the host key it was read from, and absent when the host did not send it, never fabricated. Cursor's `tool_output` JSON string is parsed into `toolResponse` (kept as the string when it is not valid JSON). Type a route to its family (`AgentEventRouteProps<'tool/after'>`) and `payload` narrows to that family's fields, in the route and in the generated `.agent-bundle/routes.d.ts` that `renderRoute` reads; `AgentEventCanonicalIdentity<E>` gains the same parameter. The per-family table ships as `agentEventPayloadFields`, the per-host key table as `agentEventPayloadNativeKeys` (with `AgentEventPayload`, `AgentEventPayloadField`, `AgentEventPayloadFieldName`, `AgentEventPayloadNativeKey`, and `agentEventPayloadFieldKinds`), and each pinned capability table mirrors its host's mapping under `hooks.eventRoutes.<event>.payload`, so the generated events reference documents field × host → native key per family. `agent-bundle/test` gains `createEventRouteInput(event, native, { host })`, which validates a host envelope and builds the `{ canonical, native }` input the harness takes, payload included; the Workbench Lifecycles view lists the mapped payload beside the canonical identity. Additive: `native` is unchanged, `idempotencyKey` still hashes only the envelope, and the bare `AgentEventRouteProps` keeps working with every field optional; only code that constructs `AgentEventCanonicalIdentity` by hand must add `payload`. (#466)
+Give every event route a canonical, per-family `canonical.payload` beside the raw `native` envelope (`AgentEventRouteProps<E>`): the fields at least two hosts report — `toolName`, `toolInput`, `toolUseId`, `toolResponse`, `sessionId` (Claude and Codex `session_id`, Cursor `conversation_id`), `transcriptPath`, `cwd`, `model`, `permissionMode`, `agentId`/`agentType`, `agentTranscriptPath`, `prompt`, `reason`, `source`, `trigger`, `error`/`isInterrupt`, `lastAssistantMessage`, and `reentry` (Claude and Codex `stop_hook_active`, Cursor `loop_count > 0`) — each delivered as `{ value, nativeKey }` naming the host key it was read from, and absent when the host did not send it, never fabricated. Cursor's `tool_output` JSON string is parsed into `toolResponse` (kept as the string when it is not valid JSON). Type a route to its family (`AgentEventRouteProps<'tool/after'>`) and `payload` narrows to that family's fields, in the route and in the generated `.agent-bundle/routes.d.ts` that `renderRoute` reads; `AgentEventCanonicalIdentity<E>` gains the same parameter. The per-family table ships as `agentEventPayloadFields`, the per-host key table as `agentEventPayloadNativeKeys` (with `AgentEventPayload`, `AgentEventPayloadField`, `AgentEventPayloadFieldName`, `AgentEventPayloadNativeKey`, and `agentEventPayloadFieldKinds`), and each pinned capability table mirrors its host's mapping under `hooks.eventRoutes.<event>.payload`, so the generated events reference documents field × host → native key per family. `agent-bundle/test` gains `createEventRouteInput(event, native, { host })`, which validates a host envelope and builds the `{ canonical, native }` input the harness takes, payload included; the Workbench Lifecycles view lists the mapped payload beside the canonical identity. `native` is unchanged, `idempotencyKey` still hashes only the envelope, and a route typed with the bare `AgentEventRouteProps` keeps working with every field optional. Breaking for one shape of consumer code: `payload` is a required property of `AgentEventCanonicalIdentity`, so a test or harness that constructs the identity by hand no longer compiles until it adds one — build the input with `createEventRouteInput` instead. (#466)

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

@@ -1,3 +1,4 @@
+import { deepFreeze } from '../core/freeze.ts';
 import type { JsonValue } from '../core/strict-json.ts';
 
 /** The event-route families admitted by the recorded #97 v1/G10 decision. */
@@ -103,7 +104,7 @@ export type AgentEventPayloadFieldKind =
   | 'string-array'
   | 'trigger';
 
-export const agentEventPayloadFieldKinds = Object.freeze({
+export const agentEventPayloadFieldKinds = deepFreeze({
   agentId: 'string',
   agentTranscriptPath: 'nullable-string',
   agentType: 'string',
@@ -153,8 +154,10 @@ const modelSwitchFields = [...sessionFields, 'fromModel', 'toModel', 'requestedM
  * The canonical payload fields of every event-route family, in the order the
  * payload object carries them. This is the one per-family table; the types
  * ({@link AgentEventPayload}) and the runtime projection derive from it.
+ * Frozen through (the family arrays share instances), so a consumer holding
+ * the export cannot change what later invocations project.
  */
-export const agentEventPayloadFields = Object.freeze({
+export const agentEventPayloadFields = deepFreeze({
   'agent/idle': [...sessionFields, 'teammateName', 'teamName'],
   'agent/start': threeHostFields,
   'agent/stop': [...threeHostFields, 'agentTranscriptPath', 'reentry', 'lastAssistantMessage'],
@@ -301,7 +304,7 @@ const cursorTool = [...cursorSession, 'cwd', 'toolName', 'toolInput', 'toolUseId
  */
 export const agentEventPayloadNativeKeys: Readonly<
   Record<AgentEventPayloadHost, Readonly<Partial<Record<CanonicalAgentEvent, NativeKeyTable>>>>
-> = Object.freeze({
+> = deepFreeze({
   claude: Object.freeze({
     'agent/idle': pick(standardKeys, [...claudeSession, 'teammateName', 'teamName']),
     'agent/start': pick(standardKeys, claudeSession),

packages/agent-bundle/tests/event-payload.test.ts

@@ -302,3 +302,17 @@ it('admits a family field only when at least two supporting hosts report it, or
     expect(used.has(field as AgentEventPayloadFieldName), `${field} belongs to a family`).toBe(true);
   }
 });
+
+it('exports the tables frozen through, so a consumer cannot change what later invocations project', () => {
+  for (const fields of Object.values(agentEventPayloadFields)) {
+    expect(Object.isFrozen(fields)).toBe(true);
+  }
+  for (const host of hosts) {
+    for (const mapping of Object.values(agentEventPayloadNativeKeys[host])) {
+      expect(Object.isFrozen(mapping)).toBe(true);
+      for (const entry of Object.values(mapping)) expect(Object.isFrozen(entry)).toBe(true);
+    }
+  }
+  expect(() => (agentEventPayloadFields['tool/before'] as unknown as string[]).push('reentry')).toThrow(TypeError);
+  expect(Object.isFrozen(agentEventPayloadFieldKinds)).toBe(true);
+});