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:
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
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.
Try it: cancel a run that waits
Try it: cancel a run that waits
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.
Which published source this page describes
Which published source this page describes
Events
Design an additive event reducer.
Receipts
Preserve and verify engine-issued proof.