@niscorp/cortex 0.1.0 → 0.1.3

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 ADDED
@@ -0,0 +1,72 @@
1
+ # @niscorp/cortex
2
+
3
+ ## 0.1.3
4
+
5
+ ### Patch Changes
6
+
7
+ - 2756aa7: `run.abort(reason)` keeps its reason: it is the `cause` of the aborted result.
8
+
9
+ `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.
10
+
11
+ 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`.
12
+
13
+ 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.
14
+
15
+ **What to change:** nothing. If you already pass a reason to `run.abort`, the aborted result now carries it as `error.cause`.
16
+
17
+ - 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.
18
+
19
+ **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.
20
+
21
+ - 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:
22
+ - 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.
23
+ - 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.
24
+ - One that changes a value (`.overwrite()`) changes it twice, while the observation's `args` hold the value as parsed once.
25
+
26
+ Convert inside `execute`. The README says this under "Errors", and tests hold it. No code changed.
27
+
28
+ **What to change:** nothing.
29
+
30
+ - a02a031: The README and DESIGN say which approval id a resumed run answers to. No code changed.
31
+
32
+ `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.
33
+
34
+ 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.
35
+
36
+ **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.
37
+
38
+ - Updated dependencies [5923e38]
39
+ - Updated dependencies [2815107]
40
+ - Updated dependencies [885bc1e]
41
+ - Updated dependencies [f9f1b26]
42
+ - Updated dependencies [e3e0ff2]
43
+ - Updated dependencies [ed9d7f4]
44
+ - @niscorp/solid@0.1.2
45
+
46
+ ## 0.1.2
47
+
48
+ ### Patch Changes
49
+
50
+ - 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.
51
+
52
+ **What to change:** nothing.
53
+
54
+ - 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:
55
+
56
+ ```ts
57
+ import prism from '@niscorp/prism/package.json' with { type: 'json' };
58
+ prism.version; // the version that is installed, not the range that asked for it
59
+ ```
60
+
61
+ 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.
62
+
63
+ **What to change:** nothing. An app that read a version by path can read it by name.
64
+
65
+ - Updated dependencies [fe30458]
66
+ - @niscorp/solid@0.1.1
67
+
68
+ ## 0.1.1
69
+
70
+ ### Patch Changes
71
+
72
+ - b67a125: Documentation only: each package's README, reference and design docs checked against its source and corrected — install lines and peers, signatures, defaults, status codes, licenses (loom, signal: Apache-2.0), and API that existed but was not documented.
package/DESIGN.md CHANGED
@@ -49,7 +49,7 @@ JSON-parsing of streams (solid), no event-bus substrate, no
49
49
  declarative rules DSL, no plan interpreter (§14), no conversation
50
50
  persistence (callers own history).
51
51
 
52
- **Peers:** `@niscorp/signal`, `@niscorp/solid`, `zod`.
52
+ **Peers:** `@niscorp/signal`, `zod`. **Dependency:** `@niscorp/solid`.
53
53
 
54
54
  ---
55
55
 
@@ -168,17 +168,21 @@ Cortex registers one synthetic tool per run:
168
168
  `{ data: <raw> }`. Envelope-first precedence; safe only because
169
169
  real data schemas are strict and discriminating — a correct
170
170
  answer is never failed for missing its coat.
171
- - **Validation feedback in-loop.** Invalid `respond` args produce a
172
- tool error result carrying the Zod issues; the model retries the
173
- call. One extra step, transcript intact, tools still warm — never a
174
- full re-run.
171
+ - **Validation feedback in-loop.** Invalid `respond` args are
172
+ appended as the assistant's turn, followed by a system message
173
+ carrying the Zod issues; the model answers again. One extra step,
174
+ transcript intact, tools still warm — never a full re-run.
175
175
  - **`respond` must be called alone.** If it appears alongside other
176
- tool calls in one turn, it receives an error result and the other
177
- calls execute normally.
176
+ tool calls in one turn, it is dropped: the other calls execute
177
+ normally and the model is told nothing about it. Its arguments have
178
+ already streamed as `output-delta` and `output-partial` by then.
178
179
  - **Termination without a result** (model stops on prose that is not
179
180
  an envelope) is a protocol violation: cortex appends a correction
180
181
  offering both exits (call `respond`, or emit ONLY the envelope) and
181
- continues, bounded by the `outputRetries` stop condition. Per-agent
182
+ continues. These corrections are not counted against
183
+ `outputRetries`, which is for answers that parsed and were refused,
184
+ so it is `stepCount` (20 turns by default) that ends a run whose
185
+ model keeps writing prose. Per-agent
182
186
  hardening: `output.forceTool: true` sets `toolChoice: 'required'`
183
187
  so every turn must be a tool call and `respond` is the only exit —
184
188
  opt-in, because some models get tool-happy under `required`.
@@ -199,8 +203,9 @@ get grammar-level enforcement for free.
199
203
  The envelope travels on the content channel: the model's final
200
204
  completion IS the envelope, as raw JSON — no tool call, no provider
201
205
  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.
206
+ validation, same correction retries (appended messages; a refused
207
+ envelope counts against `outputRetries`, a turn with no envelope in
208
+ it does not), same solid streaming via content deltas.
204
209
  Fence-tolerant parse. It is `auto`'s floor: wherever neither grammar
205
210
  nor tool params would enforce the contract, the contract rides the
206
211
  prompt either way, and emit carries the answer without a synthetic
@@ -218,8 +223,8 @@ a content-only message.
218
223
  single-sourced from the same schema Zod validates against, so docs
219
224
  and validation cannot drift. When `respond` resolves to loose or
220
225
  permissive params (or strategy is `emit`), cortex injects
221
- `OUTPUT SCHEMA:\n…` as the
222
- last system chunk automatically. Agents that hand-author a full DSL
226
+ `OUTPUT SCHEMA …` as a
227
+ system chunk automatically (placement: §5). Agents that hand-author a full DSL
223
228
  guide (the architect pattern) disable it with `output.doc: 'off'` or
224
229
  replace it with a string.
225
230
 
@@ -232,7 +237,7 @@ prefix = assemble(context fns, input) — once, at run start
232
237
  messages = [...prefix] — append-only from here on
233
238
 
234
239
  step:
235
- stopWhen checks (steps, tokens, duration, outputRetries)
240
+ stopWhen checks (steps, tokens, duration, outputRetries, repeatedCalls)
236
241
  prepareStep hook → activeTools mask, toolChoice, injected messages, llm swap
237
242
  signal.stepStream({ messages, tools, responseFormat? })
238
243
  → model-delta events (text + reasoning channels)
@@ -242,7 +247,7 @@ step:
242
247
  execute (Zod-validated input, timeout)
243
248
  onToolResult hooks (replace / redact / truncate)
244
249
  append tool result message; emit tool-end observation
245
- respond call → validate envelope → end (or error result + continue)
250
+ respond call → validate envelope → end (or correction + continue)
246
251
  ```
