@relayflows/surface 2.0.9 → 2.0.10

package/src/helpers/ramp.ts

@@ -0,0 +1,12 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { providerClient } from "@relayfile/relay-helpers";
+import type { RelayClientOptions } from "@relayfile/relay-helpers/transport";
+const rampClient = (options: RelayClientOptions) => providerClient("ramp", options);
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type RampHelper = JournalHelper<ReturnType<typeof rampClient>>;
+
+export const createRampHelper = (dispatch: EffectDispatcher): RampHelper =>
+  bindHelper("ramp", rampClient, dispatch);

package/src/helpers/recall.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { recallClient } from "@relayfile/relay-helpers";
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type RecallHelper = JournalHelper<ReturnType<typeof recallClient>>;
+
+export const createRecallHelper = (dispatch: EffectDispatcher): RecallHelper =>
+  bindHelper("recall", recallClient, dispatch);

package/src/helpers/reddit.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { redditClient } from "@relayfile/relay-helpers";
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type RedditHelper = JournalHelper<ReturnType<typeof redditClient>>;
+
+export const createRedditHelper = (dispatch: EffectDispatcher): RedditHelper =>
+  bindHelper("reddit", redditClient, dispatch);

package/src/helpers/redis.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { redisClient } from "@relayfile/relay-helpers";
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type RedisHelper = JournalHelper<ReturnType<typeof redisClient>>;
+
+export const createRedisHelper = (dispatch: EffectDispatcher): RedisHelper =>
+  bindHelper("redis", redisClient, dispatch);

package/src/helpers/s3.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { s3Client } from "@relayfile/relay-helpers";
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type S3Helper = JournalHelper<ReturnType<typeof s3Client>>;
+
+export const createS3Helper = (dispatch: EffectDispatcher): S3Helper =>
+  bindHelper("s3", s3Client, dispatch);

package/src/helpers/salesforce.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { salesforceClient } from "@relayfile/relay-helpers";
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type SalesforceHelper = JournalHelper<ReturnType<typeof salesforceClient>>;
+
+export const createSalesforceHelper = (dispatch: EffectDispatcher): SalesforceHelper =>
+  bindHelper("salesforce", salesforceClient, dispatch);

package/src/helpers/segment.ts

@@ -0,0 +1,9 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { bindHelper, type EffectDispatcher, type JournalHelper, type UnavailableHelper } from "../effect-transport.js";
+
+export type SegmentHelper = UnavailableHelper;
+
+export const createSegmentHelper = (dispatch: EffectDispatcher): SegmentHelper =>
+  bindHelper("segment", undefined, dispatch);

package/src/helpers/sendgrid.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { sendgridClient } from "@relayfile/relay-helpers";
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type SendgridHelper = JournalHelper<ReturnType<typeof sendgridClient>>;
+
+export const createSendgridHelper = (dispatch: EffectDispatcher): SendgridHelper =>
+  bindHelper("sendgrid", sendgridClient, dispatch);

package/src/helpers/sharepoint.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { sharepointClient } from "@relayfile/relay-helpers";
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type SharepointHelper = JournalHelper<ReturnType<typeof sharepointClient>>;
+
+export const createSharepointHelper = (dispatch: EffectDispatcher): SharepointHelper =>
+  bindHelper("sharepoint", sharepointClient, dispatch);

package/src/helpers/shopify.ts

@@ -0,0 +1,9 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { bindHelper, type EffectDispatcher, type JournalHelper, type UnavailableHelper } from "../effect-transport.js";
+
+export type ShopifyHelper = UnavailableHelper;
+
+export const createShopifyHelper = (dispatch: EffectDispatcher): ShopifyHelper =>
+  bindHelper("shopify", undefined, dispatch);

package/src/helpers/shortcut.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { shortcutClient } from "@relayfile/relay-helpers";
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type ShortcutHelper = JournalHelper<ReturnType<typeof shortcutClient>>;
+
+export const createShortcutHelper = (dispatch: EffectDispatcher): ShortcutHelper =>
+  bindHelper("shortcut", shortcutClient, dispatch);

package/src/helpers/slack.ts

