@niscorp/cortex 0.1.6 → 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 +69 -0
- package/DESIGN.md +53 -107
- package/README.md +102 -18
- 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/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,74 @@
|
|
|
1
1
|
# @niscorp/cortex
|
|
2
2
|
|
|
3
|
+
## 0.2.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 48138de: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app has an `onToolResult` hook that does not check `observation.kind` and relied on it running for successful calls only.
|
|
8
|
+
|
|
9
|
+
`onToolResult` hooks now run after every executed tool call, also when the tool threw or passed its time limit; before, they ran only when it returned. On an `error` observation a hook's `{ result }` replaces the error text that goes to the model and to `tool-end`: a tool that throws `connect failed: postgres://admin:hunter2@…` reached the model as written, and with a redacting hook `(o) => ({ result: '[redacted]' })` it now reaches it as `error: [redacted]`. A hook that throws makes the call an error carrying the hook's message, as for a result. A hook that returns early unless `observation.kind === 'result'` sees no difference. Hooks still do not run for a denied call, an unknown tool, or arguments that failed the input check.
|
|
10
|
+
|
|
11
|
+
- da3037e: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app listens to `output-partial` and relied on an agent with such a data schema sending none, or fewer.
|
|
12
|
+
|
|
13
|
+
More agents stream `output-partial` events, through the newer `@niscorp/solid` cortex uses for them. An agent whose data schema has a field with a constraint (`.min(1)`, `.positive()`, an email or url format), a `z.record` or a `z.lazy` (a recursive schema) emitted no `output-partial` for the whole run, and now emits them as the reply arrives. One with a field that takes any value (`z.record(z.string(), z.unknown())`, `z.any()`) stopped emitting at the first value nested inside that field, and now goes on to the end of the reply. A union field whose value only a later variant takes is kept in the partials instead of dropped. As before, a partial's value can fail the schema until the run ends, and the run's result is checked as before. Measured over real app schemas: a screen builder goes from 0 to 27 events per answer and a nova layout from 0 to 20; a run handle keeps the extra events until it is dropped.
|
|
14
|
+
|
|
15
|
+
- e957628: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app relied on `run.approve` or `run.deny` on a parent run's handle doing nothing for an approval its delegated agent asked.
|
|
16
|
+
|
|
17
|
+
An approval asked inside a delegated agent (`asTool`, `manifold.asTool`) is now answered through the parent run's handle: `run.approve(id)` or `run.deny(id)` with the id of the nested `approval-required` event reaches the child, at any depth. Before, it was ignored, and the child waited until the delegation's time limit. An answer through the child's own handle (the manifold's `onRun`) works as before; the first answer counts.
|
|
18
|
+
|
|
19
|
+
`ToolContext` has a new optional member, `forwardApprovals(handle)`, for a tool that runs an agent itself: it passes the parent's answers on to that run and returns a function that stops it. The README shows the three lines. The parent's snapshot carries no nested approval, so a nested approval does not survive a reload; a delegated agent runs under its own policy and gates, not the parent run's `gates`. The README now says both.
|
|
20
|
+
|
|
21
|
+
- efd2368: BREAKING — approved by moccadroid (owner), 2026-11-22: nothing unless an app passes `resumeRun` a snapshot it cannot resume and relied on how that failed.
|
|
22
|
+
|
|
23
|
+
`resumeRun` now checks the parts of a snapshot a resumed run cannot do without, and throws `[cortex:config] snapshot cannot be resumed: <what is wrong>` when one is missing: a `messages` list, and a `pending` with its `call` and `remaining` list. Before, such a snapshot failed in different ways: a `TypeError` from `resumeRun` with no `messages`, or a run ending `unknown` with `cfg.resumePending.remaining is not iterable`. Every snapshot that resumed still does, `null` in its optional fields included (`pending: null`, `steps: null`).
|
|
24
|
+
|
|
25
|
+
- ca26810: BREAKING — approved by moccadroid (owner), 2026-11-22: an app that takes `run.snapshot()` while a tool is running (from inside the tool, or from an event before its `tool-end`) and resumes that snapshot now runs that call a second time. Take the snapshot after the call's `tool-end`, or make the tool safe to run twice. Nothing else changes unless an app relied on a call left without an answer never running.
|
|
26
|
+
|
|
27
|
+
`resumeRun` now first runs the calls of the snapshot's last step that no tool message answers, through their gates, approvals and hooks, before it calls the model. A run aborted between two calls of one step (`c1` answered, `c2` not) left a transcript ending `assistant(c1, c2) tool[c1]`: resumed, it sent that to the provider and `c2` never ran: OpenAI refuses such a transcript, and Groq takes it (200) and the model goes on without `c2`'s result. Now `c2` runs and the model is sent `tool[c1] tool[c2]`. Any call of that step with no tool message runs, so a call that was still running when the snapshot was taken (a `pay` that calls `run.snapshot()` while it executes) runs again on resume. A resume from a pending approval is unchanged, and a fresh `agent.run()` given a transcript that ends in a call runs nothing before the model, as before.
|
|
28
|
+
|
|
29
|
+
- 322f241: BREAKING — approved by moccadroid (owner), 2026-11-22: a tool or delegated agent that hands `ctx.signal` to work meant to outlive its time limit sets a longer `timeoutMs`, or gives that work a signal of its own.
|
|
30
|
+
|
|
31
|
+
A tool call that passes its time limit (`timeoutMs`) now has its `ctx.signal` aborted, with an `AbortError` as when the run is aborted. A tool that hands `ctx.signal` to its work stops there, instead of running on after the model was told it timed out: a `send_email` that timed out and was called again sent the email twice before, and sends it once now. A tool that ignores `ctx.signal` runs on as before.
|
|
32
|
+
|
|
33
|
+
A delegated agent (`asTool`, `manifold.asTool`) runs on the delegating call's signal, so it now stops at the delegation's time limit instead of finishing after the parent has moved on.
|
|
34
|
+
|
|
35
|
+
Each tool call gets its own `ctx.signal`. It aborts with the run while the call runs; once the call has ended, a later abort of the run no longer reaches it. Gates and `onToolResult` hooks are still handed the run's signal.
|
|
36
|
+
|
|
37
|
+
### Patch Changes
|
|
38
|
+
|
|
39
|
+
- c30562a: `output.refuseCutOff: true` on an agent refuses a reply the provider cut off (finish reason `length` or `content_filter`) while its JSON was still open, and an attempt a Groq rejection (`failed_generation`) carried cut short: the run corrects the model as for a reply with no envelope (a `retry` of kind `termination`, or `provider` for a rejection) instead of accepting the reply closed at its last whole value. Without the option nothing changes. It is passed on to signal's `output.refuseCutOff`; a signal without that option ignores it.
|
|
40
|
+
- 800a541: A run with `transport: 'step'` that is aborted during the model call now ends with `code: 'aborted'` instead of returning the model's answer, and the call is handed the run's abort signal.
|
|
41
|
+
|
|
42
|
+
Two readers iterating `run.events` at the same time (for example the manifold's `onRun` tracer and the app's own loop) now both get every event and both end; before, one of them could wait forever.
|
|
43
|
+
|
|
44
|
+
An approval answered (or a run aborted) before `policy.approvalTimeoutMs` runs out no longer leaves its timer running, so a process does not stay alive until the timeout.
|
|
45
|
+
|
|
46
|
+
A correction sent back to the model quotes the issues word for word: `$$`, `$&` and `$'` in them were rewritten before.
|
|
47
|
+
|
|
48
|
+
The README's quick example no longer runs model-written text with `new Function`, and the docs say that a model swapped in by `prepareStep` is sent the output strategy resolved for the run's own `llm`.
|
|
49
|
+
|
|
50
|
+
A tool that takes no arguments now runs when its call arrives with no argument text, instead of failing with "arguments arrived as ONE STRING".
|
|
51
|
+
|
|
52
|
+
- 9c5367b: An agent whose `output.schema` takes only strings (`z.string()`, with or without checks such as `.min()`) now gets a `data` that reads as JSON as the model wrote it (`"[1,2,3]"`); before, the run ended `stopped` after its output retries. A schema that also takes any other kind of value is handled as before.
|
|
53
|
+
|
|
54
|
+
The README says that stop conditions are checked between steps and how to bound a call's time, that under `respond` an answer written as text streams no partials, that a run handle keeps every event until it is dropped, and which wiring errors `run()` throws. DESIGN says how a step with no envelope is corrected. A tool's `name` is described as the name the model calls. The agent-tool timeout default is one constant.
|
|
55
|
+
|
|
56
|
+
- Updated dependencies [d85bab1]
|
|
57
|
+
- Updated dependencies [aeaf803]
|
|
58
|
+
- Updated dependencies [2b174f8]
|
|
59
|
+
- Updated dependencies [df79faf]
|
|
60
|
+
- Updated dependencies [133c0ee]
|
|
61
|
+
- Updated dependencies [543f79d]
|
|
62
|
+
- Updated dependencies [4f89d7d]
|
|
63
|
+
- Updated dependencies [d951434]
|
|
64
|
+
- Updated dependencies [b210b56]
|
|
65
|
+
- Updated dependencies [f61ffdd]
|
|
66
|
+
- Updated dependencies [88f93c0]
|
|
67
|
+
- Updated dependencies [c5aea8b]
|
|
68
|
+
- Updated dependencies [9899bd7]
|
|
69
|
+
- @niscorp/signal@0.2.0
|
|
70
|
+
- @niscorp/solid@0.2.0
|
|
71
|
+
|
|
3
72
|
## 0.1.6
|
|
4
73
|
|
|
5
74
|
### Patch Changes
|
package/DESIGN.md
CHANGED
|
@@ -9,18 +9,7 @@ calls), [`@niscorp/solid`](../solid) (partial-JSON streaming), and
|
|
|
9
9
|
no `!`, no `enum`, no classes; arrow-const exports with explicit
|
|
10
10
|
return types; kebab-case files with role suffixes; named exports only.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
event-bus substrate, a producer pipeline, a JSON rules engine, and a
|
|
14
|
-
plan-mode interpreter. A full architecture review (2026-07) found:
|
|
15
|
-
every real consumer used only `defineAgent` + `defineTool` +
|
|
16
|
-
`runAgentStandalone`; structured mode never sent the output schema to
|
|
17
|
-
the model; the context prefix was re-templated every iteration
|
|
18
|
-
(cache-hostile); the rules engine and stateful producers were broken
|
|
19
|
-
in ways no consumer had hit because no consumer used them. v2 keeps
|
|
20
|
-
what earned its place — typed tools, gating, observations,
|
|
21
|
-
cross-library agents, context-from-functions, preview — and rebuilds
|
|
22
|
-
the execution core around the pattern the field converged on: one
|
|
23
|
-
tool loop with a typed exit.
|
|
12
|
+
The execution core is one tool loop with a typed exit.
|
|
24
13
|
|
|
25
14
|
---
|
|
26
15
|
|
|
@@ -46,7 +35,7 @@ tool loop with a typed exit.
|
|
|
46
35
|
|
|
47
36
|
**Anti-goals.** No HTTP, no UI, no database, no LLM SDK (signal), no
|
|
48
37
|
JSON-parsing of streams (solid), no event-bus substrate, no
|
|
49
|
-
declarative rules DSL, no plan interpreter
|
|
38
|
+
declarative rules DSL, no plan interpreter, no conversation
|
|
50
39
|
persistence (callers own history).
|
|
51
40
|
|
|
52
41
|
**Peers:** `@niscorp/signal`, `zod`. **Dependency:** `@niscorp/solid`.
|
|
@@ -250,8 +239,8 @@ step:
|
|
|
250
239
|
→ tool-call-delta events → output-delta / output-partial for respond args
|
|
251
240
|
for each tool call, in order:
|
|
252
241
|
tool gates (allow / deny / ask) — BEFORE execution
|
|
253
|
-
execute (Zod-validated input
|
|
254
|
-
onToolResult hooks (replace / redact / truncate)
|
|
242
|
+
execute (Zod-validated input; past timeoutMs the call's ctx.signal aborts)
|
|
243
|
+
onToolResult hooks (replace / redact / truncate), after a result, an error or a timeout
|
|
255
244
|
append tool result message; emit tool-end observation
|
|
256
245
|
respond call → validate envelope → end (or correction + continue)
|
|
257
246
|
```
|
|
@@ -260,14 +249,16 @@ Rules the loop lives by:
|
|
|
260
249
|
|
|
261
250
|
- **Append-only transcript.** The prefix is built once and never
|
|
262
251
|
re-templated. Rule injections, corrections, and budget nudges are
|
|
263
|
-
*appended* messages
|
|
264
|
-
|
|
265
|
-
uncached price on every iteration.
|
|
252
|
+
*appended* messages: a provider caches the prompt prefix, and cached
|
|
253
|
+
input is ~10× cheaper than uncached on the models we run.
|
|
266
254
|
- **Tool calls execute sequentially, in model order.** Deterministic
|
|
267
255
|
gating and event order beat latency here; parallel execution is a
|
|
268
|
-
future knob (§
|
|
256
|
+
future knob (§12).
|
|
269
257
|
- **Tool failures are observations, not exceptions.** A failed or
|
|
270
258
|
denied call becomes an error result the model sees and reacts to.
|
|
259
|
+
A call past its `timeoutMs` is one: the model is told it timed out,
|
|
260
|
+
and the call's own `ctx.signal` aborts so the tool stops rather
|
|
261
|
+
than finish unseen.
|
|
271
262
|
The run only fails on structural conditions (stop limits, model
|
|
272
263
|
call failure, abort, retries exhausted).
|
|
273
264
|
- **A tool's `input` is enforced; its `output` is a type.** The input
|
|
@@ -280,16 +271,18 @@ Rules the loop lives by:
|
|
|
280
271
|
names it was sent, so through Signal a call by id is read as an
|
|
281
272
|
attempted answer and never reaches that table; gates, observations
|
|
282
273
|
and traces always carry the canonical id. Both namespaces must be
|
|
283
|
-
collision-free per run, and nothing may claim `respond`.
|
|
284
|
-
ids on the wire while documenting names — a prompt-literal model
|
|
285
|
-
exposed the lie.)
|
|
274
|
+
collision-free per run, and nothing may claim `respond`.
|
|
286
275
|
- **Streaming is the default.** The loop consumes `signal.stepStream`
|
|
287
276
|
unless the agent sets `transport: 'step'`, which calls `llm.step()`
|
|
288
277
|
and emits no deltas or partials (§11); `await run.result` is the
|
|
289
|
-
consumer's opt-out.
|
|
278
|
+
consumer's opt-out. Either call is handed the run's abort signal,
|
|
279
|
+
and an abort during it ends the run `aborted`.
|
|
280
|
+
- **The transport is resolved once, from the run's `llm`.** A
|
|
281
|
+
`prepareStep` that swaps `llm` sends that step the same transport —
|
|
282
|
+
its `response_format`, its `respond` tool — so the model swapped in
|
|
283
|
+
must take it.
|
|
290
284
|
|
|
291
|
-
Bounds are `stopWhen` predicates — one vocabulary
|
|
292
|
-
maxToolIterations / maxTicks / maxDurationMs / budget tangle:
|
|
285
|
+
Bounds are `stopWhen` predicates — one vocabulary for every limit:
|
|
293
286
|
|
|
294
287
|
```ts
|
|
295
288
|
stopWhen: [stepCount(20), tokens(100_000), duration('5m'), outputRetries(3), repeatedCalls(3)]
|
|
@@ -299,18 +292,18 @@ stopWhen: [stepCount(20), tokens(100_000), duration('5m'), outputRetries(3), rep
|
|
|
299
292
|
call and getting the same answer — every further step would cost a
|
|
300
293
|
full prompt and change nothing.
|
|
301
294
|
|
|
302
|
-
Defaults: `stepCount(20)`, `outputRetries(3)`.
|
|
303
|
-
token cap
|
|
304
|
-
|
|
295
|
+
Defaults: `stepCount(20)`, `outputRetries(3)`. There is no default
|
|
296
|
+
duration or token cap: the right one depends on the agent.
|
|
297
|
+
|
|
298
|
+
A step that ended with no envelope is corrected with `invalidOutput`
|
|
299
|
+
and the router's evidence, which says what was missing.
|
|
305
300
|
|
|
306
301
|
---
|
|
307
302
|
|
|
308
303
|
## 5. Context — producers
|
|
309
304
|
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
machinery (priorities, state, no per-invocation data); the machinery
|
|
313
|
-
is deleted, the concept and the name stay:
|
|
305
|
+
Context comes from PRODUCERS, and how a producer constructs its
|
|
306
|
+
content is irrelevant to cortex:
|
|
314
307
|
|
|
315
308
|
```ts
|
|
316
309
|
// What enters context: one system chunk, several (a producer can emit a
|
|
@@ -370,12 +363,11 @@ that is how knowledge drifts.
|
|
|
370
363
|
hook instead of a rules engine.
|
|
371
364
|
- `input` is `string | Message[] | unknown` (non-message values are
|
|
372
365
|
JSON-stringified into the user turn). Multi-turn history is
|
|
373
|
-
caller-owned and arrives as `Message[]
|
|
374
|
-
the supported path instead of a workaround.
|
|
366
|
+
caller-owned and arrives as `Message[]`.
|
|
375
367
|
- Compaction (summarize-when-near-limit) is a future single hook on
|
|
376
|
-
the transcript (§
|
|
368
|
+
the transcript (§12).
|
|
377
369
|
|
|
378
|
-
**Preview
|
|
370
|
+
**Preview.** `await agent.preview(input, { deps })`
|
|
379
371
|
returns the exact assembled messages, the resolved tool list
|
|
380
372
|
(including `respond` and its actual params), the resolved strategy,
|
|
381
373
|
and a token estimate — no model call. Anything you can't explain in
|
|
@@ -406,8 +398,7 @@ type StopCondition = (s: RunProgress) => StopVerdict; // { stop: StopReason; m
|
|
|
406
398
|
```
|
|
407
399
|
|
|
408
400
|
- **Gates run before execution.** A deny reaches the model as a tool
|
|
409
|
-
error; the run continues.
|
|
410
|
-
— a rule could never stop the call that tripped it.)
|
|
401
|
+
error; the run continues.
|
|
411
402
|
- **Policy sugar** covers the declarative 80%:
|
|
412
403
|
|
|
413
404
|
```ts
|
|
@@ -425,7 +416,10 @@ type StopCondition = (s: RunProgress) => StopVerdict; // { stop: StopReason; m
|
|
|
425
416
|
it; the pending call blocks (tools are sequential, so
|
|
426
417
|
one pending approval at a time). `run.approve(id, { args? })` —
|
|
427
418
|
approve, optionally with edited args — or `run.deny(id, reason)`.
|
|
428
|
-
An id the handle did not ask under
|
|
419
|
+
An id the handle did not ask under goes to the runs its tools
|
|
420
|
+
started and passed on with `ctx.forwardApprovals` (`asTool` and
|
|
421
|
+
`manifold.asTool` do), so a parent's handle answers an approval asked
|
|
422
|
+
at any depth; an id nobody asked under is ignored.
|
|
429
423
|
`run.snapshot()` serializes the suspended run (messages, pending
|
|
430
424
|
call, usage); `resumeRun(agent, snapshot, opts)` restores it — so
|
|
431
425
|
approvals survive reloads and restarts. A resumed run **re-asks**:
|
|
@@ -434,6 +428,10 @@ type StopCondition = (s: RunProgress) => StopVerdict; // { stop: StopReason; m
|
|
|
434
428
|
one the resumed handle answers to. `snapshot.pending.approvalId`
|
|
435
429
|
names the ask of the run the snapshot came from, not the resumed
|
|
436
430
|
one's.
|
|
431
|
+
A snapshot with no pending approval whose last step has calls no
|
|
432
|
+
tool message answers (the run was aborted between them, or the snapshot was taken while one ran) resumes by
|
|
433
|
+
running those calls first; a fresh run never runs calls from its
|
|
434
|
+
input.
|
|
437
435
|
- **Output validation** closes the generate→verify loop in-run:
|
|
438
436
|
|
|
439
437
|
```ts
|
|
@@ -488,10 +486,7 @@ the whole tree. No event carries usage: the run's total is
|
|
|
488
486
|
whole ledger.
|
|
489
487
|
|
|
490
488
|
Process-level watching is the manifold's tap: `onRun(run => …)` hands
|
|
491
|
-
you every run created through it.
|
|
492
|
-
v1 bus had, kept, without the bus. (Precedent: AutoGen v0.4 built the
|
|
493
|
-
bus-first agent substrate; Microsoft retired it within a year for
|
|
494
|
-
plain awaited runs with typed-edge composition.)
|
|
489
|
+
you every run created through it.
|
|
495
490
|
|
|
496
491
|
---
|
|
497
492
|
|
|
@@ -514,15 +509,13 @@ const asToolDef = manifold.asTool('vex.query', { description });
|
|
|
514
509
|
```
|
|
515
510
|
|
|
516
511
|
- `agent.run()` standalone and `manifold.run()` are the same
|
|
517
|
-
function; the manifold merges defaults.
|
|
518
|
-
`runAgentStandalone`.
|
|
512
|
+
function; the manifold merges defaults.
|
|
519
513
|
- Agents may bind their own `llm`; the manifold's is the fallback.
|
|
520
|
-
(The architect's GLM-reasoning / Groq-support split becomes
|
|
521
|
-
configuration.)
|
|
522
514
|
- `asTool(agent, { description?, select? })` wraps an agent as an
|
|
523
515
|
ordinary `ToolDefinition`. Default result mapping: envelope `data`
|
|
524
516
|
if present, else `response`; `select` overrides. Child events
|
|
525
|
-
forward (§7).
|
|
517
|
+
forward (§7). The child runs on the call's `ctx.signal`, so it stops
|
|
518
|
+
at the delegation's `timeoutMs` (300 s by default).
|
|
526
519
|
- Duplicate ids throw at registration. Registration is a Map insert;
|
|
527
520
|
there is no `start`/`stop`/`drain`.
|
|
528
521
|
|
|
@@ -530,7 +523,7 @@ const asToolDef = manifold.asTool('vex.query', { description });
|
|
|
530
523
|
|
|
531
524
|
## 9. Errors
|
|
532
525
|
|
|
533
|
-
|
|
526
|
+
Two principles:
|
|
534
527
|
|
|
535
528
|
1. **Programmer errors throw** at definition/registration time:
|
|
536
529
|
duplicate ids, malformed configs.
|
|
@@ -539,7 +532,7 @@ Same two principles as v1, smaller taxonomy:
|
|
|
539
532
|
|
|
540
533
|
```ts
|
|
541
534
|
type CortexError = {
|
|
542
|
-
code: 'model_call_failed' | '
|
|
535
|
+
code: 'model_call_failed' | 'stopped' | 'aborted' | 'unknown';
|
|
543
536
|
stop?: StopReason; // when code === 'stopped':
|
|
544
537
|
// 'steps' | 'tokens' | 'duration' | 'output_retries' | 'repeated_calls' | 'custom'
|
|
545
538
|
message: string;
|
|
@@ -565,7 +558,7 @@ dependency and powers
|
|
|
565
558
|
progressively-typed envelopes — a chat `response` string streams
|
|
566
559
|
token-ish while it forms inside the JSON, and a Nova screen in `data`
|
|
567
560
|
becomes renderable before the run ends. The `retry` event resets
|
|
568
|
-
partial-output state
|
|
561
|
+
partial-output state.
|
|
569
562
|
|
|
570
563
|
---
|
|
571
564
|
|
|
@@ -574,7 +567,7 @@ partial-output state, same contract as v1's `cortex.agent.retry`.
|
|
|
574
567
|
```ts
|
|
575
568
|
// definition
|
|
576
569
|
defineAgent<TData, TDeps>(config): AgentDefinition<TData, TDeps>
|
|
577
|
-
defineTool(config): ToolDefinition
|
|
570
|
+
defineTool(config): ToolDefinition
|
|
578
571
|
schemaDoc(schema, opts?): string
|
|
579
572
|
|
|
580
573
|
// execution
|
|
@@ -625,6 +618,7 @@ DEFAULT_STOP_CONDITIONS // [stepCount(20), outputRetries(3)]
|
|
|
625
618
|
forceTool?: boolean, // toolChoice:'required' hardening
|
|
626
619
|
doc?: 'auto' | 'off' | string, // schema docs injection, default 'auto'
|
|
627
620
|
validate?: (out) => { ok: true } | { retry: string } | Promise<…>,
|
|
621
|
+
refuseCutOff?: boolean, // a reply the provider cut off with its JSON open is retried, not closed
|
|
628
622
|
},
|
|
629
623
|
toolGates?, onToolResult?, prepareStep?, stopWhen?, policy?,
|
|
630
624
|
}
|
|
@@ -632,55 +626,7 @@ DEFAULT_STOP_CONDITIONS // [stepCount(20), outputRetries(3)]
|
|
|
632
626
|
|
|
633
627
|
---
|
|
634
628
|
|
|
635
|
-
## 12.
|
|
636
|
-
|
|
637
|
-
Items 1–3 are built; the text below is the requirement as it was
|
|
638
|
-
written. The tokenizer in item 4 has not landed.
|
|
639
|
-
|
|
640
|
-
1. **`stepStream` emits `tool-call-delta`** — `{ index, id?, name?,
|
|
641
|
-
argsText }` fragments as function args stream. The SSE chunks
|
|
642
|
-
already contain them; the adapter currently drops them. This is
|
|
643
|
-
the enabler for `respond`-strategy streaming and solid, and is
|
|
644
|
-
built first.
|
|
645
|
-
2. **`StepRequest.responseFormat`** passthrough (json_schema /
|
|
646
|
-
json_object) for the `native` strategy.
|
|
647
|
-
3. **Capabilities truth.** Groq `nativeTools: true` (stale since the
|
|
648
|
-
registry was written; ray proves it daily). New capability:
|
|
649
|
-
`toolsWithStructuredOutput: boolean` — encodes the
|
|
650
|
-
can't-combine-format-and-tools constraint that shaped §3.
|
|
651
|
-
4. Later, not blocking: signal's own `complete()` tool loop can slim
|
|
652
|
-
once cortex is the loop owner; real tokenizer behind `count()`.
|
|
653
|
-
|
|
654
|
-
---
|
|
655
|
-
|
|
656
|
-
## 13. What v2 deletes from v1
|
|
657
|
-
|
|
658
|
-
| Deleted | Why |
|
|
659
|
-
|---|---|
|
|
660
|
-
| Event bus, topics, wildcard matching, typed-topic | substrate carried no load; per-run event streams + `onRun` cover the real uses |
|
|
661
|
-
| Rules engine (watch/when/then, accumulators, effects) | underpowered (counter thresholds), broken (global un-reset state, dead `call`, `deny`-all-forever, duplicating `inject`), post-hoc by construction; gates + `prepareStep` replace it |
|
|
662
|
-
| Plan mode: ActionPlan schema, plan executor, node handlers, tick loop | ~830 lines duplicating what the tool loop does, fed by fragile text parse; delegation is `asTool`; revisit as a todo/recitation tool if ever needed (§15) |
|
|
663
|
-
| Producer pipeline: priorities, eviction, compressors, token modes, producer state, stores | fought its consumers (no deps param), features unreachable or fake (`exact` mode ≡ fuzzy, per-producer compress unreachable, stateful producers had no read path) |
|
|
664
|
-
| Manifold lifecycle (`start`/`stop`/`drain`), ledger object, state store, event log | decorative or folded into run meta/events |
|
|
665
|
-
| `runAgentStandalone` | `agent.run()` is the standalone path |
|
|
666
|
-
| Full-loop validation retries | in-loop corrections (§3.1) |
|
|
667
|
-
|
|
668
|
-
---
|
|
669
|
-
|
|
670
|
-
## 14. Plan mode, revisited later — the record
|
|
671
|
-
|
|
672
|
-
v1 bet on model-emitted ActionPlans executed by a runtime. The field
|
|
673
|
-
data: BabyAGI (the pattern's origin) is archived; AutoGPT pivoted
|
|
674
|
-
away; every mainstream SDK (OpenAI Agents, Vercel, Pydantic AI,
|
|
675
|
-
Mastra) ships a native tool loop with code-first composition; the
|
|
676
|
-
survivors of "planning" are recitation todo-lists the model itself
|
|
677
|
-
maintains in-loop (Manus todo.md, Claude Code TodoWrite). If explicit
|
|
678
|
-
planning returns to cortex it returns as that: a small todo tool plus
|
|
679
|
-
a context entry, on top of the loop — not an interpreter under it.
|
|
680
|
-
|
|
681
|
-
---
|
|
682
|
-
|
|
683
|
-
## 15. Future work (known, deferred)
|
|
629
|
+
## 12. Future work (known, deferred)
|
|
684
630
|
|
|
685
631
|
- **Compaction** — one hook: summarize the transcript when a token
|
|
686
632
|
threshold nears, keep the prefix stable. Field-standard; not needed
|
|
@@ -694,14 +640,13 @@ a context entry, on top of the loop — not an interpreter under it.
|
|
|
694
640
|
- **Exact token counting** — behind `signal.count()` when a real
|
|
695
641
|
tokenizer lands.
|
|
696
642
|
- **`respond` vs `emit` A/B** on the big-DSL agents (prism mapping,
|
|
697
|
-
nova layout
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
comparison was never run.
|
|
643
|
+
nova layout). `auto` resolves them to `emit` by rule — their
|
|
644
|
+
schemas are too large for enforcing respond params — and the two
|
|
645
|
+
have not been compared on output quality.
|
|
701
646
|
|
|
702
647
|
---
|
|
703
648
|
|
|
704
|
-
##
|
|
649
|
+
## 13. Source layout
|
|
705
650
|
|
|
706
651
|
```
|
|
707
652
|
src/
|
|
@@ -715,7 +660,8 @@ src/
|
|
|
715
660
|
│
|
|
716
661
|
├── agent/
|
|
717
662
|
│ ├── define-agent.ts
|
|
718
|
-
│ ├── run.ts # RunHandle, resumeRun
|
|
663
|
+
│ ├── run.ts # RunHandle, resumeRun
|
|
664
|
+
│ ├── prefix.ts # transport resolution and prefix assembly, shared with preview
|
|
719
665
|
│ └── preview.ts
|
|
720
666
|
│
|
|
721
667
|
├── loop/
|
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
|
|
|
@@ -90,7 +90,11 @@ How the envelope travels from model to runtime. One field,
|
|
|
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
|