@niscorp/cortex 0.1.5 → 0.2.0
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 +80 -0
- package/DESIGN.md +78 -126
- package/README.md +103 -19
- package/dist/index.cjs +260 -240
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +11 -2
- package/dist/index.d.ts +11 -2
- package/dist/index.js +260 -240
- package/dist/index.js.map +1 -1
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -26,26 +26,26 @@ import { z } from 'zod';
|
|
|
26
26
|
import { createSignal } from '@niscorp/signal';
|
|
27
27
|
import { defineAgent, defineTool } from '@niscorp/cortex';
|
|
28
28
|
|
|
29
|
-
const
|
|
30
|
-
id: '
|
|
31
|
-
name: '
|
|
32
|
-
description: '
|
|
33
|
-
input: z.object({
|
|
34
|
-
execute: ({
|
|
29
|
+
const add = defineTool({
|
|
30
|
+
id: 'add',
|
|
31
|
+
name: 'add',
|
|
32
|
+
description: 'Adds a list of numbers.',
|
|
33
|
+
input: z.object({ numbers: z.array(z.number()) }),
|
|
34
|
+
execute: ({ numbers }) => numbers.reduce((sum, n) => sum + n, 0),
|
|
35
35
|
});
|
|
36
36
|
|
|
37
37
|
const calcAgent = defineAgent({
|
|
38
38
|
id: 'calc',
|
|
39
39
|
description: 'Arithmetic with a tool.',
|
|
40
|
-
instructions: 'Use the
|
|
41
|
-
tools: [
|
|
40
|
+
instructions: 'Use the add tool, then give the answer.',
|
|
41
|
+
tools: [add],
|
|
42
42
|
output: { schema: z.object({ answer: z.number() }) },
|
|
43
43
|
});
|
|
44
44
|
|
|
45
45
|
const llm = createSignal('groq'); // qwen/qwen3.8-27b — the registry default
|
|
46
46
|
|
|
47
|
-
const result = await calcAgent.run('What is
|
|
48
|
-
if (result.ok) console.log(result.output.data.answer); //
|
|
47
|
+
const result = await calcAgent.run('What is 12 + 7 + 23?', { llm }).result;
|
|
48
|
+
if (result.ok) console.log(result.output.data.answer); // 42
|
|
49
49
|
else console.error(result.error.message); // a run that fails returns its reason; it does not throw
|
|
50
50
|
```
|
|
51
51
|
|
|
@@ -86,11 +86,15 @@ How the envelope travels from model to runtime. One field,
|
|
|
86
86
|
|
|
87
87
|
| Strategy | Mechanism | Fits |
|
|
88
88
|
|---|---|---|
|
|
89
|
-
| `native` | provider `response_format: json_schema`, in-loop |
|
|
89
|
+
| `native` | provider `response_format: json_schema`, in-loop | an output schema whose envelope converts to JSON Schema with no `$ref` in ≤ 8,192 characters, on a model with `nativeJsonSchema` (auto-picked; sent with `strict: false`) |
|
|
90
90
|
| `respond` | a synthesized `respond` tool; the envelope is its arguments | where the tool params can ENFORCE the contract — the endpoint does not validate tool args itself, the schema is small, the model carries nested args intact (auto-picked there) |
|
|
91
91
|
| `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 |
|
|
92
92
|
|
|
93
|
-
Zod validates in **every** strategy.
|
|
93
|
+
Zod validates in **every** strategy. A `data` that arrives as a
|
|
94
|
+
string of JSON is decoded before it is checked. A schema that takes
|
|
95
|
+
only strings gets it as written when the decoded value fails:
|
|
96
|
+
`z.string()` takes `"[1,2,3]"`.
|
|
97
|
+
Invalid output feeds back as a
|
|
94
98
|
correction *inside the same run* (the attempt and a system message
|
|
95
99
|
naming the issues are appended) — never a full re-run. Big recursive
|
|
96
100
|
schemas (Prism nodes, Nova actions) ride `emit`; cortex injects
|
|
@@ -106,6 +110,15 @@ output: {
|
|
|
106
110
|
}
|
|
107
111
|
```
|
|
108
112
|
|
|
113
|
+
A reply the provider cut off (finish reason `length` or
|
|
114
|
+
`content_filter`) with its JSON still open is closed at its last whole
|
|
115
|
+
value and checked as any other, as is an attempt a Groq rejection
|
|
116
|
+
(`failed_generation`) carried cut short. With `output.refuseCutOff: true` it is
|
|
117
|
+
refused instead, and the run corrects the model as for a reply with no
|
|
118
|
+
envelope (a `retry` event of kind `termination`, or `provider` for a
|
|
119
|
+
rejection). An older
|
|
120
|
+
`@niscorp/signal`, without `refuseCutOff`, ignores the option.
|
|
121
|
+
|
|
109
122
|
---
|
|
110
123
|
|
|
111
124
|
## defineAgent
|
|
@@ -143,6 +156,10 @@ got the same answer as the call before it n times in a row — the same
|
|
|
143
156
|
tool, the same arguments, the same result or error — which is n + 1
|
|
144
157
|
identical calls.
|
|
145
158
|
|
|
159
|
+
Stop conditions are checked before each step; a model call that
|
|
160
|
+
stalls runs until it ends or the run is aborted. To bound a call's
|
|
161
|
+
wall-clock time, pass `signal: AbortSignal.timeout(ms)`.
|
|
162
|
+
|
|
146
163
|
`policy.tools` lists take tool **ids** (`tool.id`), not the names
|
|
147
164
|
the model calls: a name in `deny` or `requireApproval` matches
|
|
148
165
|
nothing and says nothing, and a name in `allow` leaves the tool off
|
|
@@ -153,10 +170,17 @@ the list.
|
|
|
153
170
|
and a tool whose name is not in it is not offered on that step. The
|
|
154
171
|
`respond` tool cannot be masked.
|
|
155
172
|
|
|
173
|
+
`prepareStep`'s `llm` replaces the model for that step. The step is
|
|
174
|
+
still sent the output strategy resolved for the run's own `llm` — its
|
|
175
|
+
`response_format` under `native`, its `respond` tool — so the model
|
|
176
|
+
swapped in must take that strategy.
|
|
177
|
+
|
|
156
178
|
`transport: 'step'` calls the model without streaming: the run emits
|
|
157
179
|
no `model-delta`, `output-delta` or `output-partial`. It is for a
|
|
158
180
|
provider and model pair that assembles tool-call arguments more
|
|
159
|
-
reliably outside streaming. The default is `'stream'`.
|
|
181
|
+
reliably outside streaming. The default is `'stream'`. Under either
|
|
182
|
+
transport the model call is handed the run's abort signal, and a run
|
|
183
|
+
aborted during the call ends with `code: 'aborted'`.
|
|
160
184
|
|
|
161
185
|
Multi-turn history is caller-owned: `input` accepts a `string`, a
|
|
162
186
|
`Message[]` transcript, or any JSON value.
|
|
@@ -211,8 +235,13 @@ const result = await run.result; // the no-streaming opt-out
|
|
|
211
235
|
is best-effort: a run emits none when Solid cannot follow the
|
|
212
236
|
schema or the text, and the run's result is validated on its own
|
|
213
237
|
either way.
|
|
214
|
-
- `
|
|
215
|
-
|
|
238
|
+
- Under `respond`, an answer the model writes as message text instead
|
|
239
|
+
of calling `respond` streams no `output-delta` or `output-partial`;
|
|
240
|
+
the result is the same.
|
|
241
|
+
- `run.events` replays from `run-start` to any iterator, so a handle
|
|
242
|
+
keeps every event until it is dropped; drop handles you no longer
|
|
243
|
+
read.
|
|
244
|
+
- `retry` resets partial-output state. Its `kind` says what is retried: `output` — an envelope
|
|
216
245
|
arrived and was refused; `termination` — the step ended with no
|
|
217
246
|
envelope in it; `provider` — the provider rejected the model's
|
|
218
247
|
attempt on its side. Only `output` counts against `outputRetries`,
|
|
@@ -230,6 +259,17 @@ a tool error the model reacts to; the run continues. They run in
|
|
|
230
259
|
order — the `policy` gate, the agent's `toolGates`, the manifold's
|
|
231
260
|
`gates`, the run's `gates` — and the first deny ends the chain.
|
|
232
261
|
|
|
262
|
+
`onToolResult` hooks run **after** every call that was executed,
|
|
263
|
+
whether it returned, threw or passed its time limit, in order — the
|
|
264
|
+
agent's, then the run's. A hook that returns `{ result }` replaces
|
|
265
|
+
what the model and `tool-end` get: on an `error` observation it
|
|
266
|
+
replaces the error text, so `(o) => ({ result: '[redacted]' })` turns
|
|
267
|
+
`connect failed: postgres://admin:hunter2@…` into `error: [redacted]`.
|
|
268
|
+
A hook that throws turns the call into an error carrying the hook's
|
|
269
|
+
message. A hook that should touch results only checks
|
|
270
|
+
`observation.kind`. Hooks do not run for a denied call, an unknown
|
|
271
|
+
tool, or arguments that failed the tool's input check.
|
|
272
|
+
|
|
233
273
|
```ts
|
|
234
274
|
type GateDecision =
|
|
235
275
|
| { allow: true; args?: unknown } // optionally rewrite args
|
|
@@ -260,6 +300,18 @@ ask under it, and `approve` or `deny` with it does nothing.
|
|
|
260
300
|
The resumed run keeps the snapshot's run id, transcript, step and
|
|
261
301
|
output-retry counts, usage and elapsed time, so `stepCount`, `tokens`,
|
|
262
302
|
`duration` and `outputRetries` count on from there.
|
|
303
|
+
A run aborted between the calls of one step leaves calls with no
|
|
304
|
+
answer and no pending approval. Resumed, it first runs those calls,
|
|
305
|
+
through their gates, approvals and hooks, and then calls the model.
|
|
306
|
+
A fresh `agent.run()` given a transcript that ends in a call runs
|
|
307
|
+
nothing before the model. A call still running when the snapshot was
|
|
308
|
+
taken has no answer yet either, so it runs again on resume: take the
|
|
309
|
+
snapshot after its `tool-end`, or make the tool safe to run twice.
|
|
310
|
+
A snapshot that cannot be resumed — no `messages` list, or a
|
|
311
|
+
`pending` without its `call` or its `remaining` list — makes
|
|
312
|
+
`resumeRun` throw `[cortex:config] snapshot cannot be resumed: …`,
|
|
313
|
+
naming what is wrong. Everything else is read as before: a missing or
|
|
314
|
+
`null` count starts at 0, and a `null` `pending` means none.
|
|
263
315
|
`policy.approvalTimeoutMs` turns an unanswered ask into a denial
|
|
264
316
|
(an observation, not a run failure). The denial's `reason` is
|
|
265
317
|
`approval timeout`.
|
|
@@ -297,7 +349,19 @@ const orchestrator = defineAgent({
|
|
|
297
349
|
|
|
298
350
|
The child's envelope maps to the tool result (`data` if present, else
|
|
299
351
|
`response`; override with `select`), and its events nest in the
|
|
300
|
-
parent stream.
|
|
352
|
+
parent stream. The child runs on the delegating call's `ctx.signal`:
|
|
353
|
+
it stops when the parent run is aborted or when the delegation passes
|
|
354
|
+
its time limit (`timeoutMs`, 300 s by default).
|
|
355
|
+
|
|
356
|
+
An approval the child asks is answered through the parent's handle:
|
|
357
|
+
`run.approve(id)` or `run.deny(id)` on the parent, with the id of
|
|
358
|
+
the nested `approval-required` event, reaches the child, at any depth.
|
|
359
|
+
An answer through the child's own handle (the manifold's `onRun`)
|
|
360
|
+
works too; the first answer counts. This lasts while the parent runs:
|
|
361
|
+
the parent's snapshot carries no nested approval, so it does not
|
|
362
|
+
survive a reload. A delegated agent runs under its own `policy` and
|
|
363
|
+
`toolGates` and, through `manifold.asTool`, the manifold's `gates`;
|
|
364
|
+
not the parent run's `gates`.
|
|
301
365
|
|
|
302
366
|
A tool that runs an agent itself gets the same nesting from the
|
|
303
367
|
context `execute` is handed: `agent.run(input, { onEvent:
|
|
@@ -305,6 +369,15 @@ ctx.forward, agentPath: ctx.agentPath })`. `forward` puts the child's
|
|
|
305
369
|
events on the parent's stream, and the child appends its own id to
|
|
306
370
|
the path it is given.
|
|
307
371
|
|
|
372
|
+
To answer its approvals through the parent's handle as well, pass
|
|
373
|
+
the child's handle on and stop when it is done:
|
|
374
|
+
|
|
375
|
+
```ts
|
|
376
|
+
const handle = agent.run(input, { onEvent: ctx.forward, agentPath: ctx.agentPath, signal: ctx.signal });
|
|
377
|
+
const stopForwarding = ctx.forwardApprovals?.(handle);
|
|
378
|
+
const result = await handle.result.finally(() => stopForwarding?.());
|
|
379
|
+
```
|
|
380
|
+
|
|
308
381
|
---
|
|
309
382
|
|
|
310
383
|
## preview
|
|
@@ -325,12 +398,15 @@ Anything you can't explain in the preview, the model can't either.
|
|
|
325
398
|
|
|
326
399
|
## Errors
|
|
327
400
|
|
|
328
|
-
Programmer errors throw at definition
|
|
329
|
-
|
|
401
|
+
Programmer errors throw at definition or registration time, or from
|
|
402
|
+
`run()` when they depend on the run's options: no `llm`, a tool id
|
|
403
|
+
or name used twice across the agent's and the run's tools, a tool
|
|
404
|
+
named `respond`. `resumeRun` throws for a snapshot of another agent
|
|
405
|
+
or one it cannot resume. Runtime conditions return:
|
|
330
406
|
|
|
331
407
|
```ts
|
|
332
408
|
type CortexError = {
|
|
333
|
-
code: 'model_call_failed' | '
|
|
409
|
+
code: 'model_call_failed' | 'stopped' | 'aborted' | 'unknown';
|
|
334
410
|
stop?: 'steps' | 'tokens' | 'duration' | 'output_retries' | 'repeated_calls' | 'custom';
|
|
335
411
|
message: string;
|
|
336
412
|
runId: string;
|
|
@@ -341,6 +417,14 @@ type CortexError = {
|
|
|
341
417
|
Tool failures are **observations**, not exceptions — the model sees
|
|
342
418
|
them and decides; the run fails only on structural conditions.
|
|
343
419
|
|
|
420
|
+
A tool call that passes its time limit (`timeoutMs`, 30 s by default)
|
|
421
|
+
ends in an `error` observation, `tool <id> timed out after <n>ms`,
|
|
422
|
+
and its `ctx.signal` aborts, with an `AbortError` as when the run is
|
|
423
|
+
aborted. A tool that hands `ctx.signal` to what it starts — a fetch,
|
|
424
|
+
a delegated agent — stops there; a tool that ignores it runs on, and
|
|
425
|
+
what it returns is dropped. Each call has its own `ctx.signal`: once
|
|
426
|
+
the call has ended, it no longer aborts with the run.
|
|
427
|
+
|
|
344
428
|
A tool's `input` schema validates; it does not convert. It does two
|
|
345
429
|
jobs: the model is sent its JSON Schema, taken from the schema's
|
|
346
430
|
output side, and a call's arguments are parsed with it twice — by the
|