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
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_fxandnika:image_composesaved inside the server’s project, the images an agent’s harness sent, which the server keeps, and the file anagent:task’simages: { save: }wrote from them (listed as afilewith the digest of the received bytes). Each entry has aname, itskind(fileoragent_image), a file’spath, the recordedsizeandsha256, itsmime, thetaskand the journalevent_id. From engine 0.124.1 afor_eachfan-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. Whatnika:writeandnika:editwrote 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.svgoragent_image/1.pngcomes from the manifest. Pass it, or the entry itself, todownloadArtifact()orreadArtifact(); an entry saves the package a manifest request. The manifest carries the job’sreceipt, chain head included, and the package checks that it is the job’s own. A file’spathpasses 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: awaitrun.result()first. An interrupted run never sealed its journal, so its job answersartifact_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). Itsstreamhashes 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 thanmaxBytes(16 MiB by default) withNikaConfigurationErrorbefore 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
machineBufferBytesnorrequestTimeoutbounds a download. Stop it withsignal, or cancel the stream; an unread stream holds its connection open.
Refusals
A refusal of the two routes is aNikaOperationError 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’scwd, 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:
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.