@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 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> }`. Envelope-first precedence; safe only because
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 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
+ - **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 receives an error result and the other
177
- calls execute normally.
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, bounded by the `outputRetries` stop condition. Per-agent
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, bounded by
203
- `outputRetries`), same solid streaming via content deltas.
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 error result + continue)
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 incoming calls by name OR id; gates, observations and
265
- traces always carry the canonical id. Both namespaces must be
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 a stable id; the pending call blocks (tools are sequential, so
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 }` | raw envelope JSON fragments |
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* (a tool error result / an appended
89
- message) — never a full re-run. Big recursive schemas (Prism nodes,
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
- // A typed union, not z.unknown(): an empty {} schema gives the
213
- // model zero type signal and invites stringified payloads.
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 decodeData = signal.decodeJsonish;
225
- var tryUnwrap = (record, spec) => {
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 unwrapped = tryUnwrap(record, spec);
245
- if (unwrapped !== void 0) return { ok: true, envelope: unwrapped };
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 = decodeData(record["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
- // The tool's schema converts itself (Standard JSON Schema) — it may come from
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 streamOneStep = async (llm, request) => {
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 streamOneStep(llm, request);
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: () => controller.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
  ];