Skip to main content
A trigger adapter turns one wake-up mechanism into an agent run. The lousho/triggers subpath is the extension point for your own mechanism (TriggerAdapter, TriggerRegistry) plus a few helpers shared with channels and schedules: the WebhookAuth shapes, verifySlackSignature() and parseCronExpression(). The built-in webhook, Slack and cron adapters were removed; see Migrating from triggers.

Choosing between triggers, channels and schedules

The TriggerAdapter interface

listen takes both agent and onEvent on purpose. agent is the plain “prompt in, text out” surface, and onEvent is the entry point the adapter calls when its trigger fires: a simple caller passes (input) => agent.send(input), while a caller with checkpointing, approval gates or abort control passes an onEvent that wraps all of that. Call stop() on the returned handle to shut the adapter down. Reply semantics differ per adapter. An adapter whose reply is the open request (a webhook) has no reply(), one with no caller waiting (a clock) hands the result elsewhere, and one with an out-of-band reply channel (chat) implements reply(). Write your own adapter by returning a handle from listen:
TriggerRegistry keeps adapters by name: register(name, adapter), registerMany(), get(), has(), list(), getAll(), unregister(), clear() and size(). globalTriggerRegistry is a shared instance.

Webhook authentication

The WebhookAuth shapes are the reference for webhookChannel({ auth }) (see Channels). checkWebhookAuth() and assertValidWebhookAuth() are exported for your own handler.
HMAC options: header (default x-signature-256), algorithm (sha256 or sha1, default sha256), prefix (default sha256=; '' for a bare digest), timestampHeader and toleranceSeconds (a timestamp may also be at most a minute ahead of local time). Signatures and bearer tokens are compared in constant time. A request that fails authentication gets a generic 401 {"error":"Unauthorized"} - the response never says which check failed. An invalid auth throws LOUSHO_TRIGGER_INVALID. Serve webhooks over HTTPS (terminate TLS in front of the server) so tokens and payloads are not sent in clear text.

Slack request signatures

slackChannel() verifies every request for you (see Slack in Channels). For your own handler (slash commands, interactivity), verify the RAW body with verifySlackSignature(): HMAC-SHA256 over v0:{X-Slack-Request-Timestamp}:{raw body}, compared in constant time with X-Slack-Signature (v0=<hex>). Requests more than five minutes old, or more than a minute ahead of local time, are rejected (the timestamp is in seconds, as Slack sends it). See Slack’s documentation.

Cron expressions

defineSchedule() with startSchedules() runs cron (see Schedules). parseCronExpression(expr, timezone) and CronExpressionError are exported if you need to validate an expression or compute the next fire time with .nextRun(after). Supported syntax: *, lists (1,15), ranges (1-5), steps (*/15, 10-40/10), month names (JAN) and weekday names (MON), with 0 and 7 both meaning Sunday, plus the @hourly, @daily (or @midnight), @weekly, @monthly and @yearly (or @annually) shortcuts. As in classic cron, when both day-of-month and day-of-week are restricted a day matches if either does. An invalid expression throws a CronExpressionError naming the field and showing a valid example. Around daylight-saving changes, a fixed-hour job whose time does not exist (spring forward, e.g. 30 2 * * *) runs once at the first instant after the gap (03:00) instead of being skipped for the day, and a time that happens twice (fall back) fires once; an every-hour schedule keeps firing hourly.

Abort listeners

spec.abortListeners cancels queued or running runs when a watched trigger’s event matches. Each entry names a webhook or channel trigger, a when expression over the incoming event, a match expression pairing the trigger event with a run’s own event, and a scope of queued, running or both:
when and match use the same safe expression grammar as flow conditions (see Flows); variable references are checked when the spec parses and unknown names resolve to undefined at runtime. At most 20 listeners are allowed per spec. Studio’s trigger host evaluates them on every inbound webhook and channel event, before the event’s own filter and dispatch, so the delivering run can never cancel itself; a cancelled run logs Run cancelled by abort listener <id> and its webhook response lists the cancelled run keys under cancelled.