@niscorp/cortex 0.1.3 → 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,25 @@
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
+
3
23
  ## 0.1.3
4
24
 
5
25
  ### 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
@@ -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);
@@ -1099,8 +1096,6 @@ var previewAgent = async (definition, input, options) => {
1099
1096
  ...inputMessages(input)
1100
1097
  ];
1101
1098
  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
1099
  ...allTools.map(buildToolDescriptor),
1105
1100
  ...resolved.respondDescriptor ? [resolved.respondDescriptor] : []
1106
1101
  ];