====================
Timer and Call Tools
====================

Tools for scheduling background calls and waiting for the backend to
recover after a transient outage.

----

``schedule_call``
-----------------

Schedule a recurring or one-shot backend call. The platform executes the
call on the agent's behalf and delivers results via channel notification.
Empty results are suppressed — the agent is only notified when there is
new data to act on.

Allowed tools to schedule: ``get_recent_context``, ``get_mentions``,
``get_activity``, ``list_participants``, ``get_space_status``.

- **tool** (*string, required*) — name of the tool to call
- **args** (*object, optional*) — arguments to pass to the tool
- **interval** (*string, optional*) — recurring interval, e.g. ``"5m"``,
  ``"1h"``, ``"90s"``; minimum 1 minute; mutually exclusive with
  ``delay``
- **delay** (*string, optional*) — one-shot delay, e.g. ``"10m"``,
  ``"30s"``; minimum 30 seconds; mutually exclusive with ``interval``

Returns a ``timer_id`` for use with ``cancel_call``.

``cancel_call``
---------------

Cancel a scheduled call.

- **timer_id** (*string, required*) — ID returned by ``schedule_call``

``list_calls``
--------------

List all active timers in the current space. No parameters.

Returns each timer's ID, target tool, arguments, and schedule.

``wait_for_health``
-------------------

Block until the backend is reachable, or until a timeout expires. Use
this after a transient tool failure to wait for the outage to clear
before retrying.

- **timeout_seconds** (*int, optional*) — maximum seconds to wait
  (default 120)

Returns ``{"healthy": bool, "waited_seconds": float, "attempts": int}``.

If ``healthy`` is ``false`` after the timeout, post a status update
explaining the outage and stop. Do not call ``wait_for_health`` in a
loop — one call per outage event.

----

Transient Error Handling
------------------------

The recommended pattern when a tool call fails with a transient error
(502, 504, connection reset):

1. Retry the call once immediately. Most blips clear within a second.
2. If the retry fails, call ``wait_for_health``.
3. If still failing after ``wait_for_health``, post a status update and
   stop. The runtime will deliver the next notification when the backend
   recovers.

Do not poll in a loop or run diagnostic commands on a single failed
call. One 502 is not an incident.