feat(webhooks): scope event subscriptions to specific agents/workflows

[JohnD-EE]

Summary

Adds optional agent and workflow filter arrays to AiWebhookSubscription so admins can scope a subscription to specific entities instead of receiving every event of a given type. Empty arrays preserve current behaviour — existing rows continue delivering as before.

Why

Operators running multiple agents/workflows had only one knob: subscribe to an event type and get it for every entity. That meant either flooding receivers, splitting one logical alert across N near-identical subscriptions, or filtering downstream. This PR closes the gap with two small filter columns and a centralised matching rule.

How it works

Filtering is dimension-specific: an agentIds filter only restricts events that carry an agent ID; a workflowIds filter only restricts workflow-typed events. Setting an agent filter does NOT silence unrelated workflow events. The map at lib/orchestration/webhooks/event-entity-keys.ts is the single source of truth for which payload field carries each entity ID; a coverage test asserts every wired event type is mapped.

Fails closed when a mapped event's payload is missing the expected ID — a scoped sub with a non-empty filter on that dimension does NOT match. Prevents an upstream enrichment bug from leaking events to scoped subscribers.

What landed

• Schema: two String[] @default([]) columns on AiWebhookSubscription + additive migration (add_entity_scope_to_webhook_subscription).
• Dispatcher: lib/orchestration/webhooks/dispatcher.ts runs matchesEntityScope(...) over the result of findMany before scheduling deliveries.
• Payload enrichment: workflow_budget_exceeded now carries workflowId from all four engine call sites, so workflow-typed subs can scope it.
• Validation + API: optional agentIds/workflowIds flow through createWebhookSchema / updateWebhookSchema and the route handlers; 50-entry cap per dimension.
• Admin form: new "Scope" block between Events and Retry policy, two async-search MultiSelects (agents + workflows). Workflow picker filters templates server-side (isTemplate=false) since templates are never event subjects. <FieldHelp> copy explains the dimension-specific rule.
• List table: small Scoped badge with count tooltip when either filter array is non-empty.
• Docs: "Entity-Scoped Subscriptions" section in .context/orchestration/hooks.md; form + table updates in .context/admin/orchestration-webhooks.md.

Tests

• 7 dispatcher tests for the dimension-specific rule (empty filters, agent match, agent miss, workflow-typed event with agent-only filter, etc.) + fail-closed and routing-to-only-matching-sub coverage.
• 10 unit tests for event-entity-keys.ts including a coverage assertion that every entry in WEBHOOK_EVENT_TYPES has a deliberate map entry.
• 4 form tests (Scope section renders, edit-mode prefetch resolves chip labels, empty-scope skips prefetch, workflow loader sets isTemplate=false).
• 3 table tests (Scoped badge with agents, with workflows, hidden when both empty).
• 1 engine test asserting workflow_budget_exceeded carries workflowId end-to-end.

All 4011 tests pass. Validate clean (0 errors). webhook-form.tsx coverage went from 70.6/77.6/73.8/68.2 → 91.9/86.7/85.7/89.2 (all ≥80%).

Test plan

• Pull, run npm run db:migrate:dev — non-destructive additive migration applies.
• Create Sub A: events=[`budget_exceeded`,`workflow_failed`], `agentIds=[agent-X]`, no workflow filter. Sub B: same events, no filters.
• Trigger `budget_exceeded` for agent-X (chat to budget=0). Both A and B get deliveries.
• Trigger `budget_exceeded` for agent-Y. Only B gets a delivery.
• Fail any workflow. Both A and B fire (agent filter doesn't apply to workflow events).
• Add `workflowIds=[workflow-Z]` to A. Fail workflow-Z → both fire. Fail workflow-Q → only B.
• Confirm "Limit to workflows" picker shows no templates.
• Confirm "Scoped" badge appears next to any sub that has filters set.

Backward compatibility

Fully backward compatible. Existing subscription rows default to empty arrays, which the matcher treats as "no constraint". The schema migration is purely additive. No API contract changes for existing fields.

Commits

• `e50259a6` — feat(webhooks): scope event subscriptions to specific agents/workflows
• `fa3bbc98` — feat(webhooks): exclude templates from workflow scope picker
• `52a8c957` — test(webhooks): cover entity-scope form + Scoped badge

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sunrise	Ready	Preview, Comment	May 23, 2026 9:35pm

[JohnD-EE]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.