Wait (wait)

Category: apps | Form: | Symbol: Wt

Pause automation execution for a duration or until event

Creates time-based pauses in automation execution. Use start operation with either duration_ms (positive integer, milliseconds) or until (RFC 3339 datetime, must be in the future). Returns wait_id for tracking. Use resume operation to complete a wait — if the wait hasn’t expired yet, pass force: true. Use cancel operation for idempotent cancellation (unknown wait_ids are silently accepted). Use pending operation to list all active waits. Wait state auto-expires: wait_status returns ‘expired’ when expiry has passed. Optionally set callback_url to receive a notification on expiry. State is persisted in spec.waits map, survives server restarts.

Guide

Pause flow execution for a duration or until event

What It Does

Wait suspends a flow for a fixed duration, until a specific wall-clock time, or until a CEL condition becomes true via polling. It is the timing primitive of the actor layer — used for rate limiting between API calls, scheduling deferred operations, implementing exponential backoff in retry patterns, and adding jitter to distributed systems. Wait is fully durable: the flow is persisted and the timer is maintained by the platform even if the server restarts.

Element Definition

Property	Value
Type	wait
Category	apps
Form	atom
Symbol	schedule / #F59E0B

Properties

Field	Type	Default	Description
duration	integer or object	—	Wait duration. Either milliseconds as integer, or {value, unit} where unit is ms, s, m, h, or d
until	string (date-time)	—	Wait until a specific ISO 8601 timestamp (alternative to duration)
condition	string	—	CEL expression — wait polls until this evaluates to true (alternative to duration and until)
polling.interval_ms	integer	1000	How often to re-evaluate the condition in milliseconds
polling.timeout_ms	integer	300000	Maximum time to wait for the condition to become true
jitter.enabled	boolean	false	Add random jitter to the wait duration
jitter.percent	integer	10	Jitter range as a percentage of the total duration

Ports

Direction	Port	Type	Required	Description
Input	trigger	signal	No	Optional signal to start the wait (wait starts immediately if not provided)
Output	result	request	Yes	Completion result: waited_seconds, completed_at, event_received, timeout_triggered

Topology

• Lives in: apps/automation/wait/ repository
• Referenced by: projects
• Accepts modifiers: requirements
• Uses resources: variable

Capabilities

Capability	Description
delay	Fixed duration delays
schedule	Wait until a specific wall-clock time
event-wait	Wait for a matching external event
jitter	Random jitter for distributed rate limiting

Error Codes

Code	Class	Retryable	Description
WAIT_INVALID_DURATION	validation	No	Invalid duration format or negative value
WAIT_EVENT_TIMEOUT	timeout	Yes	Condition-based wait timed out before condition became true

Quick Start

Creating via API

Create a wait element inside a project:

POST /api/{circle}/{project}/
Content-Type: application/json

{
  "element_type": "wait",
  "slug": "rate-limit-delay",
  "name": "API Rate Limit Delay",
  "spec": {
    "duration": {
      "value": 1,
      "unit": "s"
    }
  }
}

Basic Usage

Invoke the wait element to pause execution:

POST /api/{circle}/{project}/rate-limit-delay/ops/invoke
Content-Type: application/json

{}

The call blocks until the wait completes. Response:

{
  "waited_seconds": 1.003,
  "completed_at": "2026-02-25T14:32:01.003Z",
  "event_received": null,
  "timeout_triggered": false
}

Project Patterns

How Wait Fits Into Projects

Wait is always a step between two other elements in a flow — never at the start or end. The most common placement is between repeated API calls inside a loop to respect rate limits, or after a triggering function in a scheduled pipeline to defer work to a specific time. Wait elements do not inspect or modify the flow’s data payload — they only control timing.

In development stage, wait durations are honored exactly as configured (useful for testing that timing logic is correct). In demo and live stages, wait elements behave identically. For test runs where you want to skip the delay, pass an override via the variable resource attached to the wait.

Example Project Spec

# Jittered delay to spread load across distributed callers
elements:
  - element_type: wait
    slug: jittered-delay
    spec:
      duration:
        value: 5
        unit: s
      jitter:
        enabled: true
        percent: 20

This waits between 4 and 6 seconds (5s ± 20%).

Common Patterns

Rate Limiting Inside a Loop

