@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 +695 -0
- package/LICENSE +202 -0
- package/README.md +291 -0
- package/dist/index.cjs +1288 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +450 -0
- package/dist/index.d.ts +450 -0
- package/dist/index.js +1270 -0
- package/dist/index.js.map +1 -0
- package/package.json +57 -0
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
|
+
```
|