testronaut 1.10.2 → 1.12.0

package/core/browserEvidence.js

@@ -0,0 +1,184 @@
+import * as cheerio from 'cheerio';
+
+function compact(value, maxLength = 160) {
+  const text = String(value ?? '').replace(/\s+/g, ' ').trim();
+  return text.length <= maxLength ? text : `${text.slice(0, maxLength)}…`;
+}
+
+function safeUrl(value) {
+  try {
+    const url = new URL(String(value));
+    return `${url.origin}${url.pathname}`;
+  } catch {
+    return compact(String(value ?? '').split(/[?#]/, 1)[0], 500) || null;
+  }
+}
+
+function unique(values, limit) {
+  return [...new Set(values.filter(Boolean))].slice(0, limit);
+}
+
+function controlLabel($, element) {
+  const node = $(element);
+  const id = node.attr('id');
+  const explicitLabel = id
+    ? $('label').filter((_, label) => $(label).attr('for') === id).first().text()
+    : '';
+  return compact(
+    node.attr('aria-label')
+      || explicitLabel
+      || node.closest('label').text()
+      || node.attr('placeholder')
+      || node.text(),
+    120,
+  );
+}
+
+function safeSelectorAttribute(value) {
+  return compact(value, 100).replace(/[^A-Za-z0-9_.:-]/g, '');
+}
+
+function selectorFor($, element, fallbackIndex) {
+  const node = $(element);
+  const id = safeSelectorAttribute(node.attr('id'));
+  if (id) return `#${id}`;
+  const tag = String(element.tagName || element.name || 'section').toLowerCase();
+  return `${tag}:nth-of-type(${fallbackIndex + 1})`;
+}
+
+/**
+ * Extract bounded, value-free evidence from a DOM snapshot already collected by
+ * Testronaut. Input values, query strings, hashes, and body text are omitted.
+ */
+export function buildBrowserEvidence(html, {
+  url,
+  previous = null,
+  redactText = value => String(value ?? ''),
+} = {}) {
+  const currentUrl = safeUrl(url) || previous?.url || null;
+  const routeChanged = Boolean(previous?.url && currentUrl && previous.url !== currentUrl);
+  const base = !routeChanged && previous ? { ...previous } : {};
+  const evidence = {
+    ...base,
+    url: currentUrl,
+    previousUrl: routeChanged ? previous.url : (previous?.previousUrl || null),
+    routeChanged,
+  };
+
+  if (typeof html !== 'string' || !html.includes('<')) return evidence;
+
+  const $ = cheerio.load(html);
+  const redact = value => compact(redactText(compact(value)), 160);
+  const headings = unique(
+    $('h1, h2, h3').map((_, element) => redact($(element).text())).get(),
+    12,
+  );
+  const controls = [];
+  $('button, a[href], input, select, textarea, [role="button"], [role="link"]').each((_, element) => {
+    if (controls.length >= 20) return;
+    const node = $(element);
+    const tag = String(element.tagName || element.name || '').toLowerCase();
+    const type = compact(node.attr('type'), 40);
+    controls.push({
+      tag,
+      ...(node.attr('role') ? { role: compact(node.attr('role'), 40) } : {}),
+      ...(type ? { type } : {}),
+      ...(controlLabel($, element) ? { label: redact(controlLabel($, element)) } : {}),
+      ...(node.attr('id') ? { id: safeSelectorAttribute(node.attr('id')) } : {}),
+      ...(node.attr('name') ? { name: safeSelectorAttribute(node.attr('name')) } : {}),
+      ...(node.attr('href') ? { href: safeUrl(node.attr('href')) } : {}),
+    });
+  });
+  const regions = [];
+  $('header, nav, main, aside, footer, form, table, [role="dialog"], [role="main"], [role="navigation"]').each((index, element) => {
+    if (regions.length >= 12) return;
+    const node = $(element);
+    const kind = node.attr('role') || String(element.tagName || element.name || 'region').toLowerCase();
+    const regionHeadings = unique(
+      node.find('h1, h2, h3').map((_, heading) => redact($(heading).text())).get(),
+      4,
+    );
+    const regionControls = unique(
+      node.find('button, a[href], input, select, textarea, [role="button"], [role="link"]')
+        .map((_, control) => redact(controlLabel($, control))).get(),
+      8,
+    );
+    regions.push({
+      id: `region_${regions.length + 1}`,
+      kind: compact(kind, 40),
+      selector: selectorFor($, element, index),
+      headings: regionHeadings,
+      controls: regionControls,
+      counts: {
+        headings: node.find('h1, h2, h3').length,
+        controls: node.find('button, a[href], input, select, textarea, [role="button"], [role="link"]').length,
+      },
+    });
+  });
+
+  return {
+    ...evidence,
+    title: redact($('title').first().text()),
+    headings,
+    controls,
+    regions,
+    counts: {
+      headings: $('h1, h2, h3').length,
+      forms: $('form').length,
+      buttons: $('button, [role="button"]').length,
+      links: $('a[href], [role="link"]').length,
+      inputs: $('input, select, textarea').length,
+    },
+  };
+}
+
+export function mergeBrowserControlState(evidence, states = []) {
+  if (!evidence || !Array.isArray(evidence.controls)) return evidence;
+  return {
+    ...evidence,
+    controls: evidence.controls.map((control, index) => {
+      const state = states[index];
+      if (!state) return control;
+      return {
+        ...control,
+        hasValue: Boolean(state.hasValue),
+        checked: Boolean(state.checked),
+        disabled: Boolean(state.disabled),
+        readOnly: Boolean(state.readOnly),
+        visible: Boolean(state.visible),
+      };
+    }),
+  };
+}
+
+/**
+ * Read only boolean control state from the live page. Values and value lengths
+ * never leave the browser context.
+ */
+export async function collectBrowserControlState(browser) {
+  try {
+    const locator = browser?.page?.locator?.(
+      'button, a[href], input, select, textarea, [role="button"], [role="link"]',
+    );
+    if (!locator?.evaluateAll) return [];
+    return await locator.evaluateAll(elements => elements.slice(0, 20).map(element => {
+      const tag = element.tagName.toLowerCase();
+      const style = getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      const supportsValue = tag === 'input' || tag === 'select' || tag === 'textarea';
+      const inputType = tag === 'input' ? String(element.type || '').toLowerCase() : '';
+      const supportsChecked = tag === 'input' && ['checkbox', 'radio'].includes(inputType);
+      return {
+        hasValue: supportsValue ? String(element.value ?? '').length > 0 : false,
+        checked: supportsChecked ? Boolean(element.checked) : false,
+        disabled: 'disabled' in element ? Boolean(element.disabled) : element.getAttribute('aria-disabled') === 'true',
+        readOnly: 'readOnly' in element ? Boolean(element.readOnly) : false,
+        visible: rect.width > 0 && rect.height > 0 && style.display !== 'none' && style.visibility !== 'hidden',
+      };
+    }));
+  } catch {
+    return [];
+  }
+}
+
+export const __browserEvidenceInternals = { compact, safeUrl };

package/core/jevRouting.js

@@ -0,0 +1,77 @@
+const DEFAULT_CONFIDENCE_THRESHOLD = 0.4;
+
+function probability(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1 ? parsed : fallback;
+}
+
+export function resolveJevRoutingConfig(env = process.env, { provider, primaryModel } = {}) {
+  const rawMode = String(env.TESTRONAUT_JEV_ROUTING || 'off').trim().toLowerCase();
+  const mode = ['shadow', 'live'].includes(rawMode) ? rawMode : 'off';
+  const providerKey = String(provider).toLowerCase();
+  const familyDefault = {
+    openai: 'gpt-5.6-luna',
+    gemini: 'gemini-3.5-flash-lite',
+    anthropic: 'claude-haiku-4-5',
+    claude: 'claude-haiku-4-5',
+  }[providerKey] || '';
+  const defaultFastModel = primaryModel === familyDefault ? '' : familyDefault;
+  return {
+    mode,
+    fastModel: String(env.TESTRONAUT_JEV_FAST_MODEL || defaultFastModel).trim(),
+    confidenceThreshold: probability(
+      env.TESTRONAUT_JEV_ROUTING_THRESHOLD,
+      DEFAULT_CONFIDENCE_THRESHOLD,
+    ),
+  };
+}
+
+function belongsToProvider(model, provider) {
+  const value = String(model || '').toLowerCase();
+  switch (String(provider || '').toLowerCase()) {
+    case 'openai': return /^(gpt-|o\d)/.test(value);
+    case 'gemini': return value.startsWith('gemini-');
+    case 'anthropic':
+    case 'claude': return value.startsWith('claude-');
+    default: return true;
+  }
+}
+
+export function chooseJevTurnModel(strategy, config, { provider, primaryModel } = {}) {
+  const route = strategy?.modelRoute;
+  const score = Number(route?.probabilities?.fast_model);
+  const confidence = Number(route?.confidence);
+  const recommendation = route?.choice || null;
+  const stage = strategy?.missionStage?.choice || null;
+  const recovery = strategy?.recovery?.choice || null;
+  const blockedReason =
+    config.mode === 'off' ? 'routing_off' :
+    recommendation !== 'fast_model' ? 'not_fast_model' :
+    !config.fastModel ? 'fast_model_unconfigured' :
+    !belongsToProvider(config.fastModel, provider) ? 'fast_model_provider_mismatch' :
+    config.fastModel === primaryModel ? 'fast_model_matches_primary' :
+    !Number.isFinite(score) || score < config.confidenceThreshold ? 'low_probability' :
+    ['authenticate', 'failed', 'complete'].includes(stage) ? `stage_${stage}` :
+    (recovery && recovery !== 'continue') ? `recovery_${recovery}` :
+    null;
+  const eligible = !blockedReason;
+  const applied = eligible && config.mode === 'live';
+
+  return {
+    mode: config.mode,
+    provider,
+    primaryModel,
+    fastModel: config.fastModel || null,
+    selectedModel: applied ? config.fastModel : primaryModel,
+    recommendation,
+    confidence: Number.isFinite(confidence) ? confidence : null,
+    score: Number.isFinite(score) ? score : null,
+    scoreType: 'fast_model_probability',
+    threshold: config.confidenceThreshold,
+    eligible,
+    applied,
+    reason: blockedReason || (applied ? 'jev_fast_model' : 'shadow_only'),
+  };
+}
+
+export const __jevRoutingInternals = { DEFAULT_CONFIDENCE_THRESHOLD, probability, belongsToProvider };

package/core/jevShadow.js

@@ -0,0 +1,325 @@
+const DEFAULT_API_BASE = 'https://api.typesafe.ai';
+const DEFAULT_MODEL = 'jev-latest';
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_GATE_THRESHOLD = 0.8;
+
+const SHADOW_QUESTIONS = {
+  missionComplete: {
+    type: 'noul',
+    instructions: 'Is there enough evidence that the stated browser-testing mission is complete?',
+    criteria: {
+      true: 'The goal is demonstrably satisfied by the current state or observed results.',
+      false: 'The goal is incomplete, failed, uncertain, or still requires verification.',
+    },
+  },
+  progressState: {
+    type: 'choice',
+    instructions: 'Classify the current progress of this browser-testing mission.',
+    criteria: {
+      complete: 'The mission is demonstrably complete.',
+      advancing: 'Recent actions made useful progress, but more work is required.',
+      stalled: 'The agent is repeating, blocked, or not making useful progress.',
+      failed: 'The available evidence shows the mission cannot or did not complete.',
+      uncertain: 'There is not enough evidence to classify progress reliably.',
+    },
+  },
+  nextCompute: {
+    type: 'choice',
+    instructions: 'What kind of computation should Testronaut use next?',
+    criteria: {
+      finish: 'No more browser-agent reasoning is needed.',
+      deterministic_action: 'A known browser action can run without generative reasoning.',
+      observe: 'More browser state should be collected before deciding.',
+      full_reasoning: 'A generative reasoning model is needed to decide or construct the next action.',
+      stop_failed: 'The mission should stop as failed rather than spend more tokens.',
+    },
+  },
+};
+
+const STRATEGY_QUESTIONS = {
+  modelRoute: {
+    type: 'choice',
+    instructions: 'Choose the least expensive reliable computation for the next turn.',
+    criteria: {
+      deterministic: 'The exact action and every required argument are already constructed in state; code can execute it directly.',
+      fast_model: 'The relevant control or local intent is apparent, but a short tool choice, known-value mapping, or localized inference is still needed.',
+      full_model: 'Multi-step planning, broad ambiguity, novel content, or difficult recovery requires frontier reasoning.',
+      observe: 'Collect more browser evidence before choosing.',
+      finish: 'The mission is complete and should finish.',
+    },
+  },
+  postconditionSatisfied: {
+    type: 'noul',
+    instructions: 'Did the most recent browser action satisfy its intended postcondition?',
+    criteria: {
+      true: 'Structured browser evidence shows the intended state change or result.',
+      false: 'The result is absent, contradicted, failed, or cannot yet be verified.',
+    },
+  },
+  recoveryRoute: {
+    type: 'choice',
+    instructions: 'Choose the best recovery policy for the current mission state.',
+    criteria: {
+      continue: 'Progress is healthy; continue normally.',
+      retry_action: 'Retry the most recent action once.',
+      reobserve: 'Refresh browser evidence before deciding.',
+      escalate: 'Use the full reasoning model to recover.',
+      stop_failed: 'Further work is unlikely to succeed; stop as failed.',
+    },
+  },
+  missionStage: {
+    type: 'choice',
+    instructions: 'Classify the current stage of this browser mission.',
+    criteria: {
+      setup: 'Preparing browser or initial state.',
+      navigate: 'Navigating to the target area.',
+      authenticate: 'Establishing or verifying authentication.',
+      interact: 'Performing the mission-specific user actions.',
+      verify: 'Checking that the requested outcome occurred.',
+      complete: 'The mission outcome is complete.',
+      failed: 'The mission cannot complete.',
+    },
+  },
+  prerequisiteSatisfied: {
+    type: 'noul',
+    instructions: 'Does the current browser state already satisfy the mission prerequisite or required starting state?',
+    criteria: {
+      true: 'The required session, route, and starting conditions are already present.',
+      false: 'Setup, navigation, authentication, or other prerequisite work remains.',
+    },
+  },
+};
+
+function truthy(value) {
+  return /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
+}
+
+function positiveInteger(value, fallback) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function probability(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1 ? parsed : fallback;
+}
+
+function trimTrailingSlash(value) {
+  return String(value || DEFAULT_API_BASE).replace(/\/+$/, '');
+}
+
+function compactText(value, maxLength = 2000) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value ?? '');
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength)}…[truncated ${text.length - maxLength} chars]`;
+}
+
+export function resolveJevShadowConfig(env = process.env) {
+  const gateEnabled = truthy(env.TESTRONAUT_JEV_GATE);
+  const routingEnabled = /^(shadow|live)$/i.test(String(env.TESTRONAUT_JEV_ROUTING || '').trim());
+  const strategiesEnabled = truthy(env.TESTRONAUT_JEV_STRATEGIES) || routingEnabled;
+  return {
+    enabled: truthy(env.TESTRONAUT_JEV_SHADOW) || gateEnabled || strategiesEnabled,
+    gateEnabled,
+    gateThreshold: probability(env.TESTRONAUT_JEV_GATE_THRESHOLD, DEFAULT_GATE_THRESHOLD),
+    strategiesEnabled,
+    apiKey: env.TESTRONAUT_JEV_API_KEY || env.TYPESAFE_API_KEY || env.JEV_API_KEY || '',
+    apiBase: trimTrailingSlash(env.TESTRONAUT_JEV_API_BASE || env.TYPESAFE_BASE_URL),
+    model: env.TESTRONAUT_JEV_MODEL || env.TYPESAFE_DEFAULT_MODEL || DEFAULT_MODEL,
+    timeoutMs: positiveInteger(env.TESTRONAUT_JEV_TIMEOUT_MS, DEFAULT_TIMEOUT_MS),
+  };
+}
+
+function actionDescription(control = {}) {
+  const selector = control.id ? `#${control.id}` : control.name ? `[name="${control.name}"]` : '';
+  const label = control.label ? ` “${control.label}”` : '';
+  const state = [
+    control.hasValue ? 'currently populated' : 'currently empty',
+    control.checked ? 'checked' : '',
+    control.disabled ? 'disabled' : 'enabled',
+    control.visible === false ? 'not visible' : 'visible',
+  ].filter(Boolean).join(', ');
+  if (['input', 'select', 'textarea'].includes(control.tag)) {
+    return `Fill or select ${control.tag}${label}${selector ? ` at ${selector}` : ''} using an already-known mission value. Control state: ${state}. Do not refill an already populated control unless replacement is required.`;
+  }
+  return `Click ${control.role || control.tag || 'control'}${label}${selector ? ` at ${selector}` : ''}. Control state: ${state}.`;
+}
+
+export function buildJevStrategyQuestions(browserEvidence = {}) {
+  const questions = { ...SHADOW_QUESTIONS, ...STRATEGY_QUESTIONS };
+  const regions = (browserEvidence.regions || []).slice(0, 12);
+  for (const region of regions) {
+    questions[`regionRelevant_${region.id}`] = {
+      type: 'noul',
+      instructions: `Is browser region ${region.id} relevant to deciding or executing the next mission action?`,
+      criteria: {
+        true: 'The region contains evidence or controls needed for the next action.',
+        false: 'The region can be omitted from the next generative-model context.',
+      },
+    };
+  }
+
+  const controls = (browserEvidence.controls || []).slice(0, 20);
+  const actionCriteria = {
+    observe: 'Collect more browser evidence before acting.',
+    full_reasoning: 'No listed action is safely executable without generative reasoning.',
+  };
+  controls.forEach((control, index) => {
+    actionCriteria[`action_${index + 1}`] = actionDescription(control);
+  });
+  if (controls.length) {
+    questions.actionChoice = {
+      type: 'choice',
+      instructions: 'Choose the safest next action for progressing the mission.',
+      criteria: actionCriteria,
+    };
+  }
+  return { questions, regions, controls };
+}
+
+export function extractJevStrategyResults(answers = {}, catalog = {}) {
+  const regionRelevance = (catalog.regions || []).map(region => ({
+    ...region,
+    probability: Number(answers[`regionRelevant_${region.id}`]?.noul),
+  }));
+  const actionAnswer = answers.actionChoice;
+  const actionIndex = String(actionAnswer?.choice || '').match(/^action_(\d+)$/)?.[1];
+  return {
+    domRelevance: regionRelevance,
+    actionChoice: actionAnswer ? {
+      ...actionAnswer,
+      selectedControl: actionIndex ? catalog.controls?.[Number(actionIndex) - 1] ?? null : null,
+    } : null,
+    modelRoute: answers.modelRoute ?? null,
+    verification: answers.postconditionSatisfied ?? null,
+    recovery: answers.recoveryRoute ?? null,
+    missionStage: answers.missionStage ?? null,
+    prerequisite: answers.prerequisiteSatisfied ?? null,
+  };
+}
+
+export function evaluateJevCompletionCandidate(result, {
+  threshold = DEFAULT_GATE_THRESHOLD,
+  browserEvidence,
+} = {}) {
+  const answers = result?.status === 'ok' ? result.answers : null;
+  const signals = {
+    missionComplete: Number(answers?.missionComplete?.noul),
+    progressComplete: Number(answers?.progressState?.probabilities?.complete),
+    finish: Number(answers?.nextCompute?.probabilities?.finish),
+  };
+  const hasBrowserEvidence = Boolean(
+    browserEvidence?.title
+      || browserEvidence?.headings?.length
+      || browserEvidence?.controls?.length,
+  );
+  const values = Object.values(signals);
+  return {
+    candidate: Boolean(
+      hasBrowserEvidence
+        && values.every(value => Number.isFinite(value) && value >= threshold),
+    ),
+    threshold,
+    hasBrowserEvidence,
+    signals,
+  };
+}
+
+export function buildJevShadowState({
+  mission,
+  turn,
+  maxTurns,
+  phase,
+  assistantSummary,
+  assistantContent,
+  proposedTools = [],
+  events = [],
+  groundControl,
+  browserEvidence,
+} = {}) {
+  return {
+    mission: compactText(mission, 3000),
+    turn: { current: Number(turn) + 1, maximum: maxTurns },
+    phase,
+    assistant: {
+      summary: compactText(assistantSummary, 1000),
+      content: compactText(assistantContent, 2000),
+      proposedTools: proposedTools.slice(0, 12).map(tool => ({
+        name: compactText(tool?.name, 120),
+        arguments: tool?.arguments,
+      })),
+    },
+    recentEvents: events.slice(-12).map(event => compactText(event, 500)),
+    groundControl: groundControl ?? null,
+    browserEvidence: browserEvidence ?? null,
+  };
+}
+
+export function sanitizeJevShadowEvents(events = [], redactText = value => String(value ?? '')) {
+  return events
+    .filter(event => !String(event).startsWith('[tool ] ←') || String(event).includes(' result:'))
+    .map(event => redactText(event));
+}
+
+export async function evaluateJevShadow(state, {
+  config = resolveJevShadowConfig(),
+  questions = SHADOW_QUESTIONS,
+  fetchImpl = globalThis.fetch,
+  now = () => Date.now(),
+} = {}) {
+  if (!config.enabled) return null;
+  if (!config.apiKey) {
+    return { status: 'skipped', reason: 'missing_api_key' };
+  }
+  if (typeof fetchImpl !== 'function') {
+    return { status: 'error', error: 'fetch_unavailable' };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+  const startedAt = now();
+
+  try {
+    const response = await fetchImpl(`${config.apiBase}/v1/systemone`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${config.apiKey}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        state,
+        model: config.model,
+        questions,
+      }),
+      signal: controller.signal,
+    });
+
+    const latencyMs = Math.max(0, now() - startedAt);
+    if (!response.ok) {
+      return {
+        status: 'error',
+        error: `http_${response.status}`,
+        latencyMs,
+      };
+    }
+
+    const payload = await response.json();
+    return {
+      status: 'ok',
+      model: payload.model,
+      answers: payload.answers,
+      usage: payload.usage,
+      latencyMs,
+    };
+  } catch (error) {
+    return {
+      status: 'error',
+      error: error?.name === 'AbortError' ? 'timeout' : compactText(error?.message || error, 300),
+      latencyMs: Math.max(0, now() - startedAt),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export const __jevShadowInternals = { SHADOW_QUESTIONS, compactText, truthy };

package/core/jevSuiteSelection.js

@@ -0,0 +1,39 @@
+export function buildJevSuiteSelectionRequest({ changedFiles = [], missions = [] } = {}) {
+  const catalog = missions.map((mission, index) => ({
+    id: `mission_${index + 1}`,
+    file: mission.file,
+    tags: mission.tags || [],
+  }));
+  const questions = {};
+  for (const mission of catalog) {
+    questions[`select_${mission.id}`] = {
+      type: 'noul',
+      instructions: `Should the test mission ${mission.file} be selected for this code change?`,
+      criteria: {
+        true: 'The changed files could affect behavior covered by this mission, directly or through shared dependencies.',
+        false: 'The mission is unrelated to the changed files and can be omitted from this targeted run.',
+      },
+    };
+  }
+  return {
+    state: {
+      task: 'Select relevant end-to-end test missions for a targeted CI run. Prefer coverage when uncertain.',
+      changedFiles,
+      missions: catalog,
+    },
+    questions,
+    catalog,
+  };
+}
+
+export function interpretJevSuiteSelection(answers = {}, catalog = [], threshold = 0.7) {
+  return catalog.map(mission => {
+    const probability = Number(answers[`select_${mission.id}`]?.noul);
+    return {
+      file: mission.file,
+      tags: mission.tags,
+      probability,
+      selected: Number.isFinite(probability) && probability >= threshold,
+    };
+  });
+}

package/core/jevUsage.js

@@ -0,0 +1,62 @@
+export const DEFAULT_JEV_INPUT_USD_PER_MILLION = 0.042;
+
+function nonNegativeNumber(value, fallback = 0) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : fallback;
+}
+
+export function resolveJevInputPrice(env = process.env) {
+  return nonNegativeNumber(
+    env.TESTRONAUT_JEV_INPUT_USD_PER_MILLION,
+    DEFAULT_JEV_INPUT_USD_PER_MILLION,
+  );
+}
+
+export function summarizeJevUsage(steps = [], {
+  inputUsdPerMillion = resolveJevInputPrice(),
+} = {}) {
+  const entries = (Array.isArray(steps) ? steps : [])
+    .map(step => step?.jevShadow)
+    .filter(Boolean);
+  const completed = entries.filter(entry => entry.status === 'ok');
+  const inputTokens = completed.reduce(
+    (sum, entry) => sum + nonNegativeNumber(entry.usage?.input_tokens),
+    0,
+  );
+  const outputTokens = completed.reduce(
+    (sum, entry) => sum + nonNegativeNumber(entry.usage?.output_tokens),
+    0,
+  );
+  const strategyEntries = completed.map(entry => entry.strategies).filter(Boolean);
+  const countChoices = (values) => values.reduce((counts, value) => {
+    if (value) counts[value] = (counts[value] || 0) + 1;
+    return counts;
+  }, {});
+  const regionDecisions = strategyEntries.flatMap(entry => entry.domRelevance || []);
+
+  return {
+    evaluations: entries.length,
+    completed: completed.length,
+    errors: entries.filter(entry => entry.status === 'error').length,
+    skipped: entries.filter(entry => entry.status === 'skipped').length,
+    inputTokens,
+    outputTokens,
+    latencyMs: completed.reduce((sum, entry) => sum + nonNegativeNumber(entry.latencyMs), 0),
+    completionCandidates: completed.filter(entry => entry.completionGate?.candidate).length,
+    triggeredCompletions: (Array.isArray(steps) ? steps : [])
+      .filter(step => step?.jevGate?.triggered).length,
+    inputUsdPerMillion,
+    estimatedInputCostUsd: inputTokens * inputUsdPerMillion / 1_000_000,
+    strategies: strategyEntries.length ? {
+      evaluations: strategyEntries.length,
+      modelRoutes: countChoices(strategyEntries.map(entry => entry.modelRoute?.choice)),
+      actionChoices: countChoices(strategyEntries.map(entry => entry.actionChoice?.choice)),
+      recoveryRoutes: countChoices(strategyEntries.map(entry => entry.recovery?.choice)),
+      missionStages: countChoices(strategyEntries.map(entry => entry.missionStage?.choice)),
+      verifiedPostconditions: strategyEntries.filter(entry => Number(entry.verification?.noul) >= 0.8).length,
+      satisfiedPrerequisites: strategyEntries.filter(entry => Number(entry.prerequisite?.noul) >= 0.8).length,
+      regionsEvaluated: regionDecisions.length,
+      relevantRegions: regionDecisions.filter(region => Number(region.probability) >= 0.5).length,
+    } : null,
+  };
+}