@parcha/agentrun-dsl 0.1.0-beta.1 → 0.1.0-beta.11

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 (38) hide show
  1. package/README.md +25 -11
  2. package/dist/author.d.ts +89 -0
  3. package/dist/author.js +317 -0
  4. package/dist/code-exec.d.ts +6 -0
  5. package/dist/code-exec.js +126 -0
  6. package/dist/dry-run.d.ts +4 -1
  7. package/dist/dry-run.js +2 -1
  8. package/dist/index.d.ts +8 -3
  9. package/dist/index.js +9 -2
  10. package/dist/inspection.js +2 -2
  11. package/dist/long-timer.d.ts +7 -0
  12. package/dist/long-timer.js +22 -0
  13. package/dist/observer-snapshot.d.ts +3 -0
  14. package/dist/observer-snapshot.js +46 -0
  15. package/dist/predicates.d.ts +4 -0
  16. package/dist/predicates.js +19 -2
  17. package/dist/system-one.js +45 -4
  18. package/dist/vocabulary.d.ts +42 -0
  19. package/dist/vocabulary.js +74 -0
  20. package/dist/workflow-shape.js +6 -2
  21. package/dist/workflow.d.ts +164 -15
  22. package/dist/workflow.js +551 -118
  23. package/package.json +3 -2
  24. package/schema/workflow.schema.json +237 -15
  25. package/skills/author/SKILL.md +120 -0
  26. package/skills/author/examples/evidence-gate.input.json +6 -0
  27. package/skills/author/examples/evidence-gate.json +125 -0
  28. package/skills/author/examples/read-file.input.json +1 -0
  29. package/skills/author/examples/read-file.json +44 -0
  30. package/skills/author/examples/read-source-decision.input.json +4 -0
  31. package/skills/author/examples/read-source-decision.json +37 -0
  32. package/skills/author/examples/release-note.txt +10 -0
  33. package/skills/author/examples/review-release-notes.input.json +6 -0
  34. package/skills/author/examples/review-release-notes.json +123 -0
  35. package/skills/author/references/jev-decisions.md +125 -0
  36. package/skills/author/references/language.md +118 -0
  37. package/skills/author/references/sdk-authoring.md +9 -0
  38. package/skills/author/references/workflow-format.md +137 -0
@@ -1,10 +1,13 @@
1
1
  import { type AcceptPredicate } from "./predicates.js";
2
+ import { EFFECT_FAILURE_CODES } from "./vocabulary.js";
2
3
  import { type SystemOneAnswer, type SystemOneQuestion } from "./system-one.js";
3
4
  export { resolveSchemaForWorkflow } from "./schema-references.js";
4
5
  /** The model tier a node asks for: `fast` (the cheap tier), `strong` (the host's stronger model),
5
6
  * or the kind's default. A router that sends the few thin cases to `strong` buys depth only where the
6
7
  * decision is on the edge. */
7
8
  export type ModelTier = "fast" | "default" | "strong";
