@niscorp/cortex 0.1.1 → 0.1.3

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/CHANGELOG.md CHANGED
@@ -1,5 +1,70 @@
1
1
  # @niscorp/cortex
2
2
 
3
+ ## 0.1.3
4
+
5
+ ### Patch Changes
6
+
7
+ - 2756aa7: `run.abort(reason)` keeps its reason: it is the `cause` of the aborted result.
8
+
9
+ `RunHandle.abort` is typed `(reason?: string) => void` and the reason was dropped — it was not on the result, on any event, or anywhere a caller could read it back.
10
+
11
+ A run stopped by `run.abort('the member closed the tab')` now settles with `error.cause: 'the member closed the tab'`, on `run.result` and on the result the `run-end` event carries. `error.code` (`aborted`) and `error.message` are unchanged, and `run.abort()` with no reason gives the result it always gave, with no `cause`.
12
+
13
+ The reason is kept beside the run's signal and never put on it: a tool's `ctx.signal` still aborts with an `AbortError`, so a tool — or a `fetch` it started — that tells an abort by that error sees one as before. A run stopped through the caller's own `options.signal` is unchanged too; what that signal was aborted with is not read.
14
+
15
+ **What to change:** nothing. If you already pass a reason to `run.abort`, the aborted result now carries it as `error.cause`.
16
+
17
+ - 0b5a7d6: README and DESIGN describe the loop as it runs. A turn of prose with no envelope in it is corrected without counting against `outputRetries`, so `stepCount` is what ends a model that keeps writing prose, and a `stopWhen` you pass replaces the defaults; `outputRetries(n)` means n attempts and n − 1 corrections. An invalid answer gets the attempt and a system message appended, not a tool error. A `respond` sent beside other tool calls is dropped, and output streamed by a step that ends in tool calls is not the answer. Through Signal a call to a tool the agent does not have is read as an attempted answer, so `tool-end` kind `unknown-tool` is rare. `policy.tools` lists take tool ids, not the names the model calls. A tool's `output` schema types what `execute` returns and is not applied at runtime. No code changed.
18
+
19
+ **What to change:** nothing for this release. A `policy.tools` entry written with a tool's name, where its `id` differs, has never matched: write the id.
20
+
21
+ - 4abbfcc: The README says what a tool's `input` schema may be. The model is sent its JSON Schema, taken from the schema's output side, and a call's arguments are parsed with it twice: by the loop, then again in front of `execute`. So an `input` schema validates and does not convert:
22
+ - One with no JSON Schema (a `.transform()`, a `z.date()`) fails the run before the model is asked, with `code: 'unknown'` and Zod's message.
23
+ - One whose output is another kind than its input (`z.stringbool()`) is described to the model by its output and then refuses what its own first parse produced: the tool never runs.
24
+ - One that changes a value (`.overwrite()`) changes it twice, while the observation's `args` hold the value as parsed once.
25
+
26
+ Convert inside `execute`. The README says this under "Errors", and tests hold it. No code changed.
27
+
28
+ **What to change:** nothing.
29
+
30
+ - a02a031: The README and DESIGN say which approval id a resumed run answers to. No code changed.
31
+
32
+ `resumeRun` re-asks a pending approval: the resumed run's gates run again for the pending call, and `approval-required` fires again with a new id. DESIGN called the id "stable" and the README said approvals survive restarts, which read as if the id in the snapshot could be answered on the resumed run. It cannot: `resumed.approve(snapshot.pending.approvalId)` does nothing — an id a handle did not ask under is ignored — and with no `policy.approvalTimeoutMs` the run then waits.
33
+
34
+ Both documents now say so: answer with the id of the resumed run's own `approval-required` event, as the README's example already does; `snapshot.pending.approvalId` names the ask of the run the snapshot was taken from. DESIGN also says that when the gates no longer ask on resume, the pending call simply runs. A test holds the re-ask and its new id.
35
+
36
+ **What to change:** nothing if you answer from the `approval-required` event. If you kept `snapshot.pending.approvalId` to answer with after `resumeRun`, answer with the id of the resumed run's event instead.
37
+
38
+ - Updated dependencies [5923e38]
39
+ - Updated dependencies [2815107]
40
+ - Updated dependencies [885bc1e]
41
+ - Updated dependencies [f9f1b26]
42
+ - Updated dependencies [e3e0ff2]
43
+ - Updated dependencies [ed9d7f4]
44
+ - @niscorp/solid@0.1.2
45
+
46
+ ## 0.1.2
47
+
48
+ ### Patch Changes
49
+
50
+ - 06d1531: The README's first run says why it failed. Its install line now names `openai`, the SDK Signal loads when a model on Groq, OpenAI or OpenRouter is called: without it the quick example's run failed with `Missing dependency: openai`. And the example prints the reason when a run fails (`else console.error(result.error.message)`): a failed run returns its reason and does not throw, so with no API key set the example ended in silence, exit code 0. No code changed.
51
+
52
+ **What to change:** nothing.
53
+
54
+ - fe30458: Every package exports its `package.json`, so an app can say which version of a package it runs by reading it from the package:
55
+
56
+ ```ts
57
+ import prism from '@niscorp/prism/package.json' with { type: 'json' };
58
+ prism.version; // the version that is installed, not the range that asked for it
59
+ ```
60
+
61
+ Until now the `exports` map hid it, and the only way to the version was a path into `node_modules`. `check:packages` installs the tarballs and reads every package's version this way.
62
+
63
+ **What to change:** nothing. An app that read a version by path can read it by name.
64
+
65
+ - Updated dependencies [fe30458]
66
+ - @niscorp/solid@0.1.1
67
+
3
68
  ## 0.1.1
