opencode-agent-skill 15.0.0 → 15.1.0

package/README.md

@@ -4,9 +4,9 @@
 
 **Package:** <code>opencode-agent-skill</code>  
 **Host chính:** Pi Agent  
-**Phiên bản package hiện tại:** <code>15.0.0</code>  
+**Phiên bản package hiện tại:** <code>15.1.0</code>  
 **Nhánh phát triển hiện tại:** V15.19 Finalization Hardening  
-**Stable npm hiện tại:** <code>15.0.0</code>  
+**Stable npm hiện tại:** <code>15.1.0</code>  
 **Runtime:** Node.js 22.19+  
 **License:** MIT
 
@@ -1431,15 +1431,15 @@ npm pack
 Package version hiện tại trên nhánh <code>main</code> là:
 
 ~~~text
-15.0.0-beta.13
+15.1.0
 ~~~
 
-Stable npm public hiện vẫn là <code>14.4.0</code>. V15.3 DEEP Speed giảm exploration trùng lặp ở long-horizon bằng diagnosis deduplication và bounded specialist exploration, nhưng giữ nguyên plan/verifier/integration gates. V15.4 ACP-safe child runtime ngăn UES spawn lại ACP/Zed entrypoint; child specialist luôn được chạy bằng Pi CLI thật. V15.5 Per-Leaf Turbo cho phép leaf task nhỏ trong DEEP plan tự xuống FAST, giữ failure delta task-local, và tái sử dụng context theo root namespace + workspace fingerprint để giảm retry/rebuild latency. V15.6 Fast Planning đặt soft-steer/hard-idle budget riêng cho architect/plan-checker, recovery từ warm context thay vì scan lại, và lease/cleanup sandbox orphan an toàn sau crash/Stop. V15.7 Lightweight Sandbox Cleanup thu hồi worktree theo trace ngay khi /ues-run kết thúc, dọn metadata mồ côi, giảm legacy grace xuống 30 phút và cung cấp /ues-clean để dọn stale artifacts an toàn mà không đụng sandbox đang active. V15.8 Plan Gate Recovery bổ sung soft-steer + bounded recovery cho plan-checker và quét cả detached physical sandbox folders mà Git worktree registry đã quên. V15.9 Runtime Artifact Isolation loại .ues-traces/.ues-cache/.ues-services/.ues-work và runtime state khác khỏi task delta, write-scope conflict và sandbox integration, nhưng vẫn giữ safety gate cho source/config thật như apps/mobile/package.json. V15.10 Adaptive Stability Runtime thay hard-timeout tuyệt đối bằng activity-aware bounded deadlines, giữ absolute cap chống treo, salvage plan JSON đã validate từ partial output, phát graph trước prose, và role-bound context cho read-only planner trong task high-risk mà không giảm evidence budget của executor/verifier. V15.1 bắt đầu bằng deterministic <code>/ues-run</code> admission và Managed Background Services để model yếu không thể bỏ qua controller và không bị treo bởi dev server foreground.
+Stable npm public hiện vẫn là <code>15.1.0</code>. V15.3 DEEP Speed giảm exploration trùng lặp ở long-horizon bằng diagnosis deduplication và bounded specialist exploration, nhưng giữ nguyên plan/verifier/integration gates. V15.4 ACP-safe child runtime ngăn UES spawn lại ACP/Zed entrypoint; child specialist luôn được chạy bằng Pi CLI thật. V15.5 Per-Leaf Turbo cho phép leaf task nhỏ trong DEEP plan tự xuống FAST, giữ failure delta task-local, và tái sử dụng context theo root namespace + workspace fingerprint để giảm retry/rebuild latency. V15.6 Fast Planning đặt soft-steer/hard-idle budget riêng cho architect/plan-checker, recovery từ warm context thay vì scan lại, và lease/cleanup sandbox orphan an toàn sau crash/Stop. V15.7 Lightweight Sandbox Cleanup thu hồi worktree theo trace ngay khi /ues-run kết thúc, dọn metadata mồ côi, giảm legacy grace xuống 30 phút và cung cấp /ues-clean để dọn stale artifacts an toàn mà không đụng sandbox đang active. V15.8 Plan Gate Recovery bổ sung soft-steer + bounded recovery cho plan-checker và quét cả detached physical sandbox folders mà Git worktree registry đã quên. V15.9 Runtime Artifact Isolation loại .ues-traces/.ues-cache/.ues-services/.ues-work và runtime state khác khỏi task delta, write-scope conflict và sandbox integration, nhưng vẫn giữ safety gate cho source/config thật như apps/mobile/package.json. V15.10 Adaptive Stability Runtime thay hard-timeout tuyệt đối bằng activity-aware bounded deadlines, giữ absolute cap chống treo, salvage plan JSON đã validate từ partial output, phát graph trước prose, và role-bound context cho read-only planner trong task high-risk mà không giảm evidence budget của executor/verifier. V15.1 bắt đầu bằng deterministic <code>/ues-run</code> admission và Managed Background Services để model yếu không thể bỏ qua controller và không bị treo bởi dev server foreground.
 
 Test file packed với Pi:
 
 ~~~cmd