@@ -0,0 +1,16 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import type { SlackHelper as RuntimeSlackHelper } from "../slack.js";
+
+/** Generated from the pinned Slack OpenAPI fragments in scripts/slack-message-schema.json. */
+export type SlackBlock = { type: string; [key: string]: unknown; };
+export type SlackAttachment = { [key: string]: unknown; };
+
+/** Adapter argument shapes over the journal-backed Slack dispatcher. */
+export interface SlackHelper {
+  post(...args: Parameters<RuntimeSlackHelper["post"]>): ReturnType<RuntimeSlackHelper["post"]>;
+  dm(user: string, text: string): ReturnType<RuntimeSlackHelper["dm"]>;
+  reply(channel: string, threadTs: string, text: string): ReturnType<RuntimeSlackHelper["reply"]>;
+  react(channel: string, messageTs: string, emoji: string): ReturnType<RuntimeSlackHelper["react"]>;
+}

package/src/helpers/stripe.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { stripeClient } from "../helper-clients.js";
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type StripeHelper = JournalHelper<ReturnType<typeof stripeClient>>;
+
+export const createStripeHelper = (dispatch: EffectDispatcher): StripeHelper =>
+  bindHelper("stripe", stripeClient, dispatch);

package/src/helpers/teams.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { teamsClient } from "@relayfile/relay-helpers";
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type TeamsHelper = JournalHelper<ReturnType<typeof teamsClient>>;
+
+export const createTeamsHelper = (dispatch: EffectDispatcher): TeamsHelper =>
+  bindHelper("teams", teamsClient, dispatch);

package/src/helpers/telegram.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { telegramClient } from "@relayfile/relay-helpers";
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type TelegramHelper = JournalHelper<ReturnType<typeof telegramClient>>;
+
+export const createTelegramHelper = (dispatch: EffectDispatcher): TelegramHelper =>
+  bindHelper("telegram", telegramClient, dispatch);

package/src/helpers/webhook-server.ts

@@ -0,0 +1,9 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { bindHelper, type EffectDispatcher, type JournalHelper, type UnavailableHelper } from "../effect-transport.js";
+
+export type WebhookServerHelper = UnavailableHelper;
+
+export const createWebhookServerHelper = (dispatch: EffectDispatcher): WebhookServerHelper =>
+  bindHelper("webhook-server", undefined, dispatch);

package/src/helpers/x.ts

@@ -0,0 +1,9 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { bindHelper, type EffectDispatcher, type JournalHelper, type UnavailableHelper } from "../effect-transport.js";
+
+export type XHelper = UnavailableHelper;
+
+export const createXHelper = (dispatch: EffectDispatcher): XHelper =>
+  bindHelper("x", undefined, dispatch);

package/src/helpers/zendesk.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-helpers.mjs — do not edit.
+// Run `npm run gen --prefix packages/surface` from the repository root.
+
+import { zendeskClient } from "@relayfile/relay-helpers";
+import { bindHelper, type EffectDispatcher, type JournalHelper } from "../effect-transport.js";
+
+export type ZendeskHelper = JournalHelper<ReturnType<typeof zendeskClient>>;
+
+export const createZendeskHelper = (dispatch: EffectDispatcher): ZendeskHelper =>
+  bindHelper("zendesk", zendeskClient, dispatch);

package/src/index.ts

@@ -7,17 +7,40 @@ export type {
   WorkerSummary,
   CloudHelper,
 } from "./cloud.js";
-export type { AgentOptions, AgentResult, Ctx } from "./context.js";
+export type { AgentOptions, AgentResult, LlmOptions, Ctx } from "./context.js";
 export {
   COMPLETION_REASONS,
   RUN_COMPLETION_REASONS,
   type CompletionReason,
   type RunCompletionReason,
+  type FlowCompletionReason,
 } from "./completion.js";
-export type { Step } from "./step.js";
+export type {
+  Step,
+  NamedGate,
+  ReferencesInputNamedGate,
+  SubprocessNamedGate,
+  WordCountBoundsNamedGate,
+  RegexMatchNamedGate,
+} from "./step.js";
 export {
   flow,
   type FlowHandle,
+  type TriggeredFlowHandle,
   type FlowHeader,
-  type NamedAgentDeclaration,
 } from "./flow.js";
