docs: Document the AURA wait_for orchestration worker tool - #41
docs: Document the AURA wait_for orchestration worker tool#41promptless[bot] wants to merge 7 commits into
Conversation
Add a reference page for wait_for, the native orchestration worker tool that polls an MCP tool until a caller-supplied condition holds instead of sleeping for a blind fixed duration. Cover the call arguments, wait conditions, return value, stop reasons, limits, and observability. Also add wait_for to the streaming API guide's tool-coverage list and extend the Vale vocabulary. The page is authored but intentionally left out of docs.json navigation so the client controls when it appears in the sidebar. Relates to: mezmo/aura PR #449
![promptless[bot]](https://avatars.githubusercontent.com/in/979718?s=60&v=4){kind=small}
| description: "A native orchestration worker tool that polls an MCP tool until a condition holds, instead of sleeping for a blind fixed duration." | ||
| --- | ||
|
|
||
| `wait_for` is a built-in tool that AURA attaches to every orchestration worker whenever a shared Model Context Protocol (MCP) manager is available. This holds across all six supported LLM providers. It is not user-configurable: there is no TOML setting to enable or disable it. It belongs to the same native worker toolset as `submit_result` and `read_artifact`. The worker (the model) calls it, not a human. |
There was a problem hiding this comment.
Confirms wait_for is only attached (via wait_for_tools() closure) when shared_mcp is Some, and is wired identically for all six LlmConfig provider arms (OpenAI L2508, Anthropic L2541, Bedrock L2582, Gemini L2612, Ollama L2641, OpenRouter L2674) with no TOML gate — matches "attaches to every orchestration worker whenever a shared MCP manager is available... not user-configurable" and "all six supported LLM providers."
| description: "A native orchestration worker tool that polls an MCP tool until a condition holds, instead of sleeping for a blind fixed duration." | ||
| --- | ||
|
|
||
| `wait_for` is a built-in tool that AURA attaches to every orchestration worker whenever a shared Model Context Protocol (MCP) manager is available. This holds across all six supported LLM providers. It is not user-configurable: there is no TOML setting to enable or disable it. It belongs to the same native worker toolset as `submit_result` and `read_artifact`. The worker (the model) calls it, not a human. |
There was a problem hiding this comment.
wait_for, submit_result, and read_artifact are declared as sibling modules in the same orchestration/tools module, supporting the claim that wait_for "belongs to the same native worker toolset as submit_result and read_artifact."
|
|
||
| ## How It Works | ||
|
|
||
| The worker supplies a `probe` (an MCP tool plus its arguments) and an `until` condition. AURA re-runs the probe every `poll_sec` seconds until the condition holds or the time bound elapses, then returns a structured result. The probe must be an MCP-provided tool. Native built-in tools cannot be probed. |
There was a problem hiding this comment.
McpProbeDispatcher::resolve only scans McpManager's streamable/sse/stdio tool maps, then dispatches via execute_mcp_tool — confirms "the probe must be an MCP-provided tool. Native built-in tools cannot be probed."
|
|
||
| Pass these arguments in the `wait_for` tool call: | ||
|
|
||
| | Argument | Type | Required | Default | Description | |
There was a problem hiding this comment.
Confirms argument shape/required-ness and defaults: probe/until required, poll_sec optional default POLL_DEFAULT_SECS=2, max_wait_sec optional default MAX_WAIT_DEFAULT_SECS=120.
|
|
||
| Supply exactly one of these keys: | ||
|
|
||
| | Key | Type | Stops When | |
There was a problem hiding this comment.
UntilSpec enum (Matches/NotMatches/QuietForSec) confirms the three mutually-exclusive until keys and their stop semantics, cross-checked against ConditionEvaluator::observe (wait_for.rs:344-371).
|
|
||
| `wait_for` returns a structured result: | ||
|
|
||
| | Field | Type | Description | |
There was a problem hiding this comment.
WaitForOutput struct fields (reason, last_observation, elapsed_sec, samples, effective_max_wait_sec) exactly match the documented Return Value table.
| "samples": 10, | ||
| "effective_max_wait_sec": 180 | ||
| } | ||
| ``` |
There was a problem hiding this comment.
StopReason enum (Matched/Settled/Timeout) with doc comments matches the Stop Reasons table exactly.
|
|
||
| | Reason | Meaning | | ||
| | --- | --- | | ||
| | `matched` | A `matches` or `not_matches` predicate held. | |
There was a problem hiding this comment.
Timeout is produced via the Ok((StopReason::Timeout, observation, samples)) branch, not an Err path — confirms "a timeout is a normal result, not an error" and that it carries last_observation.
| ## Limits and Validation | ||
|
|
||
| ### Limits | ||
|
|
There was a problem hiding this comment.
WaitBound::from_secs clamps via secs.min(MAX_WAIT_HARD_CEILING_SECS) (300, defined at line 16); effective_max_wait_sec later reports call.budget().bound().as_secs(), i.e. the clamped value. Confirms the hard-ceiling clamp warning.
|
|
||
| These runtime bounds apply while a `wait_for` call is running: | ||
|
|
||
| <Warning> |
There was a problem hiding this comment.
Each sample is wrapped in tokio::time::timeout(remaining, ...) against the shrinking remaining budget, so a hanging probe cannot outrun the bound — confirmed further by test hanging_probe_cannot_outrun_the_bound (wait_for.rs:1195-1212).
| These runtime bounds apply while a `wait_for` call is running: | ||
|
|
||
| <Warning> | ||
| AURA clamps `max_wait_sec` to a hard ceiling of 300 seconds and silently reduces larger values. The enforced value is reported as `effective_max_wait_sec` in the Return Value. |
There was a problem hiding this comment.
MAX_OBSERVATION_BYTES = 256 * 1024 (line 25); the length check happens mid-loop after each successful sample, raising WaitForError::ObservationTooLarge — a runtime error distinct from the pre-call WaitForCallError validation variants (lines 412-434).
| </Warning> | ||
|
|
||
| If a wait legitimately needs longer than the 300-second ceiling, the worker can issue another `wait_for` call after a `timeout` result. | ||
|
|
There was a problem hiding this comment.
WaitForCallError enum lists exactly the six pre-call validation problems documented: EmptyProbeTool, ProbeArgsNotObject, InvalidPattern, Zero{Quiet,Poll,Wait}, PollExceedsBound (poll_sec >= max_wait_sec), QuietWindowExceedsBound (quiet_for_sec > max_wait_sec); enforced in WaitForCall::parse (lines 267-296) and covered by parse_rejects_every_invalid_call test (lines 1073-1155).
| Before the call runs, AURA returns the following pre-call validation problems as call errors: | ||
|
|
||
| - An empty probe tool name. | ||
| - `args` that is not an object. |
There was a problem hiding this comment.
tracing::info_span! "orchestration.wait_for" declares orchestration.probe_tool, orchestration.wait_condition, orchestration.poll_count, orchestration.stop_reason, orchestration.elapsed_ms fields, populated at lines 568-572 and 638-641 — confirms the Observability section's field list.
| - An empty probe tool name. | ||
| - `args` that is not an object. | ||
| - An invalid regular expression. | ||
| - A zero `poll_sec`, `quiet_for_sec`, or `max_wait_sec`. |
There was a problem hiding this comment.
Verified target page exists in this docs repo (aura/streaming-api-guide.mdx) and documents the aura.* SSE tool-call event reference, including tool coverage for orchestration operations (read_artifact, submit_result, list_prior_runs) at line 685 — consistent with the wait_for page's cross-link and native-toolset framing.
| - `poll_sec` greater than or equal to `max_wait_sec`. | ||
| - `quiet_for_sec` greater than `max_wait_sec`. | ||
|
|
||
| ## Observability |
There was a problem hiding this comment.
Verified anchor: aura/configuration-reference.mdx line 554 has heading "## [orchestration]" (Mintlify slug "orchestration"), and line 636 documents the worker-level mcp_filter field referenced by the See Also blurb.
Source: https://docs.mezmo.com/aura/configuration-reference#orchestration
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Wire aura/wait-for.mdx into the AURA > Features group in docs.json so the wait_for orchestration worker tool reference appears in the sidebar. Relates to: PR #41
…for-tool # Conflicts: # vale/styles/config/vocabularies/Mintlify/accept.txt
Summarize the return value and relocate it beneath Observability, since it is runtime output the worker inspects rather than a user-configurable input. Applies reviewer feedback from Greg Janco on suggestion 7d40c8e7. Relates to: PR #41
Open this suggestion in Promptless to view citations and reasoning process
AURA added
wait_for, a built-in orchestration worker tool that polls an MCP tool until a caller-supplied condition holds, instead of having a worker sleep for a blind fixed duration or spend model turns on a manual check-and-sleep loop. This adds a new reference page under the AURA docs covering what the tool is, its call arguments (probe,untilwithmatches/not_matches/quiet_for_sec,poll_sec, andmax_wait_sec), the return value and stop reasons (matched,settled,timeout), the 300-second hard ceiling and other limits, the pre-call validation errors, and the observability attributes. It also addswait_forto the streaming API guide's tool-coverage list and extends the Vale vocabulary.The page is now wired into
docs.jsonnavigation under AURA → Features, alongside the streaming API guide, so it appears in the docs sidebar.The Return Value content now lives as a subsection under Observability, since the return value is runtime output the worker inspects rather than a user-configurable input. It is summarized (scannable field table plus the
reasonvalues) and notes which fields correspond to the emitted span attributes (poll_count/samples,stop_reason/reason,elapsed_ms/elapsed_sec).Files touched:
aura/wait-for.mdx(new),aura/streaming-api-guide.mdx,docs.json,vale/styles/config/vocabularies/Mintlify/accept.txt.Review feedback (Greg Janco, 2026-07-30)
## Return Valuesection (and its### Stop Reasonssubsection) from the tool-call/configuration flow, summarized it, and relocated it as a### Return Valuesubsection under## Observability. The### Wait Conditions (until)block was intentionally left in place under## Tool Call Arguments, since it is a caller-controlled argument rather than runtime output.Trigger Events
aura/wait-for.mdxtodocs.jsonnavigation (these pages are gated through PRs, not hidden frontmatter).Tip: Add or adjust Promptless's style guide in Agent Knowledge Base ✍️