opencode-agent-skill 7.7.0 → 9.0.0

package/lib/orchestrator-policy.mjs

@@ -1,35 +1,116 @@
-const HIGH_RISK = /(auth|security|permission|payment|migration|schema|database|production|deploy|public api|breaking|secret|credential)/i
-const LONG = /(whole repo|whole repository|entire repo|entire project|long[- ]running|multi[- ]file|cross[- ]module|resume|migration|refactor all)/i
+const HIGH_RISK = /(auth|security|permission|payment|migration|schema|database|production|deploy|public api|breaking|secret|credential|phân quyền|bảo mật|thanh toán|cơ sở dữ liệu|triển khai|migrate|migration)/i
+const LONG = /(whole repo|whole repository|whole project|entire repo|entire project|large refactor|major refactor|long[- ](?:running|horizon)|durable state|dependency graph|integration verification|resume|migration|refactor all|toàn bộ repo|toàn bộ repository|toàn bộ dự án|toàn bộ project|refactor lớn|tác vụ dài|nhiều file|nhiều module|tiếp tục công việc|refactor toàn bộ|xác minh tích hợp|kiểm tra tích hợp|chia (?:công việc|task|tác vụ).*(?:dependency|phụ thuộc))/i
+const DEBUG = /(fix|bug|debug|crash|regression|failure|error|broken|sửa lỗi|lỗi|điều tra lỗi|không chạy)/i
+const CONTRACT = /(public api|api contract|openapi|response schema|request schema|breaking api|hợp đồng api|api công khai)/i
+const DATA = /(database|sql|migration|schema|transaction|index|cơ sở dữ liệu|dữ liệu|migrate)/i
+
+function signal(name, matched, weight) {
+  return matched ? { name, weight } : null
+}
+
+function profileFor(mode, risk) {
+  if (mode === "inline" && risk === "low") {
+    return {
+      name: "fast",
+      maxSkills: 2,
+      contextBudget: 12_000,
+      contextStrategy: "incremental-semantic",
+      durableState: false,
+      worktree: "off",
+      critic: "off",
+      verification: "targeted",
+      fullCI: false,
+      containerVerification: "off",
+    }
+  }
+  if (mode === "long-horizon" || risk === "high") {
+    return {
+      name: "deep",
+      maxSkills: 5,
+      contextBudget: 48_000,
+      contextStrategy: "semantic+graph+git",
+      durableState: true,
+      worktree: "auto-writers",
+      critic: "required-for-high-risk-or-final",
+      verification: "targeted+integration",
+      fullCI: true,
+      containerVerification: risk === "high" ? "preferred-if-capable" : "optional",
+    }
+  }
+  return {
+    name: "standard",
+    maxSkills: 4,
+    contextBudget: 24_000,
+    contextStrategy: "incremental-semantic+git",
+    durableState: false,
+    worktree: "auto-on-conflict",
+    critic: "on-failure-or-elevated-risk",
+    verification: "targeted+affected",
+    fullCI: false,
+    containerVerification: "off",
+  }
+}
 
 export function classifyEngineeringTask(text, facts = {}) {
   const value = String(text || "")
-  let score = 0
-  if (value.length > 250) score += 1
-  if (value.length > 700) score += 1
-  if (HIGH_RISK.test(value)) score += 2
-  if (LONG.test(value)) score += 2
-  if (Number(facts.changedFiles || 0) > 5) score += 1
-  if (Number(facts.changedFiles || 0) > 12) score += 1
-  if (facts.hasMigration || facts.hasPublicContract) score += 2
+  const declaredHighRisk =
+    ["high", "critical"].includes(String(facts.risk || "").toLowerCase()) ||
+    /\b(?:risk|rủi ro)\s*[:=-]?\s*(?:high|critical|cao|nghiêm trọng)\b/i.test(value)
+  const explicitLongHorizon = LONG.test(value)
+  const signals = [
+    signal("long-request-text", value.length > 700, 1),
+    signal("medium-request-text", value.length > 250, 1),
+    signal("high-risk-domain", HIGH_RISK.test(value), 2),
+    signal("declared-high-risk", declaredHighRisk, 2),
+    signal("explicit-long-horizon", explicitLongHorizon, 2),
+    signal("debugging", DEBUG.test(value), 1),
+    signal("public-contract", CONTRACT.test(value) || facts.hasPublicContract, 2),
+    signal("data-migration", (DATA.test(value) && /migration|schema|migrate|di trú|chuyển đổi/i.test(value)) || facts.hasMigration, 2),
+    signal("many-changed-files", Number(facts.changedFiles || 0) > 5, 1),
+    signal("very-many-changed-files", Number(facts.changedFiles || 0) > 12, 1),
+    signal("large-repository", Number(facts.repoFiles || 0) > 1500, 1),
+    signal("monorepo", facts.monorepo === true, 1),
+  ].filter(Boolean)
 
-  const risk = HIGH_RISK.test(value) || facts.hasMigration || facts.hasPublicContract
-    ? "high"
-    : score >= 3 ? "medium" : "low"
-
-  const mode = score >= 4 ? "long-horizon" : score >= 2 ? "standard" : "inline"
-  const modelTier = risk === "high" || score >= 4 ? "heavy" : score >= 2 ? "standard" : "light"
+  const score = signals.reduce((sum, item) => sum + item.weight, 0)
+  const highRisk = declaredHighRisk || HIGH_RISK.test(value) || Boolean(facts.hasMigration) || Boolean(facts.hasPublicContract)
+  const risk = highRisk ? "high" : score >= 3 ? "medium" : "low"
+  const mode = explicitLongHorizon || score >= 4 ? "long-horizon" : score >= 2 ? "standard" : "inline"
+  const modelTier = risk === "high" || mode === "long-horizon" ? "heavy" : score >= 2 ? "standard" : "light"
   const maxAttempts = risk === "high" ? 2 : 3
-  const contextBudget = mode === "long-horizon" ? 48_000 : mode === "standard" ? 32_000 : 16_000
+  const profile = profileFor(mode, risk)
+
+  const domains = []
+  if (/(auth|permission|tenant|token|session|phân quyền|xác thực)/i.test(value)) domains.push("auth-security")
+  if (/(payment|checkout|refund|webhook|thanh toán|hoàn tiền)/i.test(value)) domains.push("payment")
+  if (DATA.test(value)) domains.push("database")
+  if (CONTRACT.test(value)) domains.push("api-contract")
+  if (/(react native|expo|android|ios|gradle|xcode)/i.test(value)) domains.push("react-native")
+  else if (/(next\.js|nextjs|app router|server component)/i.test(value)) domains.push("nextjs")
+  else if (/\breact\b|useeffect|usestate|component/i.test(value)) domains.push("react")
+  if (/(docker|kubernetes|terraform|github actions|ci\/cd|deploy|triển khai)/i.test(value)) domains.push("devops")
 
   return {
-    schemaVersion: 1,
+    schemaVersion: 3,
     score,
     risk,
     mode,
+    executionProfile: profile.name,
     modelTier,
     maxAttempts,
-    contextBudget,
-    requirePlanCheck: mode === "long-horizon" || risk === "high",
+    contextBudget: profile.contextBudget,
+    maxSkills: profile.maxSkills,
+    requirePlanCheck: profile.durableState || risk === "high",
     requireIntegrationVerification: mode !== "inline" || risk === "high",
+    requireFreshEvidence: true,
+    profile,
+    domains: [...new Set(domains)],
+    signals,
+    antiHallucination: {
+      evidenceFirst: true,
+      noCompletionWithoutVerification: mode !== "inline" || risk === "high",
+      noUnsupportedSemanticClaims: true,
+      failClosedOnMissingCapability: risk === "high",
+    },
   }
 }

