@ljoukov/llm 3.0.8 → 3.0.11

package/dist/index.js

@@ -121,6 +121,15 @@ var GEMINI_2_5_PRO_PRICING = {
   outputRateLow: 10 / 1e6,
   outputRateHigh: 15 / 1e6
 };
+var GEMINI_2_5_FLASH_PRICING = {
+  threshold: 2e5,
+  inputRateLow: 0.3 / 1e6,
+  inputRateHigh: 0.3 / 1e6,
+  cachedRateLow: 0.03 / 1e6,
+  cachedRateHigh: 0.03 / 1e6,
+  outputRateLow: 2.5 / 1e6,
+  outputRateHigh: 2.5 / 1e6
+};
 var GEMINI_IMAGE_PREVIEW_PRICING = {
   inputRate: 2 / 1e6,
   cachedRate: 0.2 / 1e6,
@@ -136,6 +145,9 @@ function getGeminiProPricing(modelId) {
   if (modelId.includes("gemini-2.5-pro")) {
     return GEMINI_2_5_PRO_PRICING;
   }
+  if (modelId.includes("gemini-2.5-flash") || modelId.includes("gemini-flash-latest")) {
+    return GEMINI_2_5_FLASH_PRICING;
+  }
   if (modelId.includes("gemini-3-pro") || modelId.includes("gemini-3.1-pro")) {
     return GEMINI_3_PRO_PREVIEW_PRICING;
   }
@@ -2100,7 +2112,10 @@ var GEMINI_TEXT_MODEL_IDS = [
   "gemini-flash-latest",
   "gemini-flash-lite-latest"
 ];
-var GEMINI_IMAGE_MODEL_IDS = ["gemini-3-pro-image-preview"];
+var GEMINI_IMAGE_MODEL_IDS = [
+  "gemini-3-pro-image-preview",
+  "gemini-3.1-flash-image-preview"
+];
 var GEMINI_MODEL_IDS = [...GEMINI_TEXT_MODEL_IDS, ...GEMINI_IMAGE_MODEL_IDS];
 function isGeminiModelId(value) {
   return GEMINI_MODEL_IDS.includes(value);
@@ -2573,12 +2588,7 @@ async function runOpenAiCall(fn, modelId, runOptions) {
 }
 
 // src/openai/models.ts
-var OPENAI_MODEL_IDS = [
-  "gpt-5.3-codex",
-  "gpt-5.3-codex-spark",
-  "gpt-5.2",
-  "gpt-5.1-codex-mini"
-];
+var OPENAI_MODEL_IDS = ["gpt-5.3-codex", "gpt-5.2", "gpt-5.1-codex-mini"];
 function isOpenAiModelId(value) {
   return OPENAI_MODEL_IDS.includes(value);
 }
@@ -4250,6 +4260,9 @@ function extractFireworksToolCalls(message) {
   return calls;
 }
 function resolveGeminiThinkingConfig(modelId) {
+  if (isGeminiImageModelId(modelId)) {
+    return void 0;
+  }
   switch (modelId) {
     case "gemini-3-pro-preview":
     case "gemini-3.1-pro-preview":
@@ -4505,9 +4518,10 @@ async function runTextCall(params) {
     }, modelForProvider);
   } else {
     const geminiContents = contents.map(convertLlmContentToGeminiContent);
+    const thinkingConfig = resolveGeminiThinkingConfig(modelForProvider);
     const config = {
       maxOutputTokens: 32e3,
-      thinkingConfig: resolveGeminiThinkingConfig(modelForProvider),
+      ...thinkingConfig ? { thinkingConfig } : {},
       ...request.responseMimeType ? { responseMimeType: request.responseMimeType } : {},
       ...request.responseJsonSchema ? { responseJsonSchema: request.responseJsonSchema } : {},
       ...request.responseModalities ? { responseModalities: Array.from(request.responseModalities) } : {},
@@ -5735,6 +5749,7 @@ async function runToolLoop(request) {
           firstModelEventAtMs = Date.now();
         }
       };
+      const thinkingConfig = resolveGeminiThinkingConfig(request.model);
       const config = {
         maxOutputTokens: 32e3,
         tools: geminiTools,
@@ -5743,7 +5758,7 @@ async function runToolLoop(request) {
             mode: FunctionCallingConfigMode.VALIDATED
           }
         },
-        thinkingConfig: resolveGeminiThinkingConfig(request.model)
+        ...thinkingConfig ? { thinkingConfig } : {}
       };
       const onEvent = request.onEvent;
       const response = await runGeminiCall(
@@ -9335,6 +9350,659 @@ function createAgentTelemetryEmitter(params) {
     });
   };
 }
+
+// src/agent/candidateEvolution.ts
+import { randomBytes as randomBytes4 } from "crypto";
+var DEFAULT_BATCH_SIZE = 1;
+var DEFAULT_GENERATION_CONCURRENCY = 8;
+var DEFAULT_ASSESSMENT_CONCURRENCY = 8;
+var DEFAULT_SHARPNESS = 10;
+var DEFAULT_NOVELTY_WEIGHT = 1;
+var DEFAULT_MIDPOINT = { mode: "percentile", percentile: 75 };
+var DEFAULT_FEEDBACK_SCOPE = { mode: "ancestors" };
+var DEFAULT_SCORE_PERCENTILES = [0, 25, 50, 75, 90, 95, 100];
+function createEmptyStats() {
+  return {
+    generationCalls: 0,
+    issuesSupplied: 0,
+    proposalsGenerated: 0,
+    proposalsAfterPostCheck: 0,
+    assessmentCalls: 0,
+    postCheckCalls: 0,
+    feedbackEntriesSupplied: 0
+  };
+}
+function addStats(left, right) {
+  return {
+    generationCalls: left.generationCalls + right.generationCalls,
+    issuesSupplied: left.issuesSupplied + right.issuesSupplied,
+    proposalsGenerated: left.proposalsGenerated + right.proposalsGenerated,
+    proposalsAfterPostCheck: left.proposalsAfterPostCheck + right.proposalsAfterPostCheck,
+    assessmentCalls: left.assessmentCalls + right.assessmentCalls,
+    postCheckCalls: left.postCheckCalls + right.postCheckCalls,
+    feedbackEntriesSupplied: left.feedbackEntriesSupplied + right.feedbackEntriesSupplied
+  };
+}
+function randomId(prefix) {
+  return `${prefix}_${randomBytes4(8).toString("hex")}`;
+}
+function toFiniteNumber(value, fallback) {
+  if (!Number.isFinite(value)) {
+    return fallback;
+  }
+  return value;
+}
+function normalizeRandom(random) {
+  if (!random) {
+    return () => Math.random();
+  }
+  return () => {
+    const value = toFiniteNumber(random(), 0);
+    if (value <= 0) {
+      return 0;
+    }
+    if (value >= 1) {
+      return 0.999999999999;
+    }
+    return value;
+  };
+}
+function sigmoidScore(score, midpoint, sharpness) {
+  return 1 / (1 + Math.exp(-sharpness * (score - midpoint)));
+}
+function computePercentile(sortedValues, percentile) {
+  if (sortedValues.length === 0) {
+    return 0;
+  }
+  if (sortedValues.length === 1) {
+    return sortedValues[0] ?? 0;
+  }
+  const safePercentile = Math.max(0, Math.min(100, percentile));
+  const position = (sortedValues.length - 1) * (safePercentile / 100);
+  const lower = Math.floor(position);
+  const upper = Math.ceil(position);
+  const lowerValue = sortedValues[lower] ?? 0;
+  const upperValue = sortedValues[upper] ?? lowerValue;
+  if (lower === upper) {
+    return lowerValue;
+  }
+  const fraction = position - lower;
+  return lowerValue * (1 - fraction) + upperValue * fraction;
+}
+function computeScorePercentiles(records, percentiles) {
+  const scores = records.map((record) => record.assessment.score).filter((score) => Number.isFinite(score)).sort((a, b) => a - b);
+  const output = {};
+  for (const percentile of percentiles) {
+    output[percentile] = computePercentile(scores, percentile);
+  }
+  return output;
+}
+function pickByWeights(values, weights, random) {
+  if (values.length === 0) {
+    throw new Error("Cannot pick from an empty set.");
+  }
+  if (values.length !== weights.length) {
+    throw new Error("values and weights must have the same length.");
+  }
+  let totalWeight = 0;
+  for (const weight of weights) {
+    if (Number.isFinite(weight) && weight > 0) {
+      totalWeight += weight;
+    }
+  }
+  if (totalWeight <= 0) {
+    const index = Math.min(values.length - 1, Math.floor(random() * values.length));
+    const fallbackValue = values[index];
+    if (fallbackValue === void 0) {
+      throw new Error("Unexpected empty value during uniform fallback pick.");
+    }
+    return fallbackValue;
+  }
+  let threshold = random() * totalWeight;
+  for (let index = 0; index < values.length; index += 1) {
+    const weight = Number.isFinite(weights[index] ?? 0) && (weights[index] ?? 0) > 0 ? weights[index] ?? 0 : 0;
+    threshold -= weight;
+    if (threshold <= 0) {
+      const value = values[index];
+      if (value === void 0) {
+        break;
+      }
+      return value;
+    }
+  }
+  const last = values[values.length - 1];
+  if (last === void 0) {
+    throw new Error("Unexpected missing final value during weighted pick.");
+  }
+  return last;
+}
+function sampleWithoutReplacement(values, k, random) {
+  if (k <= 0 || values.length === 0) {
+    return [];
+  }
+  if (k >= values.length) {
+    return [...values];
+  }
+  const pool = [...values];
+  const output = [];
+  for (let index = 0; index < k; index += 1) {
+    const pickIndex = Math.min(pool.length - 1, Math.floor(random() * pool.length));
+    const [picked] = pool.splice(pickIndex, 1);
+    if (picked === void 0) {
+      break;
+    }
+    output.push(picked);
+  }
+  return output;
+}
+function isEligibleRecord(record) {
+  return record.assessment.isViable !== false && record.assessment.trainableIssues.length > 0;
+}
+function resolveIssueType(issue) {
+  const raw = issue.issueType?.trim();
+  if (!raw) {
+    return "default";
+  }
+  return raw;
+}
+function resolveIssueId(issue, parentId, index) {
+  const raw = issue.issueId?.trim();
+  if (raw && raw.length > 0) {
+    return raw;
+  }
+  return `${parentId}:issue:${index}`;
+}
+function normalizeIssuesForRecord(parentId, issues) {
+  return issues.map((issue, index) => ({
+    id: resolveIssueId(issue, parentId, index),
+    issueType: resolveIssueType(issue),
+    issue
+  }));
+}
+function sampleIssuesByType(issues, batchSize, typeWeights, random) {
+  if (issues.length === 0 || batchSize <= 0) {
+    return [];
+  }
+  const frequency = /* @__PURE__ */ new Map();
+  for (const issue of issues) {
+    frequency.set(issue.issueType, (frequency.get(issue.issueType) ?? 0) + 1);
+  }
+  const issueTypes = [...frequency.keys()];
+  const weightedFrequency = issueTypes.map((type) => {
+    const base = frequency.get(type) ?? 0;
+    const multiplierRaw = typeWeights?.[type] ?? 1;
+    const multiplier = Number.isFinite(multiplierRaw) && multiplierRaw > 0 ? multiplierRaw : 1;
+    return base * multiplier;
+  });
+  const selectedType = pickByWeights(issueTypes, weightedFrequency, random);
+  const sameTypeIssues = issues.filter((issue) => issue.issueType === selectedType);
+  const effectiveBatchSize = Math.min(batchSize, sameTypeIssues.length);
+  return sampleWithoutReplacement(sameTypeIssues, effectiveBatchSize, random);
+}
+function resolveMidpoint(midpoint, archive) {
+  if (midpoint.mode === "fixed") {
+    return midpoint.value;
+  }
+  const scores = archive.map((record) => record.assessment.score).filter((score) => Number.isFinite(score)).sort((a, b) => a - b);
+  return computePercentile(scores, midpoint.percentile);
+}
+function selectParents(input) {
+  const {
+    eligible,
+    archive,
+    parentsPerIteration,
+    sharpness,
+    midpoint,
+    noveltyWeight,
+    replace,
+    childCountByParentId,
+    random
+  } = input;
+  if (eligible.length === 0 || parentsPerIteration <= 0) {
+    return [];
+  }
+  const midpointScore = resolveMidpoint(midpoint, archive);
+  const weightedParents = eligible.map((record) => {
+    const performance = sigmoidScore(record.assessment.score, midpointScore, sharpness);
+    const childCount = childCountByParentId.get(record.id) ?? 0;
+    const novelty = 1 / (1 + noveltyWeight * childCount);
+    return {
+      record,
+      weight: performance * novelty
+    };
+  });
+  if (replace) {
+    const output2 = [];
+    for (let index = 0; index < parentsPerIteration; index += 1) {
+      output2.push(
+        pickByWeights(
+          weightedParents.map((entry) => entry.record),
+          weightedParents.map((entry) => entry.weight),
+          random
+        )
+      );
+    }
+    return output2;
+  }
+  if (parentsPerIteration >= weightedParents.length) {
+    return weightedParents.map((entry) => entry.record);
+  }
+  const pool = [...weightedParents];
+  const output = [];
+  for (let index = 0; index < parentsPerIteration; index += 1) {
+    const chosen = pickByWeights(
+      pool.map((entry) => entry.record),
+      pool.map((entry) => entry.weight),
+      random
+    );
+    output.push(chosen);
+    const removeIndex = pool.findIndex((entry) => entry.record.id === chosen.id);
+    if (removeIndex >= 0) {
+      pool.splice(removeIndex, 1);
+    }
+  }
+  return output;
+}
+function defaultObservedOutcome(input) {
+  const { assessment, parentAssessment } = input;
+  if (assessment.isViable === false) {
+    return "Inconclusive - resulting candidate was marked non-viable.";
+  }
+  const roundedScore = Number.isFinite(assessment.score) ? assessment.score.toFixed(3) : "n/a";
+  if (!parentAssessment) {
+    return `Candidate score: ${roundedScore}.`;
+  }
+  const parentScore = Number.isFinite(parentAssessment.score) ? parentAssessment.score.toFixed(3) : "n/a";
+  if (assessment.score > parentAssessment.score) {
+    return `Candidate score: ${roundedScore}. Improved over parent score ${parentScore}.`;
+  }
+  if (assessment.score < parentAssessment.score) {
+    return `Candidate score: ${roundedScore}. Worse than parent score ${parentScore}.`;
+  }
+  return `Candidate score: ${roundedScore}. Same as parent score ${parentScore}.`;
+}
+function resolveFeedbackEntries(input) {
+  const { scope, parent, candidateById, feedbackByCandidateId, childrenByParentId } = input;
+  if (scope.mode === "none") {
+    return [];
+  }
+  if (scope.mode === "ancestors") {
+    const output2 = [];
+    let currentId = parent.id;
+    let depth = 0;
+    while (currentId) {
+      if (scope.maxDepth !== void 0 && depth > scope.maxDepth) {
+        break;
+      }
+      const entry = feedbackByCandidateId.get(currentId);
+      if (entry) {
+        output2.push(entry);
+      }
+      const current = candidateById.get(currentId);
+      currentId = current?.parentId;
+      depth += 1;
+    }
+    return output2;
+  }
+  const maxDistance = scope.maxDistance;
+  if (maxDistance < 0) {
+    return [];
+  }
+  const output = [];
+  const queue = [{ id: parent.id, distance: 0 }];
+  const visited = /* @__PURE__ */ new Set();
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) {
+      continue;
+    }
+    if (visited.has(current.id)) {
+      continue;
+    }
+    visited.add(current.id);
+    const entry = feedbackByCandidateId.get(current.id);
+    if (entry) {
+      output.push(entry);
+    }
+    if (current.distance >= maxDistance) {
+      continue;
+    }
+    const parentRecord = candidateById.get(current.id);
+    const ancestorId = parentRecord?.parentId;
+    if (ancestorId && !visited.has(ancestorId)) {
+      queue.push({ id: ancestorId, distance: current.distance + 1 });
+    }
+    const children = childrenByParentId.get(current.id) ?? [];
+    for (const childId of children) {
+      if (!visited.has(childId)) {
+        queue.push({ id: childId, distance: current.distance + 1 });
+      }
+    }
+  }
+  return output;
+}
+async function mapWithConcurrency(items, maxConcurrency, worker) {
+  if (items.length === 0) {
+    return [];
+  }
+  const concurrency = Math.max(1, Math.floor(maxConcurrency));
+  const output = new Array(items.length);
+  let nextIndex = 0;
+  const runners = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (true) {
+      const index = nextIndex;
+      nextIndex += 1;
+      if (index >= items.length) {
+        break;
+      }
+      const item = items[index];
+      if (item === void 0) {
+        continue;
+      }
+      output[index] = await worker(item, index);
+    }
+  });
+  await Promise.all(runners);
+  return output;
+}
+async function runCandidateEvolution(options) {
+  const iterations = Math.max(0, Math.floor(options.iterations));
+  const parentsPerIteration = Math.max(0, Math.floor(options.parentsPerIteration));
+  const batchSize = Math.max(1, Math.floor(options.batchSize ?? DEFAULT_BATCH_SIZE));
+  const generationConcurrency = Math.max(
+    1,
+    Math.floor(options.generationConcurrency ?? DEFAULT_GENERATION_CONCURRENCY)
+  );
+  const assessmentConcurrency = Math.max(
+    1,
+    Math.floor(options.assessmentConcurrency ?? DEFAULT_ASSESSMENT_CONCURRENCY)
+  );
+  if (options.generators.length === 0) {
+    throw new Error("runCandidateEvolution requires at least one generator subagent.");
+  }
+  if (parentsPerIteration <= 0) {
+    throw new Error("parentsPerIteration must be positive.");
+  }
+  const generationNames = /* @__PURE__ */ new Set();
+  for (const generator of options.generators) {
+    if (!generator.name.trim()) {
+      throw new Error("Generator names must be non-empty.");
+    }
+    if (generationNames.has(generator.name)) {
+      throw new Error(`Duplicate generator name "${generator.name}".`);
+    }
+    generationNames.add(generator.name);
+  }
+  const random = normalizeRandom(options.random);
+  const parentSelection = options.parentSelection;
+  const selectionSharpness = parentSelection?.sharpness !== void 0 ? Math.max(1e-4, parentSelection.sharpness) : DEFAULT_SHARPNESS;
+  const selectionMidpoint = parentSelection?.midpoint ?? DEFAULT_MIDPOINT;
+  const noveltyWeight = parentSelection?.noveltyWeight !== void 0 ? Math.max(0, parentSelection.noveltyWeight) : DEFAULT_NOVELTY_WEIGHT;
+  const selectionReplace = parentSelection?.replace ?? true;
+  const feedbackScope = options.feedbackScope ?? DEFAULT_FEEDBACK_SCOPE;
+  const describeObservedOutcome = options.describeObservedOutcome ?? defaultObservedOutcome;
+  const scorePercentiles = options.scorePercentiles && options.scorePercentiles.length > 0 ? options.scorePercentiles : DEFAULT_SCORE_PERCENTILES;
+  const archive = [];
+  const feedbackEntries = [];
+  const postCheckRejections = [];
+  const snapshots = [];
+  const candidateById = /* @__PURE__ */ new Map();
+  const feedbackByCandidateId = /* @__PURE__ */ new Map();
+  const childCountByParentId = /* @__PURE__ */ new Map();
+  const childrenByParentId = /* @__PURE__ */ new Map();
+  let totalStats = createEmptyStats();
+  let stoppedEarly = false;
+  const seedAssessment = await options.assessCandidate({
+    candidate: options.seedCandidate,
+    iteration: 0
+  });
+  const seedRecord = {
+    id: randomId("candidate"),
+    candidate: options.seedCandidate,
+    assessment: seedAssessment,
+    createdAtIteration: 0
+  };
+  archive.push(seedRecord);
+  candidateById.set(seedRecord.id, seedRecord);
+  const initialStats = createEmptyStats();
+  initialStats.assessmentCalls += 1;
+  totalStats = addStats(totalStats, initialStats);
+  const initialSnapshot = {
+    iteration: 0,
+    archiveSize: archive.length,
+    bestCandidateId: seedRecord.id,
+    bestScore: seedRecord.assessment.score,
+    scorePercentiles: computeScorePercentiles(archive, scorePercentiles),
+    stats: initialStats,
+    bestCandidate: seedRecord
+  };
+  snapshots.push(initialSnapshot);
+  await options.onSnapshot?.(initialSnapshot);
+  for (let iteration = 1; iteration <= iterations; iteration += 1) {
+    const iterationStats = createEmptyStats();
+    const eligible = archive.filter((record) => isEligibleRecord(record));
+    if (eligible.length === 0) {
+      stoppedEarly = true;
+      const bestCandidate3 = archive.reduce(
+        (best, current) => current.assessment.score > best.assessment.score ? current : best
+      );
+      const snapshot2 = {
+        iteration,
+        archiveSize: archive.length,
+        bestCandidateId: bestCandidate3.id,
+        bestScore: bestCandidate3.assessment.score,
+        scorePercentiles: computeScorePercentiles(archive, scorePercentiles),
+        stats: iterationStats,
+        bestCandidate: bestCandidate3
+      };
+      snapshots.push(snapshot2);
+      await options.onSnapshot?.(snapshot2);
+      break;
+    }
+    const selectedParents = selectParents({
+      eligible,
+      archive,
+      parentsPerIteration,
+      sharpness: selectionSharpness,
+      midpoint: selectionMidpoint,
+      noveltyWeight,
+      replace: selectionReplace,
+      childCountByParentId,
+      random
+    });
+    const generationTasks = [];
+    for (const parent of selectedParents) {
+      const issueEnvelopes = normalizeIssuesForRecord(parent.id, parent.assessment.trainableIssues);
+      const sampledIssueEnvelopes = sampleIssuesByType(
+        issueEnvelopes,
+        batchSize,
+        parent.assessment.issueTypeWeights,
+        random
+      );
+      if (sampledIssueEnvelopes.length === 0) {
+        continue;
+      }
+      const visibleFeedbackEntries = resolveFeedbackEntries({
+        scope: feedbackScope,
+        parent,
+        candidateById,
+        feedbackByCandidateId,
+        childrenByParentId
+      });
+      for (const generator of options.generators) {
+        const issuesForGenerator = generator.supportsIssueBatch ? sampledIssueEnvelopes : sampledIssueEnvelopes.slice(0, 1);
+        if (issuesForGenerator.length === 0) {
+          continue;
+        }
+        generationTasks.push({
+          parent,
+          generator,
+          sampledIssueEnvelopes: issuesForGenerator,
+          feedbackEntries: visibleFeedbackEntries
+        });
+        iterationStats.generationCalls += 1;
+        iterationStats.issuesSupplied += issuesForGenerator.length;
+        iterationStats.feedbackEntriesSupplied += visibleFeedbackEntries.length;
+      }
+    }
+    if (generationTasks.length === 0) {
+      stoppedEarly = true;
+      const bestCandidate3 = archive.reduce(
+        (best, current) => current.assessment.score > best.assessment.score ? current : best
+      );
+      const snapshot2 = {
+        iteration,
+        archiveSize: archive.length,
+        bestCandidateId: bestCandidate3.id,
+        bestScore: bestCandidate3.assessment.score,
+        scorePercentiles: computeScorePercentiles(archive, scorePercentiles),
+        stats: iterationStats,
+        bestCandidate: bestCandidate3
+      };
+      snapshots.push(snapshot2);
+      await options.onSnapshot?.(snapshot2);
+      break;
+    }
+    const generatedOutputs = await mapWithConcurrency(
+      generationTasks,
+      generationConcurrency,
+      async (task) => {
+        const proposals = await task.generator.generate({
+          parent: task.parent,
+          sampledIssues: task.sampledIssueEnvelopes.map((envelope) => envelope.issue),
+          feedbackEntries: task.feedbackEntries,
+          iteration
+        });
+        return { task, proposals };
+      }
+    );
+    const pendingProposals = [];
+    for (const output of generatedOutputs) {
+      iterationStats.proposalsGenerated += output.proposals.length;
+      for (const proposal of output.proposals) {
+        pendingProposals.push({
+          proposal,
+          parent: output.task.parent,
+          generatorName: output.task.generator.name,
+          sampledIssues: output.task.sampledIssueEnvelopes.map((envelope) => envelope.issue),
+          sampledIssueIds: output.task.sampledIssueEnvelopes.map((envelope) => envelope.id),
+          sampledFeedbackEntryIds: output.task.feedbackEntries.map((entry) => entry.id)
+        });
+      }
+    }
+    const evaluatedProposals = await mapWithConcurrency(
+      pendingProposals,
+      assessmentConcurrency,
+      async (pending) => {
+        if (options.verifyGeneratedCandidate) {
+          iterationStats.postCheckCalls += 1;
+          const passes = await options.verifyGeneratedCandidate({
+            proposal: pending.proposal,
+            parent: pending.parent,
+            generatorName: pending.generatorName,
+            sampledIssues: pending.sampledIssues,
+            iteration
+          });
+          if (!passes) {
+            postCheckRejections.push({
+              id: randomId("rejected"),
+              candidate: pending.proposal.candidate,
+              parentId: pending.parent.id,
+              generatorName: pending.generatorName,
+              iteration,
+              sampledIssueIds: pending.sampledIssueIds,
+              changeSummary: pending.proposal.changeSummary
+            });
+            return null;
+          }
+        }
+        iterationStats.proposalsAfterPostCheck += 1;
+        iterationStats.assessmentCalls += 1;
+        const assessment = await options.assessCandidate({
+          candidate: pending.proposal.candidate,
+          iteration,
+          parent: pending.parent,
+          generatorName: pending.generatorName,
+          sampledIssues: pending.sampledIssues
+        });
+        return {
+          pending,
+          assessment
+        };
+      }
+    );
+    const acceptedRecords = [];
+    for (const evaluated of evaluatedProposals) {
+      if (!evaluated) {
+        continue;
+      }
+      const { pending, assessment } = evaluated;
+      acceptedRecords.push({
+        id: randomId("candidate"),
+        candidate: pending.proposal.candidate,
+        assessment,
+        createdAtIteration: iteration,
+        parentId: pending.parent.id,
+        generatorName: pending.generatorName,
+        sampledIssueIds: pending.sampledIssueIds,
+        sampledFeedbackEntryIds: pending.sampledFeedbackEntryIds,
+        changeSummary: pending.proposal.changeSummary
+      });
+    }
+    for (const record of acceptedRecords) {
+      archive.push(record);
+      candidateById.set(record.id, record);
+      if (record.parentId) {
+        const nextCount = (childCountByParentId.get(record.parentId) ?? 0) + 1;
+        childCountByParentId.set(record.parentId, nextCount);
+        const existingChildren = childrenByParentId.get(record.parentId) ?? [];
+        existingChildren.push(record.id);
+        childrenByParentId.set(record.parentId, existingChildren);
+      }
+      if (record.changeSummary && record.changeSummary.trim().length > 0) {
+        const parentAssessment = record.parentId ? candidateById.get(record.parentId)?.assessment ?? null : null;
+        const feedbackEntry = {
+          id: randomId("feedback"),
+          candidateId: record.id,
+          attemptedChange: record.changeSummary,
+          observedOutcome: describeObservedOutcome({
+            assessment: record.assessment,
+            parentAssessment
+          })
+        };
+        feedbackEntries.push(feedbackEntry);
+        feedbackByCandidateId.set(record.id, feedbackEntry);
+      }
+    }
+    totalStats = addStats(totalStats, iterationStats);
+    const bestCandidate2 = archive.reduce(
+      (best, current) => current.assessment.score > best.assessment.score ? current : best
+    );
+    const snapshot = {
+      iteration,
+      archiveSize: archive.length,
+      bestCandidateId: bestCandidate2.id,
+      bestScore: bestCandidate2.assessment.score,
+      scorePercentiles: computeScorePercentiles(archive, scorePercentiles),
+      stats: iterationStats,
+      bestCandidate: bestCandidate2
+    };
+    snapshots.push(snapshot);
+    await options.onSnapshot?.(snapshot);
+  }
+  const bestCandidate = archive.reduce(
+    (best, current) => current.assessment.score > best.assessment.score ? current : best
+  );
+  return {
+    archive,
+    feedbackEntries,
+    postCheckRejections,
+    snapshots,
+    bestCandidate,
+    totalStats,
+    stoppedEarly
+  };
+}
 export {
   CHATGPT_MODEL_IDS,
   CODEX_APPLY_PATCH_FREEFORM_TOOL_DESCRIPTION,
@@ -9407,6 +10075,7 @@ export {
   resolveFilesystemToolProfile,
   resolveFireworksModelId,
   runAgentLoop,
+  runCandidateEvolution,
   runToolLoop,
   sanitisePartForLogging,
   streamAgentLoop,