+export {
+  flowRunWritebackIdempotency,
+  type SlackHelper,
+  type SlackReceipt,
+  type SlackBlock,
+  type SlackAttachment,
+  type SlackPostMessage,
+  type SlackPostOptions,
+} from "./slack.js";
+export type { Helpers } from "./helpers/index.js";
+export type { MemoryHelper, MemoryFinding, MemoryRecallOptions, HistoryEntry, TrajectoryEntry } from "./memory.js";
+export { webhook, type TriggerSource, type WebhookFilter, type WebhookValue } from "./triggers.js";
+export * from "./triggers/index.js";
+export type { ProviderTriggerSource } from "./provider-trigger.js";
+export type { PluginMethod, PluginPrimitive } from './plugin-contract.js';

package/src/memory.ts

@@ -0,0 +1,20 @@
+import type { HistoryEntry, SearchOptions, TrajectoryEntry } from "ai-hist";
+
+export type { HistoryEntry, TrajectoryEntry } from "ai-hist";
+/** Reads cannot widen the current flow's script scope. */
+export type MemoryRecallOptions = Omit<SearchOptions, "project">;
+export interface MemoryFinding {
+  question: string;
+  chosen: string;
+  reasoning: string;
+  alternatives?: string[];
+}
+
+export interface MemoryHelper {
+  /** Local script memory read; does not journal a step. */
+  recall(query: string, options?: MemoryRecallOptions): Promise<HistoryEntry[]>;
+  /** Best matching decision trajectory, or an empty array. No journal step. */
+  why(task: string): Promise<TrajectoryEntry[]>;
+  /** Reserved for the journal-backed write slice; currently refuses. */
+  learn(finding: MemoryFinding): Promise<void>;
+}

package/src/plugin-contract.ts

@@ -0,0 +1,5 @@
+import type { Step } from './step.js';
+
+/** Plugins augment Ctx in @relayflows/surface; no catch-all index signature. */
+export type PluginMethod<Args, Output = unknown> = (args: Args) => Step<Output>;
+export type PluginPrimitive = 'run' | 'llm' | 'agent' | 'effect' | 'wait';

package/src/provider-trigger.ts

