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
TheWebhookAuth shapes are the reference for webhookChannel({ auth }) (see Channels). checkWebhookAuth() and assertValidWebhookAuth() are exported for your own handler.
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.