@niscorp/cortex 0.1.5 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,85 @@
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
+
72
+ ## 0.1.6
73
+
74
+ ### Patch Changes
75
+
76
+ - 41ac0c7: DESIGN.md and the README say what the code does: the loop streams unless `transport: 'step'`, no event carries per-step usage, the schema check is conversion, no `$ref` and at most 8,192 characters (native also needs `nativeJsonSchema` and is sent with `strict: false`), `onRun` is an option of `createManifold`, and `agent.run` takes `agentPath`.
77
+
78
+ **What to change:** nothing. Documentation only.
79
+
80
+ - Updated dependencies [a2d2df0]
81
+ - @niscorp/solid@0.1.3
82
+
3
83
  ## 0.1.5
4
84
 
5
85
  ### 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`.
@@ -88,7 +77,7 @@ type RunResult<TData> =
88
77
  | { ok: false; error: CortexError; meta: RunMeta };
89
78
 
90
79
  type RunMeta = {
91
- usage: Usage; // aggregated; per-step usage rides on events
80
+ usage: Usage; // the run's total; no event carries per-step usage
92
81
  strategy: OutputStrategy; // what actually ran
93
82
  steps: number;
94
83
  outputRetries: number;
@@ -134,9 +123,9 @@ at most syntax; cortex enforces the contract.
134
123
 
135
124
  Cortex registers one synthetic tool per run:
136
125
 
137
- - **Params, auto-detailed.** If the serialized `data` schema is
138
- strict-compatible (no recursion, no open records, no refinements)
139
- and small (≤ ~8 KB serialized), it is inlined into the tool params.
126
+ - **Params, auto-detailed.** If the envelope schema with `data`
127
+ converts to JSON Schema, contains no `$ref` and serializes to at
128
+ most 8,192 characters, it is inlined into the tool params.
140
129
  Otherwise params are loose (`data: object, see OUTPUT SCHEMA in the
141
130
  system prompt`) and the schema documentation is injected into
142
131
  context (§3.4). This is what makes Prism's `NodeSchema` and Nova's
@@ -196,11 +185,13 @@ Cortex registers one synthetic tool per run:
196
185
 
197
186
  ### 3.2 `native`
198
187
 
199
- `auto` picks it only when the provider capability
200
- `toolsWithStructuredOutput` is true (or the agent has no tools) AND
201
- the envelope schema passes the strict-compatibility walk. Small
202
- extractors and classifiers on OpenAI-class providers land here and
203
- get grammar-level enforcement for free.
188
+ `auto` picks it only when the agent has an output schema, the model
189
+ capability `nativeJsonSchema` is true, `toolsWithStructuredOutput` is
190
+ true (or the agent has no tools) AND the envelope schema passes the
191
+ same check as `respond`'s inlined params (converts, no `$ref`, ≤ 8,192
192
+ characters). The schema is sent as `response_format` with
193
+ `strict: false`. Small extractors and classifiers on OpenAI-class
194
+ providers land here.
204
195
 
205
196
  ### 3.3 `emit`
206
197
 
@@ -248,8 +239,8 @@ step:
248
239
  → tool-call-delta events → output-delta / output-partial for respond args
249
240
  for each tool call, in order:
250
241
  tool gates (allow / deny / ask) — BEFORE execution
251
- execute (Zod-validated input, timeout)
252
- 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
253
244
  append tool result message; emit tool-end observation
254
245
  respond call → validate envelope → end (or correction + continue)
255
246
  ```
@@ -258,14 +249,16 @@ Rules the loop lives by:
258
249
 
259
250
  - **Append-only transcript.** The prefix is built once and never
260
251
  re-templated. Rule injections, corrections, and budget nudges are
261
- *appended* messages. This is the KV-cache lesson: on the models we
262
- run, cached input is ~10× cheaper than uncached, and v1 paid the
263
- 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.
264
254
  - **Tool calls execute sequentially, in model order.** Deterministic
265
255
  gating and event order beat latency here; parallel execution is a
266
- future knob (§15).
256
+ future knob (§12).
267
257
  - **Tool failures are observations, not exceptions.** A failed or
268
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.
269
262
  The run only fails on structural conditions (stop limits, model
270
263
  call failure, abort, retries exhausted).
271
264
  - **A tool's `input` is enforced; its `output` is a type.** The input
@@ -278,15 +271,18 @@ Rules the loop lives by:
278
271
  names it was sent, so through Signal a call by id is read as an
279
272
  attempted answer and never reaches that table; gates, observations
280
273
  and traces always carry the canonical id. Both namespaces must be
281
- collision-free per run, and nothing may claim `respond`. (v1 sent
282
- ids on the wire while documenting names — a prompt-literal model
283
- exposed the lie.)
284
- - **Streaming is not a mode.** The loop always consumes
285
- `signal.stepStream`; `await run.result` is the opt-out. There is no
286
- `stream: true` bifurcation to test twice.
287
-
288
- Bounds are `stopWhen` predicates — one vocabulary instead of v1's
289
- maxToolIterations / maxTicks / maxDurationMs / budget tangle:
274
+ collision-free per run, and nothing may claim `respond`.
275
+ - **Streaming is the default.** The loop consumes `signal.stepStream`
276
+ unless the agent sets `transport: 'step'`, which calls `llm.step()`
277
+ and emits no deltas or partials (§11); `await run.result` is the
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.
284
+
285
+ Bounds are `stopWhen` predicates — one vocabulary for every limit:
290
286
 
291
287
  ```ts
