@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/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 calculator = defineTool({
30
- id: 'calculator',
31
- name: 'calculator',
32
- description: 'Evaluates a simple arithmetic expression.',
33
- input: z.object({ expression: z.string() }),
34
- execute: ({ expression }) => new Function(`return (${expression})`)(),
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 calculator tool, then give the answer.',
41
- tools: [calculator],
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 (2 + 3) * 7 - 6?', { llm }).result;
48
- if (result.ok) console.log(result.output.data.answer); // 29
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 | small strict-compatible schemas on capable providers (auto-picked) |
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. Invalid output feeds back as a
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
- - `retry` resets partial-output state (same contract consumers had
215
- in v1). Its `kind` says what is retried: `output` — an envelope
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/registration time. Runtime
329
- conditions return:
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' | 'output_invalid' | 'stopped' | 'aborted' | 'unknown';
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