9
+ /** An `agent` node's context (`AGENT_CONTEXTS`). */
10
+ export type AgentContext = "fresh" | "fork";
8
11
  export type VerifyClause = {
9
12
  out: string;
10
13
  state?: Record<string, unknown>;
@@ -28,14 +31,21 @@ export type Predicate = MechanicalPredicate | AskPredicate;
28
31
  export type WorkflowEffort = "minimal" | "low" | "medium" | "high";
29
32
  /** The author's thinking dial. There is deliberately no "off": thinking is never off. */
30
33
  export type WorkflowThinking = "low" | "medium" | "high";
34
+ /** Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the
35
+ * document and never reads it; it never reaches state, events, prompts or effect identities. */
36
+ export type NodeMetadata = {
37
+ [key: string]: unknown;
38
+ };
31
39
  export type WorkflowNode = {
32
40
  node: "chain";
33
41
  steps: WorkflowNode[];
42
+ metadata?: NodeMetadata;
34
43
  } | {
35
44
  node: "code";
36
45
  label: string;
37
46
  code: string;
38
47
  as?: string;
48
+ metadata?: NodeMetadata;
39
49
  } | {
40
50
  node: "agent";
41
51
  label: string;
@@ -50,6 +60,10 @@ export type WorkflowNode = {
50
60
  thinking?: WorkflowThinking;
51
61
  verify?: VerifyClause;
52
62
  tier?: ModelTier;
63
+ /** The most the node asks to spend, in dollars. @exclusiveMinimum 0 */
64
+ budget_usd?: number;
65
+ context?: AgentContext;
66
+ metadata?: NodeMetadata;
53
67
  } | {
54
68
  node: "decide";
55
69
  label: string;
@@ -64,6 +78,7 @@ export type WorkflowNode = {
64
78
  thinking?: WorkflowThinking;
65
79
  verify?: VerifyClause;
66
80
  tier?: ModelTier;
81
+ metadata?: NodeMetadata;
67
82
  } | {
68
83
  node: "extract";
69
84
  label: string;
@@ -78,6 +93,7 @@ export type WorkflowNode = {
78
93
  thinking?: WorkflowThinking;
79
94
  verify?: VerifyClause;
80
95
  tier?: ModelTier;
96
+ metadata?: NodeMetadata;
81
97
  } | {
82
98
  node: "report";
83
99
  label: string;
@@ -88,6 +104,7 @@ export type WorkflowNode = {
88
104
  tools?: string[];
89
105
  effort?: WorkflowEffort;
90
106
  thinking?: WorkflowThinking;
107
+ metadata?: NodeMetadata;
91
108
  } | ArtifactNode | {
92
109
  node: "map";
93
110
  label: string;
@@ -96,16 +113,20 @@ export type WorkflowNode = {
96
113
  as: string;
97
114
  resultPath?: string;
98
115
  maxConcurrency?: number;
116
+ metadata?: NodeMetadata;
99
117
  } | {
100
118
  node: "parallel";
101
119
  label: string;
102
120
  branches: WorkflowNode[];
121
+ metadata?: NodeMetadata;
103
122
  } | {
104
123
  node: "loop";
105
124
  label: string;
106
125
  body: WorkflowNode;
107
126
  until: Predicate;
108
127
  maxIters: number;
128
+ expect_iters?: number;
129
+ metadata?: NodeMetadata;
109
130
  } | {
110
131
  node: "escalate";
111
132
  label: string;
@@ -113,6 +134,7 @@ export type WorkflowNode = {
113
134
  kind: string;
114
135
  stage: string;
115
136
  summary: string;
137
+ metadata?: NodeMetadata;
116
138
  } | JudgeNode | PickNode | SiftNode | RouteNode | CallNode | WorkflowInvocation;
117
139
  /** A judgment as typed questions. `state` is what the questions see, interpolated by value from the
118
140
  * workflow state (a whole-string placeholder keeps its type); `out` is a flat schema of enums,
@@ -125,6 +147,7 @@ export type JudgeNode = {
125
147
  out: string;
126
148
  as: string;
127
149
  requires?: string[];
150
+ metadata?: NodeMetadata;
128
151
  };
129
152
  /** One choice whose options are the items of a list. `describe` renders each item as its option
130
153
  * text (`{item.field}`); `allowNone` adds a none-of-these option. The result at `as` is
@@ -140,6 +163,7 @@ export type PickNode = {
140
163
  allowNone?: boolean;
141
164
  as: string;
142
165
  requires?: string[];
166
+ metadata?: NodeMetadata;
143
167
  };
144
168
  /** The same question set (`out`, a judge schema) asked of every item of a list in ONE request: item i's
145
169
  * questions are prefixed `i.`; every answer lands in `as.answers[i]` and `as.values[i]`. `keep`
@@ -158,11 +182,15 @@ export type SiftNode = {
158
182
  gte?: number;
159
183
  };
160
184
  requires?: string[];
185
+ metadata?: NodeMetadata;
161
186
  };
162
- /** A choice among subgraphs. The options are the branch names, their criteria the branch
187
+ /** Run one of several named branches. Jev chooses it from `instructions` and `state`, or the workflow
188
+ * already holds the choice as a string at `valuePath` and no model is asked. */
189
+ export type RouteNode = RouteByJudgmentNode | RouteByValueNode;
190
+ /** A choice among subgraphs that Jev makes. The options are the branch names, their criteria the branch
163
191
  * descriptions; the chosen branch runs on the state. `as` (optional) records the choice and its
164
192
  * distribution; `unsure` names the branch taken when confidence is below `gte`. */
165
- export type RouteNode = {
193
+ export type RouteByJudgmentNode = {
166
194
  node: "route";
167
195
  label: string;
168
196
  state: Record<string, unknown>;
@@ -177,9 +205,33 @@ export type RouteNode = {
177
205
  branch: string;
178
206
  gte: number;
179
207
  };
208
+ valuePath?: never;
209
+ otherwise?: never;
180
210
  as?: string;
181
211
  requires?: string[];
212
+ metadata?: NodeMetadata;
182
213
  };
214
+ /** A route by a value already in state: the string at `valuePath` names the branch. A missing value or
215
+ * an unknown name takes `otherwise` when declared and fails before any branch otherwise; a value that is
216
+ * not a string always fails. `as` records `{value, taken, fallback}`. */
217
+ export type RouteByValueNode = {
218
+ node: "route";
219
+ label: string;
220
+ valuePath: string;
221
+ branches: {
222
+ [branch: string]: {
223
+ body: WorkflowNode;
224
+ };
225
+ };
226
+ otherwise?: string;
227
+ state?: never;
228
+ instructions?: never;
229
+ unsure?: never;
230
+ as?: string;
231
+ requires?: string[];
232
+ metadata?: NodeMetadata;
233
+ };
234
+ export declare const routesByValue: (node: RouteNode) => node is RouteByValueNode;
183
235
  /** A child workflow invoked as one step of its parent. The child is embedded whole, so the parent
184
236
  * digest covers every child byte; `input` is interpolated by value and is the child's ENTIRE initial
185
237
  * state (no parent state leaks in); the child's validated output is checked against the parent's
@@ -192,10 +244,13 @@ export type WorkflowInvocation = {
192
244
  input: Record<string, unknown>;
193
245
  out: string;
194
246
  as: string;
247
+ metadata?: NodeMetadata;
195
248
  };
196
249
  /** `exit` is a shell command that ended with a non-zero status: retried only when the author
197
250
  * declared retry, since re-running a command is the author's call. */
198
251
  export type CallRetryClass = "timeout" | "http_5xx" | "http_429" | "connection" | "exit";
252
+ /** A failed effect's closed code (EFFECT_FAILURE_CODES). */
253
+ export type EffectFailureCode = typeof EFFECT_FAILURE_CODES[number];
199
254
  /** The workflow's terminal deliverable. Types "markdown" and "report" use the report
200
255
  * writer; other non-empty types name a workspace file produced by an earlier call.
201
256
  * File existence and delivery are the host's responsibility. */
@@ -214,6 +269,7 @@ export type ArtifactNode = {
214
269
  effort?: WorkflowEffort;
215
270
  thinking?: WorkflowThinking;
216
271
  requires?: string[];
272
+ metadata?: NodeMetadata;
217
273
  };
218
274
  export type ArtifactState = {
219
275
  path: string;
@@ -263,19 +319,24 @@ export type CallNode = {
263
319
  produces?: string[];
264
320
  /** Wall bound in seconds for one execution. Required: an unbounded effect is how a stalled provider becomes a stalled job. */
265
321
  deadline_s: number;
322
+ /** `on` names retry classes or effect failure codes; absent, the transient retry classes. */
266
323
  retry?: {
267
324
  attempts: number;
268
325
  backoff_s?: number;
269
- on?: CallRetryClass[];
326
+ on?: (CallRetryClass | EffectFailureCode)[];
270
327
  };
271
328
  /** Repeat the call until its result settles (a queued job, an eventually consistent read). */
272
329
  poll?: PollClause;
273
330
  requires?: string[];
331
+ metadata?: NodeMetadata;
274
332
  };
275
333
  export declare const SHELL_RESULT_SCHEMA: Record<string, unknown>;
276
334
  export type LlmNode = Extract<WorkflowNode, {
277
335
  node: "agent" | "decide" | "extract" | "report";
278
336
  }>;
337
+ export type CodeNode = Extract<WorkflowNode, {
338
+ node: "code";
339
+ }>;
279
340
  export declare const REPORT_SCHEMA: Record<string, unknown>;
280
341
  export type Workflow = {
281
342
  v: 2;
@@ -307,6 +368,8 @@ export type WorkflowRunResult = {
307
368
  status: "complete";
308
369
  state: Record<string, unknown>;
309
370
  output: unknown;
371
+ /** What the host's policy wrote through `decodeSubmission`: the final `state.$host`, never part of `output`. */
372
+ host?: Record<string, unknown>;
310
373
  } | {
311
374
  status: "escalated";
312
375
  state: Record<string, unknown>;
@@ -316,8 +379,60 @@ export type MapItem = {
316
379
  label: string;
317
380
  index: number;
318
381
  };
382
+ /** Where a host policy hook is being applied. `terminal` is true for a generative node whose `out` is
383
+ * the workflow's output schema: the node that emits the terminal record. */
384
+ export type HostPolicyContext = {
385
+ workflow: {
386
+ name: string;
387
+ outputSchemaId: string;
388
+ };
389
+ node: {
390
+ kind: WorkflowNode["node"];
391
+ label: string;
392
+ out?: string;
393
+ as?: string;
394
+ };
395
+ terminal: boolean;
396
+ executionPath: string;
397
+ item?: MapItem;
398
+ };
399
+ /** Application policy around generative nodes and completed steps. This is host code handed in through
400
+ * deps: nothing in a workflow document can name or reach it, so a candidate workflow cannot change its
401
+ * host's channels. Each hook is a general capability rather than a product rule:
402
+ * - `systemBlocks` appends host text after the node's instructions.
403
+ * - `submissionSchema` widens the schema the adapter submits against with host-owned channels. The
404
+ * returned schema must accept every value the stage schema accepts; the engine validates the raw
405
+ * submission against it and the decoded domain value against the unchanged stage schema, so no host
406
+ * channel can bypass domain validation or verification.
407
+ * - `decodeSubmission` splits an accepted transport submission into the domain value and host state.
408
+ * Host state lives under the reserved `$host` state key (no workflow may write it), so it is
409
+ * checkpointed and resumed with the rest of the state, isolated per map item, branch and child
410
+ * exactly as the state is, excluded from a path-less output projection, and returned as `result.host`.
411
+ * Parallel branches merge their `$host` deltas key by key: arrays append, an unchanged value is kept,
412
+ * two branches changing one non-array key to different values is a write conflict.
413
+ * - `afterNode` enriches a completed step's state before commit and checkpoint. This is domain state:
414
+ * downstream nodes and output validation see it. */
415
+ export type HostPolicy = {
416
+ systemBlocks?: (context: HostPolicyContext) => string[];
417
+ submissionSchema?: (stageSchema: Record<string, unknown>, context: HostPolicyContext) => Record<string, unknown>;
418
+ decodeSubmission?: (submission: unknown, context: HostPolicyContext & {
419
+ host: Record<string, unknown>;
420
+ }) => {
421
+ value: unknown;
422
+ host?: Record<string, unknown>;
423
+ };
424
+ afterNode?: (context: HostPolicyContext & {
425
+ state: Record<string, unknown>;
426
+ }) => Record<string, unknown> | undefined;
427
+ };
319
428
  export type WorkflowDeps = {
320
429
  maxQuestionsPerRequest?: number;
430
+ /** Most UTF-8 bytes of JSON state one judge request may carry (the Jev adapter's `maxStateBytes`
431
+ * measure). A `sift` that would exceed it, or `maxQuestionsPerRequest`, is split into several
432
+ * requests. Absent = no byte limit. */
433
+ maxStateBytesPerRequest?: number;
434
+ /** Host application policy; see `HostPolicy`. Absent = the engine's own behavior, unchanged. */
435
+ hostPolicy?: HostPolicy;
321
436
  runNode?: (params: {
322
437
  kind: "agent" | "decide" | "extract" | "report";
323
438
  label: string;
@@ -340,6 +455,12 @@ export type WorkflowDeps = {
340
455
  message: string;
341
456
  }>;
342
457
  tier?: ModelTier;
458
+ /** An `agent` node's `budget_usd`: the most the node asks to spend, recorded; enforcement belongs to the host.
459
+ * No runner stops a run on money. A host may cap it by what it has left. */
460
+ budgetUsd?: number;
461
+ /** An `agent` node's `context`. `fork` asks the host to start the session from the caller's transcript;
462
+ * a host that has none to fork refuses it. */
463
+ context?: AgentContext;
343
464
  }) => Promise<unknown>;
344
465
  runEffect?: (params: {
345
466
  node: CallNode;
@@ -349,9 +470,25 @@ export type WorkflowDeps = {
349
470
  attempt: number;
350
471
  idempotencyKey: string;
351
472
  signal: AbortSignal;
473
+ /** The attempt's deadline instant on this process's `performance.now()` clock, exactly as the
474
+ * interpreter armed its deadline timer, so the host measures its own kill and duration against
475
+ * the instant the timer fires. Absent when the call has no deadline. */
476
+ deadlineAt?: number;
352
477
  item?: MapItem;
353
478
  executionPath?: string;
354
479
  }) => Promise<unknown>;
480
+ /** The host's executor for `code` nodes. Present, the interpreter hands it the node, the state and
481
+ * the context the transform would receive and uses what it resolves to as the transform's result
482
+ * (the same patch rules and state checks apply); a rejection fails the node as the host typed it.
483
+ * Absent, the interpreter compiles and runs the transform in this process (`compileTransform`),
484
+ * which is not a sandbox: a host that runs code from an untrusted author supplies this. */
485
+ runCode?: (node: CodeNode, state: Record<string, unknown>, ctx: {
486
+ sop: string;
487
+ label: string;
488
+ executionPath: string;
489
+ item?: MapItem;
490
+ signal?: AbortSignal;
491
+ }) => Promise<unknown>;
355
492
  runJudge?: (params: {
356
493
  label: string;
357
494
  kind: "judge" | "pick" | "sift" | "route" | "ask";
@@ -394,18 +531,31 @@ export type WorkflowDeps = {
394
531
  signal?: AbortSignal;
395
532
  /** Best-effort observation only: thrown errors and rejected promises are ignored.
396
533
  * Observers are never awaited. Use required checkpoints for durable lifecycle gates. */
397
- onEvent?: (event: {
398
- type: string;
399
- label: string;
400
- detail?: unknown;
401
- executionPath?: string;
402
- }) => void;
534
+ onEvent?: (event: WorkflowEvent) => void;
535
+ /** Trusted host boundary: return a detached snapshot without mutating the input.
536
+ * Runs before generic copying; undefined or thrown errors omit the event.
537
+ * Required trace validation cancels through the host signal, preserving execution cleanup. */
538
+ prepareEvent?: (event: WorkflowEvent) => WorkflowEvent | undefined;
539
+ };
540
+ export type WorkflowEvent = {
541
+ type: string;
542
+ label: string;
543
+ detail?: unknown;
544
+ executionPath?: string;
403
545
  };
404
546
  export declare const declaredWrites: (node: WorkflowNode | undefined) => Set<string>;
405
547
  export declare const childSteps: (child: Workflow | undefined) => WorkflowNode[] | null;
548
+ /** A failed effect: its retry class (null when the failure is not transient by nature), its closed code,
549
+ * and what the host observed (`detail`, written onto the attempt's `effect.failed` event). */
406
550
  export declare class EffectFailure extends Error {
407
551
  readonly retryClass: CallRetryClass | null;
408
- constructor(message: string, retryClass?: CallRetryClass | null);
552
+ readonly code: EffectFailureCode | null;
553
+ readonly detail?: Record<string, unknown>;
554
+ constructor(message: string, retryClass?: CallRetryClass | null, options?: {
555
+ code?: EffectFailureCode | null;
556
+ detail?: Record<string, unknown>;
557
+ cause?: unknown;
558
+ });
409
559
  }
410
560
  export declare function parseCsvRows(text: string): string[][];
411
561
  export declare function buildReferenceContext(files: Record<string, string>): {
@@ -420,9 +570,6 @@ export declare function workflowSha256(workflow: Workflow): string;
420
570
  /** Bound the complete document before any recursive schema or semantic traversal. Shared
421
571
  * objects are valid, but each occurrence consumes the budget; cycles are never JSON. */
422
572
  export declare function workflowDocumentError(value: unknown): string | undefined;
423
- /** Set executeCode:false for untrusted author feedback: check syntax and mechanical contracts
424
- * without evaluating authored expressions or probing transforms. This is not execution admission;
425
- * trusted/default validation and runtime output checks remain authoritative. */
426
573
  export declare function validateWorkflow(workflow: Workflow, opts?: {
427
574
  executeCode?: boolean;
428
575
  input?: Record<string, unknown>;
@@ -507,13 +654,15 @@ export declare class WorkflowCodeError extends Error {
507
654
  export declare class WorkflowStateError extends Error {
508
655
  readonly stage: string;
509
656
  readonly path: string;
510
- readonly reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict";
657
+ readonly reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key" | "route_missing" | "route_unknown" | "route_type";
511
658
  readonly code = "state_invalid";
512
- constructor(summary: string, stage: string, path: string, reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict");
659
+ constructor(summary: string, stage: string, path: string, reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key" | "route_missing" | "route_unknown" | "route_type");
513
660
  }
514
661
  export declare function stageSchemaForNode(workflow: Workflow, node: LlmNode): Record<string, unknown>;
515
662
  export declare const submissionSchemaForNode: typeof stageSchemaForNode;
516
663
  export declare function mergeStageDelta(state: Record<string, unknown>, node: LlmNode, result: Record<string, unknown>, schema: Record<string, unknown>): Record<string, unknown>;
664
+ /** The reserved state key host policy writes under. Engine-owned like every `$`-prefixed key: no node may name it. */
665
+ export declare const HOST_STATE_KEY = "$host";
517
666
  export declare class WorkflowVerificationError extends Error {
518
667
  readonly stage: string;
519
668
  readonly candidate: unknown;