Skip to content

docs: fill small gaps in http-api, cli, and operations-and-policy #18

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

Closed
cursor wants to merge 1 commit into from
Closed

docs: fill small gaps in http-api, cli, and operations-and-policy #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 4 additions & 0 deletions docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,6 +247,10 @@ flightdeck release promote RELEASE_ID --env ENV --window WINDOW --reason REASON
| `--window` | **Required.** Evidence window used for policy evaluation |
| `--reason` | **Required.** Rationale written to the audit ledger (non-empty) |

The `actor` field written to the audit ledger is resolved automatically from the environment:
`$USER` (Unix), `$USERNAME` (Windows), or `"unknown"` if neither is set. There is no `--actor`
flag on the CLI; the `actor` parameter is only configurable via the HTTP API or SDK.

The currently promoted release for `(agent_id, environment)` becomes the baseline for
the diff. If no release is currently promoted, the first promotion skips policy
evaluation and succeeds unconditionally.
Expand Down
17 changes: 14 additions & 3 deletions docs/http-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,12 @@ flightdeck serve

See [SECURITY.md](../SECURITY.md) for the full trust model.

## Web UI

When the server is running, visiting `http://127.0.0.1:8765/` serves the built React web UI
(`src/flightdeck/server/static/index.html`). Static assets are served from `/assets/*`. The UI
requires no authentication and communicates with the same `/v1/*` routes documented below.

## Base URL

All paths below are relative to the server base URL, e.g. `http://127.0.0.1:8765`.
Expand Down Expand Up @@ -173,7 +179,10 @@ Ingest `RunEvent` records (runtime evidence for diff and policy evaluation).
```

`api_version` may be omitted (defaults to `"v1"`). Any other value returns HTTP 400.
`run_id` must be unique per workspace; duplicates are silently ignored by storage.
`run_id` must be unique within the workspace database; duplicates are silently ignored by storage.

**Empty `events` array:** sending an empty array (`"events": []`) is rejected with HTTP 422
(Pydantic validation — `min_length=1` constraint on the request body).

**Response**
```json
Expand All @@ -195,7 +204,7 @@ Full field reference: [`schemas/v1/run_event.schema.json`](../schemas/v1/run_eve
| `workspace_id` | string | no (defaults to `"ws_local"`) | Workspace identifier for multi-workspace setups. |
| `agent_id` | string | **yes** | Stable agent identifier (must match the `spec.agent.agent_id` in the registered release). |
| `release_id` | string | **yes** | The `release_id` returned by `flightdeck release register`. Links the event to a release record. |
| `run_id` | string | **yes** | Unique run identifier per workspace. Duplicate `run_id` values are silently skipped. |
| `run_id` | string | **yes** | Unique run identifier within the workspace database. Duplicate `run_id` values are silently skipped. |
| `tenant_id` | string | **yes** | Tenant identifier. Used as a filter dimension in diff queries (`--tenant`). |
| `task_id` | string | **yes** | Task type identifier. Used as a filter dimension in diff queries (`--task`). |
| `environment` | string | **yes** | Deployment environment (e.g. `"production"`, `"staging"`). Must match the environment used in promote/rollback. |
Expand Down Expand Up @@ -251,7 +260,9 @@ the audit ledger.
}
```

`window` format: `{N}d` (days), `{N}h` (hours), `{N}m` (minutes). Required.
`window` format: `{N}d` (days), `{N}h` (hours), `{N}m` (minutes). Required. `N` must be a
positive integer (e.g. `"7d"`, `"24h"`, `"30m"`). Zero or negative values and unsupported units
return HTTP 400.
`environment` defaults to `WorkspaceConfig.default_environment` when `null`.

**Response**
Expand Down
5 changes: 4 additions & 1 deletion docs/operations-and-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,9 @@ compute_diff(
3. Load the pricing table for each release (provider + pricing_version from
`spec.pricing_reference`). Missing tables raise `OperationError` with a hint to run
`flightdeck pricing import`.
4. Parse `window` into a `timedelta`; compute `since = now - delta`, `until = now`.
4. Parse `window` into a `timedelta`; compute `since = now - delta`, `until = now`. Valid formats:
`{N}d` (days), `{N}h` (hours), `{N}m` (minutes) where `N` is a positive integer. Invalid
formats raise `OperationError` (HTTP 400 / CLI exit 1).
5. Query `run_events` for each release ID filtered by environment, tenant, task, and the
time window.
6. Call `ledger.diff_releases` to compute per-side rollups (cost, latency, error rate),
Expand Down Expand Up @@ -389,4 +391,5 @@ corresponding check in `test_schemas.py` (or `test_doctor.py`).
| `Pricing table missing model entry` | Pricing table does not list the model used in the release | Add the model to the pricing YAML and reimport with `--replace` |
| `Reason is required for promote/rollback actions` | Empty `--reason` flag | Provide a non-empty `--reason` |
| `No promoted release exists for this agent/environment; nothing to roll back to` | Trying to roll back with no baseline | Promote a release first |
| `Promoted baseline release is missing: rel_...` | A promoted pointer exists in `promoted_releases` but the referenced release row is gone from `releases` (manual DB edit or truncation) | Run `flightdeck doctor` to detect the dangling pointer; re-register the missing release or restore the database |
| `Workspace config not found: flightdeck.yaml` | Missing `flightdeck.yaml` | `flightdeck init` |
Loading