Skip to content

Latest commit

 

History

History
65 lines (54 loc) · 15.8 KB

agents-and-controls.md

File metadata and controls

65 lines (54 loc) · 15.8 KB

Dashboard REST API reference — Agents and controls

Part of the Dashboard REST API reference; see that page for how auth levels and pkg/<file>:<line> source citations are read and checked. Edit this file for routes in this area and run src/scripts/check-api-reference-citations.sh --fix to resync citations.

Method Path Auth Purpose Source

| POST | /api/kick/{agent} | Owner only | Kick — asynchronous; answers 202 once queued (see below) | pkg/dashboard/api.go:120 | | GET | /api/kick/{agent}/status | Dashboard auth/session | Outcome of the most recent kick | pkg/dashboard/api.go:124 | | POST | /api/switch/{agent}/{backend} | Owner only | Switch | pkg/dashboard/api.go:125 | | POST | /api/model/{agent}/{model} | Owner only | Model Set | pkg/dashboard/api.go:126 | | POST | /api/effort/{agent}/{effort} | Owner only | Set launch-only reasoning effort after validating against the agent's live backend (including runtime override); persists config/agent overlay, restarts the session, and default clears the stored effort | pkg/dashboard/api.go:127 | | POST | /api/pause/{agent} | Owner only | Pause | pkg/dashboard/api.go:128 | | POST | /api/resume/{agent} | Owner only | Resume | pkg/dashboard/api.go:129 | | GET | /api/agent-state/{agent} | Dashboard auth/session | Agent State | pkg/dashboard/api.go:130 | | GET | /api/breaker | Dashboard auth/session | Breaker State | pkg/dashboard/api.go:131 | | POST | /api/breaker/engage | Owner only | Breaker Engage | pkg/dashboard/api.go:132 | | POST | /api/breaker/release | Owner only | Breaker Release | pkg/dashboard/api.go:133 | | POST | /api/pin/{agent}/{dimension} | Owner only | Pin | pkg/dashboard/api.go:134 | | POST | /api/unpin/{agent}/{dimension} | Owner only | Unpin | pkg/dashboard/api.go:135 | | POST | /api/restart/{agent} | Owner only | Restart | pkg/dashboard/api.go:139 | | GET | /api/model-advisor | Dashboard auth/session | Model Advisor | pkg/dashboard/api.go:156 | | GET | /api/governor/pr-models | Dashboard auth/session | Agent-authored PR distribution by normalized attribution model/backend for window=7d, 30d, or all, including per-model rework stats and the top 10 most-reworked PRs | pkg/dashboard/api.go:157 | | GET | /api/reviewer/accuracy | Dashboard auth/session | Reviewer verdict calibration for the configured window: false-approve/false-block rates and confidence buckets per perspective and reviewer model | pkg/dashboard/api.go:220 | | GET | /api/review/queue | Dashboard auth/session | PR review queue: every open PR (agent and contributor, actionable and held) ranked by triage class, confidence band, CI state and age, with per-PR reasons; unreviewed items carry pending_since and redispatch_count from the review dispatch state; each entry carries stage {stage, entered_at, last_activity_at, quiet_for, stalled, waiting_on_hive, past_dwell, history[]} from the stage-label store (stalled/past_dwell follow governor.labels.stage.dwell and stalled.require_quiet; history[] is {from, to, at, reason, regressed}, newest last, capped at 8) and the top-level hive_held counts PRs past their stage dwell while waiting on the hive (waiting_on_hive and past_dwell both true); paged with limit (1-200, default 50) and offset | pkg/dashboard/api.go:502 | | POST | /api/review/queue/{owner}/{repo}/{number}/superseded/close | Owner only | Close a superseded PR now (grace window or not): posts the close comment, adds hive/superseded, closes it | pkg/dashboard/api.go:505 | | POST | /api/review/queue/{owner}/{repo}/{number}/superseded/keep-open | Owner only | Keep a superseded PR open: adds hive/keep-open, which the supersession sweep never auto-closes | pkg/dashboard/api.go:506 | | GET | /api/review/pipeline | Dashboard auth/session | Review pipeline: one card per review-queue PR placed in its stage (unreviewed, reviewing, changes_requested, fixing, human_hold, approved, merged, abandoned) with since, reviewers, P0–P3 severity counts, loop_count/loop_cap, next_action and reasons; filtered by repo and stage, paged with limit (1-200, default 50) and offset | pkg/dashboard/api.go:510 | | GET | /api/review/dispatch/events | Dashboard auth/session | Webhook review dispatch queue: enabled, webhooks_configured, debounce_s, pending (soonest first) and recent (newest first) dispatches with repo, number, head SHA, action, timestamps and coalesced count, plus stats counters; in memory, never calls GitHub | pkg/dashboard/api_review_event_dispatch.go:15 | | GET | /api/review/evidence | Merger or owner | Review evidence bundle for one PR head. Query repo (owner/name), number, optional head (full SHA or unique prefix of at least 7 characters; 409 when ambiguous; default is the newest head), format=json\|zip (default json) and download=1 for an attachment. json returns the bundle bytes exactly as sealed (verdicts, posted reviews, policy, CI check runs, sentinel findings, human actions, merge event, hash, optional signature); zip adds verdicts.json, review-links.json and a manifest.json of SHA-256s plus the signing public key when readable. 400 for a bad repo/number; 404 with status: "expired"/expired: true when retention removed a bundle Hive can prove existed, otherwise status: "not_found" | pkg/dashboard/api.go:514 | | GET | /api/review/evidence/list | Merger or owner | Every retained evidence bundle id and head for one PR (repo, number), oldest first, with the newest marked latest; 400 for a bad repo/number | pkg/dashboard/api.go:515 | | GET | /api/evidence/write-counters | Merger or owner | Durable attempted vs blocked agent GitHub write counters (#12069): totals by intent tier (ACMM mode) with blocked_by_reason, and weeks keyed by the UTC Monday of each ISO week with per-tier and per-reason counts. Persisted across restarts; observation only, never gates a write or merge. Empty totals/weeks before anything is recorded | pkg/dashboard/api.go:517 | | GET | /api/evidence/summary | Dashboard auth/session | Read-only aggregate over /data/evidence bundles (schema v1) plus reviewer accuracy. Query hours (default 24, capped like /api/pr-throughput; 0 = all time) or a custom from/to range (RFC3339 or YYYY-MM-DD, date-only to inclusive, to defaults to now; 400 when to precedes from, the span exceeds 3 × 366 days, or to is given without from; the response echoes from/to), repo (owner/name) and author_kind=human\|agent\|bot; 400 for a bad value. A PR falls in the window by its open time (earliest bundle created_at or merge.opened_at), never by when a bundle was written; all bundles of a PR are folded so the newest supplies verdicts and the merge / reverted_by / backfilled close come from whichever record knows them. Returns available_windows ({"24","168","720","all"} → PR count under the same filters), outcomes_by_author_kind (merged/closed/open; closed comes from backfilled records, reverted_14d is null until bundles record it), reviewer_calibration buckets per perspective, reviewer_accuracy_by_model split by author kind (blocks split into enforced_blocks / advisory_blocks by policy.require_approval; advisory blocks that preceded a merge are dissent_before_merge, not false blocks), sentinel_hits_per_week, shadow_gate (n, would_have_held, would_have_blocked, and per gate review_gate / intent the evaluated n with held / passed outcomes {n, merged, closed, open, reverted}, plus review_gate_by_lane {merge_eligible, self_merge}), write_counters (per intent tier {attempted, blocked, blocked_by_reason} from the proxy write counter file; omitted when absent or unreadable), write_activity (blocked ÷ every agent write in the window: total_writes, blocked, direct {recorded, since, partial_coverage, attempted, blocked, by_tier, blocked_by_reason} from the proxy's weekly counter buckets under /data/hive-metrics/write-counters.json, mediated {n, refused, by_action} from the audit log), claim_vs_verdict (per ISO week of agent-authored PRs: n, claimed, ci_captured, ci_not_green, verdict_not_approve, both; records with empty CI are excluded from the CI column and disclosed under missing.records_empty_ci), ci_recovery (policy {self_authored_automerge, required_checks}, n, at_claim {green, red, pending, none}, red {n, recovered_merged, green_open, abandoned, pending, outcome_unknown, enriched, not_enriched, median_pushes_to_green, median_hours_to_green, same_head_recovered}, gate {merged_n, with_checks, green, green_from_bundles, non_required_red, required_unknown, breaches, breach_prs[], suspected, suspected_prs[], pending, unknown, green_to_merge_n, median_green_to_merge_hours} over every merged PR by GitHub-confirmed state of the required checks on the merged head, as the merge gate judges (breach_prs[] carry red, merged_by; a red non-required check is disclosed, not a breach; a red review-time snapshot, a required check with no run, or a red read without a resolvable required set is only suspected), and convergence {n, passes {"1","2","3","4+","never"}, settled, in_flight, unknown, median_passes, from_github, from_bundles, by_week[]} over agent PRs by CI passes to first green, from the durable /data/hive-metrics/ci-recovery.json GitHub check-run trail rollup), work_balance (per ISO week: n, opened by actor kind {human, agent, bot}, closed, prs_opened, prs_merged, prs_closed, queue_issues, queue_prs, issue_source github|audit, throttled) with work_balance_sources (issues_github_since, issues_fetched_at, issues_known, audit_only_weeks, issue_series_weeks, queue_samples, queue_retention_days; issues from the durable GitHub rollup /data/hive-metrics/issue-activity.json for weeks at or after issues_github_since and, for earlier weeks, from the backfilled issue series <evidence-root>/<owner>/<repo>/issues/<YYYY-Www>.json written by the issue backfill (#12527) when its coverage spans the requested portion of the week (issue_series_weeks counts the repo-weeks it supplied), else the audit log (audit_only_weeks), PRs from folded bundles, queue depth from governor snapshots; missing.issues_human_opens_unobserved is true while no GitHub rollup exists unless the issue series covers every row, and whenever any row fell back to the audit log, missing.throttle_windows_unavailable discloses that no governor throttle windows are reported), intent_counters (per intent tier {attempted, blocked} from /data/hive-metrics/intent-counters.json — evaluations and the subset the intent gate would have blocked with enforcement on, #12362; omitted when absent or unreadable), complexity_by_repo (per managed repo the newest 12 monthly complexity snapshots, oldest first, each {month, ref, captured_at, files, functions, mean_cyclomatic, median_cyclomatic, p90_cyclomatic, max_cyclomatic, functions_over_threshold, threshold, static_warnings, static_warnings_by_tool}; omitted when no repo has a snapshot), the /api/reviewer/accuracy summary, and n plus missing counts (unknown-model verdicts, empty CI, unreadable records). Never consulted by merge decisions. | pkg/dashboard/api.go:520 | | GET | /api/benchmarks/export | Owner only | Anonymized per-PR benchmark records (schema hivecommons/benchmarks result.schema.json) built from the evidence bundles updated since since (RFC3339 or YYYY-MM-DD; default 90 days; 400 when malformed) plus hive_hash, publish, generated_at and count. records is empty when benchmarks.publish: false; repo/org names appear only for GitHub-public repos when benchmarks.repo_consent is on | pkg/dashboard/api.go:521 | | GET | /api/agents | Dashboard auth/session | Agents List | pkg/dashboard/api.go:305 | | POST | /api/agents | Owner only | Agent Create | pkg/dashboard/api.go:306 | | POST | /api/agents/import | Owner only | Agent Import | pkg/dashboard/api.go:307 | | DELETE | /api/agents/{name} | Owner only | Agent Delete | pkg/dashboard/api.go:308 | | GET | /api/agents/discovered | Dashboard auth/session | Agents declared under .hive/agents/*.yaml in allowlisted managed repos, with status pending / invalid / approved / rejected / orphaned; enabled: false when discovery is not running (agent configuration) | pkg/dashboard/api_repo_agents.go:23 | | POST | /api/agents/discovered/approve | Owner only | Register a pending discovered agent: body {id, name?, backend?, model?, mode?}; sets definition_source (marked discovered) and, with a sibling <name>.md, prompt_source; backend, model and mode come from the request, never the file | pkg/dashboard/api_repo_agents.go:24 | | POST | /api/agents/discovered/reject | Owner only | Decline a pending discovered agent (body {id}); stays declined until the file is removed | pkg/dashboard/api_repo_agents.go:25 | | POST | /api/agents/discovered/refresh | Owner only | Rescan every managed repo's .hive/agents/ now and return the list | pkg/dashboard/api_repo_agents.go:26 |

| GET | /api/agents/{name}/log | Dashboard auth/session | Agent Full Log | pkg/dashboard/api.go:107 | | GET | /api/agents/{name}/terminal-urls | Dashboard auth/session | Agent Terminal URLs | pkg/dashboard/api.go:111 | | GET | /api/agents/{name}/kicks | Dashboard auth/session | Agent Kick Log List | pkg/dashboard/api.go:114 | | GET | /api/agents/{name}/kicks/{id} | Dashboard auth/session | Agent Kick Log Get | pkg/dashboard/api.go:115 | | GET | /agents/{name}/kicks | Dashboard auth/session | Agent Kick History Page (HTML) | pkg/dashboard/api.go:116 | | POST | /api/agents/{name}/login-code | Owner only | Agent Login Code | pkg/dashboard/api.go:138 |

Kick is asynchronous

POST /api/kick/{agent} queues the message and returns immediately with 202; it is not a delivery confirmation.

Delivery has to wait for the agent's CLI to present its input prompt, which is bounded by inputPromptTimeout (120s). Doing that wait on the request path made the handler outlive a typical 60s ingress idle timeout, so a proxy answered 504 for kicks that had in fact succeeded — the prompt was typed, the agent ran the session, and the operator was told it failed (#5325). Retrying a false failure delivered the prompt twice.

The contract is now:

  • 400 — a genuine, deterministic precondition failure evaluated inline: unknown agent, paused, stopped, no tmux session, sandbox kick rejected, prompt over 10000 chars.
  • 202 with status: "deferred" — an auto-generated manual kick was requested before the first governor scan populated the actionable-work snapshot. The kick is deduplicated per agent and delivered after that scan finishes.
  • 202 with status: "queued" — accepted; a background delivery started.
  • 202 with status: "in-flight" — a delivery for this agent was already running, so this call was deduplicated. Delivery is exactly-once per agent, which is what makes an operator's retry harmless.

Read the result from GET /api/kick/{agent}/status, which returns status of unknown, in-flight, delivered, or failed, plus a pending boolean. While pending is true the outcome is indeterminate — the prompt may still be delivered — and clients must not render it as a failure. A CLI that never reaches its input prompt within inputPromptTimeout settles as failed with a reason.