292
288
  stopWhen: [stepCount(20), tokens(100_000), duration('5m'), outputRetries(3), repeatedCalls(3)]
@@ -296,18 +292,18 @@ stopWhen: [stepCount(20), tokens(100_000), duration('5m'), outputRetries(3), rep
296
292
  call and getting the same answer — every further step would cost a
297
293
  full prompt and change nothing.
298
294
 
299
- Defaults: `stepCount(20)`, `outputRetries(3)`. No default duration or
300
- token cap — v1's 60-second default was overridden at every call site,
301
- 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.
302
300
 
303
301
  ---
304
302
 
305
303
  ## 5. Context — producers
306
304
 
307
- The v1 producer insight was right — context comes from PRODUCERS,
308
- and how a producer constructs its content is irrelevant. v1 failed on
309
- machinery (priorities, state, no per-invocation data); the machinery
310
- 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:
311
307
 
312
308
  ```ts
313
309
  // What enters context: one system chunk, several (a producer can emit a
@@ -367,12 +363,11 @@ that is how knowledge drifts.
367
363
  hook instead of a rules engine.
368
364
  - `input` is `string | Message[] | unknown` (non-message values are
369
365
  JSON-stringified into the user turn). Multi-turn history is
370
- caller-owned and arrives as `Message[]` — ray's transcript becomes
371
- the supported path instead of a workaround.
366
+ caller-owned and arrives as `Message[]`.
372
367
  - Compaction (summarize-when-near-limit) is a future single hook on
373
- the transcript (§15), not a v1 pipeline.
368
+ the transcript (§12).
374
369
 
375
- **Preview survives, better.** `await agent.preview(input, { deps })`
370
+ **Preview.** `await agent.preview(input, { deps })`
376
371
  returns the exact assembled messages, the resolved tool list
377
372
  (including `respond` and its actual params), the resolved strategy,
378
373
  and a token estimate — no model call. Anything you can't explain in
@@ -403,8 +398,7 @@ type StopCondition = (s: RunProgress) => StopVerdict; // { stop: StopReason; m
403
398
  ```
404
399
 
405
400
  - **Gates run before execution.** A deny reaches the model as a tool
406
- error; the run continues. (v1 evaluated rules after the observation
407
- — a rule could never stop the call that tripped it.)
401
+ error; the run continues.
408
402
  - **Policy sugar** covers the declarative 80%:
409
403
 
410
404
  ```ts
@@ -422,7 +416,10 @@ type StopCondition = (s: RunProgress) => StopVerdict; // { stop: StopReason; m
422
416
  it; the pending call blocks (tools are sequential, so
423
417
  one pending approval at a time). `run.approve(id, { args? })` —
424
418
  approve, optionally with edited args — or `run.deny(id, reason)`.
425
- 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.
426
423
  `run.snapshot()` serializes the suspended run (messages, pending
427
424
  call, usage); `resumeRun(agent, snapshot, opts)` restores it — so
428
425
  approvals survive reloads and restarts. A resumed run **re-asks**:
@@ -431,6 +428,10 @@ type StopCondition = (s: RunProgress) => StopVerdict; // { stop: StopReason; m
431
428
  one the resumed handle answers to. `snapshot.pending.approvalId`
432
429
  names the ask of the run the snapshot came from, not the resumed
433
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.
434
435
  - **Output validation** closes the generate→verify loop in-run:
435
436
 
436
437
  ```ts
@@ -445,8 +446,9 @@ type StopCondition = (s: RunProgress) => StopVerdict; // { stop: StopReason; m
445
446
  hand-rolled verify-once harness bolt-on.)
446
447
 
447
448
  What hooks deliberately can't do: react to *other* runs (cross-run
448
- choreography is app code around `manifold.onRun`), mutate past
449
- transcript (append-only is load-bearing), veto text mid-generation
449
+ choreography is app code in the `onRun` option of
450
+ `createManifold`), mutate past transcript (append-only is
451
+ load-bearing), veto text mid-generation
450
452
  (validation happens at boundaries: tool call, step end, output). If
