Automations
Rule
Automations are the user-facing umbrella for agent-executed tasks that run on
demand, in response to events or webhooks, or on a cron schedule. Schedule,
Event, Manual, and Webhook are the persisted 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 Persisted Trigger Types
| Type |
Fires when |
Trigger-specific fields |
schedule |
Cron expression matches (same as recurring jobs) |
schedule (required), timezone |
event |
A matching event is emitted on the event bus |
event (required), condition (optional) |
manual |
A user explicitly invokes run-now |
None |
webhook |
A POST reaches its generated webhook endpoint |
None |
Event triggers can optionally include a condition -- a natural-language
string evaluated by a model against the event payload before dispatch. If the
condition does not match, the automation is skipped. Manual automations have no
schedule, timezone, event, or condition; they never fire from the
scheduler or event bus and run only through manage-automations
action=run-now. Webhook automations run only when their generated endpoint is
called. The endpoint path contains a secret token; share it only with the
intended webhook provider.
The UI's Email received choice is not a persisted trigger type. It is a
specialized event editor that persists triggerType: event with
event: mail.message.received and represents email filters as the event
condition.
How It Works
- 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).
- For an event trigger, the agent calls
manage-automations with
action=list-events to discover the exact registered event name and payload.
- Agent calls
manage-automations with action=define to write a
jobs/<name>.md resource.
- The scheduler acquires due schedule triggers, the event dispatcher acquires
matching event triggers, the webhook route accepts authenticated endpoint
calls, and manual triggers wait for
action=run-now.
- Event acquisition enforces owner and organization scope and evaluates any
condition against the event payload.
- Schedule, event, webhook, and explicit run-now 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.
- 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, the event dispatcher matches event names, owners, and
conditions, the webhook route authenticates its endpoint token, and run-now is
the only acquisition path for manual automations. Everything after a trigger is
accepted uses the same execution lifecycle.
Markdown Format
---
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" | "manual" | "webhook" |
How the automation fires |
event |
string? |
Event name to subscribe to (event triggers only) |
condition |
string? |
Natural-language event condition (event triggers only) |
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 last failure cause or declared skip reason |
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 registered event names, descriptions, and payload schemas before defining or changing an event trigger |
list |
List automations and their trigger, status, model, tools, and delivery metadata |
define |
Create an automation after confirming the summary with the user; requires name, trigger_type, and body |
update |
Update an existing automation in its original scope without changing its creator |
delete |
Delete an automation (always confirm with user first) |
fire-test |
Emit a test.event.fired event to validate event automations |
run-now |
Explicitly run one automation immediately with real actions and side effects |
Use list-events only when selecting an event trigger; schedule, manual, and
webhook triggers do not need event discovery. For Email received, use the
registered mail.message.received event rather than inventing an email trigger
type.
For define and update, send trigger_type: schedule with a cron schedule,
trigger_type: event with an exact registered event and optional condition,
or trigger_type: manual/webhook with none of those trigger-specific fields.
Webhook definitions return a secret endpoint path; share it only with the
intended provider. Pass the same scope when updating an existing automation.
manage-automations supports model, reasoning_effort, and mcpTools on
define/update; the MCP allowlist is enforced, not advisory.
Use run-now only for an explicit user-authorized execution. It can run any
persisted trigger type immediately, is the sole execution path for manual
automations, returns a durable run id, and does not change the next scheduled
run.
Additional tool: web-request — outbound HTTP with ${keys.NAME} substitution.
During an automation run, automation-no-op declares that no action or report
was needed. Pass a short reason (1–500 characters), such as "No urgent mail
found." The runner records skipped in the list and Past runs without counting
a failure or sending a report. This declaration cannot cover a failed tool,
rejected send, or missing credentials. Closing prose alone does not declare a
no-op: a run needs confirmed work, delivered output, or this structured signal.
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.
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 resolves the owner's agent engine through the same resolveEngine path chat and the automation's own run use (owner key, deployment fallback, or Builder Gateway) and asks it a yes/no classification question. This is a yes/no classification, not a generation task; it is never hardcoded to a single provider, so an owner using Builder Gateway, OpenRouter, or any other configured provider can use conditions, not only Anthropic.
- Empty or missing condition = unconditional (always fires).
- Results are memoized by condition, payload, execution identity, resolved engine, and model, with a 5-minute TTL and 500-entry LRU cache. The background runner's resolved engine and model are reused for the classifier, including configured engine, deployment-key, and automation model settings.
- Payload is truncated to 4000 characters before sending to the model.
- On a classifier failure (no usable credential, provider error, malformed response), evaluation throws; the trigger dispatcher records it as an
error (or a missing_credentials precondition) rather than silently skipping.
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, connection_required |
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.
connection_required is the exception to that: a run only learns a provider
is not connected by running and yielding to the connection request, so every
failed attempt leaves a thread and an agent_runs row. It skips the runtime
backoff, pauses after 3 identical failures, and stays paused until the owner
enables the automation again; connecting the provider alone does not resume
it.
- 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 schedule, event, manual, and webhook automations. Users can create,
edit, run now, view status, enable/disable, inspect, and delete automations
there. Its URL remains /agent#jobs for compatibility even though the visible
tab is Automations.
Example
User: "When someone books a meeting with a @example.com email, message me in Slack."
Agent flow:
- Calls
manage-automations with action=list-events to find calendar.booking.created.
- Confirms the plan with the user.
- 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
body: Send a Slack message to #sales with the booking details. Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.
Key Files
| File |
Purpose |
packages/core/src/triggers/types.ts |
TriggerFrontmatter interface |
packages/core/src/triggers/actions.ts |
Agent tools (define, list, update, delete, test) |
packages/core/src/triggers/dispatcher.ts |
Event subscription and agentic dispatch |
packages/core/src/jobs/background-automation-runner.ts |
Shared schedule/event/manual/webhook execution lifecycle |
packages/core/src/jobs/automation-outcome.ts |
Failure classification, pause thresholds, reserved identities |
packages/core/src/jobs/stale-reaper.ts |
Bounded reaping of stuck runs and A2A tasks |
packages/core/src/triggers/condition-evaluator.ts |
Engine-resolved condition classification with caching |
packages/core/src/event-bus/ |
Event bus (register, emit, subscribe) |
packages/core/src/tools/fetch-tool.ts |
web-request tool with key substitution |
packages/core/src/secrets/substitution.ts |
resolveKeyReferences() and validateUrlAllowlist() |
Related Skills
recurring-jobs -- schedule-triggered automations reuse the same scheduler
secrets -- ad-hoc keys and ${keys.NAME} substitution
actions -- automations can call any registered action via the agent loop
delegate-to-agent -- agentic mode runs a full runAgentLoop
1---2name: automations3description: >-4 Manual, event-triggered, webhook-triggered, and schedule-triggered5 automations with optional event conditions. Use when creating automations,6 wiring events or webhooks, running one on demand, or understanding triggers.7metadata:8 source: https://skillmd.com/skills/builderio/automations9 internal: true10---1112# Automations1314## Rule1516Automations are the user-facing umbrella for agent-executed tasks that run on17demand, in response to events or webhooks, or on a cron schedule. **Schedule**,18**Event**, **Manual**, and **Webhook** are the persisted trigger types. Each19automation is a markdown resource under `jobs/` with YAML frontmatter describing20when and how it fires, and a body containing natural-language instructions the21agent follows.2223Recurring Jobs is the legacy name and API for scheduled automations.24`manage-jobs`, `jobs/`, and `/agent#jobs` remain stable compatibility surfaces.25Use `manage-automations` for new personal or organization automations, including26per-automation model overrides and MCP allowlists. Keep `manage-jobs` for27existing schedule-only integrations and delivery metadata.2829## The Persisted Trigger Types3031| Type | Fires when | Trigger-specific fields |32| --- | --- | --- |33| `schedule` | Cron expression matches (same as recurring jobs) | `schedule` (required), `timezone` |34| `event` | A matching event is emitted on the event bus | `event` (required), `condition` (optional) |35| `manual` | A user explicitly invokes `run-now` | None |36| `webhook` | A POST reaches its generated webhook endpoint | None |3738Event triggers can optionally include a `condition` -- a natural-language39string evaluated by a model against the event payload before dispatch. If the40condition does not match, the automation is skipped. Manual automations have no41`schedule`, `timezone`, `event`, or `condition`; they never fire from the42scheduler or event bus and run only through `manage-automations`43`action=run-now`. Webhook automations run only when their generated endpoint is44called. The endpoint path contains a secret token; share it only with the45intended webhook provider.4647The UI's **Email received** choice is not a persisted trigger type. It is a48specialized event editor that persists `triggerType: event` with49`event: mail.message.received` and represents email filters as the event50condition.5152## How It Works53541. User asks the agent to create an automation (or uses the app's Automations55 page in Settings, `/settings/automations`; open it with `open-settings-page`56 page `automations`).572. For an event trigger, the agent calls `manage-automations` with58 `action=list-events` to discover the exact registered event name and payload.593. Agent calls `manage-automations` with `action=define` to write a60 `jobs/<name>.md` resource.614. The scheduler acquires due schedule triggers, the event dispatcher acquires62 matching event triggers, the webhook route accepts authenticated endpoint63 calls, and manual triggers wait for `action=run-now`.645. Event acquisition enforces owner and organization scope and evaluates any65 condition against the event payload.666. Schedule, event, webhook, and explicit run-now acquisition converge on the67 shared background-automation runner, which validates identity, resolves the68 configured model and MCP allowlist, runs the agent loop, handles continuation69 and delivery, and records usage.707. Status (`lastRun`, `lastStatus`, `lastError`) is written back to the resource71 frontmatter.7273Trigger acquisition stays separate by design: the scheduler decides when a cron74expression is due, the event dispatcher matches event names, owners, and75conditions, the webhook route authenticates its endpoint token, and `run-now` is76the only acquisition path for manual automations. Everything after a trigger is77accepted uses the same execution lifecycle.7879## Markdown Format8081```yaml82---83enabled: true84triggerType: event85event: calendar.booking.created86condition: "attendee email ends with @example.com"87mode: agentic88domain: calendar89createdBy: user@example.com90runAs: creator91---9293Send a Slack message to #sales with the booking details.94Use the web-request tool with ${keys.SLACK_WEBHOOK}.95```9697### Frontmatter Fields9899| Field | Type | Purpose |100| ------------- | ------------------------------ | ------------------------------------------------------ |101| `schedule` | `string` | Cron expression; new scheduled automations default to once per hour (`0 * * * *`) when omitted |102| `enabled` | `boolean` | Whether the automation is active |103| `triggerType` | `"schedule" \| "event" \| "manual" \| "webhook"` | How the automation fires |104| `event` | `string?` | Event name to subscribe to (event triggers only) |105| `condition` | `string?` | Natural-language event condition (event triggers only) |106| `mode` | `"agentic"` | Full agent loop (only supported mode; `"deterministic"` was removed — never implemented, rejected at define time) |107| `model` | `string?` | Override the model for this trigger's agent loop |108| `reasoningEffort` | `string?` | Override reasoning effort for this trigger's model; omitted uses the model's default |109| `domain` | `string?` | Grouping tag (mail, calendar, clips, etc.) |110| `createdBy` | `string?` | Creator email; required for organization event automations |111| `orgId` | `string?` | Organization scope |112| `runAs` | `"creator" \| "shared"` | Execution identity; trigger-aware automations use `creator` |113| `mcpTools` | `string[]?` | Exact MCP tool allowlist for this automation |114| `lastRun` | `string?` | ISO timestamp of last execution |115| `lastStatus` | `string?` | `success`, `error`, `running`, `skipped`, or `paused` |116| `lastError` | `string?` | The last failure cause or declared skip reason |117| `lastErrorCode` | `string?` | Typed code of the last failure (see Failure handling) |118| `consecutiveFailures` | `number?` | Run of identical `lastErrorCode` failures |119| `pausedReason` | `string?` | Set with `enabled: false` when the framework paused it |120| `pausedAt` | `string?` | ISO timestamp of that pause |121122## Agent Tools123124All automation operations are accessed through a single `manage-automations` tool with an `action` parameter:125126| Action | Purpose |127| ------------- | -------------------------------------------------------------------- |128| `list-events` | Discover registered event names, descriptions, and payload schemas before defining or changing an event trigger |129| `list` | List automations and their trigger, status, model, tools, and delivery metadata |130| `define` | Create an automation after confirming the summary with the user; requires `name`, `trigger_type`, and `body` |131| `update` | Update an existing automation in its original scope without changing its creator |132| `delete` | Delete an automation (always confirm with user first) |133| `fire-test` | Emit a `test.event.fired` event to validate event automations |134| `run-now` | Explicitly run one automation immediately with real actions and side effects |135136Use `list-events` only when selecting an event trigger; schedule, manual, and137webhook triggers do not need event discovery. For **Email received**, use the138registered `mail.message.received` event rather than inventing an email trigger139type.140141For `define` and `update`, send `trigger_type: schedule` with a cron `schedule`,142`trigger_type: event` with an exact registered `event` and optional `condition`,143or `trigger_type: manual`/`webhook` with none of those trigger-specific fields.144Webhook definitions return a secret endpoint path; share it only with the145intended provider. Pass the same `scope` when updating an existing automation.146`manage-automations` supports `model`, `reasoning_effort`, and `mcpTools` on147define/update; the MCP allowlist is enforced, not advisory.148149Use `run-now` only for an explicit user-authorized execution. It can run any150persisted trigger type immediately, is the sole execution path for manual151automations, returns a durable run id, and does not change the next scheduled152run.153154Additional tool: `web-request` — outbound HTTP with `${keys.NAME}` substitution.155156During an automation run, `automation-no-op` declares that no action or report157was needed. Pass a short `reason` (1–500 characters), such as "No urgent mail158found." The runner records `skipped` in the list and Past runs without counting159a failure or sending a report. This declaration cannot cover a failed tool,160rejected send, or missing credentials. Closing prose alone does not declare a161no-op: a run needs confirmed work, delivered output, or this structured signal.162163`manage-automations` accepts personal or organization scope and supports164`model`, `reasoning_effort`, and `mcpTools` on define/update. An MCP allowlist165is enforced, not advisory: every named tool must resolve in the creator's166request context or the run fails clearly, and the runner never widens access167beyond the configured names.168169## Organization Event Automations170171Organization event automations are visible to organization members but always172run as their creator:173174- `createdBy` is required and `runAs` must be `creator`.175- An organization event automation matches only events emitted for that176 creator. Organization visibility does not turn an event into a broadcast.177- Organization admins may update or delete an automation, but cannot replace178 its creator or retarget its execution identity.179- Before every run, the framework verifies that the creator still exists and is180 still a member of the organization. A removed creator or unreadable181 membership state prevents execution.182183## The Event Bus184185Integrations register events at module load time. The bus validates payloads against Standard Schema definitions and dispatches to subscribers.186187```ts188import { registerEvent, emit } from "@agent-native/core/event-bus";189import { z } from "zod";190191// Register an event type (typically in a server plugin)192registerEvent({193 name: "calendar.booking.created",194 description: "A new calendar booking was created",195 payloadSchema: z.object({196 bookingId: z.string(),197 attendeeEmail: z.string(),198 startTime: z.string(),199 }),200 example: { bookingId: "abc", attendeeEmail: "jane@co.com", startTime: "2025-01-15T10:00:00Z" },201});202203// Emit the event (from an action, webhook handler, etc.)204emit("calendar.booking.created", {205 bookingId: "abc",206 attendeeEmail: "jane@co.com",207 startTime: "2025-01-15T10:00:00Z",208}, { owner: "user@example.com" });209```210211### Built-in Events212213| Event | Source |214| ------------------------- | ------------------- |215| `test.event.fired` | Manual / manage-automations action=fire-test |216| `agent.turn.completed` | Agent chat |217| `calendar.*` | Calendar integration |218| `clip.*` | Clips integration |219| `mail.*` | Mail integration |220221### Event Bus API222223| Function | Purpose |224| ---------------- | ------------------------------------------- |225| `registerEvent` | Declare an event type with schema |226| `emit` | Fire an event (validates payload) |227| `subscribe` | Listen for an event (returns subscription ID) |228| `unsubscribe` | Remove a subscription by ID |229| `listEvents` | List all registered event definitions |230231## Condition Evaluator232233When an automation has a `condition`, the dispatcher resolves the owner's agent engine through the same `resolveEngine` path chat and the automation's own run use (owner key, deployment fallback, or Builder Gateway) and asks it a yes/no classification question. This is a yes/no classification, not a generation task; it is never hardcoded to a single provider, so an owner using Builder Gateway, OpenRouter, or any other configured provider can use conditions, not only Anthropic.234235- Empty or missing condition = unconditional (always fires).236- Results are memoized by condition, payload, execution identity, resolved engine, and model, with a 5-minute TTL and 500-entry LRU cache. The background runner's resolved engine and model are reused for the classifier, including configured engine, deployment-key, and automation model settings.237- Payload is truncated to 4000 characters before sending to the model.238- On a classifier failure (no usable credential, provider error, malformed response), evaluation throws; the trigger dispatcher records it as an `error` (or a `missing_credentials` precondition) rather than silently skipping.239240## The `web-request` Tool and Keys241242Automations 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.243244- Keys are ad-hoc secrets created by the user on Settings › API keys or through the `/_agent-native/secrets/adhoc` API.245- Each key can have a URL allowlist that restricts which origins the key can be sent to.246- `resolveKeyReferences()` resolves placeholders, falling back from user scope to workspace scope.247- `validateUrlAllowlist()` checks the resolved URL against per-key allowlists (origin-level matching).248- Automation definitions, examples, event payloads, and prompts must not249 hardcode real API keys, webhook URLs, tokens, private Builder/internal data, or250 customer data. Use `${keys.NAME}` and synthetic `example.com` identities.251252## Failure Handling253254An automation fails once, with its real cause, instead of re-failing every255tick. The runner classifies each failure (`jobs/automation-outcome.ts`):256257| Class | Codes | Pauses after |258| ------------ | --------------------------------------------------------------------- | ------------ |259| Precondition | `missing_credentials`, `missing_tools`, `owner_missing`, `owner_reserved`, `config_invalid`, `connection_required` | 3 identical (owner/identity failures: immediately) |260| Runtime | the run's own code, e.g. `http_502` | 5, with a widening gap between attempts |261262- An event or webhook automation counts a failure once per event263 (`lastFailedEventId`): queue retries of the same event never pause it alone.264- Preconditions are checked before a thread or `agent_runs` row exists: no265 "Job:" thread per tick. The failure is recorded on the automation and its run266 history only. Never write a generic "ended with status: errored"; surface the267 run's own error.268- `connection_required` is the exception to that: a run only learns a provider269 is not connected by running and yielding to the connection request, so every270 failed attempt leaves a thread and an `agent_runs` row. It skips the runtime271 backoff, pauses after 3 identical failures, and stays paused until the owner272 enables the automation again; connecting the provider alone does not resume273 it.274- A paused automation has `enabled: false`, `lastStatus: paused`, and275 `pausedReason`/`pausedAt`. The owner is emailed once by the run that paused276 it (for organization and shared jobs: the creator while still a member,277 otherwise an org owner or admin). Enabling the automation clears the pause278 and the streak. One paused for an absent credential (`missing_credentials`)279 resumes by itself once its identity has a usable LLM credential; a rejected280 key stays paused until the owner enables it again.281- Transient failures (spent credits, an unreadable credential store, a remote282 host, 429/5xx) pause like runtime ones, but the scheduler lifts the pause for283 one probe run on the same backoff (at most 6h). A failing probe pauses again284 at once without a new email; a successful one clears the streak.285- A paused job's "Run now" is still settled (stale `running`, remote286 reconcile); it never moves the streak, and resumes the job only on success.287- Pauses and automatic resumes are measurable: `automation_paused`288 (`error_code`, `failure_kind`, `consecutive_failures`, `surface`) and289 `automation_resumed` (`via`) carry `automation_hash`, the first 12 hex290 characters of sha256 of `<app>|<name>`, never the name. A failed run's291 capture carries its own thread, run and automation name in292 `extra.failureContext`.293- `runAs: shared` and organization jobs run as the organization, never as the294 creator's personal connection: only an org admin can connect the provider.295- Jobs owned by users that no longer exist, or by reserved test identities296 (`.test`, `.invalid`, `.example`, `example.com|org|net`) in production, are297 disabled with `owner_missing` / `owner_reserved`. Absence is proven only by a298 populated built-in `"user"` table (case-insensitive); a lookup error, or a299 deployment whose accounts live elsewhere (custom `getSession`), is never read300 as "deleted".301- The scheduler tick also closes `automation_runs` stuck `running` for over 25302 hours (`interrupted`, `automation_run_abandoned`) and A2A tasks idle for 24303 hours (`failed`, `a2a_task_abandoned`), a bounded batch at a time.304305## UI306307The full-page Agent surface's **Automations** tab is the primary management308surface for schedule, event, manual, and webhook automations. Users can create,309edit, run now, view status, enable/disable, inspect, and delete automations310there. Its URL remains `/agent#jobs` for compatibility even though the visible311tab is Automations.312313## Example314315User: "When someone books a meeting with a @example.com email, message me in Slack."316317Agent flow:3183191. Calls `manage-automations` with `action=list-events` to find `calendar.booking.created`.3202. Confirms the plan with the user.3213. Calls `manage-automations` with `action=define`:322 - `name`: `slack-on-example-booking`323 - `trigger_type`: `event`324 - `event`: `calendar.booking.created`325 - `condition`: `attendee email ends with @example.com`326 - `mode`: `agentic`327 - `domain`: `calendar`328 - `body`: `Send a Slack message to #sales with the booking details. Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.`329330## Key Files331332| File | Purpose |333| ---------------------------------------------- | ------------------------------------------------ |334| `packages/core/src/triggers/types.ts` | `TriggerFrontmatter` interface |335| `packages/core/src/triggers/actions.ts` | Agent tools (define, list, update, delete, test) |336| `packages/core/src/triggers/dispatcher.ts` | Event subscription and agentic dispatch |337| `packages/core/src/jobs/background-automation-runner.ts` | Shared schedule/event/manual/webhook execution lifecycle |338| `packages/core/src/jobs/automation-outcome.ts` | Failure classification, pause thresholds, reserved identities |339| `packages/core/src/jobs/stale-reaper.ts` | Bounded reaping of stuck runs and A2A tasks |340| `packages/core/src/triggers/condition-evaluator.ts` | Engine-resolved condition classification with caching |341| `packages/core/src/event-bus/` | Event bus (register, emit, subscribe) |342| `packages/core/src/tools/fetch-tool.ts` | `web-request` tool with key substitution |343| `packages/core/src/secrets/substitution.ts` | `resolveKeyReferences()` and `validateUrlAllowlist()` |344345## Related Skills346347- `recurring-jobs` -- schedule-triggered automations reuse the same scheduler348- `secrets` -- ad-hoc keys and `${keys.NAME}` substitution349- `actions` -- automations can call any registered action via the agent loop350- `delegate-to-agent` -- agentic mode runs a full `runAgentLoop`