@hifullmoon/aicommit 2.4.0 → 2.5.0

package/src/change-analysis.js

@@ -12,7 +12,7 @@ import {
   isDeepAnalysis,
   isGeneratedFile,
   localOverview,
-  localPlanItems,
+  localPlanBatches,
 } from './local-analysis.js';
 
 function gitQuote(path) {
@@ -230,16 +230,17 @@ const ANALYSIS_SYSTEM =
 export function analysisConfig(config) {
   if (config.analysisBudget) return config;
   const settings = { ...DEFAULT_LARGE_CHANGE, ...config.largeChange };
+  settings.cache = { ...DEFAULT_LARGE_CHANGE.cache, ...config.largeChange?.cache };
   const model = getProviderAdapter(config).model;
-  const output = Math.max(
-    config.maxTokens || 1024,
-    config.reasoning?.mode === 'on' ? config.reasoning.maxTokens || 4096 : 0,
-  );
+  const output =
+    config.reasoning?.mode === 'off'
+      ? config.maxTokens || 1024
+      : Math.max(config.maxTokens || 1024, config.reasoning?.maxTokens || 4096);
   settings.chunkInputTokens = Math.min(
     settings.chunkInputTokens,
     Math.max(256, model.contextWindow - output - 1024),
   );
-  return { ...config, analysisBudget: createAnalysisBudget(settings) };
+  return { ...config, largeChange: settings, analysisBudget: createAnalysisBudget(settings) };
 }
 
 export function packItems(items, maxChars, maxItems = 24) {
@@ -260,7 +261,64 @@ export function packItems(items, maxChars, maxItems = 24) {
   return batches;
 }
 
-async function jsonCall(config, instruction, items) {
+function parseAnalysisJson(raw) {
+  const text = String(raw || '')
+    .replace(/<think>[\s\S]*?<\/think>/gi, '')
+    .trim();
+  const fence = text.match(/^```[a-zA-Z]*\s*\n([\s\S]*?)\n?```$/);
+  const candidates = fence ? [fence[1].trim(), text] : [text];
+
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      if (Array.isArray(parsed)) return parsed;
+    } catch {
+      // Fall through to the balanced-array extractor below. Some providers
+      // wrap otherwise valid JSON in a short explanation or an outer object.
+    }
+
+    for (
+      let start = candidate.indexOf('[');
+      start !== -1;
+      start = candidate.indexOf('[', start + 1)
+    ) {
+      let depth = 0;
+      let quoted = false;
+      let escaped = false;
+      for (let index = start; index < candidate.length; index++) {
+        const char = candidate[index];
+        if (quoted) {
+          if (escaped) escaped = false;
+          else if (char === '\\') escaped = true;
+          else if (char === '"') quoted = false;
+          continue;
+        }
+        if (char === '"') {
+          quoted = true;
+          continue;
+        }
+        if (char === '[') depth++;
+        if (char !== ']') continue;
+        depth--;
+        if (depth !== 0) continue;
+        try {
+          const parsed = JSON.parse(candidate.slice(start, index + 1));
+          if (Array.isArray(parsed)) return parsed;
+        } catch {
+          break;
+        }
+      }
+    }
+  }
+  throw new SyntaxError('Response contains no complete JSON array.');
+}
+
+async function jsonCall(config, instruction, items, validate = null) {
+  const parseAndValidate = (raw) => {
+    const parsed = parseAnalysisJson(raw);
+    validate?.(parsed);
+    return parsed;
+  };
   const result = await getResponseText(
     config,
     [
@@ -269,13 +327,25 @@ async function jsonCall(config, instruction, items) {
     ],
     0,
     Math.min(2048, config.maxTokens || 1024),
-    'Return the complete requested JSON, preserving all input IDs.',
+    'Return the complete requested JSON array, preserving every required input ID exactly once. ' +
+      `Required IDs: ${JSON.stringify(items.map((item) => item.id))}`,
     null,
+    (response) => {
+      try {
+        parseAndValidate(response);
+        return true;
+      } catch {
+        return false;
+      }
+    },
   );
   try {
-    return JSON.parse(result.text.replace(/^```(?:json)?\s*|\s*```$/g, ''));
-  } catch {
-    throw fail(ERROR_CATEGORIES.RESPONSE_FORMAT, 'Large-change analysis returned invalid JSON.');
+    return parseAndValidate(result.text);
+  } catch (cause) {
+    if (cause?.category === ERROR_CATEGORIES.RESPONSE_FORMAT) throw cause;
+    throw fail(ERROR_CATEGORIES.RESPONSE_FORMAT, 'Large-change analysis returned invalid JSON.', {
+      cause,
+    });
   }
 }
 
@@ -303,71 +373,215 @@ export function validatePartition(groups, ids) {
     throw fail(ERROR_CATEGORIES.RESPONSE_FORMAT, 'Analysis left input IDs unassigned.');
 }
 
+function fragmentCacheKey(config, input, protect, persistentCache) {
+  return persistentCache
+    ? persistentCache.keyFor('fragment-analysis', input)
+    : createHash('sha256')
+        .update(
+          JSON.stringify({
+            version: 1,
+            input,
+            protect,
+            model: config.modelId,
+            endpoint: config.apiUrl,
+            context: config.repositoryContextText,
+          }),
+        )
+        .digest('hex');
+}
+
+function validateFragmentGroups(candidate, inputIds) {
+  validatePartition(candidate, inputIds);
+  if (candidate.some((group) => group.ids.length !== 1))
+    throw fail(
+      ERROR_CATEGORIES.RESPONSE_FORMAT,
+      'Fragment analysis combined unrelated source IDs.',
+    );
+}
+
+function estimateInitialDeepCost(
+  config,
+  capture,
+  protect,
+  previews,
+  maxBatchTokens,
+  persistentCache,
+) {
+  const batchSizes = [];
+  let batch = [];
+  let batchTokens = 0;
+  let chunks = 0;
+  let cachedChunks = 0;
+  let oversizedInput = false;
+  const fragmentsByFile = new Map();
+  const flush = () => {
+    if (!batch.length) return;
+    chunks++;
+    const inputIds = batch.map((item) => item.id);
+    const cacheKey = fragmentCacheKey(config, batch, protect, persistentCache);
+    const cached =
+      capture.analysisCache?.get(cacheKey) ||
+      persistentCache?.read(cacheKey, inputIds, (candidate) =>
+        validateFragmentGroups(candidate, inputIds),
+      );
+    if (cached) cachedChunks++;
+    else batchSizes.push(batchTokens);
+    batch = [];
+    batchTokens = 0;
+  };
+  for (const unit of capture.units(protect, previews)) {
+    if (unit.metadataOnly) continue;
+    fragmentsByFile.set(unit.fileId, (fragmentsByFile.get(unit.fileId) || 0) + 1);
+    const size = estimateTokens(JSON.stringify(unit));
+    if (size + 768 > config.analysisBudget.limits.chunkInputTokens) oversizedInput = true;
+    if (batch.length && (batchTokens + size > maxBatchTokens || batch.length >= 16)) flush();
+    batch.push(unit);
+    batchTokens += size;
+  }
+  flush();
+  const output = Math.min(2048, config.maxTokens || 1024);
+  let reductionRequests = 0;
+  if (config.analysisTask === 'split') {
+    for (const fragments of fragmentsByFile.values()) {
+      let summaries = fragments;
+      while (summaries * 160 > 2000) {
+        const batches = Math.ceil(summaries / 24);
+        reductionRequests += batches;
+        summaries = batches;
+      }
+    }
+  }
+  let planningRequests = 1;
+  if (config.analysisTask === 'split') {
+    planningRequests = 0;
+    let candidates = Math.max(1, capture.manifest.length);
+    for (let level = 0; level < 8; level++) {
+      const batches = Math.ceil(candidates / (config.splitMaxPlanFiles || 100));
+      planningRequests += batches;
+      if (batches === 1) break;
+      candidates = batches;
+    }
+  }
+  const downstreamRequests = reductionRequests + planningRequests;
+  const downstreamReserve =
+    downstreamRequests * (config.analysisBudget.limits.chunkInputTokens + output);
+  const estimatedTokens =
+    batchSizes.reduce(
+      (total, input) =>
+        total + Math.min(config.analysisBudget.limits.chunkInputTokens, input + 768) + output,
+      0,
+    ) + downstreamReserve;
+  return {
+    chunks,
+    cachedChunks,
+    requestedChunks: batchSizes.length,
+    estimatedTokens,
+    oversizedInput,
+    reductionRequests,
+    planningRequests,
+    downstreamReserve,
+  };
+}
+
 export async function analyzeChanges(
   config,
   capture,
   protect = true,
   previews = null,
   onProgress = null,
+  persistentCache = null,
 ) {
   if (!isDeepAnalysis(config)) return analyzeLocally(config, capture, protect, previews);
   const budget = config.analysisBudget;
+  const maxBatchTokens = Math.min(
+    estimateTokens('x'.repeat(config.maxDiffChars || 30000)),
+    Math.floor(budget.limits.chunkInputTokens * 0.65),
+  );
+  // chunkInputTokens is a token budget, while String#length counts UTF-16 code
+  // units. Track the same conservative UTF-8 estimate used at dispatch time so
+  // ASCII-heavy repositories do not produce roughly twice as many requests and
+  // multibyte input still stays within the configured ceiling.
   const maxChars = Math.min(
     config.maxDiffChars || 30000,
     Math.floor(budget.limits.chunkInputTokens * 0.65),
   );
-  budget.reserveFinal(
-    budget.limits.chunkInputTokens +
-      Math.max(config.maxTokens || 1024, config.reasoning?.maxTokens || 4096),
+  const estimate = estimateInitialDeepCost(
+    config,
+    capture,
+    protect,
+    previews,
+    maxBatchTokens,
+    persistentCache,
   );
+  if (estimate.oversizedInput || estimate.estimatedTokens > budget.limits.maxTotalTokens) {
+    const fallbackConfig = {
+      ...config,
+      largeChange: { ...config.largeChange, strategy: 'auto' },
+    };
+    const local = analyzeLocally(fallbackConfig, capture, protect, previews);
+    local.coverage = {
+      ...local.coverage,
+      degradedFrom: 'deep',
+      fallbackReason: estimate.oversizedInput ? 'preflight_input' : 'preflight_tokens',
+      estimatedDeepChunks: estimate.chunks,
+      estimatedCachedChunks: estimate.cachedChunks,
+      estimatedRequestedChunks: estimate.requestedChunks,
+      estimatedReductionRequests: estimate.reductionRequests,
+      estimatedPlanningRequests: estimate.planningRequests,
+      estimatedDeepTokens: estimate.estimatedTokens,
+    };
+    return local;
+  }
+  budget.reserveFinal(estimate.downstreamReserve);
   const fileFacts = new Map(capture.manifest.map((f) => [f.id, []]));
   let batch = [];
-  let length = 0;
+  let batchTokens = 0;
   let done = 0;
   let analyzed = 0;
+  let cachedChunks = 0;
+  let requestedChunks = 0;
   const pending = [];
   const cache = (capture.analysisCache ||= new Map());
   async function flush() {
     if (!batch.length) return;
     const input = batch;
     batch = [];
-    length = 0;
-    const cacheKey = createHash('sha256')
-      .update(
-        JSON.stringify({
-          version: 1,
-          input,
-          protect,
-          model: config.modelId,
-          endpoint: config.apiUrl,
-          context: config.repositoryContextText,
-        }),
-      )
-      .digest('hex');
-    const groups =
-      cache.get(cacheKey) ||
-      (await jsonCall(
+    batchTokens = 0;
+    const cacheKey = fragmentCacheKey(config, input, protect, persistentCache);
+    const inputIds = input.map((x) => x.id);
+    const validateGroups = (candidate) => validateFragmentGroups(candidate, inputIds);
+    let groups = cache.get(cacheKey);
+    let cacheHit = Boolean(groups);
+    if (!groups && persistentCache) {
+      groups = persistentCache.read(cacheKey, inputIds, validateGroups);
+      cacheHit = Boolean(groups);
+    }
+    if (!groups) {
+      groups = await jsonCall(
         config,
         'Return one entry per input ID: [{"ids":["input ID"],"summary":"concise factual changes and uncertainties"}]. Each input ID must appear exactly once. Never combine different IDs. Summaries must be at most 160 characters.',
         input,
-      ));
-    validatePartition(
-      groups,
-      input.map((x) => x.id),
-    );
-    const byId = new Map(input.map((x) => [x.id, x.fileId]));
-    if (groups.some((group) => group.ids.length !== 1))
-      throw fail(
-        ERROR_CATEGORIES.RESPONSE_FORMAT,
-        'Fragment analysis combined unrelated source IDs.',
+        validateGroups,
       );
+      requestedChunks++;
+      persistentCache?.write(cacheKey, inputIds, groups);
+    } else {
+      cachedChunks++;
+    }
+    const byId = new Map(input.map((x) => [x.id, x.fileId]));
     cache.set(cacheKey, groups);
     for (const group of groups) {
       for (const id of new Set(group.ids.map((x) => byId.get(x))))
         fileFacts.get(id).push(group.summary);
     }
     analyzed += input.filter((x) => !x.metadataOnly).length;
-    onProgress?.({ completedChunks: ++done, analyzedFragments: analyzed });
+    onProgress?.({
+      completedChunks: ++done,
+      analyzedFragments: analyzed,
+      cachedChunks,
+      requestedChunks,
+      cacheHit,
+    });
   }
   async function schedule() {
     pending.push(
@@ -387,10 +601,11 @@ export async function analyzeChanges(
         fileFacts.get(unit.fileId).push(unit.text);
         continue;
       }
-      const size = JSON.stringify(unit).length;
-      if (batch.length && (length + size > maxChars || batch.length >= 16)) await schedule();
+      const size = estimateTokens(JSON.stringify(unit));
+      if (batch.length && (batchTokens + size > maxBatchTokens || batch.length >= 16))
+        await schedule();
       batch.push(unit);
-      length += size;
+      batchTokens += size;
     }
     await schedule();
     for (const err of await Promise.all(pending)) if (err) throw err;
@@ -411,17 +626,17 @@ export async function analyzeChanges(
           summaries.map((summary, i) => ({ id: `S${i}`, summary })),
           maxChars,
         )) {
+          const ids = group.map((x) => x.id);
           const reduced = await jsonCall(
             config,
             'Return [{"ids":[all input IDs],"summary":"one factual summary, at most 400 characters"}]. Preserve important behavior and uncertainty.',
             group,
+            (candidate) => {
+              validatePartition(candidate, ids);
+              if (candidate.length !== 1)
+                throw fail(ERROR_CATEGORIES.RESPONSE_FORMAT, 'Expected one reduced summary.');
+            },
           );
-          validatePartition(
-            reduced,
-            group.map((x) => x.id),
-          );
-          if (reduced.length !== 1)
-            throw fail(ERROR_CATEGORIES.RESPONSE_FORMAT, 'Expected one reduced summary.');
           next.push(reduced[0].summary);
         }
         summaries = next;
@@ -441,15 +656,22 @@ export async function analyzeChanges(
         metadataOnlyFiles: capture.manifest.filter((f) => f.metadataOnly).length,
         failedFiles: 0,
         completedChunks: done,
+        cachedChunks,
+        requestedChunks,
       },
     };
   } catch (err) {
+    const exhausted = err.data?.analysis?.exhausted || (!budget.remainingMs() ? 'time' : undefined);
     err.data = {
       ...err.data,
       analysis: {
         ...budget.snapshot(),
+        ...err.data?.analysis,
+        ...(exhausted ? { exhausted } : {}),
         totalFiles: capture.manifest.length,
         completedChunks: done,
+        cachedChunks,
+        requestedChunks,
         complete: false,
       },
     };
@@ -472,17 +694,17 @@ export async function summarizeChanges(config, facts) {
       throw fail(ERROR_CATEGORIES.RESPONSE_FORMAT, 'Change summary did not converge.');
     const next = [];
     for (const batch of packItems(items, cap)) {
+      const ids = batch.map((x) => x.id);
       const groups = await jsonCall(
         config,
         'Return [{"ids":[all input IDs],"summary":"one summary of supported behavior changes and uncertainty, at most 400 characters"}].',
         batch,
+        (candidate) => {
+          validatePartition(candidate, ids);
+          if (candidate.length !== 1)
+            throw fail(ERROR_CATEGORIES.RESPONSE_FORMAT, 'Expected one reduced summary.');
+        },
       );
-      validatePartition(
-        groups,
-        batch.map((x) => x.id),
-      );
-      if (groups.length !== 1)
-        throw fail(ERROR_CATEGORIES.RESPONSE_FORMAT, 'Expected one reduced summary.');
       next.push({ id: `L${level}N${next.length}`, summary: groups[0].summary });
     }
     items = next;
@@ -492,6 +714,7 @@ export async function summarizeChanges(config, facts) {
 
 export async function planAnalyzedChanges(config, facts, coverage = null) {
   let candidates = facts;
+  const deep = isDeepAnalysis(config) && coverage?.strategy !== 'auto';
   const policy = normalizeCommitPolicy(config.commitPolicy, config.language);
   const cap = Math.min(
     config.splitMaxDiffChars || 16000,
@@ -499,34 +722,35 @@ export async function planAnalyzedChanges(config, facts, coverage = null) {
   );
   for (let level = 0; level < 8; level++) {
     const byId = new Map(candidates.map((x) => [x.id, x]));
-    const batches = !isDeepAnalysis(config)
-      ? [localPlanItems(config, candidates, cap)]
-      : packItems(
-          candidates.map(({ id, path, summary }) => ({ id, path, summary })),
-          cap,
-          config.splitMaxPlanFiles || 100,
-        );
-    if (!isDeepAnalysis(config) && coverage) {
-      coverage.sampledFiles = batches[0].filter((item) => item.representativeExcerpt).length;
+    const batches =
+      !deep && level === 0
+        ? localPlanBatches(config, candidates, cap)
+        : packItems(
+            candidates.map(({ id, path, summary }) => ({ id, path, summary })),
+            cap,
+            config.splitMaxPlanFiles || 100,
+          );
+    if (!deep && level === 0 && coverage) {
+      coverage.sampledFiles = batches.flat().filter((item) => item.representativeExcerpt).length;
       coverage.metadataOnlyFiles = coverage.totalFiles - coverage.sampledFiles;
     }
     const next = [];
     for (const batch of batches) {
+      const ids = batch.map((x) => x.id);
       const groups = await jsonCall(
         config,
         `Each commit message must follow this policy: ${JSON.stringify(policy)}.\nGroup related changes into logical commits, including related implementation and tests across directories. Return [{"ids":[input IDs],"summary":"factual combined change summary","subject":"commit subject","body":"optional commit body"}]. Assign every input ID exactly once. Do not merge unrelated changes just to reduce group count.`,
         batch,
-      );
-      validatePartition(
-        groups,
-        batch.map((x) => x.id),
+        (candidate) => {
+          validatePartition(candidate, ids);
+          if (candidate.some((group) => typeof group.subject !== 'string' || !group.subject.trim()))
+            throw fail(
+              ERROR_CATEGORIES.RESPONSE_FORMAT,
+              'Analysis plan is missing a commit subject.',
+            );
+        },
       );
       for (const group of groups) {
-        if (typeof group.subject !== 'string' || !group.subject.trim())
-          throw fail(
-            ERROR_CATEGORIES.RESPONSE_FORMAT,
-            'Analysis plan is missing a commit subject.',
-          );
         next.push({
           ...group,
           id: `L${level}G${next.length}`,
@@ -536,14 +760,11 @@ export async function planAnalyzedChanges(config, facts, coverage = null) {
     }
     if (batches.length === 1)
       return next.map(({ subject, body, files }) => ({ subject, body, files }));
-    if (next.length >= candidates.length)
-      throw fail(
-        ERROR_CATEGORIES.PROVIDER,
-        'Too many independent change groups for a complete global plan. Stage a smaller logical change or increase planning limits.',
-      );
     candidates = next;
   }
-  throw fail(ERROR_CATEGORIES.PROVIDER, 'Split planning exceeded the maximum summary depth.');
+  throw fail(ERROR_CATEGORIES.PROVIDER, 'Split planning exceeded the maximum summary depth.', {
+    data: { fallbackPlan: true },
+  });
 }
 
 export function needsAnalysis(capture, config, split = false) {

package/src/cli.js

@@ -52,6 +52,7 @@ function showHelp() {
     --no-reasoning        Explicitly disable reasoning when supported
     --dry-run             Generate and review without creating commits
     -y, --yes             Non-interactive: accept the generated message/plan
+    --allow-single-fallback  Let non-interactive split commit one complete group if planning exhausts its budget
     --output=<text|json>  Output mode; JSON requires --yes for commit flows
     --debug               Print debug info (parsed args, final config, etc.)
 
@@ -93,6 +94,7 @@ function parsedDefaults(overrides = {}) {
     splitPlanFile: null,
     dryRun: false,
     yes: false,
+    allowSingleFallback: false,
     setup: false,
     update: false,
     doctor: false,
@@ -201,6 +203,7 @@ export function parseArgs(args = process.argv.slice(2)) {
   let splitScopeOption = false;
   let dryRun = false;
   let yes = false;
+  let allowSingleFallback = false;
   const setup = false;
 
   for (let i = 0; i < args.length; i++) {
@@ -290,6 +293,11 @@ export function parseArgs(args = process.argv.slice(2)) {
       continue;
     }
 
+    if (arg === '--allow-single-fallback') {
+      allowSingleFallback = true;
+      continue;
+    }
+
     if (arg === '--reasoning') {
       cliReasoning = takeValue(args, i, arg, 'low|medium|high|xhigh|max');
       i++;
@@ -428,6 +436,12 @@ export function parseArgs(args = process.argv.slice(2)) {
   if (splitPlanFile && !['plan', 'apply'].includes(splitCommand)) {
     throw fail(ERROR_CATEGORIES.CONFIG, '--file is only valid with split plan or split apply.');
   }
+  if (allowSingleFallback && (splitCommand !== 'run' || !yes || dryRun)) {
+    throw fail(
+      ERROR_CATEGORIES.CONFIG,
+      '--allow-single-fallback requires non-dry-run "aicommit split run --yes".',
+    );
+  }
   if (
     configAction &&
     (cliLang || cliReasoning || split || splitCommand || splitPlanFile || dryRun || yes)
@@ -497,6 +511,7 @@ export function parseArgs(args = process.argv.slice(2)) {
     splitPlanFile,
     dryRun,
     yes,
+    allowSingleFallback,
     setup,
     update,
     doctor,

package/src/completion.js

@@ -16,6 +16,7 @@ const TOP_LEVEL = [
   '--no-reasoning',
   '--dry-run',
   '--yes',
+  '--allow-single-fallback',
   '--output',
   '--debug',
 ];
@@ -32,7 +33,7 @@ _aicommit() {
     config) COMPREPLY=( $(compgen -W "show validate path --provider --model --output --debug" -- "$cur") ); return ;;
     policy) COMPREPLY=( $(compgen -W "template check --file --range --output --debug" -- "$cur") ); return ;;
     completion) COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") ); return ;;
-    split) COMPREPLY=( $(compgen -W "run plan apply resume abort --scope --file --yes --output --debug" -- "$cur") ); return ;;
+    split) COMPREPLY=( $(compgen -W "run plan apply resume abort --scope --file --yes --allow-single-fallback --output --debug" -- "$cur") ); return ;;
   esac
   case "$prev" in
     --lang|-l) COMPREPLY=( $(compgen -W "zh en" -- "$cur") ); return ;;
@@ -72,6 +73,7 @@ _aicommit() {
     '--no-reasoning[disable reasoning]'
     '--dry-run[review without committing]'
     '--yes[accept without prompts]'
+    '--allow-single-fallback[allow non-interactive split to commit one conservative group]'
     '--output=[output mode]:output:(text json)'
     '--debug[show debug details]'
   )
@@ -118,6 +120,7 @@ complete -c aicommit -l reasoning -x -a 'low medium high xhigh max' -d 'Reasonin
 complete -c aicommit -l no-reasoning -d 'Disable reasoning'
 complete -c aicommit -l dry-run -d 'Review without committing'
 complete -c aicommit -s y -l yes -d 'Accept without prompts'
+complete -c aicommit -l allow-single-fallback -d 'Allow non-interactive split to commit one conservative group'
 complete -c aicommit -l output -x -a 'text json' -d 'Output mode'
 complete -c aicommit -l debug -d 'Show debug details'
 `;

package/src/config.js

@@ -420,7 +420,11 @@ function assertUrl(config, key) {
   }
 }
 
-function assertNumber(config, key, { integer = false, min = -Infinity, max = Infinity } = {}) {
+function assertNumber(
+  config,
+  key,
+  { integer = false, min = -Infinity, max = Infinity, label = key } = {},
+) {
   const value = config[key];
   const ok =
     typeof value === 'number' &&
@@ -431,7 +435,7 @@ function assertNumber(config, key, { integer = false, min = -Infinity, max = Inf
   if (!ok) {
     const kind = integer ? 'integer' : 'number';
     const range = Number.isFinite(max) ? ` between ${min} and ${max}` : ` >= ${min}`;
-    throw new Error(`Invalid config "${key}": expected a ${kind}${range}.`);
+    throw new Error(`Invalid config "${label}": expected a ${kind}${range}.`);
   }
 }
 
@@ -449,6 +453,30 @@ export function validateConfig(config) {
     assertNumber(settings, 'concurrency', { integer: true, min: 1, max: 4 });
     if (settings.maxTotalTokens < settings.chunkInputTokens)
       throw new Error('largeChange.maxTotalTokens must cover one input request.');
+    if (!object(settings.cache))
+      throw new Error('Invalid config "largeChange.cache": expected an object.');
+    assertKnownKeys(
+      settings.cache,
+      new Set(Object.keys(DEFAULT_LARGE_CHANGE.cache)),
+      'largeChange.cache',
+    );
+    const cache = { ...DEFAULT_LARGE_CHANGE.cache, ...settings.cache };
+    for (const key of ['enabled', 'allowUnprotected']) {
+      if (typeof cache[key] !== 'boolean')
+        throw new Error(`Invalid config "largeChange.cache.${key}": expected a boolean.`);
+    }
+    assertNumber(cache, 'ttlMs', {
+      integer: true,
+      min: 60_000,
+      max: 7 * 24 * 60 * 60 * 1000,
+      label: 'largeChange.cache.ttlMs',
+    });
+    assertNumber(cache, 'maxBytes', {
+      integer: true,
+      min: 1024 * 1024,
+      max: 256 * 1024 * 1024,
+      label: 'largeChange.cache.maxBytes',
+    });
   }
   assertUrl(config, 'apiUrl');
   assertString(config, 'modelId');