Skip to main content
A run hands back two kinds of result. Its outputs: arrive on the settlement event and on run.result(). The files it saved stay where the workflow wrote them: on a nika serve job, the server lists the ones the job’s sealed journal records and serves their bytes, so your application gets a chart, an image or an audio file without base64 in outputs and without a second store.

Outputs

Engine-owned outputs arrive on events and the terminal result:
outputs is Record<string, unknown> because the workflow defines its own shape. Validate it at the application boundary before mapping it into business state.

Artifacts of a server job

This served workflow saves one chart:
chart.nika
Saved as workflows/chart.nika on a server started with --workflows ./workflows (the server quickstart sets one up on loopback), it runs by its served name, and its settled job lists the SVG:
  • What is listed. The files nika:chart, nika:image_generate, nika:tts_generate, nika:image_fx and nika:image_compose saved inside the server’s project, the images an agent’s harness sent, which the server keeps, and the file an agent: task’s images: { save: } wrote from them (listed as a file with the digest of the received bytes). Each entry has a name, its kind (file or agent_image), a file’s path, the recorded size and sha256, its mime, the task and the journal event_id. From engine 0.124.1 a for_each fan-out of one of these builtins lists each item’s file too, when every item settled ok; a fan-out with a recovered or failed item lists none of its files. What nika:write and nika:edit wrote is not listed: their journal frame records no digest. To serve a file, save it with one of the five builtins.
  • A name is a key, never a path. file/out/totals.svg or agent_image/1.png comes from the manifest. Pass it, or the entry itself, to downloadArtifact() or readArtifact(); an entry saves the package a manifest request. The manifest carries the job’s receipt, chain head included, and the package checks that it is the job’s own. A file’s path passes a lexical, POSIX containment check only: to save the file under a local directory, resolve the joined path, check that it stays inside, and open it exclusively (wx).
  • Settled jobs only. A queued, running or paused job answers job_not_settled: await run.result() first. An interrupted run never sealed its journal, so its job answers artifact_journal_unavailable.
  • A sealed journal only. The server serves nothing from a journal that is not sealed, intact and headed by the receipt’s chain_head (artifact_journal_unverified). Give the server a run key before the jobs you want to download from: Server runbook shows both ways.

What a download proves

The server reads the whole file against its journal record before the first byte leaves, then checks every chunk again while it streams. The package checks the bytes a third time on arrival:
  • downloadArtifact() resolves once the response carries the recorded size (Content-Length) and digest (Nika-Artifact-Sha256). Its stream hashes each chunk, holds the last one back, and closes only once exactly the recorded size hashed to the recorded SHA-256. Otherwise it errors, and what you wrote is not the artifact, which is why the example writes a temporary file first.
  • readArtifact() resolves only with proven bytes, and refuses an artifact larger than maxBytes (16 MiB by default) with NikaConfigurationError before downloading it: stream that one instead.
  • A body cut short is requested again, up to 3 more times; the server has no range requests, so each attempt is the whole artifact, and its first bytes must hash as before. A file that changed since the run answers artifact_changed: the server never serves other bytes as the recorded ones.
  • Neither machineBufferBytes nor requestTimeout bounds a download. Stop it with signal, or cancel the stream; an unread stream holds its connection open.

Refusals

A refusal of the two routes is a NikaOperationError with the server’s code, its HTTP status, and operation artifacts, downloadArtifact or readArtifact: The server’s document also declares 401 (no or a wrong Bearer token), 500 (internal_error: the server could not read the journal or the file) and, on the manifest route, 408 (the request deadline). Two refusals happen before any request, with NikaCompatibilityError (capability: 'artifacts'): a server whose /health does not list artifacts, and a local run.

A local run

A local run has no artifact manifest: its files are where its workflow wrote them, under the client’s cwd, and the three methods reject with NikaCompatibilityError. Read those files directly, or return what your application needs through the workflow’s outputs:.

Without the SDK

Both routes take the server’s Bearer token. {name} is an entry’s name, with its / sent as is or as %2F:
The bytes come with Content-Type (the entry’s mime), Content-Length, Nika-Artifact-Sha256, Content-Disposition: attachment, X-Content-Type-Options: nosniff, Content-Security-Policy: sandbox and Cache-Control: no-store. A body shorter than its Content-Length is an incomplete download: retry it. The server’s own GET /v1/openapi.json declares both routes, their headers and their refusals.

Jobs

Keep outputs and artifacts attached to the run identity.

Receipts

Store proof beside the terminal result.