Skip to content

Self-improving AI Employees for everyone

6.0 KB
Raw Blame

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 / hours multiply duration by 1 / 60 / 3600. The _ match case (raw seconds) is unreachable, since Params validation refuses any other unit.
  • Explicit cancellation: asyncio.CancelledError propagates. In a Temporal activity it stays a cancel (a worker shutdown retries the wait, which is safe to repeat); in process NodeExecutor answers Cancelled. 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: unit is a Literal, so Params validation refuses any other (there is no days).
  • duration is Pydantic-validated ge=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.
  • 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