@parcha/agentrun-dsl 0.1.0-beta.33 → 0.1.0-beta.34

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/dry-run.d.ts CHANGED
@@ -11,7 +11,24 @@ export type DryRunResult = {
11
11
  problems: string[];
12
12
  stage?: string;
13
13
  };
14
- export declare function synthesizeInstance(schema: unknown, definitions?: Record<string, unknown>, depth?: number): unknown;
14
+ /** What one dry run may synthesize in all, across its input and every step's answer (DryRunOptions.budget), and what one
15
+ * synthesizeInstance call may when none is given: values (each array item, object, string, number...) and string
16
+ * characters. Synthesis counts each before it makes it and throws SynthesisTooLarge past either, so a schema that asks
17
+ * for a huge value (nested arrays of a large minItems, a long minLength) never allocates past the budget. */
18
+ export type SynthesisBudget = {
19
+ values: number;
20
+ chars: number;
21
+ };
22
+ /** The default: a million values and 16 million characters, far past what a real workflow's dry run builds (a few
23
+ * thousand values at most), and well within a host's memory (a few hundred MB at worst). */
24
+ export declare const SYNTHESIS_BUDGET: Readonly<SynthesisBudget>;
25
+ /** The schema asked synthesis for more than its budget: the dry run ends not run, saying so. */
26
+ export declare class SynthesisTooLarge extends Error {
27
+ name: string;
28
+ }
29
+ /** A value of `schema` (its `$ref`s read from `definitions`), synthesized within `budget` (SYNTHESIS_BUDGET when none):
30
+ * past it, SynthesisTooLarge. */
31
+ export declare function synthesizeInstance(schema: unknown, definitions?: Record<string, unknown>, depth?: number, budget?: Partial<SynthesisBudget>): unknown;
15
32
  export type DryRunOptions = {
16
33
  sop?: string;
17
34
  probeContext?: {
@@ -28,5 +45,15 @@ export type DryRunOptions = {
28
45
  * stops, as not run: synthetic answers can keep a loop going to its bound, and a map over a long list. 10,000 by
29
46
  * default. */
30
47
  maxSteps?: number;
48
+ /** What the whole dry run may synthesize (SynthesisBudget): its input and every step's answer together. Past it the dry
49
+ * run stops, as not run ("the schema is too large to synthesize"). SYNTHESIS_BUDGET by default. */
50
+ budget?: Partial<SynthesisBudget>;
51
+ /** The longest the dry run may take by the clock (ms): past it, it stops at its next node or step, as not run. Read
52
+ * from the clock at each, never from a timer, so a dry run that never yields still stops. 60,000 by default. */
53
+ deadlineMs?: number;
54
+ /** The most node visits (a loop's body each iteration, a map's body for each item, any node run), whether or not they
55
+ * ask anything, before the dry run stops, as not run: a loop whose body asks nothing is no step, so maxSteps alone
56
+ * never ends it. Ten times maxSteps by default. */
57
+ maxVisits?: number;
31
58
  };
32
59
  export declare function dryRunWorkflow(workflow: Workflow, opts?: DryRunOptions): Promise<DryRunResult>;
package/dist/dry-run.js CHANGED
@@ -13,29 +13,63 @@ function syntheticProviders(workflow) {
13
13
  const provider = (id) => ({ id, needs: [], capabilities, decide: async () => { throw new Error("A dry run answers its decisions itself."); } });
14
14
  return { providers: Object.fromEntries([...ids].map((id) => [id, provider(id)])), default: "dry-run" };
15
15
  }
16
- export function synthesizeInstance(schema, definitions = {}, depth = 0) {
16
+ /** The default: a million values and 16 million characters, far past what a real workflow's dry run builds (a few
17
+ * thousand values at most), and well within a host's memory (a few hundred MB at worst). */
18
+ export const SYNTHESIS_BUDGET = { values: 1_000_000, chars: 16_000_000 };
19
+ /** The schema asked synthesis for more than its budget: the dry run ends not run, saying so. */
20
+ export class SynthesisTooLarge extends Error {
21
+ name = "SynthesisTooLarge";
22
+ }
23
+ /** A budget's limits, each field the default unless given as a number (a field given as undefined keeps the default). */
24
+ const spendOf = (limit = {}) => ({
25
+ values: 0,
26
+ chars: 0,
27
+ limit: { values: typeof limit.values === "number" ? limit.values : SYNTHESIS_BUDGET.values, chars: typeof limit.chars === "number" ? limit.chars : SYNTHESIS_BUDGET.chars },
28
+ });
29
+ /** A literal's characters as the value it is (a const, an enum's first): its serialized size. */
30
+ const literalChars = (value) => JSON.stringify(value)?.length ?? 0;
31
+ function charge(spend, values, chars) {
32
+ spend.values += values;
33
+ spend.chars += chars;
34
+ if (spend.values > spend.limit.values || spend.chars > spend.limit.chars) {
35
+ throw new SynthesisTooLarge(`the schema is too large to synthesize: past ${spend.limit.values} values or ${spend.limit.chars} characters`);
36
+ }
37
+ }
38
+ /** A value of `schema` (its `$ref`s read from `definitions`), synthesized within `budget` (SYNTHESIS_BUDGET when none):
39
+ * past it, SynthesisTooLarge. */
40
+ export function synthesizeInstance(schema, definitions = {}, depth = 0, budget = SYNTHESIS_BUDGET) {
41
+ return synthesize(schema, definitions, depth, spendOf(budget));
42
+ }
43
+ function synthesize(schema, definitions, depth, spend) {
44
+ // Every value it makes is counted before it is made, once (a $ref, an anyOf or a oneOf is the value it leads to, not one
45
+ // of its own): past the budget it throws, having built no more than the budget.
17
46
  if (depth > 12 || !schema || typeof schema !== "object")
18
- return null;
47
+ return (charge(spend, 1, 0), null);
19
48
  const spec = schema;
20
49
  if (typeof spec.$ref === "string") {
21
50
  const match = /^#\/definitions\/(.+)$/.exec(spec.$ref);
22
- return match && definitions[match[1]] ? synthesizeInstance(definitions[match[1]], definitions, depth + 1) : null;
51
+ return match && definitions[match[1]] ? synthesize(definitions[match[1]], definitions, depth + 1, spend) : (charge(spend, 1, 0), null);
23
52
  }
53
+ // A literal is charged its serialized size: one written long in the schema does not escape the character budget.
24
54
  if (spec.const !== undefined)
25
- return spec.const;
55
+ return (charge(spend, 1, literalChars(spec.const)), spec.const);
26
56
  if (Array.isArray(spec.enum) && spec.enum.length)
27
- return spec.enum[0];
57
+ return (charge(spend, 1, literalChars(spec.enum[0])), spec.enum[0]);
28
58
  if (Array.isArray(spec.anyOf) && spec.anyOf.length) {
29
59
  const branch = spec.anyOf.find((candidate) => candidate?.type !== "null") ?? spec.anyOf[0];
30
- return synthesizeInstance(branch, definitions, depth + 1);
60
+ return synthesize(branch, definitions, depth + 1, spend);
31
61
  }
32
62
  if (Array.isArray(spec.oneOf) && spec.oneOf.length)
33
- return synthesizeInstance(spec.oneOf[0], definitions, depth + 1);
63
+ return synthesize(spec.oneOf[0], definitions, depth + 1, spend);
64
+ // The one value made below.
65
+ charge(spend, 1, 0);
34
66
  const type = Array.isArray(spec.type) ? spec.type[0] : spec.type;
35
67
  if (type === "object" || (!type && spec.properties)) {
36
68
  const out = Object.create(null);
37
69
  for (const [key, property] of Object.entries(spec.properties || {})) {
38
- out[key] = synthesizeInstance(property, definitions, depth + 1);
70
+ // Its name is built into every value made under it, and serialized with it: charged before it is added.
71
+ charge(spend, 0, key.length);
72
+ out[key] = synthesize(property, definitions, depth + 1, spend);
39
73
  }
40
74
  return { ...out };
41
75
  }
@@ -45,12 +79,17 @@ export function synthesizeInstance(schema, definitions = {}, depth = 0) {
45
79
  const min = Number.isInteger(spec.minItems) ? spec.minItems : 1;
46
80
  if (!spec.items)
47
81
  return [];
48
- return Array.from({ length: Math.max(1, min) }, () => synthesizeInstance(spec.items, definitions, depth + 1));
82
+ // Each item is at least one value: a length past what the budget has left is refused before the array is made.
83
+ const length = Math.max(1, min);
84
+ if (length > spend.limit.values - spend.values)
85
+ charge(spend, length, 0);
86
+ return Array.from({ length }, () => synthesize(spec.items, definitions, depth + 1, spend));
49
87
  }
50
88
  if (type === "string") {
51
89
  if (spec.maxLength === 0)
52
90
  return "";
53
91
  const min = Number.isInteger(spec.minLength) ? spec.minLength : 1;
92
+ charge(spend, 0, Math.max(1, min));
54
93
  return "x".repeat(Math.max(1, min));
55
94
  }
56
95
  if (type === "integer") {
@@ -90,6 +129,8 @@ export function synthesizeInstance(schema, definitions = {}, depth = 0) {
90
129
  return false;
91
130
  if (type === "null")
92
131
  return null;
132
+ // A schema synthesis cannot read: one character.
133
+ charge(spend, 0, 1);
93
134
  return "x";
94
135
  }
95
136
  function unsupportedConstructs(schema, path, found, depth = 0) {
@@ -151,10 +192,20 @@ export async function dryRunWorkflow(workflow, opts = {}) {
151
192
  scanSchemas(workflow);
152
193
  if (skipped.length)
153
194
  return { ok: true, status: "not_run", skipped };
195
+ // One budget for everything this dry run synthesizes.
196
+ const spend = spendOf(opts.budget);
154
197
  let input = opts.input ?? {};
155
198
  if (opts.input === undefined && workflow.input) {
156
199
  const schema = resolveSchemaForWorkflow(workflow, workflow.schemas[workflow.input.schemaId]);
157
- const generated = synthesizeInstance(schema, schema.definitions ?? workflow.schemas);
200
+ let generated;
201
+ try {
202
+ generated = synthesize(schema, schema.definitions ?? workflow.schemas, 0, spend);
203
+ }
204
+ catch (error) {
205
+ if (error instanceof SynthesisTooLarge)
206
+ return { ok: true, status: "not_run", skipped: [error.message] };
207
+ throw error;
208
+ }
158
209
  if (!generated || typeof generated !== "object" || Array.isArray(generated) || !Compile(schema).Check(generated)) {
159
210
  return { ok: true, status: "not_run", skipped: ["Could not synthesize a valid input object. Supply input explicitly to dryRunWorkflow or the dry-run CLI."] };
160
211
  }
@@ -173,12 +224,43 @@ export async function dryRunWorkflow(workflow, opts = {}) {
173
224
  // Why the dry run stopped early, kept here: the interpreter may wrap what an adapter throws.
174
225
  let stopped;
175
226
  const stop = (reason) => { stopped ??= reason; throw new Error(stopped); };
227
+ /** A step's synthetic answer within the run's budget: past it, the dry run stops (the interpreter may wrap the throw). */
228
+ const synthesized = (make) => {
229
+ try {
230
+ return make();
231
+ }
232
+ catch (error) {
233
+ if (error instanceof SynthesisTooLarge)
234
+ stop(error.message);
235
+ throw error;
236
+ }
237
+ };
238
+ const deadlineMs = opts.deadlineMs ?? 60_000;
239
+ const deadline = Date.now() + deadlineMs;
240
+ const maxVisits = opts.maxVisits ?? maxSteps * 10;
241
+ let visits = 0;
242
+ const pastDeadline = () => {
243
+ if (Date.now() > deadline)
244
+ stop(`The dry run stopped past its ${deadlineMs} ms deadline.`);
245
+ };
246
+ /** A node's visit (a loop's body each iteration, a map's body for each item), counted against maxVisits and the
247
+ * deadline, so a loop whose body asks nothing (no step) still ends. Synchronous: it reads the clock, never a timer, so
248
+ * a run that never yields still stops. */
249
+ const visit = () => {
250
+ if (opts.signal?.aborted)
251
+ stop("The dry run was stopped before it finished.");
252
+ visits += 1;
253
+ if (visits > maxVisits)
254
+ stop(`The dry run stopped after ${maxVisits} node visits: on synthetic values the workflow's loops or maps go on further, asking nothing. Supply input, or lower a loop's maxIters.`);
255
+ pastDeadline();
256
+ };
176
257
  const step = async () => {
177
258
  if (opts.signal?.aborted)
178
259
  stop("The dry run was stopped before it finished.");
179
260
  steps += 1;
180
261
  if (steps > maxSteps)
181
262
  stop(`The dry run stopped after ${maxSteps} synthetic steps: on synthetic values the workflow's loops or maps go on further. Supply input, or lower a loop's maxIters.`);
263
+ pastDeadline();
182
264
  if (steps % 64 === 0) {
183
265
  await new Promise((resolve) => setTimeout(resolve, 0));
184
266
  if (opts.signal?.aborted)
@@ -188,13 +270,14 @@ export async function dryRunWorkflow(workflow, opts = {}) {
188
270
  const runCode = opts.runCode;
189
271
  try {
190
272
  const result = await runWorkflow(workflow, input, {
273
+ onVisit: () => visit(),
191
274
  sop: opts.sop,
192
275
  ...(runCode ? { runCode: async (...args) => { await step(); return runCode(...args); } } : {}),
193
276
  onEvent: (event) => { if (typeof event.label === "string")
194
277
  currentLabel = event.label; },
195
278
  runNode: async ({ schema, review }) => {
196
279
  await step();
197
- const candidate = synthesizeInstance(schema, schema.definitions ?? workflow.schemas);
280
+ const candidate = synthesized(() => synthesize(schema, schema.definitions ?? workflow.schemas, 0, spend));
198
281
  if (review)
199
282
  await review(candidate);
200
283
  return candidate;
@@ -202,7 +285,11 @@ export async function dryRunWorkflow(workflow, opts = {}) {
202
285
  // A node that requires evidence gets a placeholder, as a provider that gives evidence would answer it.
203
286
  runJudge: async ({ questions, evidence }) => {
204
287
  await step();
205
- return { answers: synthesizeAnswers(questions), model: "synthetic", usage: null, cost_usd: null, request_sha256: "",
288
+ // Its answers are synthetic values like any step's: each charged its serialized size against the run's budget (a
289
+ // choice's first option may be a long string, and a map collects one per item).
290
+ const answers = synthesizeAnswers(questions);
291
+ synthesized(() => charge(spend, Object.keys(answers).length, literalChars(answers)));
292
+ return { answers, model: "synthetic", usage: null, cost_usd: null, request_sha256: "",
206
293
  ...(evidence === "required" ? { evidence: [{ url: "https://example.invalid/dry-run", title: null, excerpts: [], scope: "dry_run" }] } : {}) };
207
294
  },
208
295
  syntheticEffects: true,
@@ -211,7 +298,7 @@ export async function dryRunWorkflow(workflow, opts = {}) {
211
298
  await step();
212
299
  return node.via === "shell"
213
300
  ? { code: 0, stdout: "{}", stderr: "", truncated: false }
214
- : synthesizeInstance(schema ?? (workflow.schemas || {})[node.out], schema?.definitions ?? workflow.schemas ?? {});
301
+ : synthesized(() => synthesize(schema ?? (workflow.schemas || {})[node.out], schema?.definitions ?? workflow.schemas ?? {}, 0, spend));
215
302
  },
216
303
  });
217
304
  if (result.status === "escalated") {
package/dist/index.d.ts CHANGED
@@ -6,7 +6,7 @@ export type { Job } from "./job.js";
6
6
  export { DECISION_RECEIPT_VERSION, DECISION_INTERRUPTED, DECISION_REFUSED, DECISION_STATE_MAX_BYTES, rederiveDecision } from "./decision-receipts.js";
7
7
  export type { DecisionImageDigest, DecisionKind, DecisionReceipt, DecisionRule } from "./decision-receipts.js";
8
8
  export type { Workflow, WorkflowNode, NodeMetadata, WorkflowDeps, WorkflowEvent, WorkflowRunResult, HostPolicy, HostPolicyContext, Escalation, EffectSettlement, MapItem, MapItemFailure, DecisionExchange, LlmNode, JudgeNode, PickNode, SiftNode, RouteNode, RouteByJudgmentNode, RouteByValueNode, WorkflowInvocation, ArtifactNode, ArtifactState, CallNode, CodeNode, CallRetryClass, EffectFailureCode, CallPredicate, PollClause, ModelTier, AgentContext, WorkflowEffort, WorkflowThinking, VerifyClause, AskPredicate, DecisionEvidenceMode, DecisionImages, MechanicalPredicate, Predicate, ValidationCode, ValidationIssue, ValidateWorkflowOptions, } from "./workflow.js";
9
- export { dryRunWorkflow, synthesizeInstance } from "./dry-run.js";
9
+ export { dryRunWorkflow, SYNTHESIS_BUDGET, SynthesisTooLarge, synthesizeInstance, type SynthesisBudget } from "./dry-run.js";
10
10
  export type { DryRunOptions, DryRunResult } from "./dry-run.js";
11
11
  export { compileQuestions, validateAnswers, answersToValue, answersSidecar, answerConfidence, synthesizeAnswers, SYSTEM_ONE_LIMITS, SystemOneError, isSystemOneResponseReason, deriveConfidence, completeConfidence, refusedQuestions, } from "./system-one.js";
12
12
  export type { SystemOneQuestion, SystemOneAnswer, SystemOneBox, SystemOneResult, SystemOneRetryClass, SystemOneResponseReason, CompiledQuestions, AnswersSidecar, ConfidenceSource, } from "./system-one.js";
package/dist/index.js CHANGED
@@ -2,7 +2,7 @@ export { defineWorkflow, runTypedWorkflow, WorkflowSchemaConversionError } from
2
2
  export { runWorkflow, validateWorkflow, workflowSha256, WorkflowInvalidError, WorkflowInputInvalidError, WorkflowOutputInvalidError, WorkflowCodeError, WorkflowStateError, WorkflowVerificationError, WorkflowDecisionRecordError, EffectFailure, EffectDeadlineExceededError, EffectOutcomeUnknownError, EscalationSignal, routesByValue, isItemFailure, } from "./workflow.js";
3
3
  export { defineJob } from "./job.js";
4
4
  export { DECISION_RECEIPT_VERSION, DECISION_INTERRUPTED, DECISION_REFUSED, DECISION_STATE_MAX_BYTES, rederiveDecision } from "./decision-receipts.js";
5
- export { dryRunWorkflow, synthesizeInstance } from "./dry-run.js";
5
+ export { dryRunWorkflow, SYNTHESIS_BUDGET, SynthesisTooLarge, synthesizeInstance } from "./dry-run.js";
6
6
  export { compileQuestions, validateAnswers, answersToValue, answersSidecar, answerConfidence, synthesizeAnswers, SYSTEM_ONE_LIMITS, SystemOneError, isSystemOneResponseReason, deriveConfidence, completeConfidence, refusedQuestions, } from "./system-one.js";
7
7
  export { judgeFromProvider, judgeFromProviders, checkCapabilities, chargedCost, DecisionProviderError, imageDimensions } from "./decision-provider.js";
8
8
  export { evidenceOf, EVIDENCE_EXCERPT_MAX, EVIDENCE_EXCERPTS_PER_ITEM, EVIDENCE_ITEMS_MAX, EVIDENCE_TEXT_MAX, EVIDENCE_TITLE_MAX } from "./evidence.js";
@@ -628,6 +628,9 @@ export type WorkflowDeps = {
628
628
  sop?: string;
629
629
  skill?: string;
630
630
  signal?: AbortSignal;
631
+ /** Called at each node's visit, before it runs (a loop's body each iteration, a map's body for each item): a host that
632
+ * bounds the work a run does (a dry run's steps and deadline) counts it here, and throws to stop the run. */
633
+ onVisit?: (node: WorkflowNode) => void;
631
634
  /** Best-effort observation only: thrown errors and rejected promises are ignored.
632
635
  * Observers are never awaited. Use required checkpoints for durable lifecycle gates. */
633
636
  onEvent?: (event: WorkflowEvent) => void;
package/dist/workflow.js CHANGED
@@ -2764,6 +2764,7 @@ function forwardObserver(observer, transform) {
2764
2764
  return forwarded;
2765
2765
  }
2766
2766
  async function runNodeOnState(node, state, workflow, deps) {
2767
+ deps.onVisit?.(node);
2767
2768
  deps = withExecutionLocation(deps);
2768
2769
  const observer = deps.onEvent;
2769
2770
  if (observer && !guardedObservers.has(observer)) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@parcha/agentrun-dsl",
3
- "version": "0.1.0-beta.33",
3
+ "version": "0.1.0-beta.34",
4
4
  "description": "Composable, typed workflows for agents",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",