Place a wait between API calls in a loop to stay within rate limits:

# Create the wait element
POST /api/{circle}/{project}/

{
  "element_type": "wait",
  "slug": "api-throttle",
  "spec": {
    "duration": {"value": 200, "unit": "ms"},
    "jitter": {"enabled": true, "percent": 10}
  }
}

In the flow, wire each API call output through the wait before the next call. The loop body becomes: fetch-item → api-throttle → process-item.

Scheduled Deferred Execution

Wait until a computed future timestamp before sending a scheduled notification:

POST /api/{circle}/{project}/

{
  "element_type": "wait",
  "slug": "send-at-scheduler",
  "spec": {
    "until": null
  }
}

At invocation time, provide the computed timestamp:

POST /api/{circle}/{project}/send-at-scheduler/ops/invoke

{
  "until": "2026-02-26T09:00:00Z"
}

Exponential Backoff for Retries

Use a wait inside a loop with dynamically computed duration to implement exponential backoff:

POST /api/{circle}/{project}/

{
  "element_type": "wait",
  "slug": "backoff",
  "spec": {
    "duration": {"value": 1000, "unit": "ms"},
    "jitter": {"enabled": true, "percent": 15}
  }
}

On the first retry, pass duration as 1000ms. On the second, 2000ms. On the third, 4000ms. The jitter prevents all retrying clients from hitting the server at the same instant.

Applying Modifiers

Modifier	Use case
requirements	Require specific variable resources to be present before the wait starts

Common Mistakes

Setting both duration and until in spec. Only one wait mode can be active at a time. If both are set, until takes precedence. Use one or the other, not both.

Using condition-based wait without setting polling.timeout_ms. The default polling timeout is 300 000 ms (5 minutes). If your condition may take longer to become true, increase polling.timeout_ms. If it never becomes true and the timeout triggers, WAIT_EVENT_TIMEOUT is raised.

Using wait for human approval scenarios. If you need to pause a flow for a human decision, use the hitl element instead. Wait is for time-based and condition-based pauses only — it has no notification or response mechanism.

Forgetting jitter in distributed systems. If multiple parallel flow instances all wait the same fixed duration and then simultaneously retry a shared resource, they create a thundering herd. Enable jitter whenever multiple instances of the same flow run concurrently.

Relationships

• Uses: variable

Capabilities

• delay: Fixed duration delays
• schedule: Wait until specific time
• event-wait: Wait for matching event
• jitter: Random jitter for rate limiting

Properties

Property	Type	Default	Description
duration	object	—	Wait duration
until	string	—	Wait until specific time (alternative to duration)
condition	string	—	CEL expression - wait until condition is true
polling	object	—	Polling configuration — only used for condition-based waits
jitter	object	—	Add random jitter to prevent thundering herd

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

cancel

Post /ops/cancel | Auth: Execute

Cancel a pending wait

Cancel a pending wait. Requires wait_id. Idempotent — cancelling an unknown wait_id is silently accepted (returns cancelled: true). Sets status to cancelled with reason.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

pending

Get /ops/pending | Auth: Read

List all pending waits for this element

List all active (waiting) timers on this element. No input required. Returns waits array with wait_id, status, remaining_ms for each pending wait.

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

resume

Post /ops/resume | Auth: Execute

Resume execution after wait completes (or force resume early)

Complete a waiting timer. Requires wait_id. If the wait hasn’t expired yet, set force: true to resume early (otherwise returns error). Only works on waits in ‘waiting’ state.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

start

Post /ops/start | Auth: Execute

Start a wait period

Create a wait timer. Provide either duration_ms (positive integer) or until (RFC 3339 datetime, must be in the future). Optionally set callback_url for expiry notification. Returns wait_id for tracking. Both params missing = error. Past timestamps = error.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

wait_status

Get /ops/status/{wait_id} | Auth: Read

Get wait status

Get current state of a wait timer. Requires wait_id. Returns status (waiting/completed/cancelled/expired), remaining_ms (only while waiting), and timestamps. Auto-detects expired waits (remaining_ms reaches 0).

Error Codes

Code	Class	Retryable	Description
WAIT_INVALID_DURATION	validation	no	Invalid duration format
WAIT_EVENT_TIMEOUT	timeout	yes	Event wait timed out