Command reference
oko tasks read
Has Oko’s model read what each operator message is to the ledger, for the messages that have no reading yet, oldest first.
Invocation#
oko tasks read [--limit N] [--json]Inputs and options#
- --limit N, a positive whole number, is how many messages one run reads; without it the run reads every unread message, and every oko tasks control pass reads them all. Anything else is refused as “oko tasks read: --limit takes a positive whole number, got <value>”.
Output and state effect#
- Pages through the shared operator messages oldest first, so old decisions cannot starve behind new sessions. The shared database pages at its declared size. Oko skips each message with a complete reading or one recorded by a session or the operator with `oko tasks kind`, and asks Brama’s decision route two typed choices per message in one request, with the complete message as state: its kind and whether it shows frustration with the agent, each defined in prose in Oko’s reading declaration. Each answer is kept by the message’s identity with route, confidence when stated and time. Every ledger reader, `oko stats snapshot`, `oko frustration scan` and `oko index sync` consumes that reading. A model reading kept before the frustration question existed has no `frustrated` value and is read again.
- On a machine without Brama, where `oko model-service set` declared an OpenAI-compatible service, the same two choices go to that service’s declared model in one `POST /v1/chat/completions`, which must answer one JSON object naming the kind and the frustration choice, with a confidence from 0 to 1 kept when it states one; the reading is kept the same way, with that model as the one that answered. A reply that names no offered choice refuses with “<model> answered no kind this reading offers: <reply>” or “<model> answered no frustration choice this reading offers: <reply>”, one with no JSON object with “<model> answered no JSON reading: <reply>”, and a refused call with “<origin> refused the reading with HTTP <status>: <answer>”.
- Prints `read`, one entry per message with `messageId`, `sessionKey`, `ordinal` and `kind`, and `refusal`, null when all reads succeeded. The control pass keeps the same object under `reading` in `oko_control_passes`, followed by `coverage` with the remaining count, oldest dated message and undated count. A coverage refusal is separate from a model refusal; both carry the actual cause in the pass failures.
- Before reading, every answered ask of the signed-in member whose answer is not yet stored is kept as that member's steering in the session `ask-<id>` (`oko asks answer` does this itself; an answer Oko iOS wrote straight to the database arrives here). `answers` lists the asks `kept` and the ones `refused` with their cause; a refused ask does not hold back the others or the reading.
- A one-shot `oko tasks control --session ID --json` prints the retained pass but exits unsuccessfully when the reading model or coverage check refuses, naming the same cause on stderr. The scheduled routine keeps the failure and current stage in its pass instead of claiming an empty successful backlog.
Refusals and safe exits#
- The first refusal ends the run, since the next message would meet the same one: the JSON is printed with the gateway’s answer in `refusal` (“<route> refused the reading with HTTP <status>: <start of the answer>”, “<route> answered no frustration choice this reading offers: <answer>” when the route answered the kind alone, or the unreachable gateway’s own detail) and the command exits unsuccessfully with “the model could not read the next message: <refusal>”. The refusal is also recorded as the judge's health (`oko_judge_health`, observed by `oko tasks read`, and its local copy judge-health.json), so every ledger reports its unread messages with that refusal and Tama's gates read it without a network call until a later read or probe records the route answering again. Messages read before it stay kept. A shared database that cannot be read or written refuses with its own error.