← Public packages
@kentcdodds/jev
Call TypeSafe Jev evaluations via Cloudflare AI Gateway (same token/gateway as @kentcdodds/ai).
Files
/**
* Walk a declarative state machine toward a goal by repeatedly calling
* `./choose-transition` on enabled events. Chat authors the machine; this
* runner executes it (no XState runtime).
*
* @param input.machine - Declarative machine (`initial` + `states` with `on`).
* @param input.goal - Desired outcome / what we are trying to achieve.
* @param input.context - Optional context passed into choose-transition state.
* @param input.maxSteps - Max transitions (default 20).
* @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, path, finalState, stoppedReason }` — never logs secrets.
*
* @example
* import runTowardGoal from 'kody:@kentcdodds/jev/run-toward-goal'
*
* const result = await runTowardGoal({
* machine: {
* id: 'checkout',
* initial: 'idle',
* states: {
* idle: { on: { START: 'awaitingPayment' } },
* awaitingPayment: {
* description: 'Waiting for payment',
* on: {
* PAID: { target: 'done', description: 'Payment succeeded' },
* FAIL: 'failed',
* },
* },
* done: { type: 'final', description: 'Order complete' },
* failed: { type: 'final', description: 'Payment failed' },
* },
* },
* goal: 'Complete checkout after payment succeeds',
* })
* // => { ok, path, finalState, stoppedReason }
*/
import chooseTransition from './choose-transition.ts'
import type {
DeclarativeMachine,
DeclarativeTransition,
RunTowardGoalInput,
RunTowardGoalPathStep,
RunTowardGoalResult,
TransitionEvents,
} from './types.ts'
const DEFAULT_MAX_STEPS = 20
function isRecord(value: unknown): value is Record<string, unknown> {
return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
}
function resolveTarget(transition: DeclarativeTransition): string | null {
if (typeof transition === 'string') {
const target = transition.trim()
return target || null
}
if (isRecord(transition) && typeof transition.target === 'string') {
const target = transition.target.trim()
return target || null
}
return null
}
function resolveEventDescription(
eventId: string,
transition: DeclarativeTransition,
machine: DeclarativeMachine,
): string {
if (isRecord(transition) && typeof transition.description === 'string') {
const desc = transition.description.trim()
if (desc) return desc
}
const target = resolveTarget(transition)
if (target) {
const targetState = machine.states?.[target]
if (
targetState &&
typeof targetState.description === 'string' &&
targetState.description.trim()
) {
return targetState.description.trim()
}
}
return eventId
}
function enabledEventsForState(
machine: DeclarativeMachine,
stateName: string,
): {
events: TransitionEvents
targets: Record<string, string>
} {
const stateNode = machine.states?.[stateName]
const on = stateNode?.on
const events: Record<string, string> = {}
const targets: Record<string, string> = {}
if (!on || !isRecord(on)) {
return { events, targets }
}
for (const [eventId, transition] of Object.entries(on)) {
const id = typeof eventId === 'string' ? eventId.trim() : ''
if (!id) continue
const target = resolveTarget(transition as DeclarativeTransition)
if (!target) continue
events[id] = resolveEventDescription(
id,
transition as DeclarativeTransition,
machine,
)
targets[id] = target
}
return { events, targets }
}
function failure(
path: RunTowardGoalPathStep[],
finalState: string,
error: string,
extra?: {
status?: number
setup?: {
secretsNewUrl?: string
settingsHint?: string
}
},
): RunTowardGoalResult {
return {
ok: false,
path,
finalState,
stoppedReason: 'error',
error,
...(extra?.status !== undefined ? { status: extra.status } : {}),
...(extra?.setup ? { setup: extra.setup } : {}),
}
}
/**
* Walk a declarative state machine toward a goal by repeatedly calling
* `./choose-transition` on enabled events. Chat authors the machine; this
* runner executes it (no XState runtime).
*
* @param input.machine - Declarative machine (`initial` + `states` with `on`).
* @param input.goal - Desired outcome / what we are trying to achieve.
* @param input.context - Optional context passed into choose-transition state.
* @param input.maxSteps - Max transitions (default 20).
* @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, path, finalState, stoppedReason }` — never logs secrets.
*
* @example
* import runTowardGoal from 'kody:@kentcdodds/jev/run-toward-goal'
*
* const result = await runTowardGoal({
* machine: {
* id: 'checkout',
* initial: 'idle',
* states: {
* idle: { on: { START: 'awaitingPayment' } },
* awaitingPayment: {
* description: 'Waiting for payment',
* on: {
* PAID: { target: 'done', description: 'Payment succeeded' },
* FAIL: 'failed',
* },
* },
* done: { type: 'final', description: 'Order complete' },
* failed: { type: 'final', description: 'Payment failed' },
* },
* },
* goal: 'Complete checkout after payment succeeds',
* })
* // => { ok, path, finalState, stoppedReason }
*/
export default async function runTowardGoal(
input: RunTowardGoalInput,
): Promise<RunTowardGoalResult> {
if (!input || typeof input.goal !== 'string' || !input.goal.trim()) {
return failure([], '', 'goal is required (non-empty string)')
}
const machine = input.machine
if (!machine || !isRecord(machine)) {
return failure([], '', 'machine is required (declarative { initial, states })')
}
if (typeof machine.initial !== 'string' || !machine.initial.trim()) {
return failure([], '', 'machine.initial is required (non-empty state name)')
}
if (!machine.states || !isRecord(machine.states)) {
return failure([], '', 'machine.states is required (map of state nodes)')
}
const initial = machine.initial.trim()
if (!machine.states[initial]) {
return failure(
[],
initial,
`machine.initial "${initial}" is not defined in machine.states`,
)
}
const maxStepsRaw = input.maxSteps
const maxSteps =
typeof maxStepsRaw === 'number' &&
Number.isFinite(maxStepsRaw) &&
maxStepsRaw > 0
? Math.floor(maxStepsRaw)
: DEFAULT_MAX_STEPS
const path: RunTowardGoalPathStep[] = []
let current = initial
const visited = new Set<string>([current])
let lastEvent: string | null = null
while (true) {
const stateNode = machine.states[current]
if (!stateNode) {
return failure(
path,
current,
`state "${current}" is not defined in machine.states`,
)
}
if (stateNode.type === 'final') {
return {
ok: true,
path,
finalState: current,
stoppedReason: 'final',
}
}
const { events, targets } = enabledEventsForState(machine, current)
const eventIds = Object.keys(events)
if (eventIds.length === 0) {
return {
ok: true,
path,
finalState: current,
stoppedReason: 'noEvents',
}
}
if (path.length >= maxSteps) {
return {
ok: true,
path,
finalState: current,
stoppedReason: 'maxSteps',
}
}
const machineId =
typeof machine.id === 'string' && machine.id.trim()
? machine.id.trim()
: undefined
const choiceState: Record<string, unknown> = {
value: current,
}
if (input.context !== undefined) {
choiceState.context = input.context
}
if (machineId) {
choiceState.machineId = machineId
}
const choice = await chooseTransition({
state: choiceState,
goal: input.goal,
events,
context: input.context,
accountId: input.accountId,
gatewayId: input.gatewayId,
model: input.model,
})
if (!choice.ok) {
return failure(path, current, choice.error, {
status: choice.status,
setup: choice.setup,
})
}
const event = choice.event
const target = targets[event]
if (!target) {
return failure(
path,
current,
`chosen event "${event}" has no resolvable target from state "${current}"`,
)
}
if (!machine.states[target]) {
return failure(
path,
current,
`transition "${current}" —${event}→ "${target}" targets an undefined state`,
)
}
const step: RunTowardGoalPathStep = {
state: current,
event,
confidence: choice.confidence,
shortCircuited: choice.shortCircuited === true,
}
path.push(step)
// Same (state, event) fired consecutively without leaving → cycle.
if (target === current && lastEvent === event) {
return {
ok: true,
path,
finalState: current,
stoppedReason: 'cycle',
}
}
// Revisit a state we already left → cycle.
if (target !== current && visited.has(target)) {
return {
ok: true,
path,
finalState: target,
stoppedReason: 'cycle',
}
}
visited.add(target)
lastEvent = event
current = target
}
}