package/lib/process-runner.mjs

@@ -6,16 +6,17 @@ function appendBounded(current, chunk, limit) {
   return next.slice(next.length - limit)
 }
 
-function killTree(child) {
+function killTree(child, force = false) {
   if (!child?.pid) return
   if (process.platform === "win32") {
     spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" })
     return
   }
+  const signal = force ? "SIGKILL" : "SIGTERM"
   try {
-    process.kill(-child.pid, "SIGTERM")
+    process.kill(-child.pid, signal)
   } catch {
-    try { child.kill("SIGTERM") } catch {}
+    try { child.kill(signal) } catch {}
   }
 }
 
@@ -34,6 +35,7 @@ export function runProcess(executable, args = [], options = {}) {
     let idleTimedOut = false
     let aborted = false
     let finished = false
+    let escalationTimer = null
 
     const child = spawn(executable, args, {
       cwd: options.cwd,
@@ -46,6 +48,7 @@ export function runProcess(executable, args = [], options = {}) {
     const cleanup = () => {
       clearInterval(heartbeatTimer)
       clearInterval(watchdogTimer)
+      if (escalationTimer) clearTimeout(escalationTimer)
       if (options.signal) options.signal.removeEventListener("abort", onAbort)
     }
 
@@ -54,7 +57,9 @@ export function runProcess(executable, args = [], options = {}) {
       finished = true
       cleanup()
       resolve({
-        status: Number.isInteger(status) ? status : (spawnError || signal || timedOut || idleTimedOut || aborted) ? 1 : 0,
+        status: (spawnError || signal || timedOut || idleTimedOut || aborted)
+          ? (Number.isInteger(status) && status !== 0 ? status : 1)
+          : (Number.isInteger(status) ? status : 0),
         signal: signal || null,
         stdout,
         stderr: spawnError ? appendBounded(stderr, String(spawnError.message || spawnError), maxBuffer) : stderr,
@@ -89,24 +94,40 @@ export function runProcess(executable, args = [], options = {}) {
         }, heartbeatMs)
       : null
 
+    const requestStop = () => {
+      killTree(child)
+      if (process.platform !== "win32" && !escalationTimer) {
+        const graceMs = Math.max(100, Number(options.killGraceMs ?? 2_000))
+        escalationTimer = setTimeout(() => {
+          if (!finished) killTree(child, true)
+        }, graceMs)
+        escalationTimer.unref?.()
+      }
+    }
+
     const watchdogTimer = (timeoutMs > 0 || idleTimeoutMs > 0)
       ? setInterval(() => {
           const now = Date.now()
           if (timeoutMs > 0 && now - startedAt >= timeoutMs) {
-            timedOut = true
-            killTree(child)
+            if (!timedOut) {
+              timedOut = true
+              requestStop()
+            }
             return
           }
           if (idleTimeoutMs > 0 && now - lastOutputAt >= idleTimeoutMs) {
-            idleTimedOut = true
-            killTree(child)
+            if (!idleTimedOut) {
+              idleTimedOut = true
+              requestStop()
+            }
           }
         }, 500)
       : null
 
     function onAbort() {
+      if (aborted) return
       aborted = true
-      killTree(child)
+      requestStop()
     }
 
     if (options.signal) {

package/lib/runtime-events.mjs

@@ -0,0 +1,31 @@
+import { randomUUID } from "node:crypto"
+import { appendFile, readFile } from "node:fs/promises"
+
+export async function appendRuntimeEvent(file, type, data = {}) {
+  const event = {
+    schemaVersion: 1,
+    id: randomUUID(),
+    type: String(type || "unknown"),
+    at: new Date().toISOString(),
+    ...data,
+  }
+  await appendFile(file, JSON.stringify(event) + "\n", "utf8")
+  return event
+}
+
+export async function readRuntimeEvents(file, options = {}) {
+  const requested = Number(options.limit)
+  const limit = Number.isFinite(requested) && requested > 0
+    ? Math.max(1, Math.min(Math.trunc(requested), 5000))
+    : 200
+  const raw = await readFile(file, "utf8").catch((error) => {
+    if (error?.code === "ENOENT") return ""
+    throw error
+  })
+  const lines = raw.split(/\r?\n/).filter(Boolean)
+  const events = []
+  for (const line of lines.slice(-limit)) {
+    try { events.push(JSON.parse(line)) } catch {}
+  }
+  return events
+}

package/lib/semantic-index.mjs

@@ -0,0 +1,318 @@
+import { existsSync } from "node:fs"
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises"
+import path from "node:path"
+
+const SCHEMA_VERSION = 1
+const CACHE_DIR = ".ues-cache"
+const CACHE_FILE = "semantic-index-v1.json"
+const SOURCE_EXTENSIONS = new Set([
+  ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx", ".py", ".java", ".kt", ".kts",
+  ".cs", ".go", ".rs", ".rb", ".php", ".vue", ".svelte", ".dart", ".swift", ".sql",
+])
+const SKIP_DIRS = new Set([
+  ".git", "node_modules", ".next", "dist", "build", "coverage", ".venv", "venv",
+  "Pods", "DerivedData", ".gradle", ".idea", ".cache", ".turbo", "target", "bin", "obj",
+  ".ues-work", ".ues-learning", ".ues-dashboard", ".ues-sandboxes", ".ues-cache", ".ues-traces",
+])
+const STOP_IDENTIFIERS = new Set([
+  "const","let","var","function","class","interface","type","export","import","from","return",
+  "async","await","if","else","for","while","switch","case","break","continue","true","false",
+  "null","undefined","this","new","public","private","protected","static","final","void","string",
+  "number","boolean","object","def","self","None","True","False","pass","with","yield","lambda",
+  "package","using","namespace","struct","enum","trait","impl","func","map","range","select",
+])
+
+function rel(root, file) {
+  return path.relative(root, file).replaceAll("\\", "/")
+}
+
+function safeFull(root, relative) {
+  const base = path.resolve(root)
+  const full = path.resolve(base, relative)
+  if (full !== base && !full.startsWith(base + path.sep)) return null
+  return full
+}
+
+async function atomicJson(file, value) {
+  await mkdir(path.dirname(file), { recursive: true })
+  const temp = file + "." + process.pid + "." + Date.now() + ".tmp"
+  await writeFile(temp, JSON.stringify(value) + "\n", "utf8")
+  try {
+    await rename(temp, file)
+  } catch (error) {
+    await rm(temp, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
+async function walk(root, options = {}) {
+  const maxFiles = Math.max(100, Number(options.maxFiles || 6000))
+  const maxDepth = Math.max(2, Number(options.maxDepth || 14))
+  const files = []
+  async function visit(dir, depth) {
+    if (depth > maxDepth || files.length >= maxFiles) return
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => [])
+    entries.sort((a, b) => a.name.localeCompare(b.name))
+    for (const entry of entries) {
+      if (files.length >= maxFiles) break
+      if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) await visit(full, depth + 1)
+      else if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) files.push(full)
+    }
+  }
+  await visit(root, 0)
+  return { files, truncated: files.length >= maxFiles }
+}
+
+function symbolPatterns(ext) {
+  const common = [
+    { kind: "function", re: /(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/ },
+    { kind: "class", re: /(?:export\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/ },
+    { kind: "interface", re: /(?:export\s+)?interface\s+([A-Za-z_$][\w$]*)/ },
+    { kind: "type", re: /(?:export\s+)?type\s+([A-Za-z_$][\w$]*)\s*=/ },
+    { kind: "binding", re: /(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)/ },
+  ]
+  if ([".js",".mjs",".cjs",".jsx",".ts",".tsx",".vue",".svelte"].includes(ext)) return common
+  if (ext === ".py") return [
+    { kind: "function", re: /^\s*(?:async\s+)?def\s+([A-Za-z_][\w]*)\s*\(/ },
+    { kind: "class", re: /^\s*class\s+([A-Za-z_][\w]*)/ },
+  ]
+  if ([".java",".kt",".kts",".cs"].includes(ext)) return [
+    { kind: "type", re: /\b(?:class|interface|record|enum|object)\s+([A-Za-z_$][\w$]*)/ },
+    { kind: "function", re: /\b(?:public|private|protected|internal|static|final|virtual|override|async|synchronized|abstract|sealed|partial|readonly|suspend|open|inline|\s)+[\w<>,?\[\].:]+\s+([A-Za-z_$][\w$]*)\s*\(/ },
+  ]
+  if (ext === ".go") return [
+    { kind: "function", re: /^\s*func\s+(?:\([^)]*\)\s*)?([A-Za-z_][\w]*)\s*\(/ },
+    { kind: "type", re: /^\s*type\s+([A-Za-z_][\w]*)\s+/ },
+  ]
+  if (ext === ".rs") return [
+    { kind: "function", re: /^\s*(?:pub\s+)?(?:async\s+)?fn\s+([A-Za-z_][\w]*)/ },
+    { kind: "type", re: /^\s*(?:pub\s+)?(?:struct|enum|trait|type)\s+([A-Za-z_][\w]*)/ },
+  ]
+  if (ext === ".dart") return [
+    { kind: "class", re: /^\s*(?:abstract\s+)?class\s+([A-Za-z_][\w]*)/ },
+    { kind: "function", re: /^\s*(?:[\w<>,?\[\]]+\s+)+([A-Za-z_][\w]*)\s*\(/ },
+  ]
+  if (ext === ".swift") return [
+    { kind: "type", re: /^\s*(?:public\s+|internal\s+|private\s+)?(?:class|struct|enum|protocol)\s+([A-Za-z_][\w]*)/ },
+    { kind: "function", re: /^\s*(?:public\s+|internal\s+|private\s+)?func\s+([A-Za-z_][\w]*)/ },
+  ]
+  if (ext === ".sql") return [
+    { kind: "table", re: /^\s*create\s+(?:or\s+replace\s+)?table\s+(?:if\s+not\s+exists\s+)?["`\[]?([A-Za-z_][\w$.-]*)/i },
+    { kind: "view", re: /^\s*create\s+(?:or\s+replace\s+)?view\s+["`\[]?([A-Za-z_][\w$.-]*)/i },
+    { kind: "function", re: /^\s*create\s+(?:or\s+replace\s+)?(?:function|procedure)\s+["`\[]?([A-Za-z_][\w$.-]*)/i },
+  ]
+  return common
+}
+
+function parseSource(source, ext) {
+  const lines = String(source || "").split(/\r?\n/)
+  const symbols = []
+  const patterns = symbolPatterns(ext)
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]
+    for (const pattern of patterns) {
+      const match = line.match(pattern.re)
+      if (match?.[1]) {
+        symbols.push({
+          name: match[1],
+          kind: pattern.kind,
+          line: index + 1,
+          preview: line.trim().slice(0, 240),
+        })
+        break
+      }
+    }
+  }
+
+  const counts = new Map()
+  for (const match of String(source || "").matchAll(/\b[A-Za-z_$][A-Za-z0-9_$]{2,}\b/g)) {
+    const value = match[0]
+    if (STOP_IDENTIFIERS.has(value)) continue
+    counts.set(value, (counts.get(value) || 0) + 1)
+  }
+  const identifiers = Object.fromEntries(
+    [...counts.entries()]
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      .slice(0, 320),
+  )
+  return { symbols: symbols.slice(0, 400), identifiers }
+}
+
+function cachePath(root) {
+  return path.join(root, CACHE_DIR, CACHE_FILE)
+}
+
+async function readCache(root) {
+  try {
+    const parsed = JSON.parse(await readFile(cachePath(root), "utf8"))
+    if (parsed?.schemaVersion !== SCHEMA_VERSION || typeof parsed.files !== "object") return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+export async function buildSemanticIndex(root = process.cwd(), options = {}) {
+  const started = Date.now()
+  root = path.resolve(root)
+  const previous = options.rebuild ? null : await readCache(root)
+  const discovered = await walk(root, options)
+  const nextFiles = {}
+  let reused = 0
+  let reparsed = 0
+  let skippedLarge = 0
+  const maxFileBytes = Math.max(64 * 1024, Number(options.maxFileBytes || 1024 * 1024))
+
+  for (const full of discovered.files) {
+    const info = await stat(full).catch(() => null)
+    if (!info?.isFile()) continue
+    const relative = rel(root, full)
+    const signature = info.size + ":" + Math.trunc(info.mtimeMs)
+    const old = previous?.files?.[relative]
+    if (old?.signature === signature) {
+      nextFiles[relative] = old
+      reused += 1
+      continue
+    }
+    if (info.size > maxFileBytes) {
+      nextFiles[relative] = { signature, bytes: info.size, skipped: "too-large", symbols: [], identifiers: {} }
+      skippedLarge += 1
+      continue
+    }
+    const source = await readFile(full, "utf8").catch(() => "")
+    const parsed = source ? parseSource(source, path.extname(relative).toLowerCase()) : { symbols: [], identifiers: {} }
+    nextFiles[relative] = {
+      signature,
+      bytes: info.size,
+      symbols: parsed.symbols,
+      identifiers: parsed.identifiers,
+    }
+    reparsed += 1
+  }
+
+  const removed = previous
+    ? Object.keys(previous.files || {}).filter((file) => !Object.hasOwn(nextFiles, file)).length
+    : 0
+  const index = {
+    schemaVersion: SCHEMA_VERSION,
+    kind: "ues-semantic-index",
+    root,
+    generatedAt: new Date().toISOString(),
+    truncated: discovered.truncated,
+    files: nextFiles,
+  }
+  const changed = !previous || reparsed > 0 || removed > 0 || skippedLarge > 0
+  if (changed || options.rebuild) await atomicJson(cachePath(root), index)
+
+  return {
+    index,
+    stats: {
+      files: Object.keys(nextFiles).length,
+      reused,
+      reparsed,
+      removed,
+      skippedLarge,
+      truncated: discovered.truncated,
+      cacheFile: rel(root, cachePath(root)),
+      durationMs: Date.now() - started,
+    },
+  }
+}
+
+function queryTerms(query) {
+  return [...new Set(
+    String(query || "")
+      .split(/[^\p{L}\p{N}_$.-]+/u)
+      .map((item) => item.trim())
+      .filter((item) => item.length >= 2),
+  )].slice(0, 16)
+}
+
+export async function querySemanticIndex(root, query, options = {}) {
+  const terms = queryTerms(query)
+  if (!terms.length) return { query: String(query || ""), terms: [], results: [], stats: null }
+  const built = await buildSemanticIndex(root, options)
+  const lowerTerms = terms.map((term) => term.toLowerCase())
+  const results = []
+
+  for (const [file, entry] of Object.entries(built.index.files)) {
+    let score = 0
+    const reasons = []
+    const definitions = []
+    const lowerPath = file.toLowerCase()
+    for (let i = 0; i < terms.length; i += 1) {
+      const term = terms[i]
+      const lower = lowerTerms[i]
+      if (lowerPath.includes(lower)) {
+        score += 4
+        reasons.push("path:" + term)
+      }
+      for (const symbol of entry.symbols || []) {
+        const name = String(symbol.name || "")
+        const symbolLower = name.toLowerCase()
+        if (symbolLower === lower) {
+          score += 24
+          definitions.push(symbol)
+          reasons.push("definition:" + name)
+        } else if (symbolLower.startsWith(lower) || symbolLower.includes(lower)) {
+          score += 10
+          definitions.push(symbol)
+          reasons.push("symbol:" + name)
+        }
+      }
+      const identifiers = entry.identifiers || {}
+      const direct = Number(identifiers[term] || 0)
+      let folded = direct
+      if (!direct) {
+        for (const [identifier, count] of Object.entries(identifiers)) {
+          if (identifier.toLowerCase() === lower) {
+            folded = Number(count || 0)
+            break
+          }
+        }
+      }
+      if (folded > 0) {
+        score += Math.min(12, 2 + Math.log2(folded + 1) * 2)
+        reasons.push("reference:" + term + "x" + folded)
+      }
+    }
+    if (score <= 0) continue
+    results.push({
+      path: file,
+      score: Number(score.toFixed(3)),
+      definitions: definitions
+        .filter((item, index, list) => list.findIndex((other) => other.name === item.name && other.line === item.line) === index)
+        .slice(0, 12),
+      reasons: [...new Set(reasons)].slice(0, 12),
+    })
+  }
+
+  results.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+  return {
+    schemaVersion: 1,
+    kind: "ues-semantic-query",
+    query: String(query || ""),
+    terms,
+    evidenceLevel: "syntax-aware-lexical",
+    results: results.slice(0, Math.max(1, Math.min(Number(options.limit || 20), 100))),
+    stats: built.stats,
+  }
+}
+
+export async function semanticIndexStatus(root = process.cwd()) {
+  root = path.resolve(root)
+  const file = cachePath(root)
+  const exists = existsSync(file)
+  if (!exists) return { exists: false, cacheFile: rel(root, file) }
+  const cached = await readCache(root)
+  return {
+    exists: Boolean(cached),
+    cacheFile: rel(root, file),
+    schemaVersion: cached?.schemaVersion || null,
+    generatedAt: cached?.generatedAt || null,
+    files: cached ? Object.keys(cached.files || {}).length : 0,
+    truncated: Boolean(cached?.truncated),
+  }
+}