@niscorp/cortex 0.1.4 → 0.1.6

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,28 @@
1
1
  # @niscorp/cortex
2
2
 
3
+ ## 0.1.6
4
+
5
+ ### Patch Changes
6
+
7
+ - 41ac0c7: DESIGN.md and the README say what the code does: the loop streams unless `transport: 'step'`, no event carries per-step usage, the schema check is conversion, no `$ref` and at most 8,192 characters (native also needs `nativeJsonSchema` and is sent with `strict: false`), `onRun` is an option of `createManifold`, and `agent.run` takes `agentPath`.
8
+
9
+ **What to change:** nothing. Documentation only.
10
+
11
+ - Updated dependencies [a2d2df0]
12
+ - @niscorp/solid@0.1.3
13
+
14
+ ## 0.1.5
15
+
16
+ ### Patch Changes
17
+
18
+ - e7c45c3: A tool call whose arguments fail their schema is told which field is wrong, as an output is. The loop printed zod's top-level issues as they were, so a union in a tool's input came back as `: Invalid input`; it now goes through `flattenSchemaIssues`, as output does (`view.title: Invalid input: expected string, received undefined`).
19
+
20
+ `flattenSchemaIssues` reports a record key that breaks its rule with the rule's own message (`scores.Bad: keys are lower-case letters`) instead of zod's outer `Invalid key in record`. `SchemaIssue` gains two optional fields, `issues` and `origin`, which zod's issues already carry.
21
+
22
+ How a branch of a failed union is chosen is unchanged.
23
+
24
+ **What to change:** nothing.
25
+
3
26
  ## 0.1.4
4
27
 
5
28
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -88,7 +88,7 @@ type RunResult<TData> =
88
88
  | { ok: false; error: CortexError; meta: RunMeta };
89
89
 
90
90
  type RunMeta = {
91
- usage: Usage; // aggregated; per-step usage rides on events
91
+ usage: Usage; // the run's total; no event carries per-step usage
92
92
  strategy: OutputStrategy; // what actually ran
93
93
  steps: number;
94
94
  outputRetries: number;
@@ -134,9 +134,9 @@ at most syntax; cortex enforces the contract.
134
134
 
135
135
  Cortex registers one synthetic tool per run:
136
136
 
137
- - **Params, auto-detailed.** If the serialized `data` schema is
138
- strict-compatible (no recursion, no open records, no refinements)
139
- and small (≤ ~8 KB serialized), it is inlined into the tool params.
137
+ - **Params, auto-detailed.** If the envelope schema with `data`
138
+ converts to JSON Schema, contains no `$ref` and serializes to at
139
+ most 8,192 characters, it is inlined into the tool params.
140
140
  Otherwise params are loose (`data: object, see OUTPUT SCHEMA in the
141
141
  system prompt`) and the schema documentation is injected into
142
142
  context (§3.4). This is what makes Prism's `NodeSchema` and Nova's
@@ -196,11 +196,13 @@ Cortex registers one synthetic tool per run:
196
196
 
197
197
  ### 3.2 `native`
198
198
 
199
- `auto` picks it only when the provider capability
200
- `toolsWithStructuredOutput` is true (or the agent has no tools) AND
201
- the envelope schema passes the strict-compatibility walk. Small
202
- extractors and classifiers on OpenAI-class providers land here and
203
- get grammar-level enforcement for free.
199
+ `auto` picks it only when the agent has an output schema, the model
200
+ capability `nativeJsonSchema` is true, `toolsWithStructuredOutput` is
201
+ true (or the agent has no tools) AND the envelope schema passes the
202
+ same check as `respond`'s inlined params (converts, no `$ref`, ≤ 8,192
203
+ characters). The schema is sent as `response_format` with
204
+ `strict: false`. Small extractors and classifiers on OpenAI-class
205
+ providers land here.
204
206
 
205
207
  ### 3.3 `emit`
206
208
 
@@ -281,9 +283,10 @@ Rules the loop lives by:
281
283
  collision-free per run, and nothing may claim `respond`. (v1 sent
282
284
  ids on the wire while documenting names — a prompt-literal model
283
285
  exposed the lie.)
284
- - **Streaming is not a mode.** The loop always consumes
285
- `signal.stepStream`; `await run.result` is the opt-out. There is no
286
- `stream: true` bifurcation to test twice.
286
+ - **Streaming is the default.** The loop consumes `signal.stepStream`
287
+ unless the agent sets `transport: 'step'`, which calls `llm.step()`
288
+ and emits no deltas or partials (§11); `await run.result` is the
289
+ consumer's opt-out.
287
290
 
288
291
  Bounds are `stopWhen` predicates — one vocabulary instead of v1's
289
292
  maxToolIterations / maxTicks / maxDurationMs / budget tangle:
@@ -445,8 +448,9 @@ type StopCondition = (s: RunProgress) => StopVerdict; // { stop: StopReason; m
445
448
  hand-rolled verify-once harness bolt-on.)
446
449
 
447
450
  What hooks deliberately can't do: react to *other* runs (cross-run
