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" }]
}

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 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.

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.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs