@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 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
- This is the second design. The first (see git history) built an
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 (§14), no conversation
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, timeout)
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. This is the KV-cache lesson: on the models we
264
- run, cached input is ~10× cheaper than uncached, and v1 paid the
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 (§15).
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`. (v1 sent
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 instead of v1's
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)`. No default duration or
303
- token cap — v1's 60-second default was overridden at every call site,
304
- which is what a wrong default looks like.
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
- The v1 producer insight was right — context comes from PRODUCERS,
311
- and how a producer constructs its content is irrelevant. v1 failed on
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[]` — ray's transcript becomes
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 (§15), not a v1 pipeline.
368
+ the transcript (§12).
377
369
 
378
- **Preview survives, better.** `await agent.preview(input, { deps })`
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. (v1 evaluated rules after the observation
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 is ignored.
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. That is the one legitimate job the
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. There is no
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
- Same two principles as v1, smaller taxonomy:
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' | 'output_invalid' | 'stopped' | 'aborted' | 'unknown';
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, same contract as v1's `cortex.agent.retry`.
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 // v1 shape, kept
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. Signal changes this design requires
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, architect). Settled by RULE, not by measurement
698
- (2026-09-24): their schemas are too large for enforcing respond
699
- params, so `auto` resolves them to `emit` everywhere. The quality
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
- ## 16. Source layout
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, prefix assembly
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 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
 
@@ -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. 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