Scheduled tools: the forge calls an absorbed app's tool on time
An app can ask the forge to call one of its own declared tools on an interval or at a clock time. No model and no crew is involved: the forge makes the call (POST /forge/tools/<tool> with {"args":{}}) as a schedule like any other and keeps how it went.
Declare it
In the app's forge.json, next to the tools the schedule names:
"feature": {
"name": "Radar",
"tools": { "scan": { "description": "Run a scan now" } },
"schedule": [{ "tool": "scan", "every": "1h" }]
}
- At most 4 entries.
everyis15m,1h,6hor1d. A wrong entry is refused with the field named (src/apps/feature.ts). - Clock time:
{ "tool": "print_today", "at": "07:15", "tz": "America/Chicago" }instead ofevery(exactly one of the two;tzis an IANA name, daylight saving is followed). It fires once per local day. A manual run does not move the schedule. A new or changed schedule first fires at its next due time; Run now is for the impatient. - Each entry names a tool the feature declares.
- The tool is called with no arguments, so it should be one that needs none.
When it fires
A feature's schedule is sugar for top-level schedules (#13533): src/apps/feature.ts scheduleSpecs turns each entry into a schedules entry named for its tool (print_today), whose cron is the clock time in its zone (15 7 * * * in America/Chicago) or the interval in UTC, whose path is /forge/tools/<tool> and whose body is {"args":{}}. src/apps/manifest.ts adds them to the manifest's schedules, so there is one parser (schedule_spec.ts) and one firing loop (timer_fire.ts). So the entry is:
- a Schedules row on the app's page, with next and last run, the app's answer, Run now and Pause;
- counted in
/api/v1/healthschedules(total,ran,overdue), and so in the v1 proof's #11595 probe; - fired by waking the app and waiting for it to be ready; the time limit (300 s) covers the call, not the wake;
- tried again after 30 s, 2 min and 10 min when it fails (
retries3), under one idempotency key; and when it still fails the owner is asked once, with the reason (docs/APPS.md, "Declare schedules").
A name used by both a schedules entry and a feature tool is refused by the manifest. A run due while the forge was away fires within an hour (catchUp) and says it was late. Only while the app is absorbed: the forge calls a feature's tool only for an app an admin has absorbed. The timer exists from the commit (so its row shows), but when it comes due for an app that is not absorbed it is dropped unfired, with no run recorded and no call made (permits in timer_fire.ts, set by timer_service.ts); Run now on the features page and the terminal's r refuse it in words, arming nothing. Un-absorbing therefore stops the schedule at its next due time; absorbing again starts it again, at the next due time, never at once.
What the forge records
The runs are the timers' (timer_run, src/core/timers.ts): when each started, how many attempts, the HTTP status, the first 2 KB of the app's answer, the error sentence. A hand's call (the features tool, mcp) is the one thing still kept in feature_fire and feature_run (src/core/feature_fires.ts); un-absorbing or deleting the app clears those.
Read it
Every door shows one line per schedule entry, worded once by scheduleMeta in src/apps/feature_schedule.ts: scan every 1h · last 10:02, ok · 42 ms · next 11:02. When the last call failed, its error sentence stands in for ok. Before the first call the line reads scan every 1h · never run · next soon.
- Page: Settings › Features › the app, under Scheduled (a site admin's page, as the rest of it). The last run reads as the page's relative clock (
2m ago) and the next as its day; both carry the exact instant in their tooltip. A failure is in the danger colour. Each row has Run now: it arms the tool's timer for now, the one the app page's Run now arms, so the app is woken, the call retried and the run kept like any schedule's. - API and the
featurestool:GET /api/v1/features/:slugreturnsfires, a list of{ tool, at, ok, error, durationMs }(atin ms since the epoch), empty until something has fired. It also returnsschedule, one{ tool, every, lastAt, ok, error, durationMs, nextAt, line }per entry while the app is absorbed.lineis the plain-text sentence above, with clocks in UTC. Readable by whoever may read the feature. - Terminal: Feature feeds › the app: a
Scheduled:line above the feed items, the entries'lines joined by;. An admin pressesrthere to run those tools now: the same sentences as Run now on the page.
Not done
No arguments per entry.
Run history
Each scheduled tool shows its last 30 runs, with how each started (schedule, late, skipped for a missed one, mcp), when, whether it went well and how long it took.
- Features page: "Run history", one list per tool, the newest 5 shown and the older ones behind "N older".
- Terminal: open the feature under Feature feeds and press
hto switch between the feed and the history; the Scheduled lines above (one per tool, withat/zone) stay. - API:
historyinGET /api/v1/features/:slug.