Wait for an action

Availability

Available in hosted CLI 0.6.14 and MCP 0.2.14. Install or upgrade. Native connector 0.1.6 includes CLI 0.6.14/MCP 0.2.14 and all 45 manufacturing tools, plus two connection tools. Upgrade an older project configuration when needed. Existing native archives remain unchanged.

An action request may still be running after your agent loses its connection. Keep its original action ID. The observer reads that same record until its status leaves running, or the bounded wait ends. It never creates another action.

Observe the saved action

maglev actions wait ACTION_ID --json

Use an ID returned by the original request or an owned action list. If you only have an idempotency key, inspect saved actions before deciding whether a request needs recovery. This command does not look up work by idempotency key or resend a lost request.

The default wait is 30 seconds, with five seconds between completed reads. To change those bounds, create wait.json:

{"waitMs": 60000, "pollMs": 5000}

maglev actions wait ACTION_ID --input wait.json --json

The wait can last 1–60 seconds. Poll intervals can be 2–15 seconds. The total budget includes account verification and API reads; a shorter per-request timeout can still stop an individual request. One call keeps one credential and one action ID. Both live and sandbox keys are supported. The existing read endpoint requires actions:write; that permission does not approve any supplier message or commitment.

Read the result

Field	Meaning
state: "action_observed"	A complete record with a recognized status other than running was observed
state: "wait_elapsed"	The idle wait ended after a complete running observation
actionStatus	The exact saved status, without translating it into manufacturing success
actionView	The complete original action, delivery summaries, task and draft marker
observedAt	When that complete record was read; an elapsed result may already be stale
pollCount, elapsedMs	Number of action reads and total time spent in this call
readOnly: true	The observer sent no action, approval, dispatch or other write

Read the kind-specific draft at actionView.action.output.result only when output is present. Preserve its notes, unknowns and source evidence. The envelope does not certify the result or execute instructions embedded in source text.

Saved status	What your agent should do next
running with wait_elapsed	Retain the original ID and observation time; another bounded read may be appropriate
draft_ready	Review the draft and its evidence
awaiting_approval	Retrieve the complete delivery review and obtain the applicable authorization
queued	Inspect the coordination task; this is not completed engineering work
approved or sent	Inspect each delivery’s actual receipt; these labels do not establish inbox delivery or a supplier reply
done	Inspect the saved result and evidence; a record status is not proof that a product passed testing or entered production
failed	Inspect the recorded failure and original input before deciding on another attempt

All states other than running return immediately. There is no option to wait through an approval boundary or automatically move it forward. A failed action returns its saved record so the agent can inspect it; it is not the same as an API transport error.

Cancellation and errors

Press Ctrl+C or cancel the MCP call to stop observing. The server-side action may continue. Cancellation does not cancel manufacturing work or create a replacement.

• action_wait_timeout: the total deadline elapsed during a request. No complete final observation is returned. Read the same action again when appropriate.
• request_cancelled: observation was cancelled; no follow-up write occurred.
• scope_required, HTTP 401/403/404: inspect the selected account and its permissions. Do not switch accounts or recreate the action automatically.
• HTTP 429, service or network error: stop and retain available request ID and retryAfter. The observer does not retry the error.
• invalid_response: the record has an unknown status, mismatched ID/context or incomplete view. Check the API contract before interpreting it.
• response_too_large: the response or observation envelope exceeds 2 MiB. No partial evidence is returned.

An idle wait_elapsed result differs from a timeout during a read: the former contains the last completed observation and its timestamp; the latter does not claim a new observation. Neither authorizes a duplicate action.

Use from MCP

wait_for_action accepts actionId, optional waitMs and optional pollMs. It is read-only and cancellable. MCP 0.2.14 exposes 45 manufacturing tools; native connector 0.1.6 includes those 45 manufacturing tools plus two connection tools. Check the installed inventory before calling a newly released tool.

This is a bounded client call, not a background scheduler. The projects and actions guide covers creating authorized work; delivery execution covers the separate review, approval and dispatch process.