Skip to content

docs(m157): a write-access fleet parks for a human, then ships one draft PR #170

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
indykish merged 2 commits into from
Aug 10, 2026
Merged

docs(m157): a write-access fleet parks for a human, then ships one draft PR #170

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4dee52f
docs(m157): a write-access fleet parks for a human, then ships one dr…
indykish Aug 9, 2026
716eefe
docs(m157): the catalogue lists the incident crew, and the route inde…
indykish Aug 10, 2026
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
8 changes: 8 additions & 0 deletions api-reference/error-codes.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -338,6 +338,14 @@ A conflict response also contains `current_state`. Some errors contain `user_mes
| <span id="UZ-GH-001"></span>`UZ-GH-001` | 409 | GitHub App reconnect required | The GitHub App installation is gone (uninstalled or revoked), so no token can be minted. Reconnect GitHub from the dashboard — the fleet stays blocked until the App is reinstalled. | Keep the GitHub App installed with required repository access. |
| <span id="UZ-GH-002"></span>`UZ-GH-002` | 502 | GitHub token mint failed | GitHub did not return an installation token (upstream 5xx, network, or a malformed exchange response). This is temporary. Retry shortly; if the error continues, check GitHub status and the App configuration. | Keep the GitHub App installed with required repository access. |

### Repairs

| Code | HTTP | Title | Why and fix | Prevent |
|---|---|---|---|---|
| <span id="UZ-REPAIR-010"></span>`UZ-REPAIR-010` | 403 | Write mint requires an approved gate | A write-scoped repository token issues only when this run's event carries an approved repository-write gate. No card was answered for this event, or it resolved to something other than approved — the run continues read-only. Answer the approval card, then let the fleet retry. | Approve the repository-write card before the fleet writes. |
| <span id="UZ-REPAIR-011"></span>`UZ-REPAIR-011` | 403 | Fleet binding changed since approval | The fleet's repository binding no longer matches the one the approval card stated. Re-raise the approval so a human sees the current reach — the mint refuses rather than widening a decided answer. | Approve the repository-write card before the fleet writes. |
| <span id="UZ-REPAIR-012"></span>`UZ-REPAIR-012` | 200 | Duplicate repair link refused | A repair Pull Request already links this incident, so a second one is acknowledged and not recorded. The first shipped repair is the record; close the surplus Pull Request on GitHub. | Let one repair Pull Request carry each incident. |

### Connectors

| Code | HTTP | Title | Why and fix | Prevent |
Expand Down
13 changes: 13 additions & 0 deletions changelog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,19 @@ description: "Stay up to date with the latest agentsfleet product updates, new f
agentsfleet is in **stealth-mode testing** and pre-production. APIs and agent behavior may change between releases without long deprecation windows. Email [agentsfleet@agentmail.to](mailto:agentsfleet@agentmail.to) if you want a hand calibrating an agent or to join as a design partner.
</Tip>

<Update label="Aug 10, 2026" tags={["What's new", "Security", "Integrations"]}>
## A fleet with write access always parks for a human

A fleet whose repository binding declares write access now parks every event at an approval card before anything runs — even when its configuration carries no gates block, and even when its gate rules match nothing. Gate rules are editable with the same permission that wakes the fleet, so they cannot hold this boundary; the write kind itself does. The card states the write blast radius (the repository and what one approval spends), and the evidence line is sealed so crafted backticks in model output cannot break out of its code span.

## What's new

- **`incident-repairer` joins the fleet library.** It wakes on a failed deploy workflow run, reads the incident timeline and the repository at the exact verified head, authors a forward fix, then pushes one branch and opens one draft pull request over the GitHub API — no checkout, no git tooling. A human approves the write before any of it, and a human reviews the bytes on the pull-request diff before any merge.
- **A write-scoped GitHub token spends a recorded approval, never a live setting.** The mint checks the durable gate row for the run's own event — its status, its kind, and the repository binding stated on the card a human actually saw. No recorded approval → `403 UZ-REPAIR-010`. The binding drifted since the card was approved → `403 UZ-REPAIR-011`. Tokens never carry the `workflows` permission, so an approved fix cannot rewrite the pipelines that gate it.
- **A repair pull request is linked to its incident, then to its deploy result.** When the repair branch's pull request opens, the platform records the link in `core.repair_pr_links`; when the next deploy on that branch completes, the row is stamped with the outcome. The stamp matches the repository as well as the branch, so a run finishing on a same-named branch somewhere else cannot claim it. Rows are insert-only — a replayed webhook answers `duplicate_repair_link` (`UZ-REPAIR-012`) rather than overwriting history.
- **A fleet no longer wakes on its own repair.** Pull requests and workflow runs on a repair branch are the crew hearing itself, and a failed one used to look exactly like a fresh incident — so the fleet would set out to fix what it had just written, asking for another approval each time round. That traffic is now recognised and dropped on both webhook routes.
</Update>

<Update label="Aug 01, 2026" tags={["Bug fixes", "UI"]}>
## A runner you assign now runs the work

Expand Down
17 changes: 4 additions & 13 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,8 +155,7 @@
"group": "Tenant balance",
"pages": [
"GET /v1/tenants/me/billing",
"GET /v1/tenants/me/billing/charges",
"GET /v1/tenants/me/billing/charges/{event_id}/telemetry"
"GET /v1/tenants/me/billing/charges"
]
},
{
Expand Down Expand Up @@ -202,14 +201,6 @@
"PUT /v1/workspaces/{workspace_id}/preferences/{pref_key}"
]
},
{
"group": "Fleet keys",
"pages": [
"GET /v1/workspaces/{workspace_id}/fleet-keys",
"POST /v1/workspaces/{workspace_id}/fleet-keys",
"DELETE /v1/workspaces/{workspace_id}/fleet-keys/{fleet_key_id}"
]
},
{
"group": "Secrets",
"pages": [
Expand Down Expand Up @@ -289,14 +280,14 @@
"group": "Fleet events",
"pages": [
"GET /v1/workspaces/{workspace_id}/fleets/{fleet_id}/events",
"GET /v1/workspaces/{workspace_id}/fleets/{fleet_id}/events/{event_id}",
"GET /v1/workspaces/{workspace_id}/fleets/{fleet_id}/events/stream"
]
},
{
"group": "Integration grants",
"pages": [
"GET /v1/workspaces/{workspace_id}/fleets/{fleet_id}/integration-grants",
"POST /v1/workspaces/{workspace_id}/fleets/{fleet_id}/integration-requests",
"DELETE /v1/workspaces/{workspace_id}/fleets/{fleet_id}/integration-grants/{grant_id}"
]
},
Expand All @@ -319,8 +310,8 @@
"DELETE /v1/admin/platform-keys/{provider}",
"GET /v1/admin/models",
"POST /v1/admin/models",
"PATCH /v1/admin/models/{uid}",
"DELETE /v1/admin/models/{uid}"
"PATCH /v1/admin/models/{id}",
"DELETE /v1/admin/models/{id}"
]
}
]
Expand Down
11 changes: 9 additions & 2 deletions fleets/library.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Fleet library
description: Understand platform and workspace library entries.
type: explanation
audience: user
verified: 2026-07-27
verified: 2026-08-10
product_version: 0.25.0
executable: false
---
Expand Down Expand Up @@ -64,7 +64,7 @@ The dashboard protects edits with the row version loaded by the form. If another

## Prebuilt fleets

Four fleets ship as platform entries. Each is a public repository under `agentsfleet`, and each installs by its identifier.
Four fleets ship as their own public repository under `agentsfleet`. Each installs by its identifier.

| Identifier | What it does | Secrets |
| --- | --- | --- |
Expand All @@ -73,6 +73,13 @@ Four fleets ship as platform entries. Each is a public repository under `agentsf
| `zoho-sprint-daily-summarizer` | Summarizes the day's Zoho Sprints activity and posts a digest. | `zoho` |
| `zoho-recruiter-daily-summarizer` | Summarizes the day's Zoho Recruit pipeline and posts a digest. | `zoho_recruit` |

Two more ship as bundle folders inside the `agentsfleet` repository, under `library/`. An operator onboards each one by uploading its folder, not by naming a repository. They are built to work as a pair: the responder finds the cause, and the repairer writes the fix.

| Identifier | What it does | Secrets |
| --- | --- | --- |
| `incident-responder` | Sweeps Grafana and Elastic on a schedule, correlates the telemetry with recent repository history, and posts a diagnosis to Slack and Jira. Its GitHub token is minted read-only, so it can name a fix but cannot open a pull request. | `elastic`, `grafana`, `github`, `jira`, `slack` |
| `incident-repairer` | Wakes on one failed deploy run, reads the repository at the verified head, writes the fix, and opens one draft pull request. It asks for repository write access, so every one of its events parks at an approval card first. | `elastic`, `grafana`, `github`, `slack` |

A prebuilt fleet appears in your library only after an operator onboards and publishes it. Until then it does not show in the gallery.

## Limits
Expand Down
Loading