Add system cron job observability debug endpoint (AXON-692)#12
Merged
Binlogo merged 1 commit intoJun 1, 2026
Merged
Conversation
GET /api/debug/system-cron-jobs lists schedule_followup-created system
cron jobs (filtered out of the user-facing /api/cron/jobs) with each
job's recent RunRecord history. Supports thread_id and since filters and
a configurable runs_limit. POST .../{id}/run is a system-only wrapper
around CronService::run_now (non-system or missing jobs return 404).
Routes live under the protected router so enforce_gateway_auth gates
them: loopback passes, otherwise a valid gateway token is required. No
separate debug-token surface is introduced. Existing /api/cron/jobs and
/api/cron/runs behavior is unchanged (additive, read-only).
Docs: new docs/schedule-followup-observability.md, cross-linked from
schedule-followup.md.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
GET /api/debug/system-cron-jobs— debug observability for system-managedcron jobs (AXON-692).
schedule_followupjobs are created withsystem: true,which keeps them out of the user-facing
GET /api/cron/jobs. During incidents("the agent promised a followup and it never came back") there was no way to
inspect them. This endpoint lists the system cron jobs with each job's recent
RunRecordhistory, and adds a system-only manual fire.Scope
GET /api/debug/system-cron-jobs— listssystem == truejobs (reusesCronService::list_all, whichlist()filters), each with recentRunRecords (reuseslist_runs_for_job). Read-only; never repairs state.thread_idquery — exact match on the job's thread (empty/blank ignored).sincequery — unix-seconds or RFC3339 lower bound oncreated_at; anunparseable value returns
400 invalid_since(never a silent full list).runs_limitquery — recent runs per job (default 20).POST /api/debug/system-cron-jobs/{id}/run— system-only wrapper aroundCronService::run_now. Missing or non-system job →404; disabled /already-running →
409. The debug channel never fires user automations.Auth
Routes are registered under the protected router, so
enforce_gateway_authgates them: loopback passes, everything else needs a valid gateway token. Reuses
the existing gateway token rather than introducing a separate debug-token
config surface. Never exposed unauthenticated to non-loopback callers.
Invariants honored
GET /api/cron/jobsandGET /api/cron/runsbehavior unchanged (additive).run_nowwrapper strictly system-only.CronServicesignature changes.Tests
cargo test -p garyx-gateway --lib— 513 pass (7 new: no-service, system-onlylisting, thread filter, invalid-since 400, since-unix filter, run 404 missing,
run 404 non-system).
cargo clippyclean on the changed files.Docs
New
docs/schedule-followup-observability.md, cross-linked fromdocs/schedule-followup.md.Refs: AXON-692 (parent AXON-659; depends on AXON-687, merged in #10).
Local verify
Internal-tier local verification (garyx has no SCM/BOE pipeline; cargo-validated, delivered via GitHub PR).
cargo test -p garyx-gateway --lib→ 513 passed; 0 failed (7 new debug-endpoint tests: no-service, system-only listing, thread_id filter, invalid-since→ 400,sinceunix filter, run 404 missing, run 404 non-system).cargo clippy -p garyx-gateway --lib --tests→ clean on the changed files (api.rs/route_graph.rs/api/tests.rs). The repo-wide-D warningsrun surfaces pre-existing lints ingaryx-models/claude-agent-sdk(unchanged source, newly flagged by clippy 1.95) — out of scope for this PR.Reviewed via ag-dev internal single-role CR: risk MEDIUM (new additive HTTP surface), 0 blockers / 0 warnings.
Retrospective
cron_jobs/cron_runs模式 +enforce_gateway_auth,无新抽象。cargo clippy -- -D warnings被garyx-models/claude-agent-sdk既有 lint(clippy 1.95 新规则 doc_lazy_continuation / collapsible_if / sort_by_key)阻塞,与本 PR 无关 —— 建议单独 tech-debt 清理(follow-up)。