# `SuperPi.Plugins.Scheduler`
[🔗](https://github.com/oleksandr/super-pi-beam/blob/v0.1.0/lib/super_pi/plugins/scheduler.ex#L1)

Scheduled and webhook-triggered runs: the tools `schedule_create`, `schedule_list` and
`schedule_cancel`.

A schedule is a row in `schedules`, fired by one static `Oban.Plugins.Cron` entry (see
`SuperPi.Schedule` for the exactly-once design, run modes, catch-up and failure handling).
Granularity is one minute.

## Tools

| Tool | Effects | Use |
|---|---|---|
| `schedule_create` | `state_write` | Create a cron schedule (or a webhook trigger when allowed). |
| `schedule_list` | `read` | List the conversation's schedules. |
| `schedule_cancel` | `state_write` | Cancel one. |

The tools are not in the global tool catalog. `before_agent_start` appends their specs to the
conversation's tool list and `wrap_tool` serves the calls, as `Todo` does, so a harness
without this plugin never offers them.

## Config

`{SuperPi.Plugins.Scheduler, opts}`:

| Option | Default | Meaning |
|---|---|---|
| `:allow_webhooks` | `false` | Let `schedule_create` make `trigger: "webhook"` schedules. An endpoint that is outside the bearer token and spends money is opt-in. |
| `:allow_nested` | `false` | Allow `schedule_create` inside a scheduled run (the loop guard). |
| `:harness` | `"super-pi-librarian"` | Harness whose plugins a run uses. |
| `:timezone` | `"Etc/UTC"` | Zone for a cron expression when the call gives none. |
| `:max_per_conversation` | `10` | Schedules per conversation. |
| `:min_interval_minutes` | `5` | Smallest gap between two fires. |

## Limits

- Forks do not copy schedules. Rows belong to a conversation id, so forking a conversation
  ten times does not create ten daily briefings. A run of mode `"fork"` is itself a fork and
  has no schedules.
- A scheduled run cannot create schedules (the loop guard) unless `:allow_nested` is set.
- A webhook token appears once, in the result of `schedule_create`, and so in that
  conversation's transcript.

# `description`

# `id`

# `name`

# `tool_specs`

The tool specs for the given options.

---

*Consult [api-reference.md](api-reference.md) for complete listing*