Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-adminmcp-cadences-writeback-kinds.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- An owner can now change an agent's per-mode cadences (`agent.cadences`) and the write-back gate's per-kind overrides (`writeback.kind_policy`) through admin MCP preview and confirm, the same settings the dashboard's agent Cadences and Settings → Features controls save. The cadence preview says when an agent would run more often and that the mode becomes operator-owned; the write-back preview sends every existing override with the change merged in, so the endpoint's whole-map replace keeps the kinds you did not name, and it names any kind that would write at a lower level or without the opt-in label.
88 changes: 71 additions & 17 deletions src/docs/admin-mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -705,23 +705,24 @@ The audit log cannot tell an assistant-mediated write from a dashboard action.

### Registered operations

| Area | Operations |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agents | `agent.pause`, `agent.resume`, `agent.nudge`, `agent.restart`, `agent.add`, `agent.remove`, `agent.model`, `agent.backend`, `agent.effort`, `agent.interaction_tier`, `agent.github_api_hourly_cap` |
| GitHub | `github.agent_api_hourly_cap` |
| Fleet | `fleet.autonomy_level` |
| Plans | `plan.propose`, `plan.approve`, `plan.reject` |
| Governor | `governor.feature_settings`, `governor.thresholds`, `governor.threshold_scaling` |
| Issue filter | `project.issue_filter` |
| Sentinel | `sentinel.settings` |
| Merge settings | `auto_merge.update` |
| Let hive decide | `decisions.delegate_settings` |
| Repositories | `repository.pause`, `repository.resume`, `repository.item_hold` |
| Activity monitor row actions | see below |
| Budget | `budget.update`, `budget.reset`, `budget.ignore` |
| Contributors | `contributor.trust`, `contributor.agent_role`, `contributor.agent_role_grants`, `contributor.revoke`, `contributor.requeue`, `contributor.delete` |
| Backup | `backup.create` (the archive itself is not returned through MCP) |
| Circuit breaker | `circuit_breaker.engage`, `circuit_breaker.release` |
| Area | Operations |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agents | `agent.pause`, `agent.resume`, `agent.nudge`, `agent.restart`, `agent.add`, `agent.remove`, `agent.model`, `agent.backend`, `agent.effort`, `agent.interaction_tier`, `agent.github_api_hourly_cap`, `agent.cadences` |
| GitHub | `github.agent_api_hourly_cap` |
| Fleet | `fleet.autonomy_level` |
| Plans | `plan.propose`, `plan.approve`, `plan.reject` |
| Governor | `governor.feature_settings`, `governor.thresholds`, `governor.threshold_scaling` |
| Issue filter | `project.issue_filter` |
| Sentinel | `sentinel.settings` |
| Write-back | `writeback.kind_policy` |
| Merge settings | `auto_merge.update` |
| Let hive decide | `decisions.delegate_settings` |
| Repositories | `repository.pause`, `repository.resume`, `repository.item_hold` |
| Activity monitor row actions | see below |
| Budget | `budget.update`, `budget.reset`, `budget.ignore` |
| Contributors | `contributor.trust`, `contributor.agent_role`, `contributor.agent_role_grants`, `contributor.revoke`, `contributor.requeue`, `contributor.delete` |
| Backup | `backup.create` (the archive itself is not returned through MCP) |
| Circuit breaker | `circuit_breaker.engage`, `circuit_breaker.release` |

The two GitHub API cap operations change the API proxy's per-agent hourly
cap, the same settings as the dashboard's Forge App and agent General
Expand Down Expand Up @@ -795,6 +796,59 @@ Neither operation itself adds or removes a label, approves, or merges
anything. Turning reporter trust on does make later scans mark each held
issue as waiting for triage, with a label and a one-time comment.

`agent.cadences` and `writeback.kind_policy` change two more settings an
owner otherwise changes on the dashboard, through the endpoints those
controls save with. Only the hive's owner can confirm them: the endpoint
refuses any other role.

- `agent.cadences` sets one agent's cadence in one or more governor modes,
through `PUT /api/config/agent/{name}/cadences` (the agent's Cadences
settings). It takes `agent` and `modes`, an object with any of `surge`,
`busy`, `quiet` and `idle`, each a duration such as `1h` or `90m`, or
`pause`. Modes you do not name keep their cadence. A mode the hive does not
configure is refused, because the endpoint would skip it. Time-of-day and
cron schedules are still set on the dashboard. Each mode it sets becomes
operator-owned (`governor.cadence_owners`), as a dashboard edit does, so a
later ACMM level change (`fleet.autonomy_level`) or pack apply no longer
resets it to the pack default. The preview says so.
- `writeback.kind_policy` changes the write-back gate's per-kind overrides
(`writeback.kinds.<kind>`: `min_level`, `require_label`,
`unlabeled_min_level` and `own_only`), through
`PUT /api/config/governor/features` (Settings → Features). `kinds` maps a
kind to the fields to set, with `null` for a field dropping it, or to `null`
to remove that kind's override. An unknown kind or field is refused. That
endpoint replaces the whole override map it is sent, so the preview reads
the current overrides and sends them all with the change merged in: kinds
you do not name keep their override.

