← Public packages
@kentcdodds/jev
Call TypeSafe Jev evaluations via Cloudflare AI Gateway (same token/gateway as @kentcdodds/ai).
Files
/**
* Pick the next state-machine transition with TypeSafe Jev.
* Model agent logic as a state machine: give Jev the state + goal; enabled
* events become Choices (pattern credit: David Khourshid / Stately).
*
* Single enabled event short-circuits without calling Jev (confidence 1).
* Zero events returns a clear error. Multi-event builds a `choice` question
* and calls `./evaluate`.
*
* @param input.state - Current machine/agent state snapshot (string or serializable object; XState `{ value, context? }` is fine).
* @param input.goal - Desired outcome / what we are trying to achieve.
* @param input.events - Enabled events as id→description map or `{ id, description }[]`.
* @param input.context - Optional extra blob merged into the evaluate state.
* @param input.accountId - Optional Cloudflare account id override.
* @param input.gatewayId - Optional AI Gateway id override.
* @param input.model - Optional model id (default `typesafe/jev`).
* @returns `{ ok, event, confidence, probabilities, answers, model, usage }` — never logs secrets.
*
* @example
* import chooseTransition from 'kody:@kentcdodds/jev/choose-transition'
*
* const result = await chooseTransition({
* state: { value: 'awaitingPayment', context: { retries: 1 } },
* goal: 'Collect payment or escalate if stuck',
* events: {
* RETRY: 'Retry the payment charge',
* ESCALATE: 'Notify a human operator',
* CANCEL: 'Cancel the order',
* },
* })
* // => { ok: true, event: 'RETRY', confidence, probabilities, ... }
*/
import evaluate from './evaluate.ts'
import buildChoiceFromEvents, {
normalizeTransitionEvents,
} from './build-choice-from-events.ts'
import type {
Answer,
ChoiceAnswer,
ChooseTransitionInput,
ChooseTransitionResult,
JevState,
JevUsage,
TransitionEvents,
} from './types.ts'
import { DEFAULT_JEV_MODEL } from './types.ts'
const QUESTION_KEY = 'transition'
function isChoiceAnswer(answer: Answer | undefined): answer is ChoiceAnswer {
return Boolean(answer && answer.type === 'choice' && typeof answer.choice === 'string')
}
function buildEvaluateState(input: ChooseTransitionInput): JevState {
const blob: Record<string, unknown> = {
goal: input.goal,
machineState: input.state,
}
if (input.context !== undefined) {
blob.context = input.context
}
return blob
}
/**
* Pick the next state-machine transition with TypeSafe Jev.
* Model agent logic as a state machine: give Jev the state + goal; enabled
* events become Choices (pattern credit: David Khourshid / Stately).
*
* Single enabled event short-circuits without calling Jev (confidence 1).
* Zero events returns a clear error. Multi-event builds a `choice` question
* and calls `./evaluate`.
*
* @param input.state - Current machine/agent state snapshot (string or serializable object; XState `{ value, context? }` is fine).
* @param input.goal - Desired outcome / what we are trying to achieve.
* @param input.events - Enabled events as id→description map or `{ id, description }[]`.
* @param input.context - Optional extra blob merged into the evaluate state.
* @param input.accountId - Optional Cloudflare account id override.
* @param input.gatewayId - Optional AI Gateway id override.
* @param input.model - Optional model id (default `typesafe/jev`).
* @returns `{ ok, event, confidence, probabilities, answers, model, usage }` — never logs secrets.
*
* @example
* import chooseTransition from 'kody:@kentcdodds/jev/choose-transition'
*
* const result = await chooseTransition({
* state: { value: 'awaitingPayment', context: { retries: 1 } },
* goal: 'Collect payment or escalate if stuck',
* events: {
* RETRY: 'Retry the payment charge',
* ESCALATE: 'Notify a human operator',
* CANCEL: 'Cancel the order',
* },
* })
* // => { ok: true, event: 'RETRY', confidence, probabilities, ... }
*/
export default async function chooseTransition(
input: ChooseTransitionInput,
): Promise<ChooseTransitionResult> {
if (!input || typeof input.goal !== 'string' || !input.goal.trim()) {
return {
ok: false,
error: 'goal is required (non-empty string describing the desired outcome)',
}
}
if (input.state === undefined || input.state === null) {
return {
ok: false,
error: 'state is required (current machine/agent snapshot)',
}
}
const criteria = normalizeTransitionEvents(input.events as TransitionEvents)
const eventIds = Object.keys(criteria)
if (eventIds.length === 0) {
return {
ok: false,
error:
'events is empty — pass at least one enabled event (id → description) as Choices',
}
}
// Single enabled event: no model call; confidence 1.
if (eventIds.length === 1) {
const event = eventIds[0]
const probabilities: Record<string, number> = { [event]: 1 }
const answers: Record<string, Answer> = {
[QUESTION_KEY]: {
type: 'choice',
choice: event,
confidence: 1,
probabilities,
},
}
return {
ok: true,
event,
confidence: 1,
probabilities,
answers,
model: input.model?.trim() || DEFAULT_JEV_MODEL,
usage: undefined,
shortCircuited: true,
}
}
const { questions } = buildChoiceFromEvents(criteria, {
questionKey: QUESTION_KEY,
instructions:
'Given the goal and current machine state, which enabled event should fire next? Pick exactly one.',
})
const result = await evaluate({
state: buildEvaluateState(input),
questions,
accountId: input.accountId,
gatewayId: input.gatewayId,
model: input.model,
})
if (!result.ok) {
return {
ok: false,
status: result.status,
error: result.error,
setup: result.setup,
}
}
const answer = result.answers[QUESTION_KEY]
if (!isChoiceAnswer(answer)) {
return {
ok: false,
status: result.status,
error:
'Jev returned no choice answer for transition — check events criteria and response shape',
answers: result.answers,
model: result.model,
usage: result.usage,
}
}
const event = answer.choice
if (!criteria[event]) {
return {
ok: false,
status: result.status,
error: `Jev chose "${event}" which is not in the enabled events list`,
answers: result.answers,
model: result.model,
usage: result.usage,
}
}
return {
ok: true,
event,
confidence: typeof answer.confidence === 'number' ? answer.confidence : 0,
probabilities: answer.probabilities || {},
answers: result.answers,
model: result.model,
usage: result.usage as JevUsage | undefined,
shortCircuited: false,
meta: result.meta,
}
}