@nika-open/nika 0.0.0-bootstrap.0 → 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/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.