451
453
  remotely-configured steering is ever needed, it lands as a compiler
452
454
  from a config shape *to* a gate function — on top, not underneath.
@@ -479,14 +481,12 @@ const result = await run.result;
479
481
  Every event carries `{ runId, agentPath, seq, ts }`. When an agent
480
482
  runs inside another (`asTool`), the child's events forward into the
481
483
  parent stream with the extended `agentPath` — one subscription sees
482
- the whole tree. Per-step usage rides on step events and aggregates
483
- into `RunMeta.usage`; that is the whole ledger.
484
+ the whole tree. No event carries usage: the run's total is
485
+ `RunMeta.usage`, which `run-end` carries in its `meta`; that is the
486
+ whole ledger.
484
487
 
485
488
  Process-level watching is the manifold's tap: `onRun(run => …)` hands
486
- you every run created through it. That is the one legitimate job the
487
- v1 bus had, kept, without the bus. (Precedent: AutoGen v0.4 built the
488
- bus-first agent substrate; Microsoft retired it within a year for
489
- plain awaited runs with typed-edge composition.)
489
+ you every run created through it.
490
490
 
491
491
  ---
492
492
 
@@ -509,15 +509,13 @@ const asToolDef = manifold.asTool('vex.query', { description });
509
509
  ```
510
510
 
511
511
  - `agent.run()` standalone and `manifold.run()` are the same
512
- function; the manifold merges defaults. There is no
513
- `runAgentStandalone`.
512
+ function; the manifold merges defaults.
514
513
  - Agents may bind their own `llm`; the manifold's is the fallback.
515
- (The architect's GLM-reasoning / Groq-support split becomes
516
- configuration.)
517
514
  - `asTool(agent, { description?, select? })` wraps an agent as an
518
515
  ordinary `ToolDefinition`. Default result mapping: envelope `data`
519
516
  if present, else `response`; `select` overrides. Child events
520
- 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).
521
519
  - Duplicate ids throw at registration. Registration is a Map insert;
522
520
  there is no `start`/`stop`/`drain`.
523
521
 
@@ -525,7 +523,7 @@ const asToolDef = manifold.asTool('vex.query', { description });
525
523
 
526
524
  ## 9. Errors
527
525
 
528
- Same two principles as v1, smaller taxonomy:
526
+ Two principles:
529
527
 
530
528
  1. **Programmer errors throw** at definition/registration time:
531
529
  duplicate ids, malformed configs.
@@ -534,7 +532,7 @@ Same two principles as v1, smaller taxonomy:
534
532
 
535
533
  ```ts
