Skip to content
← Public packages

@kentcdodds/jev

Call TypeSafe Jev evaluations via Cloudflare AI Gateway (same token/gateway as @kentcdodds/ai).

FollowFork

Files

run-toward-goal.ts

342 lines · 8.9 KB · TypeScript
/**
 * 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
	}
}