Oko
Oko/Docs

Command reference

oko report

Inspect fleet delivery and usage by executor, model, provider, product and organization member. This is the report projection of sessions scorecard, not a separate metrics store.

Invocation#

Command
oko report [--hours N] [--socket PATH] [--json|--plain]

Inputs and options#

  • --hours bounds observations by their recorded timestamp; omit it for retained history. --socket selects the broker. --json is the default; --plain uses the shared structured-text printer.
  • Organization-scoped task claims, bound verdicts, qualification receipts and transcript ownership; the local defect lifecycle register, interruption history and measured assistant usage. The report does not refresh qualifications or modify any source.

Output and state effect#

  • groups contains each recorded dimension/name, its metrics and UTC daily trend. sources maps every citation to its register, record identity and observed fields. observations retains the inputs to aggregation. A metric with incomplete evidence has a null value and a named refusal, not an invented zero.
  • tasks_taken counts distinct task positions whose current claim was recorded in the window. tasks_closed requires a done verdict bound to the current request and defects, with the existing qualification policy applied. Defect discovery, repair and closure counts remain separate. Withdrawn positions are not closures.
  • Repair duration starts at defect discovery; closure duration starts at the task request or defect discovery. Median and p90 use linear interpolation of sorted observed durations (R7), including even-sized samples. Each distribution cites the records that supplied its endpoints.
  • repair_success_rate compares repair attempts with current-policy release-queue behavioral qualification receipts against attempts later reopened. A reopening retains the withdrawn revision and repair timestamp atomically and defeats an earlier pass. A recorded commit, published artifact or fixed field alone is not a behavioral-test pass. Legacy records without typed attempt history are explicitly refused for this metric.
  • closed_items_per_hour rates speed on each group (each model, executor, provider, product and member) over the window --hours names: value is the group's distinct closed tasks and fixed defects divided by those hours, with items and hours beside it and the closure records cited. Without --hours it is refused with `a rate per hour needs the window it is measured over: give --hours N`; a window in which the group closed nothing is refused with `no task closed and no defect fixed in the <h> h window`, and an unread closure source is refused with that source's named failure. Read it beside repair_success_rate for quality and repair_seconds for repair duration: `oko report --hours 24 --json` shows which model closes most per hour, which repairs survive and which repairs fastest.
  • queue_passed and queue_failed separately describe Stado delivery-register outcomes, not behavioral qualification. Each cites release_queue fields including the failed step and error. release_seconds measures matching repair to released_at; record_seconds measures matching repair to recorded_at for defects actually recorded by the queue. Missing historical timestamps are refused. Qualification completion uses the platform evidence completed_at timestamps, never Oko's mutable checkedAt refresh time, and a success receipt must explicitly cover the defect.
  • Tokens count contextSnapshot.promptTokens actually sent on assistant calls, using the same basis as telemetry inputs. Model and provider come from each recorded call. Cost separately uses billable usage counters and an exact source-backed API price-catalog entry; it is not an invoice or subscription charge. Missing prompt measurements, counters, prices or rates are named. Tokens and estimated cost per closed item divide the window's measured usage by its source-backed task and defect closure positions; this does not pretend to allocate a call to one task. Repeated identical call records are counted once; conflicting records sharing a call identity refuse the measurement.
  • Product attribution requires all applicable session claims to have an unambiguous qualification product; missing or conflicting qualifications cannot be silently dropped. Both claim and qualification records are cited. The report never guesses a product from a directory or a provider from a model name. Model attribution for lifecycle work uses the last recorded model call at or before that event. Missing attribution refuses the affected dimension.
  • Hangs count recorded interrupted calls whose measured duration exceeded their matching-call norm, deduplicated by session and call start. Repeated questions count subsequent identical operator-ask questions under the same subject. Repeated defect shapes count subsequent discoveries sharing their recorded shape class. The report does not classify free text with a keyword list.
  • The native sessions/report action and OkoSessions.report(hours:) return this projection. sessions/scorecard also embeds it as report. Oko Desktop → Work → Sessions → Scorecard → Fleet report shows dimension selection, metrics, daily trend, repeated classes, named refusals and expandable source records without recalculating values.
  • Start with oko report --json to retain an auditable snapshot, or oko report --plain to inspect named sources in a terminal. In Desktop, choose a dimension and expand a metric's Source records before comparing executors; a refusal means the comparison lacks evidence, not that the executor produced nothing.
  • The real tests/report/journey.rs qualification invokes the built CLI and native service, records an isolated defect through normal commands, records a repair, updates its evidence without resetting the attempt timestamp, reopens it, inspects persisted lifecycle evidence and checks the report against those records. Run cargo test --manifest-path rust/Cargo.toml --test fleet-report -- --nocapture only in the authorized release qualification stage. Reports retain revision, binary digest, commands, exits, stdout and stderr. Test source alone is not a passing result.
  • The ignored tests/report/rate.rs journey reads oko report --hours N --json and oko report --json through the built CLI and native service against the qualification account's own registers, which the report only reads. Over the window OKO_TEST_REPORT_HOURS names it checks that every rated group's value is its tasks_closed plus defects_fixed divided by those hours and that every figure stays cited; without the window it checks that every group's rate is refused naming --hours.
  • Before recording the fixture repair, the journey verifies that an absent criterion report is refused without changing the register. It then calls defects show --json and compares the complete answer with the persisted isolated defect. Only that observed readback produces a criterion report: defect identity, declared criterion, tested source revision, binary and test digests, command streams and exit status, and observed final state. Both initial and repeated repair calls use retained report paths rather than prose evidence. The combined qualification report embeds those observations; they are evidence for the isolated readback criterion, not a release-queue pass for fleet delivery.

Refusals and safe exits#

  • Malformed or non-positive --hours, missing --socket values, unknown flags and unsupported verbs are named usage refusals. Missing organization records, lifecycle history, transcript usage, attribution or price data appear beside the affected metrics with null values and source names.
  • A failed organization read is not an empty fleet. No denominator means no success or per-closure rate. Every source lookup failure remains visible in the report and Desktop.

CLI reference#