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

package/lib/control-center.mjs

@@ -4,6 +4,8 @@ import path from "node:path"
 import { readLearningState } from "./learning-engine.mjs"
 import { readRuntimeEvents } from "./runtime-events.mjs"
 import { evidenceStoreStatus } from "./evidence-store.mjs"
+import { memoryStatus } from "./memory-engine.mjs"
+import { capabilityFabricStatus } from "./capability-fabric.mjs"
 
 function escapeHtml(value) {
   return String(value ?? "")
@@ -65,11 +67,13 @@ async function collectEvalSummary(root) {
 
 export async function collectControlCenterData(root = process.cwd()) {
   root = path.resolve(root)
-  const [work, learning, evals, evidenceStore] = await Promise.all([
+  const [work, learning, evals, evidenceStore, memory, capabilityFabric] = await Promise.all([
     collectWork(root),
     readLearningState(root),
     collectEvalSummary(root),
     evidenceStoreStatus(root),
+    memoryStatus(root),
+    capabilityFabricStatus(root),
   ])
   return {
     schemaVersion: 2,
@@ -82,6 +86,16 @@ export async function collectControlCenterData(root = process.cwd()) {
       evidenceStore,
       runtime: "perception-adaptive-execution",
     },
+    v14: {
+      memory,
+      capabilityFabric: {
+        healthyCapabilities: capabilityFabric.healthyCapabilities,
+        totalCapabilities: capabilityFabric.totalCapabilities,
+        rows: capabilityFabric.rows,
+        observationState: capabilityFabric.observationState,
+      },
+      runtime: "context-memory-capability-fabric",
+    },
   }
 }
 
@@ -110,6 +124,7 @@ details{margin-top:10px;border-top:1px solid #243049;padding-top:8px}summary{cur
 <div class="section"><h2>Long-horizon work</h2><div class="grid" id="work"></div></div>
 <div class="section"><h2>Learning loop</h2><div class="grid" id="learning"></div></div>
 <div class="section"><h2>V11 runtime efficiency</h2><div class="grid" id="v11"></div></div>
+<div class="section"><h2>V14 context & memory fabric</h2><div class="grid" id="v14"></div></div>
 <div class="section"><h2>Recent runtime events</h2><div class="card"><table><thead><tr><th>Work</th><th>Event</th><th>Task</th><th>Time</th></tr></thead><tbody id="events"></tbody></table></div></div>
 <div class="section"><h2>Recent evaluations</h2><div class="card"><table><thead><tr><th>Suite</th><th>Model</th><th>Baseline</th><th>UES</th></tr></thead><tbody id="evals"></tbody></table></div></div>
 </div>
@@ -136,6 +151,9 @@ function render(next){
  const v11=document.querySelector("#v11");
  const store=data.v11?.evidenceStore||{};
  v11.innerHTML='<div class="card"><h3>Evidence store</h3><strong>'+esc(store.entries||0)+'</strong><div class="muted">'+esc(store.bytes||0)+' bytes externalized</div></div><div class="card"><h3>Runtime</h3><strong>V11</strong><div class="muted">'+esc(data.v11?.runtime||'adaptive')+'</div></div>';
+ const v14=document.querySelector("#v14");
+ const memory=data.v14?.memory||{};
+ v14.innerHTML='<div class="card"><h3>Verified memory</h3><strong>'+esc(memory.byStatus?.verified||0)+'</strong><div class="muted">'+esc(memory.entries||0)+' total entries</div></div><div class="card"><h3>Runtime</h3><strong>V14</strong><div class="muted">'+esc(data.v14?.runtime||'context-memory-fabric')+'</div></div>';
  const eventBody=document.querySelector("#events");
  eventBody.innerHTML="";
  for(const item of data.work){

package/lib/document-ingestion.mjs

@@ -0,0 +1,60 @@
+import { lstat, readFile, realpath } from "node:fs/promises"
+import { spawnSync } from "node:child_process"
+import path from "node:path"
+
+const BUILTIN_TEXT_EXTENSIONS = new Set([
+  ".txt", ".md", ".markdown", ".json", ".jsonl", ".csv", ".tsv", ".xml", ".html", ".htm",
+  ".yaml", ".yml", ".toml", ".ini", ".log", ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx",
+  ".py", ".java", ".kt", ".kts", ".cs", ".go", ".rs", ".rb", ".php", ".sql", ".css", ".scss",
+])
+const MARKITDOWN_EXTENSIONS = new Set([".pdf", ".docx", ".pptx", ".xlsx", ".xls", ".epub", ".zip"])
+
+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("document path escapes workspace root")
+  const info = await lstat(requested)
+  if (!info.isFile()) throw new Error("document path is not a file")
+  const actual = await realpath(requested)
+  if (!inside(base, actual)) throw new Error("document symlink escapes workspace root")
+  return { base, file: actual, info }
+}
+
+function runMarkItDown(file, options = {}) {
+  const timeout = Math.max(5_000, Math.min(120_000, Number(options.timeoutMs || 30_000)))
+  const maxBuffer = Math.max(256 * 1024, Math.min(16 * 1024 * 1024, Number(options.maxBuffer || 4 * 1024 * 1024)))
+  const attempts = process.platform === "win32"
+    ? [["markitdown.exe", [file]], ["markitdown", [file]], ["py", ["-m", "markitdown", file]], ["python", ["-m", "markitdown", file]]]
+    : [["markitdown", [file]], ["python3", ["-m", "markitdown", file]], ["python", ["-m", "markitdown", file]]]
+  for (const [command, args] of attempts) {
+    const result = spawnSync(command, args, { encoding: "utf8", timeout, maxBuffer, windowsHide: true })
+    if (result.status === 0 && String(result.stdout || "").trim()) return { provider: command.includes("python") || command === "py" ? "markitdown-python" : "markitdown-cli", markdown: String(result.stdout) }
+    if (result.error?.code !== "ENOENT" && result.status != null) return { provider: "markitdown-unavailable", error: String(result.stderr || result.error?.message || `exit ${result.status}`) }
+  }
+  return { provider: "markitdown-unavailable", error: "MarkItDown command/module was not found" }
+}
+
+export function documentIngestionSupport(file = "") {
+  const ext = path.extname(String(file)).toLowerCase()
+  return { schemaVersion: 1, extension: ext, builtin: BUILTIN_TEXT_EXTENSIONS.has(ext), markitdown: MARKITDOWN_EXTENSIONS.has(ext), supported: BUILTIN_TEXT_EXTENSIONS.has(ext) || MARKITDOWN_EXTENSIONS.has(ext) }
+}
+
+export async function ingestDocument(root, relative, options = {}) {
+  const target = await safeFile(root, relative)
+  const support = documentIngestionSupport(target.file)
+  const maxBytes = Math.max(16 * 1024, Math.min(32 * 1024 * 1024, Number(options.maxBytes || 4 * 1024 * 1024)))
+  if (target.info.size > maxBytes) throw new Error(`document exceeds ingestion limit (${target.info.size} > ${maxBytes} bytes)`)
+  if (support.builtin) {
+    const content = await readFile(target.file, "utf8")
+    return { schemaVersion: 1, provider: "builtin-text", file: path.relative(target.base, target.file).replaceAll("\\", "/"), bytes: target.info.size, markdown: content, optionalDependency: false }
+  }
+  if (support.markitdown) {
+    const converted = runMarkItDown(target.file, options)
+    if (converted.markdown) return { schemaVersion: 1, provider: converted.provider, file: path.relative(target.base, target.file).replaceAll("\\", "/"), bytes: target.info.size, markdown: converted.markdown, optionalDependency: true }
+    const error = new Error(`${converted.error}. Install Microsoft MarkItDown only when Office/PDF ingestion is needed.`)
+    error.code = "UES_MARKITDOWN_UNAVAILABLE"
+    throw error
+  }
+  throw new Error(`unsupported document extension: ${support.extension || "(none)"}`)
+}

package/lib/dynamic-workflow.mjs

@@ -50,6 +50,7 @@ function conflict(a, b) {
 
 function executionMode(classification, options) {
   if (classification.kind === "deterministic") return "deterministic"
+  if (options.allowInline === false) return "agent"
   if (classification.kind === "vision") {
     return classification.estimatedCost >= options.minVisionAgentCost ? "agent" : "inline"
   }
@@ -81,6 +82,7 @@ export function planDynamicWorkflow(tasks = [], inputOptions = {}) {
     minAgentCost: clampInt(inputOptions.minAgentCost, 5, 2, 12),
     minVisionAgentCost: clampInt(inputOptions.minVisionAgentCost, 4, 2, 12),
     deterministicFirst: inputOptions.deterministicFirst !== false,
+    allowInline: inputOptions.allowInline !== false,
   }
 
   const byID = new Map(tasks.map((task) => [task.id, task]))
@@ -176,4 +178,4 @@ export function planDynamicWorkflow(tasks = [], inputOptions = {}) {
     visionAgentTaskCount: flat.filter((task) => task.spawnAgent && task.kind === "vision").length,
     estimatedCoordinationSaved: flat.filter((task) => task.execution !== "agent").reduce((sum, task) => sum + task.estimatedCost, 0),
   }
-}
+}

package/lib/evidence-store.mjs

@@ -99,6 +99,87 @@ export async function getEvidence(root, ref, options = {}) {
   }
 }
 
+
+function evidenceSelector(ref) {
+  const value = String(ref || "").trim()
+  const index = value.indexOf("#")
+  if (index < 0) return { ref: value, selector: null }
+  return {
+    ref: value.slice(0, index),
+    selector: value.slice(index + 1),
+  }
+}
+
+function selectorParts(selector) {
+  const value = String(selector || "").trim()
+  if (!value) return []
+  if (value.startsWith("/")) {
+    return value
+      .split("/")
+      .slice(1)
+      .map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"))
+  }
+  return value
+    .replace(/\[(\d+)\]/g, ".$1")
+    .split(".")
+    .map((part) => part.trim())
+    .filter(Boolean)
+}
+
+function selectJsonValue(value, selector) {
+  let current = value
+  for (const part of selectorParts(selector)) {
+    if (Array.isArray(current)) {
+      if (!/^\d+$/.test(part)) throw new Error("Invalid array selector segment: " + part)
+      const index = Number(part)
+      if (index < 0 || index >= current.length) throw new Error("Evidence selector index out of range: " + part)
+      current = current[index]
+      continue
+    }
+    if (!current || typeof current !== "object" || !Object.hasOwn(current, part)) {
+      throw new Error("Evidence selector path not found: " + part)
+    }
+    current = current[part]
+  }
+  return current
+}
+
+export async function getEvidenceSelected(root, refWithSelector, options = {}) {
+  const split = evidenceSelector(refWithSelector)
+  if (!split.selector) return getEvidence(root, split.ref, options)
+
+  const hash = normalizeHash(split.ref)
+  const target = evidencePaths(root, hash)
+  const metadata = JSON.parse(await readFile(target.meta, "utf8"))
+  if (metadata.encoding !== "utf8" || !String(metadata.mediaType || "").includes("json")) {
+    throw new Error("Evidence selectors require JSON evidence")
+  }
+
+  const maxObjectBytes = Math.max(1024, Math.min(16 * 1024 * 1024, Number(options.maxObjectBytes || 4 * 1024 * 1024)))
+  if (Number(metadata.bytes || 0) > maxObjectBytes) {
+    throw new Error("JSON evidence is too large for selector retrieval; use byte slices instead")
+  }
+  const source = await readFile(target.data, "utf8")
+  const selected = selectJsonValue(JSON.parse(source), split.selector)
+  const encoded = typeof selected === "string"
+    ? selected
+    : JSON.stringify(stableValue(selected), null, 2)
+  const maxBytes = Math.max(1, Number(options.maxBytes || options.maxChars || 24_000))
+  const bytes = Buffer.from(encoded, "utf8")
+  const start = Math.max(0, Number(options.start || 0))
+  const slice = bytes.subarray(start, Math.min(bytes.length, start + maxBytes))
+  return {
+    ...metadata,
+    ref: split.ref + "#" + split.selector,
+    selector: split.selector,
+    selectedBytes: bytes.length,
+    truncated: start + slice.length < bytes.length,
+    start,
+    returnedBytes: slice.length,
+    content: slice.toString("utf8"),
+  }
+}
+
 async function metadataFiles(root) {
   const base = evidenceStoreRoot(root)
   const prefixes = await readdir(base, { withFileTypes: true }).catch(() => [])
@@ -175,4 +256,4 @@ export async function evidenceExists(root, ref) {
   } catch {
     return false
   }
-}
+}

package/lib/fast-verification-gate.mjs

@@ -0,0 +1,69 @@
+const BEHAVIORAL_TEST_COMMAND = [
+  /(?:^|\s)(?:node|bun)\s+--test(?:\s|$)/i,
+  /(?:^|\s)(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?test(?:\s|$|:)/i,
+  /(?:^|\s)(?:npx\s+)?(?:jest|vitest|pytest)(?:\s|$)/i,
+  /(?:^|\s)go\s+test(?:\s|$)/i,
+  /(?:^|\s)cargo\s+test(?:\s|$)/i,
+  /(?:^|\s)dotnet\s+test(?:\s|$)/i,
+  /(?:^|\s)(?:mvn|mvnw|gradle|gradlew|\.\/gradlew|gradlew\.bat)\b[^\n]*\btest\b/i,
+]
+
+function commandText(row = {}) {
+  const receipt = row?.receipt || {}
+  return [receipt.command, ...(Array.isArray(receipt.args) ? receipt.args : [])].filter(Boolean).join(" ").trim()
+}
+
+function finishedAtMs(row = {}) {
+  const value = Date.parse(row?.finishedAt || row?.receipt?.finishedAt || "")
+  return Number.isFinite(value) ? value : null
+}
+
+export function isBehavioralVerificationReceipt(row = {}) {
+  const receipt = row?.receipt || {}
+  if (receipt.passed !== true || Number(receipt.exitCode) !== 0) return false
+  const command = commandText(row)
+  return Boolean(command) && BEHAVIORAL_TEST_COMMAND.some((pattern) => pattern.test(command))
+}
+
+export function evaluateFastVerificationGate(input = {}) {
+  const policy = input.policy || {}
+  const implementation = input.implementation || {}
+  const receipts = Array.isArray(input.receipts) ? input.receipts : []
+  const attemptStartedAtMs = Number(input.attemptStartedAtMs || 0)
+  const eligible =
+    policy.executionProfile === "fast" &&
+    policy.singleFileBounded === true &&
+    policy.risk === "low" &&
+    input.visualRequired !== true
+  const implementationOk =
+    Number(implementation.exitCode) === 0 &&
+    String(implementation.stopReason || "").toLowerCase() !== "error"
+  const verificationText = String(implementation?.report?.sections?.verification || "").trim()
+  const implementationReportedVerification =
+    Boolean(verificationText) &&
+    !/(?:not\s+run|not\s+available|skipped|unverified|no\s+(?:tests?|checks?)\s+(?:run|available))/i.test(verificationText)
+  const behavioralReceipts = receipts
+    .filter((row) => {
+      const finished = finishedAtMs(row)
+      return isBehavioralVerificationReceipt(row) &&
+        (attemptStartedAtMs <= 0 || (finished != null && finished >= attemptStartedAtMs))
+    })
+    .map((row) => ({
+      command: commandText(row),
+      finishedAt: row?.finishedAt || row?.receipt?.finishedAt || null,
+      receiptId: row?.receipt?.id || null,
+    }))
+  let reason = "fresh-behavioral-evidence"
+  if (!eligible) reason = "not-fast-bounded"
+  else if (!implementationOk) reason = "implementation-not-clean"
+  else if (!implementationReportedVerification) reason = "implementation-did-not-report-verification"
+  else if (!behavioralReceipts.length) reason = "no-fresh-behavioral-receipt"
+  return {
+    schemaVersion: 1,
+    eligible,
+    passed: eligible && implementationOk && implementationReportedVerification && behavioralReceipts.length > 0,
+    reason,
+    behavioralReceiptCount: behavioralReceipts.length,
+    behavioralReceipts,
+  }
+}

package/lib/hierarchical-context.mjs

@@ -0,0 +1,215 @@
+import path from "node:path"
+import { buildSemanticIndex } from "./semantic-index.mjs"
+
+const DEFAULT_L0 = 256
+const DEFAULT_L1 = 4000
+const STOP = new Set([
+  "this","that","with","from","into","then","than","when","where","what","your","have","will",
+  "task","code","file","files","fix","update","change","changes","được","các","cho","với","trong","này","một","những","không","theo",
+])
+
+function terms(value) {
+  return [...new Set(
+    String(value || "")
+      .toLowerCase()
+      .split(/[^\p{L}\p{N}_$.-]+/u)
+      .map((item) => item.replace(/^[-.$]+|[-.$]+$/g, ""))
+      .filter((item) => item.length >= 2 && !STOP.has(item)),
+  )].slice(0, 32)
+}
+
+function ancestors(file) {
+  const parts = String(file || "").replaceAll("\\", "/").split("/").filter(Boolean)
+  const result = ["."]
+  let current = ""
+  for (let index = 0; index < parts.length - 1; index += 1) {
+    current = current ? `${current}/${parts[index]}` : parts[index]
+    result.push(current)
+  }
+  return result
+}
+
+function parentDir(dir) {
+  if (!dir || dir === ".") return null
+  const value = path.posix.dirname(dir)
+  return value === "." ? "." : value
+}
+
+function clip(value, limit) {
+  const text = String(value || "")
+  return text.length <= limit ? text : text.slice(0, Math.max(0, limit - 15)) + "...[truncated]"
+}
+
+function topCounts(map, limit) {
+  return [...map.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, limit)
+    .map(([name, count]) => ({ name, count }))
+}
+
+function buildNodeSummary(node, children, options = {}) {
+  const l0Limit = Math.max(96, Number(options.l0Chars || DEFAULT_L0))
+  const l1Limit = Math.max(512, Number(options.l1Chars || DEFAULT_L1))
+  const symbols = topCounts(node.symbols, 18)
+  const extensions = topCounts(node.extensions, 10)
+  const files = [...node.files].sort()
+  const childNames = (children.get(node.path) || []).sort()
+  const l0 = clip([
+    `${node.path}: ${files.length} source file(s), ${node.bytes} bytes.`,
+    symbols.length ? `Key symbols: ${symbols.slice(0, 8).map((item) => item.name).join(", ")}.` : "",
+    childNames.length ? `Child areas: ${childNames.slice(0, 6).join(", ")}.` : "",
+  ].filter(Boolean).join(" "), l0Limit)
+  const l1 = clip([
+    l0,
+    childNames.length ? `Children: ${childNames.join(", ")}` : "",
+    extensions.length ? `Extensions: ${extensions.map((item) => `${item.name || "(none)"}:${item.count}`).join(", ")}` : "",
+    symbols.length ? `Symbols: ${symbols.map((item) => `${item.name}:${item.count}`).join(", ")}` : "",
+    files.length ? `Files: ${files.slice(0, 60).join(", ")}` : "",
+  ].filter(Boolean).join("\n"), l1Limit)
+  return {
+    path: node.path,
+    fileCount: files.length,
+    bytes: node.bytes,
+    files,
+    symbols,
+    children: childNames,
+    l0,
+    l1,
+  }
+}
+
+export async function buildContextHierarchy(root = process.cwd(), options = {}) {
+  root = path.resolve(root)
+  const built = options.builtIndex || await buildSemanticIndex(root, {
+    maxFiles: options.maxFiles ?? 6000,
+    maxDepth: options.maxDepth ?? 14,
+  })
+  const nodes = new Map()
+  const children = new Map()
+  const ensure = (dir) => {
+    if (!nodes.has(dir)) {
+      nodes.set(dir, { path: dir, files: new Set(), bytes: 0, symbols: new Map(), extensions: new Map() })
+    }
+    return nodes.get(dir)
+  }
+
+  ensure(".")
+  for (const [file, entry] of Object.entries(built.index.files || {})) {
+    const dirs = ancestors(file)
+    const extension = path.posix.extname(file).toLowerCase()
+    for (const dir of dirs) {
+      const node = ensure(dir)
+      node.files.add(file)
+      node.bytes += Number(entry.bytes || 0)
+      node.extensions.set(extension, (node.extensions.get(extension) || 0) + 1)
+      for (const symbol of entry.symbols || []) {
+        const name = String(symbol.name || "")
+        if (!name) continue
+        node.symbols.set(name, (node.symbols.get(name) || 0) + 1)
+      }
+    }
+  }
+
+  for (const dir of nodes.keys()) {
+    const parent = parentDir(dir)
+    if (!parent) continue
+    const list = children.get(parent) || []
+    if (!list.includes(dir)) list.push(dir)
+    children.set(parent, list)
+  }
+
+  const summaries = [...nodes.values()]
+    .map((node) => buildNodeSummary(node, children, options))
+    .sort((a, b) => a.path.localeCompare(b.path))
+
+  return {
+    schemaVersion: 1,
+    kind: "ues-context-hierarchy",
+    root,
+    generatedAt: new Date().toISOString(),
+    levels: {
+      L0: { maxChars: Math.max(96, Number(options.l0Chars || DEFAULT_L0)), purpose: "routing abstract" },
+      L1: { maxChars: Math.max(512, Number(options.l1Chars || DEFAULT_L1)), purpose: "scope overview" },
+      L2: { purpose: "source excerpts loaded on demand by the context manifest" },
+    },
+    nodes: summaries,
+    stats: built.stats,
+  }
+}
+
+function containsFile(scope, file) {
+  if (scope === ".") return true
+  return file === scope || file.startsWith(scope + "/")
+}
+
+function scopesOverlap(left, right) {
+  if (left === "." || right === ".") return true
+  return left === right || left.startsWith(right + "/") || right.startsWith(left + "/")
+}
+
+export function selectDiverseHierarchyScopes(rows = [], maxScopes = 6) {
+  const limit = Math.max(1, Math.min(Number(maxScopes || 6), 20))
+  const selected = []
+  for (const row of rows) {
+    if (selected.length >= limit) break
+    if (selected.some((item) => scopesOverlap(item.path, row.path))) continue
+    selected.push(row)
+  }
+  if (!selected.length && rows.length) selected.push(rows[0])
+  return selected
+}
+
+export async function queryContextHierarchy(root, query, options = {}) {
+  const hierarchy = await buildContextHierarchy(root, options)
+  const wanted = terms(query)
+  const declared = (options.declaredFiles || []).map((file) => String(file || "").replaceAll("\\", "/")).filter(Boolean)
+  const scored = hierarchy.nodes.map((node) => {
+    const lowerPath = node.path.toLowerCase()
+    const symbolText = node.symbols.map((item) => item.name.toLowerCase()).join(" ")
+    const fileText = node.files.slice(0, 100).join(" ").toLowerCase()
+    let score = node.path === "." ? 0.25 : 0
+    const reasons = []
+    for (const term of wanted) {
+      if (lowerPath.includes(term)) {
+        score += 8
+        reasons.push("path:" + term)
+      }
+      if (symbolText.includes(term)) {
+        score += 5
+        reasons.push("symbol:" + term)
+      }
+      if (fileText.includes(term)) {
+        score += 2
+        reasons.push("file:" + term)
+      }
+    }
+    const declaredHits = declared.filter((file) => containsFile(node.path, file)).length
+    if (declaredHits) {
+      score += 20 + declaredHits * 4
+      reasons.push("declared:" + declaredHits)
+    }
+    const depth = node.path === "." ? 0 : node.path.split("/").length
+    if (score > 0) score += Math.min(3, depth * 0.4)
+    score -= Math.min(2.5, Math.log1p(node.fileCount) * 0.15)
+    return { ...node, score: Number(score.toFixed(3)), reasons: [...new Set(reasons)].slice(0, 12) }
+  })
+
+  const maxScopes = Math.max(1, Math.min(Number(options.maxScopes || 6), 20))
+  const positive = scored
+    .filter((item) => item.score > 0)
+    .sort((a, b) => b.score - a.score || a.fileCount - b.fileCount || a.path.localeCompare(b.path))
+  const scopes = selectDiverseHierarchyScopes(
+    positive.length ? positive : scored.filter((item) => item.path === "."),
+    maxScopes,
+  )
+
+  return {
+    schemaVersion: 1,
+    kind: "ues-context-hierarchy-query",
+    query: String(query || ""),
+    terms: wanted,
+    levels: hierarchy.levels,
+    scopes,
+    stats: hierarchy.stats,
+  }
+}

package/lib/mcp-health.mjs

@@ -0,0 +1,144 @@
+const TRANSIENT_ERROR =
+  /(timeout|timed out|econnreset|econnrefused|socket|connection (?:closed|reset|lost)|transport|network|temporar(?:y|ily)|service unavailable|bad gateway|gateway timeout|\b502\b|\b503\b|\b504\b|rate limit|\b429\b)/i
+
+function nowMs(value) {
+  const number = Number(value)
+  return Number.isFinite(number) ? number : Date.now()
+}
+
+export function isTransientMcpFailure(value = "") {
+  return TRANSIENT_ERROR.test(String(value || ""))
+}
+
+export function mcpReconnectAdvice(input = {}) {
+  const policy = input.policy || {}
+  const attempt = Math.max(1, Math.trunc(Number(input.attempt || 1)))
+  const transient = isTransientMcpFailure(input.error || input.message || "")
+  const destructive = policy.confirmationRequired === true || policy.annotations?.destructiveHint === true
+  const retryable = policy.retryAllowed === true && transient && !destructive && attempt < Math.max(1, Number(input.maxAttempts || 3))
+  return {
+    schemaVersion: 1,
+    retryable,
+    reconnectRecommended: retryable,
+    reason: destructive
+      ? "destructive-tool-never-auto-reconnect"
+      : !transient
+        ? "non-transient-failure"
+        : policy.retryAllowed !== true
+          ? "tool-not-explicitly-idempotent"
+          : retryable
+            ? "transient-idempotent-failure"
+            : "retry-budget-exhausted",
+    backoffMs: retryable ? Math.min(5_000, 250 * (2 ** Math.max(0, attempt - 1))) : 0,
+  }
+}
+
+export class McpHealthTracker {
+  constructor(options = {}) {
+    this.failureThreshold = Math.max(1, Math.min(10, Number(options.failureThreshold || 2)))
+    this.cooldownMs = Math.max(1_000, Math.min(5 * 60_000, Number(options.cooldownMs || 15_000)))
+    this.maxEntries = Math.max(16, Math.min(2_000, Number(options.maxEntries || 256)))
+    this.state = new Map()
+    this.active = new Map()
+  }
+
+  clear() {
+    this.state.clear()
+    this.active.clear()
+  }
+
+  begin(callId, toolName, policy = {}, at = Date.now()) {
+    const id = String(callId || "")
+    const name = String(toolName || "")
+    if (id && name) this.active.set(id, { name, policy, startedAt: nowMs(at) })
+    this.#trim()
+    return this.status(name, at)
+  }
+
+  finish(callId, result = {}, at = Date.now()) {
+    const id = String(callId || "")
+    const active = this.active.get(id)
+    if (!active) return null
+    this.active.delete(id)
+    const timestamp = nowMs(at)
+    const previous = this.state.get(active.name) || {
+      successes: 0,
+      failures: 0,
+      consecutiveFailures: 0,
+      cooldownUntil: 0,
+      lastError: null,
+      lastFinishedAt: 0,
+    }
+    const errorText = [
+      result.error,
+      result.message,
+      result.stderr,
+      result.text,
+    ].filter(Boolean).join("\n").slice(0, 4000)
+    const failed = result.isError === true || Number(result.exitCode) > 0
+    const transient = failed && isTransientMcpFailure(errorText)
+    const consecutiveFailures = failed ? Number(previous.consecutiveFailures || 0) + 1 : 0
+    const cooldownUntil = transient && consecutiveFailures >= this.failureThreshold
+      ? timestamp + this.cooldownMs
+      : failed
+        ? Number(previous.cooldownUntil || 0)
+        : 0
+    const reconnectAdvice = failed
+      ? mcpReconnectAdvice({ policy: active.policy, error: errorText, attempt: consecutiveFailures })
+      : null
+    const next = {
+      successes: Number(previous.successes || 0) + (failed ? 0 : 1),
+      failures: Number(previous.failures || 0) + (failed ? 1 : 0),
+      consecutiveFailures,
+      cooldownUntil,
+      lastError: failed ? errorText || "tool-result-error" : null,
+      lastTransientFailure: transient,
+      reconnectAdvice,
+      lastFinishedAt: timestamp,
+      policy: active.policy,
+    }
+    this.state.set(active.name, next)
+    this.#trim()
+    return this.status(active.name, timestamp)
+  }
+
+  status(toolName, at = Date.now()) {
+    const name = String(toolName || "")
+    const row = this.state.get(name)
+    const timestamp = nowMs(at)
+    if (!row) {
+      return { schemaVersion: 1, tool: name, status: "unknown", available: true, consecutiveFailures: 0, cooldownUntil: null }
+    }
+    const coolingDown = Number(row.cooldownUntil || 0) > timestamp
+    return {
+      schemaVersion: 1,
+      tool: name,
+      status: coolingDown ? "degraded" : row.consecutiveFailures > 0 ? "recovering" : "healthy",
+      available: !coolingDown,
+      successes: row.successes,
+      failures: row.failures,
+      consecutiveFailures: row.consecutiveFailures,
+      cooldownUntil: coolingDown ? new Date(row.cooldownUntil).toISOString() : null,
+      lastError: row.lastError,
+      lastTransientFailure: row.lastTransientFailure === true,
+      reconnectAdvice: row.reconnectAdvice || null,
+      lastFinishedAt: row.lastFinishedAt ? new Date(row.lastFinishedAt).toISOString() : null,
+    }
+  }
+
+  available(toolName, at = Date.now()) {
+    return this.status(toolName, at).available !== false
+  }
+
+  snapshot(at = Date.now()) {
+    return [...this.state.keys()]
+      .sort()
+      .map((name) => this.status(name, at))
+  }
+
+  #trim() {
+    if (this.state.size <= this.maxEntries) return
+    const ordered = [...this.state.entries()].sort((a, b) => Number(a[1]?.lastFinishedAt || 0) - Number(b[1]?.lastFinishedAt || 0))
+    for (const [name] of ordered.slice(0, Math.max(0, this.state.size - this.maxEntries))) this.state.delete(name)
+  }
+}