@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.
@@ -0,0 +1,1913 @@
1
+ import { ReadableStream } from 'node:stream/web';
2
+
3
+ interface NikaSharedConfig {
4
+ /**
5
+ * How many of a run's most recent frames a session retains, and therefore
6
+ * the most a view opened after the fact can be given, and the largest
7
+ * `bufferSize` a view may ask for. Default: 4096 frames. For scale, one
8
+ * measured fixture (a clean native run of 90 independent mock/echo infer
9
+ * tasks) wrote 273 frames; other shapes write more, so count your own.
10
+ *
11
+ * It is a finite bound, never a promise about the run. A run longer than it
12
+ * still succeeds and `run.result()` still resolves; only a late view is
13
+ * refused, with `NikaEventBufferOverflowError` whose `reason` is
14
+ * `replay_truncated` and whose `observed` says what to set. An explicit
15
+ * value is kept exactly as given. Each frame is bounded by
16
+ * `machineBufferBytes`, so the retained history holds at most
17
+ * `eventBufferSize * machineBufferBytes` of frame text per run: arithmetic
18
+ * (64 GiB at both defaults), not a memory budget, since a frame is only as
19
+ * large as what the engine wrote. That bounds the history only: frames
20
+ * already handed to a consumer, other views and other runs are not counted
21
+ * in it.
22
+ */
23
+ eventBufferSize?: number;
24
+ /**
25
+ * The most the SDK holds of one machine frame (a local engine's stdout line,
26
+ * a server's SSE event), one JSON document a server answers, one captured
27
+ * engine report, and the engine diagnostics a result keeps. Default: 16 MiB,
28
+ * the bound of a `nika serve` job store, which refuses rather than truncates
29
+ * a result that would exceed it: every result a server can settle reaches
30
+ * `run.result()` and `attachRun()` under the default. A local engine bounds
31
+ * no frame, so a local result above 16 MiB needs a larger value. A frame or
32
+ * document past the bound rejects with a `NikaProtocolError` whose message
33
+ * names `machineBufferBytes` and the size to set.
34
+ */
35
+ machineBufferBytes?: number;
36
+ }
37
+ /** The default configuration drives a native `nika` process. */
38
+ interface NikaLocalConfig extends NikaSharedConfig {
39
+ /** Working directory used by the native process transport. */
40
+ cwd?: string;
41
+ /** Binary resolution: this value, then NIKA_BIN, then the host payload package. */
42
+ bin?: string;
43
+ url?: never;
44
+ token?: never;
45
+ allowInsecureHttp?: never;
46
+ requestTimeout?: never;
47
+ fetch?: never;
48
+ }
49
+ /** Supplying a URL selects the authenticated HTTP transport. */
50
+ interface NikaRemoteConfig extends NikaSharedConfig {
51
+ /** A `nika serve --bind` base URL. */
52
+ url: string;
53
+ /** Bearer token matching the server's `--token-file`. */
54
+ token: string;
55
+ /** Plain HTTP is refused unless this is explicitly true. */
56
+ allowInsecureHttp?: boolean;
57
+ /** Bound for HTTP admission. Default: 30 seconds. */
58
+ requestTimeout?: number;
59
+ /** Fetch implementation used by the HTTP transport. */
60
+ fetch?: typeof globalThis.fetch;
61
+ /** Working directory used while capturing the immutable snapshot locally. */
62
+ cwd?: string;
63
+ /** Local engine used to capture the immutable snapshot before HTTP admission. */
64
+ bin?: string;
65
+ }
66
+ /** Public configuration for the one Nika client surface. */
67
+ type NikaConfig = NikaLocalConfig | NikaRemoteConfig;
68
+ type NikaTransportKind = 'native-process' | 'http';
69
+ /**
70
+ * Brand carrier for engine-issued identities. The SDK brands an identity
71
+ * only where the engine (or its durable record) issues it; it never invents
72
+ * one itself.
73
+ */
74
+ declare const NikaIdentityBrand: unique symbol;
75
+ interface NikaIdentity<Name extends string> {
76
+ readonly [NikaIdentityBrand]: Name;
77
+ }
78
+ /** A run identity issued by `run()` or `attachRun()`. Assignable to `string`. */
79
+ type NikaRunId = string & NikaIdentity<'NikaRunId'>;
80
+ /** An engine execution identity carried by terminal settlements and receipts. */
81
+ type NikaExecutionId = string & NikaIdentity<'NikaExecutionId'>;
82
+ /** A durable `nika serve` job identity accepted by `attachRun()`. */
83
+ type NikaJobId = string & NikaIdentity<'NikaJobId'>;
84
+ /** Machine vocabulary is additive. Known words aid completion without closing the set. */
85
+ type NikaRunStatus = 'queued' | 'running' | 'paused' | 'succeeded' | 'failed' | 'interrupted' | 'cancelled' | (string & {});
86
+ /**
87
+ * A machine check report. Unknown engine fields deliberately ride through:
88
+ * from engine 0.124, for example, a local report on a workflow that calls a
89
+ * child workflow lists those calls in `composed_calls`, and one that makes a
90
+ * paid image or speech call lists it in `cost.media`, both untyped here.
91
+ */
92
+ interface NikaCheckResult {
93
+ report_version?: number;
94
+ clean?: boolean;
95
+ exitCode?: number;
96
+ /**
97
+ * The local engine report's layers (absent from a server's acknowledgement).
98
+ * `clean` judges the file; `access_ready` judges the access plan on this
99
+ * machine, under `check({ access })` when a pin was given. A pin the engine
100
+ * refuses leaves `clean: true` with `access_ready: false`, and `blockers`
101
+ * names the refusal in the engine's words.
102
+ */
103
+ verdicts?: NikaCheckVerdicts;
104
+ [key: string]: unknown;
105
+ }
106
+ /** The layers of a local check report (`nika check --json`, engine 0.123 and later). Additive. */
107
+ interface NikaCheckVerdicts {
108
+ /** Grammar, DAG, permits and types hold, and the resolver knows every model. */
109
+ valid?: boolean;
110
+ /** A path exists on this machine for every model (presence, never a dial). */
111
+ access_ready?: boolean;
112
+ /** The seat's limits fit the declaration. */
113
+ capacity_fit?: boolean;
114
+ /** The three hold and no known blocker remains. */
115
+ run_ready?: boolean;
116
+ /** What stands in the way, in the engine's words. */
117
+ blockers?: string[];
118
+ /**
119
+ * The tasks whose own effects can still reach the network, sorted: a fetch
120
+ * or webhook to a real host, an MCP tool, a paid media call (engine 0.124.1
121
+ * and later). `access_ready` judges model routes only; the report's PERMITS
122
+ * row judges these, and a `mock/echo` rehearsal stubs none of them.
123
+ */
124
+ network_tasks?: string[];
125
+ [key: string]: unknown;
126
+ }
127
+ /** Fields every engine event can carry, whether its kind is known or not. */
128
+ interface NikaEventFields {
129
+ status?: NikaRunStatus;
130
+ sequence?: number;
131
+ receipt?: NikaReceipt;
132
+ outputs?: Record<string, unknown>;
133
+ [key: string]: unknown;
134
+ }
135
+ /** The workflow graph started executing. */
136
+ interface NikaWorkflowStartedEvent extends NikaEventFields {
137
+ kind: 'workflow_started';
138
+ }
139
+ /** A task was scheduled for execution. */
140
+ interface NikaTaskScheduledEvent extends NikaEventFields {
141
+ kind: 'task_scheduled';
142
+ }
143
+ /** A task started executing. */
144
+ interface NikaTaskStartedEvent extends NikaEventFields {
145
+ kind: 'task_started';
146
+ }
147
+ /**
148
+ * A task settled. Per-task payloads ride the open fields. On a native run,
149
+ * an `infer:` or `agent:` task's frame carries the rows `access_requirement`
150
+ * and `access_selection`: read them with `readNikaAccessRequirement` and
151
+ * `readNikaAccessSelection`.
152
+ */
153
+ interface NikaTaskCompletedEvent extends NikaEventFields {
154
+ kind: 'task_completed';
155
+ }
156
+ /**
157
+ * A resumed run (`nika run --resume <trace>`) reused a task instead of running
158
+ * it: the task's identity matched a success the trace records. The frame ends
159
+ * the task with no `task_started` before it, and the run counts the task as an
160
+ * ordinary success. Its rows (`fields`) name the `task`, the identity it
161
+ * matched (`def_hash`, `input_hash`), the reused `output` as JSON text and the
162
+ * `outcome`. A run this package starts is never a resumed one.
163
+ */
164
+ interface NikaTaskCacheHitEvent extends NikaEventFields {
165
+ kind: 'task_cache_hit';
166
+ }
167
+ /**
168
+ * The workflow graph settled. This is the terminal frame of a native-process
169
+ * run and carries the run's outputs, receipt, and final status together.
170
+ */
171
+ interface NikaWorkflowCompletedEvent<Outputs extends Record<string, unknown> = Record<string, unknown>> extends NikaEventFields {
172
+ kind: 'workflow_completed';
173
+ status?: NikaRunStatus;
174
+ outputs?: Outputs;
175
+ receipt?: NikaReceipt;
176
+ }
177
+ /** The workflow graph failed. */
178
+ interface NikaWorkflowFailedEvent extends NikaEventFields {
179
+ kind: 'workflow_failed';
180
+ error?: NikaMachineError;
181
+ }
182
+ /** The workflow graph was interrupted before settling. */
183
+ interface NikaWorkflowInterruptedEvent extends NikaEventFields {
184
+ kind: 'workflow_interrupted';
185
+ }
186
+ /**
187
+ * The terminal settlement frame of a native engine process: the one frame
188
+ * that carries the run's outputs, receipt, and final status together. Its
189
+ * HTTP peer is `execution.settled`; one guard narrows both.
190
+ */
191
+ interface NikaRunSettledEvent<Outputs extends Record<string, unknown> = Record<string, unknown>> extends NikaEventFields {
192
+ kind: 'run_settled';
193
+ status?: NikaRunStatus;
194
+ /** Why the run settled this way (engine 0.118+ · flattened on this frame). */
195
+ cause?: NikaRunCause;
196
+ elapsed_ms?: number;
197
+ tasks?: NikaTaskTally;
198
+ spend?: NikaSpend;
199
+ outputs?: Outputs;
200
+ receipt?: NikaReceipt;
201
+ /**
202
+ * The cause of a `failed` settlement (engine 0.117+): the first failed
203
+ * task's code, message and task id. Absent on a succeeded or paused run,
204
+ * and on engines that only name the cause on their `task_failed` frame.
205
+ */
206
+ error?: NikaMachineError;
207
+ }
208
+ /** The run's trace chain was sealed. */
209
+ interface NikaRunSealedEvent extends NikaEventFields {
210
+ kind: 'run_sealed';
211
+ receipt?: NikaReceipt;
212
+ }
213
+ /**
214
+ * A journal delivery loss the resident reported, exactly as its contract
215
+ * closes it: the run's journal mirror stopped recording. It is independent of
216
+ * the execution: a run can settle `succeeded` and still carry it. It is never
217
+ * a verdict and never changes a status; it says the trace may be incomplete
218
+ * before `traceVerify` is trusted. Its absence is only absence: it never
219
+ * claims that a journal exists.
220
+ *
221
+ * Defined by the `nika serve` 0.123.0 contract this package pins
222
+ * (`JournalEvidence` on `Job` and `JobEvent`); absent when the resident
223
+ * reported no loss.
224
+ */
225
+ interface NikaJournalEvidence {
226
+ status: 'mirror_lost';
227
+ /** The mirror's first error, classified: never OS text, never a path. */
228
+ reason: 'write_failed' | 'record_refused';
229
+ }
230
+ /**
231
+ * Fields only the resident's frames carry, both declared by the `nika serve`
232
+ * 0.123.0 contract this package pins (`JobEvent.at`, `JobEvent.evidence`).
233
+ * Both are optional on the wire: a 0.123.0 resident writes `at` on every
234
+ * frame and `evidence` only when it reports a journal loss.
235
+ */
236
+ interface NikaResidentEventFields extends NikaEventFields {
237
+ /** When the resident admitted the event: RFC 3339, UTC. Outside the event's hash chain. */
238
+ at?: string;
239
+ /** A reported journal delivery loss, on the terminal frame. */
240
+ evidence?: NikaJournalEvidence;
241
+ }
242
+ /**
243
+ * The HTTP transport admitted the execution and it is running. This is the
244
+ * first lifecycle frame `nika serve --bind` streams for a durable job.
245
+ */
246
+ interface NikaExecutionStartedEvent extends NikaResidentEventFields {
247
+ kind: 'execution.started';
248
+ }
249
+ /**
250
+ * The terminal settlement frame of the HTTP transport, and the peer of
251
+ * `run_settled`: the one frame that carries the run's outputs, receipt, and
252
+ * final status together.
253
+ */
254
+ interface NikaExecutionSettledEvent<Outputs extends Record<string, unknown> = Record<string, unknown>> extends NikaResidentEventFields {
255
+ kind: 'execution.settled';
256
+ status?: NikaRunStatus;
257
+ outputs?: Outputs;
258
+ receipt?: NikaReceipt;
259
+ /** The settlement the resident nests whole on this frame (engine 0.118+ · ADR-128). */
260
+ settlement?: NikaSettlement;
261
+ }
262
+ /**
263
+ * The resident cancelled the execution: a queued job cancelled before it was
264
+ * claimed, or a running one whose owner settled the request as a
265
+ * cancellation. It carries the settlement when the runtime built one.
266
+ */
267
+ interface NikaExecutionCancelledEvent extends NikaResidentEventFields {
268
+ kind: 'execution.cancelled';
269
+ settlement?: NikaSettlement;
270
+ }
271
+ /** The server refused the execution. */
272
+ interface NikaExecutionRefusedEvent extends NikaResidentEventFields {
273
+ kind: 'execution.refused';
274
+ }
275
+ /**
276
+ * The execution was interrupted before settling. A resident that restarts
277
+ * marks an orphaned running job with either word, so both are one variant.
278
+ */
279
+ interface NikaExecutionInterruptedEvent extends NikaResidentEventFields {
280
+ kind: 'execution.interrupted' | 'interrupted';
281
+ }
282
+ /**
283
+ * Forward-compatibility variant: any kind this SDK version does not know
284
+ * yet stays representable, so the event union is intentionally
285
+ * non-exhaustive.
286
+ */
287
+ interface NikaUnknownEvent extends NikaEventFields {
288
+ kind?: string;
289
+ }
290
+ /**
291
+ * One engine-owned run event, from either transport: the native process emits
292
+ * the `workflow_*` / `task_*` / `run_*` kinds, `nika serve` emits the
293
+ * `execution.*` kinds. Known kinds discriminate on `kind`; unknown kinds fall
294
+ * back to `NikaUnknownEvent`. Future fields stay open on every variant.
295
+ * `Outputs` types the terminal frames' outputs and defaults to the transport
296
+ * shape, so untyped callers see no change.
297
+ */
298
+ type NikaEvent<Outputs extends Record<string, unknown> = Record<string, unknown>> = NikaWorkflowStartedEvent | NikaTaskScheduledEvent | NikaTaskStartedEvent | NikaTaskCompletedEvent | NikaTaskCacheHitEvent | NikaWorkflowCompletedEvent<Outputs> | NikaWorkflowFailedEvent | NikaWorkflowInterruptedEvent | NikaRunSettledEvent<Outputs> | NikaRunSealedEvent | NikaExecutionStartedEvent | NikaExecutionSettledEvent<Outputs> | NikaExecutionCancelledEvent | NikaExecutionRefusedEvent | NikaExecutionInterruptedEvent | NikaUnknownEvent;
299
+ /**
300
+ * The SDK's one lifecycle vocabulary, identical on both transports. Each word
301
+ * names a fact an engine wrote; the protocol word that carried it stays on
302
+ * `raw.kind`. Transports differ in cardinality, never in these names.
303
+ *
304
+ * A frame that speaks of the run's state earns its name only for a
305
+ * (kind, status) pair a producer defines. The engine's state word decides and
306
+ * is never defaulted: an absent, null, future, or still-running status, or
307
+ * one that contradicts its kind, stays an `engine.event`.
308
+ *
309
+ * - `run.started`: `workflow_started` · `execution.started`.
310
+ * - `task.scheduled` · `task.started` · `task.completed` · `task.failed` ·
311
+ * `task.skipped` · `task.cancelled` · `task.cache_hit`: the native `task_*`
312
+ * frames. A skip or a cancellation ends a task as a completion or a failure
313
+ * does; it names its `task`, never an `error`. A skip under
314
+ * `on_error: { skip: true }` keeps the error that made it skip on `raw`, in
315
+ * the frame's `outcome` row. A recovered task ends on `task.completed`,
316
+ * and its `task_recovered` frame stays an `engine.event`. A task a resumed
317
+ * run (`nika run --resume`) reused ends on `task.cache_hit`, with no
318
+ * `task.started` before it: it names its `task`, and the identity it matched
319
+ * and the output it reused stay on `raw`; a run this package starts is
320
+ * never a resumed one. `nika serve` streams no per-task frame, so an HTTP
321
+ * run yields none; the SDK never synthesizes one.
322
+ * - `run.waiting`: the settlement frame (`run_settled` · `execution.settled`)
323
+ * carrying `paused`. A human gate holds the run: it is not failed, not a
324
+ * completed execution, and stays resumable.
325
+ * - `run.settled`: exactly these pairs, and no other. The settlement frame
326
+ * (`run_settled` · `execution.settled`) carrying `succeeded`, `failed`, or
327
+ * `cancelled`; `execution.cancelled` carrying `cancelled`;
328
+ * `execution.refused` carrying `failed`. A dedicated end kind with another
329
+ * terminal word (a refusal that `succeeded`, a cancellation that `failed`)
330
+ * contradicts itself and stays an `engine.event`.
331
+ * - `run.interrupted`: `workflow_interrupted` · `execution.interrupted` ·
332
+ * `interrupted` carrying `interrupted`. The engine lost the execution and
333
+ * its settlement is unknown: an evidence state, never a settlement. This is
334
+ * an engine-reported frame, distinct from the thrown
335
+ * `NikaObservationInterrupted`, which means this client lost its
336
+ * observation of a run that may still be running.
337
+ * - `run.sealed`: `run_sealed`, native only.
338
+ * - `engine.event`: every other frame, including kinds this SDK version does
339
+ * not know yet. Nothing is dropped; read `raw`.
340
+ *
341
+ * The projection keeps no state between frames and deduplicates nothing. The
342
+ * set is additive: keep a `default` branch.
343
+ */
344
+ type NikaRunEventKind = 'run.started' | 'task.scheduled' | 'task.started' | 'task.completed' | 'task.failed' | 'task.skipped' | 'task.cancelled' | 'task.cache_hit' | 'run.waiting' | 'run.settled' | 'run.interrupted' | 'run.sealed' | 'engine.event';
345
+ /**
346
+ * One run event in the SDK's lifecycle vocabulary, as `run.events()` yields
347
+ * it. It is a projection of exactly one protocol frame: `raw` is that frame,
348
+ * untouched, and every other field is present only when the frame stated it.
349
+ * An `engine.event` is given no lifecycle meaning: it carries no `status`,
350
+ * `task` or `error`, only its cursor and `raw`.
351
+ */
352
+ interface NikaRunEvent<Outputs extends Record<string, unknown> = Record<string, unknown>> {
353
+ readonly kind: NikaRunEventKind;
354
+ /** The transport whose protocol `raw` speaks. */
355
+ readonly transport: NikaTransportKind;
356
+ /** The engine's own state word, never renamed: a waiting run reads `paused`. */
357
+ readonly status?: NikaRunStatus;
358
+ /**
359
+ * HTTP only: the SSE sequence of this frame, the cursor to persist for
360
+ * `attachRun(id, { lastEventId })`. A native process has no durable replay,
361
+ * so a native event never carries one.
362
+ */
363
+ readonly sequence?: number;
364
+ /** The task a `task.*` frame named. */
365
+ readonly task?: string;
366
+ /** The failure the frame named: a failed task, or a failed settlement. */
367
+ readonly error?: NikaMachineError;
368
+ /** The exact protocol frame the engine wrote. */
369
+ readonly raw: NikaEvent<Outputs>;
370
+ }
371
+ /**
372
+ * Engine-issued proof material. The SDK transports it but never constructs,
373
+ * reads a workflow to enrich it, or verifies its claims itself.
374
+ */
375
+ type NikaReceipt = Readonly<Record<string, unknown>>;
376
+ interface NikaMachineError {
377
+ code?: string;
378
+ message?: string;
379
+ /** The task that failed, when a native `task_failed` frame named it. */
380
+ task?: string;
381
+ [key: string]: unknown;
382
+ }
383
+ /** Why a run settled the way it did (engine 0.118+ · ADR-128). */
384
+ type NikaRunCause = 'normal' | 'human_gate' | 'task_failed' | 'output_contract' | 'budget' | 'operator' | 'refused' | (string & {});
385
+ /**
386
+ * How much of the spend is priced (engine 0.118+): `unmetered` = no metered
387
+ * call · `unpriced` = calls without a known price (a mock, a local model, a
388
+ * subscription seat and, from engine 0.124, the keyless system voice of
389
+ * `nika:tts_generate`), never free · `partially_priced` · `priced`. A native
390
+ * task frame names why its cost is absent in its `cost_unpriced` row
391
+ * (`mock_provider`, `local_model`, `subscription_quota`…). From engine 0.124
392
+ * a paid image or speech call is billed from the engine's dated price table
393
+ * (its bill under `by_source['nika:image_generate']` or
394
+ * `by_source['nika:tts_generate']`), or counted unpriced with
395
+ * `missing_catalog_price` when the table cannot price it, or
396
+ * `provider_did_not_report_usage` when its response reported nothing to bill.
397
+ */
398
+ type NikaCostQualifier = 'priced' | 'partially_priced' | 'unpriced' | 'unmetered' | (string & {});
399
+ /** How the run's tasks ended (engine 0.118+): `recovered` is a tally, never a state. */
400
+ interface NikaTaskTally {
401
+ total?: number;
402
+ ok?: number;
403
+ failed?: number;
404
+ recovered?: number;
405
+ skipped?: number;
406
+ cancelled?: number;
407
+ never_started?: number;
408
+ [key: string]: unknown;
409
+ }
410
+ /** What the run spent and how much of it is priced (engine 0.118+). */
411
+ interface NikaSpend {
412
+ /** Present only when at least one call metered real spend; unknown cost is never zero. */
413
+ total_cost_usd?: number | null;
414
+ priced_calls?: number;
415
+ unpriced_calls?: number;
416
+ qualifier?: NikaCostQualifier;
417
+ pricing_as_of?: string | null;
418
+ /** Spend per pricing source, when the engine broke it down. */
419
+ by_source?: Record<string, number>;
420
+ [key: string]: unknown;
421
+ }
422
+ /**
423
+ * The run's settlement as the engine built it once (ADR-128): the state's
424
+ * cause, the task tally, the spend and its qualifier, the elapsed time.
425
+ * Absent on engines before 0.118; never derived from an exit code.
426
+ */
427
+ interface NikaSettlement {
428
+ /**
429
+ * The state word the settlement itself carries (`succeeded` · `failed` ·
430
+ * `paused` · `cancelled`) on the resident's nested projection; the native
431
+ * `run_settled` frame states it on the frame instead.
432
+ */
433
+ status?: NikaRunStatus;
434
+ cause?: NikaRunCause;
435
+ elapsed_ms?: number;
436
+ tasks?: NikaTaskTally;
437
+ spend?: NikaSpend;
438
+ /** The failure named on a `failed` settlement: code, message and the task, when one failed. */
439
+ error?: NikaMachineError;
440
+ [key: string]: unknown;
441
+ }
442
+ /**
443
+ * The engine's result of observing an admitted run, including a paused run.
444
+ * Admitted workflow failure resolves with `status: 'failed'`; configuration,
445
+ * transport, protocol, and compatibility errors reject instead. Use
446
+ * `isNikaRunSucceeded(result)` before treating an observation as success.
447
+ * Outputs are optional even on success, and status stays forward-compatible.
448
+ */
449
+ interface NikaRunResult<Outputs extends Record<string, unknown> = Record<string, unknown>> {
450
+ id: NikaRunId;
451
+ status: NikaRunStatus;
452
+ transport: NikaTransportKind;
453
+ exitCode?: number;
454
+ outputs?: Outputs;
455
+ receipt?: NikaReceipt;
456
+ error?: NikaMachineError;
457
+ /** Engine execution identity, when the transport surface reports one. */
458
+ execution_id?: NikaExecutionId;
459
+ /** The settlement's cause, tally and spend (engine 0.118+), when the terminal frame carried them. */
460
+ settlement?: NikaSettlement;
461
+ /**
462
+ * HTTP only: the journal delivery loss the resident reported on the terminal
463
+ * frame or the durable job that settled this run. Copied, never inferred:
464
+ * absent when the resident reported none, which claims nothing about a
465
+ * journal. It never changes `status`. A native process reports none.
466
+ */
467
+ evidence?: NikaJournalEvidence;
468
+ [key: string]: unknown;
469
+ }
470
+ /**
471
+ * An admitted run and its whole lifecycle. `run()` and `attachRun()` return
472
+ * one only after admission: a workflow the engine refuses rejects there and
473
+ * never yields a handle. Every member is bound to the run, so a method may be
474
+ * extracted (`const { events, result } = run`) and still works.
475
+ *
476
+ * The handle owns observation, settlement, status, cancellation and, on a
477
+ * server, what the settled job produced (its artifacts), nothing else:
478
+ * checking, proof, catalogs and authoring stay on `Nika`. It is
479
+ * process-bound. To continue in another process, persist `id` and the last
480
+ * `event.sequence` you fully processed, then call
481
+ * `nika.attachRun(id, { lastEventId })`, the one recovery door.
482
+ *
483
+ * `id` is what differs by transport, and the type cannot show it:
484
+ * - HTTP: the resident's durable job id. This is the identity to store.
485
+ * - native: an ephemeral correlation id of this SDK process. It appears in no
486
+ * journal and cannot be recovered after the process ends; `attachRun`
487
+ * refuses it. Resume a native run through the engine's own trace.
488
+ */
489
+ interface NikaRun<Outputs extends Record<string, unknown> = Record<string, unknown>> {
490
+ readonly id: NikaRunId;
491
+ /**
492
+ * A bounded view of the run's events in the SDK's lifecycle vocabulary;
493
+ * each event keeps its protocol frame on `raw`. Transports differ in how
494
+ * many facts they emit, never in their names. The iterator throws for a
495
+ * broken observation (`NikaObservationInterrupted` carries the cursor); an
496
+ * admitted workflow failure ends it normally and is read from `result()`.
497
+ */
498
+ readonly events: (options?: NikaEventsOptions) => AsyncIterable<NikaRunEvent<Outputs>>;
499
+ /**
500
+ * The engine's result of observing this run, settled once. One failure law:
501
+ * - rejects: a transport, protocol, or compatibility fault, or a broken
502
+ * observation (`NikaObservationInterrupted`, which carries the cursor).
503
+ * None of them says the run failed; it may still be running.
504
+ * - resolves with `status: 'failed'`: an admitted failure is result data,
505
+ * with the engine's `error.code` when the engine named one. `cancelled`
506
+ * and the engine-reported `interrupted` resolve the same way.
507
+ * - resolves with `status: 'paused'`: a human gate holds the run. It is
508
+ * neither a failure nor a completed execution.
509
+ * Read `isNikaRunSucceeded(result)` before treating it as success.
510
+ */
511
+ readonly result: () => Promise<NikaRunResult<Outputs>>;
512
+ /**
513
+ * The current durable status, without waiting for settlement. Only a
514
+ * resident owns one: a native run rejects with a typed
515
+ * `NikaCompatibilityError` instead of inventing a status.
516
+ */
517
+ readonly status: () => Promise<NikaRunStatus>;
518
+ /**
519
+ * Ask the engine to cancel. Idempotent: every call returns the one request.
520
+ * Acceptance is not a result; read what the engine recorded from `result()`.
521
+ */
522
+ readonly cancel: () => Promise<NikaCancelResult>;
523
+ /**
524
+ * Server only: what the settled job produced, as its sealed journal records
525
+ * it (`GET /v1/jobs/{id}/artifacts`): the files its builtins saved
526
+ * (`nika:chart`, `nika:image_generate`, `nika:tts_generate`, `nika:image_fx`,
527
+ * and `nika:image_compose` from engine 0.124), the images its agents'
528
+ * harnesses sent and, from engine 0.124, the file an `agent:` task saved
529
+ * such an image to with `images: { save: }`, each with its recorded size and
530
+ * SHA-256. The SDK checks that the manifest's receipt is the job's own.
531
+ *
532
+ * Needs a server whose `/health` lists `artifacts`; any other server, and a
533
+ * local run, reject with `NikaCompatibilityError` (capability `artifacts`)
534
+ * before any request. A job that has not settled rejects with
535
+ * `NikaOperationError` (`job_not_settled`, 409): await `result()` first.
536
+ */
537
+ readonly artifacts: (options?: NikaArtifactsOptions) => Promise<NikaArtifactManifest>;
538
+ /**
539
+ * Server only: one artifact's bytes as a stream, named by its manifest
540
+ * `name` or given as its entry. It resolves once the server answered with
541
+ * the recorded size and digest. The stream closes only once every byte is
542
+ * proven (exactly the recorded size, hashing to the recorded SHA-256, as the
543
+ * manifest entry and the response headers both say), and errors otherwise.
544
+ * A body cut short is downloaded again, up to 3 more times; a file that
545
+ * changed then answers 409 `artifact_changed`, a `NikaOperationError` like
546
+ * every refusal of the server. Neither `machineBufferBytes` nor
547
+ * `requestTimeout` bounds a download: stop it with `signal`, or cancel the
548
+ * stream.
549
+ */
550
+ readonly downloadArtifact: (artifact: string | NikaArtifact, options?: NikaArtifactDownloadOptions) => Promise<NikaArtifactDownload>;
551
+ /**
552
+ * Server only: one artifact's whole bytes, resolved only once they are
553
+ * proven, as `downloadArtifact()` proves them. An artifact larger than
554
+ * `maxBytes` (16 MiB by default) is refused with `NikaConfigurationError`
555
+ * before its download starts: stream it with `downloadArtifact()` instead.
556
+ */
557
+ readonly readArtifact: (artifact: string | NikaArtifact, options?: NikaArtifactReadOptions) => Promise<Uint8Array>;
558
+ /** Compatibility alias of `result()`: the same promise, kept while code migrates. */
559
+ readonly done: Promise<NikaRunResult<Outputs>>;
560
+ }
561
+ /**
562
+ * One byte stream a settled server job produced, as the job's sealed journal
563
+ * records it: a file a builtin saved inside the server's project, or an image
564
+ * an agent's harness sent. Every size and digest is the journal's. The SDK
565
+ * reads the fields below typed and lets any other ride through, since the
566
+ * server's contract may add some.
567
+ */
568
+ interface NikaArtifact {
569
+ /**
570
+ * The artifact's key, unique within the job: `file/<path>` or
571
+ * `agent_image/<n>.<ext>`. Pass it, or this entry, to
572
+ * `run.downloadArtifact()`. It is a key, never a filesystem path.
573
+ */
574
+ name: string;
575
+ /**
576
+ * `file`: a file a builtin saved (`nika:chart`, `nika:image_generate`,
577
+ * `nika:tts_generate`, `nika:image_fx`, `nika:image_compose`; from engine
578
+ * 0.124.1 each item's file of a `for_each` fan-out too), or the file
579
+ * the engine wrote from an agent's image under `images: { save: }` (engine
580
+ * 0.124: the same bytes as that image's `agent_image` entry).
581
+ * `agent_image`: an image an agent's harness sent, kept by the server.
582
+ * Known words aid completion without closing the set.
583
+ */
584
+ kind: 'file' | 'agent_image' | (string & {});
585
+ /**
586
+ * A file's path in the server's project, as the workflow wrote it
587
+ * (normalized); absent for an agent image. The SDK refuses a manifest whose
588
+ * path is not contained: it is relative, `/`-separated, with no empty, `.`
589
+ * or `..` segment, no backslash and no NUL byte.
590
+ */
591
+ path?: string;
592
+ /** The recorded size, in bytes. */
593
+ size: number;
594
+ /** The recorded SHA-256 of the bytes: 64 lowercase hexadecimal digits. */
595
+ sha256: string;
596
+ /** The recorded media type, else one derived from the extension, else `application/octet-stream`. */
597
+ mime: string;
598
+ /** The task whose journal event records it. */
599
+ task?: string;
600
+ /** The id of that journal event. */
601
+ event_id: string;
602
+ [key: string]: unknown;
603
+ }
604
+ /**
605
+ * What a settled server job produced, as its sealed journal records it
606
+ * (`GET /v1/jobs/{id}/artifacts`, read by `run.artifacts()`), bound to the
607
+ * job's receipt. The server lists only the byte streams its journal records
608
+ * with a digest: what `nika:write` and `nika:edit` wrote is not listed.
609
+ */
610
+ interface NikaArtifactManifest {
611
+ /** The job's receipt. The SDK checked that it is the job's own. */
612
+ receipt: NikaReceipt;
613
+ /** The tier the job's sealed journal attained. The SDK refuses any other word. */
614
+ verdict: 'sealed' | 'anchored';
615
+ /**
616
+ * The largest artifact this server downloads (256 MiB by default). A larger
617
+ * one stays listed, and its download is refused (403 `artifact_too_large`).
618
+ */
619
+ max_artifact_bytes: number;
620
+ /**
621
+ * The job recorded more artifacts than the server lists (1,024). A name past
622
+ * them still downloads by its name, proven against the response alone (see
623
+ * `NikaArtifactDownload.artifact`).
624
+ */
625
+ truncated: boolean;
626
+ /** In journal order; a file written twice appears once, at its last write. */
627
+ artifacts: NikaArtifact[];
628
+ [key: string]: unknown;
629
+ }
630
+ interface NikaArtifactsOptions {
631
+ /** Stops only this request. It never cancels the run. */
632
+ signal?: AbortSignal;
633
+ }
634
+ interface NikaArtifactDownloadOptions {
635
+ /**
636
+ * Stops this download: its requests, the wait before a retry and the
637
+ * stream, which then errors with `NikaTransportError`. It never cancels the
638
+ * run.
639
+ */
640
+ signal?: AbortSignal;
641
+ }
642
+ interface NikaArtifactReadOptions extends NikaArtifactDownloadOptions {
643
+ /**
644
+ * The most bytes `readArtifact()` holds: a positive integer. Default: 16 MiB.
645
+ * A listed artifact larger than it is refused before its download starts.
646
+ */
647
+ maxBytes?: number;
648
+ }
649
+ /** One artifact download (`run.downloadArtifact()`): what it is proven against, and its bytes. */
650
+ interface NikaArtifactDownload {
651
+ /** The artifact's name, as requested. */
652
+ readonly name: string;
653
+ /** The size the bytes are proven against: the manifest entry's, which `Content-Length` repeats. */
654
+ readonly size: number;
655
+ /**
656
+ * The SHA-256 the bytes are proven against: the manifest entry's, which the
657
+ * response's `Nika-Artifact-Sha256` header repeats.
658
+ */
659
+ readonly sha256: string;
660
+ /** The recorded media type: the entry's `mime`, or the response's `Content-Type` without one. */
661
+ readonly mime: string;
662
+ /**
663
+ * The manifest entry the bytes are proven against. Absent only for a name
664
+ * past the entries a truncated manifest lists: those bytes are proven
665
+ * against the response's `Content-Length` and `Nika-Artifact-Sha256` alone.
666
+ */
667
+ readonly artifact?: NikaArtifact;
668
+ /**
669
+ * The bytes, readable once. It closes only once they are proven, and holds
670
+ * its last chunk back until then; otherwise it errors: `NikaProtocolError`
671
+ * for bytes that are not the recorded ones, `NikaOperationError` for a
672
+ * server refusal on a retry (`artifact_changed`…), `NikaTransportError` for
673
+ * a download that stayed incomplete or was aborted. Read it to its end or
674
+ * cancel it: an unread stream holds its connection open. It is a Node web
675
+ * stream (`node:stream/web`): `Readable.fromWeb(download.stream)` pipes it,
676
+ * `for await` reads it.
677
+ */
678
+ readonly stream: ReadableStream<Uint8Array>;
679
+ }
680
+ interface NikaCancelResult {
681
+ runId: NikaRunId;
682
+ accepted: boolean;
683
+ /**
684
+ * `cancelled`: the job settled cancelled on the cancel reply itself.
685
+ * `already_settled`: the run had already ended, nothing was cancelled.
686
+ * `cancellation_requested`: the request was accepted while the execution
687
+ * owner had not settled yet (a native SIGTERM, or the resident's 202); the
688
+ * run then settles on its own terminal, read from `run.result()`, which may
689
+ * be `cancelled`, `succeeded`, `failed`, or `interrupted` once the
690
+ * resident's grace expired. Open to the engine's future words.
691
+ */
692
+ status: 'cancelled' | 'already_settled' | 'cancellation_requested' | (string & {});
693
+ transport: NikaTransportKind;
694
+ [key: string]: unknown;
695
+ }
696
+ /** Server-owned metadata for one contained resident workflow. */
697
+ interface NikaWorkflowMetadata {
698
+ workflow: string;
699
+ [key: string]: unknown;
700
+ }
701
+ interface NikaTraceVerifyResult {
702
+ /**
703
+ * The package's own binding. Locally: the engine's verifier held and the
704
+ * receipt matches its evidence (a keyless run's receipt does not). Over
705
+ * HTTP: the server's verdict holds and names this receipt's `trace_id`;
706
+ * `ok` holds too, so over HTTP `verified: true` includes an intact but
707
+ * unsigned journal. Read it before `verdict`.
708
+ */
709
+ verified: boolean;
710
+ /**
711
+ * Engine-owned trace verdict. The native path answers `verified` or
712
+ * `invalid`. Over HTTP it is the server's verdict on the journal it wrote
713
+ * for the job, in the CLI's words: `ok` (intact, unsigned) · `sealed` ·
714
+ * `anchored` · `replayed` hold; `incomplete` · `tampered` · `broken` do not;
715
+ * `unchained` · `empty` · `unreadable` · `refused` · `line-over-long` ·
716
+ * `unknown` are the CLI's refusal classes; `unavailable` means the server
717
+ * has no journal for the job. Over HTTP it describes the job's journal, not
718
+ * this receipt: a receipt that does not match keeps the server's `sealed`
719
+ * while `verified` is `false`. Open to additive future vocabulary.
720
+ */
721
+ verdict?: 'verified' | 'invalid' | 'unavailable' | 'ok' | 'sealed' | 'anchored' | 'replayed' | 'incomplete' | 'tampered' | 'broken' | 'unchained' | 'empty' | 'unreadable' | 'refused' | 'line-over-long' | 'unknown' | (string & {});
722
+ /**
723
+ * Engine-owned machine class beside the verdict. Locally it is
724
+ * `receipt_mismatch` when the receipt does not match the engine's evidence;
725
+ * a verifier that failed (`verdict: 'invalid'` with its `exitCode`) and a
726
+ * verdict that holds carry none. Over HTTP the server always sends one:
727
+ * beside a verdict that holds it is the seal tier (`sealed`, `unsealed`).
728
+ */
729
+ reason?: 'trace_invalid' | 'receipt_mismatch' | 'run_not_terminal' | 'trace_journal_unavailable' | 'sealed' | 'unsealed' | (string & {});
730
+ trace_id?: string;
731
+ exitCode?: number;
732
+ output?: string;
733
+ [key: string]: unknown;
734
+ }
735
+ /**
736
+ * An access pin: the path the engine takes to the workflow's models, the value
737
+ * `nika run --access` and `nika check --access` take. `model:` picks the
738
+ * intelligence; the pin picks the path. Engine 0.123.1 knows the classes
739
+ * `local`, `mock`, `harness`, `oauth` and `api` and the harness seats
740
+ * `claude-code`, `codex`, `copilot`, `gemini-cli`, `grok-build`, `kimi-code`,
741
+ * `opencode` and `qwen-code`. Known words aid completion without closing the
742
+ * set: the engine, never the SDK, judges a pin.
743
+ */
744
+ type NikaAccessPin = 'local' | 'mock' | 'harness' | 'oauth' | 'api' | 'claude-code' | 'codex' | 'copilot' | 'gemini-cli' | 'grok-build' | 'kimi-code' | 'opencode' | 'qwen-code' | (string & {});
745
+ /**
746
+ * The words a workflow file can ask of its route under
747
+ * `run.access.service_tier` (engine 0.124.2 and later). They are the
748
+ * language's words: a route's own value (`on`, `priority`) is never one.
749
+ * Known words aid completion without closing the set.
750
+ */
751
+ type NikaServiceTier = 'standard' | 'fast' | (string & {});
752
+ /**
753
+ * The access contract a workflow file declares under `run.access` and
754
+ * `run.reasoning`, as the engine records it: on the opening frame and on the
755
+ * terminal frame of each `infer:` or `agent:` task (the `access_requirement`
756
+ * row). A dimension the file does not declare is absent. An absent
757
+ * `service_tier` is not `standard`: the route keeps its own tier.
758
+ */
759
+ interface NikaAccessRequirement {
760
+ via?: string;
761
+ protocol?: 'api' | 'acp' | (string & {});
762
+ fallback?: 'none' | (string & {});
763
+ service_tier?: NikaServiceTier;
764
+ effort?: string;
765
+ [key: string]: unknown;
766
+ }
767
+ /** How a value the session read back was learned. Never a response attestation. */
768
+ type NikaConfiguredSource = 'session_config' | 'confirmed_selection' | 'accepted_request' | (string & {});
769
+ /**
770
+ * One dimension of a call's access selection (the model or the effort), with
771
+ * its facts kept apart: what the file asked, the option it travelled through,
772
+ * the exact value sent, and the value the route reported after the selection.
773
+ * `null` means not applicable or not observed, never a copied fact.
774
+ */
775
+ interface NikaSelectedValue {
776
+ requested: string | null;
777
+ option: string | null;
778
+ transmitted: string | null;
779
+ configured: string | null;
780
+ configured_source: NikaConfiguredSource | null;
781
+ [key: string]: unknown;
782
+ }
783
+ /**
784
+ * A fact only a witness can establish. `evidence` reads `unknown` exactly
785
+ * when `value` is `null`.
786
+ */
787
+ interface NikaAttestedValue {
788
+ value: string | null;
789
+ evidence: 'unknown' | (string & {});
790
+ [key: string]: unknown;
791
+ }
792
+ /**
793
+ * What one call's declared service tier became. Present on a selection only
794
+ * when the file declared a tier.
795
+ *
796
+ * `requested` is the file's word. `offered`, `transmitted` and `configured`
797
+ * are the route's own values (codex-acp: `off` and `on`). `turn` (the tier
798
+ * carried on the turn) and `effective` (the tier that served it) read
799
+ * `unknown` on an ACP session, which names neither: a configured value is
800
+ * not proof that a turn ran on that tier.
801
+ */
802
+ interface NikaServiceTierEvidence {
803
+ requested: NikaServiceTier | null;
804
+ option: string | null;
805
+ offered: string[] | null;
806
+ transmitted: string | null;
807
+ configured: string | null;
808
+ configured_source: NikaConfiguredSource | null;
809
+ turn: NikaAttestedValue;
810
+ effective: NikaAttestedValue;
811
+ [key: string]: unknown;
812
+ }
813
+ /**
814
+ * The access selection receipt of one `infer:` or `agent:` call
815
+ * (`nika/access-selection@1`), carried as the `access_selection` row of the
816
+ * task's terminal frame. Read it with `readNikaAccessSelection`.
817
+ */
818
+ interface NikaAccessSelection {
819
+ schema: 'nika/access-selection@1' | (string & {});
820
+ protocol: 'api' | 'acp' | (string & {}) | null;
821
+ model: NikaSelectedValue;
822
+ effort: NikaSelectedValue;
823
+ responder: {
824
+ model: string | null;
825
+ evidence: 'api_response' | 'cli_reported' | 'unknown' | (string & {});
826
+ [key: string]: unknown;
827
+ };
828
+ /** Only when the file declared `run.access.service_tier`. */
829
+ service_tier?: NikaServiceTierEvidence;
830
+ /** What the route moved during the turn (`model=<v>`, `effort=<v>`, `service_tier=<v>`). */
831
+ changed_mid_turn?: string[];
832
+ [key: string]: unknown;
833
+ }
834
+ interface NikaCheckOptions {
835
+ model?: string;
836
+ nativeStrict?: boolean;
837
+ /**
838
+ * Judge the access plan under this pin (`nika check --access`). On a local
839
+ * engine the report answers in `verdicts`: a pin the engine refuses keeps
840
+ * `clean: true` (the file holds) with `verdicts.access_ready: false`, and
841
+ * `verdicts.blockers` names the refusal. On a server the by-name request
842
+ * carries it as `CheckByName.access`; the server's check is source-only and
843
+ * evaluates no access plan, so it refuses only an empty or blank pin
844
+ * (`clean: false`, `error.code` `NIKA-1802`) and acknowledges any other.
845
+ * A local file checked through a server is a snapshot, which carries no
846
+ * pin: `access` is refused there (`NikaCompatibilityError`, capability
847
+ * `snapshotAccess`). Only a value neither door can carry unchanged (not a
848
+ * string, a NUL byte, a lone surrogate) is refused by the SDK, with
849
+ * `NikaConfigurationError`.
850
+ */
851
+ access?: NikaAccessPin;
852
+ /** Stops only this check request/process. */
853
+ signal?: AbortSignal;
854
+ }
855
+ interface NikaRunOptions {
856
+ /**
857
+ * Literal values for the workflow's declared `inputs:`, by name, with the
858
+ * same meaning on both transports. Values are strict JSON and stay literal:
859
+ * a string is never read as `@env:NAME`, an expression or a number, and
860
+ * nothing is coerced to the declared type. The engine validates the map
861
+ * (unknown key, type mismatch, missing required input) and refuses before
862
+ * any run exists. A value JSON cannot carry (`undefined`, a function, a
863
+ * symbol, a bigint, a non-finite number, a cycle, a class instance, a
864
+ * custom prototype, an array hole, an accessor, a Proxy) rejects `run()`
865
+ * with `NikaConfigurationError` instead of being dropped, and the
866
+ * serialized map is bounded at 1 MiB. No caller code runs while it is
867
+ * judged: no getter is invoked, and a Proxy is refused before it is read.
868
+ *
869
+ * Needs an engine that advertises the literal channel: `inputsLiteral`
870
+ * natively (values ride stdin, never argv), `jobInputs` over HTTP by served
871
+ * name. An engine without it rejects with `NikaCompatibilityError`; the SDK
872
+ * never falls back to `--var`. An execution snapshot freezes its inputs, so
873
+ * an HTTP run of a local path refuses `inputs`. Never put a secret here.
874
+ */
875
+ inputs?: Record<string, unknown>;
876
+ /**
877
+ * @deprecated Use `inputs`. `vars` is the native `--var KEY=VALUE` operator
878
+ * channel: the engine reads `@env:NAME` from its environment and coerces
879
+ * text to the declared type, so it cannot carry literal API values and has
880
+ * no HTTP form. Combining it with `inputs` rejects `run()`.
881
+ */
882
+ vars?: Record<string, string | number | boolean>;
883
+ model?: string;
884
+ /**
885
+ * Pin this run's access path, on both doors: `nika run --access=<pin>` on a
886
+ * local engine, `JobByName.access` on a server, which takes it with a
887
+ * workflow named by its served name (a snapshot of a local file carries no
888
+ * pin, and `run()` refuses `access` there with `NikaCompatibilityError`,
889
+ * capability `snapshotAccess`, before anything is captured or sent). A pin
890
+ * is a pin: the engine refuses one it does not know or that is retired
891
+ * (`NIKA-1802`), or one the workflow's model cannot use (`NIKA-1801`), and
892
+ * never substitutes another path or model. That refusal is the run's typed
893
+ * result: `run()` resolves, and `run.result()` settles `failed` with
894
+ * `result.error.code` (on a local engine `result.settlement.cause` is
895
+ * `refused` and `exitCode` is 3). A server refuses an empty or blank pin at
896
+ * admission instead: `run()` rejects with `NikaOperationError` (`code`
897
+ * `NIKA-1802`, `status` 422). Only a value neither door can carry unchanged
898
+ * (not a string, a NUL byte, a lone surrogate) is refused by the SDK, with
899
+ * `NikaConfigurationError`.
900
+ */
901
+ access?: NikaAccessPin;
902
+ maxCostUsd?: number;
903
+ /**
904
+ * Required for HTTP admission; reuse the same key and request after an
905
+ * uncertain response. Direct native runs reject this option.
906
+ */
907
+ idempotencyKey?: string;
908
+ }
909
+ /** One dependent offer of a session: its reasoning efforts or its service tiers. */
910
+ interface NikaAccessOfferListing {
911
+ /**
912
+ * `offered`: the session lists the option for the model. `not_offered`: it
913
+ * lists none. `unobserved`: not read, and `reason` says why (the model does
914
+ * not hold, the option is ambiguous or in another form, or no speed control
915
+ * is measured for this adapter release).
916
+ */
917
+ status: 'offered' | 'not_offered' | 'unobserved';
918
+ /** The session option's own id (codex-acp: `reasoning_effort`, `fast-mode`). */
919
+ option?: string;
920
+ /**
921
+ * The values, in the session's order. For efforts, the exact values a run
922
+ * accepts on `run.reasoning.effort` (no case folding, no alias); for
923
+ * service tiers, the language's words (`standard`, `fast`).
924
+ */
925
+ offered?: string[];
926
+ /** Listed values the server did not carry (beyond 64, or not a short token). */
927
+ omitted?: number;
928
+ /** The value the session holds now: what a run that declares none keeps on a session like this one. */
929
+ current?: string;
930
+ reason?: string;
931
+ }
932
+ /** What one session of a workflow's declared ACP route answered, without a prompt. */
933
+ interface NikaAccessOfferRoute {
934
+ /** The file's `run.access.via`. */
935
+ via: string;
936
+ protocol: 'acp';
937
+ /**
938
+ * `completion`: the route's one-shot completion profile, which `infer:`
939
+ * tasks run under. `agent`: its agent session, which `agent:` tasks run in.
940
+ */
941
+ profile: 'completion' | 'agent';
942
+ /** The tasks that resolve to this model in this shape. */
943
+ tasks: string[];
944
+ /**
945
+ * `observed`: the session answered. `unavailable`: it gave no offer; `code`
946
+ * and `reason` say why, as a run on the route would meet it before its prompt.
947
+ */
948
+ status: 'observed' | 'unavailable';
949
+ /** When this row was read (RFC 3339). The server serves it again until `fresh_until`. */
950
+ observed_at: string;
951
+ fresh_until: string;
952
+ /** With `unavailable`: `NIKA-1803`, `NIKA-1804` or `NIKA-1805`. */
953
+ code?: string;
954
+ reason?: string;
955
+ /** The adapter's own report on `initialize`. */
956
+ adapter?: {
957
+ name?: string;
958
+ version?: string;
959
+ };
960
+ model: {
961
+ /** The model as the file names it. */
962
+ requested: string;
963
+ /**
964
+ * `confirmed`: listed, selected for this session only and read back.
965
+ * `session_default`: the file names `default`. `legacy_list`: only the
966
+ * session's legacy model list names it. `not_offered`: the session does
967
+ * not list it. `not_confirmed`: listed, and the session answered another
968
+ * model. Efforts and tiers are read only under `confirmed` and
969
+ * `session_default`. Absent on an `unavailable` row.
970
+ */
971
+ status?: 'confirmed' | 'session_default' | 'legacy_list' | 'not_offered' | 'not_confirmed';
972
+ /** The native id the session holds, its own model, or the one it answered instead. */
973
+ current?: string;
974
+ /** The model values the session lists, in its order. */
975
+ offered?: string[];
976
+ omitted?: number;
977
+ };
978
+ effort?: NikaAccessOfferListing;
979
+ service_tier?: NikaAccessOfferListing;
980
+ }
981
+ /**
982
+ * `nika/access-offer@1`: what the sessions of a served workflow's own declared
983
+ * ACP route offer now, read by the server without a prompt. An observation
984
+ * with a time: it authorizes nothing, and a run still selects, reads back and
985
+ * refuses on its own session.
986
+ */
987
+ interface NikaAccessOffer {
988
+ schema: 'nika/access-offer@1';
989
+ workflow: string;
990
+ /**
991
+ * `read`: the routes were asked. `not_applicable`: the file selects no ACP
992
+ * sessions (no `run.access.via` under `run.access.protocol: acp`, or no
993
+ * `infer:`/`agent:` task with a static model); no session was opened and
994
+ * `reason` says why.
995
+ */
996
+ status: 'read' | 'not_applicable';
997
+ reason?: string;
998
+ /** The file's `run.access` and `run.reasoning.effort`, as the engine reads them. */
999
+ declared?: NikaAccessRequirement;
1000
+ /** Always 0: the server's door holds no prompt. */
1001
+ prompts_sent: 0;
1002
+ /** One row per session shape and model: completion rows first, then agent rows. At most eight. */
1003
+ routes: NikaAccessOfferRoute[];
1004
+ /** Sessions the workflow names beyond the eight one request reads. */
1005
+ routes_omitted: number;
1006
+ }
1007
+ interface NikaAccessOfferOptions {
1008
+ /** Stops this request. The server ends the session it was reading. */
1009
+ signal?: AbortSignal;
1010
+ /**
1011
+ * The whole call's deadline in milliseconds. Default 100 000: the server
1012
+ * bounds a request at 90 s, and a first reading opens one session per row.
1013
+ */
1014
+ timeoutMs?: number;
1015
+ }
1016
+ /** Resume observation of an already-admitted durable HTTP job. */
1017
+ interface NikaAttachRunOptions {
1018
+ /** Last SSE sequence durably consumed by the caller. Default: 0. */
1019
+ lastEventId?: number;
1020
+ }
1021
+ interface NikaEventsOptions {
1022
+ /** Stops this subscriber view. It never cancels the run. */
1023
+ signal?: AbortSignal;
1024
+ /**
1025
+ * Per-view queue bound, capped by the client eventBufferSize, which is also
1026
+ * its default. A live view that falls further behind than this fails with
1027
+ * `reason: 'live_backpressure'`; a view opened after more frames than this
1028
+ * is refused with `reason: 'replay_truncated'`. Neither skips a frame.
1029
+ */
1030
+ bufferSize?: number;
1031
+ }
1032
+ interface NikaTraceVerifyOptions {
1033
+ /** Stops only the verification request/process. */
1034
+ signal?: AbortSignal;
1035
+ }
1036
+ /** The SDK operations whose engine refusal can be returned as a typed error. */
1037
+ type NikaOperation = 'check' | 'run' | 'attachRun' | 'status' | 'cancel' | 'listWorkflows' | 'workflow' | 'accessOffer' | 'traceVerify' | 'schedule' | 'scheduleStatus' | 'compile' | 'artifacts' | 'downloadArtifact' | 'readArtifact';
1038
+ /** One engine-owned schedule finding. The vocabulary remains additive. */
1039
+ interface NikaScheduleFinding {
1040
+ code: string;
1041
+ detail: string;
1042
+ [key: string]: unknown;
1043
+ }
1044
+ /**
1045
+ * One engine-owned check finding, exactly as the engine's check report
1046
+ * carries it. `code` is absent when the engine's failure class names none (an
1047
+ * unreadable workflow file); the SDK never supplies one. The vocabulary
1048
+ * remains additive.
1049
+ */
1050
+ interface NikaCheckFinding {
1051
+ code?: string;
1052
+ message?: string;
1053
+ severity?: string;
1054
+ gate?: string;
1055
+ kind?: string;
1056
+ /** The task the finding judges, when it judges one. */
1057
+ task?: string;
1058
+ docs_url?: string;
1059
+ /**
1060
+ * The part of the workflow file the finding names, when it names one: byte
1061
+ * offsets into the file, `start` inclusive and `end` exclusive. From engine
1062
+ * 0.124 a parse refusal in a local check report carries one too. From
1063
+ * 0.124.1 the offsets count a leading byte-order mark; 0.124.0 counted
1064
+ * from the byte after it.
1065
+ */
1066
+ span?: NikaSourceSpan;
1067
+ [key: string]: unknown;
1068
+ }
1069
+ /** A byte range of a workflow file, as the engine's check findings name it. */
1070
+ interface NikaSourceSpan {
1071
+ /** The first byte, inclusive. */
1072
+ start: number;
1073
+ /** The byte after the last one. */
1074
+ end: number;
1075
+ }
1076
+ /**
1077
+ * Findings carried by the one operation-error taxonomy: a schedule refusal
1078
+ * carries schedule findings (`detail`), a refused `run()` carries the check
1079
+ * findings that refused it (`message`).
1080
+ */
1081
+ type NikaOperationFinding = NikaScheduleFinding | NikaCheckFinding;
1082
+ type NikaScheduleWhen = {
1083
+ kind: 'once';
1084
+ at: string;
1085
+ } | {
1086
+ kind: 'cadence';
1087
+ expression: string;
1088
+ };
1089
+ /** Exact declarative input accepted by PUT /v1/schedules/{id}. */
1090
+ interface NikaScheduleOptions {
1091
+ /** Stable path identity for the resident schedule. */
1092
+ id: string;
1093
+ when: NikaScheduleWhen;
1094
+ maxCostUsd: number;
1095
+ missed: 'catch-up' | 'catch-up-once' | 'skip';
1096
+ maxLatenessSeconds?: number;
1097
+ overlap?: 'skip' | 'queue' | 'replace';
1098
+ afterSkip?: 'next_slot' | 'on_completion';
1099
+ jitter?: 'hash';
1100
+ tolerance?: string;
1101
+ active?: boolean;
1102
+ pauseReason?: string;
1103
+ /** ISO calendar date (`YYYY-MM-DD`) required when active is false. */
1104
+ pauseUntil?: string;
1105
+ /** Exact prior revision for an update. Omit for create-if-absent. */
1106
+ revision?: string;
1107
+ }
1108
+ type NikaScheduleMissed = 'catch-up' | 'catch-up-once' | 'skip' | (string & {});
1109
+ type NikaScheduleOverlap = 'skip' | 'queue' | 'replace' | (string & {});
1110
+ type NikaScheduleAfterSkip = 'next_slot' | 'on_completion' | (string & {});
1111
+ /** The engine-normalized schedule definition; the SDK never normalizes it. */
1112
+ interface NikaScheduleDefinition {
1113
+ id: string;
1114
+ workflow: string;
1115
+ when: NikaScheduleWhen | {
1116
+ kind: string;
1117
+ [key: string]: unknown;
1118
+ };
1119
+ maxCostUsd: number;
1120
+ missed: NikaScheduleMissed;
1121
+ maxLatenessSeconds: number | null;
1122
+ overlap: NikaScheduleOverlap;
1123
+ afterSkip: NikaScheduleAfterSkip;
1124
+ jitter: 'hash' | (string & {}) | null;
1125
+ tolerance: string | null;
1126
+ active: boolean;
1127
+ pauseReason: string | null;
1128
+ pauseUntil: string | null;
1129
+ [key: string]: unknown;
1130
+ }
1131
+ interface NikaScheduleSlot {
1132
+ slotId: string;
1133
+ scheduledFor: string;
1134
+ requestedCivil: string | null;
1135
+ shift: 'exact' | 'advanced_first_valid' | 'folded_first' | (string & {});
1136
+ [key: string]: unknown;
1137
+ }
1138
+ type NikaScheduleDue = {
1139
+ kind: 'scheduled';
1140
+ slot: NikaScheduleSlot;
1141
+ } | {
1142
+ kind: 'catch_up';
1143
+ slot: NikaScheduleSlot;
1144
+ missedSlots: number;
1145
+ } | {
1146
+ kind: 'skipped_missed';
1147
+ slot: NikaScheduleSlot;
1148
+ missedSlots: number;
1149
+ } | {
1150
+ kind: 'skipped_too_late';
1151
+ slot: NikaScheduleSlot;
1152
+ latenessSeconds: number;
1153
+ maximumSeconds: number;
1154
+ } | {
1155
+ kind: 'paused';
1156
+ reason: string | null;
1157
+ pauseUntil: string | null;
1158
+ } | {
1159
+ kind: 'once_consumed';
1160
+ slotId: string;
1161
+ scheduledFor: string;
1162
+ } | {
1163
+ kind: 'not_due';
1164
+ } | {
1165
+ kind: string & {};
1166
+ [key: string]: unknown;
1167
+ };
1168
+ interface NikaSchedulePause {
1169
+ reason: string | null;
1170
+ until: string | null;
1171
+ }
1172
+ interface NikaScheduleClaim {
1173
+ runId: string;
1174
+ executionId: string;
1175
+ traceId: string;
1176
+ generation: string;
1177
+ [key: string]: unknown;
1178
+ }
1179
+ interface NikaScheduleLastDecision {
1180
+ action: 'claimed' | 'skipped' | (string & {});
1181
+ decision: 'scheduled' | 'catch_up' | (string & {});
1182
+ revision: string;
1183
+ slotId: string;
1184
+ scheduledFor: string;
1185
+ decidedAt: string;
1186
+ reason: string | null;
1187
+ claim: NikaScheduleClaim | null;
1188
+ [key: string]: unknown;
1189
+ }
1190
+ /** Fresh engine planning facts. The SDK transports them without interpretation. */
1191
+ interface NikaScheduleStatus {
1192
+ definition: NikaScheduleDefinition;
1193
+ origin: 'api' | (string & {});
1194
+ revision: string;
1195
+ active: boolean;
1196
+ pause: NikaSchedulePause | null;
1197
+ due?: NikaScheduleDue;
1198
+ finding?: NikaScheduleFinding;
1199
+ next: NikaScheduleSlot[];
1200
+ earliestWakeHint: string | null;
1201
+ lastDecision: NikaScheduleLastDecision | null;
1202
+ [key: string]: unknown;
1203
+ }
1204
+ /** Durable apply acknowledgement. It does not wait for a scheduled fire. */
1205
+ interface NikaScheduleApplyResult {
1206
+ applied: true;
1207
+ changed: boolean;
1208
+ status: NikaScheduleStatus;
1209
+ }
1210
+ /**
1211
+ * One stateless authoring request. Exactly one shape:
1212
+ *
1213
+ * - CREATE: `{ intent }` (or the bare-string shorthand), optionally with
1214
+ * `answers` to the engine's stable question keys.
1215
+ * - EDIT: `{ workflow, change }` — the accepted workflow's SOURCE plus the
1216
+ * change request — optionally with `answers`.
1217
+ *
1218
+ * The two shapes never mix, and there is no session: every call is a fresh
1219
+ * request carrying everything the engine needs. `nextCompileRequest()` builds
1220
+ * the request of an answer round from the previous request and its outcome.
1221
+ *
1222
+ * Who makes a provider call is explicit and per request, never ambient:
1223
+ * `cognition: 'explicitProvider'` over HTTP (the server's operator seated the
1224
+ * model), `authoringModel` on a local engine (the model you name). Without
1225
+ * either, compile is deterministic and contacts no provider.
1226
+ */
1227
+ type NikaCompileRequest = NikaCompileCreateRequest | NikaCompileEditRequest;
1228
+ /**
1229
+ * The cognition a compile request names (wire `cognition`, HTTP only):
1230
+ *
1231
+ * - `explicitProvider`: one fresh generation-2 round under the server's
1232
+ * seated authoring model (it may spend). Needs `compileNativeV2`. With a
1233
+ * kept round's `replay_token` it is that round's judged answer round: the
1234
+ * kept plan replayed with the answers, the seat asked only to judge the
1235
+ * replayed bytes (judge calls, never an authoring call); needs a server
1236
+ * whose `/health` lists `compileJudgedAnswerRound` (engine 0.123.0 when
1237
+ * its operator seats a model with `nika serve --authoring-model`).
1238
+ * - `deterministicOnly`: with `replay_token`, a zero-call generation-2 replay
1239
+ * of a round the server kept (no judge); without it, the generation-1 door
1240
+ * with its explicit (and only) cognition word.
1241
+ */
1242
+ type NikaCompileRequestCognition = 'explicitProvider' | 'deterministicOnly';
1243
+ /** How `nextCompileRequest()` builds the next round of a kept round. */
1244
+ interface NikaNextCompileOptions {
1245
+ /**
1246
+ * The cognition of the next round when it answers a kept round (a
1247
+ * `replay_token` came back, or the previous request carried one):
1248
+ * `explicitProvider` is its judged answer round (the server's seat judges
1249
+ * the replayed bytes: judge calls, no authoring call, it may spend);
1250
+ * `deterministicOnly` is its zero-call replay (no call, no judge, so a
1251
+ * model-authored candidate stays a preview). By default, after an
1252
+ * `explicitProvider` round: the judged answer round where the server serves
1253
+ * it (`outcome.judged_answer_round_available`), else a new fresh round
1254
+ * carrying the answers (it may spend); after a zero-call replay: another
1255
+ * one. Refused when no kept round is involved.
1256
+ */
1257
+ cognition?: NikaCompileRequestCognition;
1258
+ }
1259
+ /**
1260
+ * The caller's narrowing of one provider round's bounds (wire `limits`). Over
1261
+ * HTTP each value may only narrow the operator's bound (above it the server
1262
+ * answers 422 `compile_limit`, never a clamp); on a local engine the values
1263
+ * become the `--authoring-*` flags. Integers only.
1264
+ */
1265
+ interface NikaCompileLimits {
1266
+ /** Physical requests and model invocations of the round, 1–4294967295 (`--authoring-max-calls`). */
1267
+ max_calls?: number;
1268
+ /** Repair rounds, 0–4294967295; zero disables repairs (`--authoring-repairs`). */
1269
+ repairs?: number;
1270
+ /** Output tokens per completion, 1–4294967295 (`--authoring-max-tokens`). */
1271
+ max_tokens?: number;
1272
+ /**
1273
+ * The wait for one model invocation, in milliseconds (≥ 1). A local engine
1274
+ * takes whole seconds (`--authoring-timeout`), so a value that is not a
1275
+ * multiple of 1000 is refused there.
1276
+ */
1277
+ call_timeout_ms?: number;
1278
+ /**
1279
+ * The whole round's deadline, in milliseconds (≥ 1), absolute from the
1280
+ * server's admission; past it the server answers 408
1281
+ * `compile_deadline_exceeded`. Without it (and without an operator
1282
+ * deadline) nothing bounds the round on the server. The client then waits
1283
+ * for it plus the server's 5 s handoff and one `requestTimeout`, unless
1284
+ * `timeoutMs` says otherwise. HTTP only: the local engine has no such flag.
1285
+ */
1286
+ deadline_ms?: number;
1287
+ }
1288
+ /** Fields both request shapes may carry. */
1289
+ interface NikaCompileRequestFields {
1290
+ /**
1291
+ * Answers to engine questions, by stable question key (`const.request`),
1292
+ * as strict JSON values — never pre-serialized text. Natively each value is
1293
+ * serialized exactly once onto the argv `--answer=KEY=JSON` channel; over
1294
+ * HTTP it rides `answers` with its type preserved. A value JSON cannot
1295
+ * carry refuses with `NikaConfigurationError` before any spawn or request.
1296
+ */
1297
+ answers?: Record<string, unknown>;
1298
+ /** HTTP only: the wire's cognition word (see `NikaCompileRequestCognition`). */
1299
+ cognition?: NikaCompileRequestCognition;
1300
+ /**
1301
+ * The bounds of a provider round: over HTTP with `cognition:
1302
+ * 'explicitProvider'` (a fresh round or a judged answer round), natively with
1303
+ * `authoringModel`. A zero-call replay (`deterministicOnly`) refuses limits.
1304
+ */
1305
+ limits?: NikaCompileLimits;
1306
+ /**
1307
+ * HTTP only: the `Nika-Compile-Replay` token a round of the same server run
1308
+ * answered (`outcome.replay_token`), sent with the round's exact input: with
1309
+ * `cognition: 'explicitProvider'` it is the judged answer round, with
1310
+ * `'deterministicOnly'` the zero-call replay. A held judged round forgets it.
1311
+ * Not an execution grant.
1312
+ */
1313
+ replay_token?: string;
1314
+ /**
1315
+ * Local engine only (`--authoring-model provider/name`): the model that
1316
+ * interprets free intent. Its key comes from the engine's environment,
1317
+ * never from the SDK. Over HTTP the server's operator seats the model.
1318
+ */
1319
+ authoringModel?: string;
1320
+ /**
1321
+ * Local engine only (`--output`): where the engine writes a READY
1322
+ * candidate, atomically; relative paths resolve against the client's
1323
+ * `cwd`. The engine never writes anything that is not ready. The outcome
1324
+ * then carries `written` (and `existing_destination` when a file was left
1325
+ * in place).
1326
+ */
1327
+ output?: string;
1328
+ }
1329
+ interface NikaCompileCreateRequest extends NikaCompileRequestFields {
1330
+ /** Intent text, or an exact embedded skeleton name (`hello`, `chain`…). */
1331
+ intent: string;
1332
+ /** HTTP only (wire `workflow_id`): names the created workflow. */
1333
+ workflow_id?: string;
1334
+ /**
1335
+ * Local engine only (`--decision-model`): one bounded-decision seat
1336
+ * (`typesafe/<jev>` or `provider/name`) for finite ambiguities. Create only.
1337
+ */
1338
+ decisionModel?: string;
1339
+ /**
1340
+ * Local engine only (`--fresh`): ignore the plan an earlier round recorded
1341
+ * for this intent under `.nika/compile/` and read or sample it again.
1342
+ * Create only. `nextCompileRequest()` drops it so an answer round replays.
1343
+ */
1344
+ fresh?: boolean;
1345
+ workflow?: never;
1346
+ change?: never;
1347
+ original_intent?: never;
1348
+ }
1349
+ interface NikaCompileEditRequest extends NikaCompileRequestFields {
1350
+ /** The accepted workflow's exact source bytes (as a string). */
1351
+ workflow: string;
1352
+ /**
1353
+ * The requested change: free text in the engine's supported edit
1354
+ * vocabulary, or one structured constant edit mirroring the engine's
1355
+ * `set_constant` operation. The value is a strict JSON value, judged by
1356
+ * the same law as `answers`.
1357
+ */
1358
+ change: string | NikaCompileSetConstant;
1359
+ /**
1360
+ * The request the base answered (wire `original_intent`; natively the
1361
+ * intent positional beside `--base`). A text change is read against it.
1362
+ * Required with a text change on an HTTP generation-2 round, absent from
1363
+ * the generation-1 wire, refused beside `set_constant`.
1364
+ */
1365
+ original_intent?: string;
1366
+ intent?: never;
1367
+ workflow_id?: never;
1368
+ decisionModel?: never;
1369
+ fresh?: never;
1370
+ }
1371
+ /** One structured constant edit, mirroring the engine's `set_constant`. */
1372
+ interface NikaCompileSetConstant {
1373
+ set_constant: {
1374
+ /** Bare constant name (no `const.` prefix, no path). */
1375
+ name: string;
1376
+ /** The new literal, as a strict JSON value. */
1377
+ value: unknown;
1378
+ };
1379
+ }
1380
+ interface NikaCompileOptions {
1381
+ /**
1382
+ * Aborts this authoring request or process only. Compile owns no Run: this
1383
+ * never touches `run.cancel()` semantics (client#126). Stopping an HTTP
1384
+ * provider round stops this client's wait, not the server's round or its
1385
+ * spend.
1386
+ */
1387
+ signal?: AbortSignal;
1388
+ /**
1389
+ * Positive integer milliseconds before the compile child or HTTP request is
1390
+ * stopped. Without it, an HTTP generation-1 request or replay is bounded by
1391
+ * the client's `requestTimeout`; an `explicitProvider` round by its
1392
+ * `limits.deadline_ms` plus the server's handoff and one `requestTimeout`,
1393
+ * or, without that limit, by nothing the SDK sets (Node's built-in fetch
1394
+ * still stops waiting for response headers after 300 s by default); a local
1395
+ * compile by `signal` alone.
1396
+ */
1397
+ timeoutMs?: number;
1398
+ /**
1399
+ * Over HTTP, whether a generation-2 request (a provider round, a kept
1400
+ * round's judged answer round or its replay) carries what the local engine
1401
+ * observes of the files the request states (`nika compile --observe-only`
1402
+ * in the client's `cwd`: headers, key sets, short categorical values and
1403
+ * kind counts, never a row) as `observed_world`, so the server's seat, its
1404
+ * grounding law and its judge read the real shape instead of asking for it.
1405
+ * Default: sent whenever the server lists `compileObservedWorld`; `true`
1406
+ * requires it (a server without it is a typed gap); `false` sends none. A
1407
+ * kept round's later requests must observe the same files: another
1408
+ * observation is another input (`409 compile_replay_input_changed`). Where
1409
+ * the server also lists `compileTrialInputs`, the text of the files the
1410
+ * observation read rides as `trial_inputs`, and the server tries each final
1411
+ * candidate on them before it can be ready. A local compile always observes
1412
+ * (and tries) its own working directory; this has no effect there.
1413
+ */
1414
+ observe?: boolean;
1415
+ }
1416
+ /** The engine's own completeness words; `ready` is never derived from confidence. */
1417
+ type NikaCompileStatus = 'ready' | 'incomplete' | 'refused';
1418
+ /** One admissible answer of a `choice` question, spelled by the owning grammar. */
1419
+ interface NikaCompileQuestionOption {
1420
+ key: string;
1421
+ label: string;
1422
+ [key: string]: unknown;
1423
+ }
1424
+ /** One authoring question, exactly as the engine emitted it. */
1425
+ interface NikaCompileQuestion {
1426
+ /** Stable semantic hole path (`const.request`), never a session id. */
1427
+ key: string;
1428
+ label: string;
1429
+ /**
1430
+ * `text`: a JSON string · `literal`: one JSON value · `choice`: a JSON
1431
+ * string that is the `key` of one of `options`.
1432
+ */
1433
+ type: 'text' | 'literal' | 'choice';
1434
+ why: string;
1435
+ /**
1436
+ * `false`: the value belongs to a binding outside the program (a
1437
+ * schedule's timezone, missed-run and overlap policies, per-run ceiling)
1438
+ * and never blocks a ready candidate.
1439
+ */
1440
+ mandatory: boolean;
1441
+ /** Present on a `choice` question only. */
1442
+ options?: NikaCompileQuestionOption[];
1443
+ [key: string]: unknown;
1444
+ }
1445
+ /**
1446
+ * One structured authoring finding, exactly as the engine emitted it.
1447
+ * Compiler targets include `semantic_verification`, `verify_held` (the
1448
+ * verifier did not accept the candidate: it is a preview, see
1449
+ * `isNikaCompileHeld`) and `verify_resume` (no admitted judgment was made:
1450
+ * the candidate is withdrawn and the round's record kept).
1451
+ */
1452
+ interface NikaCompileDiagnostic {
1453
+ kind: 'applied' | 'missed' | 'unknown' | 'requiresHuman' | 'refused';
1454
+ target: string;
1455
+ /** For a reader; never parsed to recover compiler state. */
1456
+ message: string;
1457
+ [key: string]: unknown;
1458
+ }
1459
+ /**
1460
+ * The authoring cognition the engine records in provenance:
1461
+ * `explicitDecision` is a bounded decision seat (local `decisionModel`).
1462
+ */
1463
+ type NikaCompileCognition = 'deterministicOnly' | 'explicitProvider' | 'explicitDecision';
1464
+ /** The internal strategy that settled the request: observational, never authority. */
1465
+ type NikaCompileStrategy = 'skeleton' | 'support' | 'hot' | 'warm' | 'cold' | 'native' | (string & {});
1466
+ /**
1467
+ * The receipt of a round's provider calls (`provenance.authoring`, present
1468
+ * exactly on a `compile_version: 2` outcome). It is never workflow authority
1469
+ * or run evidence, and token usage is not an invoice.
1470
+ */
1471
+ interface NikaCompileAuthoringReceipt {
1472
+ /** The seated authoring model (`provider/name`). */
1473
+ model: string;
1474
+ /** LOGICAL calls of the round. */
1475
+ calls: number;
1476
+ /** Sum of reported counters; `null` when no call reported both counters. */
1477
+ input_tokens: number | null;
1478
+ output_tokens: number | null;
1479
+ elapsed_ms: number;
1480
+ sampling: Record<string, unknown>;
1481
+ /** What each logical call received, in call order. */
1482
+ context: Record<string, unknown>[];
1483
+ /** Provider, model identities, request authority and usage completeness. */
1484
+ backend: Record<string, unknown> | null;
1485
+ [key: string]: unknown;
1486
+ }
1487
+ /** Authoring provenance — not program identity (#1664), not execution Proof. */
1488
+ interface NikaCompileProvenance {
1489
+ compiler_version: string;
1490
+ spec_pin: string;
1491
+ skeleton: string | null;
1492
+ cognition: NikaCompileCognition;
1493
+ /** The strategy that settled a free intent, when one was engaged. */
1494
+ strategy?: NikaCompileStrategy;
1495
+ /** A file name for the candidate, never a path the compiler touched. */
1496
+ suggested_file?: string | null;
1497
+ /** The plan record the round produced; a server keeps it behind its replay token. */
1498
+ plan?: Record<string, unknown>;
1499
+ /** Bounded decision records, `semantic_verification` attempts included. */
1500
+ decision?: Record<string, unknown>;
1501
+ /** The provider-call receipt: present exactly when `compile_version` is 2. */
1502
+ authoring?: NikaCompileAuthoringReceipt;
1503
+ [key: string]: unknown;
1504
+ }
1505
+ /** The candidate's pure Check judgment, with its deliberately limited scope. */
1506
+ interface NikaCompilePreview {
1507
+ /** `sourceOnly` in this foundation: no environment or admission claim. */
1508
+ scope: 'sourceOnly';
1509
+ report: NikaCheckResult;
1510
+ [key: string]: unknown;
1511
+ }
1512
+ /**
1513
+ * The trigger the request names, stated beside the candidate whose bytes
1514
+ * carry no cadence, host or event: a requirement an operator binds through
1515
+ * the schedule contract, never a grant or a schedule row.
1516
+ */
1517
+ interface NikaCompileTrigger {
1518
+ kind: 'manual' | 'schedule' | 'webhook' | 'event' | (string & {});
1519
+ status: 'satisfied' | 'requires_binding' | 'unsupported' | (string & {});
1520
+ source_hint?: string | null;
1521
+ event_hint?: string | null;
1522
+ cadence?: string | null;
1523
+ /** The exact five-field projection when supported; older engines omit it. */
1524
+ cron?: string | null;
1525
+ at?: string | null;
1526
+ payload_input?: string | null;
1527
+ timezone?: string | null;
1528
+ missed?: string | null;
1529
+ overlap?: string | null;
1530
+ ceiling?: string | null;
1531
+ [key: string]: unknown;
1532
+ }
1533
+ /** A local engine's failure to keep or remove one of its `.nika/compile/` records. */
1534
+ interface NikaCompileRecordError {
1535
+ path: string;
1536
+ message: string;
1537
+ [key: string]: unknown;
1538
+ }
1539
+ /**
1540
+ * The machine codes a compile refusal carries on `NikaOperationError.code`.
1541
+ * HTTP (`POST /v1/compile`): `unauthorized` (401) · `request_timeout`,
1542
+ * `compile_deadline_exceeded` (408) · `compile_replay_unavailable`,
1543
+ * `compile_replay_input_changed`, `compile_context_changed` (409) ·
1544
+ * `body_too_large` (413) · `unsupported_media_type`,
1545
+ * `unsupported_content_encoding` (415) · `malformed_compile_request`,
1546
+ * `compile_version_unsupported`, `compile_mode_unsupported`,
1547
+ * `compile_cognition_unsupported`, `compile_limit`,
1548
+ * `compile_new_intent_required` (422) · `internal_error`,
1549
+ * `compile_disclosure_refused` (500) · `compile_busy`,
1550
+ * `compile_replay_capacity`, `stopping` (503). Local engine (exit 2 or 3):
1551
+ * `destination_name`, `invalid_answer`, `authoring_authority`, `read_base`,
1552
+ * `knowledge`, `authoring_config`, `compile_error`, `destination`. The
1553
+ * vocabulary is the engine's and stays open.
1554
+ */
1555
+ type NikaCompileRefusalCode = 'unauthorized' | 'request_timeout' | 'compile_deadline_exceeded' | 'compile_replay_unavailable' | 'compile_replay_input_changed' | 'compile_context_changed' | 'body_too_large' | 'unsupported_media_type' | 'unsupported_content_encoding' | 'malformed_compile_request' | 'compile_version_unsupported' | 'compile_mode_unsupported' | 'compile_cognition_unsupported' | 'compile_limit' | 'compile_new_intent_required' | 'internal_error' | 'compile_disclosure_refused' | 'compile_busy' | 'compile_replay_capacity' | 'stopping' | 'destination_name' | 'invalid_answer' | 'authoring_authority' | 'read_base' | 'knowledge' | 'authoring_config' | 'compile_error' | 'destination' | (string & {});
1556
+ /**
1557
+ * The reviewable authoring result. `candidate` is ordinary `.nika`
1558
+ * SOURCE in memory — it is not a `Workflow` handle, and `run()` does not
1559
+ * accept raw source: the caller materializes the candidate and `run(path)`
1560
+ * re-admits it. The engine never executes it.
1561
+ *
1562
+ * A candidate is proposed only when `status` is `ready`. Under `incomplete`
1563
+ * a non-null `candidate` is a preview: it may still carry holes, or the
1564
+ * verifier held it (`isNikaCompileHeld(outcome)`); a preview is never to be
1565
+ * run or saved as an accepted result.
1566
+ *
1567
+ * `incomplete` and `refused` are data, not exceptions: the SDK throws only
1568
+ * on transport, protocol, compatibility and engine-stamped failures.
1569
+ */
1570
+ interface NikaCompileOutcome {
1571
+ /**
1572
+ * The wire generation of this payload: 2 exactly when a provider call
1573
+ * happened (`provenance.authoring` is its receipt), 1 otherwise — a
1574
+ * skeleton, a structured constant, a replay and every deterministic round.
1575
+ */
1576
+ compile_version: 1 | 2;
1577
+ status: NikaCompileStatus;
1578
+ /** Exactly `status === 'ready'` — the engine's word, not a client judgment. */
1579
+ ready: boolean;
1580
+ /** The candidate source; may still carry unfilled holes when not ready. */
1581
+ candidate: string | null;
1582
+ questions: NikaCompileQuestion[];
1583
+ diagnostics: NikaCompileDiagnostic[];
1584
+ /** The boundary the candidate requests (from its pure report); never a grant. */
1585
+ requested_boundary: Record<string, unknown> | null;
1586
+ /** The trigger the request names; absent on engines before the field (0.120.x). */
1587
+ requested_trigger?: NikaCompileTrigger | null;
1588
+ check_preview: NikaCompilePreview | null;
1589
+ provenance: NikaCompileProvenance;
1590
+ /**
1591
+ * HTTP only: the `Nika-Compile-Replay` header of a provider round that left
1592
+ * a native plan the server keeps. Send it back with the round's exact input
1593
+ * (see `nextCompileRequest`): `cognition: 'explicitProvider'` for its judged
1594
+ * answer round, `'deterministicOnly'` for its zero-call replay. It is valid
1595
+ * only on that server run, until a judged round holds its candidate; do not
1596
+ * log it.
1597
+ */
1598
+ replay_token?: string;
1599
+ /**
1600
+ * HTTP only, beside a kept round (this outcome carries a `replay_token`, or
1601
+ * its request answered one): whether the server that answered serves that
1602
+ * round's judged answer round, as its `/health` lists
1603
+ * `compileJudgedAnswerRound`. An SDK fact, not part of the engine's
1604
+ * document; `nextCompileRequest()` reads it.
1605
+ */
1606
+ judged_answer_round_available?: boolean;
1607
+ /**
1608
+ * Local engine only, and only when the request named `output`: the
1609
+ * destination the engine wrote (`null` when nothing was written).
1610
+ */
1611
+ written?: string | null;
1612
+ /** Local engine only: the named `output` that already existed and was left untouched. */
1613
+ existing_destination?: string;
1614
+ /** Local engine only: the plan record under `.nika/compile/` could not be kept or removed. */
1615
+ plan_record_error?: NikaCompileRecordError;
1616
+ /** Local engine only: this round's rejections could not be kept under `.nika/compile/`. */
1617
+ declined_record_error?: NikaCompileRecordError;
1618
+ }
1619
+
1620
+ declare class NikaError extends Error {
1621
+ constructor(message: string, options?: ErrorOptions);
1622
+ }
1623
+ declare class NikaConfigurationError extends NikaError {
1624
+ constructor(message: string);
1625
+ }
1626
+ declare class NikaTransportError extends NikaError {
1627
+ readonly transport: NikaTransportKind;
1628
+ constructor(transport: NikaTransportKind, message: string, options?: ErrorOptions);
1629
+ }
1630
+ /** A typed engine/adapter capability gap, not a workflow failure. */
1631
+ declare class NikaCompatibilityError extends NikaError {
1632
+ readonly capability: string;
1633
+ readonly transport: NikaTransportKind;
1634
+ constructor(capability: string, transport: NikaTransportKind, message: string);
1635
+ }
1636
+ declare class NikaProtocolError extends NikaTransportError {
1637
+ constructor(transport: NikaTransportKind, message: string, options?: ErrorOptions);
1638
+ }
1639
+ /**
1640
+ * Observation broke before terminal settlement and the final durable read
1641
+ * stayed non-terminal. The cursor feeds attachRun(id, { lastEventId }).
1642
+ *
1643
+ * This is about the client's view, never about the run: the run may still be
1644
+ * running on the resident. It is not the engine's own `interrupted` state,
1645
+ * which arrives as a `run.interrupted` event and as `result.status`.
1646
+ */
1647
+ declare class NikaObservationInterrupted extends NikaTransportError {
1648
+ readonly runId: string;
1649
+ readonly lastSequence: number;
1650
+ readonly attempts: number;
1651
+ constructor(transport: NikaTransportKind, runId: string, lastSequence: number, attempts: number);
1652
+ }
1653
+ /** One taxonomy for engine refusals returned by an SDK operation. */
1654
+ declare class NikaOperationError extends NikaError {
1655
+ readonly operation: NikaOperation;
1656
+ readonly code: string;
1657
+ readonly transport: NikaTransportKind;
1658
+ readonly status: number;
1659
+ readonly findings?: readonly NikaOperationFinding[];
1660
+ readonly currentRevision?: string | null;
1661
+ readonly machineCode?: string;
1662
+ constructor(operation: NikaOperation, transport: NikaTransportKind, code: string, message: string, details: {
1663
+ status: number;
1664
+ findings?: readonly NikaOperationFinding[];
1665
+ currentRevision?: string | null;
1666
+ machineCode?: string;
1667
+ });
1668
+ }
1669
+ /**
1670
+ * An event view would have had to skip frames, so it refused instead. The SDK
1671
+ * never silently omits a frame. Two different bounds can be exceeded, and
1672
+ * `reason` says which. Neither is about the run: it keeps running or stays
1673
+ * settled, and `run.result()` is unaffected.
1674
+ *
1675
+ * - `live_backpressure`: a view that was observing live fell more than
1676
+ * `limit` frames behind the stream. Read faster, or give it a larger
1677
+ * `bufferSize`. Other views are unaffected.
1678
+ * - `replay_truncated`: a view was opened after the run had already produced
1679
+ * more frames than it can be given. `observed` is how many the session saw
1680
+ * and `retained` how many it still holds. When `retained === observed`
1681
+ * nothing is lost and a view with `bufferSize >= observed` replays them
1682
+ * all; when `retained < observed` the earlier frames are gone from this
1683
+ * process, so raise `eventBufferSize` to at least `observed` for the next
1684
+ * run, or observe it live.
1685
+ */
1686
+ declare class NikaEventBufferOverflowError extends NikaError {
1687
+ readonly runId: string;
1688
+ /** The bound that was exceeded: the view's `bufferSize`. */
1689
+ readonly limit: number;
1690
+ readonly reason: 'live_backpressure' | 'replay_truncated';
1691
+ /** `replay_truncated` only: frames the session had observed when it refused. */
1692
+ readonly observed?: number;
1693
+ /** `replay_truncated` only: frames the session still held when it refused. */
1694
+ readonly retained?: number;
1695
+ constructor(runId: string, limit: number, replay?: {
1696
+ observed: number;
1697
+ retained: number;
1698
+ });
1699
+ }
1700
+ declare class NikaRunOwnershipError extends NikaError {
1701
+ constructor();
1702
+ }
1703
+
1704
+ /** The local engine could not be resolved without an implicit PATH lookup. */
1705
+ declare class NikaEngineUnavailable extends NikaError {
1706
+ readonly code = "NIKA_ENGINE_UNAVAILABLE";
1707
+ readonly platform: string;
1708
+ readonly arch: string;
1709
+ readonly packageName?: string;
1710
+ constructor(platform: string, arch: string, packageName?: string);
1711
+ }
1712
+
1713
+ /**
1714
+ * Narrows a result to the engine's successful settlement. Admitted failures
1715
+ * resolve as result data; awaiting a run alone does not establish success.
1716
+ * Paused, cancelled, interrupted, failed, and unknown statuses return false.
1717
+ * Outputs remain optional: a successful workflow need not declare any.
1718
+ */
1719
+ declare function isNikaRunSucceeded<Outputs extends Record<string, unknown> = Record<string, unknown>>(result: NikaRunResult<Outputs>): result is NikaRunResult<Outputs> & {
1720
+ status: 'succeeded';
1721
+ };
1722
+
1723
+ /**
1724
+ * Whether the verifier held this outcome's candidate: it answered on these
1725
+ * bytes against the request and did not accept them (the engine's `applied`
1726
+ * diagnostic targeting `verify_held`). Such an outcome is `incomplete` and its
1727
+ * `candidate` is a preview to show at most — never run it or save it as an
1728
+ * accepted result. A server keeps no replay token for it and forgets the token
1729
+ * of a held judged answer round, so asking again is a fresh round.
1730
+ */
1731
+ declare function isNikaCompileHeld(outcome: NikaCompileOutcome): boolean;
1732
+ /**
1733
+ * The request of the next round of a compile: the same input with these
1734
+ * answers added to the previous ones (a later answer to the same key wins).
1735
+ * It maps; it judges nothing.
1736
+ *
1737
+ * - **A kept round** (HTTP): when `outcome` carries a `replay_token`, or the
1738
+ * previous request already answered a kept round with one, the next request
1739
+ * answers that round by its token with the exact input and the merged
1740
+ * answers. After an `explicitProvider` round, on a server that serves it
1741
+ * (`outcome.judged_answer_round_available`, its `/health` capability
1742
+ * `compileJudgedAnswerRound`), it is the judged answer round:
1743
+ * `cognition: 'explicitProvider'`, the token and the previous `limits`; the
1744
+ * server replays the kept plan with the answers and its seat only judges the
1745
+ * replayed bytes (judge calls, never an authoring call), answering `ready`
1746
+ * or holding the candidate. On a server without it, the next request is a
1747
+ * new fresh round carrying the answers (no token): the one round there that
1748
+ * can judge them, which authors again and may spend. With `{ cognition:
1749
+ * 'deterministicOnly' }` it is the zero-call replay instead: no `limits`, no
1750
+ * call, no judge, so a model-authored candidate comes back `incomplete` with
1751
+ * its judgment pending. A previous zero-call replay stays one unless you
1752
+ * pass `{ cognition: 'explicitProvider' }`, which asks for the judged round
1753
+ * whatever the server advertised (the client refuses it before posting
1754
+ * where the capability is missing).
1755
+ * - **No kept round**: the previous request is repeated with the merged
1756
+ * answers. A local engine replays the plan it recorded under
1757
+ * `.nika/compile/` in its working directory when the round carries at least
1758
+ * one answer (so `fresh` is dropped), and its seat's judge may decide it; a
1759
+ * local round with no answer reads the intent again. An HTTP
1760
+ * `explicitProvider` request without a token is a new fresh round: it may
1761
+ * spend again. A deterministic request is stateless.
1762
+ *
1763
+ * A held outcome (`isNikaCompileHeld`) has no next round: the server forgot
1764
+ * the token of a held judged round (a request with it answers 409
1765
+ * `compile_replay_unavailable`), and asking again would author anew. That is
1766
+ * refused here; author a new request if you mean to, or stop. A loop over
1767
+ * rounds should also stop when a round brings no new answer. An
1768
+ * `intent.clarification` answer replaces the request: a server refuses it as
1769
+ * an answer (`compile_new_intent_required`, `compile_replay_input_changed`);
1770
+ * start a new create request with the replacement intent instead.
1771
+ */
1772
+ declare function nextCompileRequest(previous: string | NikaCompileRequest, outcome: NikaCompileOutcome, answers: Record<string, unknown>, options?: NikaNextCompileOptions): NikaCompileRequest;
1773
+
1774
+ /**
1775
+ * Narrows any run event to the terminal settlement frame, which carries the
1776
+ * run's status, outputs, and receipt together. Both transports have one: the
1777
+ * native process emits `run_settled`, `nika serve` emits `execution.settled`.
1778
+ * Kind equality alone cannot exclude the forward-compatibility variant; this
1779
+ * guard can.
1780
+ */
1781
+ declare function isNikaRunSettledEvent<Outputs extends Record<string, unknown> = Record<string, unknown>>(event: NikaEvent<Outputs>): event is NikaRunSettledEvent<Outputs> | NikaExecutionSettledEvent<Outputs>;
1782
+ /**
1783
+ * Narrows any run event to a terminal one by the status the engine reported,
1784
+ * not by its kind, so it holds on either transport and across kinds this SDK
1785
+ * version does not know yet. It therefore also covers the frames that end a
1786
+ * run without settling outputs: `execution.cancelled`, `execution.refused`,
1787
+ * `interrupted`, `workflow_failed` and `workflow_cancelled` (the engine's
1788
+ * four run terminals are `workflow_completed` · `workflow_failed` ·
1789
+ * `workflow_paused` · `workflow_cancelled` · ADR-128).
1790
+ */
1791
+ declare function isNikaTerminalEvent<Outputs extends Record<string, unknown> = Record<string, unknown>>(event: NikaEvent<Outputs>): event is NikaEvent<Outputs> & {
1792
+ status: 'succeeded' | 'failed' | 'interrupted' | 'cancelled';
1793
+ };
1794
+ /** Narrows any run event to the frame that sealed the run's trace chain. */
1795
+ declare function isNikaRunSealedEvent<Outputs extends Record<string, unknown> = Record<string, unknown>>(event: NikaEvent<Outputs>): event is NikaRunSealedEvent;
1796
+ /**
1797
+ * Reads the access selection receipt of one `infer:` or `agent:` call from
1798
+ * the task's terminal frame (`task_completed`, or the failed or cancelled
1799
+ * frame of a task that reached its route): what the workflow asked, what the
1800
+ * engine sent and what the route read back, for the model, the effort and,
1801
+ * when the file declares one, the service tier.
1802
+ *
1803
+ * Returns `undefined` when the frame carries no receipt: a task that called
1804
+ * no model, a file that declares no access contract, or a run on `nika
1805
+ * serve`, which keeps these rows in the sealed journal and projects none of
1806
+ * them. A receipt that is present and malformed throws `NikaProtocolError`.
1807
+ * Accepts an engine frame (`run.events()`) or the stable event that wraps it.
1808
+ */
1809
+ declare function readNikaAccessSelection(event: NikaEvent | NikaRunEvent): NikaAccessSelection | undefined;
1810
+ /**
1811
+ * Reads the access contract the workflow file declared (`run.access`,
1812
+ * `run.reasoning`) from the opening frame or from a task's terminal frame.
1813
+ * Returns `undefined` when the frame carries none, which is every frame of a
1814
+ * file that declares no contract and every frame from `nika serve`.
1815
+ */
1816
+ declare function readNikaAccessRequirement(event: NikaEvent | NikaRunEvent): NikaAccessRequirement | undefined;
1817
+
1818
+ /** One client surface for a local engine process or a live nika serve URL. */
1819
+ declare class Nika {
1820
+ readonly transportKind: NikaTransportKind;
1821
+ private readonly transport;
1822
+ private readonly sessions;
1823
+ private readonly eventBufferSize;
1824
+ constructor(config?: NikaConfig);
1825
+ check(workflow: string, options?: NikaCheckOptions): Promise<NikaCheckResult>;
1826
+ /**
1827
+ * Authoring (issue #128): describe work — or name an accepted workflow plus
1828
+ * a change — and get the engine's checked candidate back, without running
1829
+ * anything. `compile()` never means `run()`: the outcome is data (candidate
1830
+ * source, questions, diagnostics, requested boundary and trigger,
1831
+ * source-only Check preview, provenance), `incomplete`/`refused` resolve
1832
+ * instead of throwing, and no workflow effect, approval or Proof exists.
1833
+ *
1834
+ * A provider call happens only when the request opts in: `cognition:
1835
+ * 'explicitProvider'` over `{ url }` (the server's seated model, generation
1836
+ * 2, capability `compileNativeV2`) or `authoringModel` on a local engine.
1837
+ * Answer the outcome's questions with `nextCompileRequest(request, outcome,
1838
+ * answers)`: over HTTP, after a provider round that kept its plan, it sends
1839
+ * that round's judged answer round (the seat only judges, no authoring call),
1840
+ * or with `{ cognition: 'deterministicOnly' }` its zero-call replay.
1841
+ *
1842
+ * The candidate is ordinary `.nika` SOURCE, proposed only when `ready`.
1843
+ * `run()` consumes a path, so the caller materializes the candidate and
1844
+ * `run(path)` re-admits it — the compile preview is a review, never
1845
+ * admission. A held candidate (`isNikaCompileHeld`) is a preview: never run
1846
+ * it. Over `{ url }` this calls the authenticated Serve compile door, gated
1847
+ * by its advertised capability; the SDK never compiles locally as a fallback.
1848
+ */
1849
+ compile(request: string | NikaCompileRequest, options?: NikaCompileOptions): Promise<NikaCompileOutcome>;
1850
+ /**
1851
+ * Resolves with the run's handle once the engine admitted it, and rejects
1852
+ * without one when the engine refused it. The handle owns the lifecycle:
1853
+ * `run.events()`, `run.result()`, `run.status()`, `run.cancel()`.
1854
+ *
1855
+ * `Outputs` is the caller's projection of the engine-emitted outputs map;
1856
+ * the SDK transports outputs without validating their shape.
1857
+ */
1858
+ run<Outputs extends Record<string, unknown> = Record<string, unknown>>(workflow: string, options?: NikaRunOptions): Promise<NikaRun<Outputs>>;
1859
+ /**
1860
+ * The one recovery door: reattach this client process to an
1861
+ * already-admitted durable HTTP job and get a full `NikaRun` back. Pass the
1862
+ * last `event.sequence` you fully processed as `lastEventId`. A native
1863
+ * process is process-bound and refuses with a typed compatibility error.
1864
+ */
1865
+ attachRun<Outputs extends Record<string, unknown> = Record<string, unknown>>(id: string, options?: NikaAttachRunOptions): Promise<NikaRun<Outputs>>;
1866
+ /** List contained workflow names from a resident HTTP authority. */
1867
+ listWorkflows(): Promise<readonly string[]>;
1868
+ /** Read path-free metadata for one contained workflow. */
1869
+ workflow(name: string): Promise<NikaWorkflowMetadata>;
1870
+ /**
1871
+ * Ask a `nika serve` what the sessions of a served workflow's own declared
1872
+ * ACP route offer now: the models, the reasoning efforts and the service
1873
+ * tiers, read without a prompt. The route and the models are the file's; a
1874
+ * workflow that declares no ACP route answers `status: 'not_applicable'` and
1875
+ * opens no session. The answer is an observation with a time and authorizes
1876
+ * nothing: a run still selects, reads back and refuses on its own session.
1877
+ * Needs a server that lists `accessSessionOffer` (engine 0.124.3).
1878
+ */
1879
+ accessOffer(workflow: string, options?: NikaAccessOfferOptions): Promise<NikaAccessOffer>;
1880
+ /**
1881
+ * The run's events in the protocol vocabulary of its transport
1882
+ * (`workflow_*` · `task_*` · `run_*` natively, `execution.*` over HTTP).
1883
+ *
1884
+ * @deprecated Use `run.events()`: one lifecycle vocabulary on both
1885
+ * transports, with this same frame kept on `event.raw`. This wrapper is a
1886
+ * compatibility door for one release train, counted from publication: it
1887
+ * ships unchanged in the first published train that carries `run.events()`,
1888
+ * and the earliest train that may remove it is the one after, as announced
1889
+ * in that train's release notes. It accepts only a run this client created.
1890
+ */
1891
+ events<Outputs extends Record<string, unknown> = Record<string, unknown>>(run: NikaRun<Outputs>, options?: NikaEventsOptions): AsyncIterable<NikaEvent<Outputs>>;
1892
+ /**
1893
+ * @deprecated Use `run.cancel()`; both return the one memoized request.
1894
+ * Kept through the same compatibility window as `events(run)`. It accepts
1895
+ * only a run this client created.
1896
+ */
1897
+ cancel(run: NikaRun): Promise<NikaCancelResult>;
1898
+ /**
1899
+ * Read the current durable status without waiting for terminal settlement.
1900
+ *
1901
+ * @deprecated Use `run.status()`. Kept through the same compatibility
1902
+ * window as `events(run)`. It accepts only a run this client created.
1903
+ */
1904
+ status(run: NikaRun): Promise<NikaRunStatus>;
1905
+ schedule(workflow: string, options: NikaScheduleOptions): Promise<NikaScheduleApplyResult>;
1906
+ scheduleStatus(id: string): Promise<NikaScheduleStatus>;
1907
+ traceVerify(receipt: NikaReceipt, options?: NikaTraceVerifyOptions): Promise<NikaTraceVerifyResult>;
1908
+ /** One session per admitted run, owned by this client and by no registry. */
1909
+ private own;
1910
+ private session;
1911
+ }
1912
+
1913
+ export { Nika, type NikaAccessOffer, type NikaAccessOfferListing, type NikaAccessOfferOptions, type NikaAccessOfferRoute, type NikaAccessPin, type NikaAccessRequirement, type NikaAccessSelection, type NikaArtifact, type NikaArtifactDownload, type NikaArtifactDownloadOptions, type NikaArtifactManifest, type NikaArtifactReadOptions, type NikaArtifactsOptions, type NikaAttachRunOptions, type NikaAttestedValue, type NikaCancelResult, type NikaCheckFinding, type NikaCheckOptions, type NikaCheckResult, type NikaCheckVerdicts, NikaCompatibilityError, type NikaCompileAuthoringReceipt, type NikaCompileCognition, type NikaCompileCreateRequest, type NikaCompileDiagnostic, type NikaCompileEditRequest, type NikaCompileLimits, type NikaCompileOptions, type NikaCompileOutcome, type NikaCompilePreview, type NikaCompileProvenance, type NikaCompileQuestion, type NikaCompileQuestionOption, type NikaCompileRecordError, type NikaCompileRefusalCode, type NikaCompileRequest, type NikaCompileRequestCognition, type NikaCompileSetConstant, type NikaCompileStatus, type NikaCompileStrategy, type NikaCompileTrigger, type NikaConfig, NikaConfigurationError, type NikaConfiguredSource, type NikaCostQualifier, NikaEngineUnavailable, NikaError, type NikaEvent, NikaEventBufferOverflowError, type NikaEventsOptions, type NikaExecutionCancelledEvent, type NikaExecutionId, type NikaExecutionInterruptedEvent, type NikaExecutionRefusedEvent, type NikaExecutionSettledEvent, type NikaExecutionStartedEvent, type NikaJobId, type NikaJournalEvidence, type NikaLocalConfig, type NikaMachineError, type NikaNextCompileOptions, NikaObservationInterrupted, type NikaOperation, NikaOperationError, type NikaOperationFinding, NikaProtocolError, type NikaReceipt, type NikaRemoteConfig, type NikaRun, type NikaRunCause, type NikaRunEvent, type NikaRunEventKind, type NikaRunId, type NikaRunOptions, NikaRunOwnershipError, type NikaRunResult, type NikaRunSealedEvent, type NikaRunSettledEvent, type NikaRunStatus, type NikaScheduleAfterSkip, type NikaScheduleApplyResult, type NikaScheduleClaim, type NikaScheduleDefinition, type NikaScheduleDue, type NikaScheduleFinding, type NikaScheduleLastDecision, type NikaScheduleMissed, type NikaScheduleOptions, type NikaScheduleOverlap, type NikaSchedulePause, type NikaScheduleSlot, type NikaScheduleStatus, type NikaScheduleWhen, type NikaSelectedValue, type NikaServiceTier, type NikaServiceTierEvidence, type NikaSettlement, type NikaSourceSpan, type NikaSpend, type NikaTaskCacheHitEvent, type NikaTaskCompletedEvent, type NikaTaskScheduledEvent, type NikaTaskStartedEvent, type NikaTaskTally, type NikaTraceVerifyOptions, type NikaTraceVerifyResult, NikaTransportError, type NikaTransportKind, type NikaUnknownEvent, type NikaWorkflowCompletedEvent, type NikaWorkflowFailedEvent, type NikaWorkflowInterruptedEvent, type NikaWorkflowMetadata, type NikaWorkflowStartedEvent, isNikaCompileHeld, isNikaRunSealedEvent, isNikaRunSettledEvent, isNikaRunSucceeded, isNikaTerminalEvent, nextCompileRequest, readNikaAccessRequirement, readNikaAccessSelection };