@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/LICENSE +202 -0
- package/README.md +775 -5
- 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 +87 -7
package/README.md
CHANGED
|
@@ -1,7 +1,777 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://nika.sh">
|
|
3
|
+
<picture>
|
|
4
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://nika.sh/brand/nika-logo-dark.svg">
|
|
5
|
+
<img src="https://nika.sh/brand/nika-logo-light.svg" alt="Nika" width="220">
|
|
6
|
+
</picture>
|
|
7
|
+
</a>
|
|
8
|
+
</p>
|
|
2
9
|
|
|
3
|
-
|
|
4
|
-
of [nika-open/nika-client](https://github.com/nika-open/nika-client), which publishes every real
|
|
5
|
-
version from GitHub Actions with provenance.
|
|
10
|
+
<h1 align="center">@nika-open/nika</h1>
|
|
6
11
|
|
|
7
|
-
|
|
12
|
+
<p align="center">
|
|
13
|
+
<strong>Run AI workflows from your TypeScript app, and prove what they did.</strong><br>
|
|
14
|
+
Checked before they start, typed when they finish, verifiable afterwards: the Nika engine ships inside the package.
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
<p align="center">
|
|
18
|
+
<a href="https://www.npmjs.com/package/@nika-open/nika"><img src="https://img.shields.io/npm/v/@nika-open/nika?label=npm" alt="npm version"></a>
|
|
19
|
+
<a href="https://github.com/nika-open/nika-client/actions/workflows/ci.yml"><img src="https://github.com/nika-open/nika-client/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI status"></a>
|
|
20
|
+
<a href="https://github.com/nika-open/nika/releases/latest"><img src="https://img.shields.io/github/v/release/nika-open/nika?label=engine" alt="Engine release"></a>
|
|
21
|
+
<a href="https://docs.nika.sh"><img src="https://img.shields.io/badge/docs-docs.nika.sh-8b8cf8.svg" alt="Documentation"></a>
|
|
22
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="Apache-2.0"></a>
|
|
23
|
+
<br>
|
|
24
|
+
<a href="https://scorecard.dev/viewer/?uri=github.com/nika-open/nika-client"><img src="https://api.scorecard.dev/projects/github.com/nika-open/nika-client/badge" alt="OpenSSF Scorecard"></a>
|
|
25
|
+
<a href="https://www.npmjs.com/package/@nika-open/nika"><img src="https://img.shields.io/badge/npm-provenance-2ea44f.svg" alt="Published with provenance through GitHub Actions trusted publishing"></a>
|
|
26
|
+
<a href="https://www.npmjs.com/package/@nika-open/nika"><img src="https://img.shields.io/npm/dm/@nika-open/nika?label=downloads" alt="npm downloads"></a>
|
|
27
|
+
<a href="https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/nika-open/nika-client"><img src="https://archive.softwareheritage.org/badge/origin/https://github.com/nika-open/nika-client/" alt="Archived by Software Heritage"></a>
|
|
28
|
+
</p>
|
|
29
|
+
|
|
30
|
+
**Watch this README's quick start run as written: install, one signing key, `run()`, a typed result, a verified receipt.**
|
|
31
|
+
|
|
32
|
+
<p align="center">
|
|
33
|
+
<picture>
|
|
34
|
+
<source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/stills/sdk-quickstart.png">
|
|
35
|
+
<img src="media/gifs/sdk-quickstart.gif" alt="A terminal runs npm install @supernovae-st/nika@0.124.0, which adds 2 packages: nika and nika-darwin-arm64. ./node_modules/.bin/nika --version prints nika 0.124.0 (866ed914b), and NIKA_KEYCHAIN=off ./node_modules/.bin/nika key init mints a run-signing key. The screen shows hello.nika and demo.mts from this README, then node demo.mts prints mock(echo) · Say hello from the Nika SDK. and receipt verified" width="960">
|
|
36
|
+
</picture>
|
|
37
|
+
</p>
|
|
38
|
+
<p align="center"><sub><code>npm install</code> brings the client and its native engine (two packages; the version is pinned on camera), step 1's <code>nika key init</code> mints the signing key, and <code>node demo.mts</code> prints the greeting and <code>receipt verified</code>. <code>hello.nika</code> and <code>demo.mts</code> are this page's, byte for byte. Recorded in a terminal from <code>@supernovae-st/nika</code> 0.124.0 and its bundled engine <code>nika 0.124.0 (866ed914b)</code>; the run is a <code>mock/echo</code> rehearsal.<br>▶ <a href="media/videos/sdk-quickstart.mp4?raw=true">MP4</a> · <a href="media/transcripts/sdk-quickstart.txt">transcript</a> · <a href="media/README.md">how these recordings are made</a></sub></p>
|
|
39
|
+
|
|
40
|
+
## What is Nika?
|
|
41
|
+
|
|
42
|
+
Nika turns repeatable AI work into a small file you keep. Say what you
|
|
43
|
+
want done, like *"every Monday, pull the action items out of my meeting
|
|
44
|
+
notes"*, and Nika writes it as a readable `.nika` workflow. Before
|
|
45
|
+
anything runs, `nika check` shows what the workflow will do, which models
|
|
46
|
+
and tools it uses, what it is allowed to touch and what it can cost,
|
|
47
|
+
without calling a model. You run it when you decide, with the model you
|
|
48
|
+
choose, local or cloud, and every run leaves a tamper-evident record you
|
|
49
|
+
can verify. One Rust binary, local-first, open source (AGPL-3.0).
|
|
50
|
+
|
|
51
|
+
| 1 · Say it | 2 · Check it | 3 · Run it | 4 · Prove it |
|
|
52
|
+
|:---:|:---:|:---:|:---:|
|
|
53
|
+
| Describe the job; Nika writes a `.nika` file | `nika check` audits it before any model is called | `nika run` with the model you choose | `nika trace verify` checks the run's record |
|
|
54
|
+
|
|
55
|
+
> [!TIP]
|
|
56
|
+
> **This package puts steps 2, 3 and 4 in your code.** `check()` audits a
|
|
57
|
+
> workflow, `run()` runs it and hands your app a typed result, and
|
|
58
|
+
> `traceVerify()` proves what ran. The engine comes inside the npm package:
|
|
59
|
+
> on macOS, and on Linux with glibc, there is nothing else to install.
|
|
60
|
+
|
|
61
|
+
<p align="center">
|
|
62
|
+
<a href="#quick-start">Quick start</a> ·
|
|
63
|
+
<a href="#what-happens-underneath">What happens underneath</a> ·
|
|
64
|
+
<a href="#two-doors-your-machine-or-your-server">Two doors</a> ·
|
|
65
|
+
<a href="#use-a-real-model">Use a real model</a> ·
|
|
66
|
+
<a href="#prove-what-ran">Prove what ran</a> ·
|
|
67
|
+
<a href="#api-reference">API reference</a> ·
|
|
68
|
+
<a href="#troubleshooting">Troubleshooting</a> ·
|
|
69
|
+
<a href="#install-and-versions">Install and versions</a>
|
|
70
|
+
</p>
|
|
71
|
+
|
|
72
|
+
## What you can build
|
|
73
|
+
|
|
74
|
+
Anything where your app hands work to AI and needs to trust what happened.
|
|
75
|
+
For example:
|
|
76
|
+
|
|
77
|
+
| You can build | How this package helps |
|
|
78
|
+
|---|---|
|
|
79
|
+
| **A webhook that runs a workflow per event** | On your `nika serve`, pass the verified payload as `inputs` and the sender's delivery id as `idempotencyKey`: a retried delivery reuses the same job instead of running twice ([server.md](https://github.com/nika-open/nika-client/blob/main/docs/server.md#retries-without-duplicates)). |
|
|
80
|
+
| **A release gate that can say no** | Run the checks in parallel inside one workflow, allow or refuse the deploy from its result, and keep the verified receipt ([runs.md](https://github.com/nika-open/nika-client/blob/main/docs/runs.md#read-the-result), [receipts.md](https://github.com/nika-open/nika-client/blob/main/docs/receipts.md)). |
|
|
81
|
+
| **A monitor that runs on a schedule** | Declare the cadence on your `nika serve` with `schedule()`, change it safely by revision, and reconnect after a restart ([server.md](https://github.com/nika-open/nika-client/blob/main/docs/server.md#schedules)). |
|
|
82
|
+
| **An incident assistant you can stop** | Follow each step with `run.events()` and stop it cleanly with `run.cancel()` ([`watch-and-cancel.ts`](https://github.com/nika-open/nika-client/blob/main/examples/watch-and-cancel.ts)). |
|
|
83
|
+
|
|
84
|
+
Runnable programs live in [`examples/`](https://github.com/nika-open/nika-client/tree/main/examples).
|
|
85
|
+
The release tests in
|
|
86
|
+
[`gauntlet/projects-depth`](https://github.com/nika-open/nika-client/tree/main/gauntlet/projects-depth)
|
|
87
|
+
exercise each row as a fresh Node app that installs this package from its npm
|
|
88
|
+
tarball and runs against the real engine. They are release tests, not
|
|
89
|
+
templates to copy: they also exercise the deprecated `vars`,
|
|
90
|
+
`nika.events(run)` and `run.done` forms.
|
|
91
|
+
|
|
92
|
+
## Quick start
|
|
93
|
+
|
|
94
|
+
You need Node.js 22 or newer, on macOS or Linux (glibc). The TypeScript file
|
|
95
|
+
in step 3 runs as is on Node.js 22.18 or newer; on an older 22.x, name it
|
|
96
|
+
`demo.mjs` and remove `<{ greeting: string }>`.
|
|
97
|
+
|
|
98
|
+
**1 · Install the package.** npm brings the matching engine with it, and the
|
|
99
|
+
`nika` command at `./node_modules/.bin/nika`.
|
|
100
|
+
|
|
101
|
+
```sh
|
|
102
|
+
npm install @nika-open/nika
|
|
103
|
+
NIKA_KEYCHAIN=off ./node_modules/.bin/nika key init # once per machine: a key that signs each run's record
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
`NIKA_KEYCHAIN=off` makes `nika key init` write the key as files, to
|
|
107
|
+
`~/.nika/keys/` (mode `0600`). That is where the engine your app starts and
|
|
108
|
+
`nika serve` read it, on macOS and on Linux. Without the variable,
|
|
109
|
+
`nika key init` refuses on a Linux terminal (its `--force` puts the key in the
|
|
110
|
+
desktop's Secret Service, where neither looks) and on a Mac whose keychain
|
|
111
|
+
holds a key from Nika 0.122 or older.
|
|
112
|
+
|
|
113
|
+
**2 · Write a workflow.** Save this as `hello.nika`:
|
|
114
|
+
|
|
115
|
+
```yaml
|
|
116
|
+
nika: hello
|
|
117
|
+
model: mock/echo
|
|
118
|
+
permits: {}
|
|
119
|
+
tasks:
|
|
120
|
+
greeting:
|
|
121
|
+
infer:
|
|
122
|
+
prompt: "Say hello from the Nika SDK."
|
|
123
|
+
max_tokens: 32
|
|
124
|
+
outputs:
|
|
125
|
+
greeting: ${{ tasks.greeting.output }}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
A `.nika` file is a readable workflow: the model to use, what the workflow may
|
|
129
|
+
reach, run and read (its *permits*; `permits: {}` grants no file, network,
|
|
130
|
+
command or tool access), its tasks and its outputs. `mock/echo` is the
|
|
131
|
+
engine's offline rehearsal model: it echoes the prompt back, with no key and
|
|
132
|
+
no network.
|
|
133
|
+
|
|
134
|
+
<details>
|
|
135
|
+
<summary><b>Let the engine write the file, or audit it before anything runs</b></summary>
|
|
136
|
+
|
|
137
|
+
```sh
|
|
138
|
+
./node_modules/.bin/nika compile --list # the ready-made skeletons
|
|
139
|
+
./node_modules/.bin/nika compile hello hello.nika # writes a starter hello.nika (its task asks for French)
|
|
140
|
+
./node_modules/.bin/nika check hello.nika # the audit, without calling a model
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
`nika check` is the static audit that runs before any model is called: what
|
|
144
|
+
the workflow will do, which models and tools it uses, what it may touch and
|
|
145
|
+
what it can cost. An excerpt of its report for the file above, on engine
|
|
146
|
+
0.124.5:
|
|
147
|
+
|
|
148
|
+
```text
|
|
149
|
+
nika check · hello.nika
|
|
150
|
+
✔ PLAN 1 wave · 1 task · max parallelism 1
|
|
151
|
+
wave 1 greeting (infer · mock/echo)
|
|
152
|
+
✔ MODELS 1 model resolves in this binary · this machine's paths on the ACCESS line
|
|
153
|
+
✔ ACCESS mock/echo → mock (mock · local · observed) · mock · this model route never dials
|
|
154
|
+
✔ COST $0.0000 – $0.0000 worst-case output ceiling · prompts, exec + mcp unpriced · prices 2026-10-12
|
|
155
|
+
…
|
|
156
|
+
✔ PERMITS literal + const: args fit the boundary · computed programs, paths + symlinks are the RUN's verdict
|
|
157
|
+
✔ TRIFECTA no lethal trifecta over the declared permits: without a human gate
|
|
158
|
+
✔ JOURNEY internal · 0 sources · 0 destinations · 1 model endpoint · no secret reaches an external destination
|
|
159
|
+
✔ audited · 1 task · 1 wave · permits {} · est out ≤$0.0000 · 0 hints · risk low
|
|
160
|
+
layers · valid ✔ · access ready ✔ · capacity fit ✔ · run ready ✔
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
`mock/echo` stands in for the model only. A task's own fetch, MCP tool or
|
|
164
|
+
paid media call still reaches the network in a rehearsal, so from engine
|
|
165
|
+
0.124.1 the ACCESS row names such tasks under its line, and `check()` lists
|
|
166
|
+
them in `verdicts.network_tasks` (this file has none).
|
|
167
|
+
|
|
168
|
+
▶ [Watch compile, check, run and verify on the command line](https://raw.githubusercontent.com/nika-open/nika/v0.123.0/media/gifs/full-loop.optimized.gif):
|
|
169
|
+
the same loop your code drives, all four commands captured from the real
|
|
170
|
+
CLI (engine 0.121.0), the run a `mock/echo` rehearsal.
|
|
171
|
+
|
|
172
|
+
</details>
|
|
173
|
+
|
|
174
|
+
**3 · Run it and verify it from TypeScript.** Save this as `demo.mts`:
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
import { Nika, isNikaRunSucceeded } from '@nika-open/nika';
|
|
178
|
+
|
|
179
|
+
const nika = new Nika({ cwd: process.cwd() });
|
|
180
|
+
|
|
181
|
+
// The engine checks the file first: a workflow it refuses throws here and never starts.
|
|
182
|
+
const run = await nika.run<{ greeting: string }>('hello.nika', { maxCostUsd: 0 });
|
|
183
|
+
const result = await run.result();
|
|
184
|
+
|
|
185
|
+
// A failed run is data you read, not an exception.
|
|
186
|
+
if (!isNikaRunSucceeded(result) || !result.receipt) {
|
|
187
|
+
console.error(result.status, result.error?.code, result.error?.message);
|
|
188
|
+
process.exit(1);
|
|
189
|
+
}
|
|
190
|
+
console.log(result.outputs?.greeting);
|
|
191
|
+
|
|
192
|
+
// Ask the engine to verify the run's tamper-evident record.
|
|
193
|
+
const proof = await nika.traceVerify(result.receipt);
|
|
194
|
+
console.log(proof.verified ? 'receipt verified' : `not verified: ${proof.reason}`);
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
```sh
|
|
198
|
+
node demo.mts
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
```text
|
|
202
|
+
mock(echo) · Say hello from the Nika SDK.
|
|
203
|
+
receipt verified
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
`maxCostUsd: 0` gives the run a budget of zero dollars for paid model calls:
|
|
207
|
+
the engine refuses to start a run whose paid calls would cost more, and never
|
|
208
|
+
blocks local or mock models. The `mock(echo) ·` prefix marks a rehearsal, not
|
|
209
|
+
a model's answer. [Use a real model](#use-a-real-model) when you are ready.
|
|
210
|
+
From engine 0.124 the budget covers paid image and speech calls too: a call
|
|
211
|
+
the engine's dated price table prices is floored and billed against it, and
|
|
212
|
+
one the table cannot price is refused before any request (`NIKA-1709`).
|
|
213
|
+
Local and mock models and the keyless system voice are never blocked.
|
|
214
|
+
|
|
215
|
+
> [!NOTE]
|
|
216
|
+
> **Seeing `not verified: receipt_mismatch`?** The run succeeded, but the
|
|
217
|
+
> engine your app started found no signing key it can read, so the run's
|
|
218
|
+
> record is unsealed. That engine reads `~/.nika/keys/` (or the
|
|
219
|
+
> `NIKA_RUN_KEY_FILE` and `NIKA_RUN_PUB_FILE` pair), never an OS keychain.
|
|
220
|
+
> Run step 1's `NIKA_KEYCHAIN=off ./node_modules/.bin/nika key init`, then
|
|
221
|
+
> run the demo again. A key that Nika 0.122 or older kept in the macOS
|
|
222
|
+
> keychain cannot be read or copied by Nika 0.123 and later, which never
|
|
223
|
+
> open the keychain on macOS: on such a Mac, this command mints a new key as
|
|
224
|
+
> files.
|
|
225
|
+
> On Linux, a key that `nika key init --force` put in the Secret Service can
|
|
226
|
+
> be copied instead, from a terminal: `./node_modules/.bin/nika key align`.
|
|
227
|
+
|
|
228
|
+
The same file is [`examples/quick-start.ts`](https://github.com/nika-open/nika-client/blob/main/examples/quick-start.ts),
|
|
229
|
+
next to examples that watch, cancel and recover runs.
|
|
230
|
+
|
|
231
|
+
## What happens underneath
|
|
232
|
+
|
|
233
|
+
**Watch a call travel from your code through the package to the engine, through either door.**
|
|
234
|
+
|
|
235
|
+
<p align="center">
|
|
236
|
+
<picture>
|
|
237
|
+
<source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/stills/sdk-doors.png">
|
|
238
|
+
<img src="media/gifs/sdk-doors.gif" alt="Animated diagram. The README's demo.mts on the left; the @supernovae-st/nika package in the middle; two doors on the right: new Nika() leads to the bundled engine nika 0.124.0 as a child process, new Nika({ url, token }) to nika serve, and lines 3 and 6 of demo.mts switch between them: the constructor takes url, token and allowInsecureHttp, and run() takes an idempotencyKey in place of maxCostUsd. A refused list-files.nika gets NIKA-SEC-004 and no run exists; hello.nika runs; six local events or two server events reach the app; six hash-chained journal lines end with run_sealed; traceVerify() answers verified locally and sealed on the server; one changed byte gives BROKEN at line 5" width="960">
|
|
239
|
+
</picture>
|
|
240
|
+
</p>
|
|
241
|
+
<p align="center"><sub>An illustration with captured content: the code is this README's quick start, which the capture ran, with lines 3 and 6 also as the capture's server driver ran them against <code>nika serve</code>, and every event, verdict, hash and version on screen comes from <code>@supernovae-st/nika</code> 0.124.0, its bundled engine and <code>nika serve</code> 0.124.0 in a <code>mock/echo</code> rehearsal. The cards, lanes, packets and pacing are drawn; a real run takes milliseconds. The code is readable in the 1600 px MP4.<br>▶ <a href="media/videos/sdk-doors.mp4?raw=true">MP4</a> · <a href="media/README.md#sdk-doors-an-illustration">what is captured and what is drawn</a></sub></p>
|
|
242
|
+
|
|
243
|
+
`new Nika()` starts nothing. On the first call it asks the bundled engine who
|
|
244
|
+
it is; then each call runs the engine as a child process, without a shell, in
|
|
245
|
+
your working directory:
|
|
246
|
+
|
|
247
|
+
```mermaid
|
|
248
|
+
sequenceDiagram
|
|
249
|
+
autonumber
|
|
250
|
+
participant App as Your code
|
|
251
|
+
participant SDK as @nika-open/nika
|
|
252
|
+
participant Engine as nika engine (child process)
|
|
253
|
+
App->>SDK: nika.run('hello.nika', { maxCostUsd: 0 })
|
|
254
|
+
SDK->>Engine: nika --sdk-identity (once per client)
|
|
255
|
+
Engine-->>SDK: version (the package's own), machine protocol 2, capabilities
|
|
256
|
+
SDK->>Engine: nika run hello.nika --json --max-cost-usd 0
|
|
257
|
+
Engine-->>SDK: first frame: admitted, or a refusal
|
|
258
|
+
SDK-->>App: NikaRun (a refusal rejects run() instead)
|
|
259
|
+
Engine-->>SDK: task frames, then run_settled with outputs and receipt
|
|
260
|
+
SDK-->>App: run.events(), then run.result()
|
|
261
|
+
App->>SDK: nika.traceVerify(result.receipt)
|
|
262
|
+
SDK->>Engine: nika trace verify, nika trace evidence
|
|
263
|
+
SDK-->>App: { verified, verdict, reason }
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
- **The engine decides.** It parses, audits, runs and records every workflow.
|
|
267
|
+
The process that runs a workflow is the one that judged it: no preflight,
|
|
268
|
+
no second spawn. This package carries the engine's answers to your code,
|
|
269
|
+
typed; it never parses the file itself or re-implements the proof.
|
|
270
|
+
- **The record is the engine's.** Every run writes a trace under
|
|
271
|
+
`.nika/traces/` in the working directory, and with a signing key the engine
|
|
272
|
+
seals it when the run ends. Keep `.nika/` out of git.
|
|
273
|
+
- **Your environment is the engine's.** The engine inherits your process
|
|
274
|
+
environment: that is where provider keys and `NIKA_*` settings come from.
|
|
275
|
+
It is the engine that came with the package, or `bin`/`NIKA_BIN` when you
|
|
276
|
+
set one (an absolute path), never a `nika` found on your `PATH`.
|
|
277
|
+
|
|
278
|
+
A run gives you three different facts, and each has its own evidence:
|
|
279
|
+
|
|
280
|
+
| Fact | How you see it | What it is not |
|
|
281
|
+
|---|---|---|
|
|
282
|
+
| **Admitted** | `run()` resolves with a `NikaRun`. A workflow the engine refuses makes `run()` throw `NikaOperationError` (`NIKA-SEC-004`, `NIKA-PARSE-005`, `NIKA-1708`…), and no run exists. | Not a successful execution. |
|
|
283
|
+
| **Executed** | `run.result()` and `isNikaRunSucceeded(result)`. An admitted failure is data (`status: "failed"`). A human gate is `paused` (a `run.waiting` event), not success. | Not proof that the record is sealed. |
|
|
284
|
+
| **Sealed** | `result.receipt.sealed` and `traceVerify(receipt)`. Tamper-evident, not tamper-proof. | Not "the workflow was correct", and not "a person read the output". |
|
|
285
|
+
|
|
286
|
+
**Watch the three facts from TypeScript: a refused file never runs, a run without a key is not sealed, and one changed byte breaks the proof.**
|
|
287
|
+
|
|
288
|
+
<p align="center">
|
|
289
|
+
<picture>
|
|
290
|
+
<source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/stills/sdk-admitted-executed-sealed.png">
|
|
291
|
+
<img src="media/gifs/sdk-admitted-executed-sealed.gif" alt="node gate.mts on a workflow that runs ls under permits: {} prints check refused · exit 2, NIKA-SEC-004 and its fix, then run not started: no run, no events, no trace. A one-line permits fix checks clean and runs. node prove.mts with no signing key prints sealed false and not verified · receipt_mismatch; after NIKA_KEYCHAIN=off nika key init it prints sealed true and verified. node tamper.mts changes one byte of the trace, and node verify.mts prints not verified and the engine's BROKEN at line 5" width="960">
|
|
292
|
+
</picture>
|
|
293
|
+
</p>
|
|
294
|
+
<p align="center"><sub><code>check()</code> refuses a file that runs <code>ls</code> under <code>permits: {}</code> (<code>NIKA-SEC-004</code>) and <code>run()</code> never starts it; one permits line fixes it. On a machine with no signing key the run succeeds unsealed and <code>traceVerify()</code> answers <code>receipt_mismatch</code>; after step 1's <code>nika key init</code> the next run of the same file is sealed and verified. One changed byte in the trace, and the engine answers <code>BROKEN at line 5</code>. Recorded from <code>@supernovae-st/nika</code> 0.124.0 and its bundled engine; the runs are <code>mock/echo</code> rehearsals.<br>▶ <a href="media/videos/sdk-admitted-executed-sealed.mp4?raw=true">MP4</a> · <a href="media/transcripts/sdk-admitted-executed-sealed.txt">transcript</a> · <a href="scripts/media/scenes/sdk-admitted-executed-sealed">the programs it runs</a></sub></p>
|
|
295
|
+
|
|
296
|
+
- **The file is the boundary.** A workflow lists what it may reach in
|
|
297
|
+
`permits:`, and the check catches the task that reaches past it before any
|
|
298
|
+
model is called.
|
|
299
|
+
▶ [The same audit on the command line](https://raw.githubusercontent.com/nika-open/nika/v0.123.0/media/gifs/permits-audit.optimized.gif) (captured on engine 0.121.0)
|
|
300
|
+
- **Failures you planned for.** `on_error: recover` absorbs a missing live
|
|
301
|
+
feed: the run finishes, the output says stale, the trace records the
|
|
302
|
+
failure. ▶ [Watch a missing feed absorbed](https://raw.githubusercontent.com/nika-open/nika/v0.123.0/media/gifs/on-error-recover.optimized.gif) (the CLI, captured on engine 0.121.0)
|
|
303
|
+
|
|
304
|
+
## Two doors: your machine or your server
|
|
305
|
+
|
|
306
|
+
The same `Nika` class reaches an engine through one of two doors, and the
|
|
307
|
+
constructor chooses it: `check`, `run`, `events`, `cancel` and `traceVerify`
|
|
308
|
+
keep their names and meaning on both. Some options change with the door: on a
|
|
309
|
+
server, `run()` needs an `idempotencyKey` and refuses `maxCostUsd`, and plain
|
|
310
|
+
`http://` needs `allowInsecureHttp: true` (the table says what each door
|
|
311
|
+
takes). `schedule` and `scheduleStatus` need a server, because a short-lived
|
|
312
|
+
local process cannot honestly own a schedule.
|
|
313
|
+
|
|
314
|
+
| | `new Nika()` | `new Nika({ url, token })` |
|
|
315
|
+
|---|---|---|
|
|
316
|
+
| **The engine** | the bundled engine, as a child process for each call | your `nika serve`, over HTTPS (plain HTTP to loopback only) |
|
|
317
|
+
| **A run is** | a handle that lives in your process | a durable job on the server, which a new process can reattach to |
|
|
318
|
+
| **Events** | each task, then the settlement (six for the quick start) | `run.started` and `run.settled`, each with a replay cursor; a job with inputs opens with `execution.queued`, an `engine.event` |
|
|
319
|
+
| **Retries** | not applicable | an `idempotencyKey` you own: the same key returns the same job |
|
|
320
|
+
| **Recovery** | none: a local run belongs to its process | `attachRun(jobId, { lastEventId })` |
|
|
321
|
+
| **Schedules** | refused (the CLI's `nika arm` can hand them to the OS) | `schedule()` and `scheduleStatus()` |
|
|
322
|
+
| **Spend limit** | `maxCostUsd` per run | the server's own ceiling per job (`nika serve --run-cost-ceiling`, 1 USD by default); a schedule's `maxCostUsd` |
|
|
323
|
+
| **Proof** | the engine verifies the local trace against your receipt | the server's verdict on the job's journal |
|
|
324
|
+
| **Files a run produced** | where its workflow wrote them, in your `cwd` | `run.artifacts()` lists them from the job's sealed journal; `run.downloadArtifact()` streams one, proven against its recorded SHA-256 |
|
|
325
|
+
|
|
326
|
+
**Your server in a few lines.** In the folder that holds `hello.nika`, give
|
|
327
|
+
the server a project file and a private token, then start it:
|
|
328
|
+
|
|
329
|
+
```sh
|
|
330
|
+
test -f nika.yaml || printf 'nika: my-project\n' > nika.yaml
|
|
331
|
+
mkdir -p .nika && (umask 077 && openssl rand -hex 24 > .nika/serve.token)
|
|
332
|
+
printf '.nika/\n' >> .gitignore # traces, job state and the token stay out of git
|
|
333
|
+
./node_modules/.bin/nika serve --bind 127.0.0.1:8787 --workflows . --token-file .nika/serve.token
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
From another terminal, the same app talks to it:
|
|
337
|
+
|
|
338
|
+
```ts
|
|
339
|
+
import { readFile } from 'node:fs/promises';
|
|
340
|
+
import { Nika } from '@nika-open/nika';
|
|
341
|
+
|
|
342
|
+
const token = (await readFile('.nika/serve.token', 'utf8')).trim();
|
|
343
|
+
const nika = new Nika({ url: 'http://127.0.0.1:8787', token, allowInsecureHttp: true });
|
|
344
|
+
|
|
345
|
+
const run = await nika.run('hello.nika', { idempotencyKey: 'hello-2026-10-24' }); // store it; reuse it on retry
|
|
346
|
+
for await (const event of run.events()) console.log(event.sequence, event.kind, event.status);
|
|
347
|
+
const { receipt } = await run.result();
|
|
348
|
+
const proof = receipt && (await nika.traceVerify(receipt));
|
|
349
|
+
console.log(proof?.verified, proof?.verdict);
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
```text
|
|
353
|
+
1 run.started running
|
|
354
|
+
2 run.settled succeeded
|
|
355
|
+
true sealed
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
`hello.nika` is now a name the server resolves in its `--workflows` folder,
|
|
359
|
+
so your app needs no local engine for it. A server with a signing key answers
|
|
360
|
+
`sealed`; one without answers `ok`. Store `run.id` (the job id) and the last
|
|
361
|
+
`event.sequence` you processed, and a new process picks the job back up with
|
|
362
|
+
`attachRun`. [docs/server.md](https://github.com/nika-open/nika-client/blob/main/docs/server.md)
|
|
363
|
+
covers setup, retries, recovery, restarts, artifacts, connection rules and schedules,
|
|
364
|
+
and [`examples/server-recovery.ts`](https://github.com/nika-open/nika-client/blob/main/examples/server-recovery.ts)
|
|
365
|
+
recovers a job across two processes.
|
|
366
|
+
|
|
367
|
+
**Watch the server lines above run, then one job, a retry and a wrong token.**
|
|
368
|
+
|
|
369
|
+
<p align="center">
|
|
370
|
+
<picture>
|
|
371
|
+
<source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/stills/sdk-remote.png">
|
|
372
|
+
<img src="media/gifs/sdk-remote.gif" alt="The terminal types this README's server setup: a one-line nika.yaml, a token minted into .nika/serve.token with umask 077, .nika/ appended to .gitignore, NIKA_KEYCHAIN=off nika key init, and 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="960">
|
|
373
|
+
</picture>
|
|
374
|
+
</p>
|
|
375
|
+
<p align="center"><sub>The setup lines above, typed as written (the server goes to the background of the same terminal), then a client built with <code>new Nika({ url, token, allowInsecureHttp: true })</code>: it lists and checks the served <code>hello.nika</code>, runs it with an idempotency key, receives the 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="media/videos/sdk-remote.mp4?raw=true">MP4</a> · <a href="media/transcripts/sdk-remote.txt">transcript</a> · <a href="scripts/media/scenes/sdk-remote/remote.mts">the client it runs</a></sub></p>
|
|
376
|
+
|
|
377
|
+
## Use a real model
|
|
378
|
+
|
|
379
|
+
`mock/echo` rehearses the mechanics. For a real answer, change `model:` in
|
|
380
|
+
the workflow to one that `./node_modules/.bin/nika catalog` lists.
|
|
381
|
+
|
|
382
|
+
- **A local model, no key.** With [Ollama](https://ollama.com) running:
|
|
383
|
+
|
|
384
|
+
```sh
|
|
385
|
+
ollama pull llama3.2:3b
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
```yaml
|
|
389
|
+
model: ollama/llama3.2:3b
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
- **A cloud model.** Export the key variable `nika catalog` names for the
|
|
393
|
+
provider (`MISTRAL_API_KEY` for `mistral/mistral-small-latest`) in the
|
|
394
|
+
environment that starts your app: the engine inherits it. Raise
|
|
395
|
+
`maxCostUsd` to the budget you accept, for example `{ maxCostUsd: 0.05 }`.
|
|
396
|
+
Never put a key in `inputs`.
|
|
397
|
+
- **Check the machine.** `./node_modules/.bin/nika doctor` diagnoses access
|
|
398
|
+
paths, providers and the signing key, and prints fixes; it changes
|
|
399
|
+
nothing. `nika doctor --ping` also probes local model servers. From engine
|
|
400
|
+
0.124 it also names the binary that runs (the one this package installed
|
|
401
|
+
reads `installer: npm-payload`) and every other `nika` on your `PATH` with
|
|
402
|
+
its version, which your app never uses but your shell may.
|
|
403
|
+
|
|
404
|
+
On a server, the provider keys belong to the server's environment, and a
|
|
405
|
+
server run takes no per-run model: the workflow names it.
|
|
406
|
+
|
|
407
|
+
**Watch the same engine audit a real job, then run it on a local model.**
|
|
408
|
+
|
|
409
|
+
<p align="center">
|
|
410
|
+
<picture>
|
|
411
|
+
<source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/nika-open/nika/v0.123.0/media/posters/nika-hero.png">
|
|
412
|
+
<img src="https://raw.githubusercontent.com/nika-open/nika/v0.123.0/media/gifs/nika-hero.optimized.gif" alt="nika check audits a meeting-actions workflow, then nika run executes it on a local model through Ollama and writes the meeting's action items to a typed JSON file" width="860">
|
|
413
|
+
</picture>
|
|
414
|
+
</p>
|
|
415
|
+
<p align="center"><sub>The same engine from the command line, on a real job: the audit first, then a run on a local model that writes a meeting's action items as typed JSON. The audit was captured on engine 0.121.0; the run was captured on engine 0.109.2 (August 2026) with a real local model (<code>ollama/llama3.2:3b</code>).</sub></p>
|
|
416
|
+
|
|
417
|
+
## Prove what ran
|
|
418
|
+
|
|
419
|
+
Every run leaves a *trace*: a tamper-evident, hash-chained record of what
|
|
420
|
+
happened. The run hands your code a receipt, and `traceVerify(receipt)` asks
|
|
421
|
+
the engine to check the trace against it. With a signing key, the engine also
|
|
422
|
+
seals the trace: it signs the record when the run ends.
|
|
423
|
+
|
|
424
|
+
| Where the run happened | `traceVerify()` answers |
|
|
425
|
+
|---|---|
|
|
426
|
+
| Your machine, with a key the engine can read | `{ verified: true, verdict: 'verified' }`: the record is sealed and matches the receipt |
|
|
427
|
+
| Your machine, no key it can read | `{ verified: false, verdict: 'invalid', reason: 'receipt_mismatch' }`: the run still succeeded, but its record is unsealed |
|
|
428
|
+
| `nika serve` with a key | `{ verified: true, verdict: 'sealed', reason: 'sealed' }` |
|
|
429
|
+
| `nika serve` without one | `{ verified: true, verdict: 'ok', reason: 'unsealed' }`: intact, but unsigned |
|
|
430
|
+
|
|
431
|
+
All four rows were measured with the quick-start file on engine 0.123.0.
|
|
432
|
+
|
|
433
|
+
> [!WARNING]
|
|
434
|
+
> **Over HTTP, check `proof.verified` first.** `verdict` and `reason` are the
|
|
435
|
+
> server's words about the job's journal and stay `sealed` even when the
|
|
436
|
+
> receipt you passed does not match it; then `verified` is `false`. Treat a
|
|
437
|
+
> job as sealed only when
|
|
438
|
+
> `proof.verified && ['sealed', 'anchored', 'replayed'].includes(proof.verdict ?? '')`.
|
|
439
|
+
|
|
440
|
+
> [!IMPORTANT]
|
|
441
|
+
> A verified receipt proves that the run's record is intact and matches the
|
|
442
|
+
> receipt. It does not prove that the workflow was right, or that a person
|
|
443
|
+
> read its output. The record is tamper-evident, not tamper-proof. And
|
|
444
|
+
> `receipt_mismatch` is also the engine's answer for a tampered or edited
|
|
445
|
+
> receipt: do not read every one as "just unsigned".
|
|
446
|
+
|
|
447
|
+
**What the local answers look like: unsealed, sealed and verified, then tampered.**
|
|
448
|
+
|
|
449
|
+
<p align="center">
|
|
450
|
+
<img src="media/stills/sdk-admitted-executed-sealed.png" alt="node prove.mts with no signing key prints run succeeded, receipt sealed false · 5 events and verify not verified · invalid · receipt_mismatch. NIKA_KEYCHAIN=off ./node_modules/.bin/nika key init mints a key, and node prove.mts prints receipt sealed true · 6 events and verify verified. node tamper.mts changes one byte on line 4 of the trace, and node verify.mts prints not verified · invalid and engine BROKEN at line 5" width="860">
|
|
451
|
+
</p>
|
|
452
|
+
<p align="center"><sub>The last screen of the recording above. With no signing key the run succeeds with <code>sealed false</code> and <code>receipt_mismatch</code>; step 1's <code>nika key init</code> seals the next run, and <code>traceVerify()</code> answers <code>verified</code>; after one changed byte on line 4 of its trace, the stored receipt no longer verifies and the engine names the line: <code>BROKEN at line 5</code>. Captured from <code>@supernovae-st/nika</code> 0.124.0 and its bundled engine; the runs are <code>mock/echo</code> rehearsals.<br>▶ <a href="https://raw.githubusercontent.com/nika-open/nika/v0.123.0/media/gifs/trace-proof.optimized.gif">The chain check on the command line</a>: an illustration over a real <code>nika trace verify</code>, captured on engine 0.121.0</sub></p>
|
|
453
|
+
|
|
454
|
+
**Signing keys.** The engine your app starts and `nika serve` sign with
|
|
455
|
+
`~/.nika/keys/` or the explicit `NIKA_RUN_KEY_FILE` and `NIKA_RUN_PUB_FILE`
|
|
456
|
+
pair, never with an OS keychain. On macOS, Nika 0.123 and later open no
|
|
457
|
+
keychain even from a terminal; on Linux, `nika` run from a terminal also uses
|
|
458
|
+
the desktop's Secret Service. `NIKA_KEYCHAIN=off nika key init` creates the
|
|
459
|
+
key as files on both, and with the same variable `nika key rotate` retires
|
|
460
|
+
it and writes the next one there (records it signed stay verifiable).
|
|
461
|
+
`nika key trust` prints the public key to enroll elsewhere; on Linux,
|
|
462
|
+
`nika key align` copies a Secret Service key to the files. In CI, give the
|
|
463
|
+
engine the explicit pair. Never copy a private run key into SDK
|
|
464
|
+
configuration, source control, workflow inputs or an HTTP request.
|
|
465
|
+
[docs/receipts.md](https://github.com/nika-open/nika-client/blob/main/docs/receipts.md)
|
|
466
|
+
covers what a receipt carries, every server verdict and key custody.
|
|
467
|
+
|
|
468
|
+
## API reference
|
|
469
|
+
|
|
470
|
+
Everything goes through one class, `Nika`, and the run handle it returns.
|
|
471
|
+
Create the client once: it drives the bundled engine by default, or a
|
|
472
|
+
`nika serve` when you give it a `url`.
|
|
473
|
+
|
|
474
|
+
| `Nika` method | What it does | Resolves with |
|
|
475
|
+
|---|---|---|
|
|
476
|
+
| `run(workflow, options?)` | Checks the workflow, then starts it | a `NikaRun` once the engine admits it; rejects with `NikaOperationError` when the engine refuses |
|
|
477
|
+
| `check(workflow, options?)` | Audits a workflow without running it | the engine's report: `clean` and the findings |
|
|
478
|
+
| `traceVerify(receipt, options?)` | Has the engine verify a run's record | `NikaTraceVerifyResult`: `verified`, `verdict`, `reason` |
|
|
479
|
+
| `compile(request, options?)` | Writes or edits a candidate workflow, without running it; `nextCompileRequest()` builds an answer round | `NikaCompileOutcome` |
|
|
480
|
+
| `attachRun(id, options?)` | Picks a server job back up after a restart | a `NikaRun` |
|
|
481
|
+
| `listWorkflows()` · `workflow(name)` | Lists or describes the workflows a server serves | names · metadata |
|
|
482
|
+
| `accessOffer(workflow, options?)` | Asks a server what the sessions of a served workflow's declared ACP route offer now (models, reasoning efforts, service tiers), without a prompt | `NikaAccessOffer` |
|
|
483
|
+
| `schedule(workflow, options)` · `scheduleStatus(id)` | Creates, changes or reads a schedule on a server | the applied schedule · its status |
|
|
484
|
+
|
|
485
|
+
| `NikaRun` member | What it gives you |
|
|
486
|
+
|---|---|
|
|
487
|
+
| `run.id` | The run's id: the server's durable job id over HTTP, a throwaway id on a local engine |
|
|
488
|
+
| `run.events(options?)` | The run's events as they happen, or replayed from the start |
|
|
489
|
+
| `run.result()` | The final result, settled once; a failed run resolves, it does not throw |
|
|
490
|
+
| `run.status()` | The current status without waiting (server runs only) |
|
|
491
|
+
| `run.cancel()` | Asks the engine to stop the run; every call returns the same request |
|
|
492
|
+
| `run.artifacts(options?)` | What the settled job produced, as its sealed journal lists it (server runs only) |
|
|
493
|
+
| `run.downloadArtifact(artifact, options?)` | One artifact's bytes as a stream that closes once they are proven (server runs only) |
|
|
494
|
+
| `run.readArtifact(artifact, options?)` | One artifact's proven bytes, whole, up to `maxBytes` (16 MiB by default; server runs only) |
|
|
495
|
+
| `run.done` | The same promise as `run.result()`, kept for older code |
|
|
496
|
+
|
|
497
|
+
Every member is bound to its run, so you can pass it around:
|
|
498
|
+
`const { events, result } = run`. `result.status` is the engine's word:
|
|
499
|
+
`succeeded`, `failed`, `paused` (a human gate), `cancelled` or `interrupted`.
|
|
500
|
+
|
|
501
|
+
> [!WARNING]
|
|
502
|
+
> An admitted failure **resolves**: `run.result()` does not throw for a
|
|
503
|
+
> failed workflow. Read `result.status`, or call `isNikaRunSucceeded(result)`,
|
|
504
|
+
> and treat anything but `succeeded` as its own failure, or a red run passes
|
|
505
|
+
> silently.
|
|
506
|
+
|
|
507
|
+
**Pass your app's data with `inputs`.** They fill the workflow's declared
|
|
508
|
+
`inputs:` by name, as strict JSON that stays literal (`'@env:HOME'` is text,
|
|
509
|
+
never read from the environment), and the engine type-checks them before any
|
|
510
|
+
run exists:
|
|
511
|
+
|
|
512
|
+
```ts
|
|
513
|
+
const run = await nika.run('support-triage.nika', { inputs: { ticketId: '42' } });
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
The engine must advertise the channel (`inputsLiteral` locally, `jobInputs`
|
|
517
|
+
on a server, which takes them by served name only); without it `run()`
|
|
518
|
+
rejects with `NikaCompatibilityError`, and the package
|
|
519
|
+
never falls back to `--var`. `vars` is deprecated: it is the local `--var`
|
|
520
|
+
operator channel and has no HTTP form. Keep secrets out of `inputs`.
|
|
521
|
+
[docs/runs.md](https://github.com/nika-open/nika-client/blob/main/docs/runs.md#pass-your-apps-data-inputs)
|
|
522
|
+
lists what the engine and the package refuse.
|
|
523
|
+
|
|
524
|
+
**Pin the access path with `access`.** The workflow's `model:` picks the
|
|
525
|
+
intelligence; `access` picks the path the engine takes to it, as
|
|
526
|
+
`nika run --access` does: an access class (`local`, `mock`, `harness`,
|
|
527
|
+
`oauth`, `api`) or a harness seat (`codex`, `claude-code`…). Both doors take
|
|
528
|
+
it, a server with a workflow named by its served name:
|
|
529
|
+
|
|
530
|
+
```ts
|
|
531
|
+
const run = await nika.run('support-triage.nika', { access: 'codex' });
|
|
532
|
+
const report = await nika.check('support-triage.nika', { access: 'codex' });
|
|
533
|
+
```
|
|
534
|
+
|
|
535
|
+
A pin is a pin: the engine refuses one it does not know (`NIKA-1802`) or that
|
|
536
|
+
the workflow's model cannot use (`NIKA-1801`), never taking another path, and
|
|
537
|
+
`run.result()` settles `failed` with that code. A server refuses an empty pin
|
|
538
|
+
at admission (`NikaOperationError`, `status` 422), and a local file's
|
|
539
|
+
snapshot takes none.
|
|
540
|
+
[docs/runs.md](https://github.com/nika-open/nika-client/blob/main/docs/runs.md#pin-the-access-path-access)
|
|
541
|
+
gives each door's answers.
|
|
542
|
+
|
|
543
|
+
<details>
|
|
544
|
+
<summary><b>Constructor options</b></summary>
|
|
545
|
+
|
|
546
|
+
```ts
|
|
547
|
+
const local = new Nika({ cwd: process.cwd() });
|
|
548
|
+
const remote = new Nika({ url: 'https://nika.example.com', token });
|
|
549
|
+
```
|
|
550
|
+
|
|
551
|
+
| Option | Default | What it does |
|
|
552
|
+
|---|---|---|
|
|
553
|
+
| `cwd` | the current working directory | Where the local engine runs and resolves workflow paths; for a server client, where a local file is captured |
|
|
554
|
+
| `bin` | `NIKA_BIN`, then the bundled engine | An absolute path to the engine to use |
|
|
555
|
+
| `eventBufferSize` | 4096 | How many of a run's most recent events a late view can be given |
|
|
556
|
+
| `machineBufferBytes` | 16 MiB | The size limit for one engine frame (a local line, a server event) or document; the default holds any result a `nika serve` settles, whose job store is capped at 16 MiB, and a refusal past it names the size to set |
|
|
557
|
+
| `url` | none | A `nika serve` base URL; setting it switches to HTTP |
|
|
558
|
+
| `token` | required with `url` | The bearer token from the server's `--token-file` |
|
|
559
|
+
| `allowInsecureHttp` | `false` | Allows plain `http://`, and only to a loopback host |
|
|
560
|
+
| `requestTimeout` | `30000` (30 s) | The time limit for an HTTP admission request, in milliseconds |
|
|
561
|
+
| `fetch` | `globalThis.fetch` | A custom, standards-compatible `fetch` |
|
|
562
|
+
|
|
563
|
+
`token`, `allowInsecureHttp`, `requestTimeout` and `fetch` require `url`;
|
|
564
|
+
passing them to a local client throws `NikaConfigurationError`.
|
|
565
|
+
`nika.transportKind` tells you which transport a client uses:
|
|
566
|
+
`'native-process'` or `'http'`.
|
|
567
|
+
|
|
568
|
+
</details>
|
|
569
|
+
|
|
570
|
+
**Read more,** in the pages that ship with the package:
|
|
571
|
+
|
|
572
|
+
| Topic | Page |
|
|
573
|
+
|---|---|
|
|
574
|
+
| `check()`, results, `inputs`, `run.events()` and its bounds, cancellation, typed frames, the deprecated wrappers | [docs/runs.md](https://github.com/nika-open/nika-client/blob/main/docs/runs.md) |
|
|
575
|
+
| `nika serve`: setup, idempotent runs, `attachRun`, restarts, artifacts, schedules | [docs/server.md](https://github.com/nika-open/nika-client/blob/main/docs/server.md) |
|
|
576
|
+
| Receipts, `traceVerify()` on both doors, signing keys | [docs/receipts.md](https://github.com/nika-open/nika-client/blob/main/docs/receipts.md) |
|
|
577
|
+
| `compile()`: from an intention to a checked candidate, answer rounds, provider rounds | [docs/compile.md](https://github.com/nika-open/nika-client/blob/main/docs/compile.md) |
|
|
578
|
+
| Every error, server refusals, troubleshooting | [docs/errors.md](https://github.com/nika-open/nika-client/blob/main/docs/errors.md) |
|
|
579
|
+
| The words these pages use | [docs/glossary.md](https://github.com/nika-open/nika-client/blob/main/docs/glossary.md) |
|
|
580
|
+
|
|
581
|
+
## Troubleshooting
|
|
582
|
+
|
|
583
|
+
| You see | What to do |
|
|
584
|
+
|---|---|
|
|
585
|
+
| `not verified: receipt_mismatch` after a successful run | Create a key the engine your app starts can read: `NIKA_KEYCHAIN=off ./node_modules/.bin/nika key init`. On a Mac whose keychain holds a key from Nika 0.122 or older, that mints a new key as files; on Linux, `./node_modules/.bin/nika key align` from a terminal copies a key that `nika key init --force` stored in the Secret Service instead. |
|
|
586
|
+
| `NikaEngineUnavailable` from `new Nika()` | No engine payload for this machine: use Node.js 22 or newer on macOS or glibc Linux, keep optional dependencies (no `--omit=optional`); on Windows or musl (Alpine), set an absolute `bin`/`NIKA_BIN` or connect to a `nika serve` by URL. |
|
|
587
|
+
| `NikaCompatibilityError` with `capability: 'engineIdentity'` | The engine or server does not speak machine protocol 2 (0.123 or later). Upgrade it with the package: [docs/upgrading-to-0.123.md](https://github.com/nika-open/nika-client/blob/main/docs/upgrading-to-0.123.md). |
|
|
588
|
+
| `NikaConfigurationError` about `bin` or `NIKA_BIN` | Give an absolute path; a bare name or a relative path is refused. |
|
|
589
|
+
| `nika serve` exits: `token file must be mode 0600` | `chmod 600 .nika/serve.token`; the token must be 32–512 visible ASCII bytes. |
|
|
590
|
+
| `nika serve` exits: `nothing armed — this project has no nika.yaml` | Add a one-line `nika.yaml` in the folder you serve: `nika: my-project`. |
|
|
591
|
+
| `run()` rejects with `NikaOperationError` | The engine refused the workflow before it ran: read `error.code` and `error.findings`, or run `./node_modules/.bin/nika check <file>`. |
|
|
592
|
+
| `NikaProtocolError: … exceeded … bytes (machineBufferBytes)` | A frame or record was larger than the bound: set `machineBufferBytes` to the size the message names, or remove a lowered value (the 16 MiB default holds any server result); `attachRun(jobId)` reads a server job again. |
|
|
593
|
+
|
|
594
|
+
More causes, and every error class, are in
|
|
595
|
+
[docs/errors.md](https://github.com/nika-open/nika-client/blob/main/docs/errors.md).
|
|
596
|
+
|
|
597
|
+
## Install and versions
|
|
598
|
+
|
|
599
|
+
```sh
|
|
600
|
+
npm install @nika-open/nika
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
**Status.** 0.124 is the current release line. Work stays focused on
|
|
604
|
+
maintenance, security and the media capabilities workflows need; native
|
|
605
|
+
video is planned for 0.125. The 0.123.x line is the previous line. Read the
|
|
606
|
+
[known limits](https://docs.nika.sh/changelog/known-limits) of 0.124 before
|
|
607
|
+
you build on it.
|
|
608
|
+
|
|
609
|
+
- **Node.js 22 or newer.** That is the tested floor. On an older Node.js, npm
|
|
610
|
+
warns (`EBADENGINE`) and skips the engine payload, so `new Nika()` throws
|
|
611
|
+
`NikaEngineUnavailable`.
|
|
612
|
+
- **macOS or Linux for the bundled engine.** npm installs the one platform
|
|
613
|
+
package that matches your machine (`@nika-open/nika-<os>-<arch>`: macOS
|
|
614
|
+
on Apple silicon or Intel, Linux on x64 or arm64 with glibc). On any other
|
|
615
|
+
platform, `new Nika()` throws `NikaEngineUnavailable`: point `bin` or
|
|
616
|
+
`NIKA_BIN` at a compatible engine, or connect to a `nika serve` by URL.
|
|
617
|
+
- **Which engine runs.** The client takes the engine from `bin`, then
|
|
618
|
+
`NIKA_BIN`, then that platform package. `bin` and `NIKA_BIN` must be
|
|
619
|
+
absolute paths: a bare name or a relative path would make the operating
|
|
620
|
+
system search `PATH` or the working directory, so it is refused. A `nika`
|
|
621
|
+
found on your `PATH` is deliberately never used.
|
|
622
|
+
- **The `nika` command.** `./node_modules/.bin/nika` is the full engine CLI
|
|
623
|
+
that came with the package: `check`, `compile`, `catalog`, `doctor`, `key`,
|
|
624
|
+
`serve`, `arm`, and `mcp`, the read-only MCP server for your coding agent.
|
|
625
|
+
|
|
626
|
+
**Pin the version you tested, then check what you installed:**
|
|
627
|
+
|
|
628
|
+
```sh
|
|
629
|
+
node -p "require('@nika-open/nika/package.json').version"
|
|
630
|
+
./node_modules/.bin/nika --version
|
|
631
|
+
```
|
|
632
|
+
|
|
633
|
+
The `package.json` subpath is exported for CommonJS, ESM build tools and CI
|
|
634
|
+
pin checks. It reports the installed package, not a moving registry tag.
|
|
635
|
+
|
|
636
|
+
**Package and engine move together.** Each package version bundles the engine
|
|
637
|
+
with the same number, the one it was tested with: 0.124.5 bundles
|
|
638
|
+
`nika 0.124.5 (8b640a9b7)` and speaks its machine protocol, 2, as 0.123 did.
|
|
639
|
+
It refuses an engine or server on another generation (0.122 and older speak 1)
|
|
640
|
+
at its identity probe (`nika --sdk-identity`, `GET /health`), before any job,
|
|
641
|
+
with `NikaCompatibilityError`: upgrade the package and every `nika serve`
|
|
642
|
+
together ([docs/upgrading-to-0.123.md](https://github.com/nika-open/nika-client/blob/main/docs/upgrading-to-0.123.md)).
|
|
643
|
+
The older 0.120.3 package pairs only with engines 0.120.x. The standalone CLI
|
|
644
|
+
(GitHub releases, `brew install nika-open/tap/nika`,
|
|
645
|
+
`curl -LsSf https://nika.sh/install.sh | sh`, the
|
|
646
|
+
`ghcr.io/nika-open/nika` image, where 0.124.4 and earlier stay at
|
|
647
|
+
`ghcr.io/supernovae-st/nika`) is released separately; this package
|
|
648
|
+
never uses it.
|
|
649
|
+
|
|
650
|
+
**Stay current:**
|
|
651
|
+
|
|
652
|
+
```sh
|
|
653
|
+
npm update @nika-open/nika # the package and its engine, together
|
|
654
|
+
./node_modules/.bin/nika doctor # diagnoses this machine and prints fixes; changes nothing
|
|
655
|
+
```
|
|
656
|
+
|
|
657
|
+
**The old package names.** The repositories moved to the `nika-open`
|
|
658
|
+
organization on 2026-11-20, and the package with them: it is
|
|
659
|
+
`@nika-open/nika`. Up to 0.124.4 it was published as `@supernovae-st/nika`,
|
|
660
|
+
and up to 0.115.0 as `@supernovae-st/nika-client`; neither name gets further
|
|
661
|
+
releases. Replace the old dependency, then its imports:
|
|
662
|
+
|
|
663
|
+
```sh
|
|
664
|
+
npm uninstall @supernovae-st/nika && npm install @nika-open/nika
|
|
665
|
+
```
|
|
666
|
+
|
|
667
|
+
`@supernovae-st/nika-client` is not marked deprecated on npm, so installing
|
|
668
|
+
it still succeeds without a warning and gives you the retired 0.115.0 API
|
|
669
|
+
(the `LocalNika`/HTTP split), not the `Nika` client documented here. The
|
|
670
|
+
repository is `nika-open/nika-client`; GitHub redirects the old
|
|
671
|
+
`supernovae-st/nika-client` path.
|
|
672
|
+
|
|
673
|
+
## Security
|
|
674
|
+
|
|
675
|
+
- **The server's token stays private.** `nika serve` reads its bearer token
|
|
676
|
+
from a file (`--token-file`), never from its command line, and refuses a
|
|
677
|
+
file that is not mode `0600`. The token must be 32–512 visible ASCII bytes.
|
|
678
|
+
- **No plaintext off your machine.** The client refuses plain HTTP to any
|
|
679
|
+
host but loopback, and even there only with `allowInsecureHttp: true`.
|
|
680
|
+
- **Permits stay the engine's.** A workflow's `permits` are default-deny
|
|
681
|
+
engine policy; nothing in this package grants more.
|
|
682
|
+
- **Everything is bounded.** Engine frames, diagnostics, SSE lines and
|
|
683
|
+
observer queues all have limits.
|
|
684
|
+
- **Proof comes from the engine.** Receipts and traces are engine-issued; the
|
|
685
|
+
package never makes one up.
|
|
686
|
+
- **No webhook verifier here.** This package
|
|
687
|
+
does not export a webhook-signature verifier. Verify a webhook's raw body
|
|
688
|
+
with the sender's official library before you pass anything to a workflow.
|
|
689
|
+
- **Secrets stay out.** Keep secrets out of `inputs`, and private run keys out
|
|
690
|
+
of configuration, source control, workflow inputs and HTTP requests.
|
|
691
|
+
|
|
692
|
+
To report a vulnerability privately, follow
|
|
693
|
+
[SECURITY.md](https://github.com/nika-open/nika-client/blob/main/SECURITY.md).
|
|
694
|
+
|
|
695
|
+
## Documentation
|
|
696
|
+
|
|
697
|
+
- **In this package** (`docs/`, also on GitHub):
|
|
698
|
+
[runs](https://github.com/nika-open/nika-client/blob/main/docs/runs.md),
|
|
699
|
+
[server](https://github.com/nika-open/nika-client/blob/main/docs/server.md),
|
|
700
|
+
[receipts](https://github.com/nika-open/nika-client/blob/main/docs/receipts.md),
|
|
701
|
+
[compile](https://github.com/nika-open/nika-client/blob/main/docs/compile.md),
|
|
702
|
+
[errors](https://github.com/nika-open/nika-client/blob/main/docs/errors.md),
|
|
703
|
+
[upgrading to 0.123](https://github.com/nika-open/nika-client/blob/main/docs/upgrading-to-0.123.md),
|
|
704
|
+
[glossary](https://github.com/nika-open/nika-client/blob/main/docs/glossary.md)
|
|
705
|
+
and the [HTTP contract](https://github.com/nika-open/nika-client/blob/main/docs/http-api.md).
|
|
706
|
+
For contributors: [architecture](https://github.com/nika-open/nika-client/blob/main/docs/architecture.md)
|
|
707
|
+
and [testing and release evidence](https://github.com/nika-open/nika-client/blob/main/docs/testing.md).
|
|
708
|
+
History: [migrating to 0.116](https://github.com/nika-open/nika-client/blob/main/docs/migrating-to-0.116.md)
|
|
709
|
+
and the [changelog](https://github.com/nika-open/nika-client/blob/main/CHANGELOG.md).
|
|
710
|
+
- **The SDK guide** on docs.nika.sh: [overview](https://docs.nika.sh/sdk/overview),
|
|
711
|
+
[quickstart](https://docs.nika.sh/sdk/start/quickstart),
|
|
712
|
+
[methods](https://docs.nika.sh/sdk/reference/methods),
|
|
713
|
+
[receipts](https://docs.nika.sh/sdk/runtime/receipts) and the
|
|
714
|
+
[remote client](https://docs.nika.sh/sdk/remote/client).
|
|
715
|
+
- **Upstream:** [the engine](https://github.com/nika-open/nika) and
|
|
716
|
+
[the language specification](https://github.com/nika-open/nika-spec).
|
|
717
|
+
|
|
718
|
+
## Contributing
|
|
719
|
+
|
|
720
|
+
Issues and pull requests are welcome. Before you open one, run what CI runs:
|
|
721
|
+
|
|
722
|
+
```sh
|
|
723
|
+
npm ci
|
|
724
|
+
npm run typecheck # the sources and the .ts tests, under the strict tsconfig
|
|
725
|
+
npm test # unit and contract tests, then the retired-suffix ratchet
|
|
726
|
+
npm run build
|
|
727
|
+
npm run check:package-surface # the packed ESM and CommonJS faces, and the examples
|
|
728
|
+
npm run check:release-evidence # the committed gauntlet ledgers match this version
|
|
729
|
+
```
|
|
730
|
+
|
|
731
|
+
The gauntlets exercise the packed package against a real engine, given as an
|
|
732
|
+
absolute `NIKA_BIN`:
|
|
733
|
+
|
|
734
|
+
```sh
|
|
735
|
+
NIKA_BIN=/absolute/path/to/nika npx vitest run test/engine-live.test.ts # both doors, keyless and offline
|
|
736
|
+
NIKA_BIN=/absolute/path/to/nika npm run gauntlet:projects # five clean installs from the npm tarball
|
|
737
|
+
NIKA_BIN=/absolute/path/to/nika npm run gauntlet:hostile # concurrency, cancellation, corrupt streams and traces, redaction, soak
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
`gauntlet/` also holds 100 distinct use-case workflows and the provider
|
|
741
|
+
evidence, and
|
|
742
|
+
[docs/testing.md](https://github.com/nika-open/nika-client/blob/main/docs/testing.md)
|
|
743
|
+
explains every test layer. The HTTP types mirror the pinned
|
|
744
|
+
[`openapi.json`](https://github.com/nika-open/nika-client/blob/main/openapi.json)
|
|
745
|
+
of `nika serve`: never add a field the engine does not send.
|
|
746
|
+
|
|
747
|
+
The recordings on this page are rendered, never edited:
|
|
748
|
+
`node scripts/media/render.mjs` records them from the published package and
|
|
749
|
+
`node scripts/media/validate.mjs --typecheck` checks them; `npm test` holds
|
|
750
|
+
every embed to the committed files. [media/README.md](media/README.md) has
|
|
751
|
+
the tools and the rules.
|
|
752
|
+
|
|
753
|
+
<!-- city:map -->
|
|
754
|
+
## 🦋 The Nika family
|
|
755
|
+
|
|
756
|
+
| | Repository | What it gives you |
|
|
757
|
+
|---|---|---|
|
|
758
|
+
| 🦋 | [nika](https://github.com/nika-open/nika) | The engine and CLI: write, check, run and verify AI workflows |
|
|
759
|
+
| 📖 | [nika-docs](https://github.com/nika-open/nika-docs) | The documentation, live at [docs.nika.sh](https://docs.nika.sh) |
|
|
760
|
+
| 📜 | [nika-spec](https://github.com/nika-open/nika-spec) | The language specification and the suite that proves an engine follows it |
|
|
761
|
+
| 🧩 | [nika-vscode](https://github.com/nika-open/nika-vscode) | The editor extension, frozen at 0.120 and not qualified with 0.124: use `nika lsp` and the JSON Schema |
|
|
762
|
+
| 🟦 | **[nika-client](https://github.com/nika-open/nika-client)** | **Run and verify workflows from TypeScript** |
|
|
763
|
+
| ✅ | [nika-action](https://github.com/nika-open/nika-action) | A GitHub Action that posts a `nika check` verdict on your pull requests |
|
|
764
|
+
| 🚀 | [nika-actions-starter](https://github.com/nika-open/nika-actions-starter) | A ready template: workflows, editor setup and CI from the first push |
|
|
765
|
+
| 📦 | [nika-registry](https://github.com/nika-open/nika-registry) | Shareable workflows, pinned and re-verified |
|
|
766
|
+
| 🤖 | [nika-plugins](https://github.com/nika-open/nika-plugins) | Teaches your coding agent (Claude Code, Codex, Cursor…) to write Nika |
|
|
767
|
+
| 🍺 | [homebrew-tap](https://github.com/nika-open/homebrew-tap) | `brew install nika-open/tap/nika` |
|
|
768
|
+
| 🐙 | [gh-nika](https://github.com/nika-open/gh-nika) | The Nika CLI as a GitHub CLI extension |
|
|
769
|
+
| 🏛️ | [nika-estate](https://github.com/nika-open/nika-estate) | Where each file in Nika's core repositories comes from, declared and re-checkable |
|
|
770
|
+
<!-- /city:map -->
|
|
771
|
+
|
|
772
|
+
## License
|
|
773
|
+
|
|
774
|
+
[Apache-2.0](https://github.com/nika-open/nika-client/blob/main/LICENSE).
|
|
775
|
+
The engine this package runs is licensed separately, under
|
|
776
|
+
AGPL-3.0-or-later; importing this package does not impose the engine's
|
|
777
|
+
copyleft license on your application.
|