@nika-open/nika 0.0.0-stage → 0.124.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +202 -0
- package/README.md +776 -2
- package/dist/bin/nika.js +450 -0
- package/dist/index.cjs +5921 -0
- package/dist/index.d.cts +1913 -0
- package/dist/index.d.ts +1913 -0
- package/dist/index.js +5865 -0
- package/docs/README.md +69 -0
- package/docs/architecture.md +163 -0
- package/docs/compile.md +486 -0
- package/docs/errors.md +154 -0
- package/docs/glossary.md +41 -0
- package/docs/http-api.md +396 -0
- package/docs/migrating-to-0.116.md +164 -0
- package/docs/receipts.md +156 -0
- package/docs/runs.md +670 -0
- package/docs/server.md +543 -0
- package/docs/testing.md +244 -0
- package/docs/upgrading-to-0.123.md +190 -0
- package/openapi.json +3067 -0
- package/package.json +92 -4
package/dist/index.d.cts
ADDED
|
@@ -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 };
|