Oko
Oko/Docs

Command reference

oko sessions deliver

Delivers every queued post of one batch, or of every batch, as the process a send starts does: a post is claimed by one deliverer at a time, so no message is typed twice.

Invocation#

Command
oko sessions deliver [--batch BATCH] [--socket PATH]

Inputs and options#

  • --batch names one batch folder under the posts folder; without it every batch is read.

Output and state effect#

  • Reads the role register once and the machine's agent sessions only when a target is a broker terminal rather than a session; compares each executor's text with the operator's rulings once per text, through Brama when it answers; reads the kept standing once (see `oko sessions scorecard`); then for each post records the intervention on its defect and the instruction as a send does, types the text (and Return with --submit) or leaves it in the target's inbox, and keeps the post delivered {reached, standingTone, settledAt} or refused {cause, settledAt} with its judgment {verdict, cause, by, at}.
  • A send never waits on Brama: when Brama gives no judgment (no declared service, no live lease, a 503) the message is delivered and its judgment is unjudged with that cause, and its batch is listed in the posts folder's unjudged.json. When Brama answers during a later delivery, every unjudged post is judged then (judgedLater); a judge that refuses a text refuses its posts, and one delivered unjudged and later refused is kept as refused after it was delivered. `oko sessions posts --judge` asks again, and the sending session may record its own model's judgment with `oko sessions posts --record`.
  • A post a deliverer took and never settled because that process ended is read in its target's own transcript before anything is settled. Found there (a message addressed to the session holding its text, written at or after it was queued), it is delivered {reached: “<target>: its transcript took it at <time>, though deliverer pid <pid> ended before settling it”}. Otherwise it is interrupted {deliverer, cause, settledAt}, neither delivered nor refused, and never typed a second time: “deliverer pid <pid> ended while delivering it and <target>'s transcript does not hold it, so whether the handoff reached it is unknown; it is not typed a second time”, or with “whether it reached <target> cannot be read: <why>” when no transcript of the target is on this machine or it cannot be read. Prints {settled: [posts], judgedLater: [posts], seconds: {claim, bind, judgeToneAndType, judgeLater}}.
  • A submitted post goes to the target's inbox when the reader its inbox records runs Oko's inbox extension of the digest this Oko installed (`location.json` beside the extension, `extension` in the reader record): that reader steers it into the running turn, read at the next tool boundary, or starts a turn with it when the session is idle. OMP loads an extension when it starts, so an OMP started before an install keeps the extension it loaded; a reader of another digest, or of one that records none, is not used, since the older extension hands a message only once the turn ends. The answer says the post is queued, never that it arrived: “queued in the inbox of session <id> (<file>), read by pid <pid> … not delivered yet: `oko sessions inbox <id>` names it delivered once the reader handed it to the session”, and the defect's intervention records “message handed to <where>”. `oko sessions inbox <id>` lists each message as waiting, delivered, refused or unconfirmed.

Refusals and safe exits#

  • An unknown flag refuses (exit 2); a batch folder, post or claim that cannot be read or written refuses naming the file. A post's own refusal (no defect for a supervised executor, a judge's refusal, a standing that cannot be read with --as-standing, a terminal that cannot be reached) settles that post and not the others.
  • The busy-turn guard uses the existing reverse transcript reader with the file system's observed block size, expanding until it finds the newest message or reaches the beginning. It has no fixed byte window that can hide a long message. Malformed JSON refuses with its transcript path, byte position and parse cause. A message without a string role, or an assistant message without a string stopReason, refuses because an ended turn has not been established; missing data is not treated as idle. CLI delivery and Desktop-originated posts use the same guard and diagnostics.
  • When an observed agent is named by its broker-terminal alias, delivery uses the canonical session identity already established by the intervention binding. The alias therefore reaches the same steering inbox and current-turn safeguard as the session ID, rather than bypassing them through raw terminal typing. A terminal with no observed agent keeps the existing bare-terminal behavior; identity is not guessed from the text or executable name.
  • Immediate continuation messages use the same ended-turn guard as an ordinary submitted send when no steering inbox accepted them. A routine's earlier observation that a turn ended is not sufficient: the current transcript is checked again before terminal delivery or continuation. A newly busy session refuses with the same actual transcript-state and stale-reader cause rather than receiving a follow-up behind its running turn.
  • A submitted post to a session in its turn (its last message record is a user message, a tool result or an assistant message that stopped for a tool) whose inbox is not read with the current extension is refused, and nothing is typed: “session <id> is in its turn (<record>) and nothing was typed: OMP keeps text typed into a session that is answering as a follow-up, read only once the turn ends, which may be hours; <why its inbox is not read>”. A session outside the broker whose reader is gone, of another extension, or none refuses with “session <id> runs outside Oko's broker (pid …), so nothing can be typed into it, and nothing was left for it: <why>”.

CLI reference#