Oko
Oko/Docs

Command reference

oko sessions policy

The model policy: a session a provider stopped on its limit is moved to another declared model with capacity, or continued on its own once the provider's wait is over, without anybody retyping it or moving it by hand.

Invocation#

Command
oko sessions policy [--json]; oko sessions policy run [--session ID] [--hours N] [--socket PATH] [--json]; oko sessions policy limit; oko sessions policy limit set --fraction F --ruling RULING --as-said TEXT; oko sessions policy limit unset

Inputs and options#

  • run reads the sessions `oko sessions agents` reads — every one a live process holds — together with every session recorded with a role in supervised work (`oko sessions role`), whether or not a process holds it, and with --hours every one written in the last N hours; it takes each stopped on a provider error that states when the provider may be asked again (providerError.retryAt; a 429 with retry-after-ms is one). --session restricts the pass to that one session.
  • Which models it tries, and in which order, is models.json: the declared models after the one the session runs on, wrapping round. Whether a model has capacity is Brama's answer to a subscription lease for the session on that model's subscription (holder oko): Brama gives one only from a usable member under the operator's sessions-per-subscription limit, setting apart every member its usage ledger refuses. No number is Oko's.
  • --json prints the answer as JSON; without it the same answer is printed as lines.

Output and state effect#

  • While a provider retry time is ahead, the refusal is reported on the session's lease, Brama blocks that member and releases the lease, then another account of the same provider is tried. Otherwise the policy tries the declared models after the current one. A leased candidate is switched through `oko sessions model`; a lease taken for a failed switch is released. If Brama is unreachable or refuses HTTP 403, OMP can choose an enabled account whose latest applicable usage windows show free capacity and records an unleased candidate with the Brama cause and account. Jeden cannot start without Brama. A candidate without a usable measurement is refused; when none can run the decision is waiting with each cause.
  • Once the retry time has passed, the session is continued on its own model with the declared switch message (decision resumed).
  • Each decision — session, decidedAt, decision (switched, waiting, resumed or refused), from, to, retryAt, providerError {status, message}, candidates [{model, subscription, outcome leased | unleased | refused | skipped, detail}] and detail — replaces the session's earlier one in ~/.oko/model-policy.json (written whole under ~/.oko/model-policy.lock). run prints {examined, at, decisions, stalls, interrupted, waits, continuation, spending, capacity, steps}; without run, {lastPass, decisions}: the last pass this machine kept and every kept decision, printed with `last pass by <runner> at <time> examined <n> session(s)`, `last pass by <runner> at <time> was refused: <cause>` or `no model policy pass was kept on this machine`.
  • Oko's service (`oko serve`) runs one pass at every time its declared cron fires (serve.json policyPass, `* * * * *`: the start of every minute), not a Stado routine: a hung call most often waits on Stado's object store or job queue, which a Stado routine would stand on too. Every pass, the service's, `run`'s and the native API's alike, keeps its receipt whole in ~/.oko/model-policy-pass.json — {by, startedAt, at, examined, decisions, stalls, interrupted, waits, capacity, steps, refused: null} or {by, startedAt, at, refused: <cause>} — so a machine where no pass runs is told apart from one where every pass found nothing. steps lists every step of the pass in the order it ran with the seconds it took ({step, seconds} for inventory, provider limits, spending, defect register, repair delivery, continuation, keep decisions, stalls, waits, interrupts and capacity); `run` prints them under its examined line and `oko sessions policy` under its last pass line, as `steps: <step> <seconds>s, …`, and Oko Desktop's Agent sessions prints the same line under the last pass and under the answer of Run model policy (OkoKit's `PolicyPass.steps` and `LastPass.steps`), so a pass that holds the others back names the step that took the time. A pass reads the defect register once and asks Git once per open defect whether its repair is delivered (repair delivery); continuation and capacity both work from that one answer, and a register that cannot be read refuses the continuation and leaves the capacity plan undecided on its work input with the same cause. The service also writes each pass on its log (`serve: model policy pass at <time>: examined <n>, <n> stalled, <n> settled` or `serve: model policy pass refused: <cause>`), and a cron it cannot read stops it from starting (“serve.json declares the model policy pass on `<cron>`, which is not a five-field cron: <cause>”). `oko sessions agents` carries the newest decision on each row as modelPolicy and prints it as `model policy <decision> at <time>: <detail>`. Oko Desktop's Agent sessions shows it under the row, shows the last pass above Run model policy, and runs one pass through the native API's sessions domain (policy, policy_run).
  • Each run also reports every session whose running tool call is stalled (runningTool.stalled, as `oko sessions agents` measures it) under stalls: [{session, supervisor, shape, seconds, norm, outcome}], printed as `stalled: <session> (supervisor <id>) on `<shape>` for <s>s, past the longest of <n> completed call(s) of its <shape|program|tool>, <s>s: <outcome>` — `(no supervisor recorded)` for a session nobody supervises. The norm is the narrowest measurement with a completed call: the call's own shape, else every completed call of the same tool running the same program (a command run with new arguments), else every completed call of its tool (norm.of names which); only a tool never seen completing has no norm. OkoKit's `OkoSessions.runPolicy` answers them as `PolicyPass.stalls`, and Oko Desktop's Sessions screen prints the same line under Run model policy. A stalled command is the defect of the workshop product it runs — the program named by the command's first word (its file name when given by path) whose checkout the workspace holds (`~/Documents/CodingProjects/Wisent/<program>`): the first stall of a shape records a defect against that product (title “`<shape>` runs past every completed call of its shape, leaving the session that runs it waiting”, found in the stalled session, with the measured durations as evidence) and outcome `recorded <id>`; each later stalled call of the shape is noted on that open defect (`noted <id>`) once, and a call already on the defect — the one that recorded it, or one noted before — is `already noted <id>`. A shape that runs no command, or a program the workshop holds no checkout of (`git`, `cargo`), records nothing (`no product: …`). A checkout that cannot be looked at, or a record or note the register refuses, is the outcome (`not recorded: <cause>`), and the pass goes on. `tests/stalls/report.rs` runs three passes over a stalled session against an isolated register (`OKO_DEFECT_REGISTER`); `tests/sessions/policy/stall.rs` hangs a real OMP call in the built service's broker and reads the service's own pass record and interrupt it.
  • Each run continues a stopped executor under a supervisor from Oko's registers: first its own open, unrepaired defects, then an unowned defect claimed for it, then an owed task with a linked open defect. An unlinked task is refused with its identity, not sent as an untracked intervention. With none of those, the pass sends the next repaired defect in that product checkout for an audit of its repair, tests and canonical docs; the audit and any refusal are interventions on the repaired defect. A successful audit delivery is not repeated on another pass. The decision names the item, broker terminal, stopped turn and failure cause; it is retained in the pass, `oko sessions agents` and Oko Desktop. An unreadable register refuses the continuation with the register's cause. Real tests live under tests/sessions/continuation.rs and tests/supervision/.
  • A session is one item. While an assigned item is open, the executor is continued through the guarded `oko sessions send --submit` path. After it is repaired or done, the next item starts in a fresh session of the same harness, model and checkout; its role succeeds the old executor, and the old broker terminal ends. The same fresh-session handover is used for a repaired-work audit. The audit prompt reads `oko defects show`, compares the actual revision against the promised mechanism, tests, docs and changelog, and records a gap as a defect or an observed audit note. A failed handover retains its precise cause instead of claiming the work completed.
  • A supervisor recorded by `oko sessions role set` is continued too when its turn ends while Oko has an open defect, or, with none, a not-done task in the shared task map. The policy submits a supervision pass into that supervisor's broker terminal: read the standing `oko sessions supervision` receipt, agents, defects, task map and blocker graph; inspect stalled executors, hung calls, the install chain and unassigned work. This does not replace the independently scheduled supervision routine. The decision has continuation.kind `supervision`, no individual item, the counted open work and the stopped turn; it is kept on the `oko sessions agents` row and shown in Oko Desktop's Agent sessions. A typed turn is not submitted twice; when the last item closes, no prompt is sent.
  • The real continuation journey is `cargo test --locked --manifest-path rust/Cargo.toml --test sessions-continuation -- --ignored --nocapture`. It requires `OKO_TEST_SOURCE_REVISION` and dedicated stopped supervisor sessions with broker terminals: `OKO_TEST_SUPERVISOR_HOME`, `OKO_TEST_SUPERVISOR_REGISTER`, `OKO_TEST_STOPPED_SUPERVISOR` and `OKO_TEST_SUPERVISOR_DEFECT` for an open-defect pass and unreadable-register refusal; `OKO_TEST_SUPERVISOR_TASK_HOME`, `OKO_TEST_SUPERVISOR_TASK_SESSION` and `OKO_TEST_SUPERVISOR_TASK_ID` for a task-only pass in a separately signed-in ledger. The command refuses an uncommitted source tree, retains the source and binary identity, every command and exit status, the pass, agent row and persisted decision under `.build/`. These fixtures must not be operator sessions.
  • Each run also holds every executor whose account reached the operator's share of a limit window. The account is the credential its newest model call was signed with (message.credentialId in its transcript), named through the harness's credential store (OMP's ~/.omp/agent/agent.db, auth_credentials); the share is the newest reading the harness recorded for that account and window (usage_history used_fraction, with resets_at). At or past the declared share and before the window resets, a turn the executor is in is interrupted with the same Escape `oko sessions interrupt` types, and the continuation above does not type it its next item; once the reset time passes, or a newer reading falls under the share, it is continued again. Each hold is a decision held (or unaccounted, naming why the account is unknown) with {account, window {window, usedFraction, resetsAt, readAt}, detail}; run prints the step's refusal under spending when it cannot run.
  • limit prints the declared share {fraction, ruling, asSaid, said}; limit set declares it from the operator's own words: --ruling names the ruling that holds his message (`oko rulings record`), --as-said the words of it that state the number, and --fraction the number as those words write it; limit unset removes it. The declaration is the register file spending-limit.json (OKO_SPENDING_LIMIT moves it). Oko Desktop's Agent sessions shows the declared share above Run model policy (`executors held at <fraction> of a limit window (ruling <id>: "<words>")`), or the refusal while none is declared, and its Declare and Remove run limit set and limit unset through the native API's sessions domain (policy_limit, policy_limit_set {fraction, ruling, as_said}, policy_limit_unset), each refusal in the command's own sentence.
  • The policy pass also plans executor capacity and retains it under capacity in its answer and receipt: {decidedAt, decision, executors, wanted, start, retire, reason, missing, streams, free, stalled}. One product checkout is one independent stream of open unrepaired defects; Brama's available subscriptions and declared per-member lease limits bound starts. Only models with cited scorecard repair throughput and success can enter the mix; a missing source makes decision undecided with input and cause. A stalled call past its measured norm holds starts. `oko sessions supervision` uses this same plan to start or safely retire executors under Stado; its page describes the actions and refusals. The native policy and policy_run answers and Oko Desktop's Agent sessions read the same OkoSessions.ExecutorCapacity.

Refusals and safe exits#

  • “oko sessions policy takes nothing to show each decision, run [--session ID] [--hours N] for one pass now, or limit [set --fraction F --ruling RULING --as-said TEXT | unset]; it was given <words>” and “oko sessions policy does not take <flag>; …” (exit 2).
  • “no spending limit is declared in <path>: an account's executors are held only at the share of its limit window the operator stated; declare it with `oko sessions policy limit set --fraction F --ruling RULING --as-said TEXT`” — limit and unset with nothing declared, and run's spending step, which then holds nobody. limit set refuses “ruling <id> does not hold the words "<text>"; its message reads: <message>”, “the words "<text>" do not write the fraction <F>; give the number as the operator wrote it” and “--fraction <F> is not a number: <error>”. A credential store that cannot be opened or read refuses the step with its path and cause.
  • “session <id> is not among the sessions the pass reads: no live process holds it and it has no recorded role; name --hours N to read sessions written in the last N hours” (or “… and it was not written in the last N hour(s)”).
  • A decision refused carries its cause word for word: the refusals of `oko sessions model` and `oko sessions resume` (a retiring broker, a full pool), “the provider's retry time has passed, but the session's transcript records no model to continue it on”, and “; the lease taken for it was not released: <cause>” when giving a lease back failed. A session whose ended turn a harness outside Oko's broker holds is not refused: it is continued beside that harness, which the decision names as left running. A model Brama does not lease is listed with Brama's refusal as its detail.
  • If the defect register or, when it has no open defect, the shared task map cannot be read, the supervisor continuation says what read failed; it does not call an empty register healthy. If its terminal or Return refuses the submitted pass, `not continued` retains the broker cause and the work stays open. `oko sessions policy run --session ID --json` and the native policy_run answer show that decision; `oko sessions agents --json` retains its newest cause.
  • “another model policy pass is running: <lock> is locked; the schedule runs the next pass” — only the service's scheduled pass and the supervision routine, which fire again; `run`, the native policy_run and supervision_run, and `oko sessions supervision run` instead wait for the running pass, said on standard error as `czekam: run the model policy pass after the one that is running; gdzie: <lock>; rodzaj: blokada` until it ends, and refuse “run the model policy pass after the one that is running: the lock <lock> cannot be taken: <error>” when the lock cannot be taken at all. “the model policy's decisions in <path> cannot be read: <error>; …”, “the model policy's pass receipt in <path> cannot be read: <error>; Oko writes it whole, so it was changed by hand”, “the pass ran, but its receipt was not kept: <cause>” and “HOME is not set, so the model policy's decisions file $HOME/.oko/model-policy.json has no place”. All of these exit 1.

CLI reference#