@parcha/agentrun-dsl 0.1.0-beta.23 → 0.1.0-beta.26

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/dist/author.js CHANGED
@@ -234,6 +234,8 @@ export function applyHostOutputTypes(candidate, host, options = {}) {
234
234
  return { ...node, body: visit(node.body) };
235
235
  if (node.node === "route")
236
236
  return { ...node, branches: Object.fromEntries(Object.entries(node.branches || {}).map(([name, branch]) => [name, { ...branch, body: visit(branch?.body) }])) };
237
+ // Unlike desugarWorkflow, this does not descend into a child workflow: a child may not hold an artifact node
238
+ // (validateWorkflow rejects it, see containsReportNode), so there is nothing for the prose-type rewrite to reach there.
237
239
  return node;
238
240
  };
239
241
  return { ...candidate, root: visit(candidate.root) };
package/dist/authoring.js CHANGED
@@ -98,7 +98,7 @@ function copyJson(value, ancestors, budget, depth) {
98
98
  return value;
99
99
  if (typeof value === "number" && Number.isFinite(value))
100
100
  return value;
101
- if (typeof value !== "object" || value === null)
101
+ if (typeof value !== "object")
102
102
  throw new Error("workflow documents must contain only finite JSON values");
103
103
  if (utilTypes.isProxy(value))
104
104
  throw new Error("workflow documents must not contain proxies");
package/dist/dry-run.js CHANGED
@@ -151,8 +151,8 @@ export async function dryRunWorkflow(workflow, opts = {}) {
151
151
  }
152
152
  if (opts.probeContext && !Object.prototype.hasOwnProperty.call(input, "context")) {
153
153
  input = { ...input, context: {
154
- references: opts.probeContext?.references ?? {},
155
- references_parsed: opts.probeContext?.references_parsed ?? {},
154
+ references: opts.probeContext.references ?? {},
155
+ references_parsed: opts.probeContext.references_parsed ?? {},
156
156
  } };
157
157
  }
158
158
  let currentLabel = "";
@@ -11,8 +11,7 @@ import { bindingDigests, LEDGER_FORMAT } from "./binding.js";
11
11
  import { canonicalHash as hash } from "./canonical-hash.js";
12
12
  import { RecoveryError } from "./errors.js";
13
13
  import { gatewayIntentOf } from "./handoff-receipts.js";
14
- import { validateFrozenSnapshot, openedFrozenSnapshot, serializeFrozenSnapshot, frozenStepSessionId, frozenStepId, frozenEffectId, frozenEffectPath, admitFrozenStep, closeFrozenStepAttempt, frozenStop, FROZEN_SNAPSHOT_SCHEMA, FROZEN_SNAPSHOT_SCHEMA_V4, stateDelta, applyStateDelta, isItemOutcome } from "./frozen-snapshot.js";
15
- const failure = (code, message) => new RecoveryError(message, code);
14
+ import { validateFrozenSnapshot, openedFrozenSnapshot, serializeFrozenSnapshot, frozenStepSessionId, frozenStepId, frozenEffectId, frozenEffectPath, admitFrozenStep, closeFrozenStepAttempt, frozenStop, failure, SHA256 as SHA, FROZEN_SNAPSHOT_SCHEMA, FROZEN_SNAPSHOT_SCHEMA_V4, stateDelta, applyStateDelta, isItemOutcome } from "./frozen-snapshot.js";
16
15
  /** The branch a route runs for its answer, as the interpreter takes it: the node's `unsure` branch when
17
16
  * the answer's confidence is below `unsure.gte`, else the choice the answer names. */
18
17
  export function routeTaken(node, answers) {
@@ -221,7 +220,6 @@ export async function openRecovery(store, workflow, options) {
221
220
  writtenStates.add(sha256);
222
221
  return value;
223
222
  };
224
- const SHA = /^[a-f0-9]{64}$/;
225
223
  const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
226
224
  const validEntry = (entry) => isRecord(entry) && Number.isSafeInteger(entry.length) && entry.length >= 0
227
225
  && Number.isSafeInteger(entry.items) && entry.items >= 0 && typeof entry.base === "string" && SHA.test(entry.base);
@@ -567,7 +565,7 @@ export async function openRecovery(store, workflow, options) {
567
565
  const known = [FROZEN_SNAPSHOT_SCHEMA, FROZEN_SNAPSHOT_SCHEMA_V4];
568
566
  const found = stored?.schema;
569
567
  const version = typeof found === "string" ? /^agentrun\.frozen_run\.v(\d+)$/.exec(found)?.[1] : undefined;
570
- if (version !== undefined && !known.includes(found) && Number(version) > 4) {
568
+ if (version !== undefined && Number(version) > 4) {
571
569
  throw Object.assign(new RecoveryError(`This run is stored as ${found}, newer than this build knows (${known.join(", ")}); open it with a build that knows it`, "RECOVERY_SCHEMA_NEWER"), { found, known });
572
570
  }
573
571
  // The keyed layout is sticky: a run stored in it stays in it. A run stored whole, or a new one, takes it when the
@@ -697,9 +695,8 @@ export async function openRecovery(store, workflow, options) {
697
695
  }
698
696
  wake();
699
697
  };
700
- const fileHashes = (names) => reader.hashes(names);
701
698
  const verifyFiles = (files) => {
702
- if (hash(fileHashes(Object.keys(files))) !== hash(files))
699
+ if (hash(reader.hashes(Object.keys(files))) !== hash(files))
703
700
  throw failure("FROZEN_ARTIFACT_INVALID", "Committed artifact bytes changed; effect will not be repeated");
704
701
  };
705
702
  /** An effect-level clock is set once and kept across resume: a poll window or an attempt deadline
@@ -832,7 +829,7 @@ export async function openRecovery(store, workflow, options) {
832
829
  if (step && (frame.chains[step.chain]?.index ?? -1) >= step.index)
833
830
  throw pathFault(at, "A chain step committed behind its chain's frontier");
834
831
  if (node.node === "artifact" && node.path)
835
- keepFiles(fileHashes([node.path]), at);
832
+ keepFiles(reader.hashes([node.path]), at);
836
833
  frame.done.push(at);
837
834
  done.add(at);
838
835
  // A map that committed, alone or inside what committed, has its results in the state: what it had finished
@@ -1225,7 +1222,7 @@ export async function openRecovery(store, workflow, options) {
1225
1222
  }
1226
1223
  if (signal.aborted)
1227
1224
  throw signal.reason;
1228
- const files = fileHashes(params.produces);
1225
+ const files = reader.hashes(params.produces);
1229
1226
  // A tool effect's receipt names the external call it paid for (the tool and its arguments),
1230
1227
  // so a continuation that inherits the receipt can answer the same call from it. Any other
1231
1228
  // effect keeps its arguments beside its result.
@@ -1,4 +1,6 @@
1
+ import { RecoveryError } from "./errors.js";
1
2
  import { type PartialSlot, type Sha256, type StateDelta } from "./item-state.js";
3
+ export declare const failure: (code: string, message: string) => RecoveryError;
2
4
  export declare const FROZEN_SNAPSHOT_SCHEMA = "agentrun.frozen_run.v3";
3
5
  /** The keyed layout: what lies in a map item is kept in that item's record beside the state, and a state the driver
4
6
  * references is kept once by its digest, so no record rewritten at a commit grows with a map's items. */
@@ -55,8 +57,6 @@ export type FrozenSnapshotV4 = Omit<FrozenSnapshot, "schema" | "pin"> & {
55
57
  };
56
58
  maps: Record<string, MapEntry>;
57
59
  };
58
- /** Two values a state holds under one key are the same value. A key an item copied from its base holds the base's own
59
- * object, or one with the same JSON. */
60
60
  /** A map item's state at `path`, rebuilt as the driver rebuilds it (`./item-state.ts`, which imports nothing): the
61
61
  * `agentrun.states` value its `base` names, with the item's `set` and `unset` for that path applied, checked against
62
62
  * that path's `sha256`. `item` is an `agentrun.items` value; `states` holds `agentrun.states` values by SHA-256. When
@@ -198,6 +198,7 @@ export type FrozenShape = {
198
198
  resolves: (path: string) => boolean;
199
199
  };
200
200
  export declare const emptyPathFrame: () => PathFrame;
201
+ export declare const SHA256: RegExp;
201
202
  /** Whether a value is an item's committed failure: three strings, and nothing else. */
202
203
  export declare const isItemOutcome: (value: unknown) => value is ItemOutcome;
203
204
  /** Refuses a saved snapshot the driver could not have produced for this run. */
@@ -4,14 +4,12 @@
4
4
  import { createHash } from "node:crypto";
5
5
  import { RecoveryError } from "./errors.js";
6
6
  import { itemState as rebuildItemState, partialResults as readPartialResults } from "./item-state.js";
7
- const failure = (code, message) => new RecoveryError(message, code);
7
+ export const failure = (code, message) => new RecoveryError(message, code);
8
8
  export const FROZEN_SNAPSHOT_SCHEMA = "agentrun.frozen_run.v3";
9
9
  /** The keyed layout: what lies in a map item is kept in that item's record beside the state, and a state the driver
10
10
  * references is kept once by its digest, so no record rewritten at a commit grows with a map's items. */
11
11
  export const FROZEN_SNAPSHOT_SCHEMA_V4 = "agentrun.frozen_run.v4";
12
12
  export { stateDelta, applyStateDelta, canonicalJson } from "./item-state.js";
13
- /** Two values a state holds under one key are the same value. A key an item copied from its base holds the base's own
14
- * object, or one with the same JSON. */
15
13
  /** A map item's state at `path`, rebuilt as the driver rebuilds it (`./item-state.ts`, which imports nothing): the
16
14
  * `agentrun.states` value its `base` names, with the item's `set` and `unset` for that path applied, checked against
17
15
  * that path's `sha256`. `item` is an `agentrun.items` value; `states` holds `agentrun.states` values by SHA-256. When
@@ -28,7 +26,7 @@ export function partialResults(partial, states, options = {}) {
28
26
  }
29
27
  export const emptyPathFrame = () => ({ input: null, done: [], states: {}, chains: {}, loops: {}, routes: {}, inputs: {}, steps: {} });
30
28
  const record = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
31
- const SHA256 = /^[a-f0-9]{64}$/;
29
+ export const SHA256 = /^[a-f0-9]{64}$/;
32
30
  /** `value` as an object whose fields can be read, or null. */
33
31
  const fields = (value) => record(value) ? value : null;
34
32
  const entriesOf = (value) => { const object = fields(value); return object ? Object.entries(object) : null; };
@@ -40,7 +40,7 @@ export type InheritedJob = {
40
40
  effects: InheritedEffect[];
41
41
  /** Workspace-relative produced files with the sha256 the driver committed for them. */
42
42
  files: Record<string, string>;
43
- /** The file writeFrozenEvidence wrote each effect's whole receipt to, by effect id. */
43
+ /** The file writeHandoffFiles wrote each effect's whole receipt to, by effect id. */
44
44
  effectFiles?: Record<string, string>;
45
45
  };
46
46
  /** The label a step's identity carries, distinct for every session the frozen driver admits. A step's
@@ -617,7 +617,10 @@ export type ValidationIssue = {
617
617
  code: ValidationCode;
618
618
  message: string;
619
619
  };
620
- /** Whether a workflow can run, checked without running it: `errors` refuse it, `warnings` advise and never refuse. */
620
+ /** Whether a workflow can run, checked without running it: `errors` refuse it, `warnings` advise and never refuse.
621
+ * Set `executeCode: false` for untrusted author feedback: check syntax and mechanical contracts without evaluating
622
+ * authored expressions or probing transforms. That is not execution admission; trusted/default validation and runtime
623
+ * output checks remain authoritative. */
621
624
  export declare function validateWorkflow(workflow: Workflow, opts?: {
622
625
  executeCode?: boolean;
623
626
  input?: Record<string, unknown>;
package/dist/workflow.js CHANGED
@@ -65,8 +65,12 @@ export const declaredWrites = (node) => {
65
65
  return;
66
66
  if (n.node === "report")
67
67
  out.add("report_markdown");
68
- else if (typeof n.as === "string" && n.as.trim())
68
+ // The key a generative node writes under is `as || label`, the one the interpreter uses (mergeStageDelta); a code
69
+ // node's patch keys are known only when it runs. The validator rejects a blank `as` or label, so the key is non-blank.
70
+ else if (typeof n.as === "string" && n.as !== "")
69
71
  out.add(n.as);
72
+ else if ((n.node === "agent" || n.node === "decide" || n.node === "extract") && typeof n.label === "string" && n.label !== "")
73
+ out.add(n.label);
70
74
  if (n.node === "map") {
71
75
  if (typeof n.failedAs === "string" && n.failedAs.trim())
72
76
  out.add(n.failedAs);
@@ -97,9 +101,9 @@ const loopBodyWrites = (body) => {
97
101
  }
98
102
  if (n.node === "report")
99
103
  out.add("report_markdown");
100
- else if (typeof n.as === "string" && n.as.trim())
104
+ else if (typeof n.as === "string" && n.as !== "")
101
105
  out.add(n.as);
102
- else if (["agent", "decide", "extract"].includes(n.node) && typeof n.label === "string")
106
+ else if (["agent", "decide", "extract"].includes(n.node) && typeof n.label === "string" && n.label !== "")
103
107
  out.add(n.label);
104
108
  if (n.node === "map" && typeof n.failedAs === "string" && n.failedAs.trim())
105
109
  out.add(n.failedAs);
@@ -334,9 +338,7 @@ export function workflowDocumentError(value) {
334
338
  return undefined;
335
339
  }
336
340
  const pointerKey = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
337
- /** Set executeCode:false for untrusted author feedback: check syntax and mechanical contracts
338
- * without evaluating authored expressions or probing transforms. This is not execution admission;
339
- * trusted/default validation and runtime output checks remain authoritative. */
341
+ /** The names `retry.on` accepts: a call's retry classes and the effect-failure codes. */
340
342
  const RETRY_ON_NAMES = [...CALL_RETRY_CLASSES, ...EFFECT_FAILURE_CODES];
341
343
  /** Advice the validator gives without refusing: a shape that runs and costs more than it needs to. A map with no
342
344
  * `resultPath` whose body writes no `as` returns each item's whole state, which holds the list the map ran over: the
@@ -377,7 +379,10 @@ function workflowWarnings(workflow) {
377
379
  visit(workflow.root);
378
380
  return warnings;
379
381
  }
380
- /** Whether a workflow can run, checked without running it: `errors` refuse it, `warnings` advise and never refuse. */
382
+ /** Whether a workflow can run, checked without running it: `errors` refuse it, `warnings` advise and never refuse.
383
+ * Set `executeCode: false` for untrusted author feedback: check syntax and mechanical contracts without evaluating
384
+ * authored expressions or probing transforms. That is not execution admission; trusted/default validation and runtime
385
+ * output checks remain authoritative. */
381
386
  export function validateWorkflow(workflow, opts) {
382
387
  const bounded = workflowDocumentError(workflow);
383
388
  if (bounded)
@@ -828,6 +833,15 @@ export function validateWorkflow(workflow, opts) {
828
833
  const labelIsKey = (node.node === "agent" || node.node === "decide" || node.node === "extract" || node.node === "code") && node.as === undefined;
829
834
  if (labelIsKey && typeof node.label === "string" && holdsDollar(node.label))
830
835
  fail("STATE_KEY_RESERVED", ptrOf(path), `${path} (${node.label}): label must not contain "$" — an unaliased ${node.node} node writes under its label, and "$" keys are engine-owned`);
836
+ // A generative or code node's write key must be a real state key, never blank: the interpreter writes under
837
+ // `as || label` (`as` wins when it is any non-empty string, whitespace included), so a blank or whitespace-only
838
+ // `as`, or a label that is the key and is whitespace-only, would write under a key no other node can name and hide
839
+ // a disjointness collision. (Other nodes' `as` is checked "required" in their own case.)
840
+ const writesUnderKey = node.node === "agent" || node.node === "decide" || node.node === "extract" || node.node === "code";
841
+ if (writesUnderKey && typeof node.as === "string" && !node.as.trim())
842
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label || node.node}): "as" must be a non-empty state key, not blank`);
843
+ if (labelIsKey && typeof node.label === "string" && !node.label.trim())
844
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.node}): label must be a non-empty state key when the node writes under it (no "as")`);
831
845
  }
832
846
  switch (node.node) {
833
847
  case "chain":
@@ -870,8 +884,7 @@ export function validateWorkflow(workflow, opts) {
870
884
  case "decide":
871
885
  case "extract":
872
886
  case "report":
873
- if (node.state !== undefined)
874
- checkStateMap(node.state, node.label, path);
887
+ checkStateMap(node.state, node.label, path);
875
888
  if (!node.instructions?.trim())
876
889
  fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): instructions required`);
877
890
  if (node.node !== "report" && !Object.hasOwn(workflow.schemas, node.out))
@@ -895,8 +908,7 @@ export function validateWorkflow(workflow, opts) {
895
908
  const qs = checkQuestionSchema(v.out, node.label, path);
896
909
  if (qs && !Object.values(qs).some((q) => q.type === "noul"))
897
910
  fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): verify.out "${v.out}" carries no yes/no question — a verifier decides by yes/no (a boolean named after a submission field verifies it; any other boolean is a requirement)`);
898
- if (v.state !== undefined)
899
- checkStateMap(v.state, node.label, path, "verify.state");
911
+ checkStateMap(v.state, node.label, path, "verify.state");
900
912
  if (v.maxDrives !== undefined && (!Number.isInteger(v.maxDrives) || v.maxDrives < 1))
901
913
  fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${node.label}): verify.maxDrives must be an integer >= 1`);
902
914
  if (v.override !== undefined && (typeof v.override?.below !== "number" || v.override.below <= 0 || v.override.below >= 1))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@parcha/agentrun-dsl",
3
- "version": "0.1.0-beta.23",
3
+ "version": "0.1.0-beta.26",
4
4
  "description": "Composable, typed workflows for agents",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",