For example, to run the scanner hourly when the queue is busy or surging, and
to let the stale-red branch refresh reach pull requests without the opt-in
label at L6:

```json
{"operation": "agent.cadences",
"args": {"agent": "scanner", "modes": {"surge": "1h", "busy": "1h"}}}
```

```json
{"operation": "writeback.kind_policy",
"args": {"kinds": {"base_refresh": {"unlabeled_min_level": 6}}}}
```

The preview shows each mode or kind before and after. It names as widening a
cadence that gets shorter ("scanner runs more often in surge: more spend"),
and a kind that would write at a lower level, without the opt-in label, or on
items the hive did not author. If the agent's cadences or the overrides
change between the preview and the confirm, the confirm is refused; preview
again. Neither operation kicks an agent, labels, approves or merges anything
itself.

The dashboard's write-back kind table edits only `min_level` and
`require_label`, and saving an edit there rewrites every kind's override from
the table, which drops `unlabeled_min_level` and `own_only`. The
`writeback.kind_policy` preview warns when an override it writes carries
either.

`auto_merge.update` changes merge settings, the same settings as the
dashboard's merge controls, through `PATCH /api/config/auto-merge`. It is owner
only.
Expand Down
4 changes: 2 additions & 2 deletions src/docs/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh

| `GET` | `/api/config/agent/{name}` | Dashboard auth/session | Agent Config Get | `pkg/dashboard/api.go:207` |
| `PUT` | `/api/config/agent/{name}/general` | Owner only | Agent Config General | `pkg/dashboard/api.go:208` |
| `PUT` | `/api/config/agent/{name}/cadences` | Owner only | Agent Config Cadences | `pkg/dashboard/api.go:209` |
| `PUT` | `/api/config/agent/{name}/cadences` | Owner only | Agent Config Cadences; each mode sent becomes operator-owned (`governor.cadence_owners`). Wrapped by the admin MCP `agent.cadences` operation | `pkg/dashboard/api.go:209` |
| `PUT` | `/api/config/agent/{name}/models` | Owner only | Agent Config Models | `pkg/dashboard/api.go:210` |
| `PUT` | `/api/config/agent/{name}/pipeline` | Owner only | Agent Config Pipeline | `pkg/dashboard/api.go:211` |
| `PUT` | `/api/config/agent/{name}/hooks` | Owner only | Agent Config Hooks | `pkg/dashboard/api.go:212` |
Expand Down Expand Up @@ -212,7 +212,7 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh
| `PUT` | `/api/config/write-surface` | Owner only | Replace the lane write allowlist; `{"allowlist": {}}` clears it; unknown operation or bad lane name is a 400 with nothing changed | `pkg/dashboard/api.go:566` |
| `GET` | `/api/config/review` | Dashboard auth/session | Review Config Get | `pkg/dashboard/api.go:253` |
| `PUT` | `/api/config/review` | Owner only | Review Config Set | `pkg/dashboard/api.go:256` |
| `PUT` | `/api/config/governor/features` | Owner only | Governor Features | `pkg/dashboard/api.go:262` |
| `PUT` | `/api/config/governor/features` | Owner only | Governor Features; `writebackKinds` replaces the whole `writeback.kinds` map (a kind sent as `null` or `{}` is dropped). Wrapped by the admin MCP `governor.feature_settings` and `writeback.kind_policy` operations | `pkg/dashboard/api.go:262` |
| `GET` | `/api/config/governor/general-advanced` | Owner only | Governor General Advanced Get | `pkg/dashboard/api.go:263` |
| `PUT` | `/api/config/governor/general-advanced` | Owner only | Governor General Advanced Set | `pkg/dashboard/api.go:264` |
| `GET` | `/api/config/auto-merge` | Owner only | Auto-Merge Config Get | `pkg/dashboard/api.go:268` |
Expand Down
4 changes: 2 additions & 2 deletions src/docs/api-reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f

