Skip to main content

Admit and persist identity

The served name in this example submits {"workflow":"workflows/release.nika"} to POST /v1/jobs; the server captures its served workflow itself. A served name is the workflow’s path from the project root, not from --workflows. An explicit local path such as ./release.nika instead asks a compatible local engine for a snapshot and sends those captured bytes; a snapshot freezes inputs, so inputs is refused on that form. Remote run options accept idempotencyKey, access (the job’s access pin, sent as JobByName.access beside a served name) and, where the server advertises jobInputs, literal inputs. vars, model and maxCostUsd are refused with NikaCompatibilityError (capability: 'runOptions') because their request envelopes do not exist. A snapshot of a local file carries no pin either: access beside one is refused (capability: 'snapshotAccess'). A fresh randomUUID() per retry defeats the contract: the key is what lets the server return the original job instead of starting a second one. Keys cover the whole --state-root and do not expire, so never reuse one for another operation.

Spend on the server

The server bounds spend itself: nika serve --run-cost-ceiling <USD> caps every job your code submits, 1 USD by default (none removes the cap). A job whose cost floor exceeds it is admitted, then settles failed with error.code NIKA-1709; run() does not throw. Bound a job through its workflow (its model and max_tokens), and see Spend caps.

Observe and settle

The default machineBufferBytes, 16 MiB, is the bound of the server’s own job store, so every result the server settles reaches run.result(). A client configured with a smaller bound is refused with a NikaProtocolError that names the size to set; the job keeps its result, and attachRun() with a larger bound reads it again.

Recover after a process restart

Persist the job id and the last durably consumed sequence under one name, lastEventId, and reuse it. Reattachment avoids resubmitting a workflow merely because the Node process restarted. The engine’s settlement remains available on result.settlement even when the cursor already consumed its terminal event. Only a server job id is durable: a local run.id is a throwaway id, and attachRun() refuses it.
A paused job stays paused. In 0.124.3, nika serve has no route to answer a human gate: a job that reaches a nika:prompt without a default: settles paused (a run.waiting event), no request resumes it, and cancelling it answers already_settled. For served workflows, give every nika:prompt a default: (used when no human can answer), or keep human gates on the local engine, where the CLI resumes a paused run.

Read status or cancel

A running job answers 202 with { accepted: true, status: 'cancellation_requested' }: the server accepted the request and the run is still settling. Await run.result() for its actual status. A success or failure that wins the race is preserved; an execution that has not settled within the server’s 5-second grace ends interrupted, with no settlement. A job cancelled before its execution started settles cancelled on the reply itself (200), and a job that already ended answers accepted: false, status: 'already_settled'. The API has no job-list route, so application indexes remain application-owned.

Download what it produced

Once the job has settled, run.artifacts() lists the files its sealed journal records, and run.readArtifact() or run.downloadArtifact() returns their bytes, proven against the recorded size and SHA-256. A handle from attachRun() has the same methods, so a recovered job’s files stay reachable by its id:
Outputs and artifacts covers what is listed, what a download proves and its refusals.

SSE streaming

Preserve sequence continuity across observers.

Errors

Separate run failure from boundary failure.