Event automations

Nookins automations subscribe to one versioned public event and start one bounded, durable agent turn. They are configuration, not free-form scripts: unknown events, versions, filters, agents, or delivery routes make configuration activation fail.

Configuration

Create config/automations.d/investigate_download_failure.yaml:

enabled: true
when:
  event: job.failed
  version: 1
  filters:
    job_kind: social_download
    will_retry: false
run:
  agent: main
  prompt: >
    Investigate the failed media job and report the actionable result.
delivery:
  route: owner_dm
limits:
  cooldown: 10m
  max_runs_per_hour: 3

delivery may be omitted for an internal result. External delivery always uses a named route; raw account and conversation identifiers are not accepted. Both rate limits are explicit, positive, durable across restarts, and scoped to the automation ID.

The configured prompt is followed by a bounded JSON event envelope labeled as untrusted data. Payload strings are never interpolated into the instruction or treated as instructions.

Discover and validate events

nookins events list
nookins events inspect job.failed
nookins events docs
nookins automations validate

The generated event reference is authoritative for event names, versions, automation eligibility, sensitivity, volume, and filterable fields. Filters are exact equality checks with registry-validated types.

Dry-run an automation

Create an event envelope without private production data:

{
  "sequence": 0,
  "id": "00000000-0000-4000-8000-000000000001",
  "schema_version": 1,
  "kind": "job.failed",
  "timestamp": "2026-08-20T00:00:00Z",
  "source": "operator_test",
  "account_id": null,
  "chat_id": null,
  "agent_id": null,
  "payload": {
    "job_kind": "social_download",
    "will_retry": false
  }
}

nookins automations test investigate_download_failure --event event.json

The result reports whether it matched, its selected agent and redacted route, effective limits, non-owner authority, and a redacted prompt preview. A dry run does not create a task, consume rate-limit state, or deliver output. The primary agent has the equivalent Nookins.automation.test tool.

Common recipes

Notify after a terminal job failure

Subscribe to job.failed and filter will_retry: false plus the exact job_kind. Use a named owner route for delivery. Avoid reacting to each retry.

React to a committed workspace entity

Subscribe to workspace.entity.committed. The stable filterable field is workspace_id; inspect the authorized workspace record during the resulting turn rather than embedding private content in automation configuration.

Rate-limit repeated failures

Use a non-zero cooldown to suppress bursts and max_runs_per_hour as a hard upper bound. Suppressed attempts remain visible in automation execution history with cooldown or max_runs_per_hour as the reason.

Inspect execution and suppression

Use Nookins.automation.inspect from the primary agent's direct owner session, or inspect operations in the local console. Records distinguish executing, delivered, ambiguous, and suppressed acceptance. An ambiguous external effect is not replayed automatically.

Disable safely

Set enabled: false by hand, or have the primary agent prepare an automation.disable proposal. Disabling blocks new acceptance. Already accepted durable work retains the exact automation revision that accepted it.

Migrate an event version

Event versions are exact contracts. Before changing when.version, inspect the new event definition, update filter fields and types, run nookins automations validate, and dry-run a representative envelope. Nookins does not alias renamed events or versions.

Authority and recursion

Automation turns use a dedicated non-owner principal with invocation origin automation. They cannot acquire custodian authority or access Nookins administration, owner-only features or add-ons, secrets, host maintenance, or approval authority—even when the target is the primary agent. Automation-originated terminal tasks and background agent jobs do not trigger another automation in v1.