Event sources and trigger automation

Event sources let the persistent Holaryn host notice work and start a fixed task. Webhooks, folder
changes, repeating timers, and connector delta feeds all use the same durable lifecycle:

Detect a source event.
Normalize its stable ID, cursor, trust, sensitivity, metadata, and payload reference.
Govern it with filters, coalescing, quiet hours, rate limits, and a source-local circuit.
Run the operator-authored task through the selected profile and ordinary approvals.

An event is a signal, not permission. Event metadata is attached as provenance and is not appended
to the task prompt. If a triggered run needs a gated action, hold sends it to Approvals and
cancel denies it.

Add a source

Open Scheduler → Event sources → Add a source. Choose:

Authenticated webhook for CI, home automation, or another HTTP producer.
Folder changes for create, modify, delete, and unambiguous rename events under one local
root. Holaryn stores a content-free reference, relative path, change kind, and byte size.
Repeating timer for an interval signal. Missed intervals coalesce into one event after a
restart.
Connector delta feed for a connector-owned cursor such as mail or calendar. Store the
credential in the secret system and enter only its opaque handle.

Each source has its own dispatch limit and failure circuit. A noisy source cannot consume another
source's allowance.

Add a trigger rule

Choose the source, name the rule, and write the fixed task. You can select a config profile, decide
whether gated actions hold or cancel, add an exact metadata filter, and set a coalescing window.

Example:

Source: CI events
Rule: Investigate main-branch failures
Filter: status equals failed
Coalesce: 120 seconds
Task: Inspect the referenced CI failure, summarize the first actionable cause, and propose a repair. Do not change files.
On gated action: hold for approval

A matching dispatch resembles:

The Linux test job failed while importing holaryn_agent.scheduler.
Most likely cause: the generated package omitted event_sources.py.
Suggested next check: inspect the wheel contents and hatch include rules.
No files were changed.

The exact answer depends on the selected provider and referenced evidence. The source event itself
does not authorize the agent to edit, publish, or send anything.

Send a canonical webhook event

Configure the dedicated webhook token under Settings → Networking or with
HOLARYN_WEBHOOK_TOKEN, then create a webhook source and rule. POST a stable producer event ID,
bounded metadata, and a reference:

curl -X POST http://127.0.0.1:8765/api/hooks/sources/source_ci \
  -H "X-Holaryn-Webhook-Token: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "github-delivery-42",
    "occurred_at": 1800000000,
    "cursor": "42",
    "payload_ref": "github://acme/widget/actions/runs/42",
    "metadata": {
      "status": "failed",
      "branch": "main",
      "workflow": "CI"
    }
  }'

The first accepted delivery returns 202 with its trigger instances. Repeating the same source and
event ID returns 200 with "duplicate": true and does not dispatch a second instance.

Keep raw secrets and large payloads out of source configuration and event metadata. Put credentials
in the secret store and keep data in its owning system; payload_ref tells the run where authorized
resolution can occur.

Health, pause, test, and replay

Source cards show state, cursor, lag, rule count, pending/uncertain/failed deliveries, rate limit,
and last error. Pause source stops new events from dispatching. Resume source also resets a
source-local open circuit. Test source sends a harmless synthetic event through the exact same
filters and delivery lifecycle.

Open Delivery traces to correlate source_id / event_id with its
job:trigger_<instance> run. A crash during dispatch produces an uncertain trace rather than an
automatic retry. Check the correlated run or external target first, then choose Replay delivery
only when repeating the same instance is safe. Replay does not create a new trigger identity and
does not bypass approvals.

Legacy scheduled-job webhooks

POST /api/hooks/<job_id> is still supported and immediately fires an existing scheduled job.
Use canonical source webhooks when the producer supplies event IDs, cursors, metadata filters, or
when you need delivery health and replay traces. See Webhook triggers for
both contracts.

← Previous Encrypted local state Next → Executable extensions

Event sources and trigger automation