@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.
- package/README.md +15 -10
- package/dist/author.js +13 -8
- package/dist/code-exec.d.ts +6 -0
- package/dist/code-exec.js +126 -0
- package/dist/dry-run.d.ts +4 -1
- package/dist/dry-run.js +2 -1
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2 -2
- package/dist/long-timer.d.ts +7 -0
- package/dist/long-timer.js +22 -0
- package/dist/observer-snapshot.d.ts +3 -0
- package/dist/observer-snapshot.js +46 -0
- package/dist/system-one.js +28 -2
- package/dist/vocabulary.d.ts +8 -0
- package/dist/vocabulary.js +13 -2
- package/dist/workflow-shape.js +1 -1
- package/dist/workflow.d.ts +60 -11
- package/dist/workflow.js +210 -51
- package/package.json +1 -1
- package/schema/workflow.schema.json +38 -13
- package/skills/author/references/language.md +11 -9
package/dist/workflow.d.ts
CHANGED
|
@@ -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
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
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
|
-
|
|
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>;
|