@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 +80 -0
- package/DESIGN.md +78 -126
- package/README.md +103 -19
- package/dist/index.cjs +260 -240
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +11 -2
- package/dist/index.d.ts +11 -2
- package/dist/index.js +260 -240
- package/dist/index.js.map +1 -1
- package/package.json +4 -4
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,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
|
-
|
|
13
|
-
event-bus substrate, a producer pipeline, a JSON rules engine, and a
|
|
14
|
-
plan-mode interpreter. A full architecture review (2026-07) found:
|
|
15
|
-
every real consumer used only `defineAgent` + `defineTool` +
|
|
16
|
-
`runAgentStandalone`; structured mode never sent the output schema to
|
|
17
|
-
the model; the context prefix was re-templated every iteration
|
|
18
|
-
(cache-hostile); the rules engine and stateful producers were broken
|
|
19
|
-
in ways no consumer had hit because no consumer used them. v2 keeps
|
|
20
|
-
what earned its place — typed tools, gating, observations,
|
|
21
|
-
cross-library agents, context-from-functions, preview — and rebuilds
|
|
22
|
-
the execution core around the pattern the field converged on: one
|
|
23
|
-
tool loop with a typed exit.
|
|
12
|
+
The execution core is one tool loop with a typed exit.
|
|
24
13
|
|
|
25
14
|
---
|
|
26
15
|
|
|
@@ -46,7 +35,7 @@ tool loop with a typed exit.
|
|
|
46
35
|
|
|
47
36
|
**Anti-goals.** No HTTP, no UI, no database, no LLM SDK (signal), no
|
|
48
37
|
JSON-parsing of streams (solid), no event-bus substrate, no
|
|
49
|
-
declarative rules DSL, no plan interpreter
|
|
38
|
+
declarative rules DSL, no plan interpreter, no conversation
|
|
50
39
|
persistence (callers own history).
|
|
51
40
|
|
|
52
41
|
**Peers:** `@niscorp/signal`, `zod`. **Dependency:** `@niscorp/solid`.
|
|
@@ -88,7 +77,7 @@ type RunResult<TData> =
|
|
|
88
77
|
| { ok: false; error: CortexError; meta: RunMeta };
|
|
89
78
|
|
|
90
79
|
type RunMeta = {
|
|
91
|
-
usage: Usage; //
|
|
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
|
|
138
|
-
|
|
139
|
-
|
|
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
|
|
200
|
-
`
|
|
201
|
-
the envelope schema passes the
|
|
202
|
-
|
|
203
|
-
|
|
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
|
|
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
|
|
262
|
-
|
|
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 (§
|
|
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`.
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
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)`.
|
|
300
|
-
token cap
|
|
301
|
-
|
|
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
|
-
|
|
308
|
-
|
|
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[]
|
|
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 (§
|
|
368
|
+
the transcript (§12).
|
|
374
369
|
|
|
375
|
-
**Preview
|
|
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.
|
|
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
|
|
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
|
|
449
|
-
transcript (append-only is
|
|
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.
|
|
483
|
-
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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' | '
|
|
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
|
-
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
692
|
-
|
|
693
|
-
|
|
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
|
-
##
|
|
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
|
|
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
|
|
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/
|