/** * 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 = { 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 { 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 = { [event]: 1 } const answers: Record = { [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, } }