@goodandready/dsh-moa 0.2.72 → 0.2.74

package/lib/pipeline/runner.js

@@ -1,3 +1,6 @@
+import { evaluateJudgeEscalation } from './escalation.js'
+import { calculateSelfConsistencyAgreement } from './self-consistency.js'
+import { pruneCandidateEnsemble, formatPruningDirective } from './context-pruner.js'
 import { buildAstCompositeMergeDirective } from '../moa-ast-merge.js'
 import { runVisualMoaConsensus } from '../moa-visual-consensus.js'
 import crypto from 'node:crypto'
@@ -65,6 +68,9 @@ export async function runMoAPipeline({
     isFastMode: ctxStage.isFastMode,
     collectedCtx: ctxStage.collectedCtx,
     testGateEnabled, testCommand, execFn,
+    semanticCacheEnabled: ctxStage.semanticCacheEnabled,
+    semanticCacheTtlHours: ctxStage.semanticCacheTtlHours,
+    ctx,
   })
   if (!candStage.ok) {
     if (candStage.abort) return { error: candStage.error }
@@ -102,6 +108,13 @@ export async function runMoAPipeline({
   })
   const syntaxDirective = syntaxResult.filterApplied ? formatSyntaxDirective(referenceOutputs, { blind: ctxStage.isBlindEvaluation }) : null
 
+  if (ctxStage.selfConsistencyExpanded && successfulRefs.length > 1) {
+    const scAgreement = calculateSelfConsistencyAgreement(successfulRefs)
+    if (typeof onProgress === 'function') {
+      onProgress(`🎯 *Self-Consistency Agreement: ${(scAgreement.agreementRatio * 100).toFixed(0)}% (${scAgreement.isStrongConsensus ? 'Strong consensus' : 'Divergent sampling'}) across ${scAgreement.sampleCount} samples*\n`)
+    }
+  }
+
   // Stage 3: Clarifying Questions Branch
   if (ctxStage.needsQuestions) {
     return await stageClarifyingQuestions({
@@ -186,11 +199,56 @@ export async function runMoAPipeline({
     return { error: new Error('Turn aborted') }
   }
 
+  // Pre-Stage 6: Dynamic Consensus Threshold & Multi-Judge Escalation (#300)
+  const escalationResult = evaluateJudgeEscalation({
+    candidateOutputs: syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
+    primaryJudge: ctxStage.primaryJudge,
+    fallbackJudges: ctxStage.fallbackJudges,
+    escalationJudge: ctxStage.escalationJudge,
+    policy: ctxStage.escalationPolicy,
+    threshold: ctxStage.escalationDisagreementThreshold,
+  })
+
+  let effectivePrimaryJudge = ctxStage.primaryJudge
+  let effectiveFallbackJudges = ctxStage.fallbackJudges
+  let effectiveJudgesChain = ctxStage.judgesChain
+  let effectivePreset = preset
+
+  if (escalationResult.escalated) {
+    emitEvent(ctx, MOA_EVENTS.JUDGE_ESCALATION, {
+      runId,
+      policy: ctxStage.escalationPolicy,
+      disagreement: escalationResult.disagreement,
+      threshold: escalationResult.threshold,
+      escalatedType: escalationResult.escalatedType,
+      originalJudge: escalationResult.originalJudge,
+      escalatedJudge: escalationResult.judge,
+      councilJudges: escalationResult.councilJudges,
+    })
+    if (typeof onProgress === 'function') {
+      onProgress(`⚖️ *Judge Escalation (${escalationResult.escalatedType}): ${escalationResult.reason}*\n`)
+    }
+
+    if (escalationResult.escalatedType === 'auto_upgrade') {
+      effectivePrimaryJudge = escalationResult.judge
+      effectiveFallbackJudges = ctxStage.fallbackJudges.filter(
+        (j) => !(j.provider === escalationResult.judge.provider && j.model === escalationResult.judge.model)
+      )
+      effectiveJudgesChain = [effectivePrimaryJudge, ...effectiveFallbackJudges]
+    } else if (escalationResult.escalatedType === 'council_majority') {
+      effectivePreset = {
+        ...preset,
+        multi_judge_enabled: true,
+        judge_models: escalationResult.councilJudges,
+      }
+    }
+  }
+
   // Stage 6: Multi-Judge Panel
   const mjRes = await stageMultiJudge({
-    preset,
+    preset: effectivePreset,
     successfulRefs: syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
-    referenceOutputs, primaryJudge: ctxStage.primaryJudge,
+    referenceOutputs, primaryJudge: effectivePrimaryJudge,
     userPrompt, judgeCriteria: ctxStage.judgeCriteria, prices, maxTokens: ctxStage.maxTokens,
     callLlm, signal, onProgress, cwd, runId, isRefinement: ctxStage.isRefinement,
     isFastMode: ctxStage.isFastMode, collectedCtx: ctxStage.collectedCtx, startTime,
@@ -218,18 +276,50 @@ export async function runMoAPipeline({
   const rawFileDirective = (preset?.interactive_workbench_enabled)
     ? formatFileScoresDirective()
     : null
-  const fileScoringDirective = [rawFileDirective, visualResult?.directive, adversarialTddResult?.directive, syntaxDirective].filter(Boolean).join("\n\n") || null
+
+  // Pre-Judge Stage 6.8: Cross-Candidate Unchanged Base Context Pruning (#305)
+  let synthCandidateRefs = syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs
+  let synthReferenceOutputs = referenceOutputs
+  let pruningDirective = null
+  if (ctxStage.contextPruningEnabled && ctxStage.collectedCtx?.files?.length > 0) {
+    const pruneRes = pruneCandidateEnsemble(synthCandidateRefs, ctxStage.collectedCtx.files, {
+      enabled: true,
+      contextLines: ctxStage.contextPruningDiffLines,
+    })
+    if (pruneRes.isPruned) {
+      synthCandidateRefs = pruneRes.candidates
+      const prunedByLabel = new Map(synthCandidateRefs.map((c) => [c.label, c.text]))
+      synthReferenceOutputs = referenceOutputs.map((r) => {
+        if (prunedByLabel.has(r.label)) {
+          return { ...r, text: prunedByLabel.get(r.label) }
+        }
+        return r
+      })
+      pruningDirective = formatPruningDirective(pruneRes.prunedFiles, pruneRes.totalSavedTokens)
+      emitEvent(ctx, MOA_EVENTS.CONTEXT_PRUNING, {
+        runId,
+        savedTokens: pruneRes.totalSavedTokens,
+        prunedFiles: pruneRes.prunedFiles,
+      })
+      if (typeof onProgress === 'function') {
+        onProgress(`✂️ *Context Pruning: Reduced ~${pruneRes.totalSavedTokens} prompt tokens across ${pruneRes.prunedFiles.length} file block(s)*\n`)
+      }
+    }
+  }
+
+  const fileScoringDirective = [rawFileDirective, visualResult?.directive, adversarialTddResult?.directive, syntaxDirective, pruningDirective].filter(Boolean).join("\n\n") || null
 
   // Stage 7: Synthesis Phase
   const synthRes = await stageSynthesis({
-    userPrompt, referenceOutputs,
-    successfulRefs: syntaxResult.validCandidates.length > 0 ? syntaxResult.validCandidates : successfulRefs,
+    userPrompt,
+    referenceOutputs: synthReferenceOutputs,
+    successfulRefs: synthCandidateRefs,
     judgeCriteria: ctxStage.judgeCriteria,
     isCuratorSynthesis: ctxStage.isCuratorSynthesis, isBlindEvaluation: ctxStage.isBlindEvaluation,
     priorTurnBaseline: ctxStage.priorTurnBaseline, compositeMergeDirective, fileScoringDirective,
-    multiJudgeResult, preset, prices, maxTokens: ctxStage.maxTokens, isFastMode: ctxStage.isFastMode,
-    primaryJudge: ctxStage.primaryJudge, fallbackJudges: ctxStage.fallbackJudges,
-    judgesChain: ctxStage.judgesChain, aggTemp: ctxStage.aggTemp,
+    multiJudgeResult, preset: effectivePreset, prices, maxTokens: ctxStage.maxTokens, isFastMode: ctxStage.isFastMode,
+    primaryJudge: effectivePrimaryJudge, fallbackJudges: effectiveFallbackJudges,
+    judgesChain: effectiveJudgesChain, aggTemp: ctxStage.aggTemp,
     aggTimeoutSec: ctxStage.aggTimeoutSec, isStreamAggregator: ctxStage.isStreamAggregator,
     onStreamDelta, signal, callLlm, onProgress, cwd, runId, isRefinement: ctxStage.isRefinement,
     collectedCtx: ctxStage.collectedCtx, startTime,
@@ -260,4 +350,4 @@ export async function runMoAPipeline({
   }
   return promRes.payload
 }
-
+

package/lib/pipeline/self-consistency.js

@@ -0,0 +1,135 @@
+/**
+ * Self-Consistency Temperature Sampling for Single Models (#301)
+ *
+ * Allows users with a single model slot (e.g., local Ollama/vLLM or a single API key)
+ * to benefit from Mixture of Agents ensemble diversity by generating parallel samples
+ * at varying temperatures and complementary system personas, followed by consistency voting.
+ */
+
+import { ROLE_PERSONA_PROMPTS } from '../moa-prompts.js'
+
+export const DEFAULT_SELF_CONSISTENCY_TEMPERATURES = Object.freeze([0.2, 0.6, 0.9])
+export const DEFAULT_SELF_CONSISTENCY_PERSONAS = Object.freeze(['proposer', 'challenger', 'minimalist'])
+
+/**
+ * Expands a single reference model into multiple parallel proposer slots
+ * with distinct temperatures and complementary reasoning personas.
+ *
+ * @param {Array<object>} referenceModels - Original reference model slots
+ * @param {object} [options]
+ * @param {boolean} [options.enabled=false] - Whether self-consistency expansion is enabled
+ * @param {number} [options.samples=3] - Number of candidate samples to generate (2-10)
+ * @param {Array<number>} [options.temperatures] - Array of temperatures for samples
+ * @param {Array<string>} [options.personas] - Array of persona role names
+ * @returns {{ references: Array<object>, isExpanded: boolean, sampleCount: number }}
+ */
+export function expandSelfConsistencySlots(referenceModels = [], options = {}) {
+  const {
+    enabled = false,
+    samples = 3,
+    temperatures = DEFAULT_SELF_CONSISTENCY_TEMPERATURES,
+    personas = DEFAULT_SELF_CONSISTENCY_PERSONAS,
+  } = options
+
+  // Expansion applies only when explicitly enabled or requested
+  if (!enabled) {
+    return {
+      references: Array.isArray(referenceModels) ? referenceModels : [],
+      isExpanded: false,
+      sampleCount: Array.isArray(referenceModels) ? referenceModels.length : 0,
+    }
+  }
+
+  const rawList = Array.isArray(referenceModels) && referenceModels.length > 0
+    ? referenceModels
+    : [{ provider: '', model: '' }]
+
+  // Only expand when a single model slot is configured
+  if (rawList.length !== 1) {
+    return {
+      references: rawList,
+      isExpanded: false,
+      sampleCount: rawList.length,
+    }
+  }
+
+  const baseSlot = rawList[0] || {}
+  const count = Math.min(10, Math.max(2, Number(samples) || 3))
+  const expandedList = []
+
+  for (let i = 0; i < count; i++) {
+    const temp = Array.isArray(temperatures) && typeof temperatures[i] === 'number'
+      ? temperatures[i]
+      : (DEFAULT_SELF_CONSISTENCY_TEMPERATURES[i % DEFAULT_SELF_CONSISTENCY_TEMPERATURES.length] || 0.6)
+
+    const role = Array.isArray(personas) && personas[i]
+      ? personas[i]
+      : (DEFAULT_SELF_CONSISTENCY_PERSONAS[i % DEFAULT_SELF_CONSISTENCY_PERSONAS.length] || 'proposer')
+
+    expandedList.push({
+      ...baseSlot,
+      label: baseSlot.label
+        ? `${baseSlot.label} [T=${temp}, ${role}]`
+        : `Sample ${i + 1} (${baseSlot.model || 'model'}, T=${temp})`,
+      temperature: temp,
+      role_persona: role,
+      sampleIndex: i + 1,
+      isSelfConsistencySample: true,
+    })
+  }
+
+  return {
+    references: expandedList,
+    isExpanded: true,
+    sampleCount: expandedList.length,
+  }
+}
+
+/**
+ * Calculates majority agreement and self-consistency metrics across candidate outputs.
+ *
+ * @param {Array<object>} candidateOutputs - Array of successful candidate results
+ * @returns {{ agreementRatio: number, isStrongConsensus: boolean, sampleCount: number }}
+ */
+export function calculateSelfConsistencyAgreement(candidateOutputs = []) {
+  if (!Array.isArray(candidateOutputs) || candidateOutputs.length < 2) {
+    return {
+      agreementRatio: 1.0,
+      isStrongConsensus: true,
+      sampleCount: Array.isArray(candidateOutputs) ? candidateOutputs.length : 0,
+    }
+  }
+
+  const texts = candidateOutputs
+    .filter((c) => c && typeof c.text === 'string' && c.text.trim())
+    .map((c) => c.text.trim().toLowerCase().replace(/\s+/g, ' '))
+
+  if (texts.length < 2) {
+    return {
+      agreementRatio: 1.0,
+      isStrongConsensus: true,
+      sampleCount: texts.length,
+    }
+  }
+
+  // Count exact and near-match clusters
+  let maxClusterSize = 1
+  for (let i = 0; i < texts.length; i++) {
+    let clusterSize = 1
+    for (let j = 0; j < texts.length; j++) {
+      if (i === j) continue
+      // If texts are very similar (> 85% overlap)
+      if (texts[i] === texts[j] || (texts[i].length > 20 && texts[j].includes(texts[i].slice(0, 40)))) {
+        clusterSize++
+      }
+    }
+    if (clusterSize > maxClusterSize) maxClusterSize = clusterSize
+  }
+
+  const agreementRatio = Number((maxClusterSize / texts.length).toFixed(2))
+  return {
+    agreementRatio,
+    isStrongConsensus: agreementRatio >= 0.66,
+    sampleCount: texts.length,
+  }
+}

package/lib/pipeline/semantic-cache.js

@@ -0,0 +1,348 @@
+import { bestEffort } from '../best-effort.js'
+import { emitEvent, MOA_EVENTS } from '../events.js'
+/**
+ * Semantic Caching for Intermediate Candidate Generations (#318)
+ *
+ * Persists and resolves candidate generations and similarity fingerprints locally
+ * to eliminate duplicate API costs during iterative development, questionnaire retries,
+ * or recurring benchmark runs.
+ */
+
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+// Runtime metrics tracking
+let _runtimeHits = 0
+let _runtimeMisses = 0
+let _runtimeSavedTokens = 0
+let _runtimeSavedCostUsd = 0
+
+/**
+ * Resets runtime cache hit/miss statistics (useful for tests).
+ */
+export function resetRuntimeCacheStats() {
+  _runtimeHits = 0
+  _runtimeMisses = 0
+  _runtimeSavedTokens = 0
+  _runtimeSavedCostUsd = 0
+}
+
+/**
+ * Normalizes prompt text to eliminate trivial whitespace or capitalization variations.
+ *
+ * @param {string} prompt
+ * @returns {string}
+ */
+export function normalizePrompt(prompt = '') {
+  if (typeof prompt !== 'string') return ''
+  return prompt
+    .trim()
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map((line) => line.trim().replace(/[ \t]+/g, ' '))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+}
+
+/**
+ * Computes a deterministic SHA-256 fingerprint for a candidate generation request.
+ *
+ * @param {string} prompt
+ * @param {object} [options]
+ * @param {string} [options.model='']
+ * @param {number} [options.temperature=0.6]
+ * @param {string} [options.systemPrompt='']
+ * @param {string} [options.contextHash='']
+ * @returns {string}
+ */
+export function computePromptFingerprint(prompt = '', options = {}) {
+  const {
+    model = '',
+    temperature = 0.6,
+    systemPrompt = '',
+    contextHash = '',
+  } = options
+
+  const normPrompt = normalizePrompt(prompt)
+  const normSys = normalizePrompt(systemPrompt)
+  const roundedTemp = Number(temperature || 0).toFixed(2)
+
+  const payload = [
+    normPrompt,
+    String(model || '').trim().toLowerCase(),
+    roundedTemp,
+    normSys,
+    String(contextHash || ''),
+  ].join(':::')
+
+  return crypto.createHash('sha256').update(payload, 'utf8').digest('hex')
+}
+
+/**
+ * Resolves the cache directory, ensuring it is created safely.
+ *
+ * @param {string} cwd - Base workspace directory
+ * @param {string} [customDir]
+ * @returns {string}
+ */
+export function resolveCacheDir(cwd = process.cwd(), customDir = null) {
+  const dir = customDir
+    ? path.resolve(cwd, customDir)
+    : path.resolve(cwd, '.moa', 'cache', 'semantic')
+  try {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true })
+    }
+  } catch (_err) {
+    /* ignore directory creation errors */
+  }
+  return dir
+}
+
+/**
+ * Retrieves a cached candidate generation entry.
+ *
+ * @param {string} key - SHA-256 cache fingerprint
+ * @param {object} [options]
+ * @param {string} [options.cacheDir]
+ * @param {number} [options.maxAgeMs=604800000] - 7 days default TTL
+ * @returns {object|null}
+ */
+export function getCacheEntry(key, options = {}) {
+  if (!key || typeof key !== 'string') return null
+  const { cacheDir, maxAgeMs = 7 * 24 * 60 * 60 * 1000 } = options
+  const targetDir = resolveCacheDir(options.cwd, cacheDir)
+  const filePath = path.join(targetDir, `${key}.json`)
+
+  try {
+    if (!fs.existsSync(filePath)) {
+      _runtimeMisses++
+      return null
+    }
+
+    const raw = fs.readFileSync(filePath, 'utf8')
+    const entry = JSON.parse(raw)
+    const now = Date.now()
+
+    if (entry.createdAt && (now - entry.createdAt > (entry.ttlMs || maxAgeMs))) {
+      // Expired entry
+      bestEffort('unlink expired cache entry', () => fs.unlinkSync(filePath))
+      _runtimeMisses++
+      return null
+    }
+
+    _runtimeHits++
+    const tokens = entry.usage?.totalTokens || 0
+    const cost = entry.costUsd || 0
+    _runtimeSavedTokens += tokens
+    _runtimeSavedCostUsd += cost
+
+    // Update access metadata
+    entry.lastAccessedAt = now
+    entry.hitCount = (entry.hitCount || 0) + 1
+    bestEffort('update cache access metadata', () => {
+      fs.writeFileSync(filePath, JSON.stringify(entry, null, 2), 'utf8')
+    })
+
+    return entry
+  } catch (_err) {
+    _runtimeMisses++
+    return null
+  }
+}
+
+/**
+ * Stores a candidate generation output into the semantic cache.
+ *
+ * @param {string} key - Cache fingerprint
+ * @param {object} entryData - Candidate generation payload
+ * @param {object} [options]
+ * @param {string} [options.cacheDir]
+ * @param {number} [options.ttlMs=604800000]
+ * @returns {boolean}
+ */
+export function setCacheEntry(key, entryData = {}, options = {}) {
+  if (!key || typeof key !== 'string') return false
+  const { cacheDir, ttlMs = 7 * 24 * 60 * 60 * 1000 } = options
+  const targetDir = resolveCacheDir(options.cwd, cacheDir)
+  const filePath = path.join(targetDir, `${key}.json`)
+
+  const payload = {
+    key,
+    model: entryData.model || '',
+    output: entryData.output || entryData.text || '',
+    usage: entryData.usage || { totalTokens: 0, promptTokens: 0, completionTokens: 0 },
+    costUsd: entryData.costUsd || 0,
+    createdAt: Date.now(),
+    ttlMs: entryData.ttlMs || ttlMs,
+    hitCount: 0,
+    metadata: entryData.metadata || {},
+  }
+
+  try {
+    fs.writeFileSync(filePath, JSON.stringify(payload, null, 2), 'utf8')
+    return true
+  } catch (_err) {
+    return false
+  }
+}
+
+/**
+ * Clears expired or all entries from the semantic cache.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cacheDir]
+ * @param {number} [options.olderThanMs]
+ * @returns {{ clearedCount: number }}
+ */
+export function clearSemanticCache(options = {}) {
+  const { cacheDir, olderThanMs = null } = options
+  const targetDir = resolveCacheDir(options.cwd, cacheDir)
+  let clearedCount = 0
+
+  try {
+    if (!fs.existsSync(targetDir)) return { clearedCount: 0 }
+    const files = fs.readdirSync(targetDir)
+    const now = Date.now()
+
+    for (const f of files) {
+      if (!f.endsWith('.json')) continue
+      const filePath = path.join(targetDir, f)
+      if (typeof olderThanMs === 'number' && olderThanMs > 0) {
+        try {
+          const raw = fs.readFileSync(filePath, 'utf8')
+          const entry = JSON.parse(raw)
+          if (now - (entry.createdAt || 0) < olderThanMs) {
+            continue
+          }
+        } catch (_err) {
+          /* corrupt file, proceed to unlink */
+        }
+      }
+      bestEffort('unlink cleared cache entry', () => {
+        fs.unlinkSync(filePath)
+        clearedCount++
+      })
+    }
+  } catch (_err) {
+    /* ignore read/delete errors */
+  }
+
+  return { clearedCount }
+}
+
+/**
+ * Returns cache usage metrics and statistics.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+export function getSemanticCacheStats(options = {}) {
+  const { cacheDir } = options
+  const targetDir = resolveCacheDir(options.cwd, cacheDir)
+  let entriesCount = 0
+  let totalSizeBytes = 0
+
+  try {
+    if (fs.existsSync(targetDir)) {
+      const files = fs.readdirSync(targetDir)
+      for (const f of files) {
+        if (!f.endsWith('.json')) continue
+        try {
+          const stat = fs.statSync(path.join(targetDir, f))
+          entriesCount++
+          totalSizeBytes += stat.size
+        } catch (_err) {
+          /* file unlinked concurrently */
+        }
+      }
+    }
+  } catch (_err) {
+    /* ignore dir access errors */
+  }
+
+  return {
+    entriesCount,
+    totalSizeBytes,
+    hits: _runtimeHits,
+    misses: _runtimeMisses,
+    savedTokens: _runtimeSavedTokens,
+    savedCostUsd: Number(_runtimeSavedCostUsd.toFixed(5)),
+  }
+}
+
+
+/**
+ * Wraps callLlm with local semantic caching for intermediate candidate generations (#318).
+ *
+ * @param {Function} callLlm - Raw LLM invocation function
+ * @param {object} [options]
+ * @param {boolean} [options.enabled=false]
+ * @param {number} [options.ttlMs=604800000]
+ * @param {string} [options.cwd]
+ * @param {object} [options.ctx]
+ * @returns {Function}
+ */
+export function createCachingCallLlm(callLlm, options = {}) {
+  const { enabled = false, ttlMs = 7 * 24 * 60 * 60 * 1000, cwd, ctx } = options
+  if (!enabled || typeof callLlm !== 'function') return callLlm
+
+  return async function cachedCallLlm(callArgs) {
+    if (!callArgs || typeof callArgs !== 'object') {
+      return callLlm(callArgs)
+    }
+
+    const messages = Array.isArray(callArgs.messages) ? callArgs.messages : []
+    const promptText = messages
+      .filter((m) => m && m.role === 'user')
+      .map((m) => m.content)
+      .join('\n') || String(callArgs.prompt || '')
+    const systemPrompt = messages
+      .filter((m) => m && m.role === 'system')
+      .map((m) => m.content)
+      .join('\n') || ''
+
+    const modelName = callArgs.model
+      ? (callArgs.provider ? `${callArgs.provider}:${callArgs.model}` : callArgs.model)
+      : ''
+
+    const key = computePromptFingerprint(promptText, {
+      model: modelName,
+      temperature: callArgs.temperature ?? 0.6,
+      systemPrompt,
+    })
+
+    const cached = getCacheEntry(key, { cwd, maxAgeMs: ttlMs })
+    if (cached && typeof cached.output === 'string' && cached.output.length > 0) {
+      emitEvent(ctx, MOA_EVENTS.CACHE_HIT, { key, model: modelName })
+      return {
+        text: cached.output,
+        content: cached.output,
+        usage: cached.usage || { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+        costUsd: 0,
+        cached: true,
+      }
+    }
+
+    const res = await callLlm(callArgs)
+    const text = typeof res === 'string' ? res : (res?.content || res?.text || '')
+    if (text) {
+      const usage = (typeof res === 'object' && res?.usage) ? res.usage : {
+        inputTokens: Math.max(1, Math.round((promptText.length + systemPrompt.length) / 4)),
+        outputTokens: Math.max(1, Math.round(text.length / 4)),
+        totalTokens: Math.max(2, Math.round((promptText.length + systemPrompt.length + text.length) / 4)),
+      }
+      const costUsd = typeof res === 'object' && typeof res?.costUsd === 'number' ? res.costUsd : 0
+      setCacheEntry(key, {
+        model: modelName,
+        output: text,
+        usage,
+        costUsd,
+        ttlMs,
+      }, { cwd, ttlMs })
+    }
+
+    return res
+  }
+}

package/lib/routes/cache.js

@@ -0,0 +1,42 @@
+/**
+ * Semantic Cache Management Routes (#318)
+ * Exposes inspection and purge endpoints for locally cached candidate generations.
+ */
+
+import { getSemanticCacheStats, clearSemanticCache } from '../pipeline/semantic-cache.js'
+import { writeJson, readBody, assertAuthorizedRequest } from '../access.js'
+import { isSafeWriteRequest } from '../updater.js'
+
+export function registerCacheRoutes(ctx, { workspaceRoot }) {
+  ctx.effect(() => {
+    return ctx.webServer.register({
+      kind: 'exact',
+      path: '/dsh-moa/cache',
+      handler: async (req, res) => {
+        if (!assertAuthorizedRequest(req, res, ctx)) return
+        if (req.method === 'GET') {
+          const stats = getSemanticCacheStats({ cwd: workspaceRoot })
+          return writeJson(res, 200, { ok: true, stats })
+        }
+        if (req.method === 'POST') {
+          if (!isSafeWriteRequest(req)) {
+            return writeJson(res, 403, { ok: false, error: 'Forbidden: cross-site request rejected' })
+          }
+          let olderThanMs = null
+          try {
+            const raw = await readBody(req)
+            if (raw) {
+              const body = JSON.parse(raw)
+              if (typeof body.olderThanMs === 'number') olderThanMs = body.olderThanMs
+            }
+          } catch (_err) {
+            /* ignore invalid body for clear */
+          }
+          const result = clearSemanticCache({ cwd: workspaceRoot, olderThanMs })
+          return writeJson(res, 200, { ok: true, clearedCount: result.clearedCount })
+        }
+        return writeJson(res, 405, { ok: false, error: 'GET or POST required' })
+      },
+    })
+  })
+}

package/lib/routes.js

@@ -7,15 +7,18 @@ import { registerPresetRoutes } from './routes/presets.js'
 import { registerHistoryRoutes } from './routes/history.js'
 import { registerWorkbenchRoutes } from './routes/workbench.js'
 import { registerPipelineRoutes } from './routes/pipeline.js'
+import { registerCacheRoutes } from './routes/cache.js'
 
 export { registerPresetRoutes } from './routes/presets.js'
 export { registerHistoryRoutes } from './routes/history.js'
 export { registerWorkbenchRoutes } from './routes/workbench.js'
 export { registerPipelineRoutes } from './routes/pipeline.js'
+export { registerCacheRoutes } from './routes/cache.js'
 
 export function registerMoaRoutes(ctx, deps) {
   registerPresetRoutes(ctx, deps)
   registerHistoryRoutes(ctx, deps)
   registerWorkbenchRoutes(ctx, deps)
   registerPipelineRoutes(ctx, deps)
+  registerCacheRoutes(ctx, deps)
 }