# 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 = "2", 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`) |
| `GET /_ops/runs/{id}` | `RunLogStore` | Get full run detail with steps |
| `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`.