247
252
 
248
253
  Rules the loop lives by:
@@ -259,10 +264,16 @@ Rules the loop lives by:
259
264
  denied call becomes an error result the model sees and reacts to.
260
265
  The run only fails on structural conditions (stop limits, model
261
266
  call failure, abort, retries exhausted).
267
+ - **A tool's `input` is enforced; its `output` is a type.** The input
268
+ schema is parsed before `execute` runs. The optional `output`
269
+ schema types what `execute` returns and is not applied at runtime:
270
+ the return value is not parsed, stripped or transformed by it.
262
271
  - **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
272
+ Descriptors carry the name (prompts say "call `query`"); the loop's
273
+ own table resolves a call by name OR id, but Signal routes only the
274
+ names it was sent, so through Signal a call by id is read as an
275
+ attempted answer and never reaches that table; gates, observations
276
+ and traces always carry the canonical id. Both namespaces must be
266
277
  collision-free per run, and nothing may claim `respond`. (v1 sent
267
278
  ids on the wire while documenting names — a prompt-literal model
268
279
  exposed the lie.)
@@ -274,9 +285,13 @@ Bounds are `stopWhen` predicates — one vocabulary instead of v1's
274
285
  maxToolIterations / maxTicks / maxDurationMs / budget tangle:
275
286
 
276
287
  ```ts
277
- stopWhen: [stepCount(20), tokens(100_000), duration('5m'), outputRetries(3)]
288
+ stopWhen: [stepCount(20), tokens(100_000), duration('5m'), outputRetries(3), repeatedCalls(3)]
278
289
  ```
