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.
How many events, on which door
The vocabulary is one; the number of events is not. For the quickstart’s one-taskhello.nika, measured on 0.123.0:
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.
Transcript: every screen of the recording, in order
Transcript: every screen of the recording, in order
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) andconfigured(what the route reported after the selection, with how it was learned inconfigured_source).responderis the model the provider named in its answer, when it names one.service_tieris present only when the file declares a tier. Itsrequestedis the file’s word (standardorfast);offered,transmittedandconfiguredare the route’s own values (offandonon codex-acp);turnandeffectiveread{ 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, neverstandard.
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.eventand future kinds stay visible throughevent.rawwithout crashing an older interface. - Guard
event.task. It is present only on events that named a task. event.statusis the engine’s word, never renamed: a waiting run readspaused.event.sequenceexists only over HTTP. It is the server’s replay cursor: persist it forattachRun().
Read events late
A run keeps its most recent events, so a view opened after the result replays them: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
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.
Which version is this?
Which version is this?