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

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

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

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.