279
290
 
291
+ `repeatedCalls(n)` ends a run whose model keeps sending the same tool
292
+ call and getting the same answer — every further step would cost a
293
+ full prompt and change nothing.
294
+
280
295
  Defaults: `stepCount(20)`, `outputRetries(3)`. No default duration or
281
296
  token cap — v1's 60-second default was overridden at every call site,
282
297
  which is what a wrong default looks like.
@@ -326,14 +341,19 @@ that is how knowledge drifts.
326
341
  agent's own — an app attaches shared knowledge to ANY agent without
327
342
  editing its definition.
328
343
  - **Tools bring their own guides.** `defineTool({ guide })` carries
329
- the tool's usage knowledge (a string or a deferred `() => string`,
344
+ the tool's usage knowledge (a string, a `string[]` of lines, or a
345
+ deferred function returning either,
330
346
  e.g. composing a library's exported guide). The run assembles one
331
347
  TOOL GUIDES section from the ACTIVE tools — add a tool and its
332
348
  guide arrives, change it and every agent updates, remove it and the
333
349
  guide leaves. Instructions never describe tools.
334
- - Prefix order: instructions → agent producers → run producers →
335
- tool guides → schema doc → finish protocol → input. The finish
336
- protocol is ONE cortex-owned chunk stating how the run ends under
350
+ - Prefix order: instructions → tool guides → schema doc → finish
351
+ protocol → agent producers → run producers → input. The three
352
+ middle blocks are fixed for the life of an agent, so they sit ahead
353
+ of the producers, which are not — a provider's prefix cache stops at
354
+ the first byte that changed. The finish
355
+ protocol is ONE chunk — authored by signal's transport, injected by
356
+ cortex verbatim — stating how the run ends under
337
357
  the RESOLVED transport (call `respond` / emit the envelope / reply
338
358
  under grammar) — agents never author finish lines; they cannot know
339
359
  which transport resolution picked.
@@ -348,7 +368,7 @@ that is how knowledge drifts.
348
368
  - Compaction (summarize-when-near-limit) is a future single hook on
349
369
  the transcript (§15), not a v1 pipeline.
350
370
 
351
- **Preview survives, better.** `agent.preview(input, { deps })`
371
+ **Preview survives, better.** `await agent.preview(input, { deps })`
352
372
  returns the exact assembled messages, the resolved tool list
353
373
  (including `respond` and its actual params), the resolved strategy,
354
374
  and a token estimate — no model call. Anything you can't explain in
@@ -372,10 +392,10 @@ type ToolGate<TDeps> = (call: ToolCallInfo, ctx: RunCtx<TDeps>) =>
372
392
  type ToolResultHook<TDeps> = (obs: ToolObservation, ctx: RunCtx<TDeps>) =>
373
393
  { result?: unknown } | void | Promise<…>; // replace / redact / truncate
374
394
 
375
- type PrepareStep<TDeps> = (s: StepInfo<TDeps>) =>
376
- { activeTools?: string[]; toolChoice?: ToolChoice; inject?: Message[]; llm?: SignalClient } | void;
395
+ type PrepareStep<TDeps> = (s: PrepareStepInfo<TDeps>) =>
396
+ { activeTools?: string[]; toolChoice?: ToolChoice; inject?: Message[]; llm?: SignalClient } | void | Promise<…>;
377
397
 
378
- type StopCondition = (s: RunProgress) => boolean;
398
+ type StopCondition = (s: RunProgress) => StopVerdict; // { stop: StopReason; message } | null
379
399
  ```
380
400
 
381
401
  - **Gates run before execution.** A deny reaches the model as a tool
@@ -393,12 +413,20 @@ type StopCondition = (s: RunProgress) => boolean;
393
413
  compiles to one built-in gate. Anything the sugar can't express is
394
414
  a function.
395
415
  - **Approvals suspend the run.** `ask` emits `approval-required`
396
- with a stable id; the pending call blocks (tools are sequential, so
416
+ with an id that is that ask's for as long as the run handle lives —
417
+ the event, `run.approve` / `run.deny` and `run.snapshot()` all name
418
+ it; the pending call blocks (tools are sequential, so
397
419
  one pending approval at a time). `run.approve(id, { args? })` —
398
420
  approve, optionally with edited args — or `run.deny(id, reason)`.
421
+ An id the handle did not ask under is ignored.
399
422
  `run.snapshot()` serializes the suspended run (messages, pending
400
423
  call, usage); `resumeRun(agent, snapshot, opts)` restores it — so
401
- approvals survive reloads and restarts.
424
+ approvals survive reloads and restarts. A resumed run **re-asks**:
425
+ its gates run again for the pending call (if they no longer ask, the
426
+ call simply runs) and `approval-required` fires with a new id — the
427
+ one the resumed handle answers to. `snapshot.pending.approvalId`
428
+ names the ask of the run the snapshot came from, not the resumed
429
+ one's.
402
430
  - **Output validation** closes the generate→verify loop in-run:
403
431
 
404
432
  ```ts