4
69
 
5
70
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -168,17 +168,21 @@ Cortex registers one synthetic tool per run:
168
168
  `{ data: <raw> }`. Envelope-first precedence; safe only because
169
169
  real data schemas are strict and discriminating — a correct
170
170
  answer is never failed for missing its coat.
171
- - **Validation feedback in-loop.** Invalid `respond` args produce a
172
- tool error result carrying the Zod issues; the model retries the
173
- call. One extra step, transcript intact, tools still warm — never a
174
- full re-run.
171
+ - **Validation feedback in-loop.** Invalid `respond` args are
172
+ appended as the assistant's turn, followed by a system message
173
+ carrying the Zod issues; the model answers again. One extra step,
174
+ transcript intact, tools still warm — never a full re-run.
175
175
  - **`respond` must be called alone.** If it appears alongside other
176
- tool calls in one turn, it receives an error result and the other
177
- calls execute normally.
176
+ tool calls in one turn, it is dropped: the other calls execute
177
+ normally and the model is told nothing about it. Its arguments have
178
+ already streamed as `output-delta` and `output-partial` by then.
178
179
  - **Termination without a result** (model stops on prose that is not
179
180
  an envelope) is a protocol violation: cortex appends a correction
180
181
  offering both exits (call `respond`, or emit ONLY the envelope) and
181
- continues, bounded by the `outputRetries` stop condition. Per-agent
182
+ continues. These corrections are not counted against
183
+ `outputRetries`, which is for answers that parsed and were refused,
184
+ so it is `stepCount` (20 turns by default) that ends a run whose
185
+ model keeps writing prose. Per-agent
182
186
  hardening: `output.forceTool: true` sets `toolChoice: 'required'`
183
187
  so every turn must be a tool call and `respond` is the only exit —
184
188
  opt-in, because some models get tool-happy under `required`.
@@ -199,8 +203,9 @@ get grammar-level enforcement for free.
199
203
  The envelope travels on the content channel: the model's final
200
204
  completion IS the envelope, as raw JSON — no tool call, no provider
201
205
  grammar. First-class, not degraded: same envelope, same Zod
202
- validation, same correction retries (appended messages, bounded by
203
- `outputRetries`), same solid streaming via content deltas.
206
+ validation, same correction retries (appended messages; a refused
207
+ envelope counts against `outputRetries`, a turn with no envelope in
208
+ it does not), same solid streaming via content deltas.
204
209
  Fence-tolerant parse. It is `auto`'s floor: wherever neither grammar
205
210
  nor tool params would enforce the contract, the contract rides the
206
211
  prompt either way, and emit carries the answer without a synthetic
@@ -242,7 +247,7 @@ step:
242
247
  execute (Zod-validated input, timeout)
243
248
  onToolResult hooks (replace / redact / truncate)
