opencode-agent-skill 13.0.0-beta.2 → 14.4.0

package/lib/capability-fabric.mjs

@@ -0,0 +1,359 @@
+import { existsSync } from "node:fs"
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises"
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+
+const HEALTH_WEIGHT = { healthy: 40, degraded: 15, unknown: 0, unavailable: -1000 }
+const COST_PENALTY = { low: 0, medium: 5, high: 12 }
+const LATENCY_PENALTY = { fast: 0, medium: 3, slow: 8 }
+const OBSERVATION_FILE = "CAPABILITY-OBSERVATIONS.json"
+
+function observationPath(root) {
+  return path.join(path.resolve(root), ".ues-learning", OBSERVATION_FILE)
+}
+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, null, 2) + "\n", "utf8")
+  try { await rename(temp, file) } catch (error) { await rm(temp, { force: true }).catch(() => {}); throw error }
+}
+export async function readCapabilityObservations(root = process.cwd()) {
+  try {
+    const parsed = JSON.parse(await readFile(observationPath(root), "utf8"))
+    return { schemaVersion: 1, updatedAt: parsed.updatedAt || null, capabilities: parsed.capabilities && typeof parsed.capabilities === "object" ? parsed.capabilities : {} }
+  } catch { return { schemaVersion: 1, updatedAt: null, capabilities: {} } }
+}
+export async function recordCapabilityObservation(root, capability, providerId, input = {}) {
+  if (!capability || !providerId) throw new Error("capability observation requires capability and provider id")
+  const state = await readCapabilityObservations(root)
+  const previous = state.capabilities?.[capability]?.[providerId] || {}
+  const success = input.success === true, failure = input.success === false
+  const samples = Number(previous.samples || 0) + (success || failure ? 1 : 0)
+  const successes = Number(previous.successes || 0) + (success ? 1 : 0)
+  const failures = Number(previous.failures || 0) + (failure ? 1 : 0)
+  const latencyMs = Number.isFinite(Number(input.latencyMs)) ? Math.max(0, Number(input.latencyMs)) : null
+  const previousLatencySamples = Number(previous.latencySamples || 0)
+  const latencySamples = previousLatencySamples + (latencyMs == null ? 0 : 1)
+  const avgLatencyMs = latencyMs == null ? (previous.avgLatencyMs ?? null) : ((Number(previous.avgLatencyMs || 0) * previousLatencySamples) + latencyMs) / Math.max(1, latencySamples)
+  const next = {
+    samples, successes, failures,
+    successRate: samples ? successes / samples : 0,
+    failureRate: samples ? failures / samples : 0,
+    latencySamples, avgLatencyMs: avgLatencyMs == null ? null : Number(avgLatencyMs.toFixed(2)),
+    lastLatencyMs: latencyMs, lastObservedAt: new Date().toISOString(),
+    lastError: input.error ? String(input.error).slice(0, 500) : null,
+  }
+  const capabilities = { ...state.capabilities, [capability]: { ...(state.capabilities?.[capability] || {}), [providerId]: next } }
+  await atomicJson(observationPath(root), { schemaVersion: 1, updatedAt: next.lastObservedAt, capabilities })
+  return next
+}
+
+function clamp(value, min = 0, max = 1, fallback = 0) {
+  const number = Number(value)
+  return Number.isFinite(number) ? Math.max(min, Math.min(max, number)) : fallback
+}
+
+const COMMAND_PROBE_TTL_MS = 60_000
+const commandProbeCache = new Map()
+
+function commandExists(command) {
+  if (!command) return false
+  const now = Date.now()
+  const cached = commandProbeCache.get(command)
+  if (cached && now - cached.checkedAt < COMMAND_PROBE_TTL_MS) return cached.available
+  const finder = process.platform === "win32" ? "where" : "which"
+  const result = spawnSync(finder, [command], { stdio: "ignore", windowsHide: true })
+  const available = result.status === 0
+  commandProbeCache.set(command, { available, checkedAt: now })
+  return available
+}
+
+async function packageDeclared(root, name) {
+  try {
+    const pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"))
+    return Boolean(
+      pkg.dependencies?.[name] ||
+      pkg.devDependencies?.[name] ||
+      pkg.optionalDependencies?.[name] ||
+      pkg.peerDependencies?.[name],
+    )
+  } catch {
+    return false
+  }
+}
+
+function normalizeProvider(provider = {}, index = 0) {
+  return {
+    id: String(provider.id || `provider-${index + 1}`),
+    kind: provider.kind || "builtin",
+    capability: provider.capability || null,
+    priority: Number.isFinite(Number(provider.priority)) ? Number(provider.priority) : 50,
+    quality: clamp(provider.quality, 0, 1, 0.5),
+    costClass: ["low", "medium", "high"].includes(provider.costClass) ? provider.costClass : "medium",
+    latencyClass: ["fast", "medium", "slow"].includes(provider.latencyClass) ? provider.latencyClass : "medium",
+    command: provider.command || null,
+    path: provider.path || null,
+    package: provider.package || null,
+    metadata: provider.metadata || {},
+  }
+}
+
+export function defaultCapabilityRegistry(root = process.cwd()) {
+  return {
+    schemaVersion: 1,
+    root: path.resolve(root),
+    capabilities: {
+      "code.search": [
+        { id: "ues-semantic-index", kind: "builtin", priority: 100, quality: 0.9, costClass: "low", latencyClass: "fast" },
+      ],
+      "code.edit.anchored": [
+        { id: "ues-hashline", kind: "builtin", priority: 120, quality: 0.98, costClass: "low", latencyClass: "fast", metadata: { failClosed: true, staleAnchorReject: true } },
+      ],
+      "code.structure": [
+        { id: "ast-grep", kind: "command", command: "ast-grep", priority: 120, quality: 0.96, costClass: "low", latencyClass: "fast" },
+        { id: "sg", kind: "command", command: "sg", priority: 115, quality: 0.96, costClass: "low", latencyClass: "fast" },
+        { id: "ues-semantic-index", kind: "builtin", priority: 80, quality: 0.8, costClass: "low", latencyClass: "fast" },
+      ],
+      "code.diagnostics": [
+        { id: "typescript-language-server", kind: "command", command: "typescript-language-server", priority: 110, quality: 0.95, costClass: "low", latencyClass: "medium" },
+        { id: "pyright-langserver", kind: "command", command: "pyright-langserver", priority: 105, quality: 0.95, costClass: "low", latencyClass: "medium" },
+        { id: "pylsp", kind: "command", command: "pylsp", priority: 95, quality: 0.85, costClass: "low", latencyClass: "medium" },
+        { id: "gopls", kind: "command", command: "gopls", priority: 105, quality: 0.95, costClass: "low", latencyClass: "medium" },
+        { id: "rust-analyzer", kind: "command", command: "rust-analyzer", priority: 105, quality: 0.95, costClass: "low", latencyClass: "medium" },
+        { id: "clangd", kind: "command", command: "clangd", priority: 100, quality: 0.9, costClass: "low", latencyClass: "medium" },
+      ],
+      "document.ingestion": [
+        { id: "ues-builtin-text", kind: "builtin", priority: 100, quality: 0.95, costClass: "low", latencyClass: "fast", metadata: { formats: ["text", "markdown", "json", "csv", "html", "xml"] } },
+        { id: "markitdown-cli", kind: "command", command: "markitdown", priority: 95, quality: 0.95, costClass: "low", latencyClass: "medium", metadata: { optional: true, formats: ["pdf", "docx", "pptx", "xlsx", "epub", "zip"] } },
+      ],
+      "context.reversible": [
+        { id: "ues-evidence-context", kind: "builtin", priority: 120, quality: 0.98, costClass: "low", latencyClass: "fast", metadata: { reversible: true, searchable: true, levels: ["T1", "T2", "T3", "raw"] } },
+      ],
+      memory: [
+        { id: "ues-memory", kind: "builtin", priority: 100, quality: 0.9, costClass: "low", latencyClass: "fast" },
+      ],
+      evidence: [
+        { id: "ues-evidence-store", kind: "builtin", priority: 100, quality: 0.95, costClass: "low", latencyClass: "fast" },
+      ],
+      "output.compaction": [
+        {
+          id: "ues-reversible-compactor",
+          kind: "builtin",
+          priority: 100,
+          quality: 0.98,
+          costClass: "low",
+          latencyClass: "fast",
+          metadata: { default: true, reversible: true, lossy: false, scope: "model-visible UES output" },
+        },
+        {
+          id: "rtk-cli",
+          kind: "command",
+          command: "rtk",
+          priority: 82,
+          quality: 0.9,
+          costClass: "low",
+          latencyClass: "fast",
+          metadata: { default: false, external: true, experimental: false, scope: "shell-output", upstream: "rtk-ai/rtk" },
+        },
+        {
+          id: "caveman-cli",
+          kind: "command",
+          command: "caveman",
+          priority: 55,
+          quality: 0.82,
+          costClass: "medium",
+          latencyClass: "medium",
+          metadata: {
+            default: false,
+            external: true,
+            experimental: true,
+            reversible: true,
+            upstream: "JuliusBrussee/caveman",
+            licenseNote: "External runtime includes BSL-1.1 engine components; do not vendor them into the MIT core.",
+          },
+        },
+        {
+          id: "headroom-cli",
+          kind: "command",
+          command: "headroom",
+          priority: 50,
+          quality: 0.82,
+          costClass: "medium",
+          latencyClass: "medium",
+          metadata: {
+            default: false,
+            external: true,
+            experimental: true,
+            reversible: true,
+            outputShaper: false,
+            upstream: "headroomlabs-ai/headroom",
+          },
+        },
+      ],
+      filesystem: [
+        { id: "node-fs", kind: "builtin", priority: 100, quality: 0.95, costClass: "low", latencyClass: "fast" },
+      ],
+      git: [
+        { id: "git-cli", kind: "command", command: "git", priority: 100, quality: 0.95, costClass: "low", latencyClass: "fast" },
+      ],
+      "agent.host": [
+        { id: "pi-cli", kind: "command", command: "pi", priority: 100, quality: 0.95, costClass: "low", latencyClass: "fast" },
+      ],
+      github: [
+        { id: "gh-cli", kind: "command", command: "gh", priority: 80, quality: 0.85, costClass: "low", latencyClass: "fast" },
+      ],
+      browser: [
+        { id: "project-playwright", kind: "package", package: "playwright", priority: 90, quality: 0.9, costClass: "medium", latencyClass: "medium" },
+        { id: "project-playwright-core", kind: "package", package: "playwright-core", priority: 70, quality: 0.75, costClass: "medium", latencyClass: "medium" },
+      ],
+    },
+  }
+}
+
+async function readCapabilityConfig(root, file) {
+  const target = file
+    ? path.resolve(file)
+    : process.env.UES_CAPABILITY_CONFIG
+      ? path.resolve(process.env.UES_CAPABILITY_CONFIG)
+      : path.join(path.resolve(root), ".ues-capabilities.json")
+  if (!existsSync(target)) return null
+  try {
+    const parsed = JSON.parse(await readFile(target, "utf8"))
+    return parsed && typeof parsed === "object" ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+function mergeRegistry(base, extra) {
+  if (!extra?.capabilities || typeof extra.capabilities !== "object") return base
+  const capabilities = { ...base.capabilities }
+  for (const [name, values] of Object.entries(extra.capabilities)) {
+    const custom = Array.isArray(values) ? values : []
+    const seen = new Set(custom.map((item) => item?.id).filter(Boolean))
+    const inherited = (capabilities[name] || []).filter((item) => !seen.has(item.id))
+    capabilities[name] = [...custom, ...inherited]
+  }
+  return { ...base, capabilities }
+}
+
+export async function loadCapabilityRegistry(root = process.cwd(), options = {}) {
+  root = path.resolve(root)
+  const base = options.registry || defaultCapabilityRegistry(root)
+  if (options.registry) return base
+  return mergeRegistry(base, await readCapabilityConfig(root, options.configFile))
+}
+
+export async function probeCapabilityProvider(provider, root = process.cwd()) {
+  const normalized = normalizeProvider(provider)
+  const checkedAt = new Date().toISOString()
+  if (normalized.kind === "builtin") {
+    return { ...normalized, status: "healthy", reason: "built-in", checkedAt }
+  }
+  if (normalized.kind === "command") {
+    const available = commandExists(normalized.command)
+    return {
+      ...normalized,
+      status: available ? "healthy" : "unavailable",
+      reason: available ? `command:${normalized.command}` : `missing-command:${normalized.command}`,
+      checkedAt,
+    }
+  }
+  if (normalized.kind === "path") {
+    const target = normalized.path ? path.resolve(root, normalized.path) : null
+    const available = Boolean(target && existsSync(target))
+    return {
+      ...normalized,
+      status: available ? "healthy" : "unavailable",
+      reason: available ? `path:${normalized.path}` : `missing-path:${normalized.path || ""}`,
+      checkedAt,
+    }
+  }
+  if (normalized.kind === "package") {
+    const declared = normalized.package ? await packageDeclared(root, normalized.package) : false
+    const installed = normalized.package
+      ? existsSync(path.join(root, "node_modules", normalized.package))
+      : false
+    const available = installed || declared
+    return {
+      ...normalized,
+      status: installed ? "healthy" : declared ? "degraded" : "unavailable",
+      reason: installed
+        ? `installed-package:${normalized.package}`
+        : declared
+          ? `declared-package:${normalized.package}`
+          : `missing-package:${normalized.package || ""}`,
+      checkedAt,
+    }
+  }
+  return { ...normalized, status: "unknown", reason: `unknown-kind:${normalized.kind}`, checkedAt }
+}
+
+export function selectCapabilityProvider(capability, providers = [], options = {}) {
+  const observations = options.observations || {}
+  const allowUnknown = options.allowUnknown === true
+  const rows = providers.map((provider, index) => {
+    const normalized = normalizeProvider(provider, index)
+    const status = provider.status || "unknown"
+    const observation = observations[normalized.id] || {}
+    const failureRate = clamp(observation.failureRate, 0, 1, 0)
+    const successRate = clamp(observation.successRate, 0, 1, 0)
+    const samples = Math.max(0, Number(observation.samples || 0))
+    const observationConfidence = samples > 0 ? Math.min(1, samples / 5) : 0
+    const successBoost = successRate * 12 * observationConfidence
+    const failurePenalty = failureRate * 35 * observationConfidence
+    const healthWeight = HEALTH_WEIGHT[status] ?? HEALTH_WEIGHT.unknown
+    const eligible = status === "healthy" || status === "degraded" || (allowUnknown && status === "unknown")
+    const score =
+      normalized.priority +
+      normalized.quality * 20 +
+      successBoost +
+      healthWeight -
+      (COST_PENALTY[normalized.costClass] ?? 5) -
+      (LATENCY_PENALTY[normalized.latencyClass] ?? 3) -
+      failurePenalty
+    return { ...normalized, status, eligible, samples, successRate, failureRate, observationConfidence: Number(observationConfidence.toFixed(3)), score: Number(score.toFixed(3)), reason: provider.reason || null }
+  })
+  const eligible = rows.filter((item) => item.eligible).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+  return {
+    schemaVersion: 1,
+    capability,
+    selected: eligible[0] || null,
+    fallbacks: eligible.slice(1),
+    candidates: rows.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)),
+    fallbackNeeded: eligible.length === 0,
+  }
+}
+
+export async function capabilityFabricStatus(root = process.cwd(), options = {}) {
+  root = path.resolve(root)
+  const registry = await loadCapabilityRegistry(root, options)
+  const persistedObservations = options.observations ? null : await readCapabilityObservations(root)
+  const capabilities = {}
+  const rows = []
+  for (const [name, providers] of Object.entries(registry.capabilities || {})) {
+    const probed = []
+    for (const provider of providers || []) probed.push(await probeCapabilityProvider(provider, root))
+    const selected = selectCapabilityProvider(name, probed, {
+      observations: options.observations?.[name] || persistedObservations?.capabilities?.[name] || {},
+      allowUnknown: options.allowUnknown,
+    })
+    capabilities[name] = selected
+    rows.push({
+      capability: name,
+      selected: selected.selected?.id || null,
+      status: selected.selected?.status || "unavailable",
+      fallbacks: selected.fallbacks.map((item) => item.id),
+    })
+  }
+  return {
+    schemaVersion: 1,
+    root,
+    generatedAt: new Date().toISOString(),
+    rows,
+    capabilities,
+    healthyCapabilities: rows.filter((item) => item.selected).length,
+    totalCapabilities: rows.length,
+    observationState: persistedObservations ? { updatedAt: persistedObservations.updatedAt, capabilities: Object.keys(persistedObservations.capabilities || {}).length } : null,
+  }
+}