@@ -0,0 +1,26 @@
+import { webhook, type TriggerSource, type WebhookFilter } from "./triggers.js";
+
+/** A provider inbox subscription over an envelope's type and payload. */
+export interface ProviderTriggerSource<Provider extends string, Event extends string> extends TriggerSource {
+  readonly name: Provider;
+  readonly filter: WebhookFilter & { readonly provider: Provider; readonly type: Event };
+}
+
+/** Shared implementation for generated provider declarations. */
+export function providerTrigger<P extends string, E extends string>(
+  provider: P, event: E, payload?: WebhookFilter,
+): ProviderTriggerSource<P, E> {
+  if (typeof event !== "string" || event.length === 0) throw new TypeError("provider event type must not be empty");
+  // Validate separately so an invalid payload cannot become a scalar filter leaf.
+  const filter = webhook(provider, payload).filter;
+  return webhook(provider, {
+    provider, type: event, ...(filter === undefined ? {} : { payload: filter }),
+  }) as ProviderTriggerSource<P, E>;
+}
+
+export function triggerArgument(value: string, name: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${name} must be a nonempty string`);
+  }
+  return value;
+}

package/src/runtime.ts

@@ -3,5 +3,13 @@ export {
   type AuthoredFlowDefinition,
   type FlowBody,
   type FlowHandle,
+  type TriggerHandler,
+  type TriggeredFlowHandle,
   type ReadonlyFlowHeader,
 } from "./flow.js";
+export { slackPostBody } from "./slack.js";
+
+export { createHelpers } from "./helpers/index.js";
+export { helperProviders } from "./helpers/providers.js";
+export { helperClients } from "./helpers/clients.js";
+export { invokeHelper, type HelperCall } from "./effect-transport.js";

package/src/slack.ts

@@ -0,0 +1,47 @@
+import type { Step } from "./step.js";
+import type { SlackAttachment, SlackBlock } from "./helpers/slack.js";
+
+export type { SlackAttachment, SlackBlock } from "./helpers/slack.js";
+
+/** Structured message content. Text supplies the notification/accessibility fallback. */
+export interface SlackPostMessage {
+  text?: string;
+  blocks?: SlackBlock[];
+  attachments?: SlackAttachment[];
+}
+
+export interface SlackPostOptions extends Omit<SlackPostMessage, "text"> {
+  replyTo?: string;
+}
+
+export interface SlackReceipt {
+  channel: string;
+  ts: string;
+  ref: string;
+}
+
+/** Slack writeback helpers; every call is a journal-backed effect. */
+export interface SlackHelper {
+  post(channel: string, text: string | SlackPostMessage, opts?: SlackPostOptions): Step<SlackReceipt>;
+  dm(user: string, text: string): Step<{ user: string; ts: string }>;
+  reply(channel: string, threadTs: string, text: string): Step<SlackReceipt>;
+  react(channel: string, messageTs: string, emoji: string): Step<void>;
+}
+
+/** Normalize both authoring forms to the adapter's JSON writeback body. */
+export function slackPostBody(text: string | SlackPostMessage, opts?: SlackPostOptions): SlackPostMessage & { parentRef?: string } {
+  const message = typeof text === "string" ? { text } : text;
+  const blocks = opts?.blocks ?? message.blocks;
+  const attachments = opts?.attachments ?? message.attachments;
+  return {
+    ...(message.text === undefined ? {} : { text: message.text }),
+    ...(blocks === undefined ? {} : { blocks }),
+    ...(attachments === undefined ? {} : { attachments }),
+    ...(opts?.replyTo ? { parentRef: opts.replyTo } : {}),
+  };
+}
+
+/** Stable across attempts; deliberately independent of process-tick ordinals. */
+export function flowRunWritebackIdempotency(runId: string, stepId: string): string {
+  return `${runId}:${stepId}`;
+}

package/src/step.ts

@@ -1,5 +1,56 @@
 /** A journal-backed step result with its postfix verification gate. */
 export interface Step<T> extends PromiseLike<T> {
-  /** Fail the step with `verification_failed` when the predicate is false. */
+  /**
+   * Attach a named data gate to this step's `verification:` field. The gate is
+   * lowered by the SDK into a slice-P journal-honest check that survives
+   * replay — its shape is data, not code, so covenant 1 (journal-as-truth)
+   * holds. See `packages/sdk/src/named-gates.ts` for the enforcement.
+   */
+  gate(config: NamedGate): Step<T>;
+  /**
+   * Predicate gates cannot be journaled — the JavaScript closure would not
+   * survive replay — so the executor refuses this branch with
+   * `unsupported_gate`. Use a `NamedGate` config-object gate above, or the
+   * declarative `verification:` field on the compiled step spec, when you
+   * need journal-honest verification.
+   */
   gate(predicate: (value: T) => boolean, because?: string): Step<T>;
 }
+
+/**
+ * Slice-P named data gates the authored surface can attach postfix via
+ * `.gate(config)`. The SDK's named-gate lowering enforces these exactly (see
+ * `packages/sdk/src/named-gates.ts`); the shapes here are the surface-visible
+ * subset kept in sync with `NamedDataGate` in the SDK spec.
+ */
+export type NamedGate =
+  | ReferencesInputNamedGate
+  | SubprocessNamedGate
+  | WordCountBoundsNamedGate
+  | RegexMatchNamedGate;
+
+export interface ReferencesInputNamedGate {
+  type: 'references_input';
+  input_key: string;
+  in_output_at?: Array<string | number>;
+}
+
+export interface SubprocessNamedGate {
+  type: 'subprocess_gate';
+  command: string;
+  from_output?: Array<string | number>;
+}
+
+export interface WordCountBoundsNamedGate {
+  type: 'word_count_bounds';
+  min?: number;
+  max?: number;
+}
+
+export interface RegexMatchNamedGate {
+  type: 'regex_match';
+  pattern: string;
+  /** Only i, m, and s; evaluated by a non-backtracking RE2 engine. */
+  flags?: string;
+  in_output_at?: Array<string | number>;
+}

package/src/triggers/README.md

@@ -0,0 +1,75 @@
+# Provider event triggers
+
+```ts
+import { flow, slack, github } from '@relayflows/surface';
+
+export default flow('triage')
+  .on(slack.mention('C123'), async (f, event) => { f.done('success'); })
+  .on(slack.reaction('eyes'), async (f, event) => { f.done('success'); })
+  .on(github.pull_request('opened'), async (f, event) => { f.done('success'); });
+```
+
+Provider namespaces also export from `@relayflows/surface/triggers` and
+`@relayflows/surface/triggers/slack` (or `/github`). Declarations are immutable
+webhook sources: their executor/inbox name is the provider, and their filter
+matches the provider, event type, and requested payload fields. Register those
+provider names in `flows.json`'s `executors` array for preflight.
+
+`slack.mention(channel)` subscribes to Slack's `app_mention` event;
+`slack.reaction(emoji)` subscribes to `reaction_added`. Arguments match provider
+values exactly: use the channel ID and reaction name from the incoming event.
+`github.pull_request(action)` filters `payload.action`; omitting the action
+accepts every pull request event. Upstream mappings do not declare action enums,
+so the action parameter is a string. Other generated methods accept an optional
+recursive payload filter, for example `github.push({ ref: 'refs/heads/main' })`.
+
+The receiver accepts `POST /providers/slack` with this JSON:
+
+```json
+{"type":"app_mention","payload":{"channel":"C123","text":"Please review"}}
+```
+
+It writes `{ "provider": "slack", "type": "app_mention", "payload": {...} }`
+atomically to `inbox/slack/<id>.json`. The path supplies the provider; a conflicting
+provider in the body or unknown event type is rejected. `payload` is the provider
+event body (Slack's inner `event` object). The event names are the exact mapping
+keys; dots and hyphens become underscores only in TypeScript method names.
+Ingress expects this envelope, not a raw vendor HTTP delivery. Signature
+verification and public ingress remain part of the deployment work tracked in
+#301. Generic `POST /<name>` retains its existing arbitrary-JSON contract.
+
+The SDK's `webhookTriggerSpec(id, source)` lowers a declaration to `TriggerSpec`
+for `compileSpec`/`toKernelSpec`. Provision the resulting RunSpec in
+`triggers/<provider>.json`, with executable steps, as in the existing webhook
+executor. The watcher applies the generated filters, journals matching events,
+deduplicates by inbox file ID, and archives consumed events. For example:
+
+```ts
+import { compileSpec, toKernelSpec, webhookTriggerSpec } from '@relayflows/sdk';
+import { slack } from '@relayflows/surface';
+
+const binding = toKernelSpec(compileSpec({
+  version: '0.1.0', name: 'mentions',
+  triggers: [webhookTriggerSpec('mention', slack.mention('C123'))],
+  steps: [{ id: 'ack', type: 'deterministic', command: 'printf accepted' }],
+})); // Write binding as JSON to triggers/slack.json before ingress starts.
+```
+
+Each provider inbox still binds one RunSpec. This extends E's declaration and
+inbox contract; deploying TypeScript handler bodies remains the separate #301
+binding step.
+
+Generation requires the SDK's development dependencies. The default input is
+the mapping YAML shipped in the pinned `@relayfile/adapter-core` dependency
+(currently Slack and GitHub). A checkout supplies additional providers:
+
+```sh
+node scripts/generate-triggers.mjs
+node scripts/generate-triggers.mjs --check
+node scripts/generate-triggers.mjs --adapters-dir /path/to/relayfile-adapters
+```
+
+The generator reads `packages/core/mappings/*.mapping.yaml`, then each adapter's
+`packages/<adapter>/*.mapping.yaml`; adapter-local mappings take precedence.
+Only adapters with a nonempty `webhooks:` section produce modules. It never
+imports or executes adapter code. Rebuild the surface and SDK after regeneration.

package/src/triggers/github.ts

@@ -0,0 +1,19 @@
+// GENERATED by scripts/generate-triggers.mjs — do not edit.
+
+import { providerTrigger, triggerArgument } from "../provider-trigger.js";
+import type { WebhookFilter } from "../triggers.js";
+
+export const github = Object.freeze({
+  issues(filter?: WebhookFilter) {
+    return providerTrigger("github", "issues", filter);
+  },
+  pull_request(action?: string) {
+    return providerTrigger("github", "pull_request", action === undefined ? undefined : { action: triggerArgument(action, "action") });
+  },
+  pull_request_review(filter?: WebhookFilter) {
+    return providerTrigger("github", "pull_request_review", filter);
+  },
+  push(filter?: WebhookFilter) {
+    return providerTrigger("github", "push", filter);
+  },
+});

package/src/triggers/index.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/generate-triggers.mjs — do not edit.
+
+export { github } from "./github.js";
+export { slack } from "./slack.js";
+
+/** Exact upstream event names, plus the generated Slack mention shorthand. */
+export const providerEventTypes = Object.freeze({
+  "github": Object.freeze(["issues","pull_request","pull_request_review","push"] as const),
+  "slack": Object.freeze(["app_mention","message","reaction_added"] as const),
+});

package/src/triggers/slack.ts

@@ -0,0 +1,19 @@
+// GENERATED by scripts/generate-triggers.mjs — do not edit.
+
+import { providerTrigger, triggerArgument } from "../provider-trigger.js";
+import type { WebhookFilter } from "../triggers.js";
+
+export const slack = Object.freeze({
+  message(filter?: WebhookFilter) {
+    return providerTrigger("slack", "message", filter);
+  },
+  reaction_added(filter?: WebhookFilter) {
+    return providerTrigger("slack", "reaction_added", filter);
+  },
+  mention(channel: string) {
+    return providerTrigger("slack", "app_mention", { channel: triggerArgument(channel, "channel") });
+  },
+  reaction(emoji: string) {
+    return providerTrigger("slack", "reaction_added", { reaction: triggerArgument(emoji, "emoji") });
+  },
+});

package/src/triggers.ts

@@ -0,0 +1,49 @@
+export type WebhookValue = null | boolean | number | string
+  | readonly WebhookValue[] | { readonly [key: string]: WebhookValue };
+
+/** Recursive object subset; array and scalar leaves match exactly. */
+export type WebhookFilter = { readonly [key: string]: WebhookValue };
+
+export interface TriggerSource {
+  readonly kind: "webhook";
+  readonly name: string;
+  readonly filter?: WebhookFilter;
+}
+
+/** Plain, immutable data. Constructing a source opens no receiver. */
+export function webhook(name: string, filter?: WebhookFilter): TriggerSource {
+  if (typeof name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(name)) {
+    throw new TypeError("webhook name must be 1-128 letters, digits, underscores or hyphens, starting with a letter or digit");
+  }
+  if (filter === undefined) return Object.freeze({ kind: "webhook", name });
+  if (filter === null || typeof filter !== "object" || Array.isArray(filter)) {
+    throw new TypeError("webhook filter must be a JSON object");
+  }
+  return Object.freeze({ kind: "webhook", name, filter: snapshot(filter) as WebhookFilter });
+}
+
+function snapshot(value: unknown, ancestors = new Set<object>()): WebhookValue {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value !== "object" || value === null || ancestors.has(value)) {
+    throw new TypeError("webhook filter must contain finite, acyclic JSON data");
+  }
+  const array = Array.isArray(value);
+  if (!array && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError("webhook filter must contain plain JSON objects");
+  }
+  ancestors.add(value);
+  const entries: [string, WebhookValue][] = [];
+  for (const key of Reflect.ownKeys(value)) {
+    if (array && key === "length") continue;
+    const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
+    if (typeof key !== "string" || !descriptor.enumerable || !("value" in descriptor)) {
+      throw new TypeError("webhook filter must contain JSON data properties");
+    }
+    if (array && !/^(0|[1-9][0-9]*)$/.test(key)) throw new TypeError("invalid JSON array property");
+    entries.push([key, snapshot(descriptor.value, ancestors)]);
+  }
+  ancestors.delete(value);
+  if (array && entries.length !== value.length) throw new TypeError("webhook filter arrays must not be sparse");
+  return Object.freeze(array ? entries.map(([, item]) => item) : Object.fromEntries(entries));
+}