244
249
  append tool result message; emit tool-end observation
245
- respond call → validate envelope → end (or error result + continue)
250
+ respond call → validate envelope → end (or correction + continue)
246
251
  ```
247
252
 
248
253
  Rules the loop lives by:
@@ -259,10 +264,16 @@ Rules the loop lives by:
259
264
  denied call becomes an error result the model sees and reacts to.
260
265
  The run only fails on structural conditions (stop limits, model
261
266
  call failure, abort, retries exhausted).
267
+ - **A tool's `input` is enforced; its `output` is a type.** The input
268
+ schema is parsed before `execute` runs. The optional `output`
269
+ schema types what `execute` returns and is not applied at runtime:
270
+ the return value is not parsed, stripped or transformed by it.
262
271
  - **The model sees `tool.name`; `tool.id` is the policy identity.**
263
- Descriptors carry the name (prompts say "call `query`"); the loop
264
- resolves incoming calls by name OR id; gates, observations and
265
- traces always carry the canonical id. Both namespaces must be
272
+ Descriptors carry the name (prompts say "call `query`"); the loop's
273
+ own table resolves a call by name OR id, but Signal routes only the
274
+ names it was sent, so through Signal a call by id is read as an
275
+ attempted answer and never reaches that table; gates, observations
276
+ and traces always carry the canonical id. Both namespaces must be
266
277
  collision-free per run, and nothing may claim `respond`. (v1 sent
267
278
  ids on the wire while documenting names — a prompt-literal model
268
279
  exposed the lie.)
@@ -402,12 +413,20 @@ type StopCondition = (s: RunProgress) => StopVerdict; // { stop: StopReason; m
402
413
  compiles to one built-in gate. Anything the sugar can't express is
403
414
  a function.
404
415
  - **Approvals suspend the run.** `ask` emits `approval-required`
405
- with a stable id; the pending call blocks (tools are sequential, so
416
+ with an id that is that ask's for as long as the run handle lives —
417
+ the event, `run.approve` / `run.deny` and `run.snapshot()` all name
418
+ it; the pending call blocks (tools are sequential, so
406
419
  one pending approval at a time). `run.approve(id, { args? })` —
407
420
  approve, optionally with edited args — or `run.deny(id, reason)`.
421
+ An id the handle did not ask under is ignored.
408
422
  `run.snapshot()` serializes the suspended run (messages, pending
409
423
  call, usage); `resumeRun(agent, snapshot, opts)` restores it — so
410
- approvals survive reloads and restarts.
424
+ approvals survive reloads and restarts. A resumed run **re-asks**:
425
+ its gates run again for the pending call (if they no longer ask, the
426
+ call simply runs) and `approval-required` fires with a new id — the
427
+ one the resumed handle answers to. `snapshot.pending.approvalId`
428
+ names the ask of the run the snapshot came from, not the resumed
429
+ one's.
411
430
  - **Output validation** closes the generate→verify loop in-run:
412
431
 
413
432
  ```ts
@@ -448,7 +467,7 @@ const result = await run.result;
448
467
  | `tool-start` | `{ call }` | before gates + execution — drives live UIs |
449
468
  | `tool-end` | `{ observation }` | typed union incl. denials; no casting |
450
469
  | `approval-required` | `{ approval: { id, toolId, callId, args, reason } }` | run suspends |
451
- | `output-delta` | `{ text }` | raw envelope JSON fragments |
470
+ | `output-delta` | `{ text }` | the output channel as it streams; the envelope's JSON on the step that ends the run |
452
471
  | `output-partial` | `{ output }` | solid-parsed partial envelope |
453
472
  | `retry` | `{ kind: 'output' \| 'termination' \| 'provider', attempt, issues }` | consumers reset partial state; `issues` carries the evidence (Zod issues, the rejected attempt, or the stray text) |
454
473
  | `run-end` | `{ result, meta }` | |
@@ -563,6 +582,8 @@ run.result: Promise<RunResult<TData>>
563
582
  run.approve(id, { args? }) / run.deny(id, reason?)
564
583
  run.snapshot(): RunSnapshot
565
584
  run.abort(reason?)
585
+ // the reason is `error.cause` of the `aborted` result. A tool's
586
+ // ctx.signal still aborts with an AbortError, never with the reason.
566
587
 
