@niscorp/cortex 0.1.3 → 0.1.5

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,37 @@
1
1
  # @niscorp/cortex
2
2
 
3
+ ## 0.1.5
4
+
5
+ ### Patch Changes
6
+
7
+ - 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`).
8
+
9
+ `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.
10
+
11
+ How a branch of a failed union is chosen is unchanged.
12
+
13
+ **What to change:** nothing.
14
+
15
+ ## 0.1.4
16
+
17
+ ### Patch Changes
18
+
19
+ - 1dcccd7: An envelope with a misspelt key is no longer accepted as the agent's data.
20
+
21
+ 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.
22
+
23
+ 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.
24
+
25
+ **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.
26
+
27
+ - 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.
28
+
29
+ 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.
30
+
31
+ No behaviour changed.
32
+
33
+ **What to change:** nothing.
34
+
3
35
  ## 0.1.3
4
36
 
5
37
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -165,7 +165,11 @@ 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
175
  - **Validation feedback in-loop.** Invalid `respond` args are
package/README.md CHANGED
@@ -67,7 +67,9 @@ A chat agent omits `output.schema` (its `response` becomes required);
67
67
  a data agent sets it; a rich assistant returns both — prose *and* a
68
68
  payload in one turn. Run-level metadata (usage, resolved strategy,
69
69
  attempts, elapsed) is authored by cortex on `result.meta`, never by
70
- 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.
71
73
 
72
74
  ```ts
73
75
  const result = await agent.run(input, { llm, deps }).result;
@@ -136,13 +138,26 @@ Defaults when `stopWhen` is omitted: `stepCount(20)`,
136
138
  a turn of prose with no envelope in it is corrected without being
137
139
  counted. `outputRetries(n)` ends the run at the n-th refused answer:
138
140
  n attempts, n − 1 corrections, so `outputRetries(1)` allows no
139
- second attempt.
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.
140
145
 
141
146
  `policy.tools` lists take tool **ids** (`tool.id`), not the names
142
147
  the model calls: a name in `deny` or `requireApproval` matches
143
148
  nothing and says nothing, and a name in `allow` leaves the tool off
144
149
  the list.
145
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'`.
160
+
146
161
  Multi-turn history is caller-owned: `input` accepts a `string`, a
147
162
  `Message[]` transcript, or any JSON value.
148
163
 
@@ -153,7 +168,7 @@ agent.run(input, {
153
168
  llm, deps,
154
169
  tools: [perRequestTool], // appended to the agent's static tools
155
170
  gates: [uiApprovalGate],
156
- onToolResult: [traceHook],
171
+ onToolResult: [traceHook], // run after the agent's own hooks
157
172
  onEvent: (e) => …,
158
173
  signal: abortController.signal,
159
174
  });
@@ -172,6 +187,9 @@ for await (const e of run.events) {
172
187
  const result = await run.result; // the no-streaming opt-out
173
188
  ```
174
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.
175
193
  - `tool-start` fires **before** execution — drives live "running…" UIs.
176
194
  - `tool-end` carries a typed `ToolObservation` union (result / error /
177
195
  denied / unknown-tool). No casting. Through Signal, `unknown-tool`
@@ -189,9 +207,16 @@ const result = await run.result; // the no-streaming opt-out
189
207
  Both stream before cortex knows how the step ends: words written
190
208
  beside a tool call (under `emit` and `native`) and a `respond` sent
191
209
  beside other calls arrive as `output-delta` too and are not the
192
- answer. The answer is what the last step streamed.
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.
193
214
  - `retry` resets partial-output state (same contract consumers had
194
- 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.
195
220
  - Nested runs (`asTool`) forward their events into the parent stream
196
221
  with an extended `agentPath` — one subscription sees the tree.
197
222
 
@@ -201,7 +226,9 @@ const result = await run.result; // the no-streaming opt-out
201
226
 
202
227
  All steering is plain typed functions; `policy` is sugar that
203
228
  compiles into one gate. Gates run **before** the call; a deny becomes
204
- 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.
205
232
 
206
233
  ```ts
207
234
  type GateDecision =
@@ -230,8 +257,12 @@ pending call and `approval-required` fires again, with a **new** id.
230
257
  Answer with that event's id, as above. `snapshot.pending.approvalId` is
231
258
  the ask of the run the snapshot was taken from; the resumed run did not
232
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.
233
263
  `policy.approvalTimeoutMs` turns an unanswered ask into a denial
234
- (an observation, not a run failure).
264
+ (an observation, not a run failure). The denial's `reason` is
265
+ `approval timeout`.
235
266
 
236
267
  ---
237
268
 
@@ -268,6 +299,12 @@ The child's envelope maps to the tool result (`data` if present, else
268
299
  `response`; override with `select`), and its events nest in the
269
300
  parent stream.
270
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
+
271
308
  ---
272
309
 
273
310
  ## preview
@@ -279,7 +316,7 @@ const p = await agent.preview(input, { deps, llm });
279
316
  p.strategy; // 'respond' | 'native' | 'emit' — what would actually run
280
317
  p.messages; // the assembled prefix, including injected schema docs
281
318
  p.tools; // real descriptors, including the respond tool's params
