---
title: Agent Triggers & Schedules
category: AI & Autonomous
icon: ⏱️
sort_order: 27
slug: agent-triggers-and-schedules
canonical_url: https://basaltnotes.com/guides/agent-triggers-and-schedules
markdown_url: https://basaltnotes.com/guides/agent-triggers-and-schedules.md
---
# Agent Triggers & Schedules

Basalt triggers turn a bounded event or a due schedule into an auditable Agent run and a reviewable Forge proposal. The run snapshots the selected Agent, Living Skill, Prompt Recipe, scope, instruction, allowed tools, policy, and budgets. Trigger handling does not mutate a vault directly or silently invoke an external provider.

## Trigger Sources

Event triggers can subscribe to versioned note, metadata, task, meeting, Pulse, Strata, trust, connection, webhook, Microsoft ingestion, and generic external events. Each event carries an entity reference, content fingerprint, origin, correlation and causation IDs, and depth.

Schedule triggers support a one-time future timestamp or a five-field cron expression with an IANA time zone. Recurring schedules must be at least five minutes apart. A one-time trigger disables itself when its leased occurrence is claimed. Basalt advances and leases a due occurrence before creating its event, so two workers cannot intentionally claim the same timestamp. A persistent idempotency key and run dedupe key make retries safe.

Hosted metadata writes emit `metadata.changed` through the internal event gateway after the canonical write succeeds. That gives Basalt an internal end-to-end path in addition to REST, MCP-adjacent, webhook, Zapier, n8n, and connected-source ingestion.

## Loop Prevention and Budgets

Every trigger stores:

- Maximum event depth and runs per correlation chain.
- Event cooldown and maximum concurrent runs.
- Maximum retry attempts with bounded exponential backoff.
- Maximum actions, external calls, duration, cost in microdollars, and tokens.
- A policy snapshot showing the Agent → policy → Forge → audit route.

Self-originating trigger events and over-depth events are recorded as skipped runs. Capacity and correlation exhaustion are also recorded rather than silently dropped.

Forge includes controls to pause or resume all automations, pause or resume each definition, create event/cron/one-time definitions, select local Agent/Skill/Recipe identities, set bounded budgets, issue a dry-run test event, and inspect agent/run history. Account-level and per-agent pause state is enforced by hosted event and schedule workers rather than only hidden in the UI.

## Wake-Up Cadence

Basalt's existing daily maintenance cron processes due schedules as a safe fallback. `POST /api/automations/process` lets the signed-in app wake its own schedules, and Developer/Team clients can call `POST /api/dev/automation/process`. Zapier, n8n, or another trusted scheduler can therefore provide a finer polling cadence without receiving a provider credential or an execution bypass. Actual firing precision is bounded by the chosen wake-up cadence.

Developer/Team clients can create and inspect trigger definitions through `GET|POST /api/dev/automation/triggers`, update or archive a trigger by ID, and inspect the durable run audit through `GET /api/dev/automation/runs`. Every operation is scoped to a workspace the token owner can access.

## Approved Webhook Execution

A successful run creates an `ActionProposal` in `proposed` state with explicit approval required. Most external capabilities remain proposal-only until a capability-specific executor exists.

`webhook.deliver` is the first controlled executor. A Developer or Team workspace registers an HTTPS endpoint before a proposal is created. The destination and signing secret are encrypted, and the proposal references the immutable endpoint ID rather than supplying a URL. After policy-aware Forge approval, Basalt signs and sends the bounded preview payload. Transient outcomes retry only within the proposal's external-call budget; permanent outcomes become visible dead letters. Forge shows queued, retrying, delivered, and dead-letter state.

Zapier and n8n starter assets are available from `GET /api/dev/automation/templates`. The Zapier asset is an honest configuration recipe rather than a proprietary Zap export. The n8n assets are importable workflow JSON for sending events and receiving approved signed deliveries. Registered endpoint metadata is available under `/api/dev/automation/endpoints`; URLs and signing secrets are not returned after creation.