| `GET` | `/api/config/agent/{name}` | Dashboard auth/session | Agent Config Get; `general` carries the API proxy's GitHub API hourly cap: `githubApiHourlyCap` (this agent's `agents.<name>.github_api_hourly_cap`, `null` = inherit), `githubApiHourlyCapEffective` (the cap the proxy applies now; 0 = no cap), `githubApiHourlyCapFleet` (the fleet default) and `githubApiHourlyCapBase` (the base agent of a replica or review head, else empty) | `pkg/dashboard/api.go:207` |
| `PUT` | `/api/config/agent/{name}/general` | Owner only | Agent Config General; `githubApiHourlyCap` sets `agents.<name>.github_api_hourly_cap` (a whole number, 0 = no cap, `null` = inherit the fleet default), applies to the proxy without a restart and to the agent's replicas and review heads; refused (400) on a replica or review head. Audited as `config_agent_general` with the old and new cap | `pkg/dashboard/api.go:208` |
| `PUT` | `/api/config/agent/{name}/cadences` | Owner only | Agent Config Cadences | `pkg/dashboard/api.go:209` |
| `PUT` | `/api/config/agent/{name}/cadences` | Owner only | Agent Config Cadences; each mode sent becomes operator-owned (`governor.cadence_owners`). Wrapped by the admin MCP `agent.cadences` operation | `pkg/dashboard/api.go:209` |
| `PUT` | `/api/config/agent/{name}/models` | Owner only | Agent Config Models | `pkg/dashboard/api.go:210` |
| `PUT` | `/api/config/agent/{name}/pipeline` | Owner only | Agent Config Pipeline | `pkg/dashboard/api.go:211` |
| `PUT` | `/api/config/agent/{name}/hooks` | Owner only | Agent Config Hooks | `pkg/dashboard/api.go:212` |
Expand Down Expand Up @@ -98,7 +98,7 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `PUT` | `/api/config/write-surface` | Owner only | Replace the lane write allowlist; `{"allowlist": {}}` clears it; unknown operation or bad lane name is a 400 with nothing changed | `pkg/dashboard/api.go:566` |
| `GET` | `/api/config/review` | Dashboard auth/session | Review Config Get | `pkg/dashboard/api.go:253` |
| `PUT` | `/api/config/review` | Owner only | Review Config Set | `pkg/dashboard/api.go:256` |
| `PUT` | `/api/config/governor/features` | Owner only | Governor Features | `pkg/dashboard/api.go:262` |
| `PUT` | `/api/config/governor/features` | Owner only | Governor Features; `writebackKinds` replaces the whole `writeback.kinds` map (a kind sent as `null` or `{}` is dropped). Wrapped by the admin MCP `governor.feature_settings` and `writeback.kind_policy` operations | `pkg/dashboard/api.go:262` |
| `GET` | `/api/config/governor/general-advanced` | Owner only | Governor General Advanced Get | `pkg/dashboard/api.go:263` |
| `PUT` | `/api/config/governor/general-advanced` | Owner only | Governor General Advanced Set | `pkg/dashboard/api.go:264` |
| `GET` | `/api/config/auto-merge` | Owner only | Auto-Merge Config Get | `pkg/dashboard/api.go:268` |
Expand Down
10 changes: 10 additions & 0 deletions src/docs/design/admin-mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -635,6 +635,16 @@ Phase 5 registers the fleet-level write operations under that contract:
(`ErrConfirmationStale`) instead of being overwritten. A change that admits more issues without triage, or
that makes Sentinel flag fewer pull requests, is disclosed as widening, and the Sentinel
disclosure names the pull requests that would no longer be held.
- `agent.cadences` and `writeback.kind_policy` wrap `PUT /api/config/agent/{name}/cadences` and
`PUT /api/config/governor/features` (its `writebackKinds` field) for two settings that had no
operation: one agent's per-mode cadences and the write-back gate's per-kind overrides. They use
the same `ConfirmGuard` stale-preview check. The cadence endpoint claims operator ownership of
every mode it is sent (`governor.cadence_owners`), so the op sends only the modes that change
and its preview says each becomes operator-owned, which keeps a later pack apply from resetting
it; a shorter cadence is disclosed as more spend. The Features endpoint replaces the whole
`writebackKinds` map, so the op reads the current overrides and sends them all with the change
merged in, and discloses a kind whose resolved policy (`writeback.Config.Policy`) would write at
a lower level, without the opt-in label, or on items the hive did not author.
- `auto_merge.update` wraps `PATCH /api/config/auto-merge`, the endpoint behind the dashboard's
merge settings. That endpoint replaces every list and map it is sent whole (`squash_only`,
`require_current_base`, `human_merge_paths`, the native merge queue's repos and bases, the
Expand Down
4 changes: 4 additions & 0 deletions src/docs/operator-reference/sweeps-and-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -520,6 +520,10 @@ The gate is per write-back *kind*. Each kind has a minimum ACMM level and
whether the review opt-in label (`review.require_labels`, default
`hive-review`) is required on the PR; both are overridable per kind under
`writeback.kinds.<kind>.{min_level, require_label, unlabeled_min_level}`.
An owner changes these under Settings → Features, or with the admin MCP
operation `writeback.kind_policy`, which also sets `unlabeled_min_level` and
`own_only` and keeps the overrides of kinds it does not name
([admin-mcp.md](../admin-mcp.md#registered-operations)).
The rationale for each default is the same question: does the hive have, at
that level, the power the write-back exists to govern?

Expand Down
1 change: 1 addition & 0 deletions src/pkg/adminmcp/tools_agent_ops.go
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ func DefaultWriteOps() []WriteOp {
ops = append(ops, configSurfaceWriteOps()...)
ops = append(ops, autoMergeWriteOps()...)
ops = append(ops, decisionsWriteOps()...)
ops = append(ops, cadenceWritebackWriteOps()...)
return append(ops, governorWriteOps()...)
}

Expand Down
Loading
Loading