@@ -438,8 +466,8 @@ const result = await run.result;
438
466
  | `model-delta` | `{ text, channel: 'text' \| 'reasoning' }` | provider reasoning tokens land here |
439
467
  | `tool-start` | `{ call }` | before gates + execution — drives live UIs |
440
468
  | `tool-end` | `{ observation }` | typed union incl. denials; no casting |
441
- | `approval-required` | `{ id, toolId, args, reason }` | run suspends |
442
- | `output-delta` | `{ text }` | raw envelope JSON fragments |
469
+ | `approval-required` | `{ approval: { id, toolId, callId, args, reason } }` | run suspends |
470
+ | `output-delta` | `{ text }` | the output channel as it streams; the envelope's JSON on the step that ends the run |
443
471
  | `output-partial` | `{ output }` | solid-parsed partial envelope |
444
472
  | `retry` | `{ kind: 'output' \| 'termination' \| 'provider', attempt, issues }` | consumers reset partial state; `issues` carries the evidence (Zod issues, the rejected attempt, or the stray text) |
445
473
  | `run-end` | `{ result, meta }` | |
@@ -503,10 +531,12 @@ Same two principles as v1, smaller taxonomy:
503
531
  ```ts
504
532
  type CortexError = {
505
533
  code: 'model_call_failed' | 'output_invalid' | 'stopped' | 'aborted' | 'unknown';
506
- stop?: 'steps' | 'tokens' | 'duration' | 'output_retries' | 'custom'; // when code === 'stopped'
534
+ stop?: StopReason; // when code === 'stopped':
535
+ // 'steps' | 'tokens' | 'duration' | 'output_retries' | 'repeated_calls' | 'custom'
507
536
  message: string;
508
537
  runId: string;
509
538
  agentPath: ReadonlyArray<string>;
539
+ lastOutput?: unknown; // the last invalid output when the run died on output retries
510
540
  cause?: unknown;
511
541
  };
512
542
  ```
@@ -519,7 +549,7 @@ principle as every other tool denial.
519
549
 
520
550
  ## 10. Streaming
521
551
 
522
- Always on (§4). Solid is a peer dependency and powers
552
+ Always on (§4). Solid is a dependency and powers
523
553
  `output-partial`: `respond` arg deltas (or content deltas under
524
554
  `native`/`emit`) stream through solid's partial parser into
525
555
  progressively-typed envelopes — a chat `response` string streams
@@ -538,36 +568,45 @@ defineTool(config): ToolDefinition // v1 shape, kept
538
568
  schemaDoc(schema, opts?): string
539
569
 
540
570
  // execution
541
- agent.run(input, { deps, llm?, tools?, gates?, onToolResult?, onEvent?, signal? }): RunHandle<TData>
571
+ agent.run(input, { deps, llm?, tools?, producers?, gates?, onToolResult?, onEvent?, signal? }): RunHandle<TData>
542
572
  // tools: per-run tools whose execute closes over per-invocation
543
573
  // dependencies (vex builds its query tools around the caller's
544
574
  // adapter + schema); appended to the agent's static tools.
545
- agent.preview(input, { deps }): ResolvedPreview
575
+ agent.preview(input, { deps }): Promise<ResolvedPreview>
546
576
  resumeRun(agent, snapshot, opts): RunHandle<TData>
547
577
 
548
578
  // RunHandle
549
579
  run.events: AsyncIterable<CortexEvent>
580
+ run.onEvent(listener): Unsubscribe
550
581
  run.result: Promise<RunResult<TData>>
