@nika-open/nika 0.0.0-stage → 0.124.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/README.md +776 -2
- package/dist/bin/nika.js +450 -0
- package/dist/index.cjs +5921 -0
- package/dist/index.d.cts +1913 -0
- package/dist/index.d.ts +1913 -0
- package/dist/index.js +5865 -0
- package/docs/README.md +69 -0
- package/docs/architecture.md +163 -0
- package/docs/compile.md +486 -0
- package/docs/errors.md +154 -0
- package/docs/glossary.md +41 -0
- package/docs/http-api.md +396 -0
- package/docs/migrating-to-0.116.md +164 -0
- package/docs/receipts.md +156 -0
- package/docs/runs.md +670 -0
- package/docs/server.md +543 -0
- package/docs/testing.md +244 -0
- package/docs/upgrading-to-0.123.md +190 -0
- package/openapi.json +3067 -0
- package/package.json +92 -4
package/docs/testing.md
ADDED
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
# Testing and release evidence
|
|
2
|
+
|
|
3
|
+
The release judge is the packed package consumed from an isolated Node
|
|
4
|
+
project, not a source import. Local development still starts with the fast
|
|
5
|
+
gates:
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
npm ci
|
|
9
|
+
npm run typecheck
|
|
10
|
+
npm test
|
|
11
|
+
npm run build
|
|
12
|
+
npm run check:coverage
|
|
13
|
+
npm run check:release-evidence
|
|
14
|
+
NIKA_BIN=/path/to/nika npx vitest run test/engine-live.test.ts
|
|
15
|
+
NIKA_BIN=/path/to/nika npm run gauntlet:check
|
|
16
|
+
NIKA_BIN=/path/to/nika npm run gauntlet:run
|
|
17
|
+
NIKA_BIN=/path/to/nika npm run gauntlet:projects
|
|
18
|
+
NIKA_BIN=/path/to/nika npm run gauntlet:depth
|
|
19
|
+
NIKA_BIN=/path/to/nika npm run gauntlet:hostile
|
|
20
|
+
NIKA_BIN=/path/to/nika npm run gauntlet:recovery
|
|
21
|
+
NIKA_BIN=/path/to/nika npm run gauntlet:one-door
|
|
22
|
+
npm audit
|
|
23
|
+
npm pack --dry-run
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
All engine-backed gauntlets use `NIKA_BIN` as the canonical explicit binary.
|
|
27
|
+
`NIKA_GAUNTLET_BIN` remains a compatibility fallback for the corpus-only
|
|
28
|
+
scripts. Evidence is invalid when the recorded engine identity does not match
|
|
29
|
+
the intended release candidate. `npm run check:release-evidence` binds every
|
|
30
|
+
current committed gauntlet result and packed tarball identity to the root
|
|
31
|
+
package version. Historical ledgers are limited to an explicit allowlist and
|
|
32
|
+
must remain labelled as non-gating evidence.
|
|
33
|
+
|
|
34
|
+
CI adds a behavioral provenance replay. It downloads the Linux x64 asset for
|
|
35
|
+
the exact root package version from `nika-open/nika`, verifies its GitHub
|
|
36
|
+
attestation (signed by `nika-open/nika` from v0.124.5; releases up to v0.124.4
|
|
37
|
+
verify against `supernovae-st/nika`, the identity that signed them before the
|
|
38
|
+
repository moved) and published `SHA256SUMS` entry, then reruns all 100 deterministic workflows, the hostile suite, all five mini-SaaS projects, all six depth projects,
|
|
39
|
+
the two-process recovery scenario, and five scenarios through six execution
|
|
40
|
+
doors from a freshly packed SDK. The runner
|
|
41
|
+
mints an ephemeral run-signing key. Its
|
|
42
|
+
cancellation fixtures retain the in-process `nika:wait` cases and add an
|
|
43
|
+
owned loopback rendezvous for controlled task-boundary cancellation. They
|
|
44
|
+
need no shell command, platform sandbox, or sandbox waiver. Cancellation
|
|
45
|
+
and sealed-trace claims are exercised against the public binary. The
|
|
46
|
+
cancellation fixtures cancel an execution that is observably inside its 10 s
|
|
47
|
+
`nika:wait` (the durable status reads `running`, no longer `queued`, and a
|
|
48
|
+
further delay has passed) and record both the cancel reply and the terminal it
|
|
49
|
+
leads to. Since engine 0.118, and in the 0.123.0 replay, the resident answers
|
|
50
|
+
202 `cancellation_requested`;
|
|
51
|
+
its execution owner then records `execution.interrupted` with
|
|
52
|
+
`status=interrupted` once the grace expires inside a task, or, when the request
|
|
53
|
+
lands at a task boundary, `execution.cancelled` (the `cancel_job` writer) or
|
|
54
|
+
`execution.settled` (the racing settlement writer) with `status=cancelled` and a
|
|
55
|
+
settlement whose cause is `operator`. A cancel that lands before the execution
|
|
56
|
+
starts is a 200 `cancelled` whose terminal is one of those two writer kinds,
|
|
57
|
+
only with `status=cancelled`. The verifiers bind each cancel reply to the
|
|
58
|
+
terminals it may lead to, demand the run status of that terminal, and refuse any
|
|
59
|
+
other pairing. The parsed deterministic and packed-project results must match
|
|
60
|
+
exactly except for the recovery job UUID and the depth `package_sha256`.
|
|
61
|
+
That digest is provenance of the tarball this replay packed (README lives
|
|
62
|
+
inside the npm pack): the verifier requires `depth-package.json` beside the
|
|
63
|
+
ledger, hashes the artifact, checks filename/size/sha512 integrity, refuses
|
|
64
|
+
a missing or substituted pack, then compares behavior without requiring the
|
|
65
|
+
committed baseline digest (that digest is a labelled historical ledger
|
|
66
|
+
identity, not a re-hash of this run). A documentation-only
|
|
67
|
+
README change retargets the digest and must still reproduce every behavioral
|
|
68
|
+
verdict. The hostile comparison excludes
|
|
69
|
+
`generated_at` and per-scenario duration and canonicalizes only the two ratified
|
|
70
|
+
writer kinds of a cancelled terminal after checking the exact pairing. This proves that the
|
|
71
|
+
attested public release currently reproduces the committed behavioral claims.
|
|
72
|
+
It does not claim cryptographic proof of when the committed JSON file itself
|
|
73
|
+
was originally written.
|
|
74
|
+
|
|
75
|
+
## Test layers
|
|
76
|
+
|
|
77
|
+
1. Unit tests cover configuration, local process framing, HTTP protocol
|
|
78
|
+
validation, SSE recovery, independent observer backpressure, scheduling,
|
|
79
|
+
receipts, and typed errors.
|
|
80
|
+
2. The generated corpus holds 100 distinct use cases and 100 valid workflows.
|
|
81
|
+
3. The deterministic runner executes every workflow with `mock/echo` and
|
|
82
|
+
seals trace evidence without paid-provider dependence.
|
|
83
|
+
4. Project gauntlets install the tarball into fresh applications and exercise
|
|
84
|
+
realistic multi-step use cases.
|
|
85
|
+
5. Hostile tests mutate transport frames, timing, status codes, identities,
|
|
86
|
+
revisions, and replay order.
|
|
87
|
+
6. Public Personas use only the README, exported types, packed package, public
|
|
88
|
+
binary/help, loopback HTTP, and public documentation. They are synthetic
|
|
89
|
+
users, never substitutes for human usability evidence.
|
|
90
|
+
7. `test/engine-live.test.ts` drives the engine `NIKA_BIN` names through the
|
|
91
|
+
public API on both doors (check, run with its events and result, a refused
|
|
92
|
+
run, cancellation, trace verification, a snapshot run, schedules, compile
|
|
93
|
+
choices, and a server job's artifacts, listed, streamed and refused once
|
|
94
|
+
changed), keyless and offline; it is skipped without `NIKA_BIN`, and
|
|
95
|
+
candidate CI runs it against `ENGINE_QUAL_PIN`.
|
|
96
|
+
`test/engine-0123-wire.test.ts` decodes bytes recorded from a real 0.123
|
|
97
|
+
engine and the released 0.122.0 identity, hermetically, in `npm test`.
|
|
98
|
+
|
|
99
|
+
The last public-only first-contact wave (2026-09-01, on the 0.115 client and
|
|
100
|
+
engine 0.116.2) and its convergent debt are recorded in
|
|
101
|
+
[`gauntlet/personas/REPORT.md`](https://github.com/nika-open/nika-client/blob/main/gauntlet/personas/REPORT.md); it predates
|
|
102
|
+
the current API, and no persona wave has run on 0.123.0.
|
|
103
|
+
|
|
104
|
+
## Socratic risk matrix
|
|
105
|
+
|
|
106
|
+
Every release wave must ask and demonstrate an answer to these questions:
|
|
107
|
+
|
|
108
|
+
- Can a first-time Node user succeed from the README without repository
|
|
109
|
+
knowledge?
|
|
110
|
+
- Do ESM and CommonJS load from the packed tarball on every supported Node
|
|
111
|
+
major?
|
|
112
|
+
- Does a workflow the engine refuses reject native `run()` with the engine's
|
|
113
|
+
code and findings, on every refusal dialect a supported engine writes, with
|
|
114
|
+
no run handle, no second spawn and no preflight check? Does output that
|
|
115
|
+
proves neither admission nor refusal stay a protocol fault? The answer is
|
|
116
|
+
`test/native-run-admission.test.ts`. Its `wire-*` cases replay stdout and
|
|
117
|
+
stderr captured byte-for-byte from real engines
|
|
118
|
+
(`test/fixtures/run-wire/README.md` records which, and how); its
|
|
119
|
+
`SYNTHETIC` cases are invented hostile shapes. A replay proves the SDK
|
|
120
|
+
decodes those bytes, never that an engine still writes them: a new engine
|
|
121
|
+
release needs a new capture.
|
|
122
|
+
- What happens if the server dies after admission but before the first SSE
|
|
123
|
+
frame?
|
|
124
|
+
- What happens if SSE reconnects after a duplicate, gap, conflicting replay,
|
|
125
|
+
or terminal race?
|
|
126
|
+
- Can one slow observer overflow without damaging another observer or
|
|
127
|
+
`run.result()`?
|
|
128
|
+
- Does one application read the same lifecycle words over the native process
|
|
129
|
+
and over HTTP, with `event.raw` still the protocol frame, and without a
|
|
130
|
+
per-task event the resident never streamed?
|
|
131
|
+
- Does a frame whose state word is absent, null, future, or still running
|
|
132
|
+
stay an `engine.event` instead of being named settled?
|
|
133
|
+
- Is a human gate (`paused`) kept apart from both failure and completion, and
|
|
134
|
+
the engine's `interrupted` evidence apart from a broken observation?
|
|
135
|
+
- Can two clients race the same idempotency key with equal and unequal
|
|
136
|
+
snapshots?
|
|
137
|
+
- Does cancellation win or replay honestly when settlement races it?
|
|
138
|
+
- Does a stale schedule writer receive the current revision without mutating
|
|
139
|
+
durable state?
|
|
140
|
+
- Do process and server restarts preserve the facts the API claims are
|
|
141
|
+
durable?
|
|
142
|
+
- Can a replacement client reattach with its last committed SSE cursor without
|
|
143
|
+
replaying an application side effect?
|
|
144
|
+
- Are auth failures, token rotation, malformed content types, compressed
|
|
145
|
+
bodies, oversized frames, invalid UTF-8, and timeouts typed and redacted?
|
|
146
|
+
- Are receipt job, execution, and trace identities consistent across SSE,
|
|
147
|
+
durable state, and verification?
|
|
148
|
+
- Is the run-signing private key still confined to engine custody, with only
|
|
149
|
+
public trust material entering application infrastructure?
|
|
150
|
+
- Does every live OpenAPI route have a deliberate SDK treatment?
|
|
151
|
+
- Does every documented example compile and run from the tarball?
|
|
152
|
+
- Does the version agree across package metadata, lockfile, optional native
|
|
153
|
+
packages, OpenAPI identity, engine release, npm, and GitHub?
|
|
154
|
+
- Can a claimed capability be deleted without a gate becoming red? If yes,
|
|
155
|
+
the capability is not yet wired.
|
|
156
|
+
|
|
157
|
+
## Release evidence
|
|
158
|
+
|
|
159
|
+
Record exact commands, versions, commit SHAs, platform, run counts, cost, and
|
|
160
|
+
the path to machine-readable results. A green unit suite alone is never release
|
|
161
|
+
evidence. A failed or skipped lane stays named; it is not rounded into a pass.
|
|
162
|
+
|
|
163
|
+
The release ceremony is deliberately two-step. `release.yml` validates the
|
|
164
|
+
tagged engine assets, starts the released Linux binary, proves the live
|
|
165
|
+
OpenAPI/types pin, embeds the exact prepared commit and release version in all
|
|
166
|
+
five package manifests before packing, and publishes four payloads plus the SDK
|
|
167
|
+
through npm trusted publishing with GitHub OIDC and Sigstore provenance bound
|
|
168
|
+
to the workflow identity. Every package registers organization `nika-open`,
|
|
169
|
+
repository `nika-client`, workflow filename `release.yml`, and environment
|
|
170
|
+
`npm-publish`, with direct `npm publish` enabled. The GitHub-hosted publish job
|
|
171
|
+
uses Node 24, npm 11.19.1 and `id-token: write`; it receives no npm write token.
|
|
172
|
+
`release-heal.yml` dispatches that same file on `main`; it does not publish or
|
|
173
|
+
exchange an OIDC token itself. All five package manifests identify the SDK
|
|
174
|
+
repository; native `SOURCE.json` still identifies the separate engine source.
|
|
175
|
+
See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
|
|
176
|
+
An occupied version is accepted only after its exact
|
|
177
|
+
prepared tarball integrity and fetched registry bytes match; errors other than
|
|
178
|
+
an explicit registry 404 refuse publication. `release-finalize.yml` refuses to create the SDK tag and GitHub
|
|
179
|
+
Release until all five exact versions are publicly observable on npm and every
|
|
180
|
+
published manifest carries the same prepared commit and version.
|
|
181
|
+
|
|
182
|
+
## One-door parity and process supervision
|
|
183
|
+
|
|
184
|
+
`gauntlet:one-door` compares CLI, raw HTTP by name and snapshot, and packed SDK
|
|
185
|
+
native, by-name and snapshot execution. It checks success, failure, recovery,
|
|
186
|
+
paused observation and controlled cancellation. `NIKA_ONE_DOOR_REPORT` names
|
|
187
|
+
its output file; CI retains it alongside the replay results. Development mode
|
|
188
|
+
uses an offline installation of the freshly packed SDK with the explicit
|
|
189
|
+
`NIKA_BIN`. Public npm parity requires `NIKA_PUBLIC_SDK_VERSION` and an outer
|
|
190
|
+
artifact-provenance gate; runtime agreement alone is not an attestation.
|
|
191
|
+
|
|
192
|
+
All harnesses own their child processes, impose finite deadlines and await
|
|
193
|
+
cleanup before emitting green evidence. The corpus runs in a fresh project and
|
|
194
|
+
HOME. Changed fixtures require new measured results: old committed ledgers
|
|
195
|
+
remain historical observations until a successful exact-version replay replaces
|
|
196
|
+
them. Never relabel an old binary or weaken the replay comparison.
|
|
197
|
+
|
|
198
|
+
## Compile foundation parity
|
|
199
|
+
|
|
200
|
+
Hermetic compile cases run with `npm test`, including strict request literals,
|
|
201
|
+
capability/version refusal, native exit and signal laws, temporary-file failure
|
|
202
|
+
cleanup, authenticated HTTP responses and cancellation. `npm run check:package-surface`
|
|
203
|
+
checks both packed module faces and their public TypeScript contracts, runs
|
|
204
|
+
`examples/compile-then-run.ts` from the tarball against a fixture engine, and
|
|
205
|
+
typechecks every program under `examples/` against the packed types.
|
|
206
|
+
`test/readme-surface.test.ts` holds the README's quick start byte for byte to
|
|
207
|
+
`examples/quick-start.ts`. It also holds every media path the README and
|
|
208
|
+
`docs/` use to a file committed under `media/` and recorded byte for byte in
|
|
209
|
+
`media/media-sources.json`, requires every committed media file to be used,
|
|
210
|
+
and requires alt text on every image and a reduced-motion still for every GIF.
|
|
211
|
+
`node scripts/media/validate.mjs --typecheck` checks the recordings themselves
|
|
212
|
+
against their tapes, budgets and transcripts; it needs the render tools listed
|
|
213
|
+
in [media/README.md](https://github.com/nika-open/nika-client/blob/main/media/README.md).
|
|
214
|
+
|
|
215
|
+
For a frozen engine that advertises `compile` on both native and Serve doors:
|
|
216
|
+
|
|
217
|
+
```sh
|
|
218
|
+
NIKA_BIN=/absolute/path/to/frozen/nika \
|
|
219
|
+
NIKA_COMPILE_PARITY_REPORT=/absolute/path/to/compile-parity.json \
|
|
220
|
+
node scripts/run-compile-parity-e2e.mjs
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
This installs the SDK tarball into an isolated consumer and compares the full
|
|
224
|
+
common authoring outcomes across native/HTTP and ESM/CommonJS. It checks literal
|
|
225
|
+
round trips, incomplete questions, refused expression islands, invalid bases,
|
|
226
|
+
authentication, no project-file changes and no created jobs. HTTP is given a
|
|
227
|
+
nonexistent local engine path, proving that it cannot use a fallback. The report
|
|
228
|
+
records binary and package hashes and is green only after owned-process cleanup.
|
|
229
|
+
The script needs a 0.123 or later engine (machine protocol 2), which advertises
|
|
230
|
+
`compile` on both doors; this package refuses older engines at identity. The
|
|
231
|
+
route itself first shipped with engine commit
|
|
232
|
+
`4334e58bddf539a6253f448eb05d562b6919f2b7`, in release 0.120.3. This is a
|
|
233
|
+
foundation test, not general intent authoring or execution admission
|
|
234
|
+
qualification.
|
|
235
|
+
|
|
236
|
+
The [2026-09-19 source-build receipt](https://github.com/nika-open/nika-client/blob/main/evidence/compile-4334e58b-20260919.json)
|
|
237
|
+
records 14 cases across both doors and both module systems at that producer,
|
|
238
|
+
with exact outcome parity and no resident-state or project-file mutation. Its
|
|
239
|
+
engine is a clean source build predating the published v0.120.3 binary; its SDK
|
|
240
|
+
tarball is the unreleased PR candidate. The hashes identify those tested bytes.
|
|
241
|
+
|
|
242
|
+
Compile source-build receipts live outside the published package, so recording
|
|
243
|
+
a tarball hash does not change the bytes it identifies. They do not participate
|
|
244
|
+
in the released-engine behavioral ledgers.
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
# Upgrading to 0.123
|
|
2
|
+
|
|
3
|
+
`@nika-open/nika` 0.124.5 bundles engine 0.124.5
|
|
4
|
+
(`nika 0.124.5 (8b640a9b7)`) and speaks its machine protocol, **2**, as 0.123
|
|
5
|
+
did. Engines and servers up to 0.122 speak protocol 1. Each package version
|
|
6
|
+
pairs with one protocol generation, so the move from 0.120.x is one rule:
|
|
7
|
+
|
|
8
|
+
> **Upgrade the package and every `nika serve` it talks to together.**
|
|
9
|
+
|
|
10
|
+
| Your package | Your engine or server | Result |
|
|
11
|
+
|---|---|---|
|
|
12
|
+
| 0.124.x | 0.124.x | works: the pair this package is tested with |
|
|
13
|
+
| 0.123.x or 0.124.x | 0.123.x or 0.124.x | passes the identity probe (one protocol, 2); each call still checks the capability it needs (`artifacts` needs engine 0.123.2 or later) |
|
|
14
|
+
| 0.123.x or 0.124.x | 0.122 and older (protocol 1) | refused at the identity probe, before any job: `NikaCompatibilityError`, `capability: 'engineIdentity'`, naming the engine version |
|
|
15
|
+
| 0.120.3 | 0.120.x | works; that pair stays as it was |
|
|
16
|
+
| 0.120.3 | 0.123.x or later | refused at identity by the 0.120.3 package |
|
|
17
|
+
|
|
18
|
+
Engines 0.121 and 0.122 have no matching package: they already sent compile
|
|
19
|
+
questions of type `choice` while announcing protocol 1, which the 0.120.3
|
|
20
|
+
package refuses as a protocol error.
|
|
21
|
+
|
|
22
|
+
## From 0.123 to 0.124: the same protocol
|
|
23
|
+
|
|
24
|
+
0.124 keeps machine protocol 2 and changes no `nika serve` route, schema or
|
|
25
|
+
field this package reads closed, so moving from 0.123.x needs no new rule:
|
|
26
|
+
upgrade the package and every `nika serve` together, with the steps below.
|
|
27
|
+
The package itself changes one word a local `run.events()` consumer may
|
|
28
|
+
match: a skipped or cancelled task now arrives as `task.skipped` or
|
|
29
|
+
`task.cancelled`, no longer as an `engine.event` (see
|
|
30
|
+
[runs.md](runs.md#watch-a-run-runevents)). The rest is in the data your app
|
|
31
|
+
reads (the
|
|
32
|
+
[changelog](https://github.com/nika-open/nika-client/blob/main/CHANGELOG.md)
|
|
33
|
+
lists it):
|
|
34
|
+
|
|
35
|
+
- **More workflows are refused before they run.** A child workflow is judged
|
|
36
|
+
through the task that calls it, and untrusted content is followed through
|
|
37
|
+
a file a builtin reads (`NIKA-SEC-009`, `NIKA-SEC-014`). A gate inside the
|
|
38
|
+
child does not clear its caller: give the parent a blocking `nika:prompt`
|
|
39
|
+
of its own before the call, and bind a confirm gate's answer on a call
|
|
40
|
+
whose child acts (`with: { go: "${{ tasks.ask.output }}" }` and
|
|
41
|
+
`when: ${{ with.go == true }}`). On an `infer:` seated over ACP
|
|
42
|
+
(`run.access.protocol: acp`), `temperature`, `max_tokens`, an enabled
|
|
43
|
+
`thinking` budget or a `vision:` URL blocks `run_ready`. A seat route
|
|
44
|
+
without ACP does not send `temperature`, `max_tokens` or `thinking`, and
|
|
45
|
+
check does not flag them; from 0.124.1 the run refuses any `vision:`
|
|
46
|
+
there (`NIKA-432`) and check blocks `run_ready` on it, since that command
|
|
47
|
+
never carried an image.
|
|
48
|
+
`temperature` on `openai/gpt-5`, `gpt-5-mini`, `gpt-5-nano` and the
|
|
49
|
+
o-series is refused. Run `./node_modules/.bin/nika check` on your
|
|
50
|
+
workflows before you switch.
|
|
51
|
+
- **A local check names what a rehearsal still reaches** (0.124.1):
|
|
52
|
+
`verdicts.network_tasks` lists the tasks whose own fetch, MCP tool or paid
|
|
53
|
+
media call can reach the network, which `mock/echo` does not stub, and a
|
|
54
|
+
finding's `span` in a file saved with a byte-order mark counts the mark.
|
|
55
|
+
- **A file can ask its route for a service tier** (0.124.2):
|
|
56
|
+
`run.access.service_tier` takes `standard` or `fast` on the codex seat over
|
|
57
|
+
ACP. A local run's terminal frame carries the selection receipt, which
|
|
58
|
+
`readNikaAccessSelection(event)` reads: what the file asked, what was sent
|
|
59
|
+
and what the session read back. An engine that reads the key lists
|
|
60
|
+
`accessServiceTier` in `supportedCapabilities`; an older engine refuses
|
|
61
|
+
the file when it parses it
|
|
62
|
+
([the file's own access contract](runs.md#the-files-own-access-contract-runaccess)).
|
|
63
|
+
- **A server can be asked what a file's route offers** (0.124.3):
|
|
64
|
+
`accessOffer(workflow)` reads, without a prompt, the models, the exact
|
|
65
|
+
reasoning efforts and the service tiers that the sessions of the file's
|
|
66
|
+
own `run.access` route list now, each row with the time it was read. It
|
|
67
|
+
needs a server that lists `accessSessionOffer` in `supportedCapabilities`;
|
|
68
|
+
on another server, and on the local engine, it rejects with
|
|
69
|
+
`NikaCompatibilityError` before any request
|
|
70
|
+
([ask what a route offers](server.md#ask-what-a-route-offers)).
|
|
71
|
+
- **A server can run an unpriced route under its operator's standing rule**
|
|
72
|
+
(0.124.4): `nika serve --cost-policy` names an API route the engine's
|
|
73
|
+
catalog does not price and bounds the runs on it, and a job inside the
|
|
74
|
+
rule then needs no per-run cost review. The engine records that admission
|
|
75
|
+
in the job's settlement, as `cost_admission` (`nika/cost-admission@1`):
|
|
76
|
+
the rule, its bounds, and whether the price is `unknown` or
|
|
77
|
+
`host_declared`. This package does not type it: it rides
|
|
78
|
+
`result.settlement` untyped, as every settlement field the package does
|
|
79
|
+
not know does. A server started with the flag lists
|
|
80
|
+
`costStandingPolicyV1` in `supportedCapabilities` and describes the field
|
|
81
|
+
in the document it serves; without the flag, a 0.124.4 server lists the
|
|
82
|
+
capabilities and serves the document 0.124.3 did, its version aside
|
|
83
|
+
([settlement](http-api.md#settlement)).
|
|
84
|
+
- **A failed harness turn fails its task** (`NIKA-1804`, `NIKA-1805`) where
|
|
85
|
+
0.123 settled it `succeeded` with the error text as its output.
|
|
86
|
+
- **A refused `vars` pair names its code** (`unknown_input`,
|
|
87
|
+
`input_type_mismatch`) instead of the package's `run_refused`.
|
|
88
|
+
- **The artifact manifest lists more files**: the sheet `nika:image_compose`
|
|
89
|
+
saves, an agent's image saved with `images: { save: }` beside the image
|
|
90
|
+
itself, and from 0.124.1 each file a `for_each` fan-out saved.
|
|
91
|
+
- **The keyless system voice is unpriced local work**: a run whose only spend
|
|
92
|
+
it is settles `unpriced`.
|
|
93
|
+
- **Under a cost cap, paid media is priced or refused.** The engine bills
|
|
94
|
+
image and speech calls from a dated price table against `maxCostUsd`, a
|
|
95
|
+
project `ceiling:`, a server's `--run-cost-ceiling` or a schedule's
|
|
96
|
+
`maxCostUsd`, as it already did xAI images: OpenAI `gpt-image-2`,
|
|
97
|
+
`gpt-image-2.5-sunburst` and `gpt-image-2.5-flare` (these two from the
|
|
98
|
+
usage they report), five Gemini image models, OpenAI `tts-1` and
|
|
99
|
+
`tts-1-hd`, and nine ElevenLabs models. Any other paid media call is
|
|
100
|
+
refused before any request (`NIKA-1709`, or `NIKA-1704` when only the run
|
|
101
|
+
decides it), OpenAI's default voice `gpt-4o-mini-tts`, `gpt-image-1.5` and
|
|
102
|
+
`gpt-image-1-mini` included, so a beat on one of them reads `UNREADY` at
|
|
103
|
+
`nika arm`. Move speech to `tts-1`, `tts-1-hd`, a priced ElevenLabs model
|
|
104
|
+
or the keyless `provider: system` voice, and images to `gpt-image-2` or a
|
|
105
|
+
2.5 model.
|
|
106
|
+
- **A `vision:` file is a read.** Grant each file in `permits.fs.read`: with
|
|
107
|
+
no `permits:` block it is refused (`NIKA-AUTH-006`); outside the grant, or
|
|
108
|
+
under a block that grants no read at all, a computed path included, it is
|
|
109
|
+
refused too (`NIKA-SEC-004`). `./node_modules/.bin/nika check
|
|
110
|
+
--infer-permits <file>` prints the block for a literal path. A secret in a
|
|
111
|
+
vision entry now needs `egress: [{ to: "infer" }]`.
|
|
112
|
+
|
|
113
|
+
## Steps
|
|
114
|
+
|
|
115
|
+
1. **Update the package.** `npm install @nika-open/nika@0.124.5`, then
|
|
116
|
+
check what you installed:
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
node -p "require('@nika-open/nika/package.json').version" # 0.124.5
|
|
120
|
+
./node_modules/.bin/nika --version # nika 0.124.5 (8b640a9b7)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
2. **Point `NIKA_BIN` at a 0.123 or later engine, or unset it.** An explicit `bin` or
|
|
124
|
+
`NIKA_BIN` wins over the bundled engine, and the package's own `nika`
|
|
125
|
+
command refuses a protocol-1 engine there too
|
|
126
|
+
(`NIKA_BIN=<a 0.122 binary> npx nika --version` exits 1).
|
|
127
|
+
|
|
128
|
+
3. **Upgrade each server.** Install engine 0.124.5 where your `nika serve`
|
|
129
|
+
runs (`brew install nika-open/tap/nika`,
|
|
130
|
+
`curl -LsSf https://nika.sh/install.sh | sh`, or the container image
|
|
131
|
+
`ghcr.io/nika-open/nika:0.124.5`), stop the old server as usual
|
|
132
|
+
(Ctrl-C drains running and queued jobs for up to 30 seconds), and start
|
|
133
|
+
the new one with the same flags. Then check its identity:
|
|
134
|
+
|
|
135
|
+
```sh
|
|
136
|
+
curl -s http://127.0.0.1:8787/health # "engineVersion":"0.124.5", "machineProtocolVersion":2
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
4. **Run your tests against the new pair.** Nothing in `check`, `run`,
|
|
140
|
+
`events`, `result`, `cancel`, `attachRun`, `schedule` or `traceVerify`
|
|
141
|
+
changed its signature: 0.123.0, 0.124.0 and 0.124.2 only add exports,
|
|
142
|
+
0.124.1 one optional field, `verdicts.network_tasks`, 0.124.3 one
|
|
143
|
+
method, `accessOffer`, with its types, and 0.124.4 and 0.124.5 nothing.
|
|
144
|
+
The changes are in the data those methods return: from 0.123, in the
|
|
145
|
+
section above; from 0.120.x, below.
|
|
146
|
+
|
|
147
|
+
## What changed in the data from 0.120
|
|
148
|
+
|
|
149
|
+
- **Compile questions.** A question may now be `type: 'choice'` with
|
|
150
|
+
`options[]` (at least one); answer it with one option's `key`. A `text` or
|
|
151
|
+
`literal` question carries no options. An outcome may carry
|
|
152
|
+
`requested_trigger`: the schedule the intent asks for, to bind through
|
|
153
|
+
`schedule()`, never a grant. See [compile.md](compile.md).
|
|
154
|
+
- **Provider-backed compile.** Over HTTP, `cognition: 'explicitProvider'`
|
|
155
|
+
asks a server seated with `nika serve --authoring-model` for one authoring
|
|
156
|
+
round (`compileNativeV2`), its `replay_token` answers the kept round, and
|
|
157
|
+
the judged answer round (`compileJudgedAnswerRound`) replays the kept plan
|
|
158
|
+
with your answers and only judges it. `nextCompileRequest()` builds the next
|
|
159
|
+
round and `isNikaCompileHeld()` reads the held marker. Generation-2
|
|
160
|
+
requests also carry what your local engine observes of the files the
|
|
161
|
+
intent names (`observed_world`; `observe: false` turns it off). Locally,
|
|
162
|
+
`authoringModel`, `decisionModel`, `limits`, `fresh` and `output` map to the
|
|
163
|
+
CLI's flags.
|
|
164
|
+
- **Scheduled receipts.** A `catch-up-once` firing's `receipt.origin` may
|
|
165
|
+
carry `missed_first` and `missed_count`: the silence it answers for. If you
|
|
166
|
+
validate receipt fields yourself, allow them.
|
|
167
|
+
- **Server frames.** `JobEvent.at` (when the server admitted the event) and
|
|
168
|
+
`evidence` (a reported journal loss, copied to `result.evidence`) are now
|
|
169
|
+
part of the pinned contract the package checks.
|
|
170
|
+
- **A long provider round no longer fails at 300 seconds.** The package
|
|
171
|
+
posts a provider round without a deadline through `node:http`, so Node's
|
|
172
|
+
built-in `fetch` header timeout no longer cuts it short.
|
|
173
|
+
|
|
174
|
+
The full list is in the [changelog](https://github.com/nika-open/nika-client/blob/main/CHANGELOG.md). The engine's own
|
|
175
|
+
changes are in its release notes
|
|
176
|
+
([0.123.0](https://github.com/nika-open/nika/releases/tag/v0.123.0),
|
|
177
|
+
[0.124.0](https://github.com/nika-open/nika/releases/tag/v0.124.0),
|
|
178
|
+
[0.124.1](https://github.com/nika-open/nika/releases/tag/v0.124.1),
|
|
179
|
+
[0.124.2](https://github.com/nika-open/nika/releases/tag/v0.124.2),
|
|
180
|
+
[0.124.3](https://github.com/nika-open/nika/releases/tag/v0.124.3),
|
|
181
|
+
[0.124.4](https://github.com/nika-open/nika/releases/tag/v0.124.4),
|
|
182
|
+
[0.124.5](https://github.com/nika-open/nika/releases/tag/v0.124.5)),
|
|
183
|
+
and what 0.124 does not do yet is on the
|
|
184
|
+
[known limits](https://docs.nika.sh/changelog/known-limits) page.
|
|
185
|
+
|
|
186
|
+
## Coming from 0.115 or 0.116
|
|
187
|
+
|
|
188
|
+
Read [migrating-to-0.116.md](migrating-to-0.116.md) first: it maps the
|
|
189
|
+
retired 0.115 clients (`@supernovae-st/nika-client`, `LocalNika`) onto the
|
|
190
|
+
one `Nika` class, then come back here.
|