agent@agentrun/dsl
Composable, typed workflows for agents. The core provides the v2 workflow types, validator, interpreter, events, schema, and an offline CLI. Supply agent, judgment, and effect functions only when a workflow needs them.
This is an unpublished 0.1.0-beta.1 candidate. Requires Node 22.19+; TypeScript consumers require TypeScript 5.4+.
import { runTriageDemo } from '@agentrun/dsl/demo';
const { result } = await runTriageDemo('billing');
console.log(result.output); // { queue: 'billing', priority: 'normal' }
The demo runs real control flow with scripted judgments. ambiguous escalates. No model SDK or API key is required by the core. Optional @agentrun/jev and @agentrun/pi adapters add live judgments and agent steps.
The agentrun CLI provides demo, example, inspect, validate, dry-run, and deterministic run. inspect workflow.json [--json] displays structure without executing code. Validation/run require --trusted because workflow JavaScript can execute, including during validation. This package is not an isolation boundary.
runWorkflow(workflow, input, deps) returns a complete schema-validated output or an escalation; its TypeScript output type is unknown. defineWorkflow binds Standard JSON Schema contracts, including supported Zod schemas, to a frozen v2 document; runTypedWorkflow infers those input/output types and delegates to the same interpreter. Intermediate state paths remain runtime-validated. Execution and verification failures throw. Hosts own tools, durable storage, file delivery, idempotency, recovery, and activation.
Raw JSON schemas retain unknown boundary types. Zod transforms, refinements, defaults and coercion are rejected rather than silently dropped. The core does not depend on Zod at runtime. Other Standard JSON Schema providers must faithfully represent their contracts. Typed execution accepts the original defineWorkflow result; copied or deserialized documents use runWorkflow.
Public API
The package root exports a deliberate API. The beta retains agent, structured-output, report, artifact, effect, child-workflow and focused-evaluation paths. Hosts supply their adapters and policy; a workflow cannot grant itself tool permissions.
| Group | Exports and purpose |
|---|---|
| Typed authoring | defineWorkflow, runTypedWorkflow, WorkflowSchemaConversionError; StandardJSONSchema, AuthoringSchema, TypedWorkflow, WorkflowInput, WorkflowOutput, TypedWorkflowRunResult. |
| Structural inspection | inspectWorkflow, formatWorkflowTree; WorkflowInspection, WorkflowInspectionNode. Reads structure and capability requirements; does not perform semantic validation or run code probes. |
| Run and inspect | runWorkflow, validateWorkflow, workflowSha256, dryRunWorkflow; core contracts Workflow, WorkflowNode, WorkflowDeps, WorkflowRunResult, plus the named node, predicate, effect, effort and result types. |
| Recognize outcomes | WorkflowInvalidError, WorkflowInputInvalidError, WorkflowOutputInvalidError, WorkflowVerificationError, EffectFailure, EffectDeadlineExceededError, EffectOutcomeUnknownError, EscalationSignal. A concurrent failure may contain typed outcomes in AggregateError.errors; inspect them before deciding whether an effect is safe to retry. |
| Build judgment adapters | compileQuestions, validateAnswers, answersToValue, answersSidecar, answerConfidence, SYSTEM_ONE_LIMITS, SystemOneError; SystemOneQuestion, SystemOneAnswer, SystemOneResult, SystemOneRetryClass, CompiledQuestions, AnswersSidecar. |
| Integrate a host | runWorkflowSlice, assertWorkflowCapabilities, desugarWorkflow, resolveSchemaForWorkflow, stageSchemaForNode, submissionSchemaForNode, mergeStageDelta, REPORT_SCHEMA, SHELL_RESULT_SCHEMA, getPath, predicateMatches. |
| Test without a model | synthesizeInstance, synthesizeAnswers, DryRunOptions, DryRunResult. Synthetic answers exercise execution mechanics; they do not establish judgment quality. |
runWorkflowSlice runs selected root steps against supplied state and optional seed data. It returns the slice state without checking the full workflow's terminal output contract. Use runWorkflow for a complete run. getPath reads dot-separated record keys, returning undefined when the path leaves an object. predicateMatches evaluates mechanical predicates only; use field_equals with an explicit path for a stored label.
The schema helpers resolve the owning workflow's schema catalog; stageSchemaForNode and submissionSchemaForNode name the same submission contract. mergeStageDelta stores declared submission fields under the node's output key; callers must validate the submission first. Internal traversal, compilation, CSV, reference-file and input-normalization helpers are not package-root APIs.
The separate @agentrun/dsl/demo entrypoint provides the support-triage example. @agentrun/dsl/schema provides the generated workflow JSON Schema.
Children can contain maps, loops, routes, parallel branches and other children, and appear inside those structures. Their input/state and schema catalogs stay isolated; terminal report/artifact delivery remains parent-owned. New composed structures require path-aware recovery stores when recovery is enabled. executionPath is supplied to adapters, events and checkpoint/recovery hooks. Existing host validators and durable-cursor limits remain authoritative.
Bounds
These are the current beta's validation limits. Hosts may impose tighter budgets; the bounds below are not configurable unless an override is named.
| Setting | Bound |
|---|---|
| Document traversal | At most 100,000 visited values and 128 levels of object nesting; cycles, accessors and proxies rejected |
loop.maxIters |
Integer 1–20 |
verify.maxDrives |
Integer 1–4; default 2 |
call.deadline_s |
Greater than 0 and at most 3,600 seconds |
call.retry.attempts |
Integer 1–5, including the first attempt |
call.poll.interval_s |
0.1–300 seconds |
call.poll.deadline_s |
At least the call deadline and at most 7,200 seconds |
| Choice options / route branches | At most 240; pick.allowNone reserves one option |
| Score rubric | 2–10 levels, indexed from 0 |
| Questions per judgment request | Default 256; override with host-owned WorkflowDeps.maxQuestionsPerRequest |
| Jev state | At most 48 KiB of serialized UTF-8 JSON per request |
The question-count guard applies after collection expansion, including sift items multiplied by their questions. It is a host budget guard, not a claim about a provider's service limit.
System One names TypeSafe's typed-question interface used by the judgment types. A noul answer is a truth probability from 0 to 1; answersToValue turns values at least 0.5 into true. Choice and score confidence comes from the adapter response; Noul confidence is 2 × |probability − 0.5|. Neither is a calibration guarantee.