@niscorp/cortex 0.1.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/DESIGN.md ADDED
@@ -0,0 +1,695 @@
1
+ # `@niscorp/cortex` — design
2
+
3
+ Cortex is the agent runtime of the `@niscorp` stack. It runs typed,
4
+ tool-using agents on top of [`@niscorp/signal`](../signal) (model
5
+ calls), [`@niscorp/solid`](../solid) (partial-JSON streaming), and
6
+ `zod` (validation). This document is the *why*; usage lives in
7
+ [`README.md`](./README.md). Style rules live in
8
+ [`niscorp/STYLE_GUIDE.md`](../../STYLE_GUIDE.md) — no `any`, no `as`,
9
+ no `!`, no `enum`, no classes; arrow-const exports with explicit
10
+ return types; kebab-case files with role suffixes; named exports only.
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.
24
+
25
+ ---
26
+
27
+ ## 1. What cortex does
28
+
29
+ 1. **Agents.** `defineAgent<TData, TDeps>` — configuration, not a
30
+ class. Typed output, typed per-invocation deps.
31
+ 2. **One loop.** model → tools → model. Bounded, gated, observed. The
32
+ only execution path; there is no second mode.
33
+ 3. **The envelope.** Every agent returns structured data. Terminating
34
+ the loop is a message that IS the envelope — as content (`emit`),
35
+ under provider grammar (`native`), or as the arguments of a
36
+ synthetic `respond` tool, whichever the provider can enforce.
37
+ 4. **Context.** Functions of typed deps build the prefix once per
38
+ run. The transcript is append-only after that.
39
+ 5. **Gates.** Code hooks before and after every tool call. Approvals
40
+ suspend the run; suspended runs are serializable.
41
+ 6. **Events.** Every run is a typed event stream. Observability *is*
42
+ the stream.
43
+ 7. **Manifold.** A catalog of agents and tools with shared defaults
44
+ and a run tap. Libraries (vex, prism, nova) export agents; apps
45
+ compose them; agents consume each other as tools.
46
+
47
+ **Anti-goals.** No HTTP, no UI, no database, no LLM SDK (signal), no
48
+ JSON-parsing of streams (solid), no event-bus substrate, no
49
+ declarative rules DSL, no plan interpreter (§14), no conversation
50
+ persistence (callers own history).
51
+
52
+ **Peers:** `@niscorp/signal`, `@niscorp/solid`, `zod`.
53
+
54
+ ---
55
+
56
+ ## 2. The envelope
57
+
58
+ Every agent returns the same shape. There is no text mode.
59
+
60
+ ```ts
61
+ type Envelope<TData> = {
62
+ response?: string; // human-facing text
63
+ data: TData; // schema-typed payload (undefined for pure chat agents)
64
+ reasoning?: string; // model-authored: WHY it did what it did
65
+ };
66
+ ```
67
+
68
+ Why one shape:
69
+
70
+ - **Text AND data in one turn.** A chat agent can answer in prose and
71
+ hand over a Nova screen in the same response. This is the common
72
+ case for complex assistants, not an edge case.
73
+ - **One termination rule, one streaming path, one thing to test.** A
74
+ chat agent is an envelope agent with `data: undefined`; a
75
+ classifier is one with `response` omitted.
76
+ - **`reasoning`** is the model's own short justification. It is
77
+ distinct from provider reasoning *tokens* (GLM, gpt-oss), which are
78
+ runtime telemetry and surface as `model-delta` events with
79
+ `channel: 'reasoning'` — never in the envelope.
80
+ - **`meta` is not a model field.** Usage, timing, resolved strategy,
81
+ attempt counts, provider metadata — all authored by cortex + signal
82
+ and reported on the run result and events. Models do not
83
+ self-report metadata; self-reported metadata is noise.
84
+
85
+ ```ts
86
+ type RunResult<TData> =
87
+ | { ok: true; output: Envelope<TData>; meta: RunMeta }
88
+ | { ok: false; error: CortexError; meta: RunMeta };
89
+
90
+ type RunMeta = {
91
+ usage: Usage; // aggregated; per-step usage rides on events
92
+ strategy: OutputStrategy; // what actually ran
93
+ steps: number;
94
+ outputRetries: number;
95
+ elapsedMs: number;
96
+ };
97
+ ```
98
+
99
+ ---
100
+
101
+ ## 3. Output strategies
102
+
103
+ How the envelope travels from model to runtime. The output is ALWAYS
104
+ the JSON envelope; a strategy only picks the TRANSPORT — which channel
105
+ carries its bytes. Three transports, one config field, `auto` default.
106
+
107
+ `auto` picks the transport that ENFORCES the most, and falls to `emit`
108
+ when nothing would enforce anything (signal `transport/resolve.ts`):
109
+
110
+ native — provider grammar is viable (small schema; tools allowed
111
+ beside response_format, or no tools)
112
+ respond — the tool params can enforce the contract: the endpoint
113
+ does not validate tool args itself, the full schema fits
114
+ in the params, and the model carries nested payloads on
115
+ the tool channel intact (or `output.forceTool` is set)
116
+ emit — everything else. Every model can do it, and the contract
117
+ rides the prompt — exactly as it would under a respond
118
+ whose params enforce nothing.
119
+
120
+ On Groq every agent resolves to `emit`: Groq validates tool args
121
+ server-side, so `respond` params would be sent permissive and enforce
122
+ nothing. That holds whichever model Groq serves.
123
+
124
+ | Strategy | Transport | Termination | Schema reaches model via |
125
+ |---|---|---|---|
126
+ | `respond` | tool-call arguments (synthetic `respond` tool) | the `respond` call, OR an emitted envelope on the content channel | tool params (small schemas) or prompt docs (large) |
127
+ | `native` | content channel under provider grammar (`response_format: json_schema`) | a content turn with no tool calls | provider grammar |
128
+ | `emit` | content channel; the model's completion IS the envelope | a content turn with no tool calls | prompt docs |
129
+
130
+ Zod validates the envelope in **every** strategy. Providers enforce
131
+ at most syntax; cortex enforces the contract.
132
+
133
+ ### 3.1 `respond`
134
+
135
+ Cortex registers one synthetic tool per run:
136
+
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.
140
+ Otherwise params are loose (`data: object, see OUTPUT SCHEMA in the
141
+ system prompt`) and the schema documentation is injected into
142
+ context (§3.4). This is what makes Prism's `NodeSchema` and Nova's
143
+ `ActionDefinitionSchema` work: a ~60-way recursive union cannot be
144
+ provider-enforced anywhere — the schema was always going to live in
145
+ the prompt; the strategy only decides the delivery channel of the
146
+ answer.
147
+ - **Permissive params on hard-validating providers.** When the
148
+ provider validates tool args server-side and 400s the request on a
149
+ mismatch (Groq's `tool_use_failed`; signal capability
150
+ `validatesToolArgs`), the wire params name the envelope fields but
151
+ constrain nothing (`{ response: {}, data: {}, reasoning: {} }`).
152
+ A server 400 destroys exactly the attempts the client-side decode/
153
+ repair ladder saves (a stringified `data` is repairable); with
154
+ permissive params the attempt arrives and gets repaired or a
155
+ specific correction. The contract rides the respond description +
156
+ the schema doc; validation is always client-side anyway.
157
+ - **Emit is a legal exit (respond-or-finish).** A turn with no tool
158
+ calls is first parsed (fence-tolerant) and validated as the
159
+ envelope; a valid one finishes the run exactly like a `respond`
160
+ call. Some models are unreliable tool-call finishers but emit clean
161
+ JSON — both doors lead to the same validated envelope. Only a turn with no valid envelope in it is an
162
+ error.
163
+ - **The unwrap rung.** Models regularly produce the PAYLOAD instead
164
+ of the envelope around it — especially when the payload has its
165
+ own `data`-named field (a Nova action) colliding with the
166
+ envelope's. When the output is not a plausible envelope but
167
+ validates cleanly against the data schema, it is accepted as
168
+ `{ data: <raw> }`. Envelope-first precedence; safe only because
169
+ real data schemas are strict and discriminating — a correct
170
+ answer is never failed for missing its coat.
171
+ - **Validation feedback in-loop.** Invalid `respond` args produce a
172
+ tool error result carrying the Zod issues; the model retries the
173
+ call. One extra step, transcript intact, tools still warm — never a
174
+ full re-run.
175
+ - **`respond` must be called alone.** If it appears alongside other
176
+ tool calls in one turn, it receives an error result and the other
177
+ calls execute normally.
178
+ - **Termination without a result** (model stops on prose that is not
179
+ an envelope) is a protocol violation: cortex appends a correction
180
+ offering both exits (call `respond`, or emit ONLY the envelope) and
181
+ continues, bounded by the `outputRetries` stop condition. Per-agent
182
+ hardening: `output.forceTool: true` sets `toolChoice: 'required'`
183
+ so every turn must be a tool call and `respond` is the only exit —
184
+ opt-in, because some models get tool-happy under `required`.
185
+ - **Groq-safe when chosen explicitly.** No `response_format` in any
186
+ request, so tools and structured output never conflict. `auto` does
187
+ not pick it on Groq (above): the params there would enforce nothing.
188
+
189
+ ### 3.2 `native`
190
+
191
+ `auto` picks it only when the provider capability
192
+ `toolsWithStructuredOutput` is true (or the agent has no tools) AND
193
+ the envelope schema passes the strict-compatibility walk. Small
194
+ extractors and classifiers on OpenAI-class providers land here and
195
+ get grammar-level enforcement for free.
196
+
197
+ ### 3.3 `emit`
198
+
199
+ The envelope travels on the content channel: the model's final
200
+ completion IS the envelope, as raw JSON — no tool call, no provider
201
+ grammar. First-class, not degraded: same envelope, same Zod
202
+ validation, same correction retries (appended messages, bounded by
203
+ `outputRetries`), same solid streaming via content deltas.
204
+ Fence-tolerant parse. It is `auto`'s floor: wherever neither grammar
205
+ nor tool params would enforce the contract, the contract rides the
206
+ prompt either way, and emit carries the answer without a synthetic
207
+ tool or a tool-call ending. Tool-call arguments are also a LOSSIER
208
+ channel on some models (signal capability `manglesNestedToolArgs`,
209
+ measured per model in signal's model registry), and some models
210
+ compose very large payloads better as a completion than as function
211
+ args. Explicit `respond`/`native` choices are still honored.
212
+ `output.forceTool` cannot combine with emit — the final turn must be
213
+ a content-only message.
214
+
215
+ ### 3.4 Schema documentation
216
+
217
+ `schemaDoc(schema)` renders a Zod schema as prompt documentation —
218
+ single-sourced from the same schema Zod validates against, so docs
219
+ and validation cannot drift. When `respond` resolves to loose or
220
+ permissive params (or strategy is `emit`), cortex injects
221
+ `OUTPUT SCHEMA:\n…` as the
222
+ last system chunk automatically. Agents that hand-author a full DSL
223
+ guide (the architect pattern) disable it with `output.doc: 'off'` or
224
+ replace it with a string.
225
+
226
+ ---
227
+
228
+ ## 4. The loop
229
+
230
+ ```
231
+ prefix = assemble(context fns, input) — once, at run start
232
+ messages = [...prefix] — append-only from here on
233
+
234
+ step:
235
+ stopWhen checks (steps, tokens, duration, outputRetries)
236
+ prepareStep hook → activeTools mask, toolChoice, injected messages, llm swap
237
+ signal.stepStream({ messages, tools, responseFormat? })
238
+ → model-delta events (text + reasoning channels)
239
+ → tool-call-delta events → output-delta / output-partial for respond args
240
+ for each tool call, in order:
241
+ tool gates (allow / deny / ask) — BEFORE execution
242
+ execute (Zod-validated input, timeout)
243
+ onToolResult hooks (replace / redact / truncate)
244
+ append tool result message; emit tool-end observation
245
+ respond call → validate envelope → end (or error result + continue)
246
+ ```
247
+
248
+ Rules the loop lives by:
249
+
250
+ - **Append-only transcript.** The prefix is built once and never
251
+ re-templated. Rule injections, corrections, and budget nudges are
252
+ *appended* messages. This is the KV-cache lesson: on the models we
253
+ run, cached input is ~10× cheaper than uncached, and v1 paid the
254
+ uncached price on every iteration.
255
+ - **Tool calls execute sequentially, in model order.** Deterministic
256
+ gating and event order beat latency here; parallel execution is a
257
+ future knob (§15).
258
+ - **Tool failures are observations, not exceptions.** A failed or
259
+ denied call becomes an error result the model sees and reacts to.
260
+ The run only fails on structural conditions (stop limits, model
261
+ call failure, abort, retries exhausted).
262
+ - **The model sees `tool.name`; `tool.id` is the policy identity.**
263
+ Descriptors carry the name (prompts say "call `query`"); the loop
264
+ resolves incoming calls by name OR id; gates, observations and
265
+ traces always carry the canonical id. Both namespaces must be
266
+ collision-free per run, and nothing may claim `respond`. (v1 sent
267
+ ids on the wire while documenting names — a prompt-literal model
268
+ exposed the lie.)
269
+ - **Streaming is not a mode.** The loop always consumes
270
+ `signal.stepStream`; `await run.result` is the opt-out. There is no
271
+ `stream: true` bifurcation to test twice.
272
+
273
+ Bounds are `stopWhen` predicates — one vocabulary instead of v1's
274
+ maxToolIterations / maxTicks / maxDurationMs / budget tangle:
275
+
276
+ ```ts
277
+ stopWhen: [stepCount(20), tokens(100_000), duration('5m'), outputRetries(3)]
278
+ ```
279
+
280
+ Defaults: `stepCount(20)`, `outputRetries(3)`. No default duration or
281
+ token cap — v1's 60-second default was overridden at every call site,
282
+ which is what a wrong default looks like.
283
+
284
+ ---
285
+
286
+ ## 5. Context — producers
287
+
288
+ The v1 producer insight was right — context comes from PRODUCERS,
289
+ and how a producer constructs its content is irrelevant. v1 failed on
290
+ machinery (priorities, state, no per-invocation data); the machinery
291
+ is deleted, the concept and the name stay:
292
+
293
+ ```ts
294
+ // What enters context: one system chunk, several (a producer can emit a
295
+ // GROUP — each string its own system message), or raw messages.
296
+ type ContextEntry = string | string[] | Message[];
297
+
298
+ // What makes one. Always a function — the name says so. Annotate shared
299
+ // definitions `satisfies Producer` so what a thing is stays obvious at
300
+ // the definition site while the value keeps its narrow callable type.
301
+ type Producer<TDeps = undefined> =
302
+ (ctx: ProducerArgs<TDeps>) => ContextEntry | Promise<ContextEntry>;
303
+
304
+ type ProducerArgs<TDeps> = { deps: TDeps; input: RunInput; agent: AgentInfo };
305
+
306
+ // defineAgent
307
+ context?: ReadonlyArray<ContextEntry | Producer<TDeps>>;
308
+ ```
309
+
310
+ **The principle: context is owned by whoever owns the knowledge, and
311
+ composed by spreading.** An agent owns its identity (`instructions`).
312
+ A LIBRARY owns its contract and exports it as a producer (vex's
313
+ `vexGuide()`, prism's schema). An APP owns its ambient facts and
314
+ exports its shared set (`[...appProducers(), …]` — the same list
315
+ attached to every agent, so "one agent knew today, the other didn't"
316
+ cannot happen). A TOOL owns its own usage knowledge (below). Nothing
317
+ is ever hand-summarized into a prompt on behalf of another owner —
318
+ that is how knowledge drifts.
319
+
320
+ - Strings and string returns become system messages; `Message[]`
321
+ returns give full control. Order is the array — placement IS the
322
+ array position ("today first" = put it first). No priorities, no
323
+ eviction, no compressors, no token modes, no producer state.
324
+ - `instructions` is sugar for the first producer. It exists once.
325
+ - **`RunOptions.producers`** appends per-run producers after the
326
+ agent's own — an app attaches shared knowledge to ANY agent without
327
+ editing its definition.
328
+ - **Tools bring their own guides.** `defineTool({ guide })` carries
329
+ the tool's usage knowledge (a string or a deferred `() => string`,
330
+ e.g. composing a library's exported guide). The run assembles one
331
+ TOOL GUIDES section from the ACTIVE tools — add a tool and its
332
+ guide arrives, change it and every agent updates, remove it and the
333
+ guide leaves. Instructions never describe tools.
334
+ - Prefix order: instructions → agent producers → run producers →
335
+ tool guides → schema doc → finish protocol → input. The finish
336
+ protocol is ONE cortex-owned chunk stating how the run ends under
337
+ the RESOLVED transport (call `respond` / emit the envelope / reply
338
+ under grammar) — agents never author finish lines; they cannot know
339
+ which transport resolution picked.
340
+ - Producers run **once, at run start**, to build the prefix. Dynamic
341
+ steering mid-run belongs to `prepareStep` (append a note, mask
342
+ tools, force a tool choice, swap the model) — the 20% case as one
343
+ hook instead of a rules engine.
344
+ - `input` is `string | Message[] | unknown` (non-message values are
345
+ JSON-stringified into the user turn). Multi-turn history is
346
+ caller-owned and arrives as `Message[]` — ray's transcript becomes
347
+ the supported path instead of a workaround.
348
+ - Compaction (summarize-when-near-limit) is a future single hook on
349
+ the transcript (§15), not a v1 pipeline.
350
+
351
+ **Preview survives, better.** `agent.preview(input, { deps })`
352
+ returns the exact assembled messages, the resolved tool list
353
+ (including `respond` and its actual params), the resolved strategy,
354
+ and a token estimate — no model call. Anything you can't explain in
355
+ the preview, the model can't either.
356
+
357
+ ---
358
+
359
+ ## 6. Gates and hooks
360
+
361
+ All steering is plain typed functions in arrays, composed in order.
362
+ Declarative config is sugar that compiles into the same arrays —
363
+ never a parallel engine.
364
+
365
+ ```ts
366
+ type ToolGate<TDeps> = (call: ToolCallInfo, ctx: RunCtx<TDeps>) =>
367
+ | { allow: true; args?: unknown } // optionally rewrite args
368
+ | { deny: string } // model sees a tool error
369
+ | { ask: { reason: string } } // suspend for approval
370
+ | Promise<…>;
371
+
372
+ type ToolResultHook<TDeps> = (obs: ToolObservation, ctx: RunCtx<TDeps>) =>
373
+ { result?: unknown } | void | Promise<…>; // replace / redact / truncate
374
+
375
+ type PrepareStep<TDeps> = (s: StepInfo<TDeps>) =>
376
+ { activeTools?: string[]; toolChoice?: ToolChoice; inject?: Message[]; llm?: SignalClient } | void;
377
+
378
+ type StopCondition = (s: RunProgress) => boolean;
379
+ ```
380
+
381
+ - **Gates run before execution.** A deny reaches the model as a tool
382
+ error; the run continues. (v1 evaluated rules after the observation
383
+ — a rule could never stop the call that tripped it.)
384
+ - **Policy sugar** covers the declarative 80%:
385
+
386
+ ```ts
387
+ policy: {
388
+ tools: { allow, deny, requireApproval, maxRiskLevel },
389
+ approvalTimeoutMs, // optional; no timeout by default
390
+ }
391
+ ```
392
+
393
+ compiles to one built-in gate. Anything the sugar can't express is
394
+ a function.
395
+ - **Approvals suspend the run.** `ask` emits `approval-required`
396
+ with a stable id; the pending call blocks (tools are sequential, so
397
+ one pending approval at a time). `run.approve(id, { args? })` —
398
+ approve, optionally with edited args — or `run.deny(id, reason)`.
399
+ `run.snapshot()` serializes the suspended run (messages, pending
400
+ call, usage); `resumeRun(agent, snapshot, opts)` restores it — so
401
+ approvals survive reloads and restarts.
402
+ - **Output validation** closes the generate→verify loop in-run:
403
+
404
+ ```ts
405
+ output: {
406
+ schema: ActionAgentOutputSchema,
407
+ validate: async (out) => ok ? { ok: true } : { retry: issues }, // async, can do I/O
408
+ }
409
+ ```
410
+
411
+ A failed validator feeds back like a failed Zod parse — correction
412
+ in the same run, tools still warm. (This replaces the architect's
413
+ hand-rolled verify-once harness bolt-on.)
414
+
415
+ What hooks deliberately can't do: react to *other* runs (cross-run
416
+ choreography is app code around `manifold.onRun`), mutate past
417
+ transcript (append-only is load-bearing), veto text mid-generation
418
+ (validation happens at boundaries: tool call, step end, output). If
419
+ remotely-configured steering is ever needed, it lands as a compiler
420
+ from a config shape *to* a gate function — on top, not underneath.
421
+
422
+ ---
423
+
424
+ ## 7. Events and observability
425
+
426
+ Every run exposes one ordered, typed stream. No global bus.
427
+
428
+ ```ts
429
+ const run = agent.run(input, { deps });
430
+ for await (const e of run.events) { … }
431
+ const result = await run.result;
432
+ ```
433
+
434
+ | Event | Payload | Notes |
435
+ |---|---|---|
436
+ | `run-start` | `{ input }` | |
437
+ | `step-start` | `{ step }` | |
438
+ | `model-delta` | `{ text, channel: 'text' \| 'reasoning' }` | provider reasoning tokens land here |
439
+ | `tool-start` | `{ call }` | before gates + execution — drives live UIs |
440
+ | `tool-end` | `{ observation }` | typed union incl. denials; no casting |
441
+ | `approval-required` | `{ id, toolId, args, reason }` | run suspends |
442
+ | `output-delta` | `{ text }` | raw envelope JSON fragments |
443
+ | `output-partial` | `{ output }` | solid-parsed partial envelope |
444
+ | `retry` | `{ kind: 'output' \| 'termination' \| 'provider', attempt, issues }` | consumers reset partial state; `issues` carries the evidence (Zod issues, the rejected attempt, or the stray text) |
445
+ | `run-end` | `{ result, meta }` | |
446
+
447
+ Every event carries `{ runId, agentPath, seq, ts }`. When an agent
448
+ runs inside another (`asTool`), the child's events forward into the
449
+ parent stream with the extended `agentPath` — one subscription sees
450
+ the whole tree. Per-step usage rides on step events and aggregates
451
+ into `RunMeta.usage`; that is the whole ledger.
452
+
453
+ Process-level watching is the manifold's tap: `onRun(run => …)` hands
454
+ you every run created through it. That is the one legitimate job the
455
+ v1 bus had, kept, without the bus. (Precedent: AutoGen v0.4 built the
456
+ bus-first agent substrate; Microsoft retired it within a year for
457
+ plain awaited runs with typed-edge composition.)
458
+
459
+ ---
460
+
461
+ ## 8. The manifold
462
+
463
+ A catalog, defaults, and the tap. Not a lifecycle, not a substrate,
464
+ not an execution path.
465
+
466
+ ```ts
467
+ const manifold = createManifold({
468
+ llm: groq120b, // default model
469
+ gates: [uiApprovalGate], // shared gates
470
+ onRun: (run) => trace.attach(run),
471
+ });
472
+
473
+ manifold.register(vexQueryAgent, novaLayoutAgent, queryTool);
474
+
475
+ const run = manifold.run('action.builder', { intent }, { deps: env });
476
+ const asToolDef = manifold.asTool('vex.query', { description });
477
+ ```
478
+
479
+ - `agent.run()` standalone and `manifold.run()` are the same
480
+ function; the manifold merges defaults. There is no
481
+ `runAgentStandalone`.
482
+ - Agents may bind their own `llm`; the manifold's is the fallback.
483
+ (The architect's GLM-reasoning / Groq-support split becomes
484
+ configuration.)
485
+ - `asTool(agent, { description?, select? })` wraps an agent as an
486
+ ordinary `ToolDefinition`. Default result mapping: envelope `data`
487
+ if present, else `response`; `select` overrides. Child events
488
+ forward (§7).
489
+ - Duplicate ids throw at registration. Registration is a Map insert;
490
+ there is no `start`/`stop`/`drain`.
491
+
492
+ ---
493
+
494
+ ## 9. Errors
495
+
496
+ Same two principles as v1, smaller taxonomy:
497
+
498
+ 1. **Programmer errors throw** at definition/registration time:
499
+ duplicate ids, malformed configs.
500
+ 2. **Runtime conditions return** as `Result` (§2). Tool failures are
501
+ observations (§4), not run failures.
502
+
503
+ ```ts
504
+ type CortexError = {
505
+ code: 'model_call_failed' | 'output_invalid' | 'stopped' | 'aborted' | 'unknown';
506
+ stop?: 'steps' | 'tokens' | 'duration' | 'output_retries' | 'custom'; // when code === 'stopped'
507
+ message: string;
508
+ runId: string;
509
+ agentPath: ReadonlyArray<string>;
510
+ cause?: unknown;
511
+ };
512
+ ```
513
+
514
+ An approval timeout is NOT an error code: it denies the pending call
515
+ (an observation the model reacts to) and the run continues — same
516
+ principle as every other tool denial.
517
+
518
+ ---
519
+
520
+ ## 10. Streaming
521
+
522
+ Always on (§4). Solid is a peer dependency and powers
523
+ `output-partial`: `respond` arg deltas (or content deltas under
524
+ `native`/`emit`) stream through solid's partial parser into
525
+ progressively-typed envelopes — a chat `response` string streams
526
+ token-ish while it forms inside the JSON, and a Nova screen in `data`
527
+ becomes renderable before the run ends. The `retry` event resets
528
+ partial-output state, same contract as v1's `cortex.agent.retry`.
529
+
530
+ ---
531
+
532
+ ## 11. Public API surface
533
+
534
+ ```ts
535
+ // definition
536
+ defineAgent<TData, TDeps>(config): AgentDefinition<TData, TDeps>
537
+ defineTool(config): ToolDefinition // v1 shape, kept
538
+ schemaDoc(schema, opts?): string
539
+
540
+ // execution
541
+ agent.run(input, { deps, llm?, tools?, gates?, onToolResult?, onEvent?, signal? }): RunHandle<TData>
542
+ // tools: per-run tools whose execute closes over per-invocation
543
+ // dependencies (vex builds its query tools around the caller's
544
+ // adapter + schema); appended to the agent's static tools.
545
+ agent.preview(input, { deps }): ResolvedPreview
546
+ resumeRun(agent, snapshot, opts): RunHandle<TData>
547
+
548
+ // RunHandle
549
+ run.events: AsyncIterable<CortexEvent>
550
+ run.result: Promise<RunResult<TData>>
551
+ run.approve(id, { args? }) / run.deny(id, reason?)
552
+ run.snapshot(): RunSnapshot
553
+ run.abort(reason?)
554
+
555
+ // composition
556
+ createManifold({ llm, gates?, onRun? }): Manifold
557
+ manifold.register / run / asTool / preview
558
+
559
+ // stop conditions
560
+ stepCount(n), tokens(n), duration(ms | '5m'), outputRetries(n)
561
+ ```
562
+
563
+ `defineAgent` config:
564
+
565
+ ```ts
566
+ {
567
+ id, description,
568
+ llm?, // per-agent binding; manifold/run option is fallback
569
+ instructions, // string | (ctx) => string — sugar for the first producer
570
+ context?: Producer<TDeps>[], // compose shared sets by spreading: [...appProducers(), …]
571
+ tools?: ToolDefinition[], // definitions, not id strings; each may carry its own `guide`
572
+ output?: {
573
+ schema?: ZodType<TData>, // omitted → pure chat agent (data: undefined)
574
+ response?: 'required' | 'optional', // default: required without schema, optional with
575
+ strategy?: 'auto' | 'respond' | 'native' | 'emit', // default 'auto'
576
+ forceTool?: boolean, // toolChoice:'required' hardening
577
+ doc?: 'auto' | 'off' | string, // schema docs injection, default 'auto'
578
+ validate?: (out) => { ok: true } | { retry: string } | Promise<…>,
579
+ },
580
+ toolGates?, onToolResult?, prepareStep?, stopWhen?, policy?,
581
+ }
582
+ ```
583
+
584
+ ---
585
+
586
+ ## 12. Signal changes this design requires
587
+
588
+ 1. **`stepStream` emits `tool-call-delta`** — `{ index, id?, name?,
589
+ argsText }` fragments as function args stream. The SSE chunks
590
+ already contain them; the adapter currently drops them. This is
591
+ the enabler for `respond`-strategy streaming and solid, and is
592
+ built first.
593
+ 2. **`StepRequest.responseFormat`** passthrough (json_schema /
594
+ json_object) for the `native` strategy.
595
+ 3. **Capabilities truth.** Groq `nativeTools: true` (stale since the
596
+ registry was written; ray proves it daily). New capability:
597
+ `toolsWithStructuredOutput: boolean` — encodes the
598
+ can't-combine-format-and-tools constraint that shaped §3.
599
+ 4. Later, not blocking: signal's own `complete()` tool loop can slim
600
+ once cortex is the loop owner; real tokenizer behind `count()`.
601
+
602
+ ---
603
+
604
+ ## 13. What v2 deletes from v1
605
+
606
+ | Deleted | Why |
607
+ |---|---|
608
+ | Event bus, topics, wildcard matching, typed-topic | substrate carried no load; per-run event streams + `onRun` cover the real uses |
609
+ | 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 |
610
+ | 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) |
611
+ | 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) |
612
+ | Manifold lifecycle (`start`/`stop`/`drain`), ledger object, state store, event log | decorative or folded into run meta/events |
613
+ | `runAgentStandalone` | `agent.run()` is the standalone path |
614
+ | Full-loop validation retries | in-loop corrections (§3.1) |
615
+
616
+ ---
617
+
618
+ ## 14. Plan mode, revisited later — the record
619
+
620
+ v1 bet on model-emitted ActionPlans executed by a runtime. The field
621
+ data: BabyAGI (the pattern's origin) is archived; AutoGPT pivoted
622
+ away; every mainstream SDK (OpenAI Agents, Vercel, Pydantic AI,
623
+ Mastra) ships a native tool loop with code-first composition; the
624
+ survivors of "planning" are recitation todo-lists the model itself
625
+ maintains in-loop (Manus todo.md, Claude Code TodoWrite). If explicit
626
+ planning returns to cortex it returns as that: a small todo tool plus
627
+ a context entry, on top of the loop — not an interpreter under it.
628
+
629
+ ---
630
+
631
+ ## 15. Future work (known, deferred)
632
+
633
+ - **Compaction** — one hook: summarize the transcript when a token
634
+ threshold nears, keep the prefix stable. Field-standard; not needed
635
+ for current workloads.
636
+ - **Parallel tool execution** — opt-in per agent once gate/event
637
+ ordering under concurrency is specified.
638
+ - **Durable run store** — `snapshot()` already serializes; a store
639
+ interface + replay is additive.
640
+ - **Declarative gate config** — a compiler from config to gate
641
+ functions, if remote-configured steering is ever needed.
642
+ - **Exact token counting** — behind `signal.count()` when a real
643
+ tokenizer lands.
644
+ - **`respond` vs `emit` A/B** on the big-DSL agents (prism mapping,
645
+ nova layout, architect). Settled by RULE, not by measurement
646
+ (2026-09-24): their schemas are too large for enforcing respond
647
+ params, so `auto` resolves them to `emit` everywhere. The quality
648
+ comparison was never run.
649
+
650
+ ---
651
+
652
+ ## 16. Source layout
653
+
654
+ ```
655
+ src/
656
+ ├── index.ts # public API
657
+ ├── types.ts # shared core types
658
+ │
659
+ ├── schemas/
660
+ │ ├── envelope.schema.ts # Envelope<TData> factory
661
+ │ ├── agent-config.schema.ts
662
+ │ └── tool-config.schema.ts
663
+ │
664
+ ├── agent/
665
+ │ ├── define-agent.ts
666
+ │ ├── run.ts # RunHandle, resumeRun
667
+ │ └── preview.ts
668
+ │
669
+ ├── loop/
670
+ │ ├── loop.ts # the loop (§4) — all three transports
671
+ │ ├── strategy-resolve.ts # auto resolution + strict-compat walk
672
+ │ ├── respond-tool.ts # synthetic respond descriptor + corrections
673
+ │ └── partials.ts # solid partial-output tracking
674
+ │
675
+ ├── context/
676
+ │ ├── assemble.ts
677
+ │ └── schema-doc.ts
678
+ │
679
+ ├── gates/
680
+ │ ├── types.ts
681
+ │ ├── policy.ts # sugar → built-in gate
682
+ │ └── approval.ts # suspend / approve / deny / snapshot
683
+ │
684
+ ├── events/
685
+ │ ├── types.ts # CortexEvent vocabulary
686
+ │ └── stream.ts # per-run emitter + forwarding
687
+ │
688
+ ├── manifold/
689
+ │ ├── manifold.ts
690
+ │ └── as-tool.ts
691
+ │
692
+ ├── tool/define-tool.ts
693
+ ├── errors/cortex.errors.ts
694
+ └── utils/
695
+ ```