neon.operations.wait

Poll a Neon operation until finished (or fail/timeout)

Block until a single Neon operation reaches finished (or fail on error/failed/timeout).

This is the only multi-state base atomic in the Neon library. It owns the schedule_transition polling loop that the fire-and-forget create/mutation atomics (A-04 neon.branches.create, A-08 …) deliberately do NOT embed: those return immediately with a neon_operation_id, and the orchestration layer (C-01, C-03, and any future async Neon op) composes this primitive to wait.

The workflow enters WAITING_FOR_OPERATION immediately after PENDING and re-schedules itself every poll_interval seconds via schedule_transition(action="poll", delay=poll_interval) — NOT auto_advance (an auto_advance self-loop fails workflow-validator-async). Each poll reads the operation and decides:

1. status == "finished" → schedule finish (delay 0).
2. status in ("failed", "error") → schedule timeout (delay 0), stamp failure_reason.
3. elapsed >= timeout_seconds → schedule timeout (delay 0).
4. otherwise → reschedule poll (delay poll_interval), bump poll_count.

UUID-only surface rule: connection_uuid is our identifying handle; Neon's own ids stay on the neon_<x>_id surface (neon_project_id, neon_operation_id).

Inputs:

• connection_uuid: UUID of the cloud connection (required)
• neon_project_id: Neon project id (required)
• neon_operation_id: Neon operation id to wait on (required)
• timeout_seconds: Maximum wait time in seconds; default 120, cap 600
• poll_interval: Seconds between polls; default 5, cap 30

Outputs (terminal state_data):

• neon_project_id: echoed project id
• neon_operation_id: echoed operation id
• operation_status: "finished" on success
• poll_count: number of polls executed

Read-only; no DB writes. Plugin required: context.get_plugin("neon") must expose .api_token.

External call (repeated): GET https://console.neon.tech/api/v2/projects/{neon_project_id}/operations/{neon_operation_id}

Overview

Property	Value
Workflow type	Linear
Library	App-neon
Version	1.0

Input Schema

Field	Type	Required	Default	Description
connection_uuid	uuid	Yes	—	Cloud connection UUID (resolves the neon api_token)
neon_project_id	string	Yes	—	Neon project id
neon_operation_id	string	Yes	—	Neon operation id to wait on
timeout_seconds	integer	No	—	Max wait time in seconds (default 120, cap 600)
poll_interval	integer	No	—	Seconds between polls (default 5, cap 30)

Output Schema

Field	Type	Required	Default	Description
neon_project_id	string	No	—	—
neon_operation_id	string	No	—	—
operation_status	string	No	—	—
poll_count	integer	No	—	—
connection_uuid	uuid	No	—	—
timeout_seconds	integer	No	—	—
poll_interval	integer	No	—	—
started_at_epoch	integer	No	—	—
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	start	—
waiting_for_operation	No	No	—	—	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	start	waiting_for_operation	—
waiting_for_operation	poll	waiting_for_operation	—
waiting_for_operation	finish	completed	—
waiting_for_operation	timeout	failed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "neon.operations.wait",
  "initial_data": {
    "connection_uuid": "value",
    "neon_project_id": "value",
    "neon_operation_id": "value"
  }
}