package/lib/capability-registry.mjs

@@ -107,3 +107,12 @@ export function modelCandidatesFromPolicy(policy = {}) {
 export function roleCapabilityRequirements(role) {
   return { ...(ROLE_REQUIREMENTS[role] || {}) }
 }
+
+
+export {
+  capabilityFabricStatus,
+  defaultCapabilityRegistry,
+  loadCapabilityRegistry,
+  probeCapabilityProvider,
+  selectCapabilityProvider,
+} from "./capability-fabric.mjs"

package/lib/code-intelligence/edit-anchor.mjs

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto"
+
+const DEFAULT_HASH_CHARS = 8
+
+function normalizeNewlines(value) {
+  return String(value ?? "").replace(/\r\n/g, "\n").replace(/\r/g, "\n")
+}
+
+function hashText(value, chars = DEFAULT_HASH_CHARS) {
+  return createHash("sha256").update(String(value ?? "")).digest("hex").slice(0, Math.max(6, Math.min(16, Number(chars || DEFAULT_HASH_CHARS))))
+}
+
+export function lineAnchor(lineNumber, lineText, options = {}) {
+  const line = Math.max(1, Math.trunc(Number(lineNumber || 1)))
+  return `L${line}:${hashText(lineText, options.hashChars)}`
+}
+
+export function parseLineAnchor(anchor) {
+  const match = String(anchor || "").trim().match(/^L([1-9]\d*):([a-f0-9]{6,16})$/i)
+  if (!match) return null
+  return { line: Number(match[1]), hash: match[2].toLowerCase() }
+}
+
+export function anchoredLines(source, options = {}) {
+  const text = normalizeNewlines(source)
+  const lines = text.split("\n")
+  const startLine = Math.max(1, Math.trunc(Number(options.startLine || 1)))
+  const requestedEnd = options.endLine == null ? lines.length : Math.trunc(Number(options.endLine))
+  const endLine = Math.max(startLine, Math.min(lines.length, requestedEnd || lines.length))
+  const rows = []
+  for (let line = startLine; line <= endLine; line += 1) {
+    const value = lines[line - 1] ?? ""
+    rows.push({ line, anchor: lineAnchor(line, value, options), text: value })
+  }
+  return {
+    schemaVersion: 1,
+    startLine,
+    endLine,
+    lineCount: lines.length,
+    sourceHash: hashText(text, 16),
+    rows,
+    text: rows.map((row) => `${row.anchor}|${row.text}`).join("\n"),
+  }
+}
+
+function validateAnchor(lines, rawAnchor, label, options = {}) {
+  const parsed = parseLineAnchor(rawAnchor)
+  if (!parsed) throw new Error(`${label} must use L<line>:<hash> format`)
+  if (parsed.line > lines.length) throw new Error(`${label} points beyond end of file`)
+  const actual = lineAnchor(parsed.line, lines[parsed.line - 1] ?? "", options)
+  if (actual.toLowerCase() !== String(rawAnchor).toLowerCase()) {
+    const error = new Error(`${label} is stale or ambiguous; re-read anchored source before editing`)
+    error.code = "UES_STALE_ANCHOR"
+    error.expected = actual
+    error.received = String(rawAnchor)
+    throw error
+  }
+  return parsed
+}
+
+export function applyAnchoredEdits(source, edits = [], options = {}) {
+  const text = normalizeNewlines(source)
+  const lines = text.split("\n")
+  if (!Array.isArray(edits) || edits.length === 0) throw new Error("at least one anchored edit is required")
+  const maxEdits = Math.max(1, Math.min(200, Number(options.maxEdits || 50)))
+  if (edits.length > maxEdits) throw new Error(`too many anchored edits; maximum is ${maxEdits}`)
+
+  const prepared = edits.map((edit, index) => {
+    const start = validateAnchor(lines, edit?.anchor || edit?.startAnchor, `edit[${index}].anchor`, options)
+    const end = edit?.endAnchor
+      ? validateAnchor(lines, edit.endAnchor, `edit[${index}].endAnchor`, options)
+      : start
+    if (end.line < start.line) throw new Error(`edit[${index}] endAnchor precedes anchor`)
+    return {
+      index,
+      startLine: start.line,
+      endLine: end.line,
+      replacement: normalizeNewlines(edit?.replacement ?? ""),
+    }
+  })
+
+  prepared.sort((a, b) => a.startLine - b.startLine || a.endLine - b.endLine)
+  for (let index = 1; index < prepared.length; index += 1) {
+    if (prepared[index].startLine <= prepared[index - 1].endLine) {
+      throw new Error(`anchored edits overlap at edit[${prepared[index].index}]`)
+    }
+  }
+
+  const next = [...lines]
+  for (const edit of [...prepared].sort((a, b) => b.startLine - a.startLine)) {
+    const replacementLines = edit.replacement.split("\n")
+    next.splice(edit.startLine - 1, edit.endLine - edit.startLine + 1, ...replacementLines)
+  }
+  const output = next.join("\n")
+  return {
+    schemaVersion: 1,
+    sourceHash: hashText(text, 16),
+    outputHash: hashText(output, 16),
+    applied: prepared.length,
+    text: output,
+  }
+}

package/lib/code-intelligence/index.mjs

@@ -0,0 +1,95 @@
+import { lstat, readFile, realpath, rename, rm, writeFile } from "node:fs/promises"
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+import { querySemanticIndex } from "../semantic-index.mjs"
+import { anchoredLines, applyAnchoredEdits } from "./edit-anchor.mjs"
+import { diagnoseCode, lspProviderStatus } from "./lsp-provider.mjs"
+
+const AST_COMMANDS = ["ast-grep", "sg"]
+const commandCache = new Map()
+const COMMAND_TTL_MS = 60_000
+
+function commandExists(command) {
+  const now = Date.now()
+  const cached = commandCache.get(command)
+  if (cached && now - cached.at < COMMAND_TTL_MS) return cached.available
+  const finder = process.platform === "win32" ? "where" : "which"
+  const available = spawnSync(finder, [command], { stdio: "ignore", windowsHide: true }).status === 0
+  commandCache.set(command, { available, at: now })
+  return available
+}
+
+function inside(root, target) { return target === root || target.startsWith(root + path.sep) }
+
+async function safeFile(root, relative) {
+  const base = await realpath(path.resolve(root)).catch(() => path.resolve(root))
+  const requested = path.resolve(base, String(relative || ""))
+  if (!inside(base, requested)) throw new Error("code path escapes workspace root")
+  const info = await lstat(requested)
+  if (!info.isFile()) throw new Error("code path is not a file")
+  const actual = await realpath(requested)
+  if (!inside(base, actual)) throw new Error("code symlink escapes workspace root")
+  return { base, file: actual, info }
+}
+
+export function probeCodeIntelligence(file = "") {
+  const astProvider = AST_COMMANDS.find(commandExists) || null
+  return {
+    schemaVersion: 1,
+    anchoredEditing: true,
+    semanticIndex: true,
+    astProvider,
+    lsp: lspProviderStatus(file),
+  }
+}
+
+export async function readAnchoredCode(root, relative, options = {}) {
+  const target = await safeFile(root, relative)
+  const maxBytes = Math.max(8 * 1024, Math.min(4 * 1024 * 1024, Number(options.maxBytes || 512 * 1024)))
+  if (target.info.size > maxBytes) throw new Error("code file exceeds anchored-read limit (" + target.info.size + " > " + maxBytes + " bytes)")
+  const source = await readFile(target.file, "utf8")
+  return { file: path.relative(target.base, target.file).replaceAll("\\", "/"), ...anchoredLines(source, options) }
+}
+
+export async function applyAnchoredFileEdits(root, relative, edits, options = {}) {
+  const target = await safeFile(root, relative)
+  const maxBytes = Math.max(8 * 1024, Math.min(4 * 1024 * 1024, Number(options.maxBytes || 512 * 1024)))
+  if (target.info.size > maxBytes) throw new Error("code file exceeds anchored-edit limit (" + target.info.size + " > " + maxBytes + " bytes)")
+  const source = await readFile(target.file, "utf8")
+  const result = applyAnchoredEdits(source, edits, options)
+  const relativeFile = path.relative(target.base, target.file).replaceAll("\\", "/")
+  if (options.dryRun === true) return { ...result, file: relativeFile, dryRun: true }
+  const temp = target.file + "." + process.pid + "." + Date.now() + ".ues.tmp"
+  await writeFile(temp, result.text, "utf8")
+  try { await rename(temp, target.file) } catch (error) { await rm(temp, { force: true }).catch(() => {}); throw error }
+  return { ...result, file: relativeFile, dryRun: false }
+}
+
+function runAstGrep(root, pattern, language, limit) {
+  const command = AST_COMMANDS.find(commandExists) || null
+  if (!command || !String(pattern || "").trim()) return { provider: null, results: [], error: null }
+  const args = ["run", "--pattern", String(pattern), "--json=stream"]
+  if (language) args.push("--lang", String(language))
+  args.push(".")
+  const result = spawnSync(command, args, { cwd: path.resolve(root), encoding: "utf8", timeout: 20_000, maxBuffer: 4 * 1024 * 1024, windowsHide: true })
+  if (result.status !== 0) return { provider: command, results: [], error: String(result.stderr || ("ast-grep exit " + result.status)).trim().slice(0, 1000) }
+  const rows = String(result.stdout || "").split(/\r?\n/).filter(Boolean).slice(0, limit).map((line) => {
+    try { return JSON.parse(line) } catch { return { raw: line } }
+  })
+  return { provider: command, results: rows, error: null }
+}
+
+export async function searchCodeIntelligence(root, query, options = {}) {
+  const maxResults = Math.max(1, Math.min(50, Number(options.maxResults || 12)))
+  const semantic = await querySemanticIndex(root, query, { maxFiles: options.maxFiles || 6000, limit: maxResults })
+  const structural = options.structuralPattern ? runAstGrep(root, options.structuralPattern, options.language, maxResults) : { provider: null, results: [], error: null }
+  return {
+    schemaVersion: 1,
+    query: String(query || ""),
+    providers: probeCodeIntelligence(options.file || ""),
+    semantic: { ...semantic, results: (semantic.results || []).slice(0, maxResults) },
+    structural,
+  }
+}
+
+export { diagnoseCode, lspProviderStatus } from "./lsp-provider.mjs"