536
534
  type CortexError = {
537
- code: 'model_call_failed' | 'output_invalid' | 'stopped' | 'aborted' | 'unknown';
535
+ code: 'model_call_failed' | 'stopped' | 'aborted' | 'unknown';
538
536
  stop?: StopReason; // when code === 'stopped':
539
537
  // 'steps' | 'tokens' | 'duration' | 'output_retries' | 'repeated_calls' | 'custom'
540
538
  message: string;
@@ -553,13 +551,14 @@ principle as every other tool denial.
553
551
 
554
552
  ## 10. Streaming
555
553
 
556
- Always on (§4). Solid is a dependency and powers
554
+ On unless the agent sets `transport: 'step'` (§4). Solid is a
555
+ dependency and powers
557
556
  `output-partial`: `respond` arg deltas (or content deltas under
558
557
  `native`/`emit`) stream through solid's partial parser into
559
558
  progressively-typed envelopes — a chat `response` string streams
560
559
  token-ish while it forms inside the JSON, and a Nova screen in `data`
561
560
  becomes renderable before the run ends. The `retry` event resets
562
- partial-output state, same contract as v1's `cortex.agent.retry`.
561
+ partial-output state.
563
562
 
564
563
  ---
565
564
 
@@ -568,11 +567,11 @@ partial-output state, same contract as v1's `cortex.agent.retry`.
568
567
  ```ts
569
568
  // definition
570
569
  defineAgent<TData, TDeps>(config): AgentDefinition<TData, TDeps>
571
- defineTool(config): ToolDefinition // v1 shape, kept
570
+ defineTool(config): ToolDefinition
572
571
  schemaDoc(schema, opts?): string
573
572
 
574
573
  // execution
575
- agent.run(input, { deps, llm?, tools?, producers?, gates?, onToolResult?, onEvent?, signal? }): RunHandle<TData>
574
+ agent.run(input, { deps, llm?, tools?, producers?, gates?, onToolResult?, onEvent?, signal?, agentPath? }): RunHandle<TData>
576
575
  // tools: per-run tools whose execute closes over per-invocation
577
576
  // dependencies (vex builds its query tools around the caller's
578
577
  // adapter + schema); appended to the agent's static tools.
@@ -619,6 +618,7 @@ DEFAULT_STOP_CONDITIONS // [stepCount(20), outputRetries(3)]
619
618
  forceTool?: boolean, // toolChoice:'required' hardening
620
619
  doc?: 'auto' | 'off' | string, // schema docs injection, default 'auto'
621
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
622
622
  },
623
623
  toolGates?, onToolResult?, prepareStep?, stopWhen?, policy?,
624
624
  }
@@ -626,55 +626,7 @@ DEFAULT_STOP_CONDITIONS // [stepCount(20), outputRetries(3)]
626
626
 
627
627
  ---
628
628
 
629
- ## 12. Signal changes this design requires
630
-
631
- Items 1–3 are built; the text below is the requirement as it was
632
- written. The tokenizer in item 4 has not landed.
633
-
634
- 1. **`stepStream` emits `tool-call-delta`** — `{ index, id?, name?,
635
- argsText }` fragments as function args stream. The SSE chunks
636
- already contain them; the adapter currently drops them. This is
637
- the enabler for `respond`-strategy streaming and solid, and is
638
- built first.
639
- 2. **`StepRequest.responseFormat`** passthrough (json_schema /
640
- json_object) for the `native` strategy.
641
- 3. **Capabilities truth.** Groq `nativeTools: true` (stale since the
642
- registry was written; ray proves it daily). New capability:
643
- `toolsWithStructuredOutput: boolean` — encodes the
644
- can't-combine-format-and-tools constraint that shaped §3.
645
- 4. Later, not blocking: signal's own `complete()` tool loop can slim
646
- once cortex is the loop owner; real tokenizer behind `count()`.
647
-
648
- ---
649
-
650
- ## 13. What v2 deletes from v1
651
-
652
- | Deleted | Why |
653
- |---|---|
654
- | Event bus, topics, wildcard matching, typed-topic | substrate carried no load; per-run event streams + `onRun` cover the real uses |
655
- | 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 |
656
- | 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) |
657
- | 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) |
658
- | Manifold lifecycle (`start`/`stop`/`drain`), ledger object, state store, event log | decorative or folded into run meta/events |
659
- | `runAgentStandalone` | `agent.run()` is the standalone path |
660
- | Full-loop validation retries | in-loop corrections (§3.1) |
661
-
662
- ---
663
-
664
- ## 14. Plan mode, revisited later — the record
665
-
666
- v1 bet on model-emitted ActionPlans executed by a runtime. The field
667
- data: BabyAGI (the pattern's origin) is archived; AutoGPT pivoted
668
- away; every mainstream SDK (OpenAI Agents, Vercel, Pydantic AI,
669
- Mastra) ships a native tool loop with code-first composition; the
670
- survivors of "planning" are recitation todo-lists the model itself
671
- maintains in-loop (Manus todo.md, Claude Code TodoWrite). If explicit
672
- planning returns to cortex it returns as that: a small todo tool plus
673
- a context entry, on top of the loop — not an interpreter under it.
674
-
675
- ---
676
-
677
- ## 15. Future work (known, deferred)
629
+ ## 12. Future work (known, deferred)
678
630
 
679
631
  - **Compaction** — one hook: summarize the transcript when a token
680
632
  threshold nears, keep the prefix stable. Field-standard; not needed
@@ -688,14 +640,13 @@ a context entry, on top of the loop — not an interpreter under it.
688
640
  - **Exact token counting** — behind `signal.count()` when a real
689
641
  tokenizer lands.
690
642
  - **`respond` vs `emit` A/B** on the big-DSL agents (prism mapping,
691
- nova layout, architect). Settled by RULE, not by measurement
692
- (2026-09-24): their schemas are too large for enforcing respond
693
- params, so `auto` resolves them to `emit` everywhere. The quality
694
- 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.
695
646
 
696
647
  ---
697
648
 
698
- ## 16. Source layout
649
+ ## 13. Source layout
699
650
 
700
651
  ```
701
652
  src/
@@ -709,13 +660,14 @@ src/
709
660
  │
710
661
  ├── agent/
711
662
  │ ├── define-agent.ts
712
- │ ├── run.ts # RunHandle, resumeRun, prefix assembly
663
+ │ ├── run.ts # RunHandle, resumeRun
664
+ │ ├── prefix.ts # transport resolution and prefix assembly, shared with preview
713
665
  │ └── preview.ts
714
666
  │
715
667
  ├── loop/
716
668
  │ ├── loop.ts # the loop (§4) — all three transports
717
669
  │ └── partials.ts # solid partial-output tracking
718
- │ # (auto resolution, the strict-compat walk, the respond
670
+ │ # (auto resolution, the schema size/`$ref` check, the respond
719
671
  │ # descriptor and corrections are signal's: src/transport/)
720
672
  │
721
673
  ├── context/