@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 +32 -0
- package/DESIGN.md +5 -1
- package/README.md +45 -8
- package/dist/index.cjs +15 -17
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +2 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +15 -17
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
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> }`.
|
|
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
|
-
//
|
|
213
|
-
//
|
|
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
|
|
225
|
-
var
|
|
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
|
|
245
|
-
if (
|
|
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 =
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
];
|