@nika-open/nika 0.0.0-stage → 0.124.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/README.md +776 -2
- package/dist/bin/nika.js +450 -0
- package/dist/index.cjs +5921 -0
- package/dist/index.d.cts +1913 -0
- package/dist/index.d.ts +1913 -0
- package/dist/index.js +5865 -0
- package/docs/README.md +69 -0
- package/docs/architecture.md +163 -0
- package/docs/compile.md +486 -0
- package/docs/errors.md +154 -0
- package/docs/glossary.md +41 -0
- package/docs/http-api.md +396 -0
- package/docs/migrating-to-0.116.md +164 -0
- package/docs/receipts.md +156 -0
- package/docs/runs.md +670 -0
- package/docs/server.md +543 -0
- package/docs/testing.md +244 -0
- package/docs/upgrading-to-0.123.md +190 -0
- package/openapi.json +3067 -0
- package/package.json +92 -4
package/docs/server.md
ADDED
|
@@ -0,0 +1,543 @@
|
|
|
1
|
+
# Run on your server: `nika serve`
|
|
2
|
+
|
|
3
|
+
`nika serve --bind` is the same engine running as an HTTP server you operate.
|
|
4
|
+
It holds durable jobs and schedules, so a run outlives the process that
|
|
5
|
+
started it. Your code talks to it through the same `Nika` class and the same
|
|
6
|
+
methods; the constructor names the server, and a few options change (a run
|
|
7
|
+
needs an `idempotencyKey` and takes no `maxCostUsd`). This page covers setup,
|
|
8
|
+
the job lifecycle, recovery, retries, artifacts and schedules. The wire
|
|
9
|
+
contract, route by route, is [http-api.md](http-api.md).
|
|
10
|
+
|
|
11
|
+
```mermaid
|
|
12
|
+
sequenceDiagram
|
|
13
|
+
autonumber
|
|
14
|
+
participant App as Your code
|
|
15
|
+
participant SDK as @nika-open/nika
|
|
16
|
+
participant Serve as nika serve
|
|
17
|
+
App->>SDK: nika.run('hello.nika', { idempotencyKey })
|
|
18
|
+
SDK->>Serve: GET /health (once per client: machine protocol 2, capabilities)
|
|
19
|
+
SDK->>Serve: POST /v1/jobs with Idempotency-Key
|
|
20
|
+
Serve-->>SDK: the job id (the same id again for the same key)
|
|
21
|
+
SDK-->>App: NikaRun, whose run.id is the durable job id
|
|
22
|
+
SDK->>Serve: GET /v1/jobs/{id}/events (SSE)
|
|
23
|
+
Serve-->>SDK: id 1 execution.started, id 2 execution.settled
|
|
24
|
+
SDK-->>App: run.events(): run.started, run.settled
|
|
25
|
+
Note over App,Serve: after a restart, the stored job id and last sequence resume the job
|
|
26
|
+
App->>SDK: nika.attachRun(jobId, { lastEventId })
|
|
27
|
+
SDK->>Serve: GET /v1/jobs/{id}, then SSE with Last-Event-ID
|
|
28
|
+
App->>SDK: nika.traceVerify(result.receipt)
|
|
29
|
+
SDK->>Serve: GET /v1/jobs/{id}/trace/verify
|
|
30
|
+
App->>SDK: run.artifacts(), run.downloadArtifact(name)
|
|
31
|
+
SDK->>Serve: GET /v1/jobs/{id}/artifacts, then GET /v1/jobs/{id}/artifacts/{name}
|
|
32
|
+
Serve-->>SDK: the manifest, then the bytes the job's sealed journal recorded
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Set it up
|
|
36
|
+
|
|
37
|
+
In the project folder you need four things.
|
|
38
|
+
|
|
39
|
+
1. **A project file.** The server refuses to start without one (`nothing
|
|
40
|
+
armed — this project has no nika.yaml`). A one-line `nika.yaml` is
|
|
41
|
+
enough; the [project file reference](https://docs.nika.sh/sdk/project/nika-yaml)
|
|
42
|
+
lists what else it can hold (a default cost ceiling, trace retention,
|
|
43
|
+
armed beats):
|
|
44
|
+
|
|
45
|
+
```yaml
|
|
46
|
+
nika: my-project
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
2. **A private token file.** The server refuses one that is not mode `0600`
|
|
50
|
+
or not 32–512 visible ASCII bytes:
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
mkdir -p .nika
|
|
54
|
+
(umask 077 && openssl rand -hex 24 > .nika/serve.token)
|
|
55
|
+
chmod 600 .nika/serve.token
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
3. **A `.gitignore` entry for `.nika/`.** It holds your traces, the server's
|
|
59
|
+
job state (`.nika/serve/`) and the token file. Never commit the token.
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
printf '.nika/\n' >> .gitignore
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
4. **The server**, serving the workflows under the current folder:
|
|
66
|
+
|
|
67
|
+
```sh
|
|
68
|
+
./node_modules/.bin/nika serve \
|
|
69
|
+
--bind 127.0.0.1:8787 \
|
|
70
|
+
--workflows . \
|
|
71
|
+
--token-file .nika/serve.token \
|
|
72
|
+
--state-root .nika/serve
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Then connect from Node:
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
import { readFile } from 'node:fs/promises';
|
|
79
|
+
import { Nika } from '@nika-open/nika';
|
|
80
|
+
|
|
81
|
+
const token = (await readFile('.nika/serve.token', 'utf8')).trim();
|
|
82
|
+
const nika = new Nika({
|
|
83
|
+
url: 'http://127.0.0.1:8787',
|
|
84
|
+
token,
|
|
85
|
+
allowInsecureHttp: true, // plain HTTP, accepted only to a loopback host
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
const report = await nika.check('hello.nika');
|
|
89
|
+
const run = await nika.run('hello.nika', {
|
|
90
|
+
idempotencyKey: 'hello-2026-10-24', // store it before the call; reuse it on retry
|
|
91
|
+
});
|
|
92
|
+
for await (const event of run.events()) {
|
|
93
|
+
console.log(event.sequence, event.kind, event.status);
|
|
94
|
+
}
|
|
95
|
+
const result = await run.result();
|
|
96
|
+
console.log(report.clean, result.status);
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
```text
|
|
100
|
+
1 run.started running
|
|
101
|
+
2 run.settled succeeded
|
|
102
|
+
true succeeded
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
After `new Nika(...)`, the methods are the same as for a local engine; some
|
|
106
|
+
options are not. `run()` needs an `idempotencyKey` ([Retries without
|
|
107
|
+
duplicates](#retries-without-duplicates)) and takes no `maxCostUsd`
|
|
108
|
+
([What a server run does not take](#what-a-server-run-does-not-take)).
|
|
109
|
+
|
|
110
|
+
- **Workflows by name.** `hello.nika` or `daily/report.nika` is a name the
|
|
111
|
+
server resolves in its `--workflows` folder: `check()` and `run()` send the
|
|
112
|
+
name, so your app needs no local engine and no local file.
|
|
113
|
+
`listWorkflows()` lists the names; `workflow(name)` describes one.
|
|
114
|
+
- **Your local file instead.** Pass an explicit path such as `./hello.nika`:
|
|
115
|
+
the local engine captures an immutable snapshot of the file, and the
|
|
116
|
+
package sends its exact bytes and checks the server's acknowledgement. Only
|
|
117
|
+
this needs a local engine (`bin`, `NIKA_BIN` or the platform package).
|
|
118
|
+
- **Events.** A server run yields `run.started` then `run.settled`, in the
|
|
119
|
+
same words as a local run, but no per-task events. A job admitted with
|
|
120
|
+
`inputs` first yields an `engine.event`: the server's `execution.queued`
|
|
121
|
+
frame, sequence 1. `event.sequence` is the server's replay cursor.
|
|
122
|
+
- **Model keys.** The server reads provider keys from its own environment.
|
|
123
|
+
Your app sends none, and a server run takes no per-run model.
|
|
124
|
+
- **Access pins.** `run()` and `check()` take `access` with a served name:
|
|
125
|
+
the job takes that path, as `nika run --access` does on the server's
|
|
126
|
+
machine (see [runs.md](runs.md#pin-the-access-path-access)).
|
|
127
|
+
- **Large results.** The default `machineBufferBytes`, 16 MiB, is the bound
|
|
128
|
+
of the server's own job store, so every result the server settles reaches
|
|
129
|
+
`run.result()` and `attachRun()` (see
|
|
130
|
+
[runs.md](runs.md#large-results-machinebufferbytes)).
|
|
131
|
+
|
|
132
|
+
**Watch the setup and one job: a retry that does not run twice, and a wrong token.**
|
|
133
|
+
|
|
134
|
+
<p align="center">
|
|
135
|
+
<picture>
|
|
136
|
+
<source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/stills/sdk-remote.png">
|
|
137
|
+
<img src="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/gifs/sdk-remote.gif" alt="The terminal creates a one-line nika.yaml, mints a token into .nika/serve.token with umask 077, appends .nika/ to .gitignore, runs NIKA_KEYCHAIN=off nika key init and starts nika serve --bind 127.0.0.1:8787 --workflows . --token-file .nika/serve.token in the background; curl /health shows engineVersion 0.124.0 and machine protocol 2. node remote.mts prints served hello.nika, check clean, a job id, #1 run.started running, #2 run.settled succeeded, the greeting, verify verified · sealed, retry the same job: it did not run twice, and bad token 401 unauthorized" width="860">
|
|
138
|
+
</picture>
|
|
139
|
+
</p>
|
|
140
|
+
<p align="center"><sub>The README's version of these steps, typed as written (it leaves <code>--state-root</code> at its default, <code>.nika/serve</code>, and sends the server to the background of the same terminal). The client lists and checks the served <code>hello.nika</code> by name, runs it with an idempotency key, receives two sequenced events, reads <code>verified · sealed</code>, gets the same job back for the same key and a typed 401 for a wrong token. The token is never printed. Recorded from <code>@supernovae-st/nika</code> 0.124.0 and <code>nika serve</code> 0.124.0 on loopback; the run is a <code>mock/echo</code> rehearsal.<br>▶ <a href="https://github.com/nika-open/nika-client/blob/main/media/videos/sdk-remote.mp4?raw=true">MP4</a> · <a href="https://github.com/nika-open/nika-client/blob/main/media/transcripts/sdk-remote.txt">transcript</a> · <a href="https://github.com/nika-open/nika-client/blob/main/scripts/media/scenes/sdk-remote/remote.mts">the client it runs</a></sub></p>
|
|
141
|
+
|
|
142
|
+
## Retries without duplicates
|
|
143
|
+
|
|
144
|
+
Over HTTP, `run()` needs an `idempotencyKey` you own. Store a unique key for
|
|
145
|
+
each business operation before you call. If the response is lost or times
|
|
146
|
+
out, retry the same request with the same key: you get the same job. A new
|
|
147
|
+
key can start a second job. A local run refuses the key. Keys cover the
|
|
148
|
+
server's whole `--state-root` and do not expire, so make them globally unique
|
|
149
|
+
and never reuse one for another workflow.
|
|
150
|
+
|
|
151
|
+
For a webhook, the sender's delivery id is a natural key: a retried delivery
|
|
152
|
+
then reuses the job instead of running twice. Verify the webhook's signature
|
|
153
|
+
over the raw body with the sender's library first (this package exports no
|
|
154
|
+
verifier), then pass the parsed payload as `inputs` (see
|
|
155
|
+
[runs.md](runs.md#pass-your-apps-data-inputs)).
|
|
156
|
+
|
|
157
|
+
## Recovery after a restart
|
|
158
|
+
|
|
159
|
+
A run handle belongs to its process and is not serializable. Store the
|
|
160
|
+
**job id** (`run.id`) and the last `event.sequence` you fully processed, then
|
|
161
|
+
pick the job back up without submitting it again:
|
|
162
|
+
|
|
163
|
+
```ts
|
|
164
|
+
const recovered = await nika.attachRun(saved.jobId, {
|
|
165
|
+
lastEventId: saved.lastEventSequence,
|
|
166
|
+
});
|
|
167
|
+
for await (const event of recovered.events()) {
|
|
168
|
+
await saveApplicationCheckpoint(recovered.id, event.sequence);
|
|
169
|
+
}
|
|
170
|
+
console.log(await recovered.result());
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
`attachRun` is the one way back in, and it returns a full `NikaRun`. Only a
|
|
174
|
+
server's job id is durable: a local `run.id` is a throwaway id of the SDK
|
|
175
|
+
process, appears in no journal, and `attachRun` refuses it. A cursor means
|
|
176
|
+
"fully processed", not merely "received": persist it in the same transaction
|
|
177
|
+
as the effect it records.
|
|
178
|
+
|
|
179
|
+
When observation loses the connection past its retry budget, the package
|
|
180
|
+
makes one last durable read. A finished job settles `run.result()` from the
|
|
181
|
+
server's record; a job still running rejects with
|
|
182
|
+
`NikaObservationInterrupted`, whose `lastSequence` is the `lastEventId` to
|
|
183
|
+
resume from. That error is about this client's view, not the run, which may
|
|
184
|
+
still be running. The engine's own `interrupted` state is different: a server
|
|
185
|
+
that lost an execution reports a `run.interrupted` event and
|
|
186
|
+
`result.status === 'interrupted'`, as data.
|
|
187
|
+
|
|
188
|
+
[`examples/server-recovery.ts`](https://github.com/nika-open/nika-client/blob/main/examples/server-recovery.ts) does this
|
|
189
|
+
across two processes: `start` stores the key, submits, shows that a retry
|
|
190
|
+
returns the same job and exits after the first event; `resume` reattaches
|
|
191
|
+
from the saved cursor and verifies the job's record.
|
|
192
|
+
|
|
193
|
+
## Cancel a running job: the 5-second grace
|
|
194
|
+
|
|
195
|
+
`run.cancel()` on a running job answers 202:
|
|
196
|
+
`{ accepted: true, status: 'cancellation_requested' }`, the one request every
|
|
197
|
+
later `cancel()` on that handle returns. The server signals the run and waits
|
|
198
|
+
a **fixed 5 seconds**, which no option changes, for it to reach its next wave
|
|
199
|
+
boundary and settle. What the client sees depends on that grace:
|
|
200
|
+
|
|
201
|
+
| The run | Events end with | `result.status` | `result.settlement` |
|
|
202
|
+
|---|---|---|---|
|
|
203
|
+
| reaches a wave boundary within 5 s | `run.settled` | `cancelled` (cause `operator`), or `succeeded`/`failed` if that raced the request | present |
|
|
204
|
+
| is still inside a task 5 s later (a `nika:wait`, a model call, a command) | `run.interrupted` | `interrupted`, never `cancelled` | absent: the server dropped the execution, so its task tally and spend are unknown |
|
|
205
|
+
|
|
206
|
+
`run.status()` then reads the same word, and a `cancel()` from another handle
|
|
207
|
+
(after `attachRun`) answers `accepted: false`, `status: 'already_settled'`. A
|
|
208
|
+
job cancelled while still queued settles on the reply itself (200,
|
|
209
|
+
`status: 'cancelled'`). Measured on engine 0.123.1: a job inside a 20-second
|
|
210
|
+
`nika:wait` settled `interrupted` about 5 seconds after its cancel, with the
|
|
211
|
+
events `run.started` and `run.interrupted`. `run.interrupted` is the server's
|
|
212
|
+
word about the run; it is unrelated to `NikaObservationInterrupted`, which
|
|
213
|
+
means this client lost its view. A local engine has no such grace: it lets
|
|
214
|
+
work in flight settle, however long it takes (see
|
|
215
|
+
[runs.md](runs.md#cancel-a-run)).
|
|
216
|
+
|
|
217
|
+
**When the server restarts.** Ctrl-C or SIGTERM stops new admissions, then
|
|
218
|
+
drains running and queued jobs for up to 30 seconds. Past that grace, running
|
|
219
|
+
jobs become `interrupted` and queued jobs stay queued; a restart with the same
|
|
220
|
+
`--state-root` resumes the queued ones, and interrupted jobs are not retried.
|
|
221
|
+
A SIGKILL skips the drain: the next start marks ownerless running jobs
|
|
222
|
+
`interrupted`. (`nika serve --help` documents the same rules.)
|
|
223
|
+
|
|
224
|
+
## Download what a job produced: artifacts
|
|
225
|
+
|
|
226
|
+
A settled job's artifacts are the files its builtins saved (`nika:chart`,
|
|
227
|
+
`nika:image_generate`, `nika:tts_generate`, `nika:image_fx`, and
|
|
228
|
+
`nika:image_compose` from engine 0.124) and the images its agents' harnesses
|
|
229
|
+
sent. The server lists the ones the job's sealed journal
|
|
230
|
+
records with their SHA-256, and serves their bytes checked against that record,
|
|
231
|
+
so your app gets the files without base64 in `outputs` and without uploading
|
|
232
|
+
them anywhere. The package checks every byte again as it arrives.
|
|
233
|
+
|
|
234
|
+
This workflow saves one chart:
|
|
235
|
+
|
|
236
|
+
```yaml
|
|
237
|
+
nika: chart
|
|
238
|
+
permits:
|
|
239
|
+
fs: { write: ["./out/**"] }
|
|
240
|
+
tools: ["nika:chart"]
|
|
241
|
+
tasks:
|
|
242
|
+
draw:
|
|
243
|
+
invoke:
|
|
244
|
+
tool: "nika:chart"
|
|
245
|
+
args:
|
|
246
|
+
data: [{ region: "north", total: 10 }, { region: "south", total: 4 }]
|
|
247
|
+
chart: { type: bar, x: region, y: total }
|
|
248
|
+
out: "./out/totals.svg"
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
```ts
|
|
252
|
+
import { createWriteStream } from 'node:fs';
|
|
253
|
+
import { rename } from 'node:fs/promises';
|
|
254
|
+
import { Readable } from 'node:stream';
|
|
255
|
+
import { pipeline } from 'node:stream/promises';
|
|
256
|
+
|
|
257
|
+
const run = await nika.run('chart.nika', { idempotencyKey: 'chart-2026-10-26' });
|
|
258
|
+
await run.result(); // artifacts are served once the job has settled
|
|
259
|
+
|
|
260
|
+
const manifest = await run.artifacts();
|
|
261
|
+
for (const artifact of manifest.artifacts) console.log(artifact.name, artifact.mime);
|
|
262
|
+
|
|
263
|
+
// A stream: write it under a temporary name, and keep the file once the stream closed.
|
|
264
|
+
const download = await run.downloadArtifact('file/out/totals.svg');
|
|
265
|
+
await pipeline(Readable.fromWeb(download.stream), createWriteStream('totals.svg.part'));
|
|
266
|
+
await rename('totals.svg.part', 'totals.svg');
|
|
267
|
+
|
|
268
|
+
// Or the whole bytes at once, up to maxBytes (16 MiB by default).
|
|
269
|
+
const svg = await run.readArtifact('file/out/totals.svg');
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
```text
|
|
273
|
+
file/out/totals.svg image/svg+xml
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
[`examples/artifacts.ts`](https://github.com/nika-open/nika-client/blob/main/examples/artifacts.ts) runs
|
|
277
|
+
[`examples/chart.nika`](https://github.com/nika-open/nika-client/blob/main/examples/chart.nika), this
|
|
278
|
+
workflow with its write narrowed to `./out/totals.svg`, on a local server,
|
|
279
|
+
lists the job's artifacts and streams one into a file it keeps once the
|
|
280
|
+
stream closed: no model, no provider key and no network, on a server that
|
|
281
|
+
holds a run key (see below).
|
|
282
|
+
|
|
283
|
+
- **What is listed.** Each entry has a `name`, its `kind` (`file` or
|
|
284
|
+
`agent_image`), a file's `path` in the server's project, the recorded `size`
|
|
285
|
+
and `sha256`, its `mime`, the `task` and the journal `event_id`. A name such
|
|
286
|
+
as `file/out/totals.svg` or `agent_image/1.png` is a key, never a path: pass
|
|
287
|
+
it, or the entry itself, to `downloadArtifact()` or `readArtifact()`. What
|
|
288
|
+
`nika:write` and `nika:edit` wrote is not listed, nor a file an agent wrote
|
|
289
|
+
itself: the journal records no digest for those bytes. An agent's image is
|
|
290
|
+
still listed, as the image the server kept. From engine 0.124, an `agent:`
|
|
291
|
+
task can declare `images: { save: ./out/banner.png }`: the engine writes
|
|
292
|
+
the image's received bytes there, and the manifest lists that file too
|
|
293
|
+
(`file/out/banner.png`, the received digest) beside `agent_image/1.png`,
|
|
294
|
+
the same bytes under two names. From engine 0.124.1 a `for_each` fan-out
|
|
295
|
+
that calls `nika:chart`, or another builtin whose files are listed, once
|
|
296
|
+
per item has each item's file listed, with its journaled size and digest,
|
|
297
|
+
once every item settled ok; a fan-out with a recovered or failed item still
|
|
298
|
+
lists none of its files.
|
|
299
|
+
- **Settled jobs only.** A queued, running or paused job answers 409
|
|
300
|
+
`job_not_settled`: `await run.result()` first. An interrupted job never
|
|
301
|
+
sealed its journal and answers 409 `artifact_journal_unavailable`.
|
|
302
|
+
- **The server needs a run key.** A server without one still lists
|
|
303
|
+
`artifacts`, but its journals are unsealed, so every request answers 409
|
|
304
|
+
`artifact_journal_unverified`. Run `NIKA_KEYCHAIN=off
|
|
305
|
+
./node_modules/.bin/nika key init` as the server's user: the jobs that run
|
|
306
|
+
after it serve their artifacts. A server started with an explicit pair,
|
|
307
|
+
`NIKA_RUN_KEY_FILE` and `NIKA_RUN_PUB_FILE`, seals with that pair and
|
|
308
|
+
verifies its journals against its public half.
|
|
309
|
+
- **Bound to the job.** The manifest carries the job's receipt, chain head
|
|
310
|
+
included, and the package checks that it is the job's own: the receipt the
|
|
311
|
+
run settled with, or the one the server's record of the job carries.
|
|
312
|
+
- **Proven on arrival.** `downloadArtifact()` resolves once the server
|
|
313
|
+
answered with the recorded size (`Content-Length`) and digest
|
|
314
|
+
(`Nika-Artifact-Sha256`), both equal to the manifest entry's. The stream
|
|
315
|
+
hashes each chunk, holds its last one back, and closes only once exactly the
|
|
316
|
+
recorded size hashed to the recorded SHA-256; otherwise it errors, and the
|
|
317
|
+
file you wrote is not the artifact. `readArtifact()` resolves only then.
|
|
318
|
+
- **A body cut short is downloaded again,** up to 3 more times, 100, 200
|
|
319
|
+
and 400 ms apart: a stream ends early when the server cannot read the file
|
|
320
|
+
or stops while it streams, and a retry that cannot reach the server counts
|
|
321
|
+
as one more attempt. The server has no range requests, so each retry is the
|
|
322
|
+
whole artifact again, and its first bytes must hash as they did. A file
|
|
323
|
+
that changed since the run answers 409 `artifact_changed` instead: the
|
|
324
|
+
server never serves other bytes. Still incomplete after the last attempt
|
|
325
|
+
(a server restart takes longer than these waits), the stream fails with a
|
|
326
|
+
`NikaTransportError`: download it again once the server is back.
|
|
327
|
+
- **No timeout of the package's.** Neither `machineBufferBytes` nor
|
|
328
|
+
`requestTimeout` bounds a download: the server reads the whole file against
|
|
329
|
+
its record before the first byte, and the body takes as long as it needs.
|
|
330
|
+
Stop it with `signal`, or cancel the stream; an unread stream holds its
|
|
331
|
+
connection open.
|
|
332
|
+
- **Size bounds.** `readArtifact()` holds at most `maxBytes`, 16 MiB by
|
|
333
|
+
default; a larger artifact is refused with `NikaConfigurationError` before
|
|
334
|
+
its download starts, so stream it. The server refuses an artifact over its
|
|
335
|
+
own `max_artifact_bytes` (256 MiB by default) with 403
|
|
336
|
+
`artifact_too_large`; that one stays listed.
|
|
337
|
+
- **Fewer requests.** Pass the entry from `run.artifacts()`: a name makes the
|
|
338
|
+
package read the manifest first, an entry does not. A name the manifest
|
|
339
|
+
does not list gets the server's 404 `artifact_not_found`. A manifest lists
|
|
340
|
+
at most 1,024 entries (`truncated: true` says more exist); a name past them
|
|
341
|
+
still downloads, proven against the response's headers alone, and
|
|
342
|
+
`download.artifact` is then absent.
|
|
343
|
+
- **Which servers.** A server that serves artifacts lists `artifacts` in
|
|
344
|
+
`/health`, from engine 0.123.2; 0.123.1 and older do not. On any other
|
|
345
|
+
server, and on a local run, the three methods reject with
|
|
346
|
+
`NikaCompatibilityError` (`capability: 'artifacts'`) before any request. A local run's files are
|
|
347
|
+
where its workflow wrote them, in the client's `cwd`.
|
|
348
|
+
|
|
349
|
+
Every refusal is a `NikaOperationError` with the server's `code` and HTTP
|
|
350
|
+
`status`; [errors.md](errors.md#a-servers-refusal) lists them.
|
|
351
|
+
|
|
352
|
+
## Connection rules
|
|
353
|
+
|
|
354
|
+
Plain HTTP is accepted only to a loopback host (`localhost`, `127.0.0.0/8`,
|
|
355
|
+
`[::1]`), and only with `allowInsecureHttp: true`; every other host needs
|
|
356
|
+
HTTPS, so the token never leaves the machine in plaintext. The URL may not
|
|
357
|
+
carry credentials, a query or a fragment, and the token must be 32–512 visible
|
|
358
|
+
ASCII bytes. To serve other machines, start the server with `--allow-remote`
|
|
359
|
+
behind a reverse proxy that terminates TLS (the server does not), and connect
|
|
360
|
+
with `https://`.
|
|
361
|
+
|
|
362
|
+
## What a server run does not take
|
|
363
|
+
|
|
364
|
+
`inputs` work by served name when the server advertises `jobInputs` (see
|
|
365
|
+
[runs.md](runs.md#pass-your-apps-data-inputs)), and so does `access`, which
|
|
366
|
+
every server from engine 0.123 on reads (see
|
|
367
|
+
[runs.md](runs.md#pin-the-access-path-access)). A local file's snapshot takes
|
|
368
|
+
neither: the package refuses them beside one (`snapshotInputs`,
|
|
369
|
+
`snapshotAccess`). There is no per-run `model`, `vars` or `maxCostUsd` over
|
|
370
|
+
HTTP: the package refuses them with a typed error instead of dropping them.
|
|
371
|
+
The server applies its own per-run ceiling to manual jobs
|
|
372
|
+
(`nika serve --run-cost-ceiling`, 1 USD by default; `none` turns it off).
|
|
373
|
+
From engine 0.124 that ceiling covers paid media too: a priced image or
|
|
374
|
+
speech call is floored and billed against it, and one the engine's price
|
|
375
|
+
table cannot price is refused before any request. The server still admits
|
|
376
|
+
such a job (`202`): it settles `failed` with `error.code` `NIKA-1709` before
|
|
377
|
+
any task runs, and its result has no `settlement` (see
|
|
378
|
+
[errors.md](errors.md#troubleshooting)).
|
|
379
|
+
Bound a server run through its workflow too: its model and `max_tokens`. A
|
|
380
|
+
server `check()` refuses `model` and `nativeStrict` the same way; its
|
|
381
|
+
`access` is acknowledged, not judged, since the server's check evaluates no
|
|
382
|
+
access plan (an empty pin is refused, `NIKA-1802`).
|
|
383
|
+
|
|
384
|
+
## Schedules
|
|
385
|
+
|
|
386
|
+
A schedule belongs to a server. A local client refuses `schedule` and
|
|
387
|
+
`scheduleStatus`, because a short-lived process cannot own schedule state.
|
|
388
|
+
|
|
389
|
+
```ts
|
|
390
|
+
const applied = await nika.schedule('hello.nika', {
|
|
391
|
+
id: 'weekday-hello',
|
|
392
|
+
when: { kind: 'cadence', expression: 'TZ=Europe/Paris 0 9 * * 1-5' },
|
|
393
|
+
maxCostUsd: 0.01,
|
|
394
|
+
missed: 'catch-up-once',
|
|
395
|
+
overlap: 'skip',
|
|
396
|
+
afterSkip: 'next_slot',
|
|
397
|
+
});
|
|
398
|
+
|
|
399
|
+
const status = await nika.scheduleStatus('weekday-hello');
|
|
400
|
+
console.log(applied.changed, status.next, status.lastDecision);
|
|
401
|
+
|
|
402
|
+
// Pause it: send the whole declaration again, with the revision you read.
|
|
403
|
+
await nika.schedule('hello.nika', {
|
|
404
|
+
id: 'weekday-hello',
|
|
405
|
+
when: { kind: 'cadence', expression: 'TZ=Europe/Paris 0 9 * * 1-5' },
|
|
406
|
+
maxCostUsd: 0.01,
|
|
407
|
+
missed: 'catch-up-once',
|
|
408
|
+
overlap: 'skip',
|
|
409
|
+
afterSkip: 'next_slot',
|
|
410
|
+
revision: status.revision,
|
|
411
|
+
active: false,
|
|
412
|
+
pauseReason: 'maintenance',
|
|
413
|
+
pauseUntil: '2026-12-01',
|
|
414
|
+
});
|
|
415
|
+
```
|
|
416
|
+
|
|
417
|
+
- **Revisions.** A create is sent with `If-None-Match: *`; an update needs
|
|
418
|
+
the exact prior revision (`If-Match`). Revisions are the engine's opaque
|
|
419
|
+
`sha256:<64 lowercase hex>` values: never make one up. A writer holding a
|
|
420
|
+
stale revision gets a typed `NikaOperationError` with HTTP `status` 412,
|
|
421
|
+
`code: 'schedule_conflict'` (the package's name for it), `machineCode:
|
|
422
|
+
'schedule_precondition_failed'` (the server's own code) and
|
|
423
|
+
`currentRevision`: the revision to retry from beside a stale `If-Match`,
|
|
424
|
+
`null` when the server names none (a missing or malformed precondition).
|
|
425
|
+
- **Expressions.** A cron expression carries its time zone:
|
|
426
|
+
`TZ=<IANA zone> …`. `tolerance` uses `m/k`. Timed hash jitter is not
|
|
427
|
+
supported and is refused.
|
|
428
|
+
- **Pausing.** `active: false` needs a `pauseReason` and a `pauseUntil`
|
|
429
|
+
calendar date (`YYYY-MM-DD`).
|
|
430
|
+
- **Overlap.** `afterSkip` needs `overlap: "skip"`, the engine's default, so
|
|
431
|
+
leaving `overlap` out works too.
|
|
432
|
+
- **Budget.** A schedule's `maxCostUsd` must be a positive number: `0` is
|
|
433
|
+
refused, where a local `run()` accepts it. An occurrence runs under the
|
|
434
|
+
lower of it and the server's own ceiling, when the server keeps one. From
|
|
435
|
+
engine 0.124 that cap covers paid media too: an occurrence whose workflow
|
|
436
|
+
makes a paid image or speech call the engine's price table cannot price
|
|
437
|
+
fails with `NIKA-1709` before any task runs, as a manual job does.
|
|
438
|
+
- **Older state.** Treat any `status.finding` recovered from older state as
|
|
439
|
+
not runnable. The engine refuses a new active declaration it cannot plan
|
|
440
|
+
before storing it. The planning facts in a status are the engine's, and new
|
|
441
|
+
ones may appear.
|
|
442
|
+
- **A catch-up's receipt.** After the server was down, a `catch-up-once`
|
|
443
|
+
run's `receipt.origin` names the silence it answers for: `missed_first`,
|
|
444
|
+
the first slot that passed unfired, and `missed_count`, how many slots it
|
|
445
|
+
holds; its `scheduled_for` is the last one.
|
|
446
|
+
|
|
447
|
+
**No server?** The CLI can hand a project's armed beats to your operating
|
|
448
|
+
system's scheduler instead: `./node_modules/.bin/nika arm --emit launchd
|
|
449
|
+
--write` on macOS, `--emit systemd` on Linux. A unit started by the OS does
|
|
450
|
+
not see the keys you export in your shell, so pass them with
|
|
451
|
+
`--env-file <file>`. See
|
|
452
|
+
[OS schedulers](https://docs.nika.sh/sdk/operations/os-schedulers) and the
|
|
453
|
+
[known limits](https://docs.nika.sh/changelog/known-limits).
|
|
454
|
+
|
|
455
|
+
## Ask what a route offers
|
|
456
|
+
|
|
457
|
+
A workflow file can declare how its model calls travel: `run.access` (`via`,
|
|
458
|
+
`protocol`, `fallback`, `service_tier`) and `run.reasoning.effort`. A run
|
|
459
|
+
learns what its session offers on the way to its prompt and says so only when
|
|
460
|
+
it refuses. From engine 0.124.3 a server can be asked first:
|
|
461
|
+
|
|
462
|
+
```ts
|
|
463
|
+
const offer = await nika.accessOffer('workflows/brief.nika');
|
|
464
|
+
if (offer.status === 'not_applicable') {
|
|
465
|
+
console.log(offer.reason); // the file selects no ACP sessions
|
|
466
|
+
} else {
|
|
467
|
+
for (const route of offer.routes) {
|
|
468
|
+
if (route.status === 'unavailable') {
|
|
469
|
+
console.log(route.profile, route.code, route.reason);
|
|
470
|
+
continue;
|
|
471
|
+
}
|
|
472
|
+
console.log(route.profile, route.model.status, route.effort?.offered, route.service_tier?.offered);
|
|
473
|
+
// completion confirmed [ 'low', 'medium', 'high' ] [ 'standard', 'fast' ]
|
|
474
|
+
}
|
|
475
|
+
}
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
- **The route is the file's.** The call names a served workflow and nothing
|
|
479
|
+
else. The server asks only when the file declares `run.access.via` under
|
|
480
|
+
`run.access.protocol: acp`; any other workflow answers
|
|
481
|
+
`status: 'not_applicable'` with the reason, and no session is opened.
|
|
482
|
+
- **No prompt is sent.** The server opens each session as a run opens it,
|
|
483
|
+
selects the file's model for that session only, lists what the session has
|
|
484
|
+
for that model and ends it. `prompts_sent` is always `0`: an offer uses no
|
|
485
|
+
turn of the subscription.
|
|
486
|
+
- **One row per session shape and model.** `completion` is the route's
|
|
487
|
+
one-shot profile, which `infer:` tasks run under; `agent` is its agent
|
|
488
|
+
session, which `agent:` tasks run in. `tasks` names the tasks of each row.
|
|
489
|
+
- **`effort.offered` is exact.** It holds the values a run accepts on
|
|
490
|
+
`run.reasoning.effort` for that model, with no case folding and no alias.
|
|
491
|
+
`effort.current` is what a run that declares no effort keeps on a session
|
|
492
|
+
like this one. `service_tier.offered` holds the language's words
|
|
493
|
+
(`standard`, `fast`).
|
|
494
|
+
- **A model the session does not list is a state, not an error.**
|
|
495
|
+
`model.status` is then `not_offered` (with the models it does list in
|
|
496
|
+
`model.offered`), and the efforts and tiers are `unobserved`: they are
|
|
497
|
+
never read from another model. The same holds for `legacy_list` and
|
|
498
|
+
`not_confirmed`.
|
|
499
|
+
- **A session that gives no offer is a row.** `status: 'unavailable'` carries
|
|
500
|
+
the code a run would meet before its prompt (`NIKA-1803` adapter absent,
|
|
501
|
+
silent or outside its pin; `NIKA-1804` session death; `NIKA-1805` refused)
|
|
502
|
+
and a reason.
|
|
503
|
+
- **A row has a time.** `observed_at` and `fresh_until` say when it was read
|
|
504
|
+
and until when the server serves it again (60 seconds, 15 when
|
|
505
|
+
unavailable). One reading runs at a time on the server; a ninth concurrent
|
|
506
|
+
request is refused with `NikaOperationError` `access_offer_busy`.
|
|
507
|
+
|
|
508
|
+
The call has its own deadline, 100 seconds by default (`timeoutMs`), because
|
|
509
|
+
a first reading opens a session per row; `signal` stops it. It needs a server
|
|
510
|
+
that lists `accessSessionOffer`: on another server, and on the local engine,
|
|
511
|
+
it rejects with `NikaCompatibilityError` before any request.
|
|
512
|
+
|
|
513
|
+
An offer authorizes nothing. A model, an effort or a tier can leave a route
|
|
514
|
+
between the offer and the run: `run()` is admitted as before, and the run
|
|
515
|
+
selects, reads back and refuses on its own session.
|
|
516
|
+
|
|
517
|
+
## Local engine or server: what differs
|
|
518
|
+
|
|
519
|
+
| Operation | Local engine | `nika serve` |
|
|
520
|
+
|---|---|---|
|
|
521
|
+
| `check` | yes; `model` and `nativeStrict` allowed | yes; those two refused |
|
|
522
|
+
| `check` `access` | `--access=<pin>`; the report judges the access plan (`verdicts`) | by served name; acknowledged, not judged; an empty pin refused |
|
|
523
|
+
| `run` | yes; `model` and `maxCostUsd` allowed | yes; `idempotencyKey` required; `model` and `maxCostUsd` refused |
|
|
524
|
+
| `run` `access` | `--access=<pin>`; a pin the engine refuses settles the run `failed`, cause `refused` | by served name (`JobByName.access`); a pin the execution refuses settles the job `failed`; an empty pin refused at admission (422); a snapshot refuses it |
|
|
525
|
+
| `run` `inputs` | literal JSON over stdin; the engine must advertise `inputsLiteral` | literal JSON by served name; the server must advertise `jobInputs`; a snapshot refuses them |
|
|
526
|
+
| A file that declares `run.access.service_tier` | the engine must advertise `accessServiceTier`; the task frames carry `access_requirement` and `access_selection` (`readNikaAccessSelection`) | the server must advertise `accessServiceTier`, or it answers 422 for that file; the tier is a field of the file, never of the request; the per-call receipt stays in the sealed journal and no frame carries it |
|
|
527
|
+
| `run` `vars` (deprecated) | the `--var` operator channel, unchanged | refused |
|
|
528
|
+
| `attachRun` | refused: a local run belongs to its process | reattaches to a durable job, from an optional event cursor |
|
|
529
|
+
| `run.status()` | refused; await `run.result()` | the durable status |
|
|
530
|
+
| `run.events()` | lifecycle words over the engine's task and run frames | the same words over sequenced SSE with bounded replay; no per-task events |
|
|
531
|
+
| `run.cancel()` | signals the process; idempotent; in-flight work settles, however long | 200 settles the job; 202 accepts the request, and `run.result()` settles on the server's ending: `interrupted` once the fixed 5-second grace expires |
|
|
532
|
+
| `run.id` | a throwaway correlation id, never durable | the server's durable job id: the one to store |
|
|
533
|
+
| `traceVerify` | the engine's verifier plus the signed receipt binding | the server's verdict on the journal it wrote (`ok`, `sealed`…), or `unavailable` without one |
|
|
534
|
+
| `run.artifacts()` · `run.downloadArtifact()` · `run.readArtifact()` | refused: a local run's files are where its workflow wrote them | the files a settled job's sealed journal records, each download proven against its recorded size and SHA-256, when the server lists `artifacts` |
|
|
535
|
+
| `schedule` / `scheduleStatus` | refused | the server's schedules |
|
|
536
|
+
| `listWorkflows` / `workflow` | refused | the served workflow catalog, without paths |
|
|
537
|
+
| `accessOffer` | refused: an offer is read by a server for a workflow it serves | what the sessions of the workflow's declared ACP route offer now, when the server advertises `accessSessionOffer` |
|
|
538
|
+
| `compile` | the engine's `compile` capability; `authoringModel`, `decisionModel`, `fresh` and `output` allowed | `POST /v1/compile`, when advertised; `cognition` and `replay_token` need `compileNativeV2` |
|
|
539
|
+
|
|
540
|
+
The vocabulary is one; the number of events is not. A local engine reports
|
|
541
|
+
each task, a server reports durable, sequenced execution frames, and the
|
|
542
|
+
package names only what a transport actually sent. Do not assume the same
|
|
543
|
+
count on both. The frames under `event.raw` stay deliberately open.
|