feat(relay): a webhook caller can key deliveries into one session per subject

[strstensky]

Implements #1764.

What changes

A generic webhook hook gains a third sessionMode, perSubject: the caller names the session subject with an X-AC-Session-Key header, and every delivery carrying the same value continues one session — so an external subject (a service-desk ticket and its comments, an order, a conversation) accumulates context across events instead of waking the agent context-free each time.

• relay (hooks/ingress.ts): sessionKeyFor takes the subject key; in perSubject mode with a valid header (same 1–200-char validation as the delivery key) the session key is <hookId>:subject:<key> — the subject: segment keeps the space disjoint from per-delivery keys. A delivery without the header degrades to per-delivery, and the header is inert in the other modes. msgId keeps the delivery key untouched, so the daemon's (sessionKey, msgId) dedup semantics are exactly as before: a retried delivery is still absorbed, distinct deliveries of one subject append turns. This is deliberate — the existing X-AC-Delivery-Key cannot express continuity, because reusing it makes the second delivery a redelivery, not a follow-up (design decision 6).
• protocol (relay-cp.ts): perSubject joins the RcHookAssign.sessionMode wire enum. An older relay parsing a rule compiled with the new mode rejects the frame, so CP and relay should ship together — same coupling as any prior enum widening on this frame.
• control-plane: HookSessionModeEnum and CreateWebhookHookBody accept perSubject (create and whole-definition PUT both flow through the same schema); HookSessionMode in persistence/ports.ts; Prisma HookSessionMode enum plus an additive migration (ALTER TYPE … ADD VALUE IF NOT EXISTS 'perSubject'). The compile path already passes sessionMode through opaquely.
• web: the webhook create form gains a "Session continuity" select (per delivery / per subject / shared — the latter two were previously API-only, shared remains reachable only via API on update), with a helper line explaining the header when perSubject is picked; CreateHookInput/HookDto typings widened.
• docs (webhook-triggers-and-github-events.md): the ingress contract lists the new header with its role (affinity, not idempotency), the relay step list gains the affinity-computation step, and the General Webhook sessionMode section documents perSubject including the affinity-vs-idempotency split.

The GitHub hook kind's perThread (one session per issue/PR) is exactly this pattern minted relay-side from signed payload facts; perSubject hands the same capability to generic callers who authenticate via the capability URL, whose payload is already trusted instruction by design.

What does not change

perDelivery and shared behave byte-identically (existing ingress tests untouched and green). Delivery-key semantics, HMAC verification, rate limiting, the 202/deliveryKey response, body truncation, and the GitHub/GitLab ingresses are untouched. The daemon needs no change — it already treats sessionKey as an opaque affinity key. The session key is not part of the HMAC-signed content, matching the existing delivery-key header's treatment; a caller who wants it tamper-proof can bind it inside the signed body.

Verification

Unit level only — no live relay/CP pair was exercised:

• relay: 5 new ingress.test.ts cases — two deliveries sharing a session key land in one session with distinct msgIds; a missing header falls back to per-delivery; an oversized (>200) key is ignored like an absent one; the header is inert outside perSubject; shared/perDelivery cases unchanged. 642/642 pass.
• control-plane: test:unit 2247/2247 pass; typecheck clean (prisma generate + tsc).
• protocol tests, daemon typecheck, web typecheck and web tests (211 files / 2356) all pass; changed files are eslint- and prettier-clean.
• The migration is additive (ADD VALUE IF NOT EXISTS), no table rewrite.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[agentconnect-md-test]

The control-plane, protocol, relay, and console wiring for perSubject is internally consistent, but there is one blocking end-to-end gap: the daemon does not recognize the new affinity-key shape, so distinct deliveries for one subject still create distinct sessions. Existing session modes are unaffected. I traced the relay frame through buildHookMessage, transcript coordinate fallback, and the session-store key; the focused suites could not be executed because dependencies are absent and this runner cannot fetch the pinned pnpm package. git diff --check passes.

_{sent by review-bot (Codex · gpt-5.6-sol) · open in session}

[agentconnect-md-test]

[P2] Preserve this affinity in the daemon normalizer. buildHookMessage() currently recognizes only hookId (shared), hookId:deliveryKey (per-delivery), and GitHub keys containing #. A value such as hookId:subject:ticket-42 falls through with no normalized thread; transcriptCoords() then substitutes this delivery's msgId, so deliveries d1 and d2 produce different session-store keys despite having the same subject key. Please add a perSubject normalization path that yields stable, mode-namespaced channel/thread coordinates.