From 69707c25595bc76ada4776cb00475d476ac325e4 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Fri, 14 Aug 2026 14:06:53 +0530 Subject: [PATCH 1/4] docs(m160): login saves a durable credential, one per computer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Records the M160_002 and M136_001 milestone shipped in agentsfleet#600. Changelog: one `` for Aug 14, 2026 — the durable `afc_` credential, the removal of `agentsfleet login --token` and its piped-input path, logout no longer ending a dashboard session, the deployment a credential records, and the boot refusal of `OIDC_PROVIDER=custom`. Pages corrected against source on `main`, not against prose: - `cli/configuration.mdx` — login takes no token on the command line and reads none from piped input. The API Uniform Resource Locator (URL) order is `--api`, `AGENTSFLEET_API_URL`, the server recorded at login, then the built-in URL; the `.env.local` rung it claimed is read nowhere in the client. Adds the `DEPLOYMENT_UNKNOWN` refusal. - `cli/agentsfleet.mdx` — login and logout rows restated. - `api-reference/introduction.mdx` — login saves a durable credential, not a short-lived JSON Web Token (JWT). - `docs.json` — registers the three `/v1/cli-credentials` operations, which the OpenAPI drift check wanted. Catch-up sweep, found while verifying the above: - `api-reference/error-codes.mdx` regenerated from the error registry (`make gen-error-codes`). Beyond `UZ-AUTH-023/024/025` this pulls in drift the page never received: `UZ-FLEETKEY-001` dropped, `UZ-APIKEY-001` pointed at `POST /v1/api-keys`, and the `UZ-AGT-015`, `UZ-EXEC-017`, `UZ-REPAIR-013`, and `UZ-REPAIR-014` rows added. - `api-reference/scopes.mdx` — `fleetkey:read` and `fleetkey:write` do not exist in `auth/scopes.zig`; `approval:read` is included by `approval:resolve`. - `cli/agentsfleet.mdx` — the three `agentsfleet fleet-key` commands have no command, no route, and no OpenAPI path on `main`. `product_version` stays pinned at 0.25.0 across every page, which is what `scripts/check-documentation.py` enforces; `verified` moves to 2026-08-14 on the five pages checked against source today. Co-Authored-By: Claude Opus 5 (1M context) --- api-reference/error-codes.mdx | 35 +++++++++++++++++----------------- api-reference/introduction.mdx | 6 ++++-- api-reference/scopes.mdx | 6 ++---- changelog.mdx | 25 ++++++++++++++++++++++++ cli/agentsfleet.mdx | 9 +++------ cli/configuration.mdx | 18 +++++++++++------ docs.json | 5 ++++- 7 files changed, 68 insertions(+), 36 deletions(-) diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index d1e74fc..8df7b6c 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -3,7 +3,7 @@ title: Error codes description: API error response fields and stable error codes. type: reference audience: user -verified: 2026-07-28 +verified: 2026-08-14 product_version: 0.25.0 executable: false --- @@ -95,6 +95,9 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-AUTH-019` | 400 | Invalid ciphertext | ciphertext is missing or empty. Expect a base64url-encoded AES-256-GCM output. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-020` | 400 | Invalid nonce | nonce is missing, empty, or the wrong length. Expect a base64url-encoded 12-byte value. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-022` | 403 | Insufficient scope | You need an additional scope for that. Ask an agentsfleet admin to grant the scope this action requires. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-023` | 401 | Command-line credential revoked | This credential was revoked — by a logout, by a newer login from the same machine, or from the dashboard. Run `agentsfleet login` to mint a new one. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-024` | 404 | Command-line credential not found | No live credential of yours has that identifier. It may be revoked, or it may belong to someone else; the two answer alike on purpose. List your live ones with `GET /v1/cli-credentials`. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-025` | 401 | Credential exchange failed | Login recovered a browser session but could not exchange it for a durable credential, so nothing was saved. The session lasts about a minute, so this usually means it expired before the exchange. Run `agentsfleet login` again. | Keep sign-in sessions and credentials current. | ### API @@ -103,12 +106,6 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-API-001` | 429 | Too many requests | The API is handling its maximum number of requests. Wait for the Retry-After delay, then retry. | Limit concurrent requests and honor retry delays. | | `UZ-API-002` | 503 | Activity stream capacity reached | The API is serving its maximum number of activity streams. Close unused dashboard tabs or retry shortly. | Limit concurrent requests and honor retry delays. | -### Fleet keys - -| Code | HTTP | Title | Why and fix | Prevent | -|---|---|---|---|---| -| `UZ-FLEETKEY-001` | 404 | Fleet key not found | Fleet key not found. Verify the fleet_key_id. | Use a current Fleet API key for the intended fleet. | - ### Webhooks | Code | HTTP | Title | Why and fix | Prevent | @@ -152,6 +149,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-AGT-012` | 409 | Fleet is paused | This Fleet is paused. Resume it before sending new work. | Use fleet identifiers from the current workspace. | | `UZ-AGT-013` | 500 | Fleet install rolled back | We couldn't finish setting up your fleet. Nothing was created — try again. | Use fleet identifiers from the current workspace. | | `UZ-AGT-014` | 412 | Fleet source is stale | Someone else edited this Fleet's source since you opened it. Reload to see their change, then re-apply your edit. | Use fleet identifiers from the current workspace. | +| `UZ-AGT-015` | 404 | Event not found | We couldn't find that event. It may have aged out, or the identifier doesn't match one on this Fleet. | Use fleet identifiers from the current workspace. | ### Schedules @@ -284,6 +282,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-EXEC-014` | 400 | Run settings invalid | The run settings are invalid. Check the fleet files before retrying. | Check runner settings and access before starting work. | | `UZ-EXEC-015` | 402 | Run stopped: fleet limit reached | The run stopped because the fleet reached its configured limit. | Check runner settings and access before starting work. | | `UZ-EXEC-016` | 401 | Runner token rejected | The control plane rejected this host's agt_r runner token (401/403) on the heartbeat. Retrying can't fix it — mint a fresh agt_r and issue the host's runner token again, then restart the runner. | Check runner settings and access before starting work. | +| `UZ-EXEC-017` | 409 | Assignment exceeds host capability | The policy assigned to this runner needs an enforcement mechanism its host cannot deliver. The runner row names the missing mechanism; fix the host or relax the assignment from the dashboard. | Check runner settings and access before starting work. | ### Approvals @@ -308,7 +307,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-APIKEY-001` | 401 | Invalid API key | API key is invalid or revoked. Mint a replacement with: `POST /v1/workspaces/{ws}/fleet-keys` | Use current API key identifiers and replace revoked keys. | +| `UZ-APIKEY-001` | 401 | Invalid API key | API key is invalid or revoked. Mint a replacement with: `POST /v1/api-keys` | Use current API key identifiers and replace revoked keys. | | `UZ-APIKEY-003` | 404 | API key not found | We couldn't find that API key. It may have already been deleted — refresh the list. | Use current API key identifiers and replace revoked keys. | | `UZ-APIKEY-004` | 401 | API key has been revoked | This key was revoked and can no longer authenticate. Mint a replacement with: POST /v1/api-keys | Use current API key identifiers and replace revoked keys. | | `UZ-APIKEY-005` | 409 | Key name already exists in this tenant | An API key with that name already exists. Pick a different name for this tenant. | Use current API key identifiers and replace revoked keys. | @@ -316,11 +315,21 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-APIKEY-007` | 409 | active cannot be set to true; mint a new key instead | A revoked key can't be reactivated. Mint a new key instead. | Use current API key identifiers and replace revoked keys. | | `UZ-APIKEY-008` | 409 | Active API key must be revoked before deletion | Revoke this key before deleting it. Revoke it first, then delete the revoked key. | Use current API key identifiers and replace revoked keys. | +### Repository repair + +| Code | HTTP | Title | Why and fix | Prevent | +|---|---|---|---|---| +| `UZ-REPAIR-010` | 403 | Write mint requires an approved gate | A write-scoped repository token issues only when this lease's event carries an approved repository-write gate. No approval card was answered for this event, or it resolved to something other than approved. The run continues read-only. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `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. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `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. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `UZ-REPAIR-013` | 403 | Write request allowance exhausted | This approval already funded 32 write-credential requests. Answer a new repository-write approval before another write-scoped token request. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `UZ-REPAIR-014` | 200 | Repair provenance refused | The repair branch did not resolve to an approved write gate with the same workspace, Fleet, event, installation, repository, and App author. The delivery is acknowledged without recording a link or waking a Fleet. | Have a human approve the repository-write gate before the run mints a write-scoped token. | + ### Integration grants | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-GRANT-001` | 403 | No integration grant for service | This fleet has no approved grant for the target service. Request one with: `POST /v1/workspaces/{ws}/fleets/{id}/integration-requests` | Use active integration grants approved for the fleet. | +| `UZ-GRANT-001` | 403 | No integration grant for service | This fleet has no approved grant for the target service. A grant is seeded when the fleet is installed, from the credentials its bundle declares; it becomes usable once its approval gate is resolved. Check the grant with: `GET /v1/workspaces/{ws}/fleets/{id}/integration-grants` | Use active integration grants approved for the fleet. | | `UZ-GRANT-002` | 404 | Integration grant not found | We couldn't find that grant request. It may have already been resolved — refresh the list. | Use active integration grants approved for the fleet. | | `UZ-GRANT-003` | 409 | Grant already resolved | Someone already resolved this. Refresh to see the outcome and who resolved it. | Use active integration grants approved for the fleet. | @@ -338,14 +347,6 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `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. | | `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 | -|---|---|---|---|---| -| `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. | -| `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. | -| `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 | diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 60c6fc8..63992e9 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -3,7 +3,7 @@ title: API introduction description: Base URL, authentication, errors, and common response formats. type: explanation audience: user -verified: 2026-07-22 +verified: 2026-08-14 product_version: 0.25.0 executable: false --- @@ -24,7 +24,9 @@ Use the API when a script or service needs direct access. Use the command-line c Most paths accept a bearer token in the `Authorization` header. Tenant API keys start with `agt_t` and are shown once when created. -Interactive users can sign in with `agentsfleet login`. The login flow saves a short-lived JSON Web Token (JWT). +Interactive users sign in with `agentsfleet login`. Login saves a durable command-line credential that starts with `afc_`. The credential resolves to the person who signed in. + +The credential stays valid until a logout, a newer login from the same computer, or a dashboard revoke ends it. Webhook and connector paths use provider signatures instead of bearer tokens. The OpenAPI security section on each operation states the required method. diff --git a/api-reference/scopes.mdx b/api-reference/scopes.mdx index 81d0665..dab4b74 100644 --- a/api-reference/scopes.mdx +++ b/api-reference/scopes.mdx @@ -3,7 +3,7 @@ title: API scopes description: Permissions that an agentsfleet access token can carry. type: reference audience: user -verified: 2026-07-12 +verified: 2026-08-14 product_version: 0.25.0 executable: false --- @@ -40,8 +40,6 @@ curl -s https://api.agentsfleet.net/v1/fleets -H 'Authorization: Bearer af_test_ | `apikey:read` | Lists tenant API keys. | `apikey:write`, `apikey:admin` | | `apikey:write` | Creates and rotates tenant API keys. | `apikey:admin` | | `apikey:admin` | Revokes tenant API keys. | None | -| `fleetkey:read` | Lists fleet keys. | `fleetkey:write` | -| `fleetkey:write` | Creates and deletes fleet keys. | None | | `grant:read` | Lists integration grants. | `grant:write` | | `grant:write` | Revokes integration grants. | None | | `connector:read` | Reads connector state. | `connector:write` | @@ -50,7 +48,7 @@ curl -s https://api.agentsfleet.net/v1/fleets -H 'Authorization: Bearer af_test_ | `workspace:admin` | Creates and lists workspaces. | None | | `library:write` | Adds an entry to a workspace library. | None | | `platform-library:write` | Adds an entry to the platform library. | None | -| `approval:read` | Reads pending approvals. | None | +| `approval:read` | Reads pending approvals. | `approval:resolve` | | `approval:resolve` | Approves or denies a request. | None | Operator tokens may carry `runner:*`, `platform-key:*`, `platform-library:*`, `model:*`, or `workspace:any`. Tenant integrations do not need these scopes. diff --git a/changelog.mdx b/changelog.mdx index 6659f79..5872d40 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -7,6 +7,31 @@ 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. + + ## Login saves a credential that outlives the browser session + + `agentsfleet login` used to save the browser session token it recovered, and that token is valid for about a minute. A terminal went stale while its operator was still reading the success message, and no renewal path exists. Login now spends that minute on one call to `POST /v1/cli-credentials` and saves the durable `afc_` credential that comes back. The credential resolves to the person who signed in rather than to the tenant, so an audit trail records who ran a command instead of a free-text label. + + ## Breaking changes + + - **`agentsfleet login --token` is gone.** The flag is refused as an unknown option rather than ignored. Piped input goes with it: a login with no terminal attached and no `AGENTSFLEET_API_KEY` fails and names that variable. Unattended callers set `AGENTSFLEET_API_KEY` to a tenant API key, which authenticates every request and writes nothing to disk. + - **`agentsfleet logout` no longer ends your dashboard session.** It revokes this computer's credential, aborts any unfinished sign-in, and clears local state. A browser session is a different credential class that refreshes through the identity provider, so signing out of a terminal leaves the dashboard you are reading signed in. A revoke that cannot reach the server still clears local state, and warns that the credential stays live until you revoke it from the dashboard. + - **A deployment that sets `OIDC_PROVIDER=custom` is refused at boot.** The value selected a second ladder that read capability and workspace claims from `custom_claims`, `app_metadata`, and namespaced keys, none of which anything writes. `OIDC_PROVIDER=clerk` is unchanged, so no deployment that runs today needs editing. + + ## What's new + + - **One live credential per computer.** A second login from the same computer revokes what it left behind, and `core.cli_credentials` carries a partial unique index, so two live credentials for one person and computer cannot be recorded at all. Only a hash is stored. `GET /v1/cli-credentials` lists your live ones and `DELETE /v1/cli-credentials/{id}` revokes one. + - **A credential records the server that issued it.** Later commands reach that server with no flag and no environment variable. The order is `--api`, then `AGENTSFLEET_API_URL`, then the recorded server, then the built-in URL. A saved credential that records no server, dialed at a server nobody named, is refused before anything is sent, with error code `DEPLOYMENT_UNKNOWN` and exit code `1`. The `logout` and `doctor` commands still run, because one ends a credential and the other explains the refusal. + - **Three error codes name what went wrong.** `UZ-AUTH-023` says the credential was revoked, `UZ-AUTH-024` says no live credential of yours has that identifier, and `UZ-AUTH-025` says login recovered a session but could not exchange it, so nothing was saved. A `401` or `403` from the client now names the API URL the credential was presented to. + + ## Security + + - **Minting a credential takes a browser sign-in.** A credential still authenticates listing and revoking, so a terminal can end its own access without opening a browser, but it cannot mint a replacement. Minting used to accept an existing credential, which turned one stolen credential into an unbounded supply under machine names of the caller's choosing. + - **A stored value is checked against its whole shape.** The load path and the mint response both require `afc_` followed by exactly 64 lower-case hexadecimal characters. A prefix check passed values carrying trailing bytes. + - **A tenant API key carries its creator's capabilities.** An `agt_t` key resolves its capability set from the identity provider, keyed on the `created_by` subject the key already stored, instead of a nine-entry set compiled into the binary that no operator could narrow. Narrowing that person narrows every key they minted, on the next request past the cache window. A creator the provider no longer knows resolves to no capability, and an unreachable provider past the staleness ceiling reports unavailable rather than an empty grant. + - **Each claim is read from exactly one key.** The capability claim is `scopes` and nothing else. The reader used to try OAuth2's `scope` first, so a token carrying both would have supplied a capability set we never granted, on the authorisation path. The `scp` spelling and the `workspaceId` alias are unread. + + ## A fleet with write access always parks for a human diff --git a/cli/agentsfleet.mdx b/cli/agentsfleet.mdx index 2613a80..25f7514 100644 --- a/cli/agentsfleet.mdx +++ b/cli/agentsfleet.mdx @@ -3,7 +3,7 @@ title: Command reference description: Commands available in the agentsfleet command-line client. type: reference audience: user -verified: 2026-07-12 +verified: 2026-08-14 product_version: 0.25.0 executable: false --- @@ -63,8 +63,8 @@ Commands: | Command | Effect | |---|---| -| `agentsfleet login` | Signs in through a browser or supplied token. | -| `agentsfleet logout` | Revokes every active session and clears local credentials. | +| `agentsfleet login` | Signs in through a browser and saves a durable credential for this computer. | +| `agentsfleet logout` | Revokes this computer's credential and any unfinished sign-in, then clears local credentials. Browser sessions stay signed in. | | `agentsfleet auth status` | Shows the token source, claims, and server status. | | `agentsfleet doctor` | Checks client settings, authentication, and API access. | @@ -78,9 +78,6 @@ Commands: | `agentsfleet workspace show [WORKSPACE_ID]` | Shows one workspace. | | `agentsfleet workspace secrets` | Prints the secret command and dashboard path. | | `agentsfleet workspace delete ` | Removes one workspace from local client state. Remote data remains. | -| `agentsfleet fleet-key create` | Creates a key bound to one fleet. The raw key appears once. | -| `agentsfleet fleet-key list` | Lists fleet keys without raw values. | -| `agentsfleet fleet-key delete ` | Revokes a fleet key. Calls using that key fail. | | `agentsfleet api-key create` | Creates a tenant API key. The raw key appears once. | | `agentsfleet api-key list` | Lists tenant API keys. | | `agentsfleet api-key revoke ` | Revokes a tenant API key. Calls using that key fail. | diff --git a/cli/configuration.mdx b/cli/configuration.mdx index b9771d9..1a0956c 100644 --- a/cli/configuration.mdx +++ b/cli/configuration.mdx @@ -3,7 +3,7 @@ title: Client configuration description: Environment variables and value order for the agentsfleet client. type: reference audience: user -verified: 2026-07-12 +verified: 2026-08-14 product_version: 0.25.0 executable: false --- @@ -14,7 +14,9 @@ executable: false The client reads command options, environment variables, saved login data, and built-in defaults. A value earlier in the documented order wins. -For authentication, `AGENTSFLEET_API_KEY` overrides the saved login token. The `login` command accepts `--token`, piped input, or browser approval. +For authentication, `AGENTSFLEET_API_KEY` overrides the saved login credential. The `login` command approves in a browser. It accepts no token on the command line and reads no token from piped input. + +Login also records the server it signed into. Later commands reach that same server unless you name another one. ## Example with output @@ -32,22 +34,26 @@ AGENTSFLEET_API_URL=https://api.agentsfleet.net agentsfleet --version |---|---|---|---| | `AGENTSFLEET_API_URL` | Sets the API base URL. | `https://api.agentsfleet.net` | URL beginning with `http://` or `https://` | | `AGENTSFLEET_DASHBOARD_URL` | Sets the browser login URL. | `https://app.agentsfleet.net` | URL beginning with `http://` or `https://` | -| `AGENTSFLEET_API_KEY` | Authenticates every request and overrides saved login data. | None | Valid tenant API key | +| `AGENTSFLEET_API_KEY` | Authenticates every request and overrides saved login data. Nothing is written to disk. | None | Valid tenant API key starting with `agt_t` | | `AGENTSFLEET_STATE_DIR` | Stores local credentials, settings, and telemetry consent. | `~/.config/agentsfleet` | Writable directory path | | `NO_COLOR` | Disables coloured output when set to `1`. | Unset | `1` or unset | | `AGENTSFLEET_TELEMETRY_DISABLED` | Disables usage telemetry when set to `1`. | Unset | `1` or unset | | `DO_NOT_TRACK` | Disables usage telemetry when set to `1`. | Unset | `1` or unset | | `AGENTSFLEET_TELEMETRY_DEBUG` | Prints telemetry details to standard error when set to `1`. | Unset | `1` or unset | -The API URL uses this order: `--api`, `AGENTSFLEET_API_URL`, `.env.local`, then the built-in URL. +The API URL uses this order: `--api`, `AGENTSFLEET_API_URL`, the server recorded at login, then the built-in URL. ## Errors -An invalid URL returns exit code `4`. A missing token returns exit code `1`. +An invalid URL returns exit code `4`. A missing credential returns exit code `1`. A network failure returns exit code `2`. The client does not change saved login data after a network failure. -Do not put tokens in command history. Use `AGENTSFLEET_API_KEY` through your secret manager for unattended commands. +A saved credential that records no server returns exit code `1` with error code `DEPLOYMENT_UNKNOWN`. Nothing is sent. Pass `--api `, set `AGENTSFLEET_API_URL`, or run `agentsfleet login` again. + +The `logout` and `doctor` commands still run in that state. One ends a credential and the other explains the refusal. + +Do not put credentials in command history. Use `AGENTSFLEET_API_KEY` through your secret manager for unattended commands. ## Related pages diff --git a/docs.json b/docs.json index 4e8e340..f618210 100644 --- a/docs.json +++ b/docs.json @@ -125,7 +125,10 @@ "POST /v1/auth/sessions/{session_id}/verify", "DELETE /v1/auth/sessions/{session_id}", "DELETE /v1/auth/sessions/all", - "POST /v1/auth/identity-events/clerk" + "POST /v1/auth/identity-events/clerk", + "POST /v1/cli-credentials", + "GET /v1/cli-credentials", + "DELETE /v1/cli-credentials/{id}" ] }, { From 4176afe76fd9c623b21ef99bd831f66f2f201cb7 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Fri, 14 Aug 2026 14:18:00 +0530 Subject: [PATCH 2/4] docs: pin the documented product version at 0.26.2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `make gen-error-codes` in `agentsfleet` stamps that repository's `VERSION` into the generated front matter, so the generated `error-codes.mdx` has carried `0.26.2` since the release while `scripts/check-documentation.py` still rejected anything but `0.25.0`. Every regeneration failed this repository's own checker. Moves the pin, all 25 published pages, and the checker's own `VALID_PAGE` fixture together — the three places that spell the version. `verified` is untouched: it records the last source check per page, and only the five pages read against source on Aug 14, 2026 carry that date. Co-Authored-By: Claude Opus 5 (1M context) --- api-reference/error-codes.mdx | 2 +- api-reference/introduction.mdx | 2 +- api-reference/scopes.mdx | 2 +- billing/budgets.mdx | 2 +- cli/agentsfleet.mdx | 2 +- cli/configuration.mdx | 2 +- cli/flags.mdx | 2 +- cli/install.mdx | 2 +- concepts.mdx | 2 +- concepts/context-lifecycle.mdx | 2 +- fleets/authoring.mdx | 2 +- fleets/connectors.mdx | 2 +- fleets/install.mdx | 2 +- fleets/library.mdx | 2 +- fleets/overview.mdx | 2 +- fleets/running.mdx | 2 +- fleets/secrets.mdx | 2 +- fleets/tools.mdx | 2 +- fleets/troubleshooting.mdx | 2 +- fleets/webhooks.mdx | 2 +- index.mdx | 2 +- memory.mdx | 2 +- quickstart.mdx | 2 +- scripts/check-documentation.py | 2 +- scripts/test-documentation.py | 2 +- workspaces/managing.mdx | 2 +- workspaces/overview.mdx | 2 +- 27 files changed, 27 insertions(+), 27 deletions(-) diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index 8df7b6c..bff5fda 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -4,7 +4,7 @@ description: API error response fields and stable error codes. type: reference audience: user verified: 2026-08-14 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx index 63992e9..60b7a65 100644 --- a/api-reference/introduction.mdx +++ b/api-reference/introduction.mdx @@ -4,7 +4,7 @@ description: Base URL, authentication, errors, and common response formats. type: explanation audience: user verified: 2026-08-14 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/api-reference/scopes.mdx b/api-reference/scopes.mdx index dab4b74..0604ed7 100644 --- a/api-reference/scopes.mdx +++ b/api-reference/scopes.mdx @@ -4,7 +4,7 @@ description: Permissions that an agentsfleet access token can carry. type: reference audience: user verified: 2026-08-14 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/billing/budgets.mdx b/billing/budgets.mdx index d6e94a0..a09150e 100644 --- a/billing/budgets.mdx +++ b/billing/budgets.mdx @@ -4,7 +4,7 @@ description: Daily and monthly spending limits for one fleet. type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/cli/agentsfleet.mdx b/cli/agentsfleet.mdx index 25f7514..9d0908d 100644 --- a/cli/agentsfleet.mdx +++ b/cli/agentsfleet.mdx @@ -4,7 +4,7 @@ description: Commands available in the agentsfleet command-line client. type: reference audience: user verified: 2026-08-14 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/cli/configuration.mdx b/cli/configuration.mdx index 1a0956c..45eea16 100644 --- a/cli/configuration.mdx +++ b/cli/configuration.mdx @@ -4,7 +4,7 @@ description: Environment variables and value order for the agentsfleet client. type: reference audience: user verified: 2026-08-14 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/cli/flags.mdx b/cli/flags.mdx index 4e350e0..3edfed3 100644 --- a/cli/flags.mdx +++ b/cli/flags.mdx @@ -4,7 +4,7 @@ description: Options accepted by the agentsfleet command-line client. type: reference audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: true --- diff --git a/cli/install.mdx b/cli/install.mdx index 427c50a..8d7f92b 100644 --- a/cli/install.mdx +++ b/cli/install.mdx @@ -4,7 +4,7 @@ description: Install and remove the agentsfleet command-line client. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: true --- diff --git a/concepts.mdx b/concepts.mdx index 699c230..a78727f 100644 --- a/concepts.mdx +++ b/concepts.mdx @@ -4,7 +4,7 @@ description: Understand tenants, workspaces, fleets, tools, events, and runs. type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/concepts/context-lifecycle.mdx b/concepts/context-lifecycle.mdx index 3d53f6e..10103ca 100644 --- a/concepts/context-lifecycle.mdx +++ b/concepts/context-lifecycle.mdx @@ -4,7 +4,7 @@ description: Learn how a fleet keeps useful context during long runs. type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/authoring.mdx b/fleets/authoring.mdx index 88d4c09..a082307 100644 --- a/fleets/authoring.mdx +++ b/fleets/authoring.mdx @@ -4,7 +4,7 @@ description: Create the two files that define a fleet. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/connectors.mdx b/fleets/connectors.mdx index f702d8f..d520002 100644 --- a/fleets/connectors.mdx +++ b/fleets/connectors.mdx @@ -4,7 +4,7 @@ description: Connect a workspace to GitHub, Slack, Zoho Desk, Jira, or Linear. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/install.mdx b/fleets/install.mdx index f8d3943..d34b5cc 100644 --- a/fleets/install.mdx +++ b/fleets/install.mdx @@ -4,7 +4,7 @@ description: Install a fleet from your workspace library. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/library.mdx b/fleets/library.mdx index 99caf6b..3b39d5e 100644 --- a/fleets/library.mdx +++ b/fleets/library.mdx @@ -4,7 +4,7 @@ description: Understand platform and workspace library entries. type: explanation audience: user verified: 2026-08-10 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/overview.mdx b/fleets/overview.mdx index 64125f1..67c2cca 100644 --- a/fleets/overview.mdx +++ b/fleets/overview.mdx @@ -4,7 +4,7 @@ description: Understand what a fleet owns and how its lifecycle works. type: explanation audience: user verified: 2026-07-21 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/running.mdx b/fleets/running.mdx index dc3479f..242af7b 100644 --- a/fleets/running.mdx +++ b/fleets/running.mdx @@ -4,7 +4,7 @@ description: Inspect, message, stop, resume, kill, and delete a fleet. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/secrets.mdx b/fleets/secrets.mdx index b2b9372..95860df 100644 --- a/fleets/secrets.mdx +++ b/fleets/secrets.mdx @@ -4,7 +4,7 @@ description: Store, replace, inspect, and delete workspace secrets. type: how-to audience: user verified: 2026-07-29 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/tools.mdx b/fleets/tools.mdx index 1f5d659..f6d560f 100644 --- a/fleets/tools.mdx +++ b/fleets/tools.mdx @@ -4,7 +4,7 @@ description: Understand the tools that a fleet can call. type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/troubleshooting.mdx b/fleets/troubleshooting.mdx index e3dfde5..291a9a7 100644 --- a/fleets/troubleshooting.mdx +++ b/fleets/troubleshooting.mdx @@ -4,7 +4,7 @@ description: Find and fix common fleet failures. type: troubleshooting audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/fleets/webhooks.mdx b/fleets/webhooks.mdx index 667ad79..67cf7d8 100644 --- a/fleets/webhooks.mdx +++ b/fleets/webhooks.mdx @@ -4,7 +4,7 @@ description: Send signed provider events to a fleet. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/index.mdx b/index.mdx index 6326035..bf6293e 100644 --- a/index.mdx +++ b/index.mdx @@ -4,7 +4,7 @@ description: Create and run event-driven fleets. type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/memory.mdx b/memory.mdx index 254b909..d76c60b 100644 --- a/memory.mdx +++ b/memory.mdx @@ -4,7 +4,7 @@ description: Learn what a fleet can remember between events. type: explanation audience: user verified: 2026-07-18 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/quickstart.mdx b/quickstart.mdx index acbb9f7..8a85b85 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -4,7 +4,7 @@ description: Install your first fleet and send it a GitHub event. type: tutorial audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/scripts/check-documentation.py b/scripts/check-documentation.py index 74b5b6f..2aa516b 100755 --- a/scripts/check-documentation.py +++ b/scripts/check-documentation.py @@ -100,7 +100,7 @@ "UDP", "URL", } -EXPECTED_VERSION = "0.25.0" +EXPECTED_VERSION = "0.26.2" NON_PAGE_CODE_SNIPPETS = {Path("snippets/rates.mdx")} ERROR_REFERENCE_PRIVATE_TERMS = { "API_MAX_", diff --git a/scripts/test-documentation.py b/scripts/test-documentation.py index 4da6bec..8b35471 100755 --- a/scripts/test-documentation.py +++ b/scripts/test-documentation.py @@ -24,7 +24,7 @@ type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/workspaces/managing.mdx b/workspaces/managing.mdx index 16b1098..20d1a60 100644 --- a/workspaces/managing.mdx +++ b/workspaces/managing.mdx @@ -4,7 +4,7 @@ description: Create, select, inspect, and remove local workspace entries. type: how-to audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- diff --git a/workspaces/overview.mdx b/workspaces/overview.mdx index 41293a5..6fce855 100644 --- a/workspaces/overview.mdx +++ b/workspaces/overview.mdx @@ -4,7 +4,7 @@ description: Understand what a workspace owns and separates. type: explanation audience: user verified: 2026-07-12 -product_version: 0.25.0 +product_version: 0.26.2 executable: false --- From a4e239aa38f4808bf741077b377094d637883976 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Fri, 14 Aug 2026 14:45:13 +0530 Subject: [PATCH 3/4] docs(m160): stop pointing users at the credential API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Indy's call, Aug 14, 2026: a user is never told to check with the `/v1/cli-credentials` API, and the list operation is gone from the product — `GET /v1/cli-credentials` had no caller and offered a stolen credential free reconnaissance (agentsfleet#602 removes it). - `error-codes.mdx` regenerated: `UZ-AUTH-024` states the refusal and points nowhere, since there is deliberately no way to enumerate credentials. - `changelog.mdx`: the entry describes what login and logout do and names no endpoint. - `docs.json`: the `GET /v1/cli-credentials` operation row is removed; mint and revoke stay, since the OpenAPI reference still documents what the product itself calls. Committed with OPENAPI_URL pointed at the agentsfleet#602 branch spec — the drift check against `main` stays red until that PR merges, and is clean against the spec this change documents. Merge order: agentsfleet#602 first, then this. Co-Authored-By: Claude Opus 5 (1M context) --- api-reference/error-codes.mdx | 2 +- changelog.mdx | 4 ++-- docs.json | 1 - 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index bff5fda..ef8edc3 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -96,7 +96,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-AUTH-020` | 400 | Invalid nonce | nonce is missing, empty, or the wrong length. Expect a base64url-encoded 12-byte value. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-022` | 403 | Insufficient scope | You need an additional scope for that. Ask an agentsfleet admin to grant the scope this action requires. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-023` | 401 | Command-line credential revoked | This credential was revoked — by a logout, by a newer login from the same machine, or from the dashboard. Run `agentsfleet login` to mint a new one. | Keep sign-in sessions and credentials current. | -| `UZ-AUTH-024` | 404 | Command-line credential not found | No live credential of yours has that identifier. It may be revoked, or it may belong to someone else; the two answer alike on purpose. List your live ones with `GET /v1/cli-credentials`. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-024` | 404 | Command-line credential not found | No live credential of yours has that identifier. It may be revoked, or it may belong to someone else; the two answer alike on purpose. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-025` | 401 | Credential exchange failed | Login recovered a browser session but could not exchange it for a durable credential, so nothing was saved. The session lasts about a minute, so this usually means it expired before the exchange. Run `agentsfleet login` again. | Keep sign-in sessions and credentials current. | ### API diff --git a/changelog.mdx b/changelog.mdx index e5bc424..805fa5b 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -10,7 +10,7 @@ description: "Stay up to date with the latest agentsfleet product updates, new f ## Login saves a credential that outlives the browser session - `agentsfleet login` used to save the browser session token it recovered, and that token is valid for about a minute. A terminal went stale while its operator was still reading the success message, and no renewal path exists. Login now spends that minute on one call to `POST /v1/cli-credentials` and saves the durable `afc_` credential that comes back. The credential resolves to the person who signed in rather than to the tenant, so an audit trail records who ran a command instead of a free-text label. + `agentsfleet login` used to save the browser session token it recovered, and that token is valid for about a minute. A terminal went stale while its operator was still reading the success message, and no renewal path exists. Login now spends that minute exchanging the session for a durable `afc_` credential, and the credential is what reaches disk. It resolves to the person who signed in rather than to the tenant, so an audit trail records who ran a command instead of a free-text label. ## Breaking changes @@ -20,7 +20,7 @@ description: "Stay up to date with the latest agentsfleet product updates, new f ## What's new - - **One live credential per computer.** A second login from the same computer revokes what it left behind, and `core.cli_credentials` carries a partial unique index, so two live credentials for one person and computer cannot be recorded at all. Only a hash is stored. `GET /v1/cli-credentials` lists your live ones and `DELETE /v1/cli-credentials/{id}` revokes one. + - **One live credential per computer.** A second login from the same computer revokes what it left behind, and `core.cli_credentials` carries a partial unique index, so two live credentials for one person and computer cannot be recorded at all. Only a hash is stored, so the credential cannot be read back from anywhere. `agentsfleet logout` is how a computer ends its own. - **A credential records the server that issued it.** Later commands reach that server with no flag and no environment variable. The order is `--api`, then `AGENTSFLEET_API_URL`, then the recorded server, then the built-in URL. A saved credential that records no server, dialed at a server nobody named, is refused before anything is sent, with error code `DEPLOYMENT_UNKNOWN` and exit code `1`. The `logout` and `doctor` commands still run, because one ends a credential and the other explains the refusal. - **Three error codes name what went wrong.** `UZ-AUTH-023` says the credential was revoked, `UZ-AUTH-024` says no live credential of yours has that identifier, and `UZ-AUTH-025` says login recovered a session but could not exchange it, so nothing was saved. A `401` or `403` from the client now names the API URL the credential was presented to. diff --git a/docs.json b/docs.json index f618210..8ef1d8b 100644 --- a/docs.json +++ b/docs.json @@ -127,7 +127,6 @@ "DELETE /v1/auth/sessions/all", "POST /v1/auth/identity-events/clerk", "POST /v1/cli-credentials", - "GET /v1/cli-credentials", "DELETE /v1/cli-credentials/{id}" ] }, From 072b1bef4e53b7ea12607e69bde98a895aec6622 Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Fri, 14 Aug 2026 15:08:10 +0530 Subject: [PATCH 4/4] docs: regenerate error-codes from the plain-language registry sweep MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every hint now states what failed, what is expected, and how to correct it, in short plain sentences — no internal table names, no milestone markers, no cross-references to other codes, no design lectures. 167 codes, no hint over 200 characters. Generated by `make gen-error-codes` from agentsfleet's registry after its plain-language sweep; that change rides the same agentsfleet PR this branch already depends on, so the merge order is unchanged. Co-Authored-By: Claude Opus 5 (1M context) --- api-reference/error-codes.mdx | 66 +++++++++++++++++------------------ 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index ef8edc3..d1e4268 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -51,7 +51,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-UUIDV7-009` | 400 | Invalid identifier shape | The supplied identifier does not match the expected version 7 universally unique identifier shape. | Use identifiers returned by agentsfleet. | +| `UZ-UUIDV7-009` | 400 | Invalid identifier shape | The identifier is not a valid version 7 universally unique identifier (UUID). | Use identifiers returned by agentsfleet. | ### Service failures @@ -84,10 +84,10 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-AUTH-004` | 503 | Authentication service unavailable | Authentication service is temporarily unavailable. Retry shortly. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-005` | 404 | Session not found | Session was not found. It may have expired or been invalidated. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-006` | 401 | Session expired | Your session has expired. Please sign in again. | Keep sign-in sessions and credentials current. | -| `UZ-AUTH-011` | 400 | Verification code did not match | The 6-digit verification code did not match what the dashboard issued. Double-check the code shown in your browser and try again. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-011` | 400 | Verification code did not match | The 6-digit code does not match the one shown in your browser. Re-enter it and try again. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-012` | 410 | Login session already consumed | This login session has already been consumed. Start over with `agentsfleet login`. | Keep sign-in sessions and credentials current. | -| `UZ-AUTH-013` | 410 | Login session aborted | This login session was aborted (too many wrong codes, explicit cancel, or replaced by a newer session). Start over with `agentsfleet login`. | Keep sign-in sessions and credentials current. | -| `UZ-AUTH-014` | 409 | Login session not approved | This login session has not been approved in the dashboard yet. Approve it in your browser before submitting a verification code. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-013` | 410 | Login session aborted | This login session was aborted: too many wrong codes, a cancel, or a newer session. Start over with `agentsfleet login`. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-014` | 409 | Login session not approved | This login session is not approved yet. Approve it in your browser, then submit the code. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-015` | 409 | Login session already approved | This login session has already been approved. Do not call /approve a second time. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-016` | 400 | Invalid command-line public key | The supplied public_key is malformed. Expect base64url-encoded P-256 SubjectPublicKeyInfo. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-017` | 400 | Invalid token name | token_name must contain 1 to 64 characters from space through tilde. | Keep sign-in sessions and credentials current. | @@ -95,16 +95,16 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-AUTH-019` | 400 | Invalid ciphertext | ciphertext is missing or empty. Expect a base64url-encoded AES-256-GCM output. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-020` | 400 | Invalid nonce | nonce is missing, empty, or the wrong length. Expect a base64url-encoded 12-byte value. | Keep sign-in sessions and credentials current. | | `UZ-AUTH-022` | 403 | Insufficient scope | You need an additional scope for that. Ask an agentsfleet admin to grant the scope this action requires. | Keep sign-in sessions and credentials current. | -| `UZ-AUTH-023` | 401 | Command-line credential revoked | This credential was revoked — by a logout, by a newer login from the same machine, or from the dashboard. Run `agentsfleet login` to mint a new one. | Keep sign-in sessions and credentials current. | -| `UZ-AUTH-024` | 404 | Command-line credential not found | No live credential of yours has that identifier. It may be revoked, or it may belong to someone else; the two answer alike on purpose. | Keep sign-in sessions and credentials current. | -| `UZ-AUTH-025` | 401 | Credential exchange failed | Login recovered a browser session but could not exchange it for a durable credential, so nothing was saved. The session lasts about a minute, so this usually means it expired before the exchange. Run `agentsfleet login` again. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-023` | 401 | Command-line credential revoked | This credential was revoked by a logout or by a newer login from this machine. Run `agentsfleet login` to get a new one. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-024` | 404 | Command-line credential not found | You have no live credential with that identifier. It may be revoked, or it may not be yours. | Keep sign-in sessions and credentials current. | +| `UZ-AUTH-025` | 401 | Credential exchange failed | Login could not exchange the browser session for a durable credential, so nothing was saved. The session likely expired. Run `agentsfleet login` again. | Keep sign-in sessions and credentials current. | ### API | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-API-001` | 429 | Too many requests | The API is handling its maximum number of requests. Wait for the Retry-After delay, then retry. | Limit concurrent requests and honor retry delays. | -| `UZ-API-002` | 503 | Activity stream capacity reached | The API is serving its maximum number of activity streams. Close unused dashboard tabs or retry shortly. | Limit concurrent requests and honor retry delays. | +| `UZ-API-001` | 429 | Too many requests | The API is at its request limit. Wait for the Retry-After delay, then retry. | Limit concurrent requests and honor retry delays. | +| `UZ-API-002` | 503 | Activity stream capacity reached | The API is at its activity-stream limit. Close unused dashboard tabs or retry shortly. | Limit concurrent requests and honor retry delays. | ### Webhooks @@ -112,22 +112,22 @@ A conflict response also contains `current_state`. Some errors contain `user_mes |---|---|---|---|---| | `UZ-WH-001` | 404 | Fleet not found for webhook | No fleet is registered for this webhook endpoint. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-002` | 400 | Malformed webhook | Webhook payload could not be parsed. Check Content-Type and body. | Keep webhook signing secrets matched and service clocks synchronized. | -| `UZ-WH-010` | 401 | Invalid webhook signature | Webhook signature verification failed. Confirm the signing secret stored for this provider (Slack/Clerk/other) matches the one configured upstream. | Keep webhook signing secrets matched and service clocks synchronized. | -| `UZ-WH-011` | 401 | Stale webhook timestamp | Webhook request timestamp is outside the allowed 5-minute drift window. This may indicate a replay attack or clock skew. | Keep webhook signing secrets matched and service clocks synchronized. | -| `UZ-WH-020` | 401 | Webhook credential not configured | Create a random webhook secret with at least 32 bytes. Store it as this source's webhook_secret, configure the same value upstream, then resend. | Keep webhook signing secrets matched and service clocks synchronized. | -| `UZ-WH-021` | 404 | Connector installation is not mapped | Reconnect the provider App to the intended workspace before redelivering the event. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-010` | 401 | Invalid webhook signature | The webhook signature did not verify. The stored signing secret must match the one configured upstream. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-011` | 401 | Stale webhook timestamp | The webhook timestamp is more than 5 minutes off. That means a replay or clock skew. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-020` | 401 | Webhook credential not configured | Create a random webhook secret of at least 32 bytes. Store it as this source's webhook_secret, set the same value upstream, then resend. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-021` | 404 | Connector installation is not mapped | Reconnect the provider App to the intended workspace, then redeliver the event. | Keep webhook signing secrets matched and service clocks synchronized. | | `UZ-WH-022` | 404 | No fleet subscription matched | Bind the repository and event to an active fleet with an approved integration grant. | Keep webhook signing secrets matched and service clocks synchronized. | -| `UZ-WH-030` | 413 | Webhook payload too large | Webhook body exceeds the 1 MiB ingest limit. Reduce the payload size or filter at the source. | Keep webhook signing secrets matched and service clocks synchronized. | +| `UZ-WH-030` | 413 | Webhook payload too large | The webhook body exceeds the 1 MiB limit. Reduce the payload size. | Keep webhook signing secrets matched and service clocks synchronized. | ### Slack | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-SLK-010` | 401 | Invalid Slack signature | The Slack request signature did not verify. Confirm the platform Slack app signing secret matches the one vaulted at slack-app/signing_secret. | Keep Slack app credentials, permissions, and clocks current. | -| `UZ-SLK-011` | 401 | Stale Slack timestamp | The Slack request timestamp is outside the allowed 5-minute drift window — a replay attempt or a skewed server clock. | Keep Slack app credentials, permissions, and clocks current. | -| `UZ-SLK-020` | 200 | Slack team not installed | The Slack team that sent this event has no connector install, so the event is acknowledged (200) and ignored. Re-run Connect Slack in the dashboard to (re)install. | Keep Slack app credentials, permissions, and clocks current. | -| `UZ-SLK-022` | 502 | Slack token exchange failed | The Slack OAuth code could not be exchanged for a bot token. Retry the connect flow; if the error continues, verify the platform Slack app credentials. | Keep Slack app credentials, permissions, and clocks current. | -| `UZ-SLK-030` | 502 | Slack answer post failed | The channel bot's answer could not be delivered to Slack (missing chat:write, a 429, or a Slack outage). It is logged and retried with backoff; the run itself never fails. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-010` | 401 | Invalid Slack signature | The Slack signature did not verify. The Slack app's signing secret must match the one vaulted at slack-app/signing_secret. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-011` | 401 | Stale Slack timestamp | The Slack timestamp is more than 5 minutes off. That means a replay or clock skew. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-020` | 200 | Slack team not installed | This Slack team has no connector install; the event is acknowledged and ignored. Re-run Connect Slack from the dashboard. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-022` | 502 | Slack token exchange failed | The Slack OAuth code could not be exchanged for a bot token. Retry the connect flow; if it continues, check the Slack app credentials. | Keep Slack app credentials, permissions, and clocks current. | +| `UZ-SLK-030` | 502 | Slack answer post failed | The answer could not be posted to Slack: missing chat:write, a 429, or an outage. It retries with backoff; the run does not fail. | Keep Slack app credentials, permissions, and clocks current. | ### Tools @@ -261,7 +261,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-RUN-012` | 402 | Lease renewal blocked: no credits | The tenant balance cannot cover another run slice. The lease does not renew, and the run stops cleanly. | Keep runner settings and lease health within configured limits. | | `UZ-RUN-013` | 400 | Renew body malformed | The renew request body could not be parsed. Token counts become zero, but the renewed slice still charges for runtime. The lease still renews. | Keep runner settings and lease health within configured limits. | | `UZ-RUN-014` | 404 | Runner not found | We couldn't find that runner. It may have been removed — refresh the list. | Keep runner settings and lease health within configured limits. | -| `UZ-RUN-015` | 402 | Lease renewal blocked: fleet budget exhausted | The fleet reached its daily_dollars or monthly_dollars limit from `TRIGGER.md`. The lease cannot renew, so the run stops. This differs from UZ-RUN-012, which reports a low tenant balance. | Keep runner settings and lease health within configured limits. | +| `UZ-RUN-015` | 402 | Lease renewal blocked: fleet budget exhausted | The fleet reached its daily_dollars or monthly_dollars limit from `TRIGGER.md`, so the run stops. The tenant balance is fine; this is the fleet's own budget. | Keep runner settings and lease health within configured limits. | | `UZ-RUN-016` | 409 | Active runner must be revoked before deletion | This runner is still live. Revoke it first, then delete it. | Keep runner settings and lease health within configured limits. | ### Runs @@ -281,8 +281,8 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-EXEC-013` | 500 | Runner fleet run failed | The runner could not finish the fleet run. Check the activity stream. | Check runner settings and access before starting work. | | `UZ-EXEC-014` | 400 | Run settings invalid | The run settings are invalid. Check the fleet files before retrying. | Check runner settings and access before starting work. | | `UZ-EXEC-015` | 402 | Run stopped: fleet limit reached | The run stopped because the fleet reached its configured limit. | Check runner settings and access before starting work. | -| `UZ-EXEC-016` | 401 | Runner token rejected | The control plane rejected this host's agt_r runner token (401/403) on the heartbeat. Retrying can't fix it — mint a fresh agt_r and issue the host's runner token again, then restart the runner. | Check runner settings and access before starting work. | -| `UZ-EXEC-017` | 409 | Assignment exceeds host capability | The policy assigned to this runner needs an enforcement mechanism its host cannot deliver. The runner row names the missing mechanism; fix the host or relax the assignment from the dashboard. | Check runner settings and access before starting work. | +| `UZ-EXEC-016` | 401 | Runner token rejected | The control plane rejected this host's runner token. Retrying cannot fix it: mint a fresh agt_r token, re-issue the host's runner token, and restart the runner. | Check runner settings and access before starting work. | +| `UZ-EXEC-017` | 409 | Assignment exceeds host capability | The assigned policy needs an enforcement mechanism this host cannot deliver. The runner row names it. Fix the host or relax the assignment. | Check runner settings and access before starting work. | ### Approvals @@ -299,7 +299,7 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-MEM-002` | 404 | Fleet not found for memory op | The fleet_id does not exist or does not belong to the requesting workspace. Verify the fleet_id and workspace scope. | Use an existing fleet and a valid memory category. | +| `UZ-MEM-002` | 404 | Fleet not found for memory op | The fleet_id does not exist or is not in this workspace. Verify both. | Use an existing fleet and a valid memory category. | | `UZ-MEM-003` | 503 | Saved memory unavailable | Saved memory is unavailable. The fleet uses temporary workspace memory until the service recovers. | Use an existing fleet and a valid memory category. | | `UZ-MEM-004` | 404 | Memory entry not found | That memory entry is already gone — the fleet isn't holding anything under that key. | Use an existing fleet and a valid memory category. | @@ -313,23 +313,23 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | `UZ-APIKEY-005` | 409 | Key name already exists in this tenant | An API key with that name already exists. Pick a different name for this tenant. | Use current API key identifiers and replace revoked keys. | | `UZ-APIKEY-006` | 409 | API key is already revoked | That API key is already revoked. Refresh the list to see its current state. | Use current API key identifiers and replace revoked keys. | | `UZ-APIKEY-007` | 409 | active cannot be set to true; mint a new key instead | A revoked key can't be reactivated. Mint a new key instead. | Use current API key identifiers and replace revoked keys. | -| `UZ-APIKEY-008` | 409 | Active API key must be revoked before deletion | Revoke this key before deleting it. Revoke it first, then delete the revoked key. | Use current API key identifiers and replace revoked keys. | +| `UZ-APIKEY-008` | 409 | Active API key must be revoked before deletion | This key is still active. Revoke it first, then delete it. | Use current API key identifiers and replace revoked keys. | ### Repository repair | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-REPAIR-010` | 403 | Write mint requires an approved gate | A write-scoped repository token issues only when this lease's event carries an approved repository-write gate. No approval card was answered for this event, or it resolved to something other than approved. The run continues read-only. | Have a human approve the repository-write gate before the run mints a write-scoped token. | -| `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. | Have a human approve the repository-write gate before the run mints a write-scoped token. | -| `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. | Have a human approve the repository-write gate before the run mints a write-scoped token. | -| `UZ-REPAIR-013` | 403 | Write request allowance exhausted | This approval already funded 32 write-credential requests. Answer a new repository-write approval before another write-scoped token request. | Have a human approve the repository-write gate before the run mints a write-scoped token. | -| `UZ-REPAIR-014` | 200 | Repair provenance refused | The repair branch did not resolve to an approved write gate with the same workspace, Fleet, event, installation, repository, and App author. The delivery is acknowledged without recording a link or waking a Fleet. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `UZ-REPAIR-010` | 403 | Write mint requires an approved gate | No repository-write approval was answered for this event, so no write-scoped token issues. The run continues read-only. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `UZ-REPAIR-011` | 403 | Fleet binding changed since approval | The fleet's repository binding no longer matches the approved card. Re-raise the approval so a human sees the current reach. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `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. Close the surplus Pull Request on GitHub. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `UZ-REPAIR-013` | 403 | Write request allowance exhausted | This approval already funded 32 write-credential requests. Answer a new repository-write approval first. | Have a human approve the repository-write gate before the run mints a write-scoped token. | +| `UZ-REPAIR-014` | 200 | Repair provenance refused | The repair branch does not match an approved write gate on workspace, Fleet, event, installation, repository, and App author. The delivery is acknowledged and nothing is recorded. | Have a human approve the repository-write gate before the run mints a write-scoped token. | ### Integration grants | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `UZ-GRANT-001` | 403 | No integration grant for service | This fleet has no approved grant for the target service. A grant is seeded when the fleet is installed, from the credentials its bundle declares; it becomes usable once its approval gate is resolved. Check the grant with: `GET /v1/workspaces/{ws}/fleets/{id}/integration-grants` | Use active integration grants approved for the fleet. | +| `UZ-GRANT-001` | 403 | No integration grant for service | This fleet has no approved grant for the target service. Check it with `GET /v1/workspaces/{ws}/fleets/{id}/integration-grants` and resolve its approval. | Use active integration grants approved for the fleet. | | `UZ-GRANT-002` | 404 | Integration grant not found | We couldn't find that grant request. It may have already been resolved — refresh the list. | Use active integration grants approved for the fleet. | | `UZ-GRANT-003` | 409 | Grant already resolved | Someone already resolved this. Refresh to see the outcome and who resolved it. | Use active integration grants approved for the fleet. | @@ -338,14 +338,14 @@ A conflict response also contains `current_state`. Some errors contain `user_mes | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| | `UZ-CRED-001` | 404 | Integration not connected | That integration isn't connected. Connect it from the Integrations page, then try again. | Create required workspace secrets before starting a run. | -| `UZ-CRED-002` | 503 | Credential broker not configured | The on-demand credential broker is not wired on this deployment (a boot-time misconfiguration, not a client error). An operator must configure it before runners can mint credentials. | Create required workspace secrets before starting a run. | +| `UZ-CRED-002` | 503 | Credential broker not configured | The on-demand credential broker is not configured on this deployment. An operator must set it up before runners can mint credentials. | Create required workspace secrets before starting a run. | ### GitHub | Code | HTTP | Title | Why and fix | Prevent | |---|---|---|---|---| -| `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. | -| `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. | +| `UZ-GH-001` | 409 | GitHub App reconnect required | The GitHub App installation was uninstalled or revoked, so no token can be minted. Reconnect GitHub from the dashboard. | Keep the GitHub App installed with required repository access. | +| `UZ-GH-002` | 502 | GitHub token mint failed | GitHub did not return an installation token. Retry shortly; if it continues, check GitHub status and the App configuration. | Keep the GitHub App installed with required repository access. | ### Connectors