551
582
  run.approve(id, { args? }) / run.deny(id, reason?)
552
583
  run.snapshot(): RunSnapshot
553
584
  run.abort(reason?)
585
+ // the reason is `error.cause` of the `aborted` result. A tool's
586
+ // ctx.signal still aborts with an AbortError, never with the reason.
554
587
 
555
588
  // composition
556
- createManifold({ llm, gates?, onRun? }): Manifold
557
- manifold.register / run / asTool / preview
589
+ createManifold({ llm?, gates?, onRun? }): Manifold
590
+ manifold.register / run / asTool / preview / agent / tool / agents / tools
591
+ asTool(agent, { id?, description?, llm?, timeoutMs?, deps, select? }): ToolDefinition
592
+
593
+ // gates
594
+ policyGate(policy): ToolGate
558
595
 
559
596
  // stop conditions
560
- stepCount(n), tokens(n), duration(ms | '5m'), outputRetries(n)
597
+ stepCount(n), tokens(n), duration(ms | '5m'), outputRetries(n), repeatedCalls(n)
598
+ DEFAULT_STOP_CONDITIONS // [stepCount(20), outputRetries(3)]
561
599
  ```
562
600
 
563
601
  `defineAgent` config:
564
602
 
565
603
  ```ts
566
604
  {
567
- id, description,
568
- llm?, // per-agent binding; manifold/run option is fallback
605
+ id, description?,
606
+ llm?, // per-agent binding; run option overrides it, manifold is the fallback
607
+ transport?: 'stream' | 'step', // default 'stream'; 'step' makes non-streaming calls (no deltas, no partials)
569
608
  instructions, // string | (ctx) => string — sugar for the first producer
570
- context?: Producer<TDeps>[], // compose shared sets by spreading: [...appProducers(), …]
609
+ context?: (ContextEntry | Producer<TDeps>)[], // compose shared sets by spreading: [...appProducers(), …]
571
610
  tools?: ToolDefinition[], // definitions, not id strings; each may carry its own `guide`
572
611
  output?: {
573
612
  schema?: ZodType<TData>, // omitted → pure chat agent (data: undefined)
@@ -585,6 +624,9 @@ stepCount(n), tokens(n), duration(ms | '5m'), outputRetries(n)
585
624
 
586
625
  ## 12. Signal changes this design requires
587
626
 
627
+ Items 1–3 are built; the text below is the requirement as it was
628
+ written. The tokenizer in item 4 has not landed.
629
+
588
630
  1. **`stepStream` emits `tool-call-delta`** — `{ index, id?, name?,
589
631
  argsText }` fragments as function args stream. The SSE chunks
590
632
  already contain them; the adapter currently drops them. This is
@@ -657,20 +699,20 @@ src/
657
699
  ├── types.ts # shared core types
658
700
  │
659
701
  ├── schemas/
660
- │ ├── envelope.schema.ts # Envelope<TData> factory
661
- │ ├── agent-config.schema.ts
702
+ │ ├── index.ts
703
+ │ ├── envelope.schema.ts # envelope wire / accept schemas, validateEnvelope
662
704
  │ └── tool-config.schema.ts
663
705
  │
664
706
  ├── agent/
665
707
  │ ├── define-agent.ts
666
- │ ├── run.ts # RunHandle, resumeRun
708
+ │ ├── run.ts # RunHandle, resumeRun, prefix assembly
667
709
  │ └── preview.ts
668
710
  │
669
711
  ├── loop/
670
712
  │ ├── loop.ts # the loop (§4) — all three transports
671
- │ ├── strategy-resolve.ts # auto resolution + strict-compat walk
672
- │ ├── respond-tool.ts # synthetic respond descriptor + corrections
673
713
  │ └── partials.ts # solid partial-output tracking
714
+ │ # (auto resolution, the strict-compat walk, the respond
715
+ │ # descriptor and corrections are signal's: src/transport/)
674
716
  │
675
717
  ├── context/
676
718
  │ ├── assemble.ts
@@ -679,15 +721,17 @@ src/
679
721
  ├── gates/
680
722
  │ ├── types.ts
681
723
  │ ├── policy.ts # sugar → built-in gate
682
- │ └── approval.ts # suspend / approve / deny / snapshot
724
+ │ ├── stop.ts # stop conditions + defaults
725
+ │ └── approval.ts # suspend / approve / deny
683
726
  │
684
727
  ├── events/
685
728
  │ ├── types.ts # CortexEvent vocabulary
686
- │ └── stream.ts # per-run emitter + forwarding
729
+ │ └── channel.ts # per-run emitter + forwarding
687
730
  │
688
731
  ├── manifold/
689
732
  │ ├── manifold.ts
690
- │ └── as-tool.ts
733
+ │ ├── as-tool.ts
734
+ │ └── types.ts # erased agent shapes
691
735
  │
692
736
  ├── tool/define-tool.ts
693
737
  ├── errors/cortex.errors.ts
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
  ---
@@ -85,9 +89,9 @@ How the envelope travels from model to runtime. One field,
85
89
  | `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
90
 
87
91
  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
92
+ correction *inside the same run* (the attempt and a system message
93
+ naming the issues are appended) — never a full re-run. Big recursive
94
+ schemas (Prism nodes, Nova actions) ride `emit`; cortex injects
91
95
  the JSON Schema into the prompt automatically (`output.doc: 'auto'`,
92
96
  via `schemaDoc()` — single-sourced from the Zod schema).
93
97
 
@@ -127,7 +131,17 @@ const agent = defineAgent<Data, Deps>({
127
131
  Deps are per-invocation, typed, and consumed by context entries,
128
132
  gates and hooks — agents are defined once, never rebuilt per call.
129
133
  Defaults when `stopWhen` is omitted: `stepCount(20)`,
130
- `outputRetries(3)`.
134
+ `outputRetries(3)`. A `stopWhen` you pass replaces both, so keep a
135
+ `stepCount` in it: `outputRetries` counts refused answers only, and
136
+ a turn of prose with no envelope in it is corrected without being
137
+ counted. `outputRetries(n)` ends the run at the n-th refused answer:
138
+ n attempts, n − 1 corrections, so `outputRetries(1)` allows no
139
+ second attempt.
140
+
141
+ `policy.tools` lists take tool **ids** (`tool.id`), not the names
142
+ the model calls: a name in `deny` or `requireApproval` matches
143
+ nothing and says nothing, and a name in `allow` leaves the tool off
144
+ the list.
131
145
 
132
146
  Multi-turn history is caller-owned: `input` accepts a `string`, a
133
147
  `Message[]` transcript, or any JSON value.
@@ -160,11 +174,22 @@ const result = await run.result; // the no-streaming opt-out
160
174
 
161
175
  - `tool-start` fires **before** execution — drives live "running…" UIs.
162
176
  - `tool-end` carries a typed `ToolObservation` union (result / error /
163
- denied / unknown-tool). No casting.
177
+ denied / unknown-tool). No casting. Through Signal, `unknown-tool`
178
+ is rare: Signal routes only calls to tools the step declared, and
179
+ reads a call to any other name as an attempted answer. It is
180
+ validated as the envelope (a `retry`, or the run's output if it
181
+ passes), or dropped when it comes beside a call to a declared tool,
182
+ and never reaches `tool-start`. The kind arises when `resumeRun` is
183
+ not handed the per-run tool the pending call names, or with a
184
+ client that does its own routing.
164
185
  - `output-delta` streams the raw envelope JSON as it generates;
165
186
  `output-partial` streams the progressively parsed envelope via
166
187
  [`@niscorp/solid`](../solid) — a chat `response` streams token-ish,
167
188
  a Nova screen in `data` becomes renderable before the run ends.
189
+ Both stream before cortex knows how the step ends: words written
190
+ beside a tool call (under `emit` and `native`) and a `respond` sent
191
+ beside other calls arrive as `output-delta` too and are not the
192
+ answer. The answer is what the last step streamed.
168
193
  - `retry` resets partial-output state (same contract consumers had
169
194
  in v1).
170
195
  - Nested runs (`asTool`) forward their events into the parent stream
@@ -200,6 +225,11 @@ run.onEvent((e) => {
200
225
  Suspended runs serialize: `run.snapshot()` → JSON →
201
226
  `resumeRun(agent, snapshot, { llm, deps })` re-asks the pending
202
227
  approval and continues — approvals survive reloads and restarts.
228
+ Re-asks means just that: the resumed run's gates run again for the
229
+ pending call and `approval-required` fires again, with a **new** id.
230
+ Answer with that event's id, as above. `snapshot.pending.approvalId` is
231
+ the ask of the run the snapshot was taken from; the resumed run did not
232
+ ask under it, and `approve` or `deny` with it does nothing.
203
233
  `policy.approvalTimeoutMs` turns an unanswered ask into a denial
204
234
  (an observation, not a run failure).
205
235
 
@@ -264,7 +294,7 @@ conditions return:
264
294
  ```ts
265
295
  type CortexError = {
266
296
  code: 'model_call_failed' | 'output_invalid' | 'stopped' | 'aborted' | 'unknown';
267
- stop?: 'steps' | 'tokens' | 'duration' | 'output_retries' | 'custom';
297
+ stop?: 'steps' | 'tokens' | 'duration' | 'output_retries' | 'repeated_calls' | 'custom';
268
298
  message: string;
269
299
  runId: string;
270
300
  agentPath: ReadonlyArray<string>;
@@ -274,6 +304,24 @@ type CortexError = {
274
304
  Tool failures are **observations**, not exceptions — the model sees
275
305
  them and decides; the run fails only on structural conditions.
276
306
 
307
+ A tool's `input` schema validates; it does not convert. It does two
308
+ jobs: the model is sent its JSON Schema, taken from the schema's
309
+ output side, and a call's arguments are parsed with it twice — by the
310
+ loop, then again in front of `execute`. Converting belongs inside
311
+ `execute`, and this is what it costs in the schema:
312
+
313
+ - A schema with no JSON Schema (a `.transform()`, a `z.date()`) fails
314
+ the run before the model is asked: `code: 'unknown'`, with Zod's
315
+ message (`Transforms cannot be represented in JSON Schema`).
316
+ - A schema whose output is another kind than its input
317
+ (`z.stringbool()`) is described to the model by its output and then
318
+ refuses what its own first parse produced: every call ends in an
319
+ `error` observation and `execute` never runs.
320
+ - A schema that changes a value (`.overwrite()`) changes it twice.
321
+ That is harmless where a second pass changes nothing (`.trim()`),
322
+ and wrong where it does; the observation's `args` hold the value
323
+ as parsed once.
324
+
277
325
  ---
278
326
 
279
327
  ## Building
@@ -281,7 +329,7 @@ them and decides; the run fails only on structural conditions.
281
329
  ```bash
282
330
  pnpm build # tsup ESM + CJS + DTS
283
331
  pnpm test # vitest run — scripted SignalClient stub, no network
284
- pnpm typecheck # tsc on src
332
+ pnpm typecheck # tsc on src + test
285
333
  ```
286
334
 
287
335
  ---
package/dist/index.cjs CHANGED
@@ -891,6 +891,7 @@ var wireRun = (wiring) => {
891
891
  if (options?.onEvent) channel.onEvent(options.onEvent);
892
892
  const approvals = createApprovalBridge();
893
893
  const controller = new AbortController();
894
+ let abortReason;
894
895
  const externalSignal = options?.signal;
895
896
  const onExternalAbort = () => controller.abort();
896
897
  if (externalSignal) {
@@ -990,6 +991,9 @@ var wireRun = (wiring) => {
990
991
  }
991
992
  };
992
993
  }
994
+ if (!outcome.ok && outcome.error.code === "aborted" && abortReason !== void 0) {
995
+ outcome = { ...outcome, error: { ...outcome.error, cause: abortReason } };
996
+ }
993
997
  channel.emit({ type: "run-end", result: outcome, meta: outcome.meta });
994
998
  channel.close();
995
999
  if (externalSignal) externalSignal.removeEventListener("abort", onExternalAbort);
@@ -1015,7 +1019,10 @@ var wireRun = (wiring) => {
1015
1019
  elapsedMs: state.elapsedBase + (Date.now() - state.startedAt),
1016
1020
  ...state.pending && { pending: state.pending }
1017
1021
  }),
1018
- abort: () => controller.abort()
1022
+ abort: (reason) => {
1023
+ if (!controller.signal.aborted) abortReason = reason;
1024
+ controller.abort();
1025
+ }
1019
1026
  };
1020
1027
  };
1021
1028
  var createRun = (definition, input, options) => wireRun({ definition, input, options, runId: newRunId() });