/** * 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 { 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 } { const stateNode = machine.states?.[stateName] const on = stateNode?.on const events: Record = {} const targets: Record = {} 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 { 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([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 = { 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 } }