@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,125 @@
|
|
|
1
|
+
{
|
|
2
|
+
"v": 2,
|
|
3
|
+
"name": "fictional-evidence-gate",
|
|
4
|
+
"schemas": {
|
|
5
|
+
"Record": {
|
|
6
|
+
"type": "object",
|
|
7
|
+
"additionalProperties": false,
|
|
8
|
+
"required": [
|
|
9
|
+
"claim",
|
|
10
|
+
"evidence"
|
|
11
|
+
],
|
|
12
|
+
"properties": {
|
|
13
|
+
"claim": {
|
|
14
|
+
"type": "string"
|
|
15
|
+
},
|
|
16
|
+
"evidence": {
|
|
17
|
+
"type": "string"
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
},
|
|
21
|
+
"Input": {
|
|
22
|
+
"type": "object",
|
|
23
|
+
"additionalProperties": false,
|
|
24
|
+
"required": [
|
|
25
|
+
"record"
|
|
26
|
+
],
|
|
27
|
+
"properties": {
|
|
28
|
+
"record": {
|
|
29
|
+
"$ref": "#/definitions/Record"
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
},
|
|
33
|
+
"Questions": {
|
|
34
|
+
"type": "object",
|
|
35
|
+
"additionalProperties": false,
|
|
36
|
+
"required": [
|
|
37
|
+
"supported"
|
|
38
|
+
],
|
|
39
|
+
"properties": {
|
|
40
|
+
"supported": {
|
|
41
|
+
"type": "boolean",
|
|
42
|
+
"description": "Does the supplied evidence explicitly support every factual detail in the claim, without adding assumptions or contradicting it?"
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
"Gate": {
|
|
47
|
+
"type": "object",
|
|
48
|
+
"additionalProperties": false,
|
|
49
|
+
"required": [
|
|
50
|
+
"accepted"
|
|
51
|
+
],
|
|
52
|
+
"properties": {
|
|
53
|
+
"accepted": {
|
|
54
|
+
"type": "boolean"
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
},
|
|
58
|
+
"Result": {
|
|
59
|
+
"type": "object",
|
|
60
|
+
"additionalProperties": false,
|
|
61
|
+
"required": [
|
|
62
|
+
"record",
|
|
63
|
+
"accepted"
|
|
64
|
+
],
|
|
65
|
+
"properties": {
|
|
66
|
+
"record": {
|
|
67
|
+
"$ref": "#/definitions/Record"
|
|
68
|
+
},
|
|
69
|
+
"accepted": {
|
|
70
|
+
"type": "boolean"
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
},
|
|
75
|
+
"input": {
|
|
76
|
+
"schemaId": "Input"
|
|
77
|
+
},
|
|
78
|
+
"output": {
|
|
79
|
+
"schemaId": "Result",
|
|
80
|
+
"path": "result"
|
|
81
|
+
},
|
|
82
|
+
"root": {
|
|
83
|
+
"node": "chain",
|
|
84
|
+
"steps": [
|
|
85
|
+
{
|
|
86
|
+
"node": "code",
|
|
87
|
+
"label": "retain-record",
|
|
88
|
+
"code": "(s) => ({ original: s.record })"
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
"node": "judge",
|
|
92
|
+
"label": "check-evidence",
|
|
93
|
+
"state": {
|
|
94
|
+
"record": "{original}"
|
|
95
|
+
},
|
|
96
|
+
"out": "Questions",
|
|
97
|
+
"as": "check"
|
|
98
|
+
},
|
|
99
|
+
{
|
|
100
|
+
"node": "code",
|
|
101
|
+
"label": "probability-gate",
|
|
102
|
+
"code": "(s) => { const p = s['check$answers']?.answers?.supported?.noul; return { accepted: typeof p === 'number' && Number.isFinite(p) && p >= 0.90 && p <= 1 }; }",
|
|
103
|
+
"as": "gate"
|
|
104
|
+
},
|
|
105
|
+
{
|
|
106
|
+
"node": "escalate",
|
|
107
|
+
"label": "request-better-evidence",
|
|
108
|
+
"when": {
|
|
109
|
+
"predicate": "field_equals",
|
|
110
|
+
"path": "gate.accepted",
|
|
111
|
+
"value": false
|
|
112
|
+
},
|
|
113
|
+
"kind": "needs_evidence",
|
|
114
|
+
"stage": "verification",
|
|
115
|
+
"summary": "Evidence did not meet the required yes-probability threshold."
|
|
116
|
+
},
|
|
117
|
+
{
|
|
118
|
+
"node": "code",
|
|
119
|
+
"label": "assemble-result",
|
|
120
|
+
"code": "(s) => ({ record: s.original, accepted: s.gate.accepted })",
|
|
121
|
+
"as": "result"
|
|
122
|
+
}
|
|
123
|
+
]
|
|
124
|
+
}
|
|
125
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{ "path": "README.md" }
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
{
|
|
2
|
+
"v": 2,
|
|
3
|
+
"name": "read-file",
|
|
4
|
+
"schemas": {
|
|
5
|
+
"Input": {
|
|
6
|
+
"type": "object",
|
|
7
|
+
"properties": { "path": { "type": "string", "minLength": 1 } },
|
|
8
|
+
"required": ["path"],
|
|
9
|
+
"additionalProperties": false
|
|
10
|
+
},
|
|
11
|
+
"ToolResult": {
|
|
12
|
+
"type": "object",
|
|
13
|
+
"properties": {
|
|
14
|
+
"content": {
|
|
15
|
+
"type": "array",
|
|
16
|
+
"items": {
|
|
17
|
+
"type": "object",
|
|
18
|
+
"properties": {
|
|
19
|
+
"type": { "type": "string", "enum": ["text", "image"] },
|
|
20
|
+
"text": { "type": "string" },
|
|
21
|
+
"data": { "type": "string" },
|
|
22
|
+
"mimeType": { "type": "string" }
|
|
23
|
+
},
|
|
24
|
+
"required": ["type"]
|
|
25
|
+
}
|
|
26
|
+
},
|
|
27
|
+
"details": {}
|
|
28
|
+
},
|
|
29
|
+
"required": ["content"]
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
"input": { "schemaId": "Input" },
|
|
33
|
+
"output": { "schemaId": "ToolResult", "path": "file" },
|
|
34
|
+
"root": {
|
|
35
|
+
"node": "call",
|
|
36
|
+
"label": "read-file",
|
|
37
|
+
"via": "tool",
|
|
38
|
+
"tool": "read",
|
|
39
|
+
"args": { "path": "{path}" },
|
|
40
|
+
"out": "ToolResult",
|
|
41
|
+
"as": "file",
|
|
42
|
+
"deadline_s": 10
|
|
43
|
+
}
|
|
44
|
+
}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
{
|
|
2
|
+
"v": 2,
|
|
3
|
+
"name": "fictional-read-source-decision",
|
|
4
|
+
"schemas": {
|
|
5
|
+
"Input": { "type": "object", "properties": {
|
|
6
|
+
"question": { "type": "string", "minLength": 1 },
|
|
7
|
+
"paths": { "type": "array", "items": { "type": "string", "minLength": 1 } }
|
|
8
|
+
}, "required": ["question", "paths"], "additionalProperties": false },
|
|
9
|
+
"ToolResult": { "type": "object", "properties": {
|
|
10
|
+
"content": { "type": "array", "items": { "type": "object", "properties": {
|
|
11
|
+
"type": { "const": "text" }, "text": { "type": "string" }
|
|
12
|
+
}, "required": ["type", "text"] } }, "details": {}
|
|
13
|
+
}, "required": ["content"] },
|
|
14
|
+
"Questions": { "type": "object", "properties": {
|
|
15
|
+
"matches": { "type": "boolean", "description": "Does the original source text satisfy the condition asked in question, taking account of its headings, scope and exclusions rather than keyword overlap?" }
|
|
16
|
+
}, "required": ["matches"], "additionalProperties": false },
|
|
17
|
+
"Results": { "type": "array", "items": { "type": "object", "properties": {
|
|
18
|
+
"path": { "type": "string" }, "source": { "$ref": "#/definitions/ToolResult" },
|
|
19
|
+
"probability": { "type": "number", "minimum": 0, "maximum": 1 }
|
|
20
|
+
}, "required": ["path", "source", "probability"], "additionalProperties": false } }
|
|
21
|
+
},
|
|
22
|
+
"input": { "schemaId": "Input" },
|
|
23
|
+
"output": { "schemaId": "Results", "path": "results" },
|
|
24
|
+
"root": {
|
|
25
|
+
"node": "map", "label": "read-and-judge-originals", "itemsPath": "paths", "maxConcurrency": 2,
|
|
26
|
+
"as": "results", "resultPath": "record",
|
|
27
|
+
"body": { "node": "chain", "steps": [
|
|
28
|
+
{ "node": "call", "label": "read-original", "via": "tool", "tool": "read",
|
|
29
|
+
"args": { "path": "{item}" }, "out": "ToolResult", "as": "source", "deadline_s": 30 },
|
|
30
|
+
{ "node": "judge", "label": "source-membership", "state": {
|
|
31
|
+
"question": "{question}", "source": "{source}"
|
|
32
|
+
}, "out": "Questions", "as": "decision" },
|
|
33
|
+
{ "node": "code", "label": "retain-source-and-probability", "as": "record",
|
|
34
|
+
"code": "(s) => ({ path: s.item, source: s.source, probability: s['decision$answers'].answers.matches.noul })" }
|
|
35
|
+
] }
|
|
36
|
+
}
|
|
37
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
FICTIONAL EXAMPLE — not a real product release
|
|
2
|
+
|
|
3
|
+
# Current release
|
|
4
|
+
|
|
5
|
+
Clients MUST send the X-Workspace header with their workspace slug.
|
|
6
|
+
|
|
7
|
+
# Future proposals — not approved
|
|
8
|
+
|
|
9
|
+
Changing the authentication mechanism remains a proposal. No authentication
|
|
10
|
+
migration is required by this release.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
{
|
|
2
|
+
"v": 2,
|
|
3
|
+
"name": "review-release-notes",
|
|
4
|
+
"schemas": {
|
|
5
|
+
"Input": {
|
|
6
|
+
"type": "object",
|
|
7
|
+
"properties": {
|
|
8
|
+
"notes": {
|
|
9
|
+
"type": "array",
|
|
10
|
+
"items": {
|
|
11
|
+
"type": "string",
|
|
12
|
+
"minLength": 1
|
|
13
|
+
},
|
|
14
|
+
"minItems": 1,
|
|
15
|
+
"maxItems": 5
|
|
16
|
+
}
|
|
17
|
+
},
|
|
18
|
+
"required": [
|
|
19
|
+
"notes"
|
|
20
|
+
],
|
|
21
|
+
"additionalProperties": false
|
|
22
|
+
},
|
|
23
|
+
"Change": {
|
|
24
|
+
"type": "object",
|
|
25
|
+
"properties": {
|
|
26
|
+
"breakingChange": {
|
|
27
|
+
"type": "string",
|
|
28
|
+
"minLength": 1
|
|
29
|
+
},
|
|
30
|
+
"migrationAction": {
|
|
31
|
+
"type": "string",
|
|
32
|
+
"minLength": 1
|
|
33
|
+
}
|
|
34
|
+
},
|
|
35
|
+
"required": [
|
|
36
|
+
"breakingChange",
|
|
37
|
+
"migrationAction"
|
|
38
|
+
],
|
|
39
|
+
"additionalProperties": false
|
|
40
|
+
},
|
|
41
|
+
"Report": {
|
|
42
|
+
"type": "object",
|
|
43
|
+
"properties": {
|
|
44
|
+
"summary": {
|
|
45
|
+
"type": "string",
|
|
46
|
+
"minLength": 1
|
|
47
|
+
},
|
|
48
|
+
"changes": {
|
|
49
|
+
"type": "array",
|
|
50
|
+
"items": {
|
|
51
|
+
"type": "object",
|
|
52
|
+
"properties": {
|
|
53
|
+
"breakingChange": {
|
|
54
|
+
"type": "string",
|
|
55
|
+
"minLength": 1
|
|
56
|
+
},
|
|
57
|
+
"migrationAction": {
|
|
58
|
+
"type": "string",
|
|
59
|
+
"minLength": 1
|
|
60
|
+
}
|
|
61
|
+
},
|
|
62
|
+
"required": [
|
|
63
|
+
"breakingChange",
|
|
64
|
+
"migrationAction"
|
|
65
|
+
],
|
|
66
|
+
"additionalProperties": false
|
|
67
|
+
},
|
|
68
|
+
"minItems": 1
|
|
69
|
+
}
|
|
70
|
+
},
|
|
71
|
+
"required": [
|
|
72
|
+
"summary",
|
|
73
|
+
"changes"
|
|
74
|
+
],
|
|
75
|
+
"additionalProperties": false
|
|
76
|
+
}
|
|
77
|
+
},
|
|
78
|
+
"input": {
|
|
79
|
+
"schemaId": "Input"
|
|
80
|
+
},
|
|
81
|
+
"output": {
|
|
82
|
+
"schemaId": "Report",
|
|
83
|
+
"path": "report"
|
|
84
|
+
},
|
|
85
|
+
"root": {
|
|
86
|
+
"node": "chain",
|
|
87
|
+
"steps": [
|
|
88
|
+
{
|
|
89
|
+
"node": "map",
|
|
90
|
+
"label": "extract-each-release-note",
|
|
91
|
+
"itemsPath": "notes",
|
|
92
|
+
"as": "changes",
|
|
93
|
+
"maxConcurrency": 2,
|
|
94
|
+
"body": {
|
|
95
|
+
"node": "extract",
|
|
96
|
+
"label": "extract-change",
|
|
97
|
+
"instructions": "Extract the breaking change and its migration action from the supplied release note. Preserve the exact header name and required action. Do not invent a migration step.",
|
|
98
|
+
"state": {
|
|
99
|
+
"text": "{item}"
|
|
100
|
+
},
|
|
101
|
+
"requires": [
|
|
102
|
+
"item"
|
|
103
|
+
],
|
|
104
|
+
"out": "Change",
|
|
105
|
+
"as": "change"
|
|
106
|
+
}
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
"node": "extract",
|
|
110
|
+
"label": "summarize-migration",
|
|
111
|
+
"instructions": "Summarize these migration actions for a client maintainer. Return the supplied changes unchanged alongside the summary. Do not invent steps.",
|
|
112
|
+
"state": {
|
|
113
|
+
"changes": "{changes}"
|
|
114
|
+
},
|
|
115
|
+
"requires": [
|
|
116
|
+
"changes"
|
|
117
|
+
],
|
|
118
|
+
"out": "Report",
|
|
119
|
+
"as": "report"
|
|
120
|
+
}
|
|
121
|
+
]
|
|
122
|
+
}
|
|
123
|
+
}
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
# Design Jev decisions in AgentRun
|
|
2
|
+
|
|
3
|
+
Jev returns typed judgments and probabilities, not generated prose, tool calls or
|
|
4
|
+
multi-step research. The host supplies its adapter and credentials; the workflow
|
|
5
|
+
names the question. Do not write
|
|
6
|
+
HTTP requests or SDK setup into workflow code. This guide maps the TypeSafe
|
|
7
|
+
programming model to the installed DSL; the general TypeSafe skill is optional.
|
|
8
|
+
|
|
9
|
+
## Choose the boundary
|
|
10
|
+
|
|
11
|
+
Work backward from the action the result controls. Code handles exact lookups,
|
|
12
|
+
parsing, arithmetic, joins, grouping and constraints. An agent handles open-ended
|
|
13
|
+
research or generation. Jev can select relevant evidence, interpret a boundary,
|
|
14
|
+
compare a claim to its source or choose among known actions. It need not be a
|
|
15
|
+
final approval stage, and a workflow without a semantic decision need not use it.
|
|
16
|
+
|
|
17
|
+
Ask one coherent judgment per property. Separate independently useful conditions;
|
|
18
|
+
keep related context together. Avoid asking whether a whole complex answer is
|
|
19
|
+
"correct" when no source supporting that answer is supplied. Question descriptions
|
|
20
|
+
must carry their meaning; property names alone are not instructions.
|
|
21
|
+
|
|
22
|
+
## Construct the evidence, not another opinion
|
|
23
|
+
|
|
24
|
+
For source-grounded work, a useful pattern is:
|
|
25
|
+
|
|
26
|
+
1. A tool or agent locates candidate references, retaining their identities.
|
|
27
|
+
2. Direct tool calls fetch the original text at those references.
|
|
28
|
+
3. Jev sees the question or full selection rule **and that original text**.
|
|
29
|
+
4. Code uses the returned values; an agent may repair missing evidence or synthesize.
|
|
30
|
+
|
|
31
|
+
Keep source text separate from a candidate extraction, paraphrase or claim. An
|
|
32
|
+
agent's field named `quote`, `headerContext` or `verified` does not make it original
|
|
33
|
+
evidence. Re-read the cited source through the host tool when independent checking
|
|
34
|
+
matters. Include relevant headings, units, dates, neighboring rows, exclusions and
|
|
35
|
+
section boundaries. An exact quote match checks presence, not interpretation.
|
|
36
|
+
|
|
37
|
+
Judge only what the supplied context can establish. If a source is truncated,
|
|
38
|
+
follow its continuation when relevant; if it is missing, retrieve or surface the
|
|
39
|
+
gap. Do not silently substitute a summary to fit a size limit. Narrow or partition
|
|
40
|
+
large contexts at meaningful boundaries while retaining their qualifiers.
|
|
41
|
+
The adapter has no default byte ceiling. A host may explicitly configure
|
|
42
|
+
`maxStateBytes`; local size errors then report the measured UTF-8 JSON bytes and
|
|
43
|
+
that host's limit before any HTTP request is sent. Provider context limits are
|
|
44
|
+
separate and token-based, not a fixed bytes-to-tokens conversion. Jev 1.13's
|
|
45
|
+
documented contract, checked on 2026-09-22, allows 32k tokens for state plus the
|
|
46
|
+
longest question and 64k for state plus all questions combined; check the selected
|
|
47
|
+
model's current contract. Oversized provider requests remain
|
|
48
|
+
errors, not permission to truncate evidence or silently retry a different graph.
|
|
49
|
+
|
|
50
|
+
`sift` sends its items together, in as few requests as the host's limits allow:
|
|
51
|
+
when the items exceed `maxQuestionsPerRequest` or the host's
|
|
52
|
+
`maxStateBytesPerRequest`, it splits them in order into requests that each fit.
|
|
53
|
+
Shared `state` is added to every request; it does not replace or narrow each item.
|
|
54
|
+
`describe` adds an item summary, but the full original item is still sent. A tool envelope can contain
|
|
55
|
+
the same text in both `content` and `details`, so character limits on individual
|
|
56
|
+
reads do not establish the final serialized size.
|
|
57
|
+
|
|
58
|
+
When judgments are independent, explicitly use `map` with a `judge` body for one
|
|
59
|
+
request per original. For records that already contain `document`, `page` and
|
|
60
|
+
`text`, a body can use `state: {rule: "{question}", original: "{item}"}`. For tool
|
|
61
|
+
envelopes, select the host's actual original-text and provenance fields instead
|
|
62
|
+
of sending duplicate representations. Retain the full reviewed rule, relevant
|
|
63
|
+
headers, units, dates, exclusions and neighboring rows. If an individual original
|
|
64
|
+
is still too large, retrieve or partition it at meaningful boundaries; do not
|
|
65
|
+
silently truncate it or replace it with an agent's interpretation. This explicit
|
|
66
|
+
graph change changes request count; nothing is truncated.
|
|
67
|
+
|
|
68
|
+
The fictional [read-source decision](../examples/read-source-decision.json) and
|
|
69
|
+
[input](../examples/read-source-decision.input.json) show direct tool results passed
|
|
70
|
+
to a judge unchanged, followed by deterministic probability projection in code. Its
|
|
71
|
+
paths are inputs, not a built-in corpus: place the bundled fictional
|
|
72
|
+
[release note](../examples/release-note.txt) in the working directory before running
|
|
73
|
+
that input. Adapt the tool and its
|
|
74
|
+
return schema to the tools the host actually names; an agent locator can produce the
|
|
75
|
+
references earlier in the same graph.
|
|
76
|
+
|
|
77
|
+
## Use the installed primitives
|
|
78
|
+
|
|
79
|
+
- `judge`: a flat output schema describes several independent questions over one
|
|
80
|
+
explicit `state` map. Boolean properties become yes-probabilities (Noul); enums
|
|
81
|
+
become Choice; integer properties with minimum 0, maximum N−1 and N described
|
|
82
|
+
levels in `criteria` (2–10 levels) become Score. Put the complete question in each
|
|
83
|
+
`description`.
|
|
84
|
+
- `sift`: ask questions about each candidate and retain originals. Pass shared task
|
|
85
|
+
context in `state`; each item also needs its own original evidence. Candidate
|
|
86
|
+
coverage matters: no judge can recover a source absent from the candidate set.
|
|
87
|
+
- `pick`: choose from known candidates, with `allowNone` when none may fit.
|
|
88
|
+
- `route`: run one of several branches. With `instructions` and `state`, Jev
|
|
89
|
+
chooses a semantic branch, and its `unsure` gate concerns that new decision, not
|
|
90
|
+
an earlier judge's probability. With `valuePath`, the workflow already holds the
|
|
91
|
+
choice and no question is asked.
|
|
92
|
+
|
|
93
|
+
Route by value when the decision exists. A common shape: a `judge` answers the
|
|
94
|
+
question, a `code` step applies your thresholds to its raw probabilities and
|
|
95
|
+
writes an action string, and a `route` with `valuePath` runs that action's branch.
|
|
96
|
+
Asking a second `route` instead costs another request and can choose differently
|
|
97
|
+
from the judge, past your thresholds. Use Jev where the answer needs judgment and
|
|
98
|
+
code where it is certain from the data: exact matches, lookups, arithmetic and a
|
|
99
|
+
threshold already decided.
|
|
100
|
+
|
|
101
|
+
Batch independent questions over the same state. They cannot read each other's
|
|
102
|
+
answers. Use another step when a decision is needed to retrieve new evidence or
|
|
103
|
+
construct new state. Inspect the assembled state and questions, not just node names.
|
|
104
|
+
|
|
105
|
+
## Consume uncertainty honestly
|
|
106
|
+
|
|
107
|
+
`judge` stores decoded values at its `as` key and raw answers at `<as>$answers`.
|
|
108
|
+
A boolean is true at yes-probability 0.5; to enforce another threshold, read the
|
|
109
|
+
raw `.answers.<property>.noul` number and compare in code. A Noul near 0.5 means
|
|
110
|
+
uncertainty between yes and no, not medium intensity. Choice/Score confidence is
|
|
111
|
+
distribution concentration, not proof that the workflow is right.
|
|
112
|
+
|
|
113
|
+
Use thresholds appropriate to the task, with an explicit missing/uncertain path.
|
|
114
|
+
An example threshold is not calibrated policy. Low probability can justify
|
|
115
|
+
exclusion, another retrieval, cheap-agent repair or escalation, depending on the
|
|
116
|
+
question. Do not reject an entire result just because an unused condition is
|
|
117
|
+
uncertain. Preserve raw decisions so these policies can be inspected separately.
|
|
118
|
+
|
|
119
|
+
Typed output proves an interface, not truth. Test source coverage, semantics and
|
|
120
|
+
the downstream action independently. A fake-judge fixture proves wiring only.
|
|
121
|
+
|
|
122
|
+
Maintained against TypeSafe's state, primitives/Noul, confidence and citation-check
|
|
123
|
+
documentation, reviewed 2026-09-22. Upstream reference locations:
|
|
124
|
+
`https://docs.typesafe.ai/concepts/state`, `https://docs.typesafe.ai/primitives`,
|
|
125
|
+
`https://docs.typesafe.ai/confidence`, `https://docs.typesafe.ai/cookbooks/citation_check`.
|
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
<!-- Generated from packages/dsl/src/author.ts by node scripts/generate-author-contract.mjs. Do not edit. -->
|
|
2
|
+
|
|
3
|
+
# AgentRun workflow language
|
|
4
|
+
|
|
5
|
+
You author AgentRun workflows: JSON documents the AgentRun interpreter runs.
|
|
6
|
+
Deliver the complete JSON document the way your host asks; never deliver prose, a file name or a fragment. Make the smallest workflow that satisfies the request. A candidate runs nothing until its host accepts it, and an accepted candidate is not activated by acceptance.
|
|
7
|
+
|
|
8
|
+
## Document
|
|
9
|
+
|
|
10
|
+
A workflow is {"v":2,"name","schemas","input"?,"output","root"}.
|
|
11
|
+
- `schemas` maps ids to inline JSON Schema objects. Every schema id a node, `input` or `output` names must exist there. Inside a schema, reference a catalog schema or an inline definition only as {"$ref":"#/definitions/<id>"}.
|
|
12
|
+
- The input contract: the run starts from the input object and nothing else. `input.schemaId`, when present, is enforced before the first node. A node may read only input keys and keys an earlier node wrote.
|
|
13
|
+
- `output.schemaId` validates the final value; `output.path` selects it from state and must name an input key or a key an earlier node wrote.
|
|
14
|
+
- State is one object. Each step writes its result under one key: its `as`, or, for an agent, decide, extract or code node without `as`, its label. A report writes `report_markdown`. A code node without `as` that returns an object merges that object's top-level fields instead.
|
|
15
|
+
- Keys that begin with `$` are engine-owned: `$host` (host state), `<as>$answers` (raw judge answers and confidences) and `<as>$verify` (verifier results). Read them; never write one. No `as` may begin with `$`, and neither may the label of an agent, decide, extract or code node without `as`.
|
|
16
|
+
- `{dot.path}` placeholders are replaced from state in `state` maps (including `verify.state` and `ask.state`), call `args`, `input`, `env` and `produces`, a child workflow's `input`, and `escalate.summary`; `pick` and `sift` `describe` templates also see `{item...}`. A placeholder that is the whole string keeps its value's type. Every key a state map, call or child input interpolates must be produced upstream. `instructions`, `code` and `command` are literal and never interpolated.
|
|
17
|
+
|
|
18
|
+
## Node kinds
|
|
19
|
+
|
|
20
|
+
This is the complete set. Each kind accepts exactly these fields; any other field is an error.
|
|
21
|
+
- `chain`: `steps`
|
|
22
|
+
- `code`: `label`, `code`, `as`
|
|
23
|
+
- `agent`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`, `budget_usd`, `context`
|
|
24
|
+
- `decide`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
|
|
25
|
+
- `extract`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
|
|
26
|
+
- `report`: `label`, `state`, `instructions`, `sopSection`, `requires`, `tools`, `effort`, `thinking`
|
|
27
|
+
- `artifact`: `label`, `state`, `type`, `path`, `instructions`, `sopSection`, `requires`, `tools`, `effort`, `thinking`
|
|
28
|
+
- `map`: `label`, `itemsPath`, `body`, `as`, `resultPath`, `maxConcurrency`, `onItemFailure`, `failedAs`
|
|
29
|
+
- `parallel`: `label`, `branches`
|
|
30
|
+
- `loop`: `label`, `body`, `until`, `maxIters`, `expect_iters`
|
|
31
|
+
- `escalate`: `label`, `when`, `kind`, `stage`, `summary`
|
|
32
|
+
- `call`: `label`, `via`, `tool`, `args`, `code`, `input`, `command`, `env`, `where`, `out`, `as`, `produces`, `deadline_s`, `retry`, `poll`, `requires`
|
|
33
|
+
- `workflow`: `label`, `workflow`, `input`, `out`, `as`
|
|
34
|
+
- `judge`: `label`, `state`, `out`, `as`, `requires`
|
|
35
|
+
- `pick`: `label`, `itemsPath`, `describe`, `instructions`, `state`, `allowNone`, `as`, `requires`
|
|
36
|
+
- `sift`: `label`, `itemsPath`, `describe`, `state`, `out`, `as`, `keep`, `requires`
|
|
37
|
+
- `route`: `label`, `state`, `instructions`, `branches`, `unsure`, `valuePath`, `otherwise`, `as`, `requires`
|
|
38
|
+
|
|
39
|
+
Every kind also accepts `metadata`, an object the host owns and the engine never reads; set only the keys the host addendum names.
|
|
40
|
+
|
|
41
|
+
### Generative nodes: agent, decide, extract, report
|
|
42
|
+
|
|
43
|
+
Each runs one adapter session. A kind is a preset (its duty, default effort and model tier), not a capability limit:
|
|
44
|
+
- `extract` transcribes facts already present in its input into `out`: faithfully, null for an absent field, nothing invented, no judgment.
|
|
45
|
+
- `decide` judges what is already in state.
|
|
46
|
+
- `agent` gathers new evidence with its tools.
|
|
47
|
+
- `report` renders the final record as the deliverable prose. It has no `out` or `as`: it writes `report_markdown`.
|
|
48
|
+
|
|
49
|
+
Their fields:
|
|
50
|
+
- `instructions` (required, non-empty) states the node's duty as literal prose. The node receives `state` (an interpolated map) or, without it, the accumulated state as its JSON input; refer to keys by name.
|
|
51
|
+
- `out` names the schema the submission must satisfy; the value lands at `as`.
|
|
52
|
+
- `requires` lists state paths that must hold evidence before the node runs, each produced upstream: missing values, null, blank strings, empty arrays and empty objects stop the run; `false` and `0` pass.
|
|
53
|
+
- `tools` names tools the host offers. `[]` means no tools; omitting `tools` offers every tool the host allows. Never name a tool the host did not offer.
|
|
54
|
+
- `effort` is minimal|low|medium|high; `thinking` is low|medium|high (never off); `tier` is fast|default|strong. They are requests to the host: resource ceilings are the host's. A node that names no `thinking` thinks at medium, unless its host sets another level.
|
|
55
|
+
- An `agent` node may carry `budget_usd`, the most it asks to spend in dollars (above 0), which the host caps by what it has left, and `context`, fresh|fork: `fresh` (the default) sees only its instructions and state; `fork` asks the host to start it from the caller's transcript, which a host refuses where it has none.
|
|
56
|
+
- `sopSection` names one heading of the host's SOP, or a list of them, as the exact text after "## ". The node receives those sections verbatim.
|
|
57
|
+
- `verify` reviews a submission before it is accepted: {"out": a question schema with at least one boolean question, "state"?, "maxDrives"?: an integer >= 1 (default 2, no maximum), "override"?: {"below": a number in (0, 1), default 0.3}}. A boolean question named after a submission field doubts that field when its yes-probability is below `override.below`; any other boolean question is a requirement met at 0.5. A rejected submission returns to the same session with the reasons.
|
|
58
|
+
- When the workflow has a report, no decide or extract `out` schema carries `report_markdown`.
|
|
59
|
+
|
|
60
|
+
### Terminal nodes: report and artifact
|
|
61
|
+
|
|
62
|
+
A workflow has at most one terminal node, a `report` or an `artifact`, and it is the last step of the root chain. No terminal node sits inside a map, loop, parallel branch, route branch or child workflow.
|
|
63
|
+
- An `artifact` of type `markdown` or `report` is the report writer: give it the report's fields.
|
|
64
|
+
- Any other `artifact` type names a file: `path` is the workspace-relative file an earlier shell call declared in `produces`, and the node has no model fields (`instructions`, `state`, `sopSection`, `tools`, `effort`, `thinking`).
|
|
65
|
+
|
|
66
|
+
### Judgment nodes: judge, pick, sift, route
|
|
67
|
+
|
|
68
|
+
Typed questions answered by the host's judge in one request each: no tools, no session, no `sopSection`.
|
|
69
|
+
- A question schema is a flat object. Each property's `description` is its question. A boolean yields a yes-probability; a string enum (at most 240 options, optional per-option `criteria`) yields a choice; an integer with `criteria`: [level descriptions] (2 to 10 levels, minimum 0, maximum the last level index) yields a score. Nothing else is a question.
|
|
70
|
+
- `judge`: a non-empty `state` map, `out` (a question schema) and `as`. The decoded value lands at `as`, the raw answers at `<as>$answers`.
|
|
71
|
+
- `pick`: `itemsPath`, `describe` (the option text per item, such as "{item.name}"), `instructions` (the one question) and `as`; `allowNone` adds a none-of-these option. The result is {index, item, none, option}.
|
|
72
|
+
- `sift`: `itemsPath`, `out` (a question schema asked of every item; the host splits the items across requests when they exceed its limits) and `as`. `keep` {path: a question id or <id>.confidence, never a choice, gte?} keeps passing items, in order, at `<as>.items`.
|
|
73
|
+
- `route` runs one of 2 or more named `branches`. Jev chooses: a non-empty `state` map, `instructions` (the one question) and up to 240 branches, each {criteria?, body}; `unsure` {branch, gte: a number in (0, 1]} takes that branch when the choice's confidence is below `gte`. Or the workflow already holds the choice: `valuePath` names the state string that is the branch, each branch is {body}, no question is asked, and `otherwise` (a branch) takes a missing or unknown name, which otherwise fails; a non-string fails. `as` records the choice.
|
|
74
|
+
- A decoded boolean is true at yes-probability 0.5. To hold a different threshold, read `<as>$answers.answers.<id>.noul` in a code node.
|
|
75
|
+
|
|
76
|
+
### Control nodes
|
|
77
|
+
|
|
78
|
+
- `chain`: non-empty `steps`, run in order.
|
|
79
|
+
- `map`: `itemsPath` (an upstream list), `body` and `as`. The body sees `item` and `item_index`; `maxConcurrency` is a positive integer (default 4); `resultPath` selects one path from each completed item's state. Without `resultPath`, and with no `as` in the body, each item's result is its whole state, the mapped list included: set `resultPath` (or an `as` in the body) for a large map; the validator warns. `onItemFailure` is `stop` (default: the first failing item stops the map and the run) or `collect`. With `collect`, an item whose node fails (a call that failed after its retries, an agent that delivered no record, output that does not match its schema, a failed check) ends as {item_index, label, code, message} in the list at `failedAs`, the other items finish, and `as` stays aligned with the items: `as[i]` is item i's result, or `null` when item i failed. Filter the nulls explicitly if only successes are wanted. Gate on `failedAs` with `escalate` or a code node; never let failures pass silently. A crash, a cancel, an `escalate` inside the item or an effect whose outcome is unknown is never collected.
|
|
80
|
+
- `parallel`: at least two `branches`, each starting from the state before the parallel node. Branches write disjoint keys and never read a sibling's writes.
|
|
81
|
+
- `loop`: `body`, `until` (a predicate) and an integer `maxIters` of at least 1 (no maximum), optionally an integer `expect_iters` of at least 1 (priced passes). At the bound the state passes through with `until` unmet; follow the loop with an escalate or gate on that condition.
|
|
82
|
+
- `escalate`: `when` (a predicate), and non-empty `kind`, `stage` and `summary`. When the predicate holds the run stops without output and returns the escalation with its interpolated summary.
|
|
83
|
+
- `workflow`: `label`, `workflow` (a complete inline child), `input` (an object, interpolated, the child's entire initial state), `out` (a parent schema checked against the child's output) and `as`. The child declares `input.schemaId` in its own schemas and contains no report or artifact.
|
|
84
|
+
- `code`: `code` is one synchronous function expression such as "(s) => ({ total: s.items.length })". It receives the full state; return new values and never mutate it. `Date`, `Promise`, timers, `fetch`, `require`, `process`, `Function` and `globalThis` are unavailable. It is trusted host JavaScript, not a sandbox. Use code for typed-state mechanics, never to read meaning from prose.
|
|
85
|
+
- `call`: one side effect with no model in the loop. `via` is tool|executor|shell; `as` and `deadline_s` (a finite number greater than 0, no maximum) are required — an unbounded effect is how a stalled provider becomes a stalled job.
|
|
86
|
+
- `via: tool` takes `tool` (a host tool address), `args` (an object) and `out` (the tool's result schema).
|
|
87
|
+
- `via: executor` takes `code` (a body that returns its JSON result and uses only `tools` and `input`), `input` and `out`.
|
|
88
|
+
- `via: shell` takes `command` (literal) and `env` (UPPER_CASE names to strings, interpolated by value; the way long values reach a command). Its result has the fixed shape {code, stdout, stderr, truncated?}: no `out`. Only a shell call may declare `produces` (workspace-relative files, checked after the effect).
|
|
89
|
+
- `retry` {attempts: an integer >= 1, backoff_s?: a number >= 0, on?: [timeout, http_5xx, http_429, connection, exit, 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]}. `where` accepts only "sandbox".
|
|
90
|
+
- `poll` {until, fail_when?, interval_s: >= 0.1 (a busy-loop guard), deadline_s: at least the call's deadline_s (no maximum)} repeats the call until `until` holds on its own result; `fail_when` fails it at once. Both are mechanical predicates whose paths are relative to the result and lie in its declared shape.
|
|
91
|
+
- Validation and dry runs never perform effects: they synthesize the declared result, and a shell result's stdout is "{}".
|
|
92
|
+
|
|
93
|
+
## Predicates
|
|
94
|
+
|
|
95
|
+
`loop.until` and `escalate.when` take one of these; `poll` takes only the first 8. Each path or key reads a state value an input or an earlier node produced.
|
|
96
|
+
A predicate is one JSON object that names itself in its `predicate` field beside its own fields, for example `{"predicate": "field_true", "path": "review.approved"}`.
|
|
97
|
+
- `field_equals` {path, value}: holds when the value at `path` equals `value` (a string, number or boolean)
|
|
98
|
+
- `field_true` {path}: holds when the value at `path` is `true`
|
|
99
|
+
- `in` {path, values}: holds when the value at `path` is one of `values` (a non-empty list of strings, numbers or booleans)
|
|
100
|
+
- `count_gte` {path, n}: holds when the array (or number) at `path` has at least `n` items
|
|
101
|
+
- `gte` {path, n}: holds when the finite number at `path` is at least `n`
|
|
102
|
+
- `lt` {path, n}: holds when the finite number at `path` is below `n`
|
|
103
|
+
- `empty` {path}: holds when the value at `path` is an empty array, an empty string, null or absent
|
|
104
|
+
- `no_new_items` {key}: takes `key`, not `path`; holds when that state key is an empty array or falsy
|
|
105
|
+
- `ask` {instructions, state, criteria, gte}: a yes/no question for the host's judge: `instructions` is the question, `state` what it sees (default: the whole state), `criteria` optional {true, false} descriptions; holds when the yes-probability is at least `gte` (in (0.5, 1], default 0.6)
|
|
106
|
+
|
|
107
|
+
## Authority
|
|
108
|
+
|
|
109
|
+
- Use only tools the host names. Never invent a tool, capability, evidence source or successful check.
|
|
110
|
+
- Code, call and artifact nodes need the host's explicit authorization for executable candidates.
|
|
111
|
+
- When the host supplies rubric sections, they are authoritative source text: every generative node's `sopSection` lists all of them, a merged judgment inherits the union of its parents' sections, and policy is never paraphrased into instructions. Judgment nodes, `ask` predicates and `verify` clauses are then refused until the host reviews a separate question contract.
|
|
112
|
+
- Acceptance checks are the host's. Never change a check, fixture or threshold to pass.
|
|
113
|
+
- Bound loops and parallelism. Uncertainty escalates or takes an explicit fallback such as `route.unsure` or a threshold gate.
|
|
114
|
+
- Ask Jev only what needs judgment; compute what is certain in code. Once a judge and code have decided, route by `valuePath`: asking a route again can contradict that decision.
|
|
115
|
+
|
|
116
|
+
## Example
|
|
117
|
+
|
|
118
|
+
{"v":2,"name":"summarize","schemas":{"Input":{"type":"object","properties":{"text":{"type":"string","minLength":1}},"required":["text"],"additionalProperties":false},"Result":{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"],"additionalProperties":false}},"input":{"schemaId":"Input"},"output":{"schemaId":"Result","path":"result"},"root":{"node":"extract","label":"summarize","instructions":"Summarize the text field faithfully. Invent nothing.","out":"Result","as":"result","requires":["text"],"tools":[]}}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# The SDK authoring path
|
|
2
|
+
|
|
3
|
+
Use this path when the host calls `authorWorkflow` from `@parcha/agentrun-dsl` rather than exposing the `agentrun` tool. The host supplies its own `runNode` adapter; the author asks it for one session with no tools and a `submit` tool. Deliver each candidate as the submit tool's value. Read validation and acceptance feedback, then repair within that session. The host retains each version and rejection. Acceptance does not activate or execute a replacement.
|
|
4
|
+
|
|
5
|
+
The session's system text is the [language reference](language.md) followed by the host's addendum, when the host supplies one. The addendum names the host's initial state, output types, node kinds and rules. Candidates using a node kind or artifact type outside a declared addendum are refused before validation.
|
|
6
|
+
|
|
7
|
+
With `rubricSections`, every generated LLM node must reference every supplied section, including child workflows. This conservative author policy rejects Jev nodes, semantic `ask` predicates, and `verify` clauses until the host has a separately reviewed question contract. Execution must receive the same authoritative SOP text. A schema field named `node`, `verify`, or `predicate` is ordinary data, not a judgment clause.
|
|
8
|
+
|
|
9
|
+
Host-owned acceptance callbacks and fixtures remain outside generated workflows. Do not edit them to obtain a pass. Structural acceptance alone does not establish behavior. Keep request text, rubric text, candidates, and reviews in storage appropriate for their contents.
|
|
10
|
+
|
|
11
|
+
A host that ships a workflow with the input it runs on exports a `Job` (`{ workflow, input, files? }`, files as bytes by path); `defineJob(job)` returns its argument and keeps the workflow's literal type, so `export const workflow = {...} as const satisfies Workflow` and `export default defineJob({ workflow, input })` compile together.
|