Skip to main content

Admit, observe and settle

run() admits the workflow first: a file that fails admission throws NikaOperationError and no handle is created. The returned NikaRun carries id plus its lifecycle methods; the run itself is not an async iterator. Subscribe through run.events(); the run’s ending lives in run.result(). The result’s settlement carries the engine’s cause, task tally, spend, elapsed time and error. A paused result means a human gate (nika:prompt with no default) holds the run: it is neither a failure nor a success, and the result’s exitCode is 4. Resume a paused local run from the command line, with the trace its receipt names and the answer:
The trace path is result.receipt.trace_path. Give a gate a default: (used when no human can answer) for a run that must never wait.

Stop observation without cancelling

Aborting the observer ends only that view: the loop exits without an error, and the run keeps running. It never cancels engine work.

Cancel explicitly

run.cancel() is idempotent: every call returns the same request. Locally the SDK sends the engine SIGTERM. The task already running (a model call, a nika:wait) finishes and is counted, tasks not yet started are cancelled, and run.result() then resolves cancelled with exitCode 130 and settlement.cause operator. That can take as long as the task in flight: cancelling a run inside a 20-second nika:wait settled after the wait ended.
Save slow.nika, then start it and cancel it after a second and a half:
slow.nika
cancel.mts
cancellation_requested acknowledges the request, not its outcome: keep awaiting run.result(), which may still read succeeded or failed if the run ended first. On nika serve an execution that has not settled within the server’s 5-second grace ends interrupted instead. Only the deprecated nika.cancel(run) wrapper can throw NikaRunOwnershipError, for a run another client created; the handle’s own methods are bound to their run.

Events

Design an additive event reducer.

Receipts

Preserve and verify engine-issued proof.