Oko
Oko/Docs

Command reference

oko sessions audit

Every recorded session on this machine, from the oldest transcript to the newest, diagnosed for the operator's lost time by an OpenAI model through Brama, with every finding checked against the session's own transcript before it is kept.

Invocation#

Command
oko sessions audit run [--session ID] [--json]; oko sessions audit list [--json]; oko sessions audit show ID [--json]

Inputs and options#

  • run reads every session transcript this machine holds (the roots `oko sessions agents` reads), oldest first; --session ID audits that one. OKO_AUDIT_MODEL_ALIAS names the Brama alias of the OpenAI model that writes each diagnosis; Oko runs no model of its own.
  • The model is given the session's turns, numbered from one, each with its time and speaker: the operator's messages and the agent's own words, without tool calls or tool results.

Output and state effect#

  • The model answers by one record_diagnosis call: a summary and findings, each with what was lost, the first and last turn of the stretch and passages quoted from it. Oko checks each finding against the transcript: its turns must exist and be in order, and every quote must appear word for word in them. A finding that holds carries lostSeconds, the time between its first and last turn as their own records date them (null when a turn records no time); one that does not carries why (“turns <a>..<b> are not turns of this session, which has <n>”, “"<quote>" is not in turns <a>..<b>”, “it quotes nothing”). The verdict is checked when every finding holds and partly refused otherwise; a session with no turns is kept as no turns.
  • Each verdict {session, transcript, transcriptWrittenAt, auditedAt, model, summary, findings, held, refused, lostSeconds, verdict} is written to ~/.oko/session-audits.json as soon as it is checked, so a run that stops keeps what it audited. A session already audited at its transcript's current time is not asked again; one whose transcript was written since is audited anew. run prints {audited, alreadyAudited, failed, register}, each failure with its session and cause, and names each session on standard error as it is asked.
  • list prints every kept verdict; show prints one. Without --json each is one line: session, verdict, held and refused findings, lost seconds and the summary.

Refusals and safe exits#

  • “no audit model is declared: set OKO_AUDIT_MODEL_ALIAS to the Brama alias of the OpenAI model that writes each session's diagnosis; Oko runs no model of its own”.
  • A session whose transcript cannot be read, or whose diagnosis Brama or the model refused, is listed under failed with the cause and the run goes on: “Brama could not be asked for the audit model <alias>: <cause>”, “Brama answered the audit model <alias> with HTTP <status>: <body>”, “<model> answered <n> record_diagnosis calls where exactly one is required: <answer>”, “<model> called record_diagnosis with no arguments string: <answer>”, “<model> answered no JSON diagnosis: <arguments>” and “<model>'s diagnosis carries no findings list: <answer>”.
  • “oko sessions audit run --session <id>: this machine holds no transcript of it; looked in <roots>”, “oko sessions audit show <id>: no audit of it is recorded in <path>; `oko sessions audit run --session <id>` audits it”, and a register that cannot be read or written, named with its path. These exit 1; “oko sessions audit takes run [--session ID], list, or show ID, each with --json; it was given <words>” exits 2.

CLI reference#