Skip to main content

Run lifecycle

The Outputs generic narrows result().outputs at compile time. It is a type-level convenience only — nothing runtime-validates model output against it. The workflow’s outputs: block exports named values; it does not validate them. Runtime shape enforcement comes from infer.schema (checked when the model answers) or an explicit validator task (nika:validate) — not from the export mapping, and never from a TypeScript generic. run.id differs by transport: on HTTP it is the resident’s durable job id (the identity to store); on the native transport it is an ephemeral correlation id of this SDK process — it appears in no journal, cannot be recovered after the process ends, and attachRun refuses it. Resume a native run through the engine’s own trace instead.
result() has one failure law: it rejects on transport, protocol or compatibility faults and on a broken observation (NikaObservationInterrupted, which carries the cursor) — none of which say the run failed; it may still be running. It resolves status: 'failed' for an admitted workflow failure (result data, with the engine’s error.code when named), and status: 'paused' when a human gate holds the run. Read isNikaRunSucceeded(result) before treating it as success.

Events

engine.event is the preservation door: every frame this SDK version does not name arrives there with its raw frame untouched; nothing is dropped, and no lifecycle meaning is invented for it. Keep a default branch in reducers; the set is additive. run.sealed names a run_sealed frame if an engine streams one; engine 0.124.3 writes the seal to the run’s record only, so read result.receipt.sealed locally or traceVerify(...).verdict.

Check and cancellation

NikaCheckResult is an open engine projection. A local check carries the findings report, process exitCode and verdicts, typed NikaCheckVerdicts (valid · access_ready · capacity_fit · run_ready · blockers · network_tasks): under check({ access }) a pin the engine refuses keeps clean: true with verdicts.access_ready: false and the refusal in verdicts.blockers. access_ready judges the model routes only; from engine 0.124.1, network_tasks lists, sorted, the tasks whose own effects can still reach the network (a fetch or webhook to a real host, an MCP tool, a paid media call), which a mock/echo rehearsal does not stub. Each finding (NikaCheckFinding) that names a part of the file carries span, a NikaSourceSpan ({ start, end }): byte offsets into the workflow file, start inclusive and end exclusive. From engine 0.124 a parse refusal carries one too, and from 0.124.1 the offsets count a file’s byte-order mark, as the file is saved. A served-name HTTP check carries clean: true plus status, snapshot_digest, root and units, or clean: false with a typed refusal in error; it does not invent a local findings report or exit code. NikaCancelResult describes action acceptance: cancelled (settled on the reply), already_settled, or cancellation_requested — execution continues toward its own settlement in the last case. Use run.result() for the actual result, including success racing cancellation.

Compile

A request is a create ({ intent }, or the intent as a bare string) or an edit ({ workflow, change }, the accepted source plus the change), never both. incomplete and refused are data: the SDK throws only on transport, protocol, compatibility and engine-stamped failures. Under incomplete, a non-null candidate is a preview, never a result to run or save.

Artifacts

A server’s manifest is checked field by field: the verdict is sealed or anchored, names are unique, sizes are byte counts, digests are SHA-256 and a file’s path is contained; any other key rides through. The path check is lexical and POSIX, the server’s own, so it does not make a path safe to join under a local directory on every system: to write an artifact under yours, resolve the joined path, check that it stays inside, and open it exclusively (wx). The download stream errors with NikaProtocolError for bytes that are not the recorded ones, NikaOperationError for a server refusal on a retry (artifact_changed), and NikaTransportError for a download that stayed incomplete or was aborted. Outputs and artifacts shows them in use.

Access pins

The words aid completion without closing the set: the engine, never the SDK, judges a pin. run({ access }) and check({ access }) take one (Configuration).

Access contract and receipt

From 0.124.2. What a workflow file declares under run.access and run.reasoning, and what one model call did with it:
null means not applicable or not observed, never a copied value. A configured value is what the route reported after the selection: session_config when nothing was asked and the session stated its own, confirmed_selection when a value was sent and read back, accepted_request when the route took it without answering a configuration. changed_mid_turn lists a model, an effort or a tier the route itself moved during the turn. readNikaAccessRequirement and readNikaAccessSelection return these from a task’s terminal frame (Run events).

Access offer

From 0.124.3. What accessOffer() returns: the sessions of a served workflow’s declared ACP route, read without a prompt (Ask what a route offers):
The document is closed: the reader refuses an answer with a key or a word it does not know, with NikaProtocolError. An observed row carries its model.status and both listings. An unavailable row carries the code a run would meet before its prompt.

Proof

Locally the verdict is verified, or invalid (reason: 'receipt_mismatch' for an unsealed or edited record; no reason when the trace file cannot be read). Over HTTP it is the CLI verifier’s tier in lower case: ok means intact but unsigned (reason: 'unsealed'), and unavailable means the server holds no journal for the job. The published 0.124.3 declarations list the same words, with the CLI verifier’s refusal classes (unchained · empty · unreadable · refused · line-over-long · unknown), and over HTTP a verdict that holds always carries its seal tier as reason (sealed or unsealed). Receipts has the measured table.

Errors

NikaObservationInterrupted means this client lost its observation of a run that may still be running: an evidence state, never a settlement. Schedule types (NikaScheduleOptions, NikaScheduleStatus, NikaScheduleApplyResult) are exported for the revision-checked server schedule contract; their engine-owned fields are additive.

Published type declarations (v0.124.3)

Review the source of the published declarations.