-pi install .\opencode-agent-skill-14.4.0.tgz
+pi install .\opencode-agent-skill-15.1.0.tgz
 pi list
 ~~~
 

package/lib/affected-tests.mjs

@@ -9,6 +9,7 @@ const SOURCE_EXT = new Set([".js",".jsx",".mjs",".cjs",".ts",".tsx",".py",".java
 const SKIP = new Set([".git","node_modules",".next","dist","build","coverage",".venv","venv","target","Pods","DerivedData",".gradle",".ues-cache",".ues-work",".ues-sandboxes",".ues-traces",".ues-learning",".ues-dashboard",".ues-memory",".ues-evals",".ues-services"])
 const AFFECTED_TEST_CACHE = new Map()
 const AFFECTED_TEST_INFLIGHT = new Map()
+const TEST_CONTENT_CACHE = new Map()
 
 function git(root, args) {
   return spawnSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: 8 * 1024 * 1024 })
@@ -47,6 +48,37 @@ async function walk(root, options = {}) {
   return rows
 }
 
+async function projectFiles(root, options = {}) {
+  const indexed = git(root, ["ls-files", "-co", "--exclude-standard", "-z"])
+  if (indexed.status === 0) {
+    const files = String(indexed.stdout || "")
+      .split("\0")
+      .map((value) => normalize(value))
+      .filter(Boolean)
+      .filter((relative) => !relative.split("/").some((part) => SKIP.has(part)))
+      .map((relative) => path.resolve(root, relative))
+    return { files: [...new Set(files)], source: "git-index" }
+  }
+  return { files: await walk(root, options), source: "filesystem-walk" }
+}
+
+async function cachedTestContent(file, info) {
+  if (!info?.size || info.size > 512 * 1024) return ""
+  const key = path.resolve(file)
+  const signature = String(info.size) + ":" + String(Math.trunc(Number(info.mtimeMs || 0)))
+  const cached = TEST_CONTENT_CACHE.get(key)
+  if (cached?.signature === signature) return cached.content
+  const content = await readFile(key, "utf8").catch(() => "")
+  TEST_CONTENT_CACHE.delete(key)
+  TEST_CONTENT_CACHE.set(key, { signature, content })
+  while (TEST_CONTENT_CACHE.size > 1200) {
+    const oldest = TEST_CONTENT_CACHE.keys().next().value
+    if (!oldest) break
+    TEST_CONTENT_CACHE.delete(oldest)
+  }
+  return content
+}
+
 export function gitChangedFiles(root = process.cwd()) {
   root = path.resolve(root)
   const inside = git(root, ["rev-parse", "--is-inside-work-tree"])
@@ -190,7 +222,8 @@ export async function resolveAffectedTests(root = process.cwd(), options = {}) {
   }
 
   const compute = async () => {
-    const files = await walk(root, options)
+    const inventory = await projectFiles(root, options)
+    const files = inventory.files
     const tests = files
       .map((file) => normalize(path.relative(root, file)))
       .filter((file) => TEST_RE.test(file))
@@ -198,9 +231,7 @@ export async function resolveAffectedTests(root = process.cwd(), options = {}) {
     const ranked = []
     for (const testFile of tests) {
       const info = await stat(path.join(root, testFile)).catch(() => null)
-      const content = info?.size && info.size <= 512 * 1024
-        ? await readFile(path.join(root, testFile), "utf8").catch(() => "")
-        : ""
+      const content = await cachedTestContent(path.join(root, testFile), info)
       let best = { score: 0, reasons: [], changedFile: null }
       for (const changedFile of changed) {
         const current = scoreTest(testFile, changedFile, content)
@@ -232,6 +263,7 @@ export async function resolveAffectedTests(root = process.cwd(), options = {}) {
       suggestedCommands,
       truncated: ranked.length > selected.length,
       cacheHit: false,
+      inventorySource: inventory.source,
     }
   }
 
@@ -257,4 +289,5 @@ export async function resolveAffectedTests(root = process.cwd(), options = {}) {
 export function clearAffectedTestCache() {
   AFFECTED_TEST_CACHE.clear()
   AFFECTED_TEST_INFLIGHT.clear()
+  TEST_CONTENT_CACHE.clear()
 }

package/lib/code-intelligence/index.mjs

@@ -3,7 +3,7 @@ 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"
+import { diagnoseCode, lspOperation, lspProviderStatus, LSP_OPERATIONS } from "./lsp-provider.mjs"
 
 const AST_COMMANDS = ["ast-grep", "sg"]
 const commandCache = new Map()
@@ -40,6 +40,7 @@ export function probeCodeIntelligence(file = "") {
     semanticIndex: true,
     astProvider,
     lsp: lspProviderStatus(file),
+    lspOperations: [...LSP_OPERATIONS],
   }
 }
 
@@ -92,4 +93,4 @@ export async function searchCodeIntelligence(root, query, options = {}) {
   }
 }
 
-export { diagnoseCode, lspProviderStatus } from "./lsp-provider.mjs"
+export { diagnoseCode, lspOperation, lspProviderStatus, LSP_OPERATIONS } from "./lsp-provider.mjs"

package/lib/code-intelligence/lsp-provider.mjs

@@ -1,7 +1,7 @@
 import { spawn, spawnSync } from "node:child_process"
 import { lstat, readFile, realpath } from "node:fs/promises"
 import path from "node:path"
-import { pathToFileURL } from "node:url"
+import { fileURLToPath, pathToFileURL } from "node:url"
 
 const PROVIDERS = [
   { id: "typescript-language-server", extensions: new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]), commands: [["typescript-language-server", ["--stdio"]]], languageId: (ext) => [".ts", ".tsx"].includes(ext) ? "typescript" : "javascript" },
@@ -11,6 +11,17 @@ const PROVIDERS = [
   { id: "clangd", extensions: new Set([".c", ".cc", ".cpp", ".cxx", ".h", ".hpp"]), commands: [["clangd", []]], languageId: (ext) => [".c", ".h"].includes(ext) ? "c" : "cpp" },
 ]
 
+export const LSP_OPERATIONS = Object.freeze([
+  "diagnostics",
+  "definition",
+  "references",
+  "symbols",
+  "hover",
+  "rename-preview",
+  "incoming-calls",
+  "outgoing-calls",
+])
+
 const commandCache = new Map()
 const COMMAND_TTL_MS = 60_000
 
@@ -31,11 +42,11 @@ function inside(root, target) {
 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("diagnostic path escapes workspace root")
+  if (!inside(base, requested)) throw new Error("LSP path escapes workspace root")
   const info = await lstat(requested)
-  if (!info.isFile()) throw new Error("diagnostic path is not a file")
+  if (!info.isFile()) throw new Error("LSP path is not a file")
   const actual = await realpath(requested)
-  if (!inside(base, actual)) throw new Error("diagnostic symlink escapes workspace root")
+  if (!inside(base, actual)) throw new Error("LSP symlink escapes workspace root")
   return { base, file: actual, info }
 }
 
@@ -59,7 +70,13 @@ export function lspProviderStatus(file = "") {
       const selected = provider.commands.find(([command]) => commandExists(command)) || null
       return { id: provider.id, available: Boolean(selected), command: selected?.[0] || null, extensions: [...provider.extensions] }
     })
-  return { schemaVersion: 1, extension: ext, available: providers.some((row) => row.available), providers }
+  return {
+    schemaVersion: 2,
+    extension: ext,
+    available: providers.some((row) => row.available),
+    operations: [...LSP_OPERATIONS],
+    providers,
+  }
 }
 
 function encodeMessage(payload) {
@@ -67,6 +84,23 @@ function encodeMessage(payload) {
   return Buffer.concat([Buffer.from("Content-Length: " + body.length + "\r\n\r\n", "ascii"), body])
 }
 
+function relativeUri(base, uri) {
+  try {
+    if (!String(uri || "").startsWith("file:")) return String(uri || "")
+    const file = fileURLToPath(uri)
+    if (!inside(base, file)) return String(uri || "")
+    return path.relative(base, file).replaceAll("\\", "/")
+  } catch {
+    return String(uri || "")
+  }
+}
+
+function position(options = {}) {
+  const line = Math.max(1, Math.trunc(Number(options.line || 1)))
+  const character = Math.max(1, Math.trunc(Number(options.character || 1)))
+  return { line: line - 1, character: character - 1 }
+}
+
 function sanitizeDiagnostic(value = {}) {
   return {
     range: value.range || null,
@@ -77,73 +111,214 @@ function sanitizeDiagnostic(value = {}) {
   }
 }
 
-export async function diagnoseCode(root, relative, options = {}) {
+function sanitizeLocations(base, value, limit = 120) {
+  const list = Array.isArray(value) ? value : value ? [value] : []
+  return list.slice(0, limit).map((item) => {
+    if (item?.targetUri) {
+      return {
+        file: relativeUri(base, item.targetUri),
+        range: item.targetRange || null,
+        selectionRange: item.targetSelectionRange || null,
+        originSelectionRange: item.originSelectionRange || null,
+      }
+    }
+    return {
+      file: relativeUri(base, item?.uri),
+      range: item?.range || null,
+    }
+  })
+}
+
+function flattenSymbols(base, values, output, parent = null, limit = 160) {
+  for (const item of Array.isArray(values) ? values : []) {
+    if (output.length >= limit) break
+    output.push({
+      name: String(item?.name || "").slice(0, 300),
+      detail: item?.detail == null ? null : String(item.detail).slice(0, 500),
+      kind: item?.kind ?? null,
+      containerName: item?.containerName || parent,
+      file: item?.location?.uri ? relativeUri(base, item.location.uri) : null,
+      range: item?.range || item?.location?.range || null,
+      selectionRange: item?.selectionRange || null,
+    })
+    if (Array.isArray(item?.children)) flattenSymbols(base, item.children, output, item?.name || parent, limit)
+  }
+  return output
+}
+
+function hoverText(contents) {
+  if (contents == null) return ""
+  if (typeof contents === "string") return contents
+  if (Array.isArray(contents)) {
+    return contents.map((item) => typeof item === "string" ? item : item?.value || "").filter(Boolean).join("\n")
+  }
+  if (typeof contents === "object") return String(contents.value || "")
+  return String(contents)
+}
+
+function sanitizeWorkspaceEdit(base, edit, limit = 240) {
+  const rows = []
+  for (const [uri, edits] of Object.entries(edit?.changes || {})) {
+    for (const item of Array.isArray(edits) ? edits : []) {
+      rows.push({ file: relativeUri(base, uri), range: item.range || null, newText: String(item.newText || "").slice(0, 4000) })
+      if (rows.length >= limit) return { edits: rows, truncated: true }
+    }
+  }
+  for (const change of Array.isArray(edit?.documentChanges) ? edit.documentChanges : []) {
+    const uri = change?.textDocument?.uri
+    for (const item of Array.isArray(change?.edits) ? change.edits : []) {
+      rows.push({ file: relativeUri(base, uri), range: item.range || null, newText: String(item.newText || "").slice(0, 4000) })
+      if (rows.length >= limit) return { edits: rows, truncated: true }
+    }
+  }
+  return { edits: rows, truncated: false }
+}
+
+function sanitizeHierarchyItem(base, item) {
+  if (!item) return null
+  return {
+    name: String(item.name || "").slice(0, 300),
+    detail: item.detail == null ? null : String(item.detail).slice(0, 500),
+    kind: item.kind ?? null,
+    file: relativeUri(base, item.uri),
+    range: item.range || null,
+    selectionRange: item.selectionRange || null,
+    _raw: item,
+  }
+}
+
+function sanitizeHierarchyCalls(base, values, direction, limit = 120) {
+  return (Array.isArray(values) ? values : []).slice(0, limit).map((call) => {
+    const item = direction === "incoming" ? call.from : call.to
+    const clean = sanitizeHierarchyItem(base, item)
+    if (clean) delete clean._raw
+    return {
+      item: clean,
+      ranges: direction === "incoming" ? (call.fromRanges || []) : (call.fromRanges || []),
+    }
+  })
+}
+
+async function withLspSession(root, relative, options, operation) {
   const target = await safeFile(root, relative)
   const provider = providerFor(target.file)
   const relativeFile = path.relative(target.base, target.file).replaceAll("\\", "/")
   if (!provider?.command) {
-    return { schemaVersion: 1, file: relativeFile, available: false, provider: provider?.id || null, diagnostics: [], reason: provider ? "lsp-command-unavailable" : "unsupported-extension" }
+    return {
+      schemaVersion: 2,
+      file: relativeFile,
+      available: false,
+      provider: provider?.id || null,
+      operation: options.operation || null,
+      reason: provider ? "lsp-command-unavailable" : "unsupported-extension",
+      result: null,
+    }
   }
 
   const maxBytes = Math.max(8 * 1024, Math.min(4 * 1024 * 1024, Number(options.maxBytes || 1024 * 1024)))
-  if (target.info.size > maxBytes) throw new Error("diagnostic file exceeds limit (" + target.info.size + " > " + maxBytes + " bytes)")
+  if (target.info.size > maxBytes) throw new Error("LSP file exceeds limit (" + target.info.size + " > " + maxBytes + " bytes)")
   const source = await readFile(target.file, "utf8")
   const uri = pathToFileURL(target.file).href
   const rootUri = pathToFileURL(target.base + path.sep).href
-  const timeoutMs = Math.max(500, Math.min(10_000, Number(options.timeoutMs || 3000)))
-  const maxDiagnostics = Math.max(1, Math.min(500, Number(options.maxDiagnostics || 100)))
+  const timeoutMs = Math.max(500, Math.min(15_000, Number(options.timeoutMs || 5000)))
 
   return await new Promise((resolve) => {
-    const child = spawn(provider.command, provider.args, { cwd: target.base, stdio: ["pipe", "pipe", "pipe"], windowsHide: true, shell: false })
+    const child = spawn(provider.command, provider.args, {
+      cwd: target.base,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+      shell: false,
+    })
     let buffer = Buffer.alloc(0)
     let stderr = ""
     let settled = false
-    let initialized = false
-    let diagnostics = []
+    let nextId = 1
+    const pending = new Map()
+    const notificationWaiters = new Map()
+    const recentNotifications = new Map()
     let timer = null
 
-    const finish = (reason, error = null) => {
+    const finish = (reason, result = null, error = null) => {
       if (settled) return
       settled = true
       if (timer) clearTimeout(timer)
+      for (const waiter of pending.values()) waiter.reject(new Error("LSP session settled: " + reason))
+      pending.clear()
       try {
-        if (initialized && child.stdin.writable) {
-          child.stdin.write(encodeMessage({ jsonrpc: "2.0", id: 2, method: "shutdown", params: null }))
-          child.stdin.write(encodeMessage({ jsonrpc: "2.0", method: "exit", params: null }))
-        }
+        if (child.stdin.writable) child.stdin.write(encodeMessage({ jsonrpc: "2.0", method: "exit", params: null }))
       } catch {}
       setTimeout(() => { try { child.kill() } catch {} }, 50).unref?.()
       resolve({
-        schemaVersion: 1,
+        schemaVersion: 2,
         file: relativeFile,
         available: true,
         provider: provider.id,
         command: provider.command,
-        diagnostics: diagnostics.slice(0, maxDiagnostics),
+        operation: options.operation || null,
         reason,
+        result,
         stderr: stderr.trim().slice(0, 2000) || null,
-        error: error ? String(error instanceof Error ? error.message : error).slice(0, 1000) : null,
+        error: error ? String(error instanceof Error ? error.message : error).slice(0, 1200) : null,
       })
     }
 
-    const handle = (message) => {
-      if (message?.id === 1 && message?.result) {
-        initialized = true
-        try {
-          child.stdin.write(encodeMessage({ jsonrpc: "2.0", method: "initialized", params: {} }))
-          child.stdin.write(encodeMessage({
-            jsonrpc: "2.0",
-            method: "textDocument/didOpen",
-            params: { textDocument: { uri, languageId: provider.languageId, version: 1, text: source } },
-          }))
-        } catch (error) {
-          finish("write-failed", error)
-        }
+    const send = (payload) => {
+      if (settled || !child.stdin.writable) throw new Error("LSP stdin unavailable")
+      child.stdin.write(encodeMessage(payload))
+    }
+
+    const request = (method, params) => new Promise((res, rej) => {
+      const id = nextId++
+      pending.set(id, { resolve: res, reject: rej, method })
+      try { send({ jsonrpc: "2.0", id, method, params }) }
+      catch (error) { pending.delete(id); rej(error) }
+    })
+
+    const notify = (method, params) => send({ jsonrpc: "2.0", method, params })
+
+    const waitForNotification = (method) => {
+      if (recentNotifications.has(method)) {
+        const value = recentNotifications.get(method)
+        recentNotifications.delete(method)
+        return Promise.resolve(value)
+      }
+      return new Promise((res) => {
+        const list = notificationWaiters.get(method) || []
+        list.push(res)
+        notificationWaiters.set(method, list)
+      })
+    }
+
+    const dispatch = (message) => {
+      if (message?.id != null && pending.has(message.id)) {
+        const waiter = pending.get(message.id)
+        pending.delete(message.id)
+        if (message.error) waiter.reject(new Error(String(message.error.message || "LSP request failed")))
+        else waiter.resolve(message.result)
         return
       }
-      if (message?.method === "textDocument/publishDiagnostics" && message?.params?.uri === uri) {
-        diagnostics = Array.isArray(message.params.diagnostics) ? message.params.diagnostics.map(sanitizeDiagnostic).slice(0, maxDiagnostics) : []
-        finish("publishDiagnostics")
+      if (message?.method) {
+        // Language servers may issue configuration/capability requests. Reply
+        // deterministically so the server does not stall waiting on a client UI.
+        if (message.id != null) {
+          try {
+            const result = message.method === "workspace/configuration"
+              ? (Array.isArray(message.params?.items) ? message.params.items.map(() => null) : [])
+              : null
+            send({ jsonrpc: "2.0", id: message.id, result })
+          } catch {}
+        }
+        const waiters = notificationWaiters.get(message.method) || []
+        if (waiters.length) {
+          notificationWaiters.delete(message.method)
+          for (const waiter of waiters) waiter(message.params)
+        } else {
+          recentNotifications.set(message.method, message.params)
+          if (recentNotifications.size > 16) {
+            const oldest = recentNotifications.keys().next().value
+            if (oldest) recentNotifications.delete(oldest)
+          }
+        }
       }
     }
 
@@ -159,31 +334,130 @@ export async function diagnoseCode(root, relative, options = {}) {
         if (buffer.length < bodyStart + length) return
         const body = buffer.subarray(bodyStart, bodyStart + length).toString("utf8")
         buffer = buffer.subarray(bodyStart + length)
-        try { handle(JSON.parse(body)) } catch {}
+        try { dispatch(JSON.parse(body)) } catch {}
       }
     }
 
     child.stdout.on("data", (chunk) => { buffer = Buffer.concat([buffer, Buffer.from(chunk)]); parse() })
     child.stderr.on("data", (chunk) => { if (stderr.length < 64 * 1024) stderr += chunk.toString() })
-    child.on("error", (error) => finish("spawn-error", error))
+    child.on("error", (error) => finish("spawn-error", null, error))
     child.on("close", (code) => { if (!settled) finish("server-exit:" + (code ?? "unknown")) })
 
-    try {
-      child.stdin.write(encodeMessage({
-        jsonrpc: "2.0",
-        id: 1,
-        method: "initialize",
-        params: {
+    timer = setTimeout(() => finish("timeout"), timeoutMs)
+    timer.unref?.()
+
+    ;(async () => {
+      try {
+        await request("initialize", {
           processId: process.pid,
           rootUri,
-          capabilities: { textDocument: { publishDiagnostics: { relatedInformation: true } } },
+          capabilities: {
+            textDocument: {
+              publishDiagnostics: { relatedInformation: true },
+              definition: { linkSupport: true },
+              references: {},
+              documentSymbol: { hierarchicalDocumentSymbolSupport: true },
+              hover: { contentFormat: ["markdown", "plaintext"] },
+              rename: { prepareSupport: true },
+              callHierarchy: {},
+            },
+            workspace: { workspaceFolders: true, applyEdit: false },
+          },
           workspaceFolders: [{ uri: rootUri, name: path.basename(target.base) || "workspace" }],
-        },
-      }))
-    } catch (error) {
-      finish("initialize-write-failed", error)
+        })
+        notify("initialized", {})
+        notify("textDocument/didOpen", {
+          textDocument: { uri, languageId: provider.languageId, version: 1, text: source },
+        })
+        const result = await operation({
+          request,
+          notify,
+          waitForNotification,
+          uri,
+          base: target.base,
+          file: relativeFile,
+        })
+        finish("ok", result)
+      } catch (error) {
+        finish("request-error", null, error)
+      }
+    })()
+  })
+}
+
+export async function lspOperation(root, relative, operation, options = {}) {
+  const op = String(operation || "")
+  if (!LSP_OPERATIONS.includes(op)) throw new Error("unsupported LSP operation: " + op)
+  const maxResults = Math.max(1, Math.min(500, Number(options.maxResults || 120)))
+  return withLspSession(root, relative, { ...options, operation: op }, async (session) => {
+    const pos = position(options)
+    const textDocument = { uri: session.uri }
+
+    if (op === "diagnostics") {
+      const params = await session.waitForNotification("textDocument/publishDiagnostics")
+      const values = Array.isArray(params?.diagnostics) ? params.diagnostics : []
+      return { diagnostics: values.slice(0, maxResults).map(sanitizeDiagnostic) }
     }
-    timer = setTimeout(() => finish("timeout"), timeoutMs)
-    timer.unref?.()
+    if (op === "definition") {
+      const result = await session.request("textDocument/definition", { textDocument, position: pos })
+      return { locations: sanitizeLocations(session.base, result, maxResults) }
+    }
+    if (op === "references") {
+      const result = await session.request("textDocument/references", {
+        textDocument,
+        position: pos,
+        context: { includeDeclaration: options.includeDeclaration !== false },
+      })
+      return { locations: sanitizeLocations(session.base, result, maxResults) }
+    }
+    if (op === "symbols") {
+      const result = await session.request("textDocument/documentSymbol", { textDocument })
+      return { symbols: flattenSymbols(session.base, result, [], null, maxResults) }
+    }
+    if (op === "hover") {
+      const result = await session.request("textDocument/hover", { textDocument, position: pos })
+      return {
+        range: result?.range || null,
+        markdown: hoverText(result?.contents).slice(0, Number(options.maxHoverChars || 12000)),
+      }
+    }
+    if (op === "rename-preview") {
+      const newName = String(options.newName || "").trim()
+      if (!newName) throw new Error("rename-preview requires newName")
+      let prepared = null
+      try {
+        prepared = await session.request("textDocument/prepareRename", { textDocument, position: pos })
+      } catch {}
+      const result = await session.request("textDocument/rename", { textDocument, position: pos, newName })
+      return {
+        prepared: prepared || null,
+        newName,
+        ...sanitizeWorkspaceEdit(session.base, result, maxResults),
+        applied: false,
+      }
+    }
+    if (op === "incoming-calls" || op === "outgoing-calls") {
+      const prepared = await session.request("textDocument/prepareCallHierarchy", { textDocument, position: pos })
+      const item = Array.isArray(prepared) ? prepared[0] : prepared
+      if (!item) return { root: null, calls: [] }
+      const method = op === "incoming-calls" ? "callHierarchy/incomingCalls" : "callHierarchy/outgoingCalls"
+      const result = await session.request(method, { item })
+      const rootItem = sanitizeHierarchyItem(session.base, item)
+      if (rootItem) delete rootItem._raw
+      return {
+        root: rootItem,
+        calls: sanitizeHierarchyCalls(session.base, result, op === "incoming-calls" ? "incoming" : "outgoing", maxResults),
+      }
+    }
+    return null
   })
 }
+
+export async function diagnoseCode(root, relative, options = {}) {
+  const result = await lspOperation(root, relative, "diagnostics", options)
+  return {
+    ...result,
+    diagnostics: result?.result?.diagnostics || [],
+    result: undefined,
+  }
+}