@niscorp/cortex 0.1.0 → 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 +72 -0
- package/DESIGN.md +92 -48
- package/README.md +55 -7
- package/dist/index.cjs +8 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +8 -1
- package/dist/index.js.map +1 -1
- package/package.json +6 -5
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# @niscorp/cortex
|
|
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
|
+
|
|
68
|
+
## 0.1.1
|
|
69
|
+
|
|
70
|
+
### Patch Changes
|
|
71
|
+
|
|
72
|
+
- b67a125: Documentation only: each package's README, reference and design docs checked against its source and corrected — install lines and peers, signatures, defaults, status codes, licenses (loom, signal: Apache-2.0), and API that existed but was not documented.
|
package/DESIGN.md
CHANGED
|
@@ -49,7 +49,7 @@ JSON-parsing of streams (solid), no event-bus substrate, no
|
|
|
49
49
|
declarative rules DSL, no plan interpreter (§14), no conversation
|
|
50
50
|
persistence (callers own history).
|
|
51
51
|
|
|
52
|
-
**Peers:** `@niscorp/signal`, `@niscorp/solid
|
|
52
|
+
**Peers:** `@niscorp/signal`, `zod`. **Dependency:** `@niscorp/solid`.
|
|
53
53
|
|
|
54
54
|
---
|
|
55
55
|
|
|
@@ -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
|
|
172
|
-
|
|
173
|
-
|
|
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
|
|
177
|
-
|
|
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
|
|
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
|
|
203
|
-
`outputRetries
|
|
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
|
|
@@ -218,8 +223,8 @@ a content-only message.
|
|
|
218
223
|
single-sourced from the same schema Zod validates against, so docs
|
|
219
224
|
and validation cannot drift. When `respond` resolves to loose or
|
|
220
225
|
permissive params (or strategy is `emit`), cortex injects
|
|
221
|
-
`OUTPUT SCHEMA
|
|
222
|
-
|
|
226
|
+
`OUTPUT SCHEMA …` as a
|
|
227
|
+
system chunk automatically (placement: §5). Agents that hand-author a full DSL
|
|
223
228
|
guide (the architect pattern) disable it with `output.doc: 'off'` or
|
|
224
229
|
replace it with a string.
|
|
225
230
|
|
|
@@ -232,7 +237,7 @@ prefix = assemble(context fns, input) — once, at run start
|
|
|
232
237
|
messages = [...prefix] — append-only from here on
|
|
233
238
|
|
|
234
239
|
step:
|
|
235
|
-
stopWhen checks (steps, tokens, duration, outputRetries)
|
|
240
|
+
stopWhen checks (steps, tokens, duration, outputRetries, repeatedCalls)
|
|
236
241
|
prepareStep hook → activeTools mask, toolChoice, injected messages, llm swap
|
|
237
242
|
signal.stepStream({ messages, tools, responseFormat? })
|
|
238
243
|
→ model-delta events (text + reasoning channels)
|
|
@@ -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
|
|
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
|
|
265
|
-
|
|
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.)
|
|
@@ -274,9 +285,13 @@ Bounds are `stopWhen` predicates — one vocabulary instead of v1's
|
|
|
274
285
|
maxToolIterations / maxTicks / maxDurationMs / budget tangle:
|
|
275
286
|
|
|
276
287
|
```ts
|
|
277
|
-
stopWhen: [stepCount(20), tokens(100_000), duration('5m'), outputRetries(3)]
|
|
288
|
+
stopWhen: [stepCount(20), tokens(100_000), duration('5m'), outputRetries(3), repeatedCalls(3)]
|
|
278
289
|
```
|
|
279
290
|
|
|
291
|
+
`repeatedCalls(n)` ends a run whose model keeps sending the same tool
|
|
292
|
+
call and getting the same answer — every further step would cost a
|
|
293
|
+
full prompt and change nothing.
|
|
294
|
+
|
|
280
295
|
Defaults: `stepCount(20)`, `outputRetries(3)`. No default duration or
|
|
281
296
|
token cap — v1's 60-second default was overridden at every call site,
|
|
282
297
|
which is what a wrong default looks like.
|
|
@@ -326,14 +341,19 @@ that is how knowledge drifts.
|
|
|
326
341
|
agent's own — an app attaches shared knowledge to ANY agent without
|
|
327
342
|
editing its definition.
|
|
328
343
|
- **Tools bring their own guides.** `defineTool({ guide })` carries
|
|
329
|
-
the tool's usage knowledge (a string
|
|
344
|
+
the tool's usage knowledge (a string, a `string[]` of lines, or a
|
|
345
|
+
deferred function returning either,
|
|
330
346
|
e.g. composing a library's exported guide). The run assembles one
|
|
331
347
|
TOOL GUIDES section from the ACTIVE tools — add a tool and its
|
|
332
348
|
guide arrives, change it and every agent updates, remove it and the
|
|
333
349
|
guide leaves. Instructions never describe tools.
|
|
334
|
-
- Prefix order: instructions →
|
|
335
|
-
|
|
336
|
-
|
|
350
|
+
- Prefix order: instructions → tool guides → schema doc → finish
|
|
351
|
+
protocol → agent producers → run producers → input. The three
|
|
352
|
+
middle blocks are fixed for the life of an agent, so they sit ahead
|
|
353
|
+
of the producers, which are not — a provider's prefix cache stops at
|
|
354
|
+
the first byte that changed. The finish
|
|
355
|
+
protocol is ONE chunk — authored by signal's transport, injected by
|
|
356
|
+
cortex verbatim — stating how the run ends under
|
|
337
357
|
the RESOLVED transport (call `respond` / emit the envelope / reply
|
|
338
358
|
under grammar) — agents never author finish lines; they cannot know
|
|
339
359
|
which transport resolution picked.
|
|
@@ -348,7 +368,7 @@ that is how knowledge drifts.
|
|
|
348
368
|
- Compaction (summarize-when-near-limit) is a future single hook on
|
|
349
369
|
the transcript (§15), not a v1 pipeline.
|
|
350
370
|
|
|
351
|
-
**Preview survives, better.** `agent.preview(input, { deps })`
|
|
371
|
+
**Preview survives, better.** `await agent.preview(input, { deps })`
|
|
352
372
|
returns the exact assembled messages, the resolved tool list
|
|
353
373
|
(including `respond` and its actual params), the resolved strategy,
|
|
354
374
|
and a token estimate — no model call. Anything you can't explain in
|
|
@@ -372,10 +392,10 @@ type ToolGate<TDeps> = (call: ToolCallInfo, ctx: RunCtx<TDeps>) =>
|
|
|
372
392
|
type ToolResultHook<TDeps> = (obs: ToolObservation, ctx: RunCtx<TDeps>) =>
|
|
373
393
|
{ result?: unknown } | void | Promise<…>; // replace / redact / truncate
|
|
374
394
|
|
|
375
|
-
type PrepareStep<TDeps> = (s:
|
|
376
|
-
{ activeTools?: string[]; toolChoice?: ToolChoice; inject?: Message[]; llm?: SignalClient } | void
|
|
395
|
+
type PrepareStep<TDeps> = (s: PrepareStepInfo<TDeps>) =>
|
|
396
|
+
{ activeTools?: string[]; toolChoice?: ToolChoice; inject?: Message[]; llm?: SignalClient } | void | Promise<…>;
|
|
377
397
|
|
|
378
|
-
type StopCondition = (s: RunProgress) =>
|
|
398
|
+
type StopCondition = (s: RunProgress) => StopVerdict; // { stop: StopReason; message } | null
|
|
379
399
|
```
|
|
380
400
|
|
|
381
401
|
- **Gates run before execution.** A deny reaches the model as a tool
|
|
@@ -393,12 +413,20 @@ type StopCondition = (s: RunProgress) => boolean;
|
|
|
393
413
|
compiles to one built-in gate. Anything the sugar can't express is
|
|
394
414
|
a function.
|
|
395
415
|
- **Approvals suspend the run.** `ask` emits `approval-required`
|
|
396
|
-
with
|
|
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
|
|
397
419
|
one pending approval at a time). `run.approve(id, { args? })` —
|
|
398
420
|
approve, optionally with edited args — or `run.deny(id, reason)`.
|
|
421
|
+
An id the handle did not ask under is ignored.
|
|
399
422
|
`run.snapshot()` serializes the suspended run (messages, pending
|
|
400
423
|
call, usage); `resumeRun(agent, snapshot, opts)` restores it — so
|
|
401
|
-
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.
|
|
402
430
|
- **Output validation** closes the generate→verify loop in-run:
|
|
403
431
|
|
|
404
432
|
```ts
|
|
@@ -438,8 +466,8 @@ const result = await run.result;
|
|
|
438
466
|
| `model-delta` | `{ text, channel: 'text' \| 'reasoning' }` | provider reasoning tokens land here |
|
|
439
467
|
| `tool-start` | `{ call }` | before gates + execution — drives live UIs |
|
|
440
468
|
| `tool-end` | `{ observation }` | typed union incl. denials; no casting |
|
|
441
|
-
| `approval-required` | `{ id, toolId, args, reason }` | run suspends |
|
|
442
|
-
| `output-delta` | `{ text }` |
|
|
469
|
+
| `approval-required` | `{ approval: { id, toolId, callId, args, reason } }` | run suspends |
|
|
470
|
+
| `output-delta` | `{ text }` | the output channel as it streams; the envelope's JSON on the step that ends the run |
|
|
443
471
|
| `output-partial` | `{ output }` | solid-parsed partial envelope |
|
|
444
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) |
|
|
445
473
|
| `run-end` | `{ result, meta }` | |
|
|
@@ -503,10 +531,12 @@ Same two principles as v1, smaller taxonomy:
|
|
|
503
531
|
```ts
|
|
504
532
|
type CortexError = {
|
|
505
533
|
code: 'model_call_failed' | 'output_invalid' | 'stopped' | 'aborted' | 'unknown';
|
|
506
|
-
stop?:
|
|
534
|
+
stop?: StopReason; // when code === 'stopped':
|
|
535
|
+
// 'steps' | 'tokens' | 'duration' | 'output_retries' | 'repeated_calls' | 'custom'
|
|
507
536
|
message: string;
|
|
508
537
|
runId: string;
|
|
509
538
|
agentPath: ReadonlyArray<string>;
|
|
539
|
+
lastOutput?: unknown; // the last invalid output when the run died on output retries
|
|
510
540
|
cause?: unknown;
|
|
511
541
|
};
|
|
512
542
|
```
|
|
@@ -519,7 +549,7 @@ principle as every other tool denial.
|
|
|
519
549
|
|
|
520
550
|
## 10. Streaming
|
|
521
551
|
|
|
522
|
-
Always on (§4). Solid is a
|
|
552
|
+
Always on (§4). Solid is a dependency and powers
|
|
523
553
|
`output-partial`: `respond` arg deltas (or content deltas under
|
|
524
554
|
`native`/`emit`) stream through solid's partial parser into
|
|
525
555
|
progressively-typed envelopes — a chat `response` string streams
|
|
@@ -538,36 +568,45 @@ defineTool(config): ToolDefinition // v1 shape, kept
|
|
|
538
568
|
schemaDoc(schema, opts?): string
|
|
539
569
|
|
|
540
570
|
// execution
|
|
541
|
-
agent.run(input, { deps, llm?, tools?, gates?, onToolResult?, onEvent?, signal? }): RunHandle<TData>
|
|
571
|
+
agent.run(input, { deps, llm?, tools?, producers?, gates?, onToolResult?, onEvent?, signal? }): RunHandle<TData>
|
|
542
572
|
// tools: per-run tools whose execute closes over per-invocation
|
|
543
573
|
// dependencies (vex builds its query tools around the caller's
|
|
544
574
|
// adapter + schema); appended to the agent's static tools.
|
|
545
|
-
agent.preview(input, { deps }): ResolvedPreview
|
|
575
|
+
agent.preview(input, { deps }): Promise<ResolvedPreview>
|
|
546
576
|
resumeRun(agent, snapshot, opts): RunHandle<TData>
|
|
547
577
|
|
|
548
578
|
// RunHandle
|
|
549
579
|
run.events: AsyncIterable<CortexEvent>
|
|
580
|
+
run.onEvent(listener): Unsubscribe
|
|
550
581
|
run.result: Promise<RunResult<TData>>
|
|
551
582
|
run.approve(id, { args? }) / run.deny(id, reason?)
|
|
552
583
|
run.snapshot(): RunSnapshot
|
|
553
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.
|
|
554
587
|
|
|
555
588
|
// composition
|
|
556
|
-
createManifold({ llm
|
|
557
|
-
manifold.register / run / asTool / preview
|
|
589
|
+
createManifold({ llm?, gates?, onRun? }): Manifold
|
|
590
|
+
manifold.register / run / asTool / preview / agent / tool / agents / tools
|
|
591
|
+
asTool(agent, { id?, description?, llm?, timeoutMs?, deps, select? }): ToolDefinition
|
|
592
|
+
|
|
593
|
+
// gates
|
|
594
|
+
policyGate(policy): ToolGate
|
|
558
595
|
|
|
559
596
|
// stop conditions
|
|
560
|
-
stepCount(n), tokens(n), duration(ms | '5m'), outputRetries(n)
|
|
597
|
+
stepCount(n), tokens(n), duration(ms | '5m'), outputRetries(n), repeatedCalls(n)
|
|
598
|
+
DEFAULT_STOP_CONDITIONS // [stepCount(20), outputRetries(3)]
|
|
561
599
|
```
|
|
562
600
|
|
|
563
601
|
`defineAgent` config:
|
|
564
602
|
|
|
565
603
|
```ts
|
|
566
604
|
{
|
|
567
|
-
id, description
|
|
568
|
-
llm?, // per-agent binding;
|
|
605
|
+
id, description?,
|
|
606
|
+
llm?, // per-agent binding; run option overrides it, manifold is the fallback
|
|
607
|
+
transport?: 'stream' | 'step', // default 'stream'; 'step' makes non-streaming calls (no deltas, no partials)
|
|
569
608
|
instructions, // string | (ctx) => string — sugar for the first producer
|
|
570
|
-
context?: Producer<TDeps>[], // compose shared sets by spreading: [...appProducers(), …]
|
|
609
|
+
context?: (ContextEntry | Producer<TDeps>)[], // compose shared sets by spreading: [...appProducers(), …]
|
|
571
610
|
tools?: ToolDefinition[], // definitions, not id strings; each may carry its own `guide`
|
|
572
611
|
output?: {
|
|
573
612
|
schema?: ZodType<TData>, // omitted → pure chat agent (data: undefined)
|
|
@@ -585,6 +624,9 @@ stepCount(n), tokens(n), duration(ms | '5m'), outputRetries(n)
|
|
|
585
624
|
|
|
586
625
|
## 12. Signal changes this design requires
|
|
587
626
|
|
|
627
|
+
Items 1–3 are built; the text below is the requirement as it was
|
|
628
|
+
written. The tokenizer in item 4 has not landed.
|
|
629
|
+
|
|
588
630
|
1. **`stepStream` emits `tool-call-delta`** — `{ index, id?, name?,
|
|
589
631
|
argsText }` fragments as function args stream. The SSE chunks
|
|
590
632
|
already contain them; the adapter currently drops them. This is
|
|
@@ -657,20 +699,20 @@ src/
|
|
|
657
699
|
├── types.ts # shared core types
|
|
658
700
|
│
|
|
659
701
|
├── schemas/
|
|
660
|
-
│ ├──
|
|
661
|
-
│ ├──
|
|
702
|
+
│ ├── index.ts
|
|
703
|
+
│ ├── envelope.schema.ts # envelope wire / accept schemas, validateEnvelope
|
|
662
704
|
│ └── tool-config.schema.ts
|
|
663
705
|
│
|
|
664
706
|
├── agent/
|
|
665
707
|
│ ├── define-agent.ts
|
|
666
|
-
│ ├── run.ts # RunHandle, resumeRun
|
|
708
|
+
│ ├── run.ts # RunHandle, resumeRun, prefix assembly
|
|
667
709
|
│ └── preview.ts
|
|
668
710
|
│
|
|
669
711
|
├── loop/
|
|
670
712
|
│ ├── loop.ts # the loop (§4) — all three transports
|
|
671
|
-
│ ├── strategy-resolve.ts # auto resolution + strict-compat walk
|
|
672
|
-
│ ├── respond-tool.ts # synthetic respond descriptor + corrections
|
|
673
713
|
│ └── partials.ts # solid partial-output tracking
|
|
714
|
+
│ # (auto resolution, the strict-compat walk, the respond
|
|
715
|
+
│ # descriptor and corrections are signal's: src/transport/)
|
|
674
716
|
│
|
|
675
717
|
├── context/
|
|
676
718
|
│ ├── assemble.ts
|
|
@@ -679,15 +721,17 @@ src/
|
|
|
679
721
|
├── gates/
|
|
680
722
|
│ ├── types.ts
|
|
681
723
|
│ ├── policy.ts # sugar → built-in gate
|
|
682
|
-
│
|
|
724
|
+
│ ├── stop.ts # stop conditions + defaults
|
|
725
|
+
│ └── approval.ts # suspend / approve / deny
|
|
683
726
|
│
|
|
684
727
|
├── events/
|
|
685
728
|
│ ├── types.ts # CortexEvent vocabulary
|
|
686
|
-
│ └──
|
|
729
|
+
│ └── channel.ts # per-run emitter + forwarding
|
|
687
730
|
│
|
|
688
731
|
├── manifold/
|
|
689
732
|
│ ├── manifold.ts
|
|
690
|
-
│
|
|
733
|
+
│ ├── as-tool.ts
|
|
734
|
+
│ └── types.ts # erased agent shapes
|
|
691
735
|
│
|
|
692
736
|
├── tool/define-tool.ts
|
|
693
737
|
├── errors/cortex.errors.ts
|
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* (
|
|
89
|
-
|
|
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
|
|
|
@@ -264,7 +294,7 @@ conditions return:
|
|
|
264
294
|
```ts
|
|
265
295
|
type CortexError = {
|
|
266
296
|
code: 'model_call_failed' | 'output_invalid' | 'stopped' | 'aborted' | 'unknown';
|
|
267
|
-
stop?: 'steps' | 'tokens' | 'duration' | 'output_retries' | 'custom';
|
|
297
|
+
stop?: 'steps' | 'tokens' | 'duration' | 'output_retries' | 'repeated_calls' | 'custom';
|
|
268
298
|
message: string;
|
|
269
299
|
runId: string;
|
|
270
300
|
agentPath: ReadonlyArray<string>;
|
|
@@ -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
|
|
@@ -281,7 +329,7 @@ them and decides; the run fails only on structural conditions.
|
|
|
281
329
|
```bash
|
|
282
330
|
pnpm build # tsup ESM + CJS + DTS
|
|
283
331
|
pnpm test # vitest run — scripted SignalClient stub, no network
|
|
284
|
-
pnpm typecheck # tsc on src
|
|
332
|
+
pnpm typecheck # tsc on src + test
|
|
285
333
|
```
|
|
286
334
|
|
|
287
335
|
---
|
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: () =>
|
|
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() });
|