@parcha/agentrun-dsl 0.1.0-beta.2 → 0.1.0-beta.20
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/README.md +46 -16
- package/dist/author.d.ts +96 -0
- package/dist/author.js +320 -0
- package/dist/authoring.js +1 -1
- package/dist/cli.js +8 -3
- package/dist/code-exec.d.ts +6 -0
- package/dist/code-exec.js +126 -0
- package/dist/decision-receipts.d.ts +98 -0
- package/dist/decision-receipts.js +51 -0
- package/dist/dry-run.d.ts +14 -1
- package/dist/dry-run.js +39 -13
- package/dist/graph.d.ts +83 -0
- package/dist/graph.js +231 -0
- package/dist/index.d.ts +12 -4
- package/dist/index.js +6 -2
- package/dist/inspection.js +2 -2
- package/dist/job.d.ts +14 -0
- package/dist/job.js +5 -0
- package/dist/long-timer.d.ts +7 -0
- package/dist/long-timer.js +22 -0
- package/dist/observer-snapshot.d.ts +3 -0
- package/dist/observer-snapshot.js +46 -0
- package/dist/predicates.d.ts +4 -0
- package/dist/predicates.js +19 -2
- package/dist/recovery/binding.d.ts +10 -0
- package/dist/recovery/binding.js +43 -0
- package/dist/recovery/call-key.d.ts +13 -0
- package/dist/recovery/call-key.js +24 -0
- package/dist/recovery/canonical-hash.d.ts +7 -0
- package/dist/recovery/canonical-hash.js +22 -0
- package/dist/recovery/driver.d.ts +208 -0
- package/dist/recovery/driver.js +1222 -0
- package/dist/recovery/effect-failure.d.ts +34 -0
- package/dist/recovery/effect-failure.js +62 -0
- package/dist/recovery/errors.d.ts +31 -0
- package/dist/recovery/errors.js +51 -0
- package/dist/recovery/execution-path.d.ts +53 -0
- package/dist/recovery/execution-path.js +167 -0
- package/dist/recovery/file-store.d.ts +7 -0
- package/dist/recovery/file-store.js +131 -0
- package/dist/recovery/frozen-snapshot.d.ts +244 -0
- package/dist/recovery/frozen-snapshot.js +171 -0
- package/dist/recovery/handoff-block.d.ts +36 -0
- package/dist/recovery/handoff-block.js +148 -0
- package/dist/recovery/handoff-digest.d.ts +58 -0
- package/dist/recovery/handoff-digest.js +195 -0
- package/dist/recovery/handoff-files.d.ts +54 -0
- package/dist/recovery/handoff-files.js +162 -0
- package/dist/recovery/handoff-receipts.d.ts +42 -0
- package/dist/recovery/handoff-receipts.js +53 -0
- package/dist/recovery/handoff-redact.d.ts +12 -0
- package/dist/recovery/handoff-redact.js +44 -0
- package/dist/recovery/handoff.d.ts +44 -0
- package/dist/recovery/handoff.js +46 -0
- package/dist/recovery/index.d.ts +18 -0
- package/dist/recovery/index.js +16 -0
- package/dist/recovery/item-state.d.ts +48 -0
- package/dist/recovery/item-state.js +89 -0
- package/dist/recovery/journal.d.ts +28 -0
- package/dist/recovery/journal.js +139 -0
- package/dist/recovery/memory-store.d.ts +4 -0
- package/dist/recovery/memory-store.js +20 -0
- package/dist/recovery/store.d.ts +105 -0
- package/dist/recovery/store.js +6 -0
- package/dist/recovery/testing/conformance.d.ts +4 -0
- package/dist/recovery/testing/conformance.js +268 -0
- package/dist/recovery/testing/crash-points.d.ts +18 -0
- package/dist/recovery/testing/crash-points.js +43 -0
- package/dist/recovery/testing/crash-sweep.d.ts +65 -0
- package/dist/recovery/testing/crash-sweep.js +146 -0
- package/dist/recovery/testing/index.d.ts +3 -0
- package/dist/recovery/testing/index.js +4 -0
- package/dist/recovery/testing/preload.d.ts +1 -0
- package/dist/recovery/testing/preload.js +3 -0
- package/dist/recovery/transport-facts.d.ts +23 -0
- package/dist/recovery/transport-facts.js +46 -0
- package/dist/recovery/with-recovery.d.ts +44 -0
- package/dist/recovery/with-recovery.js +87 -0
- package/dist/system-one.d.ts +17 -1
- package/dist/system-one.js +62 -5
- package/dist/vocabulary.d.ts +42 -0
- package/dist/vocabulary.js +74 -0
- package/dist/workflow-shape.d.ts +7 -0
- package/dist/workflow-shape.js +85 -62
- package/dist/workflow.d.ts +187 -16
- package/dist/workflow.js +967 -324
- package/package.json +18 -2
- package/schema/workflow.schema.json +251 -15
- package/skills/author/SKILL.md +122 -0
- package/skills/author/examples/evidence-gate.input.json +6 -0
- package/skills/author/examples/evidence-gate.json +125 -0
- package/skills/author/examples/read-file.input.json +1 -0
- package/skills/author/examples/read-file.json +44 -0
- package/skills/author/examples/read-source-decision.input.json +4 -0
- package/skills/author/examples/read-source-decision.json +37 -0
- package/skills/author/examples/release-note.txt +10 -0
- package/skills/author/examples/review-release-notes.input.json +6 -0
- package/skills/author/examples/review-release-notes.json +123 -0
- package/skills/author/references/jev-decisions.md +125 -0
- package/skills/author/references/language.md +118 -0
- package/skills/author/references/sdk-authoring.md +11 -0
- package/skills/author/references/workflow-format.md +137 -0
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { WorkflowDeps } from "../workflow.js";
|
|
2
|
+
import type { openRecovery, RecoveryEffectParams } from "./driver.js";
|
|
3
|
+
/** A recovery driver, as `openRecovery` returns it. */
|
|
4
|
+
export type RecoveryDriver = Awaited<ReturnType<typeof openRecovery>>;
|
|
5
|
+
/** The attempt of an LLM step a node runner is asked to run, as the driver admitted it. One attempt is one session:
|
|
6
|
+
* a runner that keeps what an attempt delivered keys it by `sessionId`. */
|
|
7
|
+
export type RecoveryStep = {
|
|
8
|
+
sessionId: string;
|
|
9
|
+
attempt: number;
|
|
10
|
+
earlierSessionIds: readonly string[];
|
|
11
|
+
};
|
|
12
|
+
/** What a host's node runner receives under the driver: the interpreter's parameters, and the attempt it runs. A
|
|
13
|
+
* runner marks a failure no second attempt should follow (one that ended on a bound of its own) with `final: true`
|
|
14
|
+
* on what it throws. */
|
|
15
|
+
export type RecoveryNodeParams = Parameters<NonNullable<WorkflowDeps["runNode"]>>[0] & {
|
|
16
|
+
step?: RecoveryStep;
|
|
17
|
+
};
|
|
18
|
+
/** The host's adapters as `withRecovery` takes them: the interpreter's, with the two that learn more under the driver. */
|
|
19
|
+
export type RecoveryAdapters = Omit<WorkflowDeps, "runEffect" | "runNode"> & {
|
|
20
|
+
runEffect?: (params: RecoveryEffectParams) => Promise<unknown>;
|
|
21
|
+
runNode?: (params: RecoveryNodeParams) => Promise<unknown>;
|
|
22
|
+
};
|
|
23
|
+
export type WithRecoveryOptions = {
|
|
24
|
+
/** The node runner keeps what each attempt delivered: asked again for a `sessionId` whose record it holds, it
|
|
25
|
+
* returns that record without running anything. A step found delivered is then asked of it again as the same
|
|
26
|
+
* attempt, and nothing is spent. Absent, such a step has spent its attempt.
|
|
27
|
+
* A record the interpreter refuses is therefore returned, and refused, again at every later open: the step neither
|
|
28
|
+
* advances nor spends, and the run fails the same way each time until the host ends it (an escalation, a new run). */
|
|
29
|
+
durableNodes?: boolean;
|
|
30
|
+
};
|
|
31
|
+
/** The dependencies to run a workflow with under `driver`. The interpreter's `recovery` hooks cover nodes; three
|
|
32
|
+
* things they have no slot for are applied to the host's adapters here:
|
|
33
|
+
* - `runEffect`: each effect is admitted before it is dispatched, a completed one is answered from its receipt, and
|
|
34
|
+
* one admitted and never completed is refused;
|
|
35
|
+
* - `runJudge`: a route's answer is committed as its decision before any branch step runs, and a resume inside the
|
|
36
|
+
* branch follows it without asking again; every answer's spend is committed with the driver's state;
|
|
37
|
+
* - `runNode`: an LLM step's record is committed before the step runs, with two attempts, each handed to the
|
|
38
|
+
* runner as its `step`. A failed attempt is followed at once by the second, unless the runner marked the
|
|
39
|
+
* failure final; a step that spent both is refused at every later open. A process that dies inside a step spends
|
|
40
|
+
* no attempt. A step that delivered a submission and whose node never committed (the interpreter refused it, or
|
|
41
|
+
* the process died first) is answered again from the runner's own record under `durableNodes`, and has spent its
|
|
42
|
+
* attempt otherwise.
|
|
43
|
+
* The run stops through the driver's signal, together with the host's own. */
|
|
44
|
+
export declare function withRecovery(driver: RecoveryDriver, deps: RecoveryAdapters, options?: WithRecoveryOptions): WorkflowDeps;
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import { validateAnswers } from "../system-one.js";
|
|
2
|
+
/** The dependencies to run a workflow with under `driver`. The interpreter's `recovery` hooks cover nodes; three
|
|
3
|
+
* things they have no slot for are applied to the host's adapters here:
|
|
4
|
+
* - `runEffect`: each effect is admitted before it is dispatched, a completed one is answered from its receipt, and
|
|
5
|
+
* one admitted and never completed is refused;
|
|
6
|
+
* - `runJudge`: a route's answer is committed as its decision before any branch step runs, and a resume inside the
|
|
7
|
+
* branch follows it without asking again; every answer's spend is committed with the driver's state;
|
|
8
|
+
* - `runNode`: an LLM step's record is committed before the step runs, with two attempts, each handed to the
|
|
9
|
+
* runner as its `step`. A failed attempt is followed at once by the second, unless the runner marked the
|
|
10
|
+
* failure final; a step that spent both is refused at every later open. A process that dies inside a step spends
|
|
11
|
+
* no attempt. A step that delivered a submission and whose node never committed (the interpreter refused it, or
|
|
12
|
+
* the process died first) is answered again from the runner's own record under `durableNodes`, and has spent its
|
|
13
|
+
* attempt otherwise.
|
|
14
|
+
* The run stops through the driver's signal, together with the host's own. */
|
|
15
|
+
export function withRecovery(driver, deps, options = {}) {
|
|
16
|
+
const { runEffect, runJudge, runNode } = deps;
|
|
17
|
+
return {
|
|
18
|
+
...deps,
|
|
19
|
+
recovery: driver.recovery,
|
|
20
|
+
signal: deps.signal ? AbortSignal.any([deps.signal, driver.signal]) : driver.signal,
|
|
21
|
+
runEffect: runEffect && driver.wrapEffect(runEffect),
|
|
22
|
+
runJudge: runJudge && (async (params) => {
|
|
23
|
+
const decided = params.kind === "route" ? driver.routeDecision(params.executionPath) : undefined;
|
|
24
|
+
if (decided)
|
|
25
|
+
return decided.result;
|
|
26
|
+
const result = await runJudge(params);
|
|
27
|
+
const cost = typeof result.cost_usd === "number" && Number.isFinite(result.cost_usd) ? result.cost_usd : null;
|
|
28
|
+
// An answer the interpreter would refuse is spent at its price and is never a decision: the question is
|
|
29
|
+
// asked again by the next process.
|
|
30
|
+
try {
|
|
31
|
+
validateAnswers(params.questions, result.answers);
|
|
32
|
+
}
|
|
33
|
+
catch (error) {
|
|
34
|
+
driver.recordQuestionSpend(cost);
|
|
35
|
+
throw error;
|
|
36
|
+
}
|
|
37
|
+
driver.recordQuestionSpend(cost, params.kind === "route" ? { executionPath: params.executionPath, label: params.label, result: result, receipts: null } : undefined);
|
|
38
|
+
// The decision is durable before the interpreter acts on the answer, and a stop taken meanwhile ends the run here.
|
|
39
|
+
await driver.flush();
|
|
40
|
+
driver.checkStop();
|
|
41
|
+
return result;
|
|
42
|
+
}),
|
|
43
|
+
runNode: runNode && (async (params) => {
|
|
44
|
+
const admit = () => driver.stepSession(params.executionPath, params.label, { attemptsAllowed: 2 });
|
|
45
|
+
let admission = admit();
|
|
46
|
+
for (;;) {
|
|
47
|
+
// An attempt that delivered a submission is asked for again only when its node never committed. A runner that
|
|
48
|
+
// keeps what it delivered answers it again below, as the same attempt; with any other runner it is spent.
|
|
49
|
+
if (admission.status === "submitted" && !options.durableNodes) {
|
|
50
|
+
driver.stepAttemptFailed(params.executionPath);
|
|
51
|
+
admission = admit();
|
|
52
|
+
}
|
|
53
|
+
// A step that failed on an item failure is refused with it, so the item it lies in ends on the same failure.
|
|
54
|
+
if (admission.status === "failed") {
|
|
55
|
+
throw admission.failure ? Object.assign(new Error(admission.failure.message), { code: admission.failure.code, itemFailure: true })
|
|
56
|
+
: new Error(`${params.label} failed after ${admission.attemptsAllowed} attempts`);
|
|
57
|
+
}
|
|
58
|
+
// The step's record is durable before the attempt runs. A stop or a caller's cancellation that landed
|
|
59
|
+
// meanwhile ends the step here: the runner is not called, and no attempt is spent. A pause waiting for an
|
|
60
|
+
// effect in flight holds the step here until it is taken.
|
|
61
|
+
await driver.flush();
|
|
62
|
+
await driver.seam();
|
|
63
|
+
if (params.signal?.aborted)
|
|
64
|
+
throw params.signal.reason;
|
|
65
|
+
try {
|
|
66
|
+
const submission = await runNode({ ...params, step: { sessionId: admission.sessionId, attempt: admission.attempt, earlierSessionIds: admission.earlierSessionIds } });
|
|
67
|
+
driver.stepSubmitted(params.executionPath);
|
|
68
|
+
return submission;
|
|
69
|
+
}
|
|
70
|
+
catch (error) {
|
|
71
|
+
// A stop the driver took, or a sibling's failure, ends the step where it is: no attempt is spent.
|
|
72
|
+
if (driver.signal.aborted || params.signal?.aborted)
|
|
73
|
+
throw error;
|
|
74
|
+
// A failure the runner marked final (an attempt that ended on a bound of its own) gets no second attempt: it
|
|
75
|
+
// would spend the same again.
|
|
76
|
+
const final = error?.final === true;
|
|
77
|
+
driver.stepAttemptFailed(params.executionPath, final, error);
|
|
78
|
+
if (final)
|
|
79
|
+
throw error;
|
|
80
|
+
admission = admit();
|
|
81
|
+
if (admission.status !== "running")
|
|
82
|
+
throw error;
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}),
|
|
86
|
+
};
|
|
87
|
+
}
|
package/dist/system-one.d.ts
CHANGED
|
@@ -13,6 +13,18 @@ export type SystemOneQuestion = {
|
|
|
13
13
|
type: "score";
|
|
14
14
|
instructions: string;
|
|
15
15
|
criteria: string[];
|
|
16
|
+
}
|
|
17
|
+
/** Locates what its instructions describe in the request's image. A host-side question: no workflow node declares one, and it needs an image sent with the request. */
|
|
18
|
+
| {
|
|
19
|
+
type: "box";
|
|
20
|
+
instructions: string;
|
|
21
|
+
};
|
|
22
|
+
/** A box's edges as fractions of the image's height (`top`, `bottom`) and width (`left`, `right`), from the top left corner. */
|
|
23
|
+
export type SystemOneBox = {
|
|
24
|
+
top: number;
|
|
25
|
+
bottom: number;
|
|
26
|
+
left: number;
|
|
27
|
+
right: number;
|
|
16
28
|
};
|
|
17
29
|
export type SystemOneAnswer = {
|
|
18
30
|
type: "choice";
|
|
@@ -28,6 +40,10 @@ export type SystemOneAnswer = {
|
|
|
28
40
|
legend: Record<string, string>;
|
|
29
41
|
probabilities: Record<string, number>;
|
|
30
42
|
confidence: number;
|
|
43
|
+
} | {
|
|
44
|
+
type: "box";
|
|
45
|
+
box: SystemOneBox;
|
|
46
|
+
confidence: number | null;
|
|
31
47
|
};
|
|
32
48
|
export type SystemOneResult = {
|
|
33
49
|
answers: Record<string, SystemOneAnswer>;
|
|
@@ -65,7 +81,7 @@ export type AnswersSidecar = {
|
|
|
65
81
|
export declare function answersSidecar(answers: Record<string, SystemOneAnswer>): AnswersSidecar;
|
|
66
82
|
export declare function synthesizeAnswers(questions: Record<string, SystemOneQuestion>): Record<string, SystemOneAnswer>;
|
|
67
83
|
export type SystemOneRetryClass = "http_429" | "http_5xx" | "connection" | "timeout";
|
|
68
|
-
declare const responseReasons: readonly ["answers_shape", "answer_keys", "answer_shape", "answer_type", "noul_probability", "confidence", "probabilities", "probability_keys", "probability_mass", "score_legend", "score_consistency", "choice_option", "score_range"];
|
|
84
|
+
declare const responseReasons: readonly ["answers_shape", "answer_keys", "answer_shape", "answer_type", "noul_probability", "confidence", "box_coordinates", "probabilities", "probability_keys", "probability_mass", "score_legend", "score_consistency", "choice_option", "score_range"];
|
|
69
85
|
export type SystemOneResponseReason = typeof responseReasons[number];
|
|
70
86
|
export declare function isSystemOneResponseReason(value: unknown): value is SystemOneResponseReason;
|
|
71
87
|
export declare class SystemOneError extends Error {
|
package/dist/system-one.js
CHANGED
|
@@ -94,6 +94,8 @@ export function answersToValue(answers, questions) {
|
|
|
94
94
|
out[id] = a.noul >= 0.5;
|
|
95
95
|
else if (q.type === "score" && a.type === "score")
|
|
96
96
|
out[id] = Math.max(0, Math.round(a.score));
|
|
97
|
+
else if (q.type === "box" && a.type === "box")
|
|
98
|
+
out[id] = { ...a.box };
|
|
97
99
|
else
|
|
98
100
|
throw new Error(`System One answered question "${id}" with type "${a.type}", expected ${q.type}`);
|
|
99
101
|
}
|
|
@@ -104,6 +106,7 @@ export function answerConfidence(answer) {
|
|
|
104
106
|
throw new SystemOneError("System One answer missing for a question that was asked", null);
|
|
105
107
|
if (answer.type === "noul")
|
|
106
108
|
return Math.abs(answer.noul - 0.5) * 2;
|
|
109
|
+
// A box the provider reported no confidence for counts as none: unknown is never read as sure.
|
|
107
110
|
return typeof answer.confidence === "number" ? answer.confidence : 0;
|
|
108
111
|
}
|
|
109
112
|
export function answersSidecar(answers) {
|
|
@@ -124,6 +127,8 @@ export function synthesizeAnswers(questions) {
|
|
|
124
127
|
const options = Object.keys(q.criteria);
|
|
125
128
|
out[id] = { type: "choice", choice: options[0], probabilities: Object.fromEntries(options.map((o) => [o, 1 / options.length])), confidence: 0 };
|
|
126
129
|
}
|
|
130
|
+
else if (q.type === "box")
|
|
131
|
+
out[id] = { type: "box", box: { top: 0, bottom: 1, left: 0, right: 1 }, confidence: 0 };
|
|
127
132
|
else if (q.type === "noul")
|
|
128
133
|
out[id] = { type: "noul", noul: 0.5 };
|
|
129
134
|
else
|
|
@@ -132,7 +137,7 @@ export function synthesizeAnswers(questions) {
|
|
|
132
137
|
return { ...out };
|
|
133
138
|
}
|
|
134
139
|
const responseReasons = ["answers_shape", "answer_keys", "answer_shape", "answer_type", "noul_probability",
|
|
135
|
-
"confidence", "probabilities", "probability_keys", "probability_mass", "score_legend", "score_consistency", "choice_option", "score_range"];
|
|
140
|
+
"confidence", "box_coordinates", "probabilities", "probability_keys", "probability_mass", "score_legend", "score_consistency", "choice_option", "score_range"];
|
|
136
141
|
export function isSystemOneResponseReason(value) {
|
|
137
142
|
return typeof value === "string" && responseReasons.includes(value);
|
|
138
143
|
}
|
|
@@ -150,6 +155,49 @@ export class SystemOneError extends Error {
|
|
|
150
155
|
}
|
|
151
156
|
}
|
|
152
157
|
const unit = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 1;
|
|
158
|
+
// System One reports probabilities rounded to two places, so the reported sum drifts from 1 by up to
|
|
159
|
+
// half a step per option (3 × 0.33 = 0.99; 8 × 0.13 = 1.04). A distribution is accepted when it could
|
|
160
|
+
// be that rounding of one summing to 1: a value on the two-place grid may be off by ±0.005 (within
|
|
161
|
+
// [0, 1]); any other value is taken as exact. With no grid values this is |sum − 1| ≤ 1e-5, the
|
|
162
|
+
// check for full-precision distributions. Answers are accepted as reported, never rescaled.
|
|
163
|
+
const ROUNDING_HALF_STEP = 0.005;
|
|
164
|
+
const onTwoPlaceGrid = (p) => Math.abs(p * 100 - Math.round(p * 100)) < 1e-9;
|
|
165
|
+
function roundedFromUnitMass(probabilities) {
|
|
166
|
+
let low = 0, high = 0;
|
|
167
|
+
for (const p of probabilities) {
|
|
168
|
+
const step = onTwoPlaceGrid(p) ? ROUNDING_HALF_STEP : 0;
|
|
169
|
+
low += Math.max(0, p - step);
|
|
170
|
+
high += Math.min(1, p + step);
|
|
171
|
+
}
|
|
172
|
+
return low <= 1 + 1e-5 && high >= 1 - 1e-5;
|
|
173
|
+
}
|
|
174
|
+
// A Score's weighted level drifts the same way. The unrounded probabilities lie within their rounding
|
|
175
|
+
// intervals and sum to 1, so Σ level·p lies between two bounds: start every level at its interval's
|
|
176
|
+
// low end, then give the rest of the unit mass to the lowest levels (the minimum) or the highest (the
|
|
177
|
+
// maximum), each up to its interval's high end. A score on the grid is itself off by up to 0.005. The
|
|
178
|
+
// score is accepted when its interval meets [min, max]; with no grid values this is
|
|
179
|
+
// |score − Σ level·p| ≤ 1e-5. A score that is not a number contradicts nothing here and is left to
|
|
180
|
+
// the range check, as before.
|
|
181
|
+
function scoreContradictsDistribution(score, probabilities) {
|
|
182
|
+
const levels = Object.entries(probabilities).map(([level, p]) => {
|
|
183
|
+
const step = onTwoPlaceGrid(p) ? ROUNDING_HALF_STEP : 0;
|
|
184
|
+
return { level: Number(level), low: Math.max(0, p - step), high: Math.min(1, p + step) };
|
|
185
|
+
}).sort((a, b) => a.level - b.level);
|
|
186
|
+
const floor = levels.reduce((sum, l) => sum + l.level * l.low, 0);
|
|
187
|
+
const spare = Math.max(0, 1 - levels.reduce((sum, l) => sum + l.low, 0));
|
|
188
|
+
const fill = (order) => {
|
|
189
|
+
let rest = spare, weighted = floor;
|
|
190
|
+
for (const l of order) {
|
|
191
|
+
const add = Math.min(rest, l.high - l.low);
|
|
192
|
+
weighted += l.level * add;
|
|
193
|
+
rest -= add;
|
|
194
|
+
}
|
|
195
|
+
return weighted;
|
|
196
|
+
};
|
|
197
|
+
const min = fill(levels), max = fill([...levels].reverse());
|
|
198
|
+
const step = onTwoPlaceGrid(score) ? ROUNDING_HALF_STEP : 0;
|
|
199
|
+
return score - step > max + 1e-5 || score + step < min - 1e-5;
|
|
200
|
+
}
|
|
153
201
|
export function validateAnswers(questions, answers) {
|
|
154
202
|
if (!answers || typeof answers !== "object" || Array.isArray(answers))
|
|
155
203
|
throw new SystemOneError("System One response carries no answers", null, undefined, "answers_shape");
|
|
@@ -162,6 +210,17 @@ export function validateAnswers(questions, answers) {
|
|
|
162
210
|
throw new SystemOneError("System One returned no answer for a question", null, undefined, "answer_shape");
|
|
163
211
|
if (a.type !== q.type)
|
|
164
212
|
throw new SystemOneError("System One answer type does not match its question", null, undefined, "answer_type");
|
|
213
|
+
if (q.type === "box") {
|
|
214
|
+
const box = a.box;
|
|
215
|
+
if (!box || typeof box !== "object" || Array.isArray(box) || Object.keys(box).length !== 4 || !["top", "bottom", "left", "right"].every(edge => unit(box[edge])))
|
|
216
|
+
throw new SystemOneError("System One answer: a box's edges are not fractions in [0, 1]", null, undefined, "box_coordinates");
|
|
217
|
+
// An edge pair that runs backwards is a box with negative width or height: not a box.
|
|
218
|
+
if (box.top > box.bottom || box.left > box.right)
|
|
219
|
+
throw new SystemOneError("System One answer: a box's top and left edges cannot lie past its bottom and right", null, undefined, "box_coordinates");
|
|
220
|
+
if (!(a.confidence === null || unit(a.confidence)))
|
|
221
|
+
throw new SystemOneError("System One answer: confidence is not in [0, 1]", null, undefined, "confidence");
|
|
222
|
+
continue;
|
|
223
|
+
}
|
|
165
224
|
if (q.type === "noul") {
|
|
166
225
|
if (!unit(a.noul))
|
|
167
226
|
throw new SystemOneError("System One answer: noul is not a probability", null, undefined, "noul_probability");
|
|
@@ -175,14 +234,12 @@ export function validateAnswers(questions, answers) {
|
|
|
175
234
|
const probabilityKeys = Object.keys(a.probabilities);
|
|
176
235
|
if (Array.isArray(a.probabilities) || probabilityKeys.length !== expectedKeys.length || expectedKeys.some(key => !Object.hasOwn(a.probabilities, key)))
|
|
177
236
|
throw new SystemOneError("System One answer: probabilities must contain exactly the declared options", null, undefined, "probability_keys");
|
|
178
|
-
|
|
179
|
-
if (Math.abs(mass - 1) > 1e-5)
|
|
237
|
+
if (!roundedFromUnitMass(Object.values(a.probabilities)))
|
|
180
238
|
throw new SystemOneError("System One answer: probabilities must sum to 1", null, undefined, "probability_mass");
|
|
181
239
|
if (q.type === "score") {
|
|
182
240
|
if (!a.legend || typeof a.legend !== "object" || Array.isArray(a.legend) || Object.keys(a.legend).length !== expectedKeys.length || q.criteria.some((text, index) => a.legend[String(index)] !== text))
|
|
183
241
|
throw new SystemOneError("System One answer: legend must match the score criteria", null, undefined, "score_legend");
|
|
184
|
-
|
|
185
|
-
if (Math.abs(weighted - a.score) > 1e-5)
|
|
242
|
+
if (scoreContradictsDistribution(a.score, a.probabilities))
|
|
186
243
|
throw new SystemOneError("System One answer: score must match its weighted distribution", null, undefined, "score_consistency");
|
|
187
244
|
}
|
|
188
245
|
if (q.type === "choice" && !(typeof a.choice === "string" && Object.prototype.hasOwnProperty.call(q.criteria, a.choice)))
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
export declare const WORKFLOW_NODE_KINDS: readonly ["chain", "code", "agent", "decide", "extract", "report", "artifact", "map", "parallel", "loop", "escalate", "call", "workflow", "judge", "pick", "sift", "route"];
|
|
2
|
+
export type WorkflowNodeKind = typeof WORKFLOW_NODE_KINDS[number];
|
|
3
|
+
/** Generative kinds: one adapter session each, answering against a schema. */
|
|
4
|
+
export declare const GENERATIVE_NODE_KINDS: readonly ["agent", "decide", "extract", "report"];
|
|
5
|
+
/** Typed-question kinds: one judge request each, no tools and no session. */
|
|
6
|
+
export declare const JUDGMENT_NODE_KINDS: readonly ["judge", "pick", "sift", "route"];
|
|
7
|
+
/** The fields each node kind accepts. Any other key is an authoring error. */
|
|
8
|
+
export declare const NODE_FIELDS: {
|
|
9
|
+
readonly [Kind in WorkflowNodeKind]: readonly string[];
|
|
10
|
+
};
|
|
11
|
+
/** Fields every node kind accepts in addition to its own. `metadata` is the host's: an optional object of
|
|
12
|
+
* host markers the engine admits, carries and hashes with the document, and never reads. */
|
|
13
|
+
export declare const HOST_NODE_FIELDS: readonly ["metadata"];
|
|
14
|
+
/** Accepted and ignored for older v2 documents; never taught. The engine invokes the adapter once per node. */
|
|
15
|
+
export declare const IGNORED_NODE_FIELDS: {
|
|
16
|
+
readonly [Kind in WorkflowNodeKind]?: readonly string[];
|
|
17
|
+
};
|
|
18
|
+
/** Predicates that read a state value. `poll` accepts only these. */
|
|
19
|
+
export declare const MECHANICAL_PREDICATES: readonly ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items"];
|
|
20
|
+
/** Every predicate `loop.until` and `escalate.when` accept: the mechanical set plus `ask`, a yes/no judge question. */
|
|
21
|
+
export declare const WORKFLOW_PREDICATES: readonly ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items", "ask"];
|
|
22
|
+
export type WorkflowPredicateName = typeof WORKFLOW_PREDICATES[number];
|
|
23
|
+
/** The fields each predicate takes. */
|
|
24
|
+
export declare const PREDICATE_FIELDS: {
|
|
25
|
+
readonly [Name in WorkflowPredicateName]: readonly string[];
|
|
26
|
+
};
|
|
27
|
+
export declare const EFFORT_LEVELS: readonly ["minimal", "low", "medium", "high"];
|
|
28
|
+
/** There is no "off": every generative node thinks. */
|
|
29
|
+
export declare const THINKING_LEVELS: readonly ["low", "medium", "high"];
|
|
30
|
+
export declare const MODEL_TIERS: readonly ["fast", "default", "strong"];
|
|
31
|
+
/** An `agent` node's context: `fresh` sees its instructions and state only; `fork` asks the host to start
|
|
32
|
+
* the node from the caller's transcript, where the host can (a host refuses it where it cannot). */
|
|
33
|
+
export declare const AGENT_CONTEXTS: readonly ["fresh", "fork"];
|
|
34
|
+
export declare const CALL_TRANSPORTS: readonly ["tool", "executor", "shell"];
|
|
35
|
+
export declare const CALL_RETRY_CLASSES: readonly ["timeout", "http_5xx", "http_429", "connection", "exit"];
|
|
36
|
+
/** The closed codes a failed effect carries: a call's, or a code node's that a host runs out of process.
|
|
37
|
+
* `retry.on` names these or the retry classes above. A retry class implies its code (timeout is
|
|
38
|
+
* effect_timeout, exit is effect_exit, the transient transport classes are effect_transport); a host
|
|
39
|
+
* that types a failure itself names the code. */
|
|
40
|
+
export declare const EFFECT_FAILURE_CODES: readonly ["effect_timeout", "effect_exit", "effect_transport", "effect_not_granted", "effect_produces_missing", "effect_path_escape", "effect_code_unsafe", "output_invalid", "state_invalid", "effect_unknown_transport"];
|
|
41
|
+
/** Artifact types the engine itself treats as prose (the report writer). Every other type names a file. */
|
|
42
|
+
export declare const PROSE_ARTIFACT_TYPES: readonly ["markdown", "report"];
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
// The language's closed vocabulary. The validator admits exactly these kinds, fields and predicates,
|
|
2
|
+
// and the author contract names them from the same constants, so the two cannot drift.
|
|
3
|
+
export const WORKFLOW_NODE_KINDS = [
|
|
4
|
+
"chain", "code", "agent", "decide", "extract", "report", "artifact", "map", "parallel", "loop",
|
|
5
|
+
"escalate", "call", "workflow", "judge", "pick", "sift", "route",
|
|
6
|
+
];
|
|
7
|
+
/** Generative kinds: one adapter session each, answering against a schema. */
|
|
8
|
+
export const GENERATIVE_NODE_KINDS = ["agent", "decide", "extract", "report"];
|
|
9
|
+
/** Typed-question kinds: one judge request each, no tools and no session. */
|
|
10
|
+
export const JUDGMENT_NODE_KINDS = ["judge", "pick", "sift", "route"];
|
|
11
|
+
const GENERATIVE_FIELDS = ["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "verify", "tier"];
|
|
12
|
+
/** The fields each node kind accepts. Any other key is an authoring error. */
|
|
13
|
+
export const NODE_FIELDS = {
|
|
14
|
+
chain: ["node", "steps"],
|
|
15
|
+
code: ["node", "label", "code", "as"],
|
|
16
|
+
agent: [...GENERATIVE_FIELDS, "budget_usd", "context"],
|
|
17
|
+
decide: GENERATIVE_FIELDS,
|
|
18
|
+
extract: GENERATIVE_FIELDS,
|
|
19
|
+
report: ["node", "label", "state", "instructions", "sopSection", "requires", "tools", "effort", "thinking"],
|
|
20
|
+
artifact: ["node", "label", "state", "type", "path", "instructions", "sopSection", "requires", "tools", "effort", "thinking"],
|
|
21
|
+
map: ["node", "label", "itemsPath", "body", "as", "resultPath", "maxConcurrency", "onItemFailure", "failedAs"],
|
|
22
|
+
parallel: ["node", "label", "branches"],
|
|
23
|
+
loop: ["node", "label", "body", "until", "maxIters", "expect_iters"],
|
|
24
|
+
escalate: ["node", "label", "when", "kind", "stage", "summary"],
|
|
25
|
+
call: ["node", "label", "via", "tool", "args", "code", "input", "command", "env", "where", "out", "as", "produces", "deadline_s", "retry", "poll", "requires"],
|
|
26
|
+
workflow: ["node", "label", "workflow", "input", "out", "as"],
|
|
27
|
+
judge: ["node", "label", "state", "out", "as", "requires"],
|
|
28
|
+
pick: ["node", "label", "itemsPath", "describe", "instructions", "state", "allowNone", "as", "requires"],
|
|
29
|
+
sift: ["node", "label", "itemsPath", "describe", "state", "out", "as", "keep", "requires"],
|
|
30
|
+
route: ["node", "label", "state", "instructions", "branches", "unsure", "valuePath", "otherwise", "as", "requires"],
|
|
31
|
+
};
|
|
32
|
+
/** Fields every node kind accepts in addition to its own. `metadata` is the host's: an optional object of
|
|
33
|
+
* host markers the engine admits, carries and hashes with the document, and never reads. */
|
|
34
|
+
export const HOST_NODE_FIELDS = ["metadata"];
|
|
35
|
+
/** Accepted and ignored for older v2 documents; never taught. The engine invokes the adapter once per node. */
|
|
36
|
+
export const IGNORED_NODE_FIELDS = {
|
|
37
|
+
agent: ["budget"],
|
|
38
|
+
decide: ["samples", "voteField"],
|
|
39
|
+
};
|
|
40
|
+
/** Predicates that read a state value. `poll` accepts only these. */
|
|
41
|
+
export const MECHANICAL_PREDICATES = ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items"];
|
|
42
|
+
/** Every predicate `loop.until` and `escalate.when` accept: the mechanical set plus `ask`, a yes/no judge question. */
|
|
43
|
+
export const WORKFLOW_PREDICATES = [...MECHANICAL_PREDICATES, "ask"];
|
|
44
|
+
/** The fields each predicate takes. */
|
|
45
|
+
export const PREDICATE_FIELDS = {
|
|
46
|
+
field_equals: ["path", "value"],
|
|
47
|
+
field_true: ["path"],
|
|
48
|
+
in: ["path", "values"],
|
|
49
|
+
count_gte: ["path", "n"],
|
|
50
|
+
gte: ["path", "n"],
|
|
51
|
+
lt: ["path", "n"],
|
|
52
|
+
empty: ["path"],
|
|
53
|
+
no_new_items: ["key"],
|
|
54
|
+
ask: ["instructions", "state", "criteria", "gte"],
|
|
55
|
+
};
|
|
56
|
+
export const EFFORT_LEVELS = ["minimal", "low", "medium", "high"];
|
|
57
|
+
/** There is no "off": every generative node thinks. */
|
|
58
|
+
export const THINKING_LEVELS = ["low", "medium", "high"];
|
|
59
|
+
export const MODEL_TIERS = ["fast", "default", "strong"];
|
|
60
|
+
/** An `agent` node's context: `fresh` sees its instructions and state only; `fork` asks the host to start
|
|
61
|
+
* the node from the caller's transcript, where the host can (a host refuses it where it cannot). */
|
|
62
|
+
export const AGENT_CONTEXTS = ["fresh", "fork"];
|
|
63
|
+
export const CALL_TRANSPORTS = ["tool", "executor", "shell"];
|
|
64
|
+
export const CALL_RETRY_CLASSES = ["timeout", "http_5xx", "http_429", "connection", "exit"];
|
|
65
|
+
/** The closed codes a failed effect carries: a call's, or a code node's that a host runs out of process.
|
|
66
|
+
* `retry.on` names these or the retry classes above. A retry class implies its code (timeout is
|
|
67
|
+
* effect_timeout, exit is effect_exit, the transient transport classes are effect_transport); a host
|
|
68
|
+
* that types a failure itself names the code. */
|
|
69
|
+
export const EFFECT_FAILURE_CODES = [
|
|
70
|
+
"effect_timeout", "effect_exit", "effect_transport", "effect_not_granted", "effect_produces_missing",
|
|
71
|
+
"effect_path_escape", "effect_code_unsafe", "output_invalid", "state_invalid", "effect_unknown_transport",
|
|
72
|
+
];
|
|
73
|
+
/** Artifact types the engine itself treats as prose (the report writer). Every other type names a file. */
|
|
74
|
+
export const PROSE_ARTIFACT_TYPES = ["markdown", "report"];
|
package/dist/workflow-shape.d.ts
CHANGED
|
@@ -1 +1,8 @@
|
|
|
1
|
+
/** A shape problem: its message, and a JSON Pointer to the value it is about (to the nearest value the document has, when
|
|
2
|
+
* the one the rule names is missing). */
|
|
3
|
+
export type ShapeIssue = {
|
|
4
|
+
path: string;
|
|
5
|
+
message: string;
|
|
6
|
+
};
|
|
1
7
|
export declare function workflowShapeErrors(value: unknown, complete?: boolean): string[];
|
|
8
|
+
export declare function workflowShapeIssues(value: unknown, complete?: boolean): ShapeIssue[];
|