@parcha/agentrun-dsl 0.1.0-beta.5 → 0.1.0-beta.9

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.
@@ -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>;
@@ -57,6 +60,9 @@ export type WorkflowNode = {
57
60
  thinking?: WorkflowThinking;
58
61
  verify?: VerifyClause;
59
62
  tier?: ModelTier;
63
+ /** The most the node asks to spend, in dollars. @exclusiveMinimum 0 */
64
+ budget_usd?: number;
65
+ context?: AgentContext;
60
66
  metadata?: NodeMetadata;
61
67
  } | {
62
68
  node: "decide";
@@ -119,6 +125,7 @@ export type WorkflowNode = {
119
125
  body: WorkflowNode;
120
126
  until: Predicate;
121
127
  maxIters: number;
128
+ expect_iters?: number;
122
129
  metadata?: NodeMetadata;
123
130
  } | {
124
131
  node: "escalate";
@@ -216,6 +223,8 @@ export type WorkflowInvocation = {
216
223
  /** `exit` is a shell command that ended with a non-zero status: retried only when the author
217
224
  * declared retry, since re-running a command is the author's call. */
218
225
  export type CallRetryClass = "timeout" | "http_5xx" | "http_429" | "connection" | "exit";
226
+ /** A failed effect's closed code (EFFECT_FAILURE_CODES). */
227
+ export type EffectFailureCode = typeof EFFECT_FAILURE_CODES[number];
219
228
  /** The workflow's terminal deliverable. Types "markdown" and "report" use the report
220
229
  * writer; other non-empty types name a workspace file produced by an earlier call.
221
230
  * File existence and delivery are the host's responsibility. */
@@ -284,10 +293,11 @@ export type CallNode = {
284
293
  produces?: string[];
285
294
  /** Wall bound in seconds for one execution. Required: an unbounded effect is how a stalled provider becomes a stalled job. */
286
295
  deadline_s: number;
296
+ /** `on` names retry classes or effect failure codes; absent, the transient retry classes. */
287
297
  retry?: {
288
298
  attempts: number;
289
299
  backoff_s?: number;
290
- on?: CallRetryClass[];
300
+ on?: (CallRetryClass | EffectFailureCode)[];
291
301
  };
292
302
  /** Repeat the call until its result settles (a queued job, an eventually consistent read). */
293
303
  poll?: PollClause;
@@ -298,6 +308,9 @@ export declare const SHELL_RESULT_SCHEMA: Record<string, unknown>;
298
308
  export type LlmNode = Extract<WorkflowNode, {
299
309
  node: "agent" | "decide" | "extract" | "report";
300
310
  }>;
311
+ export type CodeNode = Extract<WorkflowNode, {
312
+ node: "code";
313
+ }>;
301
314
  export declare const REPORT_SCHEMA: Record<string, unknown>;
302
315
  export type Workflow = {
303
316
  v: 2;
@@ -388,6 +401,10 @@ export type HostPolicy = {
388
401
  };
389
402
  export type WorkflowDeps = {
390
403
  maxQuestionsPerRequest?: number;
404
+ /** Most UTF-8 bytes of JSON state one judge request may carry (the Jev adapter's `maxStateBytes`
405
+ * measure). A `sift` that would exceed it, or `maxQuestionsPerRequest`, is split into several
406
+ * requests. Absent = no byte limit. */
407
+ maxStateBytesPerRequest?: number;
391
408
  /** Host application policy; see `HostPolicy`. Absent = the engine's own behavior, unchanged. */
392
409
  hostPolicy?: HostPolicy;
393
410
  runNode?: (params: {
@@ -412,6 +429,12 @@ export type WorkflowDeps = {
412
429
  message: string;
413
430
  }>;
414
431
  tier?: ModelTier;
432
+ /** An `agent` node's `budget_usd`: the most the node asks to spend, recorded; enforcement belongs to the host.
433
+ * No runner stops a run on money. A host may cap it by what it has left. */
434
+ budgetUsd?: number;
435
+ /** An `agent` node's `context`. `fork` asks the host to start the session from the caller's transcript;
436
+ * a host that has none to fork refuses it. */
437
+ context?: AgentContext;
415
438
  }) => Promise<unknown>;
416
439
  runEffect?: (params: {
417
440
  node: CallNode;
@@ -421,9 +444,25 @@ export type WorkflowDeps = {
421
444
  attempt: number;
422
445
  idempotencyKey: string;
423
446
  signal: AbortSignal;
447
+ /** The attempt's deadline instant on this process's `performance.now()` clock, exactly as the
448
+ * interpreter armed its deadline timer, so the host measures its own kill and duration against
449
+ * the instant the timer fires. Absent when the call has no deadline. */
450
+ deadlineAt?: number;
424
451
  item?: MapItem;
425
452
  executionPath?: string;
426
453
  }) => Promise<unknown>;
454
+ /** The host's executor for `code` nodes. Present, the interpreter hands it the node, the state and
455
+ * the context the transform would receive and uses what it resolves to as the transform's result
456
+ * (the same patch rules and state checks apply); a rejection fails the node as the host typed it.
457
+ * Absent, the interpreter compiles and runs the transform in this process (`compileTransform`),
458
+ * which is not a sandbox: a host that runs code from an untrusted author supplies this. */
459
+ runCode?: (node: CodeNode, state: Record<string, unknown>, ctx: {
460
+ sop: string;
461
+ label: string;
462
+ executionPath: string;
463
+ item?: MapItem;
464
+ signal?: AbortSignal;
465
+ }) => Promise<unknown>;
427
466
  runJudge?: (params: {
428
467
  label: string;
429
468
  kind: "judge" | "pick" | "sift" | "route" | "ask";
@@ -466,18 +505,31 @@ export type WorkflowDeps = {
466
505
  signal?: AbortSignal;
467
506
  /** Best-effort observation only: thrown errors and rejected promises are ignored.
468
507
  * Observers are never awaited. Use required checkpoints for durable lifecycle gates. */
469
- onEvent?: (event: {
470
- type: string;
471
- label: string;
472
- detail?: unknown;
473
- executionPath?: string;
474
- }) => void;
508
+ onEvent?: (event: WorkflowEvent) => void;
509
+ /** Trusted host boundary: return a detached snapshot without mutating the input.
510
+ * Runs before generic copying; undefined or thrown errors omit the event.
511
+ * Required trace validation cancels through the host signal, preserving execution cleanup. */
512
+ prepareEvent?: (event: WorkflowEvent) => WorkflowEvent | undefined;
513
+ };
514
+ export type WorkflowEvent = {
515
+ type: string;
516
+ label: string;
517
+ detail?: unknown;
518
+ executionPath?: string;
475
519
  };
476
520
  export declare const declaredWrites: (node: WorkflowNode | undefined) => Set<string>;
477
521
  export declare const childSteps: (child: Workflow | undefined) => WorkflowNode[] | null;
522
+ /** A failed effect: its retry class (null when the failure is not transient by nature), its closed code,
523
+ * and what the host observed (`detail`, written onto the attempt's `effect.failed` event). */
478
524
  export declare class EffectFailure extends Error {
479
525
  readonly retryClass: CallRetryClass | null;
480
- constructor(message: string, retryClass?: CallRetryClass | null);
526
+ readonly code: EffectFailureCode | null;
527
+ readonly detail?: Record<string, unknown>;
528
+ constructor(message: string, retryClass?: CallRetryClass | null, options?: {
529
+ code?: EffectFailureCode | null;
530
+ detail?: Record<string, unknown>;
531
+ cause?: unknown;
532
+ });
481
533
  }
482
534
  export declare function parseCsvRows(text: string): string[][];
483
535
  export declare function buildReferenceContext(files: Record<string, string>): {
@@ -492,9 +544,6 @@ export declare function workflowSha256(workflow: Workflow): string;
492
544
  /** Bound the complete document before any recursive schema or semantic traversal. Shared
493
545
  * objects are valid, but each occurrence consumes the budget; cycles are never JSON. */
494
546
  export declare function workflowDocumentError(value: unknown): string | undefined;
495
- /** Set executeCode:false for untrusted author feedback: check syntax and mechanical contracts
496
- * without evaluating authored expressions or probing transforms. This is not execution admission;
497
- * trusted/default validation and runtime output checks remain authoritative. */
498
547
  export declare function validateWorkflow(workflow: Workflow, opts?: {
499
548
  executeCode?: boolean;
500
549
  input?: Record<string, unknown>;