wait_for_job
Wait for a job to reach a terminal state with live progress notifications, returning the final status for downstream tools.
Instructions
Wait for a job to reach a terminal state, emitting live MCP progress notifications.
Preferred over manually looping get_job_status. The MCP host shows a live progress indicator while this tool holds the connection — no extra token cost.
Architecture ──────────── Every poll cycle does two things in sequence:
Fetch /messages → extract native progress %, emit MCP notification
Fetch /status → act on phase transitions or terminal states
This separation means messages drive the visual indicator (they are more real-time) while status is the authoritative source for workflow transitions. Neither endpoint is used as a shortcut to skip the other; both are polled every cycle so transient failures in one don't cause false terminations.
Progress is always monotonically non-decreasing. Within a phase, msg_progress can oscillate (e.g. QC triggers new row-discovery rounds in the table-maker), but the emitted value is clamped to last_emitted. Across phases a geometric slice scheme is used so the bar never goes backward regardless of how many phases occur.
Progress geometry (lazy split) ────────────────────────────── Starts with the full 0–99 range so single-phase jobs (e.g. full validation after approve_validation) map their native 0–100% directly across the whole bar. On each intermediate phase transition, 80% of the current range is "spent" on the completed phase and the remaining 20% is handed to the next phase — keeping progress monotonic for any number of QC re-discovery rounds or pipeline stages. True terminal always emits exactly 100.
Terminal states: preview_complete, failed, completed-without-intermediate-step. Intermediate: completed + current_step in (Config Generation, Table Making, Claim Extraction, …) — tool advances phase and keeps polling.
Returns the same payload shape as get_job_status so downstream tools (approve_validation, get_results, etc.) apply directly.
job_id: the session_id value returned by upload_file / start_table_validation / start_table_maker. "job_id" and "session_id" are the same string — every workflow uses session_id as its job identifier throughout the pipeline. timeout_seconds: max wall time before returning last known state (default 900). Upload-interview + config-gen phases and large table previews can take up to 15 minutes — set timeout_seconds=900 or higher for long-running jobs. poll_interval: seconds between poll cycles (default 10) warmup_seconds: when > 0, applies synthetic sqrt-curve progress from 0→70% over this many seconds during the pre-message phase (before the first progress message or intermediate step arrives). Use this when the pipeline has a silent setup phase (e.g. instructions= mode where the backend runs an internal AI interview + config generation before preview messages begin). The warmup is automatically disabled once the first intermediate step completes (phase-split takes over). For instructions= mode, pass 300.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Session ID returned by upload_file, start_table_validation, or start_table_maker. | |
| timeout_seconds | No | Maximum wall-clock seconds to wait before returning last known state (default 900). | |
| poll_interval | No | Seconds between status poll cycles (default 10). | |
| warmup_seconds | No | Seconds of synthetic sqrt-curve progress during silent setup phases (default 0; use 300 for instructions= mode). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |