@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.
Files changed (102) hide show
  1. package/README.md +46 -16
  2. package/dist/author.d.ts +96 -0
  3. package/dist/author.js +320 -0
  4. package/dist/authoring.js +1 -1
  5. package/dist/cli.js +8 -3
  6. package/dist/code-exec.d.ts +6 -0
  7. package/dist/code-exec.js +126 -0
  8. package/dist/decision-receipts.d.ts +98 -0
  9. package/dist/decision-receipts.js +51 -0
  10. package/dist/dry-run.d.ts +14 -1
  11. package/dist/dry-run.js +39 -13
  12. package/dist/graph.d.ts +83 -0
  13. package/dist/graph.js +231 -0
  14. package/dist/index.d.ts +12 -4
  15. package/dist/index.js +6 -2
  16. package/dist/inspection.js +2 -2
  17. package/dist/job.d.ts +14 -0
  18. package/dist/job.js +5 -0
  19. package/dist/long-timer.d.ts +7 -0
  20. package/dist/long-timer.js +22 -0
  21. package/dist/observer-snapshot.d.ts +3 -0
  22. package/dist/observer-snapshot.js +46 -0
  23. package/dist/predicates.d.ts +4 -0
  24. package/dist/predicates.js +19 -2
  25. package/dist/recovery/binding.d.ts +10 -0
  26. package/dist/recovery/binding.js +43 -0
  27. package/dist/recovery/call-key.d.ts +13 -0
  28. package/dist/recovery/call-key.js +24 -0
  29. package/dist/recovery/canonical-hash.d.ts +7 -0
  30. package/dist/recovery/canonical-hash.js +22 -0
  31. package/dist/recovery/driver.d.ts +208 -0
  32. package/dist/recovery/driver.js +1222 -0
  33. package/dist/recovery/effect-failure.d.ts +34 -0
  34. package/dist/recovery/effect-failure.js +62 -0
  35. package/dist/recovery/errors.d.ts +31 -0
  36. package/dist/recovery/errors.js +51 -0
  37. package/dist/recovery/execution-path.d.ts +53 -0
  38. package/dist/recovery/execution-path.js +167 -0
  39. package/dist/recovery/file-store.d.ts +7 -0
  40. package/dist/recovery/file-store.js +131 -0
  41. package/dist/recovery/frozen-snapshot.d.ts +244 -0
  42. package/dist/recovery/frozen-snapshot.js +171 -0
  43. package/dist/recovery/handoff-block.d.ts +36 -0
  44. package/dist/recovery/handoff-block.js +148 -0
  45. package/dist/recovery/handoff-digest.d.ts +58 -0
  46. package/dist/recovery/handoff-digest.js +195 -0
  47. package/dist/recovery/handoff-files.d.ts +54 -0
  48. package/dist/recovery/handoff-files.js +162 -0
  49. package/dist/recovery/handoff-receipts.d.ts +42 -0
  50. package/dist/recovery/handoff-receipts.js +53 -0
  51. package/dist/recovery/handoff-redact.d.ts +12 -0
  52. package/dist/recovery/handoff-redact.js +44 -0
  53. package/dist/recovery/handoff.d.ts +44 -0
  54. package/dist/recovery/handoff.js +46 -0
  55. package/dist/recovery/index.d.ts +18 -0
  56. package/dist/recovery/index.js +16 -0
  57. package/dist/recovery/item-state.d.ts +48 -0
  58. package/dist/recovery/item-state.js +89 -0
  59. package/dist/recovery/journal.d.ts +28 -0
  60. package/dist/recovery/journal.js +139 -0
  61. package/dist/recovery/memory-store.d.ts +4 -0
  62. package/dist/recovery/memory-store.js +20 -0
  63. package/dist/recovery/store.d.ts +105 -0
  64. package/dist/recovery/store.js +6 -0
  65. package/dist/recovery/testing/conformance.d.ts +4 -0
  66. package/dist/recovery/testing/conformance.js +268 -0
  67. package/dist/recovery/testing/crash-points.d.ts +18 -0
  68. package/dist/recovery/testing/crash-points.js +43 -0
  69. package/dist/recovery/testing/crash-sweep.d.ts +65 -0
  70. package/dist/recovery/testing/crash-sweep.js +146 -0
  71. package/dist/recovery/testing/index.d.ts +3 -0
  72. package/dist/recovery/testing/index.js +4 -0
  73. package/dist/recovery/testing/preload.d.ts +1 -0
  74. package/dist/recovery/testing/preload.js +3 -0
  75. package/dist/recovery/transport-facts.d.ts +23 -0
  76. package/dist/recovery/transport-facts.js +46 -0
  77. package/dist/recovery/with-recovery.d.ts +44 -0
  78. package/dist/recovery/with-recovery.js +87 -0
  79. package/dist/system-one.d.ts +17 -1
  80. package/dist/system-one.js +62 -5
  81. package/dist/vocabulary.d.ts +42 -0
  82. package/dist/vocabulary.js +74 -0
  83. package/dist/workflow-shape.d.ts +7 -0
  84. package/dist/workflow-shape.js +85 -62
  85. package/dist/workflow.d.ts +187 -16
  86. package/dist/workflow.js +967 -324
  87. package/package.json +18 -2
  88. package/schema/workflow.schema.json +251 -15
  89. package/skills/author/SKILL.md +122 -0
  90. package/skills/author/examples/evidence-gate.input.json +6 -0
  91. package/skills/author/examples/evidence-gate.json +125 -0
  92. package/skills/author/examples/read-file.input.json +1 -0
  93. package/skills/author/examples/read-file.json +44 -0
  94. package/skills/author/examples/read-source-decision.input.json +4 -0
  95. package/skills/author/examples/read-source-decision.json +37 -0
  96. package/skills/author/examples/release-note.txt +10 -0
  97. package/skills/author/examples/review-release-notes.input.json +6 -0
  98. package/skills/author/examples/review-release-notes.json +123 -0
  99. package/skills/author/references/jev-decisions.md +125 -0
  100. package/skills/author/references/language.md +118 -0
  101. package/skills/author/references/sdk-authoring.md +11 -0
  102. package/skills/author/references/workflow-format.md +137 -0
@@ -22,7 +22,7 @@ function discriminatedErrors(value) {
22
22
  const validator = diagnosticValidators.get(schema);
23
23
  if (!validator.Check(entry))
24
24
  for (const error of validator.Errors(entry)) {
25
- errors.push(`workflow${path}${error.instancePath || (path ? "" : "/")}: ${error.message}`);
25
+ errors.push({ path: `${path}${error.instancePath}`, message: `workflow${path}${error.instancePath || (path ? "" : "/")}: ${error.message}` });
26
26
  if (errors.length >= 8)
27
27
  return;
28
28
  }
@@ -58,124 +58,147 @@ function discriminatedErrors(value) {
58
58
  check(documentSchema.definitions.Workflow, value, "");
59
59
  return errors;
60
60
  }
61
+ /** The deepest prefix of `path` that names a value in `document`: a rule about a missing key points at its container. */
62
+ function present(document, path) {
63
+ let cursor = document;
64
+ let reached = "";
65
+ for (const raw of path.split("/").slice(1)) {
66
+ const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
67
+ if (cursor === null || typeof cursor !== "object" || !Object.hasOwn(cursor, key))
68
+ break;
69
+ cursor = cursor[key];
70
+ reached += `/${raw}`;
71
+ }
72
+ return reached;
73
+ }
61
74
  export function workflowShapeErrors(value, complete = false) {
75
+ return workflowShapeIssues(value, complete).map(issue => issue.message);
76
+ }
77
+ export function workflowShapeIssues(value, complete = false) {
78
+ const located = (issues) => issues.map(issue => ({ path: present(value, issue.path), message: issue.message }));
62
79
  if (complete) {
63
80
  if (fullValidator.Check(value))
64
81
  return [];
65
82
  const selected = discriminatedErrors(value);
66
83
  if (selected.length)
67
- return selected;
68
- return [...fullValidator.Errors(value)].slice(0, 8).map(error => `workflow${error.instancePath || "/"}: ${error.message}`);
84
+ return located(selected);
85
+ return located([...fullValidator.Errors(value)].slice(0, 8).map(error => ({ path: error.instancePath, message: `workflow${error.instancePath || "/"}: ${error.message}` })));
69
86
  }
87
+ const at = (loc, key) => ({ text: `${loc.text}.${key}`, ptr: `${loc.ptr}/${pointer(key)}` });
88
+ const index = (loc, i) => ({ text: `${loc.text}[${i}]`, ptr: `${loc.ptr}/${i}` });
70
89
  const errors = [];
71
- const fail = (path, expected) => { errors.push(`${path} must be ${expected}`); };
72
- const record = (entry, path) => {
90
+ const fail = (loc, expected) => { errors.push({ path: loc.ptr, message: `${loc.text} must be ${expected}` }); };
91
+ const record = (entry, loc) => {
73
92
  if (isRecord(entry))
74
93
  return true;
75
- fail(path, "an object");
94
+ fail(loc, "an object");
76
95
  return false;
77
96
  };
78
- const strings = (entry, path, keys) => {
97
+ const strings = (entry, loc, keys) => {
79
98
  for (const key of keys)
80
99
  if (entry[key] !== undefined && typeof entry[key] !== "string")
81
- fail(`${path}.${key}`, "a string");
100
+ fail(at(loc, key), "a string");
82
101
  };
83
- const stringList = (entry, path) => {
102
+ const stringList = (entry, loc) => {
84
103
  if (entry === undefined)
85
104
  return;
86
105
  if (!Array.isArray(entry)) {
87
- fail(path, "an array of strings");
106
+ fail(loc, "an array of strings");
88
107
  return;
89
108
  }
90
- entry.forEach((item, index) => { if (typeof item !== "string")
91
- fail(`${path}[${index}]`, "a string"); });
109
+ entry.forEach((item, i) => { if (typeof item !== "string")
110
+ fail(index(loc, i), "a string"); });
92
111
  };
93
112
  // Preserve existing diagnostics for missing, non-finite and out-of-range numbers, and
94
113
  // primitive strings such as poll.deadline_s="soon". Objects can throw during coercion.
95
- const numeric = (entry, path, keys) => {
114
+ const numeric = (entry, loc, keys) => {
96
115
  for (const key of keys) {
97
116
  const item = entry[key];
98
117
  if (item !== null && item !== undefined && !["number", "string", "boolean"].includes(typeof item))
99
- fail(`${path}.${key}`, "a number");
118
+ fail(at(loc, key), "a number");
100
119
  }
101
120
  };
102
- const objectField = (entry, path, key, visit) => {
121
+ const objectField = (entry, loc, key, visit) => {
103
122
  if (entry[key] === undefined)
104
123
  return;
105
- if (record(entry[key], `${path}.${key}`))
106
- visit?.(entry[key], `${path}.${key}`);
124
+ if (record(entry[key], at(loc, key)))
125
+ visit?.(entry[key], at(loc, key));
107
126
  };
108
- const predicate = (entry, path) => {
109
- strings(entry, path, ["predicate", "path", "key", "instructions"]);
110
- numeric(entry, path, ["n", "gte"]);
111
- objectField(entry, path, "state");
112
- objectField(entry, path, "criteria", (criteria, at) => strings(criteria, at, ["true", "false"]));
127
+ const predicate = (entry, loc) => {
128
+ strings(entry, loc, ["predicate", "path", "key", "instructions"]);
129
+ numeric(entry, loc, ["n", "gte"]);
130
+ objectField(entry, loc, "state");
131
+ objectField(entry, loc, "criteria", (criteria, here) => strings(criteria, here, ["true", "false"]));
113
132
  };
114
- const node = (entry, path) => {
133
+ const node = (entry, loc) => {
115
134
  if (entry === undefined)
116
135
  return; // missing bodies already receive semantic diagnostics
117
- if (!record(entry, path))
136
+ if (!record(entry, loc))
118
137
  return;
119
- strings(entry, path, ["node", "label", "code", "as", "out", "instructions", "itemsPath", "resultPath", "kind", "stage", "summary", "describe", "type", "path", "tool", "command", "via", "where", "effort", "thinking", "tier"]);
120
- numeric(entry, path, ["maxConcurrency", "maxIters", "deadline_s"]);
138
+ strings(entry, loc, ["node", "label", "code", "as", "out", "instructions", "itemsPath", "resultPath", "kind", "stage", "summary", "describe", "type", "path", "tool", "command", "via", "where", "effort", "thinking", "tier", "valuePath", "otherwise", "onItemFailure", "failedAs"]);
139
+ numeric(entry, loc, ["maxConcurrency", "maxIters", "expect_iters", "deadline_s"]);
121
140
  for (const key of ["requires", "tools", "produces"])
122
- stringList(entry[key], `${path}.${key}`);
141
+ stringList(entry[key], at(loc, key));
123
142
  if (entry.sopSection !== undefined && typeof entry.sopSection !== "string")
124
- stringList(entry.sopSection, `${path}.sopSection`);
143
+ stringList(entry.sopSection, at(loc, "sopSection"));
125
144
  for (const key of ["state", "args", "input", "env"])
126
- objectField(entry, path, key);
145
+ objectField(entry, loc, key);
146
+ // Host-owned and opaque: only its container is checked, never its keys or values.
147
+ if (entry.metadata !== undefined && !isRecord(entry.metadata)) {
148
+ errors.push({ path: at(loc, "metadata").ptr, message: `${loc.text} (${typeof entry.label === "string" && entry.label ? entry.label : String(entry.node)}): metadata must be a plain object of host markers` });
149
+ }
127
150
  for (const key of ["until", "when"])
128
- objectField(entry, path, key, predicate);
129
- objectField(entry, path, "verify", (verify, at) => {
130
- strings(verify, at, ["out"]);
131
- numeric(verify, at, ["maxDrives"]);
132
- objectField(verify, at, "state");
133
- objectField(verify, at, "override", (override, here) => numeric(override, here, ["below"]));
151
+ objectField(entry, loc, key, predicate);
152
+ objectField(entry, loc, "verify", (verify, here) => {
153
+ strings(verify, here, ["out"]);
154
+ numeric(verify, here, ["maxDrives"]);
155
+ objectField(verify, here, "state");
156
+ objectField(verify, here, "override", (override, inner) => numeric(override, inner, ["below"]));
134
157
  });
135
- objectField(entry, path, "keep", (keep, at) => { strings(keep, at, ["path"]); numeric(keep, at, ["gte"]); });
136
- objectField(entry, path, "unsure", (unsure, at) => { strings(unsure, at, ["branch"]); numeric(unsure, at, ["gte"]); });
137
- objectField(entry, path, "retry", (retry, at) => {
138
- numeric(retry, at, ["attempts", "backoff_s"]);
139
- stringList(retry.on, `${at}.on`);
158
+ objectField(entry, loc, "keep", (keep, here) => { strings(keep, here, ["path"]); numeric(keep, here, ["gte"]); });
159
+ objectField(entry, loc, "unsure", (unsure, here) => { strings(unsure, here, ["branch"]); numeric(unsure, here, ["gte"]); });
160
+ objectField(entry, loc, "retry", (retry, here) => {
161
+ numeric(retry, here, ["attempts", "backoff_s"]);
162
+ stringList(retry.on, at(here, "on"));
140
163
  });
141
- objectField(entry, path, "poll", (poll, at) => {
142
- numeric(poll, at, ["interval_s", "deadline_s"]);
164
+ objectField(entry, loc, "poll", (poll, here) => {
165
+ numeric(poll, here, ["interval_s", "deadline_s"]);
143
166
  for (const key of ["until", "fail_when"])
144
- objectField(poll, at, key, predicate);
167
+ objectField(poll, here, key, predicate);
145
168
  });
146
169
  if (entry.node === "chain" || entry.node === "parallel") {
147
170
  const key = entry.node === "chain" ? "steps" : "branches";
148
171
  if (entry[key] !== undefined) {
149
172
  if (!Array.isArray(entry[key]))
150
- fail(`${path}.${key}`, "an array of nodes");
173
+ fail(at(loc, key), "an array of nodes");
151
174
  else
152
- entry[key].forEach((child, index) => node(child, `${path}.${key}[${index}]`));
175
+ entry[key].forEach((child, i) => node(child, index(at(loc, key), i)));
153
176
  }
154
177
  }
155
178
  if (entry.node === "map" || entry.node === "loop")
156
- node(entry.body, `${path}.body`);
179
+ node(entry.body, at(loc, "body"));
157
180
  if (entry.node === "route")
158
- objectField(entry, path, "branches", (branches, at) => {
181
+ objectField(entry, loc, "branches", (branches, here) => {
159
182
  for (const [name, branch] of Object.entries(branches))
160
- if (record(branch, `${at}.${name}`)) {
161
- strings(branch, `${at}.${name}`, ["criteria"]);
162
- node(branch.body, `${at}.${name}.body`);
183
+ if (record(branch, at(here, name))) {
184
+ strings(branch, at(here, name), ["criteria"]);
185
+ node(branch.body, at(at(here, name), "body"));
163
186
  }
164
187
  });
165
188
  if (entry.node === "workflow")
166
- workflow(entry.workflow, `${path}.workflow`);
189
+ workflow(entry.workflow, at(loc, "workflow"));
167
190
  };
168
- const workflow = (entry, path) => {
169
- if (!record(entry, path))
191
+ const workflow = (entry, loc) => {
192
+ if (!record(entry, loc))
170
193
  return;
171
- strings(entry, path, ["name"]);
172
- record(entry.schemas, `${path}.schemas`);
173
- objectField(entry, path, "input", (input, at) => strings(input, at, ["schemaId"]));
174
- if (record(entry.output, `${path}.output`))
175
- strings(entry.output, `${path}.output`, ["schemaId", "path"]);
176
- if (record(entry.root, `${path}.root`))
177
- node(entry.root, `${path}.root`);
194
+ strings(entry, loc, ["name"]);
195
+ record(entry.schemas, at(loc, "schemas"));
196
+ objectField(entry, loc, "input", (input, here) => strings(input, here, ["schemaId"]));
197
+ if (record(entry.output, at(loc, "output")))
198
+ strings(entry.output, at(loc, "output"), ["schemaId", "path"]);
199
+ if (record(entry.root, at(loc, "root")))
200
+ node(entry.root, at(loc, "root"));
178
201
  };
179
- workflow(value, "workflow");
180
- return errors.slice(0, 8);
202
+ workflow(value, { text: "workflow", ptr: "" });
203
+ return located(errors.slice(0, 8));
181
204
  }