Skip to main content
run.events() yields NikaRunEvents: a lifecycle kind that means the same on both transports, the task a task.* event names, the engine’s own status word, and the exact engine frame on event.raw.
events.mts

How many events, on which door

The vocabulary is one; the number of events is not. For the quickstart’s one-task hello.nika, measured on 0.123.0: A server job admitted with a non-empty inputs map opens with one more, an engine.event for the server’s execution.queued frame (sequence 1, with no status; the frame’s queued stays on event.raw.status). A failing task adds task.failed locally (with event.error), and the settlement reads failed. Locally, a skipped task adds task.skipped (one skipped by on_error: { skip: true } keeps the error that made it skip on event.raw), a cancelled task adds task.cancelled, and a task that a resumed run (nika run --resume) reused adds task.cache_hit, with no task.started before it. These three carry task, never error or status; the package itself never passes --resume. A human gate ends the stream with run.waiting (paused) on both doors. Longer workflows emit more: never assert a fixed count, and build a server-side progress view from run.started, the final event and run.status().

Sixteen events for a four-task run. nika check first plans brief.nika in three waves, with a nika:wait task, review, in the second. watch.mts then prints each event of run.events() with the second it arrived: run.started, four task.scheduled, a task.started and a task.completed per task, two engine.events whose frame (permit_checked, workflow_completed) is on event.raw.kind, and run.settled; then result() reads succeeded · cause normal · 4/4 tasks ok. The two-second gap is review waiting: engine 0.123.0 streams its start only when it completes. Recorded in a terminal from @supernovae-st/nika 0.123.0 and its bundled engine nika 0.123.0 (0bfde3765); every model call is mock/echo, the engine’s offline rehearsal model, with no provider key and no network.

run.sealed names a frame engine 0.124.3 does not stream: it writes the seal to the run’s record only. Read result.receipt.sealed locally, or traceVerify(receipt), to know whether a run is sealed.

Read the access contract and its receipt

A workflow file can declare how its model calls must travel: run.access (via, protocol, fallback, and from engine 0.124.2 service_tier) and run.reasoning.effort. On a local run, the terminal frame of each infer: or agent: task carries two rows about it, and from 0.124.2 two functions parse them:
  • readNikaAccessRequirement(event) returns what the file asked, in the file’s words. A key the file leaves out is absent, never a default.
  • readNikaAccessSelection(event) returns what the route did with it. For the model and for the effort it keeps four facts apart: requested (what the file asked), option (the session option or request field it travelled through), transmitted (the exact value sent) and configured (what the route reported after the selection, with how it was learned in configured_source). responder is the model the provider named in its answer, when it names one.
  • service_tier is present only when the file declares a tier. Its requested is the file’s word (standard or fast); offered, transmitted and configured are the route’s own values (off and on on codex-acp); turn and effective read { value: null, evidence: 'unknown' } on an ACP session, because no ACP answer names the tier a turn carried or the tier that served it. An absent block means the file asked for none, never standard.
Both functions accept a NikaRunEvent or the engine frame it wraps. They return undefined when the frame carries no such row: a task that called no model, a file that declares no contract, or any frame from nika serve, which keeps these rows in the job’s sealed journal and sends neither over HTTP. They throw NikaProtocolError on a row that is present and malformed. Before you run a file that declares run.access.service_tier, require the capability on the door you use: accessServiceTier in supportedCapabilities (nika --sdk-identity locally, /health on a server). An engine older than 0.124.2 refuses the key when it parses the file, and a server without the token answers 422 for it. Ask a seat for its fast tier has the language side and what each refusal says.

Rules for a reducer

  • The result is the truth. Never infer completion from the last event you recognized; await run.result().
  • Keep a default branch. The set is additive: engine.event and future kinds stay visible through event.raw without crashing an older interface.
  • Guard event.task. It is present only on events that named a task.
  • event.status is the engine’s word, never renamed: a waiting run reads paused.
  • event.sequence exists only over HTTP. It is the server’s replay cursor: persist it for attachRun().

Read events late

A run keeps its most recent events, so a view opened after the result replays them:
The bound is eventBufferSize, 4096 by default. Past it, the run still runs and run.result() still resolves; only a late view is refused, with NikaEventBufferOverflowError (reason: 'replay_truncated', and error.observed says how many events there were). A live view that falls more than its bufferSize behind fails with reason: 'live_backpressure'. Neither refusal skips an event, and neither is about the run.

Stop a view, not the run

An AbortSignal stops only its own view: a live loop simply ends at the abort, without an error, while the run keeps running. It never cancels engine work: call run.cancel() for that.

Results

The settlement every event stream ends on.

SSE streaming

Server events, sequence cursors and recovery.