mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-06-21 10:22:18 +00:00
feat(cron): wire on_jobs_changed, cron.chronos config, docs + agent↔NAS contract
Phase 4F (F.1 + F.2 + F.3, agent side). F.4 is the operator-run live smoke
(needs a NAS deployment); recorded in the PR, not code.
F.1 — on_jobs_changed wiring:
- cron/scheduler.py: _notify_provider_jobs_changed() — resolve the active
provider, call on_jobs_changed(), swallow errors. Lives in scheduler.py (not
jobs.py) so the store stays free of provider imports (no import cycle).
- Wired at the consumer surfaces AFTER a successful mutation: the cronjob model
tool (tools/cronjob_tools.py, create/update/remove/pause/resume) — which the
`hermes cron` CLI also routes through — and the REST handlers
(gateway/platforms/api_server.py, same five). Built-in's no-op default = zero
behavior change on the default path. Sleeping-agent direct jobs.json writes
(no tool/CLI/REST) are covered by reconcile-on-wake in start().
F.2 — config: cron.chronos.{portal_url,callback_url,expected_audience,
nas_jwks_url}. All non-secret; the agent holds no scheduler creds and the
outbound provision call reuses the existing Nous token (no token key). Additive
deep-merge key, no version literal.
F.3 — docs:
- docs/chronos-managed-cron-contract.md: authoritative agent↔NAS wire contract
(the three agent-cron endpoints + inbound /api/cron/fire + the 3-hop trust
model + at-most-once/re-arm semantics). This is what the NAS-side agent builds
against.
- cron-internals.md: "Managed cron (Chronos) for scale-to-zero" section.
- cli-commands.md: cron.provider accepts chronos + the cron.chronos.* keys.
- User docs name no scheduler vendor (QStash is a NAS-internal detail).
INVARIANT re-verified: zero qstash/upstash hits across plugins/cron, gateway,
hermes_cli, tools, website/docs (the one remaining repo hit is an unrelated
Context7 MCP comment in tools/mcp_tool.py).
Tests: test_jobs_changed_notify (5) — notify calls provider hook, swallows
errors, built-in harmless, tool create/remove notify. Full cron + chronos +
webhook + config + api_server_jobs suites green (504 in the cron+chronos+webhook
run).
This commit is contained in:
parent
3fc7b624d8
commit
b75757d4aa
8 changed files with 409 additions and 5 deletions
|
|
@ -129,6 +129,48 @@ A provider only controls the trigger, never execution.
|
|||
|
||||
In CLI mode, cron jobs only fire when `hermes cron` commands are run or during active CLI sessions.
|
||||
|
||||
### Managed cron (Chronos) for scale-to-zero
|
||||
|
||||
Hosted gateways can run the **Chronos** provider (`cron.provider: chronos`)
|
||||
instead of the built-in ticker. Chronos lets an idle gateway **scale to zero**
|
||||
and still fire cron jobs: rather than a 60-second in-process loop (which would
|
||||
keep the process awake), it asks Nous infrastructure to arm exactly **one
|
||||
managed one-shot per job at that job's real next-fire time**. At fire time Nous
|
||||
calls the gateway back over an authenticated webhook (`POST /api/cron/fire`);
|
||||
the gateway runs the job through the same `run_one_job` path as the built-in,
|
||||
then re-arms the next one-shot. Between fires the process can be fully stopped —
|
||||
it wakes only on a genuine fire, never on a periodic timer.
|
||||
|
||||
The flow (the managed scheduler is provided by Nous; the agent holds no
|
||||
scheduler credentials):
|
||||
|
||||
```
|
||||
create/update a cron job
|
||||
→ Chronos asks Nous to arm a one-shot at the job's next_run_at
|
||||
(authenticated with the agent's existing Nous token)
|
||||
→ at fire time Nous calls the gateway: POST {callback_url}/api/cron/fire
|
||||
(authenticated with a short-lived, purpose-scoped Nous-minted JWT)
|
||||
→ the gateway verifies the token, claims the job (store compare-and-set so
|
||||
multi-replica deployments fire at-most-once), runs it, and re-arms the next
|
||||
one-shot
|
||||
```
|
||||
|
||||
Config (all non-secret; on hosted agents Nous sets these at provision time):
|
||||
|
||||
| key | meaning |
|
||||
|---|---|
|
||||
| `cron.provider` | `chronos` to activate (empty = built-in ticker) |
|
||||
| `cron.chronos.portal_url` | Nous base URL (arming + the fire-token issuer) |
|
||||
| `cron.chronos.callback_url` | the gateway's own public base URL for inbound fires |
|
||||
| `cron.chronos.expected_audience` | this agent's fire-token audience |
|
||||
| `cron.chronos.nas_jwks_url` | key set for verifying the inbound fire token |
|
||||
|
||||
If Chronos is misconfigured or the agent isn't logged into Nous,
|
||||
`resolve_cron_scheduler()` falls back to the built-in ticker (logged warning) —
|
||||
cron never loses its trigger. Recurring jobs re-arm after each fire; `repeat`-N
|
||||
jobs stop cleanly when the count is exhausted (no orphaned one-shot). The full
|
||||
agent↔Nous wire contract lives in `docs/chronos-managed-cron-contract.md`.
|
||||
|
||||
### Fresh Session Isolation
|
||||
|
||||
Each cron job runs in a completely fresh agent session:
|
||||
|
|
|
|||
|
|
@ -534,11 +534,13 @@ hermes cron <list|create|edit|pause|resume|run|remove|status|tick>
|
|||
| `tick` | Run due jobs once and exit. |
|
||||
|
||||
The cron **trigger** is pluggable via the `cron.provider` config key. Empty
|
||||
(the default) uses the built-in in-process ticker. A named provider (e.g.
|
||||
`chronos`, a managed-cron provider for scale-to-zero deployments) is discovered
|
||||
from `plugins/cron/<name>/` or `$HERMES_HOME/plugins/<name>/`; an unknown or
|
||||
unavailable provider falls back to the built-in, so cron is never left without
|
||||
a trigger. See the [cron internals](../developer-guide/cron-internals.md#gateway-integration) doc.
|
||||
(the default) uses the built-in in-process ticker. Set it to `chronos` (the
|
||||
NAS-managed provider for scale-to-zero hosted gateways) — configured via the
|
||||
`cron.chronos.*` keys (`portal_url`, `callback_url`, `expected_audience`,
|
||||
`nas_jwks_url`) — or name a custom provider under `plugins/cron/<name>/` or
|
||||
`$HERMES_HOME/plugins/<name>/`. An unknown or unavailable provider falls back to
|
||||
the built-in, so cron is never left without a trigger. See the
|
||||
[cron internals](../developer-guide/cron-internals.md#gateway-integration) doc.
|
||||
|
||||
## `hermes kanban`
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue