@parcha/agentrun-dsl 0.1.0-beta.1 → 0.1.0-beta.3
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 +11 -2
- package/dist/author.d.ts +86 -0
- package/dist/author.js +304 -0
- package/dist/index.d.ts +7 -2
- package/dist/index.js +8 -1
- package/dist/predicates.d.ts +4 -0
- package/dist/predicates.js +19 -2
- package/dist/vocabulary.d.ts +31 -0
- package/dist/vocabulary.js +60 -0
- package/dist/workflow.d.ts +54 -2
- package/dist/workflow.js +274 -48
- package/package.json +3 -2
- package/skills/author/SKILL.md +120 -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 +113 -0
- package/skills/author/references/language.md +113 -0
- package/skills/author/references/sdk-authoring.md +9 -0
- package/skills/author/references/workflow-format.md +137 -0
package/dist/workflow.d.ts
CHANGED
|
@@ -307,6 +307,8 @@ export type WorkflowRunResult = {
|
|
|
307
307
|
status: "complete";
|
|
308
308
|
state: Record<string, unknown>;
|
|
309
309
|
output: unknown;
|
|
310
|
+
/** What the host's policy wrote through `decodeSubmission`: the final `state.$host`, never part of `output`. */
|
|
311
|
+
host?: Record<string, unknown>;
|
|
310
312
|
} | {
|
|
311
313
|
status: "escalated";
|
|
312
314
|
state: Record<string, unknown>;
|
|
@@ -316,8 +318,56 @@ export type MapItem = {
|
|
|
316
318
|
label: string;
|
|
317
319
|
index: number;
|
|
318
320
|
};
|
|
321
|
+
/** Where a host policy hook is being applied. `terminal` is true for a generative node whose `out` is
|
|
322
|
+
* the workflow's output schema: the node that emits the terminal record. */
|
|
323
|
+
export type HostPolicyContext = {
|
|
324
|
+
workflow: {
|
|
325
|
+
name: string;
|
|
326
|
+
outputSchemaId: string;
|
|
327
|
+
};
|
|
328
|
+
node: {
|
|
329
|
+
kind: WorkflowNode["node"];
|
|
330
|
+
label: string;
|
|
331
|
+
out?: string;
|
|
332
|
+
as?: string;
|
|
333
|
+
};
|
|
334
|
+
terminal: boolean;
|
|
335
|
+
executionPath: string;
|
|
336
|
+
item?: MapItem;
|
|
337
|
+
};
|
|
338
|
+
/** Application policy around generative nodes and completed steps. This is host code handed in through
|
|
339
|
+
* deps: nothing in a workflow document can name or reach it, so a candidate workflow cannot change its
|
|
340
|
+
* host's channels. Each hook is a general capability rather than a product rule:
|
|
341
|
+
* - `systemBlocks` appends host text after the node's instructions.
|
|
342
|
+
* - `submissionSchema` widens the schema the adapter submits against with host-owned channels. The
|
|
343
|
+
* returned schema must accept every value the stage schema accepts; the engine validates the raw
|
|
344
|
+
* submission against it and the decoded domain value against the unchanged stage schema, so no host
|
|
345
|
+
* channel can bypass domain validation or verification.
|
|
346
|
+
* - `decodeSubmission` splits an accepted transport submission into the domain value and host state.
|
|
347
|
+
* Host state lives under the reserved `$host` state key (no workflow may write it), so it is
|
|
348
|
+
* checkpointed and resumed with the rest of the state, isolated per map item, branch and child
|
|
349
|
+
* exactly as the state is, excluded from a path-less output projection, and returned as `result.host`.
|
|
350
|
+
* Parallel branches merge their `$host` deltas key by key: arrays append, an unchanged value is kept,
|
|
351
|
+
* two branches changing one non-array key to different values is a write conflict.
|
|
352
|
+
* - `afterNode` enriches a completed step's state before commit and checkpoint. This is domain state:
|
|
353
|
+
* downstream nodes and output validation see it. */
|
|
354
|
+
export type HostPolicy = {
|
|
355
|
+
systemBlocks?: (context: HostPolicyContext) => string[];
|
|
356
|
+
submissionSchema?: (stageSchema: Record<string, unknown>, context: HostPolicyContext) => Record<string, unknown>;
|
|
357
|
+
decodeSubmission?: (submission: unknown, context: HostPolicyContext & {
|
|
358
|
+
host: Record<string, unknown>;
|
|
359
|
+
}) => {
|
|
360
|
+
value: unknown;
|
|
361
|
+
host?: Record<string, unknown>;
|
|
362
|
+
};
|
|
363
|
+
afterNode?: (context: HostPolicyContext & {
|
|
364
|
+
state: Record<string, unknown>;
|
|
365
|
+
}) => Record<string, unknown> | undefined;
|
|
366
|
+
};
|
|
319
367
|
export type WorkflowDeps = {
|
|
320
368
|
maxQuestionsPerRequest?: number;
|
|
369
|
+
/** Host application policy; see `HostPolicy`. Absent = the engine's own behavior, unchanged. */
|
|
370
|
+
hostPolicy?: HostPolicy;
|
|
321
371
|
runNode?: (params: {
|
|
322
372
|
kind: "agent" | "decide" | "extract" | "report";
|
|
323
373
|
label: string;
|
|
@@ -507,13 +557,15 @@ export declare class WorkflowCodeError extends Error {
|
|
|
507
557
|
export declare class WorkflowStateError extends Error {
|
|
508
558
|
readonly stage: string;
|
|
509
559
|
readonly path: string;
|
|
510
|
-
readonly reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict";
|
|
560
|
+
readonly reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key";
|
|
511
561
|
readonly code = "state_invalid";
|
|
512
|
-
constructor(summary: string, stage: string, path: string, reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict");
|
|
562
|
+
constructor(summary: string, stage: string, path: string, reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key");
|
|
513
563
|
}
|
|
514
564
|
export declare function stageSchemaForNode(workflow: Workflow, node: LlmNode): Record<string, unknown>;
|
|
515
565
|
export declare const submissionSchemaForNode: typeof stageSchemaForNode;
|
|
516
566
|
export declare function mergeStageDelta(state: Record<string, unknown>, node: LlmNode, result: Record<string, unknown>, schema: Record<string, unknown>): Record<string, unknown>;
|
|
567
|
+
/** The reserved state key host policy writes under. Engine-owned like every `$`-prefixed key: no node may name it. */
|
|
568
|
+
export declare const HOST_STATE_KEY = "$host";
|
|
517
569
|
export declare class WorkflowVerificationError extends Error {
|
|
518
570
|
readonly stage: string;
|
|
519
571
|
readonly candidate: unknown;
|
package/dist/workflow.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { createHash } from "node:crypto";
|
|
2
2
|
import { isDeepStrictEqual, types as utilTypes } from "node:util";
|
|
3
|
-
import { predicateMatches, MECHANICAL_PREDICATE_NAMES } from "./predicates.js";
|
|
3
|
+
import { predicateMatches, getPath, MECHANICAL_PREDICATE_NAMES } from "./predicates.js";
|
|
4
|
+
import { WORKFLOW_NODE_KINDS, NODE_FIELDS, IGNORED_NODE_FIELDS, WORKFLOW_PREDICATES, THINKING_LEVELS, MODEL_TIERS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, PROSE_ARTIFACT_TYPES } from "./vocabulary.js";
|
|
4
5
|
import { validateAnswers, answerConfidence, answersSidecar, answersToValue, compileQuestions, SYSTEM_ONE_LIMITS } from "./system-one.js";
|
|
5
6
|
import { Compile } from "typebox/compile";
|
|
6
7
|
import { compileTransform, compileTransformSyntax } from "./code-exec.js";
|
|
@@ -8,7 +9,7 @@ import { workflowShapeErrors } from "./workflow-shape.js";
|
|
|
8
9
|
import { resolveSchemaForWorkflow } from "./schema-references.js";
|
|
9
10
|
export { resolveSchemaForWorkflow } from "./schema-references.js";
|
|
10
11
|
export function artifactNodeIsProse(node) {
|
|
11
|
-
return
|
|
12
|
+
return PROSE_ARTIFACT_TYPES.includes(node.type);
|
|
12
13
|
}
|
|
13
14
|
export function desugarWorkflow(workflow) {
|
|
14
15
|
const visit = (node) => {
|
|
@@ -75,6 +76,41 @@ export const declaredWrites = (node) => {
|
|
|
75
76
|
visit(node);
|
|
76
77
|
return out;
|
|
77
78
|
};
|
|
79
|
+
/** The top-level keys a loop body writes, with engine sidecars; null when an unaliased code node makes them unknowable. */
|
|
80
|
+
const loopBodyWrites = (body) => {
|
|
81
|
+
const out = new Set();
|
|
82
|
+
let known = true;
|
|
83
|
+
const visit = (n) => {
|
|
84
|
+
if (!n || typeof n !== "object" || !known)
|
|
85
|
+
return;
|
|
86
|
+
if (n.node === "code" && n.as === undefined) {
|
|
87
|
+
known = false;
|
|
88
|
+
return;
|
|
89
|
+
}
|
|
90
|
+
if (n.node === "report")
|
|
91
|
+
out.add("report_markdown");
|
|
92
|
+
else if (typeof n.as === "string" && n.as.trim())
|
|
93
|
+
out.add(n.as);
|
|
94
|
+
else if (["agent", "decide", "extract"].includes(n.node) && typeof n.label === "string")
|
|
95
|
+
out.add(n.label);
|
|
96
|
+
if (n.node === "map" || n.node === "workflow")
|
|
97
|
+
return;
|
|
98
|
+
if (Array.isArray(n.steps))
|
|
99
|
+
n.steps.forEach(visit);
|
|
100
|
+
if (Array.isArray(n.branches))
|
|
101
|
+
n.branches.forEach(visit);
|
|
102
|
+
else if (n.node === "route" && n.branches && typeof n.branches === "object")
|
|
103
|
+
Object.values(n.branches).forEach((b) => visit(b?.body));
|
|
104
|
+
if (n.body)
|
|
105
|
+
visit(n.body);
|
|
106
|
+
};
|
|
107
|
+
visit(body);
|
|
108
|
+
if (!known)
|
|
109
|
+
return null;
|
|
110
|
+
for (const key of [...out])
|
|
111
|
+
out.add(`${key}$answers`).add(`${key}$verify`);
|
|
112
|
+
return out;
|
|
113
|
+
};
|
|
78
114
|
const routeBodies = (node) => node.node === "route" ? Object.values(node.branches || {}).map((b) => b?.body).filter(Boolean) : [];
|
|
79
115
|
const snapshotState = (state) => {
|
|
80
116
|
try {
|
|
@@ -84,7 +120,10 @@ const snapshotState = (state) => {
|
|
|
84
120
|
throw new Error("Workflow state must be structured-cloneable", { cause });
|
|
85
121
|
}
|
|
86
122
|
};
|
|
87
|
-
const KINDS = new Set(
|
|
123
|
+
const KINDS = new Set(WORKFLOW_NODE_KINDS);
|
|
124
|
+
const kindsMatchType = true;
|
|
125
|
+
void kindsMatchType;
|
|
126
|
+
const KIND_KEYS = Object.fromEntries(WORKFLOW_NODE_KINDS.map((kind) => [kind, new Set([...NODE_FIELDS[kind], ...(IGNORED_NODE_FIELDS[kind] ?? [])])]));
|
|
88
127
|
export const childSteps = (child) => {
|
|
89
128
|
const root = child?.root;
|
|
90
129
|
if (!root || typeof root !== "object")
|
|
@@ -114,7 +153,7 @@ function containsReportNode(node) {
|
|
|
114
153
|
return routeBodies(node).some(containsReportNode);
|
|
115
154
|
return false;
|
|
116
155
|
}
|
|
117
|
-
const PREDICATES = new Set(
|
|
156
|
+
const PREDICATES = new Set(WORKFLOW_PREDICATES);
|
|
118
157
|
function predicateShapeErrors(pred) {
|
|
119
158
|
const out = [];
|
|
120
159
|
if (pred.predicate === "in") {
|
|
@@ -431,6 +470,54 @@ export function validateWorkflow(workflow, opts) {
|
|
|
431
470
|
}
|
|
432
471
|
return patches;
|
|
433
472
|
};
|
|
473
|
+
const snapshotKnowledge = () => ({
|
|
474
|
+
available: reachability ? new Set(reachability.available) : null, unknowable: reachability?.unknowable ?? true,
|
|
475
|
+
typed: new Map(typedOutputs), probed: new Map([...probedSubtrees].map(([key, values]) => [key, [...values]])),
|
|
476
|
+
spread: new Set(spreadTaintedKeys), files: new Set(producedFiles),
|
|
477
|
+
});
|
|
478
|
+
const restoreKnowledge = (knowledge) => {
|
|
479
|
+
if (reachability && knowledge.available) {
|
|
480
|
+
reachability.available = new Set(knowledge.available);
|
|
481
|
+
reachability.unknowable = knowledge.unknowable;
|
|
482
|
+
}
|
|
483
|
+
typedOutputs.clear();
|
|
484
|
+
for (const [key, value] of knowledge.typed)
|
|
485
|
+
typedOutputs.set(key, value);
|
|
486
|
+
probedSubtrees.clear();
|
|
487
|
+
for (const [key, values] of knowledge.probed)
|
|
488
|
+
probedSubtrees.set(key, [...values]);
|
|
489
|
+
spreadTaintedKeys.clear();
|
|
490
|
+
for (const key of knowledge.spread)
|
|
491
|
+
spreadTaintedKeys.add(key);
|
|
492
|
+
producedFiles.clear();
|
|
493
|
+
for (const file of knowledge.files)
|
|
494
|
+
producedFiles.add(file);
|
|
495
|
+
};
|
|
496
|
+
/** After a parallel node: each branch's own changes applied over the state before it; keys, files and shapes accumulate. */
|
|
497
|
+
const mergeKnowledge = (before, branches) => {
|
|
498
|
+
restoreKnowledge(before);
|
|
499
|
+
for (const branch of branches) {
|
|
500
|
+
if (reachability && branch.available)
|
|
501
|
+
for (const key of branch.available)
|
|
502
|
+
reachability.available.add(key);
|
|
503
|
+
for (const [key, value] of branch.typed)
|
|
504
|
+
if (before.typed.get(key) !== value)
|
|
505
|
+
typedOutputs.set(key, value);
|
|
506
|
+
for (const key of before.typed.keys())
|
|
507
|
+
if (!branch.typed.has(key))
|
|
508
|
+
typedOutputs.delete(key);
|
|
509
|
+
for (const [key, values] of branch.probed)
|
|
510
|
+
if (before.probed.get(key)?.length !== values.length || before.probed.get(key)?.some((v, i) => v !== values[i]))
|
|
511
|
+
probedSubtrees.set(key, [...values]);
|
|
512
|
+
for (const key of branch.spread)
|
|
513
|
+
spreadTaintedKeys.add(key);
|
|
514
|
+
for (const file of branch.files)
|
|
515
|
+
producedFiles.add(file);
|
|
516
|
+
}
|
|
517
|
+
// The merged state depends on which branches ran how; later reachability checks stand down, as before.
|
|
518
|
+
if (reachability)
|
|
519
|
+
reachability.unknowable = true;
|
|
520
|
+
};
|
|
434
521
|
const checkPredicatePath = (when, label, path) => {
|
|
435
522
|
if (!reachability || !when?.path)
|
|
436
523
|
return;
|
|
@@ -464,6 +551,21 @@ export function validateWorkflow(workflow, opts) {
|
|
|
464
551
|
}
|
|
465
552
|
errors.push(`${path} (${label}): predicate path "${when.path}" is not produced by the code node that writes "${head}" (its shape has: ${missingAt && typeof missingAt === "object" ? Object.keys(missingAt).join(", ") : typeof missingAt}); the guard can never fire`);
|
|
466
553
|
};
|
|
554
|
+
// A mechanical predicate reads one state key; when no input key or earlier node writes it, the guard can never fire.
|
|
555
|
+
const checkPredicateHead = (pred, label, path, field, produced) => {
|
|
556
|
+
if (!reachability || reachability.unknowable || !pred || typeof pred !== "object")
|
|
557
|
+
return;
|
|
558
|
+
const available = produced ?? reachability.available;
|
|
559
|
+
const { predicate, path: at, key } = pred;
|
|
560
|
+
const read = predicate === "no_new_items" ? key : predicate === "ask" ? undefined : at;
|
|
561
|
+
if (typeof read !== "string" || !read.trim())
|
|
562
|
+
return;
|
|
563
|
+
const head = read.split(".")[0];
|
|
564
|
+
if (!available.has(head))
|
|
565
|
+
errors.push(`${path} (${label}): ${field} reads "${read}" but no input key or earlier node produces "${head}"; the guard can never fire`);
|
|
566
|
+
else if (!produced)
|
|
567
|
+
checkTypedPath(read, `${path} (${label}) ${field}`);
|
|
568
|
+
};
|
|
467
569
|
const checkInterpolations = (value, label, path) => {
|
|
468
570
|
if (!reachability || reachability.unknowable || value === undefined)
|
|
469
571
|
return;
|
|
@@ -570,27 +672,6 @@ export function validateWorkflow(workflow, opts) {
|
|
|
570
672
|
catch { /* Schema diagnostics above retain the original compilation failure. */ }
|
|
571
673
|
}
|
|
572
674
|
}
|
|
573
|
-
const KIND_KEYS = {
|
|
574
|
-
chain: new Set(["node", "steps"]),
|
|
575
|
-
code: new Set(["node", "label", "code", "as"]),
|
|
576
|
-
// "budget" (agent) and "samples"/"voteField" (decide) are deprecated-and-ignored: tolerated
|
|
577
|
-
// for legacy v2 documents. The engine invokes the adapter once per node.
|
|
578
|
-
agent: new Set(["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "budget", "verify", "tier"]),
|
|
579
|
-
decide: new Set(["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "samples", "voteField", "verify", "tier"]),
|
|
580
|
-
extract: new Set(["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "verify", "tier"]),
|
|
581
|
-
report: new Set(["node", "label", "state", "instructions", "sopSection", "requires", "tools", "effort", "thinking"]),
|
|
582
|
-
artifact: new Set(["node", "label", "state", "type", "path", "instructions", "sopSection", "requires", "tools", "effort", "thinking"]),
|
|
583
|
-
map: new Set(["node", "label", "itemsPath", "body", "as", "resultPath", "maxConcurrency"]),
|
|
584
|
-
parallel: new Set(["node", "label", "branches"]),
|
|
585
|
-
loop: new Set(["node", "label", "body", "until", "maxIters"]),
|
|
586
|
-
escalate: new Set(["node", "label", "when", "kind", "stage", "summary"]),
|
|
587
|
-
call: new Set(["node", "label", "via", "tool", "args", "code", "input", "command", "where", "out", "as", "produces", "deadline_s", "retry", "poll", "requires", "env"]),
|
|
588
|
-
workflow: new Set(["node", "label", "workflow", "input", "out", "as"]),
|
|
589
|
-
judge: new Set(["node", "label", "state", "out", "as", "requires"]),
|
|
590
|
-
pick: new Set(["node", "label", "itemsPath", "describe", "instructions", "state", "allowNone", "as", "requires"]),
|
|
591
|
-
sift: new Set(["node", "label", "itemsPath", "describe", "state", "out", "as", "keep", "requires"]),
|
|
592
|
-
route: new Set(["node", "label", "state", "instructions", "branches", "unsure", "as", "requires"]),
|
|
593
|
-
};
|
|
594
675
|
const checkStateMap = (map, label, path, field = "state") => {
|
|
595
676
|
if (map === undefined)
|
|
596
677
|
return;
|
|
@@ -633,6 +714,14 @@ export function validateWorkflow(workflow, opts) {
|
|
|
633
714
|
const extraneous = Object.keys(node).filter((key) => !allowed.has(key));
|
|
634
715
|
if (extraneous.length)
|
|
635
716
|
errors.push(`${path} (${node.label || node.node}): unknown key(s) for a ${node.node} node: ${extraneous.join(", ")}`);
|
|
717
|
+
// `$`-prefixed state keys are engine-owned (`$host`, `<as>$verify`): no node may write one. A label
|
|
718
|
+
// is the state key whenever `as` is omitted, so labels are held to the same rule.
|
|
719
|
+
if (typeof node.as === "string" && node.as.startsWith("$"))
|
|
720
|
+
errors.push(`${path} (${node.label || node.node}): "as" must not name an engine-owned "$" state key ("${node.as}")`);
|
|
721
|
+
// Only an unaliased generative or code node writes under its label; every other label is a name, not a key.
|
|
722
|
+
const labelIsKey = (node.node === "agent" || node.node === "decide" || node.node === "extract" || node.node === "code") && node.as === undefined;
|
|
723
|
+
if (labelIsKey && typeof node.label === "string" && node.label.startsWith("$"))
|
|
724
|
+
errors.push(`${path} (${node.label}): label must not begin with "$" — an unaliased ${node.node} node writes under its label, and "$" keys are engine-owned`);
|
|
636
725
|
}
|
|
637
726
|
switch (node.node) {
|
|
638
727
|
case "chain":
|
|
@@ -681,12 +770,12 @@ export function validateWorkflow(workflow, opts) {
|
|
|
681
770
|
errors.push(`${path} (${node.label}): instructions required`);
|
|
682
771
|
if (node.node !== "report" && !Object.hasOwn(workflow.schemas, node.out))
|
|
683
772
|
errors.push(`${path} (${node.label}): out schema "${node.out}" not in workflow.schemas`);
|
|
684
|
-
if (node.thinking !== undefined && !
|
|
773
|
+
if (node.thinking !== undefined && !THINKING_LEVELS.includes(String(node.thinking)))
|
|
685
774
|
errors.push(`${path} (${node.label}): thinking must be low|medium|high — thinking is never off`);
|
|
686
775
|
if (node.tools !== undefined && (!Array.isArray(node.tools) || node.tools.some((t) => typeof t !== "string" || !t.trim())))
|
|
687
776
|
errors.push(`${path} (${node.label}): tools must be a list of non-empty tool names when present (an empty list disables tools)`);
|
|
688
777
|
checkRequires(node, path);
|
|
689
|
-
if (node.tier !== undefined && !
|
|
778
|
+
if (node.tier !== undefined && !MODEL_TIERS.includes(String(node.tier)))
|
|
690
779
|
errors.push(`${path} (${node.label}): tier must be fast|default|strong`);
|
|
691
780
|
if (node.node !== "report" && node.verify !== undefined) {
|
|
692
781
|
const v = node.verify;
|
|
@@ -739,8 +828,6 @@ export function validateWorkflow(workflow, opts) {
|
|
|
739
828
|
errors.push(`${path} (${node.label}): parallel needs at least two branches`);
|
|
740
829
|
if (containsReportNode(node))
|
|
741
830
|
errors.push(`${path} (${node.label}): a report node cannot live inside a parallel branch — the report is rendered once, after every branch has landed`);
|
|
742
|
-
if (reachability)
|
|
743
|
-
reachability.unknowable = true;
|
|
744
831
|
{
|
|
745
832
|
const writers = new Map();
|
|
746
833
|
(node.branches || []).forEach((branch, i) => {
|
|
@@ -752,7 +839,21 @@ export function validateWorkflow(workflow, opts) {
|
|
|
752
839
|
}
|
|
753
840
|
});
|
|
754
841
|
}
|
|
755
|
-
|
|
842
|
+
{
|
|
843
|
+
// Every branch starts from the state before the parallel node: a branch never sees a sibling's writes.
|
|
844
|
+
// All walk knowledge is restored per branch, then the branches' results merge (their writes are disjoint).
|
|
845
|
+
const before = snapshotKnowledge();
|
|
846
|
+
const after = [];
|
|
847
|
+
(node.branches || []).forEach((branch, i) => {
|
|
848
|
+
restoreKnowledge(before);
|
|
849
|
+
walk(branch, `${path}.branches[${i}]`);
|
|
850
|
+
after.push(snapshotKnowledge());
|
|
851
|
+
});
|
|
852
|
+
if (after.length)
|
|
853
|
+
mergeKnowledge(before, after);
|
|
854
|
+
if (reachability)
|
|
855
|
+
reachability.unknowable = true;
|
|
856
|
+
}
|
|
756
857
|
return;
|
|
757
858
|
case "loop":
|
|
758
859
|
if (!Number.isInteger(node.maxIters) || node.maxIters < 1 || node.maxIters > 20)
|
|
@@ -760,6 +861,12 @@ export function validateWorkflow(workflow, opts) {
|
|
|
760
861
|
if (containsReportNode(node.body))
|
|
761
862
|
errors.push(`${path} (${node.label}): a report node cannot live inside a loop body — the report is rendered once, after the record is final`);
|
|
762
863
|
checkPredicate(node.until, node.label, path, "until");
|
|
864
|
+
{
|
|
865
|
+
// `until` reads the state after the body: the keys before the loop plus every key the body writes.
|
|
866
|
+
const bodyWrites = loopBodyWrites(node.body);
|
|
867
|
+
if (reachability && !reachability.unknowable && bodyWrites)
|
|
868
|
+
checkPredicateHead(node.until, node.label, path, "until", new Set([...reachability.available, ...bodyWrites]));
|
|
869
|
+
}
|
|
763
870
|
if (reachability)
|
|
764
871
|
reachability.unknowable = true;
|
|
765
872
|
walk(node.body, `${path}.body`);
|
|
@@ -769,6 +876,7 @@ export function validateWorkflow(workflow, opts) {
|
|
|
769
876
|
checkPredicate(node.when, node.label, path, "when");
|
|
770
877
|
if (!node.kind?.trim() || !node.stage?.trim() || !node.summary?.trim())
|
|
771
878
|
errors.push(`${path} (${node.label}): kind, stage, summary required`);
|
|
879
|
+
checkPredicateHead(node.when, node.label, path, "when");
|
|
772
880
|
checkPredicatePath(node.when, node.label, path);
|
|
773
881
|
return;
|
|
774
882
|
case "judge": {
|
|
@@ -919,6 +1027,8 @@ export function validateWorkflow(workflow, opts) {
|
|
|
919
1027
|
errors.push(`${path} (${label}): out schema "${String(node.out)}" not in workflow.schemas`);
|
|
920
1028
|
if (!node.input || typeof node.input !== "object" || Array.isArray(node.input))
|
|
921
1029
|
errors.push(`${path} (${label}): input must be an object mapping onto the child's initial state`);
|
|
1030
|
+
else if (Object.hasOwn(node.input, HOST_STATE_KEY))
|
|
1031
|
+
errors.push(`${path} (${label}): input must not contain the reserved "${HOST_STATE_KEY}" key`);
|
|
922
1032
|
const child = node.workflow;
|
|
923
1033
|
const steps = childSteps(child);
|
|
924
1034
|
if (!child || typeof child !== "object" || !steps || !steps.length)
|
|
@@ -946,7 +1056,7 @@ export function validateWorkflow(workflow, opts) {
|
|
|
946
1056
|
}
|
|
947
1057
|
case "call": {
|
|
948
1058
|
const label = node.label || "call";
|
|
949
|
-
if (!
|
|
1059
|
+
if (!CALL_TRANSPORTS.includes(String(node.via)))
|
|
950
1060
|
errors.push(`${path} (${label}): via must be tool|executor|shell`);
|
|
951
1061
|
if (node.via === "tool") {
|
|
952
1062
|
if (!node.tool?.trim())
|
|
@@ -1007,7 +1117,7 @@ export function validateWorkflow(workflow, opts) {
|
|
|
1007
1117
|
errors.push(`${path} (${label}): retry.attempts must be 1..5`);
|
|
1008
1118
|
if (r?.backoff_s !== undefined && !(Number.isFinite(r.backoff_s) && r.backoff_s >= 0 && r.backoff_s <= 60))
|
|
1009
1119
|
errors.push(`${path} (${label}): retry.backoff_s must be 0..60`);
|
|
1010
|
-
if (r?.on !== undefined && (!Array.isArray(r.on) || r.on.some((c) => !
|
|
1120
|
+
if (r?.on !== undefined && (!Array.isArray(r.on) || r.on.some((c) => !CALL_RETRY_CLASSES.includes(String(c)))))
|
|
1011
1121
|
errors.push(`${path} (${label}): retry.on may name only timeout|http_5xx|http_429|connection|exit`);
|
|
1012
1122
|
}
|
|
1013
1123
|
if (node.poll !== undefined) {
|
|
@@ -1163,9 +1273,6 @@ export function validateWorkflow(workflow, opts) {
|
|
|
1163
1273
|
errors.push(...workflowShapeErrors(workflow, true));
|
|
1164
1274
|
return errors.length ? { ok: false, errors } : { ok: true };
|
|
1165
1275
|
}
|
|
1166
|
-
function getPath(value, path) {
|
|
1167
|
-
return path.split(".").reduce((acc, key) => (acc == null ? acc : acc[key]), value);
|
|
1168
|
-
}
|
|
1169
1276
|
function interpolate(template, state) {
|
|
1170
1277
|
return template.replace(/\{([a-zA-Z0-9_.$]+)\}/g, (_, p) => {
|
|
1171
1278
|
let v = getPath(state, p);
|
|
@@ -1705,6 +1812,25 @@ async function runRouteNode(node, state, workflow, deps) {
|
|
|
1705
1812
|
}
|
|
1706
1813
|
const EXECUTION_PATH = Symbol("workflow.executionPath");
|
|
1707
1814
|
const SCOPED_EFFECTS = Symbol("workflow.scopedEffects");
|
|
1815
|
+
/** The map item a scoped copy of deps runs for, so host policy context can name it. */
|
|
1816
|
+
const MAP_ITEM = Symbol("workflow.mapItem");
|
|
1817
|
+
/** The reserved state key host policy writes under. Engine-owned like every `$`-prefixed key: no node may name it. */
|
|
1818
|
+
export const HOST_STATE_KEY = "$host";
|
|
1819
|
+
const hostStateOf = (state) => {
|
|
1820
|
+
const host = state[HOST_STATE_KEY];
|
|
1821
|
+
return host && typeof host === "object" && !Array.isArray(host) ? host : {};
|
|
1822
|
+
};
|
|
1823
|
+
const hostContext = (workflow, node, deps) => {
|
|
1824
|
+
const item = deps[MAP_ITEM];
|
|
1825
|
+
const generative = node.node === "agent" || node.node === "decide" || node.node === "extract" || node.node === "report";
|
|
1826
|
+
return {
|
|
1827
|
+
workflow: { name: workflow.name, outputSchemaId: workflow.output.schemaId },
|
|
1828
|
+
node: { kind: node.node, label: String(node.label ?? node.node), ...("out" in node && typeof node.out === "string" ? { out: node.out } : {}), ...("as" in node && typeof node.as === "string" ? { as: node.as } : {}) },
|
|
1829
|
+
terminal: generative && node.node !== "report" && node.out === workflow.output.schemaId,
|
|
1830
|
+
executionPath: executionPath(deps),
|
|
1831
|
+
...(item ? { item } : {}),
|
|
1832
|
+
};
|
|
1833
|
+
};
|
|
1708
1834
|
const executionPath = (deps) => deps[EXECUTION_PATH] ?? "/root";
|
|
1709
1835
|
const scopeExecution = (deps, ...parts) => ({
|
|
1710
1836
|
...deps,
|
|
@@ -1741,6 +1867,7 @@ function scopeDepsToItem(deps, item, signal) {
|
|
|
1741
1867
|
const recovery = deps.recovery;
|
|
1742
1868
|
return {
|
|
1743
1869
|
...deps,
|
|
1870
|
+
...{ [MAP_ITEM]: item },
|
|
1744
1871
|
checkpoint: undefined,
|
|
1745
1872
|
...(signal ? { signal } : {}),
|
|
1746
1873
|
...(deps.runNode ? { runNode: params => deps.runNode({ ...params, item: params.item ?? item, ...(signal ? { signal: params.signal ?? signal } : {}) }) } : {}),
|
|
@@ -1816,9 +1943,20 @@ async function runNodeOnState(node, state, workflow, deps) {
|
|
|
1816
1943
|
try {
|
|
1817
1944
|
if (deps.signal?.aborted)
|
|
1818
1945
|
throw deps.signal.reason ?? new Error("workflow aborted");
|
|
1819
|
-
|
|
1946
|
+
let out = await runNodeBody(node, state, workflow, deps);
|
|
1820
1947
|
if (deps.signal?.aborted)
|
|
1821
1948
|
throw deps.signal.reason ?? new Error("workflow aborted");
|
|
1949
|
+
// Host policy enrichment lands before commit and checkpoint: a resumed run sees exactly what ran.
|
|
1950
|
+
if (isStep && deps.hostPolicy?.afterNode) {
|
|
1951
|
+
const patch = deps.hostPolicy.afterNode({ ...hostContext(workflow, node, deps), state: out });
|
|
1952
|
+
if (patch && typeof patch === "object" && !Array.isArray(patch) && Object.prototype.hasOwnProperty.call(patch, HOST_STATE_KEY)) {
|
|
1953
|
+
throw new WorkflowStateError(`host policy afterNode for "${label}" may not write the reserved "${HOST_STATE_KEY}" key; return host state from decodeSubmission`, label, HOST_STATE_KEY, "reserved_state_key");
|
|
1954
|
+
}
|
|
1955
|
+
if (patch && typeof patch === "object" && !Array.isArray(patch) && Object.keys(patch).length) {
|
|
1956
|
+
out = { ...out, ...patch };
|
|
1957
|
+
deps.onEvent?.({ type: "host.patched", label, detail: { keys: Object.keys(patch) } });
|
|
1958
|
+
}
|
|
1959
|
+
}
|
|
1822
1960
|
if (deps.recovery && node.node !== "chain")
|
|
1823
1961
|
await deps.recovery.commit(node, out, undefined, executionPath(deps));
|
|
1824
1962
|
if (deps.signal?.aborted)
|
|
@@ -1881,6 +2019,8 @@ async function runNodeBody(node, state, workflow, deps) {
|
|
|
1881
2019
|
throw new WorkflowCodeError(node.label, cause);
|
|
1882
2020
|
}
|
|
1883
2021
|
const patch = node.as ? { [node.as]: out } : (out && typeof out === "object" && !Array.isArray(out) ? out : { [node.label]: out });
|
|
2022
|
+
if (Object.prototype.hasOwnProperty.call(patch, HOST_STATE_KEY))
|
|
2023
|
+
throw new WorkflowStateError(`code node "${node.label}" wrote the reserved "${HOST_STATE_KEY}" state key`, node.label, HOST_STATE_KEY, "reserved_state_key");
|
|
1884
2024
|
deps.onEvent?.({ type: "code.patch", label: node.label, detail: patch });
|
|
1885
2025
|
return { ...state, ...patch };
|
|
1886
2026
|
}
|
|
@@ -1897,27 +2037,68 @@ async function runNodeBody(node, state, workflow, deps) {
|
|
|
1897
2037
|
assertNodeInputs(node, state);
|
|
1898
2038
|
const promptState = node.state ? interpolateValue(node.state, state, node.label) : promptStateOf(state);
|
|
1899
2039
|
const verifier = node.node !== "report" && node.verify ? compileVerifier(workflow, node, state, deps) : null;
|
|
2040
|
+
// Host policy: the adapter submits against the transport schema (the stage schema plus the host's
|
|
2041
|
+
// channels); the decoded domain value is what the stage schema, the verifier and the state see.
|
|
2042
|
+
const policy = deps.hostPolicy;
|
|
2043
|
+
const context = policy ? hostContext(workflow, node, deps) : null;
|
|
2044
|
+
const transportSchema = policy?.submissionSchema && context ? policy.submissionSchema(schema, context) : schema;
|
|
2045
|
+
const transportValidator = transportSchema === schema ? validator : Compile(transportSchema);
|
|
2046
|
+
const stageName = node.node === "report" ? "report" : node.out;
|
|
2047
|
+
const decode = (raw) => {
|
|
2048
|
+
normalizeStringNullsForSchema(raw, transportSchema);
|
|
2049
|
+
if (!transportValidator.Check(raw)) {
|
|
2050
|
+
throw new WorkflowOutputInvalidError(`${node.node} node "${node.label}" submission does not satisfy schema "${stageName}"`, schemaProblems(transportValidator, raw), node.label);
|
|
2051
|
+
}
|
|
2052
|
+
const decoded = policy?.decodeSubmission && context ? policy.decodeSubmission(raw, { ...context, host: hostStateOf(state) }) : { value: raw };
|
|
2053
|
+
if (decoded !== null && typeof decoded === "object" && decoded.value !== raw)
|
|
2054
|
+
normalizeStringNullsForSchema(decoded.value, schema);
|
|
2055
|
+
if (!validator.Check(decoded.value)) {
|
|
2056
|
+
throw new WorkflowOutputInvalidError(`${node.node} node "${node.label}" decoded submission does not satisfy schema "${stageName}"`, schemaProblems(validator, decoded.value), node.label);
|
|
2057
|
+
}
|
|
2058
|
+
return decoded;
|
|
2059
|
+
};
|
|
2060
|
+
// A verify clause reviews the domain value: the host's channels are split off before the judge sees it.
|
|
2061
|
+
const review = verifier
|
|
2062
|
+
? (transportSchema === schema && !policy?.decodeSubmission
|
|
2063
|
+
? verifier.review
|
|
2064
|
+
: async (candidate) => {
|
|
2065
|
+
let decoded;
|
|
2066
|
+
try {
|
|
2067
|
+
decoded = decode(structuredClone(candidate));
|
|
2068
|
+
}
|
|
2069
|
+
catch (error) {
|
|
2070
|
+
if (error instanceof WorkflowOutputInvalidError)
|
|
2071
|
+
return { accepted: false, message: error.message };
|
|
2072
|
+
throw error;
|
|
2073
|
+
}
|
|
2074
|
+
return verifier.review(decoded.value);
|
|
2075
|
+
})
|
|
2076
|
+
: undefined;
|
|
1900
2077
|
let submission;
|
|
1901
2078
|
submission = await deps.runNode({
|
|
1902
2079
|
signal: deps.signal,
|
|
1903
2080
|
kind: node.node, label: node.label,
|
|
1904
|
-
...(
|
|
2081
|
+
...(review ? { review } : {}),
|
|
1905
2082
|
...(node.tier ? { tier: node.tier } : {}),
|
|
1906
|
-
system: [sopSlice, deps.skill, node.instructions].filter(Boolean),
|
|
2083
|
+
system: [sopSlice, deps.skill, node.instructions, ...(policy?.systemBlocks && context ? policy.systemBlocks(context) : [])].filter(Boolean),
|
|
1907
2084
|
user: JSON.stringify(promptState),
|
|
1908
|
-
schema,
|
|
2085
|
+
schema: transportSchema,
|
|
1909
2086
|
...(node.effort ? { effort: node.effort } : {}),
|
|
1910
2087
|
...(node.thinking ? { thinking: node.thinking } : {}),
|
|
1911
2088
|
...(Array.isArray(node.tools) ? { tools: node.tools } : {}),
|
|
1912
2089
|
});
|
|
1913
|
-
|
|
1914
|
-
|
|
1915
|
-
throw new WorkflowOutputInvalidError(`${node.node} node "${node.label}" submission does not satisfy schema "${node.node === "report" ? "report" : node.out}"`, schemaProblems(validator, submission), node.label);
|
|
1916
|
-
}
|
|
1917
|
-
const result = submission;
|
|
2090
|
+
const decoded = decode(submission);
|
|
2091
|
+
const result = decoded.value;
|
|
1918
2092
|
const verified = verifier ? await verifier.finish(result) : null;
|
|
1919
|
-
|
|
1920
|
-
|
|
2093
|
+
let merged = mergeStageDelta(state, node, verified ? verified.submission : result, stageSchema);
|
|
2094
|
+
if (verified)
|
|
2095
|
+
merged = { ...merged, [`${("as" in node && node.as) || node.label}$verify`]: verified.record };
|
|
2096
|
+
const hostState = decoded.host && typeof decoded.host === "object" && !Array.isArray(decoded.host) ? decoded.host : null;
|
|
2097
|
+
if (hostState && Object.keys(hostState).length) {
|
|
2098
|
+
deps.onEvent?.({ type: "host.decoded", label: node.label, detail: { keys: Object.keys(hostState) } });
|
|
2099
|
+
merged = { ...merged, [HOST_STATE_KEY]: { ...hostStateOf(merged), ...hostState } };
|
|
2100
|
+
}
|
|
2101
|
+
return merged;
|
|
1921
2102
|
}
|
|
1922
2103
|
case "map": {
|
|
1923
2104
|
const items = getPath(state, node.itemsPath);
|
|
@@ -2009,8 +2190,48 @@ async function runNodeBody(node, state, workflow, deps) {
|
|
|
2009
2190
|
throw withSiblingUncertainty(failure, uncertainties);
|
|
2010
2191
|
const merged = { ...state };
|
|
2011
2192
|
const writer = new Map();
|
|
2193
|
+
// Host state is engine-owned and merges by delta: every branch started from the same `$host`, so an
|
|
2194
|
+
// array grows by what each branch appended, an unchanged value is kept, and two branches that set one
|
|
2195
|
+
// non-array key to different values are a write conflict like any other.
|
|
2196
|
+
const baseHost = hostStateOf(baseline);
|
|
2197
|
+
const mergedHost = { ...baseHost };
|
|
2198
|
+
const hostWriter = new Map();
|
|
2199
|
+
let hostChanged = false;
|
|
2200
|
+
outs.forEach((out, i) => {
|
|
2201
|
+
const branchHost = hostStateOf((out || {}));
|
|
2202
|
+
for (const [key, value] of Object.entries(branchHost)) {
|
|
2203
|
+
if (Object.hasOwn(baseHost, key) && isDeepStrictEqual(value, baseHost[key]))
|
|
2204
|
+
continue;
|
|
2205
|
+
hostChanged = true;
|
|
2206
|
+
// The same value from several branches is one write, whatever its shape.
|
|
2207
|
+
if (hostWriter.has(key) && isDeepStrictEqual(mergedHost[key], value))
|
|
2208
|
+
continue;
|
|
2209
|
+
const base = baseHost[key];
|
|
2210
|
+
const prior = hostWriter.get(key);
|
|
2211
|
+
const conflict = () => new WorkflowStateError(`parallel node "${node.label}": branches ${prior} and ${i} both wrote host state ${HOST_STATE_KEY}.${key} to different values`, node.label, `${HOST_STATE_KEY}.${key}`, "parallel_write_conflict");
|
|
2212
|
+
// An append is an array that extends the base array (or a new array on a key with no base).
|
|
2213
|
+
// Appends from several branches join in branch order. An append meets a prior non-append
|
|
2214
|
+
// write of the same key as a conflict, whichever branch came first: no shape wins silently.
|
|
2215
|
+
if (Array.isArray(value) && (base === undefined || Array.isArray(base)) && (!Array.isArray(base) || (value.length >= base.length && base.every((entry, n) => isDeepStrictEqual(entry, value[n]))))) {
|
|
2216
|
+
if (prior !== undefined && !Array.isArray(mergedHost[key]))
|
|
2217
|
+
throw conflict();
|
|
2218
|
+
const appended = value.slice(Array.isArray(base) ? base.length : 0);
|
|
2219
|
+
mergedHost[key] = [...(Array.isArray(mergedHost[key]) ? mergedHost[key] : []), ...appended];
|
|
2220
|
+
hostWriter.set(key, i);
|
|
2221
|
+
continue;
|
|
2222
|
+
}
|
|
2223
|
+
if (prior !== undefined && !isDeepStrictEqual(mergedHost[key], value))
|
|
2224
|
+
throw conflict();
|
|
2225
|
+
hostWriter.set(key, i);
|
|
2226
|
+
mergedHost[key] = value;
|
|
2227
|
+
}
|
|
2228
|
+
});
|
|
2229
|
+
if (hostChanged)
|
|
2230
|
+
merged[HOST_STATE_KEY] = mergedHost;
|
|
2012
2231
|
outs.forEach((out, i) => {
|
|
2013
2232
|
for (const [key, value] of Object.entries((out || {}))) {
|
|
2233
|
+
if (key === HOST_STATE_KEY)
|
|
2234
|
+
continue;
|
|
2014
2235
|
if (Object.hasOwn(baseline, key) && isDeepStrictEqual(value, baseline[key]))
|
|
2015
2236
|
continue;
|
|
2016
2237
|
const prior = writer.get(key);
|
|
@@ -2240,14 +2461,19 @@ export async function runWorkflow(workflow, input, deps) {
|
|
|
2240
2461
|
deps = { ...deps, [SCOPED_EFFECTS]: true };
|
|
2241
2462
|
if (deps.recovery && !deps.recovery.supportsExecutionPaths && needsComposedRecovery(workflow.root))
|
|
2242
2463
|
throw new Error("Composed child workflows require recovery.supportsExecutionPaths: true and stores keyed by executionPath");
|
|
2464
|
+
if (Object.prototype.hasOwnProperty.call(input, HOST_STATE_KEY))
|
|
2465
|
+
throw new WorkflowInputInvalidError(workflow.name, [`input must not contain the reserved "${HOST_STATE_KEY}" key`]);
|
|
2243
2466
|
try {
|
|
2244
2467
|
const state = await runNodeOnState(workflow.root, snapshotState(input), workflow, deps);
|
|
2245
|
-
const
|
|
2468
|
+
const host = hostStateOf(state);
|
|
2469
|
+
const output = workflow.output.path
|
|
2470
|
+
? getPath(state, workflow.output.path)
|
|
2471
|
+
: (Object.prototype.hasOwnProperty.call(state, HOST_STATE_KEY) ? Object.fromEntries(Object.entries(state).filter(([key]) => key !== HOST_STATE_KEY)) : state);
|
|
2246
2472
|
const validator = Compile(resolveSchemaForWorkflow(workflow, workflow.schemas[workflow.output.schemaId]));
|
|
2247
2473
|
if (!validator.Check(output)) {
|
|
2248
2474
|
throw new WorkflowOutputInvalidError(`workflow "${workflow.name}" output does not satisfy schema "${workflow.output.schemaId}"`, schemaProblems(validator, output));
|
|
2249
2475
|
}
|
|
2250
|
-
return { status: "complete", state, output };
|
|
2476
|
+
return { status: "complete", state, output, ...(Object.keys(host).length ? { host } : {}) };
|
|
2251
2477
|
}
|
|
2252
2478
|
catch (error) {
|
|
2253
2479
|
if (error instanceof EscalationSignal)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@parcha/agentrun-dsl",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.3",
|
|
4
4
|
"description": "Composable, typed workflows for agents",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -23,7 +23,8 @@
|
|
|
23
23
|
"README.md",
|
|
24
24
|
"LICENSE",
|
|
25
25
|
"NOTICE",
|
|
26
|
-
"schema"
|
|
26
|
+
"schema",
|
|
27
|
+
"skills"
|
|
27
28
|
],
|
|
28
29
|
"engines": {
|
|
29
30
|
"node": ">=22.19.0"
|