567
588
  // composition
568
589
  createManifold({ llm?, gates?, onRun? }): Manifold
package/README.md CHANGED
@@ -8,6 +8,9 @@ hand cortex the client) and `zod` (you hand it the schemas).
8
8
 
9
9
  ```bash
10
10
  pnpm add @niscorp/cortex @niscorp/signal zod
11
+ # Signal loads the provider's SDK when a model is called. For Groq, OpenAI,
12
+ # OpenRouter or any OpenAI-compatible API (the quick example runs on Groq):
13
+ pnpm add openai
11
14
  ```
12
15
 
13
16
  For the *why* behind the architecture — the envelope, output
@@ -43,6 +46,7 @@ const llm = createSignal('groq'); // qwen/qwen3.8-27b — the registry default
43
46
 
44
47
  const result = await calcAgent.run('What is (2 + 3) * 7 - 6?', { llm }).result;
45
48
  if (result.ok) console.log(result.output.data.answer); // 29
49
+ else console.error(result.error.message); // a run that fails returns its reason; it does not throw
46
50
  ```
47
51
 
48
52
  ---
@@ -85,9 +89,9 @@ How the envelope travels from model to runtime. One field,
85
89
  | `emit` | the model's completion IS the envelope (content channel) | everything else — auto-picked wherever neither of the above enforces anything: all of Groq, big schemas, models that mangle nested tool args |
86
90
 
87
91
  Zod validates in **every** strategy. Invalid output feeds back as a
88
- correction *inside the same run* (a tool error result / an appended
89
- message) — never a full re-run. Big recursive schemas (Prism nodes,
90
- Nova actions) ride `emit`; cortex injects
92
+ correction *inside the same run* (the attempt and a system message
93
+ naming the issues are appended) — never a full re-run. Big recursive
94
+ schemas (Prism nodes, Nova actions) ride `emit`; cortex injects
91
95
  the JSON Schema into the prompt automatically (`output.doc: 'auto'`,
92
96
  via `schemaDoc()` — single-sourced from the Zod schema).
93
97
 
@@ -127,7 +131,17 @@ const agent = defineAgent<Data, Deps>({
127
131
  Deps are per-invocation, typed, and consumed by context entries,
128
132
  gates and hooks — agents are defined once, never rebuilt per call.
129
133
  Defaults when `stopWhen` is omitted: `stepCount(20)`,
130
- `outputRetries(3)`.
134
+ `outputRetries(3)`. A `stopWhen` you pass replaces both, so keep a
135
+ `stepCount` in it: `outputRetries` counts refused answers only, and
136
+ a turn of prose with no envelope in it is corrected without being
137
+ counted. `outputRetries(n)` ends the run at the n-th refused answer:
138
+ n attempts, n − 1 corrections, so `outputRetries(1)` allows no
139
+ second attempt.
140
+
141
+ `policy.tools` lists take tool **ids** (`tool.id`), not the names
142
+ the model calls: a name in `deny` or `requireApproval` matches
143
+ nothing and says nothing, and a name in `allow` leaves the tool off
144
+ the list.
131
145
 
132
146
  Multi-turn history is caller-owned: `input` accepts a `string`, a
133
147
  `Message[]` transcript, or any JSON value.
@@ -160,11 +174,22 @@ const result = await run.result; // the no-streaming opt-out
160
174
 
161
175
  - `tool-start` fires **before** execution — drives live "running…" UIs.
162
176
  - `tool-end` carries a typed `ToolObservation` union (result / error /
163
- denied / unknown-tool). No casting.
177
+ denied / unknown-tool). No casting. Through Signal, `unknown-tool`
178
+ is rare: Signal routes only calls to tools the step declared, and
179
+ reads a call to any other name as an attempted answer. It is
180
+ validated as the envelope (a `retry`, or the run's output if it
181
+ passes), or dropped when it comes beside a call to a declared tool,
182
+ and never reaches `tool-start`. The kind arises when `resumeRun` is
183
+ not handed the per-run tool the pending call names, or with a
184
+ client that does its own routing.
164
185
  - `output-delta` streams the raw envelope JSON as it generates;
165
186
  `output-partial` streams the progressively parsed envelope via
166
187
  [`@niscorp/solid`](../solid) — a chat `response` streams token-ish,
167
188
  a Nova screen in `data` becomes renderable before the run ends.
189
+ Both stream before cortex knows how the step ends: words written
190
+ beside a tool call (under `emit` and `native`) and a `respond` sent
191
+ beside other calls arrive as `output-delta` too and are not the
192
+ answer. The answer is what the last step streamed.
168
193
  - `retry` resets partial-output state (same contract consumers had
169
194
  in v1).
170
195
  - Nested runs (`asTool`) forward their events into the parent stream
@@ -200,6 +225,11 @@ run.onEvent((e) => {
200
225
  Suspended runs serialize: `run.snapshot()` → JSON →
201
226
  `resumeRun(agent, snapshot, { llm, deps })` re-asks the pending
202
227
  approval and continues — approvals survive reloads and restarts.
228
+ Re-asks means just that: the resumed run's gates run again for the
229
+ pending call and `approval-required` fires again, with a **new** id.
230
+ Answer with that event's id, as above. `snapshot.pending.approvalId` is
231
+ the ask of the run the snapshot was taken from; the resumed run did not
232
+ ask under it, and `approve` or `deny` with it does nothing.
203
233
  `policy.approvalTimeoutMs` turns an unanswered ask into a denial
204
234
  (an observation, not a run failure).
205
235
 
@@ -274,6 +304,24 @@ type CortexError = {
274
304
  Tool failures are **observations**, not exceptions — the model sees
275
305
  them and decides; the run fails only on structural conditions.
276
306
 
307
+ A tool's `input` schema validates; it does not convert. It does two
308
+ jobs: the model is sent its JSON Schema, taken from the schema's
309
+ output side, and a call's arguments are parsed with it twice — by the
310
+ loop, then again in front of `execute`. Converting belongs inside
311
+ `execute`, and this is what it costs in the schema:
312
+
313
+ - A schema with no JSON Schema (a `.transform()`, a `z.date()`) fails
314
+ the run before the model is asked: `code: 'unknown'`, with Zod's
315
+ message (`Transforms cannot be represented in JSON Schema`).
316
+ - A schema whose output is another kind than its input
317
+ (`z.stringbool()`) is described to the model by its output and then
318
+ refuses what its own first parse produced: every call ends in an
319
+ `error` observation and `execute` never runs.
320
+ - A schema that changes a value (`.overwrite()`) changes it twice.
321
+ That is harmless where a second pass changes nothing (`.trim()`),
322
+ and wrong where it does; the observation's `args` hold the value
323
+ as parsed once.
324
+
277
325
  ---
278
326
 
279
327
  ## Building
package/dist/index.cjs CHANGED
@@ -891,6 +891,7 @@ var wireRun = (wiring) => {
891
891
  if (options?.onEvent) channel.onEvent(options.onEvent);
892
892
  const approvals = createApprovalBridge();
893
893
  const controller = new AbortController();
894
+ let abortReason;
894
895
  const externalSignal = options?.signal;
895
896
  const onExternalAbort = () => controller.abort();
896
897
  if (externalSignal) {
@@ -990,6 +991,9 @@ var wireRun = (wiring) => {
990
991
  }
991
992
  };
992
993
  }
994
+ if (!outcome.ok && outcome.error.code === "aborted" && abortReason !== void 0) {
995
+ outcome = { ...outcome, error: { ...outcome.error, cause: abortReason } };
996
+ }
993
997
  channel.emit({ type: "run-end", result: outcome, meta: outcome.meta });
994
998
  channel.close();
995
999
  if (externalSignal) externalSignal.removeEventListener("abort", onExternalAbort);
@@ -1015,7 +1019,10 @@ var wireRun = (wiring) => {
1015
1019
  elapsedMs: state.elapsedBase + (Date.now() - state.startedAt),
1016
1020
  ...state.pending && { pending: state.pending }
1017
1021
  }),
1018
- abort: () => controller.abort()
1022
+ abort: (reason) => {
1023
+ if (!controller.signal.aborted) abortReason = reason;
1024
+ controller.abort();
1025
+ }
1019
1026
  };
1020
1027
  };
1021
1028
  var createRun = (definition, input, options) => wireRun({ definition, input, options, runId: newRunId() });