watch_print_status
Check a background print watcher's status, progress, and snapshots. Optionally block until a matching event occurs or a timeout elapses.
Instructions
Check the current status of a background print watcher.
Returns progress, collected snapshots, and whether the watcher
has finished.
By default returns immediately with the current state. Set
``block_until_event=True`` to wait server-side until a new
event fires on the bus matching this watcher's printer (or
``timeout`` seconds elapse). Loop a single blocking call
instead of polling every N seconds — roughly 50× fewer tool
invocations on a multi-hour print.
Args:
watch_id: The watcher ID returned by ``watch_print``.
block_until_event: If True, block until a matching event
arrives on the event bus or ``timeout`` is reached.
Default False (return immediately, current behaviour).
timeout: Maximum seconds to block when
``block_until_event=True``. Default 60. MCP clients
should set their tool-call timeout comfortably above
this (e.g. 120s) so the call returns cleanly instead
of being killed mid-wait.
event_types: Optional list of event-type strings to wait
on. Defaults to
``["vision.alert", "print.terminal", "recovery.completed"]``
— failure alerts, print completion, and recovery
terminal state (so a recovered-and-resumed print
doesn't leave the watcher hanging if no
``print.terminal`` fires for the failed attempt).
Pass a custom list to wait on different events
(e.g. ``["vision.frame_captured"]`` to wake on
every snapshot).
When ``block_until_event=True`` and an event arrives, the
return payload includes ``events_received`` (list of events)
alongside the watcher's current status. On timeout the
payload includes ``timed_out: True``. If the watcher has
already finished before subscription, the call returns
immediately with ``watcher_already_finished: True``.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| timeout | No | ||
| watch_id | Yes | ||
| event_types | No | ||
| block_until_event | No |