# schedule_recall — Manual

## What it does
Schedules a headless callback for the current session. At the specified time Navi wakes up, reads the context message you left for yourself, and continues working — using other tools if needed.

Only one pending recall is allowed per session. To schedule a new one, cancel or wait for the existing one first.

## Core principle: the recall is a TOOL, not a chat message
The value of this instrument is not "remind the user later". The value is **"continue a multi-step task after a delay or on a schedule"**.

When you set `additional_context_message`, write it as a **self-instruction** telling yourself exactly what to do next with other tools:

- BAD:  `"Tell the user that 2 hours have passed."`
- GOOD: `"Check the /tmp/build.log file with filesystem tool. If the build succeeded, report the result. If it failed, read the last 50 lines of the log and tell the user what went wrong."`

## Call types

| Type | When to use |
|------|-------------|
| `once` | Single delayed action: "check logs in 30 minutes", "continue installation after reboot". |
| `recurring` | Periodic action: "check inbox every 15 minutes", "poll API status every 5 minutes". Requires `interval_seconds`. |
| `immediate` | Fire ASAP (within the next scheduler poll cycle). Use when you want to hand off to a headless run right now without blocking the chat. |

## Parameters
- `call_type` (string, required) — `once`, `recurring`, or `immediate`
- `when` (string, required for `once`/`recurring`) — when to trigger
- `interval_seconds` (integer, required for `recurring`) — repeat interval
- `additional_context_message` (string, required) — **self-instruction** describing what to do when the recall fires
- `internal_comment` (string, optional) — human-readable note why this recall was set

## `when` format
- ISO datetime: `2026-05-20T14:30:00` or `2026-05-20T14:30:00Z`
- Relative: `30m`, `2h 15m`, `1d 6h`, `in 3 hours`, `in 45 minutes`
- Tomorrow: `tomorrow at 09:00`, `tomorrow 14:30`

## Popular scenarios

### Continue a long task that hit iteration limit
You ran out of iterations while configuring a server. Schedule a recall in 0 seconds (or `immediate`) with context: `"Continue Nginx configuration from step 3: edit /etc/nginx/sites-available/default and reload."`

### Wait for an external process
User started a build / download / export. Schedule `once` for the estimated finish time. In the context message tell yourself which files to check and how to report results.

### Periodic monitoring
Schedule `recurring` with `interval_seconds: 900` (15 min). Context: `"Read /var/log/myapp/errors.log. If new ERROR lines appeared since last check, summarize them."`

### Defer heavy work so the chat stays responsive
A task needs 20 tool calls but the user wants to keep chatting. Set `immediate`, context: `"Execute the full data migration plan from scratchpad_id='migration_plan'. Report progress and any errors."` The user gets a fast acknowledgment; the heavy work runs headlessly and appears in session history.

## Rules
1. `additional_context_message` must be actionable — it should read like a todo item you assign to yourself.
2. Mention specific tool names or file paths when possible. Future-you has the same tools but not the same short-term memory.
3. If the task spans multiple phases, consider chaining recalls: first recall fires, does phase 1, then schedules the next recall for phase 2.
4. Only one pending recall per session. If you need multiple timers, use a single recurring recall and track state in a scratchpad or file.

## After a successful call
The recall is stored in PostgreSQL. The background scheduler polls every minute (or sooner if a recall is due). When it fires, Navi runs headlessly: the session shows all thinking and tool calls in history, and the user cannot send new messages until the run finishes.