@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 +20 -0
- package/DESIGN.md +5 -1
- package/README.md +45 -8
- package/dist/index.cjs +11 -16
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +11 -16
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
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> }`.
|
|
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
|
-
//
|
|
213
|
-
//
|
|
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
|
|
225
|
-
var
|
|
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
|
|
245
|
-
if (
|
|
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 =
|
|
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
|
-
//
|
|
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
|
|
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
|
|
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
|
];
|