282
- p.estimatedTokens;
319
+ p.estimatedTokens; // rough: characters / 4, plus 4 per message and 256 per non-text part
283
320
  ```
284
321
 
285
322
  Anything you can't explain in the preview, the model can't either.
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
  });
@@ -209,8 +212,8 @@ var envelopeLooseWireSchema = (spec) => {
209
212
  return zod.z.object({
210
213
  reasoning: zod.z.string().nullish().describe(REASONING_DESCRIPTION),
211
214
  response,
212
- // A typed union, not z.unknown(): an empty {} schema gives the
213
- // model zero type signal and invites stringified payloads.
215
+ // Not z.unknown(): an empty {} schema tells the model no type, and it
216
+ // sends the payload as a string.
214
217
  data: zod.z.union([zod.z.record(zod.z.string(), zod.z.unknown()), zod.z.array(zod.z.unknown())]).describe(LOOSE_DATA_DESCRIPTION)
215
218
  });
216
219
  }
@@ -221,12 +224,13 @@ var envelopeLooseWireSchema = (spec) => {
221
224
  };
222
225
  var envelopeAcceptSchema = (_spec) => zod.z.union([zod.z.record(zod.z.string(), zod.z.unknown()), zod.z.array(zod.z.unknown())]);
223
226
  var KNOWN_KEYS = /* @__PURE__ */ new Set(["response", "data", "reasoning"]);
224
- var decodeData = signal.decodeJsonish;
225
- var tryUnwrap = (record, spec) => {
227
+ var takesAnyObject = (schema) => schema.safeParse({ "cortex:no-such-field": true }).success;
228
+ var asBarePayload = (record, spec) => {
226
229
  if (!spec.schema || spec.responseMode === "required") return void 0;
227
230
  const keys = Object.keys(record);
228
231
  const looksWrapped = keys.length > 0 && keys.every((key) => KNOWN_KEYS.has(key));
229
232
  if (looksWrapped) return void 0;
233
+ if (takesAnyObject(spec.schema)) return void 0;
230
234
  const parsed = spec.schema.safeParse(record);
231
235
  if (!parsed.success) return void 0;
232
236
  return { data: parsed.data };
@@ -241,8 +245,8 @@ var validateEnvelope = (raw, spec) => {
241
245
  if (!KNOWN_KEYS.has(key)) issues.push(`unknown key "${key}" \u2014 only response, data, reasoning are allowed`);
242
246
  }
243
247
  if (issues.length > 0) {
244
- const unwrapped = tryUnwrap(record, spec);
245
- if (unwrapped !== void 0) return { ok: true, envelope: unwrapped };
248
+ const bare = asBarePayload(record, spec);
249
+ if (bare !== void 0) return { ok: true, envelope: bare };
246
250
  }
247
251
  const response = record["response"] ?? void 0;
248
252
  if (spec.responseMode === "required" && typeof response !== "string") {
@@ -255,7 +259,7 @@ var validateEnvelope = (raw, spec) => {
255
259
  issues.push("reasoning: must be a string");
256
260
  }
257
261
  if (spec.schema) {
258
- const data = decodeData(record["data"]);
262
+ const data = signal.decodeJsonish(record["data"]);
259
263
  let parsed = spec.schema.safeParse(data);
260
264
  if (!parsed.success) {
261
265
  const repaired = spec.schema.safeParse(signal.deepDecodeJsonish(data));
@@ -365,13 +369,9 @@ var stringify = (value) => {
365
369
  }
366
370
  };
367
371
  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
372
  name: tool.config.name,
372
373
  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.
374
+ // Converted by the schema's own zod, not by cortex's: it may come from another copy of zod.
375
375
  parameters: tool.config.input["~standard"].jsonSchema.output({ target: "draft-07" })
376
376
  });
377
377
  var runLoop = async (cfg) => {
@@ -507,7 +507,7 @@ var runLoop = async (cfg) => {
507
507
  if (repaired.success) parsedArgs = repaired;
508
508
  }
509
509
  if (!parsedArgs.success) {
510
- 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("; ");
511
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)` : "";
512
512
  record(
513
513
  call,
@@ -583,7 +583,7 @@ var runLoop = async (cfg) => {
583
583
  return verdict;
584
584
  };
585
585
  const streamEmittedOutput = cfg.resolved.transport !== "respond";
586
- const streamOneStep = async (llm, request) => {
586
+ const oneStep = async (llm, request) => {
587
587
  if (cfg.transport === "step") {
588
588
  try {
589
589
  return ok(await llm.step(request));
@@ -689,7 +689,7 @@ var runLoop = async (cfg) => {
689
689
  ...cfg.resolved.outputToolName !== void 0 && { outputTool: cfg.resolved.outputToolName }
690
690
  }
691
691
  };
692
- const stepOutcome = await streamOneStep(llm, request);
692
+ const stepOutcome = await oneStep(llm, request);
693
693
  if (!stepOutcome.ok) return fail(stepOutcome.error);
694
694
  const result = stepOutcome.data;
695
695
  s.usage = addUsage(s.usage, result.usage);
@@ -1099,8 +1099,6 @@ var previewAgent = async (definition, input, options) => {
1099
1099
  ...inputMessages(input)
1100
1100
  ];
1101
1101
  const tools = [
1102
- // The run's own builder — the preview shows the model-visible NAME,
1103
- // not the id, or it would explain a request that never goes out.
1104
1102
  ...allTools.map(buildToolDescriptor),
1105
1103
  ...resolved.respondDescriptor ? [resolved.respondDescriptor] : []
1106
1104
  ];