klieo-ops-api 3.8.2

Read-only HTTP monitoring router for klieo agentic systems.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

# klieo-ops-api

Read-only HTTP monitoring router for klieo agentic systems.

Mount at `/_ops` to expose operator visibility into agent runs, A2A tasks, and MCP stream state.

## Quickstart — laptop-dev

```toml
[dependencies]
klieo-ops-api = { version = "3", features = ["dev-auth"] }
```

```rust
use klieo_ops_api::OpsRouterBuilder;

# fn run() -> Result<(), klieo_ops_api::OpsBuilderError> {
let router = OpsRouterBuilder::new()
    .with_dev_auth()
    // .with_run_log_store(run_store) — wire your stores here
    .build()?;
# let _ = router; Ok(()) }
```

`with_dev_auth()` wires `AllowAnonymous` and is gated behind the
`dev-auth` feature (CWE-1188). Production builds without that feature
cannot reach the permissive authenticator. **Never** enable
`dev-auth` on a multi-tenant network — bind to loopback or a dev
container only.

## Cargo features

| Feature | Default | Purpose |
|---|---|---|
| `dev-auth` | off | Surfaces `OpsRouterBuilder::with_dev_auth()`, which wires `AllowAnonymous`. Laptop-dev only; CWE-1188. |
| `test-fixtures` | off | Activates `klieo-auth-common/test-fixtures` + `klieo-core/test-utils` for downstream test harnesses. |

## Production wiring

```rust
use std::sync::Arc;
use klieo_auth_common::Authenticator;
use klieo_ops_api::OpsRouterBuilder;

# fn run(auth: Arc<dyn Authenticator>) -> Result<(), klieo_ops_api::OpsBuilderError> {
let ops = OpsRouterBuilder::new()
    .with_authenticator(auth)
    // .with_run_log_store(run_store)
    // .with_task_store(task_store)
    // .with_resume_buffer(resume_buf)
    .build()?;
# let _ = ops; Ok(()) }
```

## Endpoints

| Endpoint | Store required | Description |
|---|---|---|
| `GET /_ops/runs` | `RunLogStore` | List agent runs (filter: `agent`, `status`, `limit`, `needs_reconciliation`) |
| `GET /_ops/runs/{id}` | `RunLogStore` | Get full run detail with steps |
| `GET /_ops/runs/{id}/reconciliation` | `RunLogStore` (+ `KvStore`) | What a failed run left behind — see below |
| `GET /_ops/agents` | `RunLogStore` | Per-agent run count aggregation |
| `GET /_ops/tasks` | `A2aTaskStore` | List A2A tasks by `context_id` |
| `GET /_ops/streams` | `KvResumeBuffer` | List active MCP stream checkpoints |

Missing stores return `501 Not Implemented`. Auth is pluggable via `klieo-auth-common::Authenticator`.

## Reconciliation worksheet

klieo does **not** roll back side effects. `GET /_ops/runs/{id}/reconciliation`
reports what a failed run left behind, split into `committed_effects` (the tool
returned success; the effect exists) and `attempted_unknown` (nobody can
confirm the outcome).

`GET /_ops/runs?needs_reconciliation=true` is the triage list. The filter is
pushed down to the store, so it applies before the row limit rather than
thinning an already-truncated page.

Wire a `KvStore` (`with_kv_store`) to recover calls that were dispatched on
resume but never confirmed. Without one the endpoint does not fail — it returns
the committed half, which comes from the run log and is always complete.

Unlike the `klieo-ops-viz` lens, this surface serves **raw** argument and result
values. It is the surface to use when you need the actual amount and account.

Background: [ADR-055](../../docs/adr/adr-055-agent-loop-compensation.md) ·
[recipe](../../docs/book/src/recipes/reconcile-a-failed-run.md) ·
`cargo run -p reconcile-failed-run`.