Agents can create durable jobs as JSON files under the session repo. The long-lived acp-host process fires due jobs into the right session slots — even if the Telegram worker is down.
Storage
<repo>/.acpbot/schedules/<id>.jsonOptional scripts (relative to repo root):
.acpbot/schedules/scripts/<name>MCP tools (server acpbot)
| Tool | Action |
|---|---|
schedule_create | prompt (required) + optional script path + once / cron |
schedule_list | Jobs for ACPBOT_SESSION_KEY (or whole repo with all: true) |
schedule_cancel | Soft-disable for this session (enabled: false); all: true for any in-repo job |
schedule_run_now | Set nextRunAt=now so the host fires on the next tick |
script must be relative to the repo root (no .. escapes). Prefer .acpbot/schedules/scripts/<name>.
Cron
- 5-field cron:
m h dom mon dow - Next-run is computed in UTC for MVP
- The
timezonefield is stored (non-UTC values may warn on create) but does not shift the schedule yet - When both day-of-month and day-of-week are restricted, classic cron OR applies (either may match)
Host fire (acpbot host)
Requirements:
[repos]inconfig.tomlmaps catalog keys → absolute repo paths- Optional
[schedule].tick_ms(default20000)
Each tick:
- Scan each catalog repo’s
.acpbot/schedules/ - Collect jobs with
enabled && nextRunAt <= now - Claim on disk before the agent turn:
once→enabled: falsecron→ advancenextRunAtfrom now
- Ensure the job’s
sessionKeyslot and prompt with an envelope (prompt + optional script path)
| Outcome | Behavior |
|---|---|
| Success | Claim retained; cron already advanced |
| Slot busy | Claim rolled back, lastStatus: busy, retry next tick |
| Fire error | Claim left in place (no hot-loop); re-due once jobs via schedule_run_now |
Works without the Telegram worker (create/list/cancel only need MCP). Firing needs acp-host. Delivering Telegram photos/files from a fire needs the worker (worker API).
Agent skill: package skills/schedules — use Telegram /skills, or acpbot skills install (see Skills).
Implementation map
| Area | Path |
|---|---|
| Store / types | src/schedules/ |
| Host ticker | src/acp-host/scheduler.ts |
| MCP tools | src/mcp/server.ts (built-in acpbot) |
| Agent skill | skills/schedules/ |
| Tests | test/host-scheduler.test.ts, test/schedules-store.test.ts |