@agentrun/jev

Optional TypeSafe Jev support for AgentRun DSL. Jev answers focused questions with typed values and probability distributions. The workflow decides how to use them.

Requires Node.js 22.19 or later. This is a public-beta release candidate; package publication is pending.

After publication to npm:

npm install @agentrun/dsl @agentrun/jev
export TYPESAFE_API_KEY="your-key"

import { createJevRunner } from '@agentrun/jev';

const runJudge = createJevRunner();
// Supply runJudge alongside your other runWorkflow dependencies.
const result = await runJudge({
  label: 'triage',
  kind: 'judge',
  state: { ticket: 'I was charged twice.' },
  questions: {
    team: {
      type: 'choice',
      instructions: 'Which team should handle this ticket?',
      criteria: { billing: 'Invoices, payments, or refunds', other: 'Everything else' },
    },
  },
});
console.log(result.answers.team);

judge, pick, sift, route, semantic predicates, and judgment verification use the same runJudge adapter. Choice, Noul, and Score answers retain their raw probabilities. The core validates answer IDs, probability keys and normalization, score rubrics, and value ranges before consuming a result. A typed answer remains a model judgment, not proof that a real-world claim is true.

System One is TypeSafe's typed-question interface, exposed by the SDK as systemOne. A Noul answer is a truth probability from 0 to 1; the DSL converts probabilities of at least 0.5 to true and retains the probability beside that value. Choice and Score confidence comes from the response. Jev does not return a separate confidence for Noul; the DSL derives its own gate-strength value from the distance from 0.5, scaled to 0–1. These numbers are useful gate inputs, not calibrated guarantees.

The public adapter API is createJevRunner, JevError, and the types JevOptions, JevClient, JevErrorCode. The shared question, answer and distribution helpers live in @agentrun/dsl.

Configuration

const controller = new AbortController();
const runJudge = createJevRunner({
  timeoutMs: 30_000,       // Total budget, including retry waits.
  maxAttempts: 3,         // Includes the first attempt; maximum 10.
  retryBaseMs: 500,
  retryMaxMs: 5_000,
  signal: controller.signal,
});

The official @typesafe-ai/sdk resolves TYPESAFE_API_KEY and TYPESAFE_BASE_URL. Explicit apiKey and baseURL options take precedence. An API root ends before /v1/systemone. Set fetch for a custom transport, or supply a client with a systemOne(request, options) method. A custom client must honor the request signal and disable its own retries; it owns its credentials and cannot be combined with transport options.

The adapter owns retries: transient HTTP 408, 429, 5xx responses and connection failures retry with bounded exponential delays. SDK retries are disabled. Validation failures and other HTTP errors do not retry. The deadline and either the runner or per-call signal interrupt both requests and backoff. Cancellation bounds when the adapter returns; an uncooperative custom client can still continue its own work.

Request state is limited to 48 KiB of serialized UTF-8 JSON. The core allows up to 240 options per choice and 2–10 levels per score rubric. Adapter timeouts are positive integer milliseconds up to 2,147,483,647; retry delays may also be zero. maxAttempts is 1–10, with a default of 3.

JevError provides a stable code, attempts, and optional HTTP status. Errors deliberately omit raw service bodies, headers, input state, and causes. SDK logging is disabled. Custom clients and transports own their own logging. Do not expose credentials in browser code.

Successful results retain answers, reported model, reported token usage, and a SHA-256 of the submitted request. cost_usd is null unless both usage and explicit pricing: { inputUsdPerMillionTokens, outputUsdPerMillionTokens } are available. Configured prices produce an estimate for the successful response; costs from unsuccessful or interrupted attempts are unknown.

Offline tests

From the repository root, run npm run build and npm test -w @agentrun/jev. Tests inject fake HTTP responses and do not load provider credentials or call a model.

Use Jev from an existing agent loop

The movie decision tool composes actual judge, route, sift, and pick nodes behind one callable function. Register that function as a tool in your existing host. The host keeps the agent loop, tool permissions, and writing; Jev supplies the typed judgments.