@niscorp/cortex 0.1.1 → 0.1.4
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 +85 -0
- package/DESIGN.md +42 -17
- package/README.md +96 -11
- package/dist/index.cjs +19 -17
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +19 -17
- package/dist/index.js.map +1 -1
- package/package.json +6 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,90 @@
|
|
|
1
1
|
# @niscorp/cortex
|
|
2
2
|
|
|
3
|
+
## 0.1.4
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 1dcccd7: An envelope with a misspelt key is no longer accepted as the agent's data.
|
|
8
|
+
|
|
9
|
+
A model may send the payload alone, without `{ response, data, reasoning }` around it, and cortex reads it as the data when it passes the agent's schema. A schema that takes any object passed everything: under `z.record(z.string(), z.unknown())` the answer `{ respnse: 'Done.', data: { id: 7 } }` came back as the data, whole, and under an object schema whose fields are all optional it came back as `{}`. The run finished with the wrong data and no correction.
|
|
10
|
+
|
|
11
|
+
The payload alone is now read only when the schema can tell it from an envelope, which is when the schema refuses an object that holds one unknown key. Under any other schema an unknown key is reported to the model, as it is for an agent with no data schema.
|
|
12
|
+
|
|
13
|
+
**What to change:** nothing. An agent whose data schema takes any object (a record, or an object with only optional fields) and whose model sends the payload alone now spends one correction round on it. Prism's mapping agent is one such agent, because any JSON object is a Prism config. A required field in the schema, or `z.strictObject`, keeps the payload-alone reading.
|
|
14
|
+
|
|
15
|
+
- a4ccf0e: The README states thirteen facts about the API that were written only in source comments, and DESIGN.md gives the condition for reading a bare payload.
|
|
16
|
+
|
|
17
|
+
The README now says what `meta.usage.reported` means, what `repeatedCalls(n)` counts (n + 1 identical calls), that `prepareStep`'s `activeTools` takes tool names, what `transport: 'step'` does, the order hooks and gates run in, who receives `run-start`, that `output-partial` is best-effort, the three kinds of `retry`, what a resumed run keeps, the reason on an approval that timed out, how a hand-written delegating tool nests its child's events, and how `estimatedTokens` is counted.
|
|
18
|
+
|
|
19
|
+
No behaviour changed.
|
|
20
|
+
|
|
21
|
+
**What to change:** nothing.
|
|
22
|
+
|
|
23
|
+
## 0.1.3
|
|
24
|
+
|
|
25
|
+
### Patch Changes
|
|
26
|
+
|
|
27
|
+
- 2756aa7: `run.abort(reason)` keeps its reason: it is the `cause` of the aborted result.
|
|
28
|
+
|
|
29
|
+
`RunHandle.abort` is typed `(reason?: string) => void` and the reason was dropped — it was not on the result, on any event, or anywhere a caller could read it back.
|
|
30
|
+
|
|
31
|
+
A run stopped by `run.abort('the member closed the tab')` now settles with `error.cause: 'the member closed the tab'`, on `run.result` and on the result the `run-end` event carries. `error.code` (`aborted`) and `error.message` are unchanged, and `run.abort()` with no reason gives the result it always gave, with no `cause`.
|
|
32
|
+
|
|
33
|
+
The reason is kept beside the run's signal and never put on it: a tool's `ctx.signal` still aborts with an `AbortError`, so a tool — or a `fetch` it started — that tells an abort by that error sees one as before. A run stopped through the caller's own `options.signal` is unchanged too; what that signal was aborted with is not read.
|
|
34
|
+
|
|
35
|
+
**What to change:** nothing. If you already pass a reason to `run.abort`, the aborted result now carries it as `error.cause`.
|
|
36
|
+
|
|
37
|
+
- 0b5a7d6: README and DESIGN describe the loop as it runs. A turn of prose with no envelope in it is corrected without counting against `outputRetries`, so `stepCount` is what ends a model that keeps writing prose, and a `stopWhen` you pass replaces the defaults; `outputRetries(n)` means n attempts and n − 1 corrections. An invalid answer gets the attempt and a system message appended, not a tool error. A `respond` sent beside other tool calls is dropped, and output streamed by a step that ends in tool calls is not the answer. Through Signal a call to a tool the agent does not have is read as an attempted answer, so `tool-end` kind `unknown-tool` is rare. `policy.tools` lists take tool ids, not the names the model calls. A tool's `output` schema types what `execute` returns and is not applied at runtime. No code changed.
|
|
38
|
+
|
|
39
|
+
**What to change:** nothing for this release. A `policy.tools` entry written with a tool's name, where its `id` differs, has never matched: write the id.
|
|
40
|
+
|
|
41
|
+
- 4abbfcc: The README says what a tool's `input` schema may be. The model is sent its JSON Schema, taken from the schema's output side, and a call's arguments are parsed with it twice: by the loop, then again in front of `execute`. So an `input` schema validates and does not convert:
|
|
42
|
+
- One with no JSON Schema (a `.transform()`, a `z.date()`) fails the run before the model is asked, with `code: 'unknown'` and Zod's message.
|
|
43
|
+
- One whose output is another kind than its input (`z.stringbool()`) is described to the model by its output and then refuses what its own first parse produced: the tool never runs.
|
|
44
|
+
- One that changes a value (`.overwrite()`) changes it twice, while the observation's `args` hold the value as parsed once.
|
|
45
|
+
|
|
46
|
+
Convert inside `execute`. The README says this under "Errors", and tests hold it. No code changed.
|
|
47
|
+
|
|
48
|
+
**What to change:** nothing.
|
|
49
|
+
|
|
50
|
+
- a02a031: The README and DESIGN say which approval id a resumed run answers to. No code changed.
|
|
51
|
+
|
|
52
|
+
`resumeRun` re-asks a pending approval: the resumed run's gates run again for the pending call, and `approval-required` fires again with a new id. DESIGN called the id "stable" and the README said approvals survive restarts, which read as if the id in the snapshot could be answered on the resumed run. It cannot: `resumed.approve(snapshot.pending.approvalId)` does nothing — an id a handle did not ask under is ignored — and with no `policy.approvalTimeoutMs` the run then waits.
|
|
53
|
+
|
|
54
|
+
Both documents now say so: answer with the id of the resumed run's own `approval-required` event, as the README's example already does; `snapshot.pending.approvalId` names the ask of the run the snapshot was taken from. DESIGN also says that when the gates no longer ask on resume, the pending call simply runs. A test holds the re-ask and its new id.
|
|
55
|
+
|
|
56
|
+
**What to change:** nothing if you answer from the `approval-required` event. If you kept `snapshot.pending.approvalId` to answer with after `resumeRun`, answer with the id of the resumed run's event instead.
|
|
57
|
+
|
|
58
|
+
- Updated dependencies [5923e38]
|
|
59
|
+
- Updated dependencies [2815107]
|
|
60
|
+
- Updated dependencies [885bc1e]
|
|
61
|
+
- Updated dependencies [f9f1b26]
|
|
62
|
+
- Updated dependencies [e3e0ff2]
|
|
63
|
+
- Updated dependencies [ed9d7f4]
|
|
64
|
+
- @niscorp/solid@0.1.2
|
|
65
|
+
|
|
66
|
+
## 0.1.2
|
|
67
|
+
|
|
68
|
+
### Patch Changes
|
|
69
|
+
|
|
70
|
+
- 06d1531: The README's first run says why it failed. Its install line now names `openai`, the SDK Signal loads when a model on Groq, OpenAI or OpenRouter is called: without it the quick example's run failed with `Missing dependency: openai`. And the example prints the reason when a run fails (`else console.error(result.error.message)`): a failed run returns its reason and does not throw, so with no API key set the example ended in silence, exit code 0. No code changed.
|
|
71
|
+
|
|
72
|
+
**What to change:** nothing.
|
|
73
|
+
|
|
74
|
+
- fe30458: Every package exports its `package.json`, so an app can say which version of a package it runs by reading it from the package:
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
import prism from '@niscorp/prism/package.json' with { type: 'json' };
|
|
78
|
+
prism.version; // the version that is installed, not the range that asked for it
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Until now the `exports` map hid it, and the only way to the version was a path into `node_modules`. `check:packages` installs the tarballs and reads every package's version this way.
|
|
82
|
+
|
|
83
|
+
**What to change:** nothing. An app that read a version by path can read it by name.
|
|
84
|
+
|
|
85
|
+
- Updated dependencies [fe30458]
|
|
86
|
+
- @niscorp/solid@0.1.1
|
|
87
|
+
|
|
3
88
|
## 0.1.1
|
|
4
89
|
|
|
5
90
|
### Patch Changes
|
package/DESIGN.md
CHANGED
|
@@ -165,20 +165,28 @@ Cortex registers one synthetic tool per run:
|
|
|
165
165
|
own `data`-named field (a Nova action) colliding with the
|
|
166
166
|
envelope's. When the output is not a plausible envelope but
|
|
167
167
|
validates cleanly against the data schema, it is accepted as
|
|
168
|
-
`{ data: <raw> }`.
|
|
168
|
+
`{ data: <raw> }`. That reading is taken only when the data schema
|
|
169
|
+
refuses an object that holds one unknown key: a schema that accepts
|
|
170
|
+
such an object cannot tell a bare payload from an envelope with a
|
|
171
|
+
misspelt key, and the output is then judged as an envelope.
|
|
172
|
+
Envelope-first precedence; safe only because
|
|
169
173
|
real data schemas are strict and discriminating — a correct
|
|
170
174
|
answer is never failed for missing its coat.
|
|
171
|
-
- **Validation feedback in-loop.** Invalid `respond` args
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
full re-run.
|
|
175
|
+
- **Validation feedback in-loop.** Invalid `respond` args are
|
|
176
|
+
appended as the assistant's turn, followed by a system message
|
|
177
|
+
carrying the Zod issues; the model answers again. One extra step,
|
|
178
|
+
transcript intact, tools still warm — never a full re-run.
|
|
175
179
|
- **`respond` must be called alone.** If it appears alongside other
|
|
176
|
-
tool calls in one turn, it
|
|
177
|
-
|
|
180
|
+
tool calls in one turn, it is dropped: the other calls execute
|
|
181
|
+
normally and the model is told nothing about it. Its arguments have
|
|
182
|
+
already streamed as `output-delta` and `output-partial` by then.
|
|
178
183
|
- **Termination without a result** (model stops on prose that is not
|
|
179
184
|
an envelope) is a protocol violation: cortex appends a correction
|
|
180
185
|
offering both exits (call `respond`, or emit ONLY the envelope) and
|
|
181
|
-
continues
|
|
186
|
+
continues. These corrections are not counted against
|
|
187
|
+
`outputRetries`, which is for answers that parsed and were refused,
|
|
188
|
+
so it is `stepCount` (20 turns by default) that ends a run whose
|
|
189
|
+
model keeps writing prose. Per-agent
|
|
182
190
|
hardening: `output.forceTool: true` sets `toolChoice: 'required'`
|
|
183
191
|
so every turn must be a tool call and `respond` is the only exit —
|
|
184
192
|
opt-in, because some models get tool-happy under `required`.
|
|
@@ -199,8 +207,9 @@ get grammar-level enforcement for free.
|
|
|
199
207
|
The envelope travels on the content channel: the model's final
|
|
200
208
|
completion IS the envelope, as raw JSON — no tool call, no provider
|
|
201
209
|
grammar. First-class, not degraded: same envelope, same Zod
|
|
202
|
-
validation, same correction retries (appended messages
|
|
203
|
-
`outputRetries
|
|
210
|
+
validation, same correction retries (appended messages; a refused
|
|
211
|
+
envelope counts against `outputRetries`, a turn with no envelope in
|
|
212
|
+
it does not), same solid streaming via content deltas.
|
|
204
213
|
Fence-tolerant parse. It is `auto`'s floor: wherever neither grammar
|
|
205
214
|
nor tool params would enforce the contract, the contract rides the
|
|
206
215
|
prompt either way, and emit carries the answer without a synthetic
|
|
@@ -242,7 +251,7 @@ step:
|
|
|
242
251
|
execute (Zod-validated input, timeout)
|
|
243
252
|
onToolResult hooks (replace / redact / truncate)
|
|
244
253
|
append tool result message; emit tool-end observation
|
|
245
|
-
respond call → validate envelope → end (or
|
|
254
|
+
respond call → validate envelope → end (or correction + continue)
|
|
246
255
|
```
|
|
247
256
|
|
|
248
257
|
Rules the loop lives by:
|
|
@@ -259,10 +268,16 @@ Rules the loop lives by:
|
|
|
259
268
|
denied call becomes an error result the model sees and reacts to.
|
|
260
269
|
The run only fails on structural conditions (stop limits, model
|
|
261
270
|
call failure, abort, retries exhausted).
|
|
271
|
+
- **A tool's `input` is enforced; its `output` is a type.** The input
|
|
272
|
+
schema is parsed before `execute` runs. The optional `output`
|
|
273
|
+
schema types what `execute` returns and is not applied at runtime:
|
|
274
|
+
the return value is not parsed, stripped or transformed by it.
|
|
262
275
|
- **The model sees `tool.name`; `tool.id` is the policy identity.**
|
|
263
|
-
Descriptors carry the name (prompts say "call `query`"); the loop
|
|
264
|
-
resolves
|
|
265
|
-
|
|
276
|
+
Descriptors carry the name (prompts say "call `query`"); the loop's
|
|
277
|
+
own table resolves a call by name OR id, but Signal routes only the
|
|
278
|
+
names it was sent, so through Signal a call by id is read as an
|
|
279
|
+
attempted answer and never reaches that table; gates, observations
|
|
280
|
+
and traces always carry the canonical id. Both namespaces must be
|
|
266
281
|
collision-free per run, and nothing may claim `respond`. (v1 sent
|
|
267
282
|
ids on the wire while documenting names — a prompt-literal model
|
|
268
283
|
exposed the lie.)
|
|
@@ -402,12 +417,20 @@ type StopCondition = (s: RunProgress) => StopVerdict; // { stop: StopReason; m
|
|
|
402
417
|
compiles to one built-in gate. Anything the sugar can't express is
|
|
403
418
|
a function.
|
|
404
419
|
- **Approvals suspend the run.** `ask` emits `approval-required`
|
|
405
|
-
with
|
|
420
|
+
with an id that is that ask's for as long as the run handle lives —
|
|
421
|
+
the event, `run.approve` / `run.deny` and `run.snapshot()` all name
|
|
422
|
+
it; the pending call blocks (tools are sequential, so
|
|
406
423
|
one pending approval at a time). `run.approve(id, { args? })` —
|
|
407
424
|
approve, optionally with edited args — or `run.deny(id, reason)`.
|
|
425
|
+
An id the handle did not ask under is ignored.
|
|
408
426
|
`run.snapshot()` serializes the suspended run (messages, pending
|
|
409
427
|
call, usage); `resumeRun(agent, snapshot, opts)` restores it — so
|
|
410
|
-
approvals survive reloads and restarts.
|
|
428
|
+
approvals survive reloads and restarts. A resumed run **re-asks**:
|
|
429
|
+
its gates run again for the pending call (if they no longer ask, the
|
|
430
|
+
call simply runs) and `approval-required` fires with a new id — the
|
|
431
|
+
one the resumed handle answers to. `snapshot.pending.approvalId`
|
|
432
|
+
names the ask of the run the snapshot came from, not the resumed
|
|
433
|
+
one's.
|
|
411
434
|
- **Output validation** closes the generate→verify loop in-run:
|
|
412
435
|
|
|
413
436
|
```ts
|
|
@@ -448,7 +471,7 @@ const result = await run.result;
|
|
|
448
471
|
| `tool-start` | `{ call }` | before gates + execution — drives live UIs |
|
|
449
472
|
| `tool-end` | `{ observation }` | typed union incl. denials; no casting |
|
|
450
473
|
| `approval-required` | `{ approval: { id, toolId, callId, args, reason } }` | run suspends |
|
|
451
|
-
| `output-delta` | `{ text }` |
|
|
474
|
+
| `output-delta` | `{ text }` | the output channel as it streams; the envelope's JSON on the step that ends the run |
|
|
452
475
|
| `output-partial` | `{ output }` | solid-parsed partial envelope |
|
|
453
476
|
| `retry` | `{ kind: 'output' \| 'termination' \| 'provider', attempt, issues }` | consumers reset partial state; `issues` carries the evidence (Zod issues, the rejected attempt, or the stray text) |
|
|
454
477
|
| `run-end` | `{ result, meta }` | |
|
|
@@ -563,6 +586,8 @@ run.result: Promise<RunResult<TData>>
|
|
|
563
586
|
run.approve(id, { args? }) / run.deny(id, reason?)
|
|
564
587
|
run.snapshot(): RunSnapshot
|
|
565
588
|
run.abort(reason?)
|
|
589
|
+
// the reason is `error.cause` of the `aborted` result. A tool's
|
|
590
|
+
// ctx.signal still aborts with an AbortError, never with the reason.
|
|
566
591
|
|
|
567
592
|
// composition
|
|
568
593
|
createManifold({ llm?, gates?, onRun? }): Manifold
|
package/README.md
CHANGED
|
@@ -8,6 +8,9 @@ hand cortex the client) and `zod` (you hand it the schemas).
|
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
10
|
pnpm add @niscorp/cortex @niscorp/signal zod
|
|
11
|
+
# Signal loads the provider's SDK when a model is called. For Groq, OpenAI,
|
|
12
|
+
# OpenRouter or any OpenAI-compatible API (the quick example runs on Groq):
|
|
13
|
+
pnpm add openai
|
|
11
14
|
```
|
|
12
15
|
|
|
13
16
|
For the *why* behind the architecture — the envelope, output
|
|
@@ -43,6 +46,7 @@ const llm = createSignal('groq'); // qwen/qwen3.8-27b — the registry default
|
|
|
43
46
|
|
|
44
47
|
const result = await calcAgent.run('What is (2 + 3) * 7 - 6?', { llm }).result;
|
|
45
48
|
if (result.ok) console.log(result.output.data.answer); // 29
|
|
49
|
+
else console.error(result.error.message); // a run that fails returns its reason; it does not throw
|
|
46
50
|
```
|
|
47
51
|
|
|
48
52
|
---
|
|
@@ -63,7 +67,9 @@ A chat agent omits `output.schema` (its `response` becomes required);
|
|
|
63
67
|
a data agent sets it; a rich assistant returns both — prose *and* a
|
|
64
68
|
payload in one turn. Run-level metadata (usage, resolved strategy,
|
|
65
69
|
attempts, elapsed) is authored by cortex on `result.meta`, never by
|
|
66
|
-
the model.
|
|
70
|
+
the model. `meta.usage.reported` is `false` when any step's tokens
|
|
71
|
+
were counted by Signal instead of reported by the provider; the
|
|
72
|
+
totals are then an estimate.
|
|
67
73
|
|
|
68
74
|
```ts
|
|
69
75
|
const result = await agent.run(input, { llm, deps }).result;
|
|
@@ -85,9 +91,9 @@ How the envelope travels from model to runtime. One field,
|
|
|
85
91
|
| `emit` | the model's completion IS the envelope (content channel) | everything else — auto-picked wherever neither of the above enforces anything: all of Groq, big schemas, models that mangle nested tool args |
|
|
86
92
|
|
|
87
93
|
Zod validates in **every** strategy. Invalid output feeds back as a
|
|
88
|
-
correction *inside the same run* (
|
|
89
|
-
|
|
90
|
-
Nova actions) ride `emit`; cortex injects
|
|
94
|
+
correction *inside the same run* (the attempt and a system message
|
|
95
|
+
naming the issues are appended) — never a full re-run. Big recursive
|
|
96
|
+
schemas (Prism nodes, Nova actions) ride `emit`; cortex injects
|
|
91
97
|
the JSON Schema into the prompt automatically (`output.doc: 'auto'`,
|
|
92
98
|
via `schemaDoc()` — single-sourced from the Zod schema).
|
|
93
99
|
|
|
@@ -127,7 +133,30 @@ const agent = defineAgent<Data, Deps>({
|
|
|
127
133
|
Deps are per-invocation, typed, and consumed by context entries,
|
|
128
134
|
gates and hooks — agents are defined once, never rebuilt per call.
|
|
129
135
|
Defaults when `stopWhen` is omitted: `stepCount(20)`,
|
|
130
|
-
`outputRetries(3)`.
|
|
136
|
+
`outputRetries(3)`. A `stopWhen` you pass replaces both, so keep a
|
|
137
|
+
`stepCount` in it: `outputRetries` counts refused answers only, and
|
|
138
|
+
a turn of prose with no envelope in it is corrected without being
|
|
139
|
+
counted. `outputRetries(n)` ends the run at the n-th refused answer:
|
|
140
|
+
n attempts, n − 1 corrections, so `outputRetries(1)` allows no
|
|
141
|
+
second attempt. `repeatedCalls(n)` ends the run when a tool call has
|
|
142
|
+
got the same answer as the call before it n times in a row — the same
|
|
143
|
+
tool, the same arguments, the same result or error — which is n + 1
|
|
144
|
+
identical calls.
|
|
145
|
+
|
|
146
|
+
`policy.tools` lists take tool **ids** (`tool.id`), not the names
|
|
147
|
+
the model calls: a name in `deny` or `requireApproval` matches
|
|
148
|
+
nothing and says nothing, and a name in `allow` leaves the tool off
|
|
149
|
+
the list.
|
|
150
|
+
|
|
151
|
+
`prepareStep`'s `activeTools` is the other way round: it takes the
|
|
152
|
+
**names** the model calls, the strings its `tools` argument lists,
|
|
153
|
+
and a tool whose name is not in it is not offered on that step. The
|
|
154
|
+
`respond` tool cannot be masked.
|
|
155
|
+
|
|
156
|
+
`transport: 'step'` calls the model without streaming: the run emits
|
|
157
|
+
no `model-delta`, `output-delta` or `output-partial`. It is for a
|
|
158
|
+
provider and model pair that assembles tool-call arguments more
|
|
159
|
+
reliably outside streaming. The default is `'stream'`.
|
|
131
160
|
|
|
132
161
|
Multi-turn history is caller-owned: `input` accepts a `string`, a
|
|
133
162
|
`Message[]` transcript, or any JSON value.
|
|
@@ -139,7 +168,7 @@ agent.run(input, {
|
|
|
139
168
|
llm, deps,
|
|
140
169
|
tools: [perRequestTool], // appended to the agent's static tools
|
|
141
170
|
gates: [uiApprovalGate],
|
|
142
|
-
onToolResult: [traceHook],
|
|
171
|
+
onToolResult: [traceHook], // run after the agent's own hooks
|
|
143
172
|
onEvent: (e) => …,
|
|
144
173
|
signal: abortController.signal,
|
|
145
174
|
});
|
|
@@ -158,15 +187,36 @@ for await (const e of run.events) {
|
|
|
158
187
|
const result = await run.result; // the no-streaming opt-out
|
|
159
188
|
```
|
|
160
189
|
|
|
190
|
+
- `run-start` is emitted before `agent.run()` returns: the `onEvent`
|
|
191
|
+
option and `run.events` deliver it, a listener added with
|
|
192
|
+
`run.onEvent` does not.
|
|
161
193
|
- `tool-start` fires **before** execution — drives live "running…" UIs.
|
|
162
194
|
- `tool-end` carries a typed `ToolObservation` union (result / error /
|
|
163
|
-
denied / unknown-tool). No casting.
|
|
195
|
+
denied / unknown-tool). No casting. Through Signal, `unknown-tool`
|
|
196
|
+
is rare: Signal routes only calls to tools the step declared, and
|
|
197
|
+
reads a call to any other name as an attempted answer. It is
|
|
198
|
+
validated as the envelope (a `retry`, or the run's output if it
|
|
199
|
+
passes), or dropped when it comes beside a call to a declared tool,
|
|
200
|
+
and never reaches `tool-start`. The kind arises when `resumeRun` is
|
|
201
|
+
not handed the per-run tool the pending call names, or with a
|
|
202
|
+
client that does its own routing.
|
|
164
203
|
- `output-delta` streams the raw envelope JSON as it generates;
|
|
165
204
|
`output-partial` streams the progressively parsed envelope via
|
|
166
205
|
[`@niscorp/solid`](../solid) — a chat `response` streams token-ish,
|
|
167
206
|
a Nova screen in `data` becomes renderable before the run ends.
|
|
207
|
+
Both stream before cortex knows how the step ends: words written
|
|
208
|
+
beside a tool call (under `emit` and `native`) and a `respond` sent
|
|
209
|
+
beside other calls arrive as `output-delta` too and are not the
|
|
210
|
+
answer. The answer is what the last step streamed. `output-partial`
|
|
211
|
+
is best-effort: a run emits none when Solid cannot follow the
|
|
212
|
+
schema or the text, and the run's result is validated on its own
|
|
213
|
+
either way.
|
|
168
214
|
- `retry` resets partial-output state (same contract consumers had
|
|
169
|
-
in v1).
|
|
215
|
+
in v1). Its `kind` says what is retried: `output` — an envelope
|
|
216
|
+
arrived and was refused; `termination` — the step ended with no
|
|
217
|
+
envelope in it; `provider` — the provider rejected the model's
|
|
218
|
+
attempt on its side. Only `output` counts against `outputRetries`,
|
|
219
|
+
and `attempt` numbers each kind on its own.
|
|
170
220
|
- Nested runs (`asTool`) forward their events into the parent stream
|
|
171
221
|
with an extended `agentPath` — one subscription sees the tree.
|
|
172
222
|
|
|
@@ -176,7 +226,9 @@ const result = await run.result; // the no-streaming opt-out
|
|
|
176
226
|
|
|
177
227
|
All steering is plain typed functions; `policy` is sugar that
|
|
178
228
|
compiles into one gate. Gates run **before** the call; a deny becomes
|
|
179
|
-
a tool error the model reacts to; the run continues.
|
|
229
|
+
a tool error the model reacts to; the run continues. They run in
|
|
230
|
+
order — the `policy` gate, the agent's `toolGates`, the manifold's
|
|
231
|
+
`gates`, the run's `gates` — and the first deny ends the chain.
|
|
180
232
|
|
|
181
233
|
```ts
|
|
182
234
|
type GateDecision =
|
|
@@ -200,8 +252,17 @@ run.onEvent((e) => {
|
|
|
200
252
|
Suspended runs serialize: `run.snapshot()` → JSON →
|
|
201
253
|
`resumeRun(agent, snapshot, { llm, deps })` re-asks the pending
|
|
202
254
|
approval and continues — approvals survive reloads and restarts.
|
|
255
|
+
Re-asks means just that: the resumed run's gates run again for the
|
|
256
|
+
pending call and `approval-required` fires again, with a **new** id.
|
|
257
|
+
Answer with that event's id, as above. `snapshot.pending.approvalId` is
|
|
258
|
+
the ask of the run the snapshot was taken from; the resumed run did not
|
|
259
|
+
ask under it, and `approve` or `deny` with it does nothing.
|
|
260
|
+
The resumed run keeps the snapshot's run id, transcript, step and
|
|
261
|
+
output-retry counts, usage and elapsed time, so `stepCount`, `tokens`,
|
|
262
|
+
`duration` and `outputRetries` count on from there.
|
|
203
263
|
`policy.approvalTimeoutMs` turns an unanswered ask into a denial
|
|
204
|
-
(an observation, not a run failure).
|
|
264
|
+
(an observation, not a run failure). The denial's `reason` is
|
|
265
|
+
`approval timeout`.
|
|
205
266
|
|
|
206
267
|
---
|
|
207
268
|
|
|
@@ -238,6 +299,12 @@ The child's envelope maps to the tool result (`data` if present, else
|
|
|
238
299
|
`response`; override with `select`), and its events nest in the
|
|
239
300
|
parent stream.
|
|
240
301
|
|
|
302
|
+
A tool that runs an agent itself gets the same nesting from the
|
|
303
|
+
context `execute` is handed: `agent.run(input, { onEvent:
|
|
304
|
+
ctx.forward, agentPath: ctx.agentPath })`. `forward` puts the child's
|
|
305
|
+
events on the parent's stream, and the child appends its own id to
|
|
306
|
+
the path it is given.
|
|
307
|
+
|
|
241
308
|
---
|
|
242
309
|
|
|
243
310
|
## preview
|
|
@@ -249,7 +316,7 @@ const p = await agent.preview(input, { deps, llm });
|
|
|
249
316
|
p.strategy; // 'respond' | 'native' | 'emit' — what would actually run
|
|
250
317
|
p.messages; // the assembled prefix, including injected schema docs
|
|
251
318
|
p.tools; // real descriptors, including the respond tool's params
|
|
252
|
-
p.estimatedTokens;
|
|
319
|
+
p.estimatedTokens; // rough: characters / 4, plus 4 per message and 256 per non-text part
|
|
253
320
|
```
|
|
254
321
|
|
|
255
322
|
Anything you can't explain in the preview, the model can't either.
|
|
@@ -274,6 +341,24 @@ type CortexError = {
|
|
|
274
341
|
Tool failures are **observations**, not exceptions — the model sees
|
|
275
342
|
them and decides; the run fails only on structural conditions.
|
|
276
343
|
|
|
344
|
+
A tool's `input` schema validates; it does not convert. It does two
|
|
345
|
+
jobs: the model is sent its JSON Schema, taken from the schema's
|
|
346
|
+
output side, and a call's arguments are parsed with it twice — by the
|
|
347
|
+
loop, then again in front of `execute`. Converting belongs inside
|
|
348
|
+
`execute`, and this is what it costs in the schema:
|
|
349
|
+
|
|
350
|
+
- A schema with no JSON Schema (a `.transform()`, a `z.date()`) fails
|
|
351
|
+
the run before the model is asked: `code: 'unknown'`, with Zod's
|
|
352
|
+
message (`Transforms cannot be represented in JSON Schema`).
|
|
353
|
+
- A schema whose output is another kind than its input
|
|
354
|
+
(`z.stringbool()`) is described to the model by its output and then
|
|
355
|
+
refuses what its own first parse produced: every call ends in an
|
|
356
|
+
`error` observation and `execute` never runs.
|
|
357
|
+
- A schema that changes a value (`.overwrite()`) changes it twice.
|
|
358
|
+
That is harmless where a second pass changes nothing (`.trim()`),
|
|
359
|
+
and wrong where it does; the observation's `args` hold the value
|
|
360
|
+
as parsed once.
|
|
361
|
+
|
|
277
362
|
---
|
|
278
363
|
|
|
279
364
|
## Building
|
package/dist/index.cjs
CHANGED
|
@@ -209,8 +209,8 @@ var envelopeLooseWireSchema = (spec) => {
|
|
|
209
209
|
return zod.z.object({
|
|
210
210
|
reasoning: zod.z.string().nullish().describe(REASONING_DESCRIPTION),
|
|
211
211
|
response,
|
|
212
|
-
//
|
|
213
|
-
//
|
|
212
|
+
// Not z.unknown(): an empty {} schema tells the model no type, and it
|
|
213
|
+
// sends the payload as a string.
|
|
214
214
|
data: zod.z.union([zod.z.record(zod.z.string(), zod.z.unknown()), zod.z.array(zod.z.unknown())]).describe(LOOSE_DATA_DESCRIPTION)
|
|
215
215
|
});
|
|
216
216
|
}
|
|
@@ -221,12 +221,13 @@ var envelopeLooseWireSchema = (spec) => {
|
|
|
221
221
|
};
|
|
222
222
|
var envelopeAcceptSchema = (_spec) => zod.z.union([zod.z.record(zod.z.string(), zod.z.unknown()), zod.z.array(zod.z.unknown())]);
|
|
223
223
|
var KNOWN_KEYS = /* @__PURE__ */ new Set(["response", "data", "reasoning"]);
|
|
224
|
-
var
|
|
225
|
-
var
|
|
224
|
+
var takesAnyObject = (schema) => schema.safeParse({ "cortex:no-such-field": true }).success;
|
|
225
|
+
var asBarePayload = (record, spec) => {
|
|
226
226
|
if (!spec.schema || spec.responseMode === "required") return void 0;
|
|
227
227
|
const keys = Object.keys(record);
|
|
228
228
|
const looksWrapped = keys.length > 0 && keys.every((key) => KNOWN_KEYS.has(key));
|
|
229
229
|
if (looksWrapped) return void 0;
|
|
230
|
+
if (takesAnyObject(spec.schema)) return void 0;
|
|
230
231
|
const parsed = spec.schema.safeParse(record);
|
|
231
232
|
if (!parsed.success) return void 0;
|
|
232
233
|
return { data: parsed.data };
|
|
@@ -241,8 +242,8 @@ var validateEnvelope = (raw, spec) => {
|
|
|
241
242
|
if (!KNOWN_KEYS.has(key)) issues.push(`unknown key "${key}" \u2014 only response, data, reasoning are allowed`);
|
|
242
243
|
}
|
|
243
244
|
if (issues.length > 0) {
|
|
244
|
-
const
|
|
245
|
-
if (
|
|
245
|
+
const bare = asBarePayload(record, spec);
|
|
246
|
+
if (bare !== void 0) return { ok: true, envelope: bare };
|
|
246
247
|
}
|
|
247
248
|
const response = record["response"] ?? void 0;
|
|
248
249
|
if (spec.responseMode === "required" && typeof response !== "string") {
|
|
@@ -255,7 +256,7 @@ var validateEnvelope = (raw, spec) => {
|
|
|
255
256
|
issues.push("reasoning: must be a string");
|
|
256
257
|
}
|
|
257
258
|
if (spec.schema) {
|
|
258
|
-
const data =
|
|
259
|
+
const data = signal.decodeJsonish(record["data"]);
|
|
259
260
|
let parsed = spec.schema.safeParse(data);
|
|
260
261
|
if (!parsed.success) {
|
|
261
262
|
const repaired = spec.schema.safeParse(signal.deepDecodeJsonish(data));
|
|
@@ -365,13 +366,9 @@ var stringify = (value) => {
|
|
|
365
366
|
}
|
|
366
367
|
};
|
|
367
368
|
var buildToolDescriptor = (tool) => ({
|
|
368
|
-
// The model sees the tool's NAME — the field designed for it (prompts
|
|
369
|
-
// say "call `query`"). The id stays the gate/policy/observation
|
|
370
|
-
// identity; the loop resolves calls by either.
|
|
371
369
|
name: tool.config.name,
|
|
372
370
|
description: tool.config.description,
|
|
373
|
-
//
|
|
374
|
-
// the caller's zod copy, not ours.
|
|
371
|
+
// Converted by the schema's own zod, not by cortex's: it may come from another copy of zod.
|
|
375
372
|
parameters: tool.config.input["~standard"].jsonSchema.output({ target: "draft-07" })
|
|
376
373
|
});
|
|
377
374
|
var runLoop = async (cfg) => {
|
|
@@ -583,7 +580,7 @@ var runLoop = async (cfg) => {
|
|
|
583
580
|
return verdict;
|
|
584
581
|
};
|
|
585
582
|
const streamEmittedOutput = cfg.resolved.transport !== "respond";
|
|
586
|
-
const
|
|
583
|
+
const oneStep = async (llm, request) => {
|
|
587
584
|
if (cfg.transport === "step") {
|
|
588
585
|
try {
|
|
589
586
|
return ok(await llm.step(request));
|
|
@@ -689,7 +686,7 @@ var runLoop = async (cfg) => {
|
|
|
689
686
|
...cfg.resolved.outputToolName !== void 0 && { outputTool: cfg.resolved.outputToolName }
|
|
690
687
|
}
|
|
691
688
|
};
|
|
692
|
-
const stepOutcome = await
|
|
689
|
+
const stepOutcome = await oneStep(llm, request);
|
|
693
690
|
if (!stepOutcome.ok) return fail(stepOutcome.error);
|
|
694
691
|
const result = stepOutcome.data;
|
|
695
692
|
s.usage = addUsage(s.usage, result.usage);
|
|
@@ -891,6 +888,7 @@ var wireRun = (wiring) => {
|
|
|
891
888
|
if (options?.onEvent) channel.onEvent(options.onEvent);
|
|
892
889
|
const approvals = createApprovalBridge();
|
|
893
890
|
const controller = new AbortController();
|
|
891
|
+
let abortReason;
|
|
894
892
|
const externalSignal = options?.signal;
|
|
895
893
|
const onExternalAbort = () => controller.abort();
|
|
896
894
|
if (externalSignal) {
|
|
@@ -990,6 +988,9 @@ var wireRun = (wiring) => {
|
|
|
990
988
|
}
|
|
991
989
|
};
|
|
992
990
|
}
|
|
991
|
+
if (!outcome.ok && outcome.error.code === "aborted" && abortReason !== void 0) {
|
|
992
|
+
outcome = { ...outcome, error: { ...outcome.error, cause: abortReason } };
|
|
993
|
+
}
|
|
993
994
|
channel.emit({ type: "run-end", result: outcome, meta: outcome.meta });
|
|
994
995
|
channel.close();
|
|
995
996
|
if (externalSignal) externalSignal.removeEventListener("abort", onExternalAbort);
|
|
@@ -1015,7 +1016,10 @@ var wireRun = (wiring) => {
|
|
|
1015
1016
|
elapsedMs: state.elapsedBase + (Date.now() - state.startedAt),
|
|
1016
1017
|
...state.pending && { pending: state.pending }
|
|
1017
1018
|
}),
|
|
1018
|
-
abort: () =>
|
|
1019
|
+
abort: (reason) => {
|
|
1020
|
+
if (!controller.signal.aborted) abortReason = reason;
|
|
1021
|
+
controller.abort();
|
|
1022
|
+
}
|
|
1019
1023
|
};
|
|
1020
1024
|
};
|
|
1021
1025
|
var createRun = (definition, input, options) => wireRun({ definition, input, options, runId: newRunId() });
|
|
@@ -1092,8 +1096,6 @@ var previewAgent = async (definition, input, options) => {
|
|
|
1092
1096
|
...inputMessages(input)
|
|
1093
1097
|
];
|
|
1094
1098
|
const tools = [
|
|
1095
|
-
// The run's own builder — the preview shows the model-visible NAME,
|
|
1096
|
-
// not the id, or it would explain a request that never goes out.
|
|
1097
1099
|
...allTools.map(buildToolDescriptor),
|
|
1098
1100
|
...resolved.respondDescriptor ? [resolved.respondDescriptor] : []
|
|
1099
1101
|
];
|