448
- choreography is app code around `manifold.onRun`), mutate past
449
- transcript (append-only is load-bearing), veto text mid-generation
451
+ choreography is app code in the `onRun` option of
452
+ `createManifold`), mutate past transcript (append-only is
453
+ load-bearing), veto text mid-generation
450
454
  (validation happens at boundaries: tool call, step end, output). If
451
455
  remotely-configured steering is ever needed, it lands as a compiler
452
456
  from a config shape *to* a gate function — on top, not underneath.
@@ -479,8 +483,9 @@ const result = await run.result;
479
483
  Every event carries `{ runId, agentPath, seq, ts }`. When an agent
480
484
  runs inside another (`asTool`), the child's events forward into the
481
485
  parent stream with the extended `agentPath` — one subscription sees
482
- the whole tree. Per-step usage rides on step events and aggregates
483
- into `RunMeta.usage`; that is the whole ledger.
486
+ the whole tree. No event carries usage: the run's total is
487
+ `RunMeta.usage`, which `run-end` carries in its `meta`; that is the
488
+ whole ledger.
484
489
 
485
490
  Process-level watching is the manifold's tap: `onRun(run => …)` hands
486
491
  you every run created through it. That is the one legitimate job the
@@ -553,7 +558,8 @@ principle as every other tool denial.
553
558
 
554
559
  ## 10. Streaming
555
560
 
556
- Always on (§4). Solid is a dependency and powers
561
+ On unless the agent sets `transport: 'step'` (§4). Solid is a
562
+ dependency and powers
557
563
  `output-partial`: `respond` arg deltas (or content deltas under
558
564
  `native`/`emit`) stream through solid's partial parser into
559
565
  progressively-typed envelopes — a chat `response` string streams
@@ -572,7 +578,7 @@ defineTool(config): ToolDefinition // v1 shape, kept
572
578
  schemaDoc(schema, opts?): string
573
579
 
574
580
  // execution
575
- agent.run(input, { deps, llm?, tools?, producers?, gates?, onToolResult?, onEvent?, signal? }): RunHandle<TData>
581
+ agent.run(input, { deps, llm?, tools?, producers?, gates?, onToolResult?, onEvent?, signal?, agentPath? }): RunHandle<TData>
576
582
  // tools: per-run tools whose execute closes over per-invocation
577
583
  // dependencies (vex builds its query tools around the caller's
578
584
  // adapter + schema); appended to the agent's static tools.
@@ -715,7 +721,7 @@ src/
715
721
  ├── loop/
716
722
  │ ├── loop.ts # the loop (§4) — all three transports
717
723
  │ └── partials.ts # solid partial-output tracking
718
- │ # (auto resolution, the strict-compat walk, the respond
724
+ │ # (auto resolution, the schema size/`$ref` check, the respond
719
725
  │ # descriptor and corrections are signal's: src/transport/)
720
726
  │
721
727
  ├── context/
package/README.md CHANGED
@@ -86,7 +86,7 @@ How the envelope travels from model to runtime. One field,
86
86
 
87
87
  | Strategy | Mechanism | Fits |
88
88
  |---|---|---|
89
- | `native` | provider `response_format: json_schema`, in-loop | small strict-compatible schemas on capable providers (auto-picked) |
89
+ | `native` | provider `response_format: json_schema`, in-loop | an output schema whose envelope converts to JSON Schema with no `$ref` in ≤ 8,192 characters, on a model with `nativeJsonSchema` (auto-picked; sent with `strict: false`) |
90
90
  | `respond` | a synthesized `respond` tool; the envelope is its arguments | where the tool params can ENFORCE the contract — the endpoint does not validate tool args itself, the schema is small, the model carries nested args intact (auto-picked there) |
91
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 |
92
92
 
package/dist/index.cjs CHANGED
@@ -177,6 +177,9 @@ var pickBranch = (branches) => branches.reduce((best, branch) => {
177
177
  });
178
178
  var flattenSchemaIssues = (issues, prefix = []) => issues.flatMap((issue) => {
179
179
  const path = [...prefix, ...issue.path];
180
+ if (issue.code === "invalid_key" && issue.origin === "record" && issue.issues && issue.issues.length > 0) {
181
+ return flattenSchemaIssues(issue.issues, path);
182
+ }
180
183
  if (issue.code !== "invalid_union" || !issue.errors || issue.errors.length === 0) return [{ ...issue, path }];
181
184
  return flattenSchemaIssues(pickBranch(issue.errors), path);
182
185
  });
@@ -504,7 +507,7 @@ var runLoop = async (cfg) => {
504
507
  if (repaired.success) parsedArgs = repaired;
505
508
  }
506
509
  if (!parsedArgs.success) {
507
- const issues = parsedArgs.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
510
+ const issues = flattenSchemaIssues(parsedArgs.error.issues).map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
508
511
  const hint = typeof args === "string" ? ' (your arguments arrived as ONE STRING \u2014 call again with a plain JSON object, e.g. {"key": "value"})' : isEmptyObject(args) ? ` (your arguments arrived EMPTY \u2014 nothing was sent. Call ${toolId} again with its arguments filled in, as its parameters describe)` : "";
509
512
  record(
510
513
  call,