Oko
Oko/Docs

Command reference

oko sessions resume

Hands a session a message by continuing it in a new terminal of Oko's broker with its own runtime (`omp --resume` for an OMP session) on the model named or chosen, and answers once the message is the newest prompt of a transcript — whether or not the broker started the session.

Invocation#

Command
oko sessions resume (ID | --since TIME) --text TEXT [--model PROVIDER/MODEL] [--socket PATH] [--json]

Inputs and options#

  • ID is the session id, as `oko sessions agents` prints it; --text is the message, handed to the runtime as its prompt.
  • --since TIME takes the place of ID after a frozen machine or a dead terminal host: every session written since TIME (today, YYYY-MM-DD as that day's start on this machine, or an RFC 3339 time) that no live process holds is resumed with the same --text and --model, one after another. Sessions a live process still holds are listed under running and left alone; each other session answers on its own — the single resume's answer under resumed, or its refusal word for word under refused — so one refused session does not stop the rest. It replaces Jeden's former `jeden restore`, which reopened OMP's sessions outside the broker.
  • --model names the model the session continues on, passed to the harness as its --model (OMP and Jeden take provider/model, such as openai-codex/gpt-6-sol). Without it, OMP chooses a declared model whose provider has an enabled account with measured free usage, preferring the least-used account and then the fewest live sessions; Jeden spreads across the declared mix. Jeden resolves its declared model against Brama's catalog. An old transcript's model is not reused by default.
  • The runtime, executable and arguments come from runtimes.json. Oko first asks Brama for a subscription lease of the chosen model's provider. OAuth OMP accounts are pinned through its auth broker; a sole enabled API key with one measured account is read directly from OMP's credential store without a broker pool. Jeden receives its lease through JEDEN_LEASE. If Brama cannot be asked or refuses HTTP 403, OMP may instead use an enabled account whose latest applicable usage windows show free capacity. The result names the Brama cause, model and account. A pool refusal other than HTTP 403 stops the session.
  • A Jeden session is also handed the lease itself, as Brama's lease document in JEDEN_LEASE. Oko's proxy relays model routes only, so Jeden runs on that lease, names it in its own records, and takes no lease of its own; moving a Jeden session to another account is the model policy's, as for every other harness.
  • A Jeden session is continued in place: its run is also given `--resume-session <the session's directory>` (ledgerResume in runtimes.json), so Jeden continues it with its history and chat memory, and the delivery is proved by the message as the newest task of that same ledger. An OMP session handed over to Jeden opens a ledger of its own, found by the task it opens with.
  • Every Jeden start and continuation is given JEDEN_CHAT=oko-<a new UUID> (newChat in runtimes.json). Jeden keeps one never-ending chat per agent and one process writes a chat, so a session Jeden starts — an OMP session handed over included — begins a chat of its own and never contends with another agent for its workspace's chat; a session Jeden continues stays in the chat it started in, whatever the variable names.

Output and state effect#

  • Records the start in oko_session_deliveries as pending, waits on the kernel's events for the transcript, its directory and the harness's process — no clock — and records the delivery started once the message is the newest prompt of the session's own transcript or of the file OMP moves the session to when another live process still holds it (a header naming the session as its parent). That file is also recorded as the session's continuation.
  • Prints session, runtime, model, state, brokerSession, pid, socket, resumed (the transcript resumed), transcript (where the message landed), moved, spawnedAt, settledAt and attach (`oko sessions attach ID --socket BROKER`). The terminal keeps running the session; `oko sessions send` types into it from then on.
  • With --since it prints {since, running, sessions}: since as the RFC 3339 time it read from, running the sessions a live process still holds, and sessions one {session, resumed} (the answer above) or {session, refused} (the refusal word for word) per stopped session. The native API's sessions domain answers the same to resume_since {since, text, model?}; Oko Desktop's Agent sessions offers it as Resume stopped sessions, with a since field and one message, and lists each session's landing or refusal.

Refusals and safe exits#

  • “oko sessions resume requires <id>”, “oko sessions resume requires --text <text>”, “oko sessions resume --text takes the message to hand the session; it was empty”, “oko sessions resume: --model takes a value; write --model <text>” and “oko sessions resume does not take <flag>; it takes --text, --model, --since, --socket” (exit 2). With --since: “oko sessions resume takes either <session> or --since, not both; …”, “oko sessions resume --since takes today, YYYY-MM-DD or an RFC 3339 time; "<value>" is none of them (…)” and “oko sessions resume --since <time> is in the future” (exit 2).
  • “no transcript of session <id> on this machine: no live transcript root holds a file named for it; `oko sessions agents --hours N` lists the sessions this machine holds”.
  • A Brama lease refusal other than HTTP 403 stops the session and names Brama's status and whole error document. If Brama cannot be asked or refuses HTTP 403, OMP starts only when its credential store has an enabled account with measured free usage for the selected model; the result names the Brama cause. Jeden still requires a lease. An unreadable usage store or no measured free account refuses OMP with that cause instead of silently falling back to an unknown account. If OMP has multiple enabled credentials or measured account keys for an API key with no identity, Oko names that ambiguity and refuses rather than guessing which credential the usage belongs to.
  • For OMP on a lease, the session is not started and the lease is released when the lease names no account (“Brama's lease <id> on subscription <id> names no account, so OMP cannot be held to it …”), when OMP holds no account for it (“OMP holds no <provider> account for <account>, the account Brama leased, so the session was not started; `omp usage accounts --json` lists these <provider> accounts: […]”), when the model is not provider/model, when `omp usage accounts --json` fails (its exit and stderr) and when the auth broker ends before it logs `auth-broker listening` (its exit and what it logged).
  • “session <id> has a live process writing it (pid <pids>); its newest record is <record>, so its turn has not ended and a resume would start a second writer of the same work; …”, naming the broker terminal to type into with `oko sessions send` when it runs in one. A broker terminal started on the session holds it even after the harness rewrote its transcript in place. A live process whose turn has ended does not refuse — an answer that calls no tool, or a turn the provider ended (stopReason error or aborted). Silence alone never permits a second writer: an unfinished tool call remains protected for as long as its writer holds the transcript. The CLI and Desktop resume action use this same admission check.
  • “session <id> was not resumed: Oko's broker terminals could not be read, so whether one still runs it is unknown (<cause>)”: not knowing whether a terminal runs the session is not read as nobody does. `oko sessions model` refuses the same way (“session <id> was not switched: …”).
  • “session <id> was not resumed: its transcript <path> records no working directory to continue it in” and “session <id> was not resumed: the delivery could not be recorded in oko_session_deliveries (<cause>); nothing was started”.
  • “<runtime> sessions cannot be resumed by this machine: runtimes.json declares how to continue claude, codex, jeden, omp only” and “no agent runtime to resume the session with: <runtime> is not installed at any declared path (<paths>)”.
  • “runtimes.json starts <runtime> with --model, and neither --model nor models.json names a model <runtime> runs”; for Jeden, “the model `<name>` could not be resolved to an id Brama serves: Brama's catalog was not read (<cause>)”, “Brama's catalog lists no model whose id has `<name>` as a part; it lists <ids>” or “Brama's catalog lists <n> models whose id has `<name>` as a part and none states when it was created, so the newest cannot be told: <ids>”, each ending “; rust/src/pty/client/models/models.json chose `<name>` for a jeden session”.
  • “session <id> was not resumed: <executable>, broker <terminal>, pid <pid> (not running): the message was not observed as the newest prompt of the session's transcript or of one beside it, and no transcript open or write was observed after <n>s; terminal output: …” when the terminal ended without the message landing; the delivery is recorded refused with that screen. All of these exit 1.

CLI reference#