Self-improving AI Employees for everyone
Timer (timer)
| Field | Value |
|---|---|
| Category | workflow / utility / tool (dual-purpose) |
| Backend handler | Plugin server/nodes/scheduler/timer/__init__.py (TimerNode); dispatch via BaseNode.execute() + the @Operation("wait") method. |
| Tests | server/tests/nodes/test_workflow_triggers.py |
| Skill (if any) | timer-skill |
| Dual-purpose tool | yes - exposed on the tool output handle so AI agents can invoke it |
Purpose
One-shot delay node. When executed, it broadcasts a waiting status to the
frontend, sleeps for the requested duration via asyncio.sleep, then returns
timing metadata. Unlike cronScheduler, it does not loop and has no concept
of next-run; it simply pauses the branch of the workflow it is on for
duration units.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Trigger to start the timer. Upstream data is not consumed by the handler. |
Parameters
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
duration |
number | 1 |
yes | - | How long to wait. Pydantic-validated ge=1, le=86400. |
unit |
options | seconds |
no | - | One of seconds / minutes / hours; validation refuses any other value. |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | Timing metadata (see below). |
Dual-purpose: the plugin sets usable_as_tool = True with tool_name = "timer", so when wired to an agent's input-tools handle the LLM fills the same Params schema. There is no separate output-tool handle declared.
Output payload
{
timestamp: string; // ISO 8601 - when the timer finished
elapsed_ms: number; // Wall-clock elapsed milliseconds
duration: number; // Input duration (echoed)
unit: string; // Input unit (echoed)
message: string; // "Timer completed after <duration> <unit>"
}
Wrapped in the standard envelope: { success: true, result: <payload>, execution_time, timestamp, node_id, node_type: "timer" }.
Logic Flow
flowchart TD
A[BaseNode.execute -> wait op] --> B[duration = int params.duration]
B --> C{unit?}
C -- seconds --> S1[wait_seconds = duration]
C -- minutes --> S2[wait_seconds = duration * 60]
C -- hours --> S3[wait_seconds = duration * 3600]
C -- other --> S4[wait_seconds = duration]
S1 --> D[get_status_broadcaster.update_node_status 'waiting'<br/>with complete_time + wait_seconds]
S2 --> D
S3 --> D
S4 --> D
D --> E[await asyncio.sleep wait_seconds]
E -- CancelledError --> F[The cancel propagates<br/>a Temporal activity reports a cancel; in process NodeExecutor answers Cancelled]
E -- ok --> H[elapsed_ms = now - start]
H --> I[Return success envelope<br/>with timestamp / elapsed_ms / duration / unit / message]
Decision Logic
- Unit mapping:
seconds/minutes/hoursmultiply duration by 1 / 60 / 3600. The_match case (raw seconds) is unreachable, sinceParamsvalidation refuses any other unit. - Explicit cancellation:
asyncio.CancelledErrorpropagates. In a Temporal activity it stays a cancel (a worker shutdown retries the wait, which is safe to repeat); in processNodeExecutoranswersCancelled. Cooperative generation Stop does not cancel this sleep.
Stop/Resume boundary
When dispatched through Temporal, this operation is one regular Activity. For a new controlled generation, Stop before admission holds it; Stop after admission lets the delay finish under its existing timeout/retry policy and retains its output. Stopped is acknowledged after that result's bookkeeping, and Resume admits the next pending graph node or agent tool. The duration is not checkpointed halfway through, and Resume does not repeat a completed timer. Workflow checkpoint/maintenance sleeps are separately excluded from the drain count; this user-requested delay is admitted node work. See Workflow control and Node creation.
Side Effects
- Database writes: none.
- Broadcasts:
StatusBroadcaster.update_node_status(node_id, "waiting", {message, complete_time, wait_seconds}, workflow_id)fires exactly once before the sleep. - External API calls: none.
- File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials: none.
- Services:
services.status_broadcaster.get_status_broadcaster. - Python packages:
asyncio,time,datetime(stdlib). - Environment variables: none.
Edge cases & known limits
- Only three unit strings are accepted:
unitis aLiteral, soParamsvalidation refuses any other (there is nodays). durationis Pydantic-validatedge=1, le=86400, but the Activity's timeouts bound a wait first:- As a tool call, one attempt lasts at most the Timer's declared
start_to_close_timeout, the 10-minute action default, so a wait longer than about 9 minutes times out. The tool description says so. - As a graph node, one attempt can last up to the 24-hour graph ceiling.
- Either way, there are three attempts, and each waits the full duration again: a worker restart starts the wait from the beginning.
- As a tool call, one attempt lasts at most the Timer's declared
- The call blocks: an agent waiting on it does nothing else meanwhile.
- Cancellation (
asyncio.CancelledError) propagates as a cancel, so downstream nodes do not execute when the timer is cancelled.
Related
- Skills using this as a tool:
timer-skill. - Sibling triggers:
cronSchedulerfor recurring schedules;startfor manual entry. - Architecture docs: Execution Engine Design