feat(surface,sdk): provider-specific event triggers via codegen (#346)

[kjgbot]

Closes #346. Delivered via implement-slice.flow.ts (flows-driven dogfood, mixed codex/claude).

---

Note

Medium Risk
Touches webhook ingress validation and trigger lowering on the event path; mistakes could mis-route or accept bad envelopes, though path authority and fail-closed checks are explicit.

Overview
Adds mapping-driven Slack/GitHub trigger declarations on the surface (slack.mention, github.pull_request, etc.), generated by scripts/generate-triggers.mjs from adapter YAML, plus new @relayflows/surface/triggers exports and docs for flow.on(...) provider subscriptions.

The SDK lowers those sources with webhookTriggerSpec into the existing inbox executor contract (executor name = provider, optional payload pattern) and validates POST /providers/<provider> envelopes via providerInboxEvent before atomic writes to inbox/<provider>/. Generic POST /<name> behavior is unchanged.

Tests cover codegen drift checks, envelope validation, kernel CLI isolation/dedupe, and extended HTTP/daemon flows; docs/evidence/spec-X captures verification logs (full SDK suite still red on sandbox socket EPERM, with targeted provider tests green separately). No kernel production code changes.

^{Reviewed by Cursor Bugbot for commit 5abac69. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 342b491c-f292-498e-8384-e9c1cf866673

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[kjgbot]

maintainability lens — PASS

Maintainability review — PR #351

Concerns

• packages/sdk/src/trigger-executor.ts:14 — webhookTriggerSpec unconditionally emits dedupeKeyTemplate: '{{event.type}}' with the inline comment "The inbox watcher supplies the durable file ID as the event key." A reader sees a {{event.type}} template that would collapse every event of one type into a single run, but the tests at provider-trigger-executor.test.ts:41-49 show dedup is actually driven by the key field on the event envelope (event-1.json vs event-2.json), not by event.type. Either the template is dead metadata (delete it), it is overridden by the kernel (say so and cite the site), or the value should reflect what the watcher really uses (e.g. {{event.key}}). Today three plausible readings all typecheck; six months from now the comment will still assert one thing while the field asserts another.

• packages/sdk/src/trigger-executor.ts:20 — the function is named providerInboxEvent and typed (provider, value) => WebhookFilter. It reads as a factory for an event, but it returns a filter shape. The consumer at serve-webhook.ts:80 reassigns payload = providerInboxEvent(...) and writes the filter to disk as the inbox envelope. Rename to something like canonicalizeProviderEnvelope or split validation from filter production; the current name/return-type mismatch is the exact "implicit contract" this lens flags.

• packages/sdk/src/cli/serve-webhook.ts:79-83 — the error message forwarded on invalid_provider_event is error.message, which will bubble up raw triggers.ts snapshot exceptions ("webhook filter must contain finite, acyclic JSON data", "invalid JSON array property") to public HTTP callers. That leaks the internal filter abstraction through a provider-ingress endpoint. Wrap or map these messages to a stable ingress vocabulary.

• packages/surface/src/provider-trigger.ts:14 — the as ProviderTriggerSource<P, E> cast strengthens filter?: WebhookFilter to a required intersection with {provider, type}. It is only safe because webhook() happens to preserve the filter today; nothing forces that. Consider narrowing webhook()'s return in an overload, or asserting the shape at runtime before the cast.

• scripts/generate-triggers.mjs:70-82 — Slack mention/reaction shorthands are hard-coded in the generator, with a comment justifying the special case but no registration point. When someone adds Discord or Linear next, they'll re-open this file. Consider a per-provider shorthand map colocated with the mapping (or in a small pinned JSON) so the generator stays provider-agnostic. Note this is documented, so it's a note, not a blocker.

Notes

• docs/evidence/spec-X/README.md:14-24 is honest about the 185 failed sandbox tests and pins the socket-EPERM root cause — good practice per AGENTS.md §"Evidence is captured, not narrated". But the HTTP tests are the ones that would fail the ingress if it regressed; there is no unit-level substitute for webhook.test.ts routes provider envelopes... in the passing set. Rerun-in-permissive-env is unavoidable.

• Generated files carry a byte-identical drift guard (check-generated-helpers.mjs) — that is the right safety net.

• The README at packages/surface/src/triggers/README.md explicitly points to flows: event triggers via webhook + inbox watcher — SURFACE §1 harness #301 for the deployment slice; that keeps the boundary honest.

REVIEW_PASSED

[kjgbot]

history lens — PASS

Blockers: none. PR #351 passes the HISTORY lens.

Notes

• The change extends the webhook/inbox implementation introduced by f8b4be51 (feat(surface,sdk,kernel): event triggers via webhook + inbox watcher (#301) #317). packages/sdk/src/trigger-executor.ts, lines 4–15 lowers declarations into the existing executor contract. It does not replace journal persistence or introduce a second deduplication mechanism. I found no reintroduction of deliberately removed behavior recorded in the drive log.
• The provider declarations fit RFC settled decisions gate1: kernel + sdk skeletons (bootstrap relayflow output) #1 and drive: WP-13: Fix SDK test failures from sandbox environment gaps #13: scripts/generate-triggers.mjs, lines 39–48 reads upstream adapter mappings, while the generated surface lowers to existing primitives. The diff introduces neither provider SDKs inside the kernel nor a new integration step type.
• Commit 5abac69d says “provider-specific event triggers via codegen”; its body is empty. That feature description matches the diff and makes no test-success claim. docs/evidence/spec-X/README.md, lines 18–24 explicitly acknowledges the unsuccessful full-suite attempt and distinguishes the separately captured provider tests.

Concerns — nonblocking

• The HTTP/daemon path still needs successful execution in an environment permitting local sockets. The supplied evidence discloses that limitation; this review does not independently certify those tests.
• docs/evidence/spec-X/sdk.txt, lines 1–6 points to a machine-local temporary transcript. Persisting the complete log would make the evidence portable.
• packages/surface/src/triggers/README.md, lines 37–60 documents normalized ingress, one RunSpec per provider inbox, and deployment work deferred to flows: event triggers via webhook + inbox watcher — SURFACE §1 harness #301. These are disclosed scope limits, not evidence of a newly introduced RFC contradiction.

REVIEW_PASSED

[kjgbot]

structure lens — MISSING

[kjgbot]

🎯 review-swarm: FAILED (M:pass H:pass S:missing)

Lens transcripts posted as sibling comments above.