automations

# Automations ## Rule Automations are the user-facing umbrella for agent-executed tasks that fire in response to events or on a cron schedule. **Scheduled** and **Event** are the two trigger types. Each automation is a markdown resource under `jobs/` with YAML frontmatter describing when and how it fires, and a body containing natural-language instructions the agent follows. Recurring Jobs is the legacy name and API for scheduled automations. `manage-jobs`, `jobs/`, and `/agent#jobs` remain stable compatibility surfaces. Use `manage-automations` for new personal or organization automations, including per-automation model overrides and MCP allowlists. Keep `manage-jobs` for existing schedule-only integrations and delivery metadata. ## The Two Trigger Types | Type | Fires when | Key field | | ---------- | ----------------------------------------------- | ------------------- | | `schedule` | Cron expression matches (same as recurring jobs) | `schedule` (cron) | | `event` | A matching event is emitted on the event bus | `event` (event name) | Event triggers can optionally include a `condition` -- a natural-language string evaluated by Haiku against the event payload before dispatch. If the condition does not match, the automation is skipped. ## How It Works 1. User asks the agent to create an automation (or uses the app's Automations page in Settings, `/settings/automations`; open it with `open-settings-page` page `automations`). 2. Agent calls `manage-automations` with `action=list-events` to discover available events. 3. Agent calls `manage-automations` with `action=define` to write a `jobs/<name>.md` resource. 4. The trigger dispatcher subscribes to the event on the bus. 5. When the event fires, the dispatcher loads all matching triggers, enforces owner and organization scope, and evaluates conditions via Haiku. 6. Event and cron acquisition converge on the shared background-automation runner, which validates identity, resolves the configured model and MCP allowlist, runs the agent loop, handles continuation and delivery, and records usage. 7. Status (`lastRun`, `lastStatus`, `lastError`) is written back to the resource frontmatter. Trigger acquisition stays separate by design: the scheduler decides when a cron expression is due, while the event dispatcher matches event names, owners, and conditions. Everything after a trigger is accepted uses the same execution lifecycle. ## Markdown Format ```yaml --- schedule: "" enabled: true triggerType: event event: calendar.booking.created condition: "attendee email ends with @example.com" mode: agentic domain: calendar createdBy: user@example.com runAs: creator --- Send a Slack message to #sales with the booking details. Use the web-request tool with ${keys.SLACK_WEBHOOK}. ``` ### Frontmatter Fields | Field | Type | Purpose | | ------------- | ------------------------------ | ------------------------------------------------------ | | `schedule` | `string` | Cron expression; new scheduled automations default to once per hour (`0 * * * *`) when omitted | | `enabled` | `boolean` | Whether the automation is active | | `triggerType` | `"schedule" \| "event"` | How the automation fires | | `event` | `string?` | Event name to subscribe to (event triggers) | | `condition` | `string?` | Natural-language condition evaluated before dispatch | | `mode` | `"agentic"` | Full agent loop (only supported mode; `"deterministic"` was removed — never implemented, rejected at define time) | | `model` | `string?` | Override the model for this trigger's agent loop | | `reasoningEffort` | `string?` | Override reasoning effort for this trigger's model; omitted uses the model's default | | `domain` | `string?` | Grouping tag (mail, calendar, clips, etc.) | | `createdBy` | `string?` | Creator email; required for organization event automations | | `orgId` | `string?` | Organization scope | | `runAs` | `"creator" \| "shared"` | Execution identity; trigger-aware automations use `creator` | | `mcpTools` | `string[]?` | Exact MCP tool allowlist for this automation | | `lastRun` | `string?` | ISO timestamp of last execution | | `lastStatus` | `string?` | `success`, `error`, `running`, `skipped`, or `paused` | | `lastError` | `string?` | The real cause of the last failed run | | `lastErrorCode` | `string?` | Typed code of the last failure (see Failure handling) | | `consecutiveFailures` | `number?` | Run of identical `lastErrorCode` failures | | `pausedReason` | `string?` | Set with `enabled: false` when the framework paused it | | `pausedAt` | `string?` | ISO timestamp of that pause | ## Agent Tools All automation operations are accessed through a single `manage-automations` tool with an `action` parameter: | Action | Purpose | | ------------- | -------------------------------------------------------------------- | | `list-events` | Discover all registered events with descriptions and payload schemas | | `list` | List all automations with status, filter by domain or enabled | | `define` | Create a new automation (name, trigger type, event, condition, body) | | `update` | Update an existing automation (enabled, condition, body) | | `delete` | Delete an automation (always confirm with user first) | | `fire-test` | Emit a `test.event.fired` event to validate automations | | `run-now` | Run one automation immediately with its real actions and side effects | Additional tool: `web-request` — outbound HTTP with `${keys.NAME}` substitution. `manage-automations` accepts personal or organization scope and supports `model`, `reasoning_effort`, and `mcpTools` on define/update. An MCP allowlist is enforced, not advisory: every named tool must resolve in the creator's request context or the run fails clearly, and the runner never widens access beyond the configured names. ## Organization Event Automations Organization event automations are visible to organization members but always run as their creator: - `createdBy` is required and `runAs` must be `creator`. - An organization event automation matches only events emitted for that creator. Organization visibility does not turn an event into a broadcast. - Organization admins may update or delete an automation, but cannot replace its creator or retarget its execution identity. - Before every run, the framework verifies that the creator still exists and is still a member of the organization. A removed creator or unreadable membership state prevents execution. ## The Event Bus Integrations register events at module load time. The bus validates payloads against Standard Schema definitions and dispatches to subscribers. ```ts import { registerEvent, emit } from "@agent-native/core/event-bus"; import { z } from "zod"; // Register an event type (typically in a server plugin) registerEvent({ name: "calendar.booking.created", description: "A new calendar booking was created", payloadSchema: z.object({ bookingId: z.string(), attendeeEmail: z.string(), startTime: z.string(), }), example: { bookingId: "abc", attendeeEmail: "jane@co.com", startTime: "2025-01-15T10:00:00Z" }, }); // Emit the event (from an action, webhook handler, etc.) emit("calendar.booking.created", { bookingId: "abc", attendeeEmail: "jane@co.com", startTime: "2025-01-15T10:00:00Z", }, { owner: "user@example.com" }); ``` ### Built-in Events | Event | Source | | ------------------------- | ------------------- | | `test.event.fired` | Manual / manage-automations action=fire-test | | `agent.turn.completed` | Agent chat | | `calendar.*` | Calendar integration | | `clip.*` | Clips integration | | `mail.*` | Mail integration | ### Event Bus API | Function | Purpose | | ---------------- | ------------------------------------------- | | `registerEvent` | Declare an event type with schema | | `emit` | Fire an event (validates payload) | | `subscribe` | Listen for an event (returns subscription ID) | | `unsubscribe` | Remove a subscription by ID | | `listEvents` | List all registered event definitions | ## Condition Evaluator When an automation has a `condition`, the dispatcher calls the configured fast/classification model to classify whether the event payload satisfies the condition. This is a yes/no classification, not a generation task. The exact model ID lives in `condition-evaluator.ts`. - Empty or missing condition = unconditional (always fires). - Results are memoized (SHA-256 of condition + payload) with a 5-minute TTL and 500-entry LRU cache. - Payload is truncated to 4000 characters before sending to Haiku. - On API failure, the condition evaluates to `false` (safe default -- skips the automation). ## The `web-request` Tool and Keys Automations use the `web-request` tool for outbound HTTP. It supports `${keys.NAME}` placeholders in the URL, headers, and body. These are resolved server-side after the agent emits the tool call -- the raw secret value never enters the agent's context. - Keys are ad-hoc secrets created by the user on Settings › API keys or through the `/_agent-native/secrets/adhoc` API. - Each key can have a URL allowlist that restricts which origins the key can be sent to. - `resolveKeyReferences()` resolves placeholders, falling back from user scope to workspace scope. - `validateUrlAllowlist()` checks the resolved URL against per-key allowlists (origin-level matching). - Automation definitions, examples, event payloads, and prompts must not hardcode real API keys, webhook URLs, tokens, private Builder/internal data, or customer data. Use `${keys.NAME}` and synthetic `example.com` identities. ## Failure Handling An automation fails once, with its real cause, instead of re-failing every tick. The runner classifies each failure (`jobs/automation-outcome.ts`): | Class | Codes | Pauses after | | ------------ | --------------------------------------------------------------------- | ------------ | | Precondition | `missing_credentials`, `missing_tools`, `owner_missing`, `owner_reserved`, `config_invalid` | 3 identical (owner/identity failures: immediately) | | Runtime | the run's own code, e.g. `http_502` | 5, with a widening gap between attempts | - An event or webhook automation counts a failure once per event (`lastFailedEventId`): queue retries of the same event never pause it alone. - Preconditions are checked before a thread or `agent_runs` row exists: no "Job:" thread per tick. The failure is recorded on the automation and its run history only. Never write a generic "ended with status: errored"; surface the run's own error. - A paused automation has `enabled: false`, `lastStatus: paused`, and `pausedReason`/`pausedAt`. The owner is emailed once by the run that paused it (for organization and shared jobs: the creator while still a member, otherwise an org owner or admin). Enabling the automation clears the pause and the streak. One paused for an absent credential (`missing_credentials`) resumes by itself once its identity has a usable LLM credential; a rejected key stays paused until the owner enables it again. - Transient failures (spent credits, an unreadable credential store, a remote host, 429/5xx) pause like runtime ones, but the scheduler lifts the pause for one probe run on the same backoff (at most 6h). A failing probe pauses again at once without a new email; a successful one clears the streak. - A paused job's "Run now" is still settled (stale `running`, remote reconcile); it never moves the streak, and resumes the job only on success. - Pauses and automatic resumes are measurable: `automation_paused` (`error_code`, `failure_kind`, `consecutive_failures`, `surface`) and `automation_resumed` (`via`) carry `automation_hash`, the first 12 hex characters of sha256 of `<app>|<name>`, never the name. A failed run's capture carries its own thread, run and automation name in `extra.failureContext`. - `runAs: shared` and organization jobs run as the organization, never as the creator's personal connection: only an org admin can connect the provider. - Jobs owned by users that no longer exist, or by reserved test identities (`.test`, `.invalid`, `.example`, `example.com|org|net`) in production, are disabled with `owner_missing` / `owner_reserved`. Absence is proven only by a populated built-in `"user"` table (case-insensitive); a lookup error, or a deployment whose accounts live elsewhere (custom `getSession`), is never read as "deleted". - The scheduler tick also closes `automation_runs` stuck `running` for over 25 hours (`interrupted`, `automation_run_abandoned`) and A2A tasks idle for 24 hours (`failed`, `a2a_task_abandoned`), a bounded batch at a time. ## UI The full-page Agent surface's **Automations** tab is the primary management surface for scheduled and event-triggered automations. Users can view status, enable/disable, inspect, and delete automations there. Its URL remains `/agent#jobs` for compatibility even though the visible tab is Automations. Creation typically happens through the agent chat. ## Example User: "When someone books a meeting with a @example.com email, message me in Slack." Agent flow: 1. Calls `manage-automations` with `action=list-events` to find `calendar.booking.created`. 2. Confirms the plan with the user. 3. Calls `manage-automations` with `action=define`: - `name`: `slack-on-example-booking` - `trigger_type`: `event` - `event`: `calendar.booking.created` - `condition`: `attendee email ends with @example.com` - `mode`: `agentic` - `domain`: `calendar`