@asobacloud/nehanda 0.0.0-stage → 0.2.0

package/lib/laya.mjs

@@ -0,0 +1,296 @@
+import { layaRequest, LAYA_DEFAULT_TIMEOUT_MS } from './laya_sidecar.mjs'
+
+/** Max characters of state passed to Laya (~300 tokens). */
+export const LAYA_STATE_CHAR_BUDGET = 1200
+
+export const TASK_STATUS_CRITERIA = {
+  investigating: 'reading code, searching, diagnosing, exploring',
+  modifying_code: 'editing, writing, applying patches, implementing',
+  awaiting_user: 'needs user input, clarification, or approval',
+  verifying: 'running tests, checking builds, validating behavior',
+  blocked: 'stuck on errors, failures, missing deps, permission denied',
+  idle: 'greeting, done, no active engineering task',
+}
+
+export const TYPE_QUESTIONS = {
+  episodic: {
+    type: 'noul',
+    instructions: 'Is this a concrete interaction event or turn-specific observation?',
+  },
+  semantic: {
+    type: 'noul',
+    instructions: 'Does this encode lasting factual knowledge about the codebase or domain?',
+  },
+  procedural: {
+    type: 'noul',
+    instructions: 'Does this describe how to do something (steps, commands, workflows)?',
+  },
+  preference: {
+    type: 'noul',
+    instructions: 'Does this capture a user preference or standing instruction?',
+  },
+}
+
+export const RELATION_QUESTIONS = {
+  semantic_related: {
+    type: 'noul',
+    instructions: 'Are these two memories semantically related?',
+  },
+  causal_influence: {
+    type: 'noul',
+    instructions: 'Does the first memory causally influence or explain the second?',
+  },
+  same_episode: {
+    type: 'noul',
+    instructions: 'Do these memories belong to the same task episode?',
+  },
+  entity_equivalent: {
+    type: 'noul',
+    instructions: 'Do these memories refer to the same entity (file, symbol, service)?',
+  },
+}
+
+export const ROUTE_QUESTIONS = {
+  need_semantic: { type: 'noul', instructions: 'Should semantic relations be searched for this query?' },
+  need_temporal: { type: 'noul', instructions: 'Should temporal relations be searched for this query?' },
+  need_causal: { type: 'noul', instructions: 'Should causal relations be searched for this query?' },
+  need_entity: { type: 'noul', instructions: 'Should entity relations be searched for this query?' },
+  multi_hop: { type: 'noul', instructions: 'Does answering require multi-hop graph traversal?' },
+  recency_important: { type: 'noul', instructions: 'Is recent information especially important?' },
+}
+
+export const EVIDENCE_QUESTIONS = {
+  sufficient: { type: 'noul', instructions: 'Is the current evidence set sufficient to answer?' },
+  further_utility: { type: 'noul', instructions: 'Would further retrieval likely improve the answer?' },
+  missing_required: { type: 'noul', instructions: 'Is required evidence still missing?' },
+  contradiction: { type: 'noul', instructions: 'Is there an unresolved contradiction in the evidence?' },
+}
+
+export const CANDIDATE_QUESTIONS = {
+  relevance: { type: 'noul', instructions: 'Is this candidate relevant to the query?' },
+  relation_useful: { type: 'noul', instructions: 'Is the relation that reached this candidate useful?' },
+  novelty: { type: 'noul', instructions: 'Does this candidate add new information beyond current evidence?' },
+  supports_evidence: { type: 'noul', instructions: 'Does this candidate support or clarify current evidence?' },
+}
+
+export const SESSION_STATE_QUESTIONS = {
+  task_status: {
+    type: 'choice',
+    instructions: 'What is the agent currently doing?',
+    criteria: TASK_STATUS_CRITERIA,
+  },
+  escalation_risk: {
+    type: 'noul',
+    instructions: 'Is the agent blocked, failing repeatedly, or needing escalation?',
+  },
+}
+
+/** Truncate from the end (most recent) to fit Laya's state budget. */
+export function truncateForLaya(text, budget = LAYA_STATE_CHAR_BUDGET) {
+  if (!text) return ''
+  const s = String(text)
+  if (s.length <= budget) return s
+  return s.slice(s.length - budget)
+}
+
+/**
+ * @typedef {{ predict?: Function, timeoutMs?: number }} LayaOpts
+ */
+
+/** Optional injectible predictor for tests; defaults to sidecar. */
+let _predictOverride = null
+
+export function setLayaPredictOverride(fn) {
+  _predictOverride = fn
+}
+
+export function clearLayaPredictOverride() {
+  _predictOverride = null
+}
+
+/**
+ * Core System-1 call. Returns { ok, answers, error, degraded }.
+ * On timeout/failure, returns degraded heuristic answers when questions are known.
+ */
+export async function queryLaya(state, questions, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? LAYA_DEFAULT_TIMEOUT_MS
+  const clipped = truncateForLaya(state)
+
+  if (typeof opts.predict === 'function') {
+    try {
+      const result = await opts.predict(clipped, questions)
+      return { ok: true, answers: normalizeAnswers(result), degraded: false }
+    } catch (e) {
+      return { ok: false, answers: heuristicAnswers(questions, clipped), error: String(e), degraded: true }
+    }
+  }
+
+  if (_predictOverride) {
+    try {
+      const result = await _predictOverride(clipped, questions)
+      return { ok: true, answers: normalizeAnswers(result), degraded: false }
+    } catch (e) {
+      process.stderr.write(
+        `[laya] WARNING: System-1 degraded (predictOverride threw) — ${e}. Falling back to heuristics.\n`
+      )
+      return { ok: false, answers: heuristicAnswers(questions, clipped), error: String(e), degraded: true }
+    }
+  }
+
+  const resp = await layaRequest('predict', { state: clipped, questions }, timeoutMs)
+  if (!resp.ok) {
+    const errMsg = resp.error || 'laya failed'
+    // Laya is mandatory — a failure here means System-1 is not working.
+    // Emit a visible warning so operators know this is not running correctly.
+    process.stderr.write(
+      `[laya] WARNING: System-1 degraded — ${errMsg}. ` +
+      `Run lib/scripts/ensure-laya-env.sh to fix. Falling back to heuristics.\n`
+    )
+    return {
+      ok: false,
+      answers: heuristicAnswers(questions, clipped),
+      error: errMsg,
+      degraded: true,
+    }
+  }
+  return { ok: true, answers: normalizeAnswers(resp.result), degraded: false }
+}
+
+function normalizeAnswers(result) {
+  if (!result) return {}
+  if (result.answers && typeof result.answers === 'object') return result.answers
+  return result
+}
+
+function noulProb(answers, key) {
+  const a = answers?.[key]
+  if (a == null) return 0
+  if (typeof a === 'number') return a
+  if (typeof a.noul === 'number') return a.noul
+  if (typeof a.probability === 'number') return a.probability
+  return 0
+}
+
+function choiceOf(answers, key, fallback = 'investigating') {
+  const a = answers?.[key]
+  if (!a) return fallback
+  if (typeof a === 'string') return a
+  if (typeof a.choice === 'string') return a.choice
+  return fallback
+}
+
+function confidenceOf(answers, key) {
+  const a = answers?.[key]
+  if (a && typeof a.confidence === 'number') return a.confidence
+  return null
+}
+
+/** Keyword heuristic fallback when Laya is unavailable — never crash the CLI. */
+export function heuristicAnswers(questions, stateText = '') {
+  const t = (stateText || '').toLowerCase()
+  const out = {}
+  for (const [key, q] of Object.entries(questions || {})) {
+    if (q.type === 'choice' && key === 'task_status') {
+      let choice = 'investigating'
+      if (/\b(error|fail|blocked|denied)\b/.test(t)) choice = 'blocked'
+      else if (/\b(test|pytest|npm test|verify|build)\b/.test(t)) choice = 'verifying'
+      else if (/\b(edit|write|patch|implement|search\/replace)\b/.test(t)) choice = 'modifying_code'
+      else if (/\b(please confirm|awaiting|should i)\b/.test(t)) choice = 'awaiting_user'
+      out[key] = { choice, confidence: 0.4 }
+    } else if (q.type === 'noul') {
+      let p = 0.3
+      if (key === 'escalation_risk' || key === 'blocked') p = /\b(error|fail|blocked)\b/.test(t) ? 0.7 : 0.2
+      if (key === 'episodic') p = 0.6
+      if (key === 'semantic') p = 0.5
+      if (key === 'procedural') p = /\b(run|command|step)\b/.test(t) ? 0.6 : 0.3
+      if (key === 'sufficient') p = 0.5
+      if (key === 'further_utility') p = 0.4
+      out[key] = { noul: p, confidence: 0.35 }
+    } else if (q.type === 'choice') {
+      const first = Object.keys(q.criteria || {})[0] || 'other'
+      out[key] = { choice: first, confidence: 0.3 }
+    }
+  }
+  return out
+}
+
+/**
+ * Extract canonical session control state from transcript tail + tool file paths.
+ * file_target is hybrid: deterministic paths win; Laya only sets categorical fields.
+ */
+export async function extractCanonicalState(transcriptText, filePaths = [], opts = {}) {
+  const paths = Array.isArray(filePaths) ? filePaths.filter(Boolean) : []
+  const file_target = paths.length ? paths[paths.length - 1] : null
+  const q = await queryLaya(transcriptText, SESSION_STATE_QUESTIONS, opts)
+  const answers = q.answers
+  const task_status = choiceOf(answers, 'task_status')
+  const escalation_risk = noulProb(answers, 'escalation_risk') >= 0.5
+  const conf = confidenceOf(answers, 'task_status') ?? (q.degraded ? 0.35 : 0.7)
+  return {
+    task_status,
+    file_target,
+    escalation_risk,
+    confidence_score: conf,
+    degraded: q.degraded,
+    error: q.error || null,
+  }
+}
+
+export async function typeMemoryObservation(text, opts = {}) {
+  const q = await queryLaya(text, TYPE_QUESTIONS, opts)
+  return {
+    t_episodic: noulProb(q.answers, 'episodic'),
+    t_semantic: noulProb(q.answers, 'semantic'),
+    t_procedural: noulProb(q.answers, 'procedural'),
+    t_preference: noulProb(q.answers, 'preference'),
+    degraded: q.degraded,
+  }
+}
+
+export async function judgeRelations(pairText, opts = {}) {
+  const q = await queryLaya(pairText, RELATION_QUESTIONS, opts)
+  return {
+    semantic: noulProb(q.answers, 'semantic_related'),
+    causal: noulProb(q.answers, 'causal_influence'),
+    same_episode: noulProb(q.answers, 'same_episode'),
+    entity: noulProb(q.answers, 'entity_equivalent'),
+    degraded: q.degraded,
+  }
+}
+
+export async function routeQuery(queryText, opts = {}) {
+  const q = await queryLaya(queryText, ROUTE_QUESTIONS, opts)
+  return {
+    semantic: noulProb(q.answers, 'need_semantic'),
+    temporal: noulProb(q.answers, 'need_temporal'),
+    causal: noulProb(q.answers, 'need_causal'),
+    entity: noulProb(q.answers, 'need_entity'),
+    multi_hop: noulProb(q.answers, 'multi_hop'),
+    recency: noulProb(q.answers, 'recency_important'),
+    degraded: q.degraded,
+  }
+}
+
+export async function assessEvidence(evidenceText, opts = {}) {
+  const q = await queryLaya(evidenceText, EVIDENCE_QUESTIONS, opts)
+  return {
+    sufficient: noulProb(q.answers, 'sufficient'),
+    further_utility: noulProb(q.answers, 'further_utility'),
+    missing_required: noulProb(q.answers, 'missing_required'),
+    contradiction: noulProb(q.answers, 'contradiction'),
+    degraded: q.degraded,
+  }
+}
+
+export async function scoreCandidate(candidateText, opts = {}) {
+  const q = await queryLaya(candidateText, CANDIDATE_QUESTIONS, opts)
+  return {
+    relevance: noulProb(q.answers, 'relevance'),
+    relation_useful: noulProb(q.answers, 'relation_useful'),
+    novelty: noulProb(q.answers, 'novelty'),
+    supports_evidence: noulProb(q.answers, 'supports_evidence'),
+    degraded: q.degraded,
+  }
+}
+
+export { noulProb, choiceOf }

package/lib/laya_sidecar.mjs

@@ -0,0 +1,198 @@
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const WORKER_PATH = path.resolve(__dirname, 'scripts', 'laya_worker.py')
+const ENSURE_SCRIPT = path.resolve(__dirname, 'scripts', 'ensure-laya-env.sh')
+const DEFAULT_TIMEOUT_MS = 100
+const NEHANDA_HOME = process.env.NEHANDA_HOME || path.join(process.env.HOME || '/tmp', '.nehanda')
+const VENV_PYTHON = path.join(NEHANDA_HOME, 'venv', 'bin', 'python')
+const LAYA_READY_MARKER = path.join(NEHANDA_HOME, '.laya-ready')
+
+let child = null
+let reqId = 1
+let pending = new Map()
+let buffer = ''
+let restartCount = 0
+const MAX_RESTARTS = 3
+
+// Track provision state so ensureLayaReady() is idempotent across the process lifetime.
+let _provisionDone = false
+let _provisionError = null
+
+/**
+ * Resolve the Python binary that has the laya package installed.
+ * Returns the venv python path if available, otherwise throws — no silent
+ * fallback to system python3 which will never have laya installed.
+ */
+function resolvePython() {
+  if (process.env.LAYA_PYTHON) return process.env.LAYA_PYTHON
+  if (fs.existsSync(VENV_PYTHON)) return VENV_PYTHON
+  throw new Error(
+    `Laya venv not found at ${VENV_PYTHON}. ` +
+    `Run lib/scripts/ensure-laya-env.sh or call ensureLayaReady() at startup.`
+  )
+}
+
+function attachChild(c) {
+  buffer = ''
+  c.stdout.on('data', chunk => {
+    buffer += chunk.toString('utf8')
+    const lines = buffer.split('\n')
+    buffer = lines.pop() ?? ''
+    for (const line of lines) {
+      if (!line.trim()) continue
+      let msg
+      try { msg = JSON.parse(line) } catch { continue }
+      if (msg.id != null && pending.has(msg.id)) {
+        const { resolve, timer } = pending.get(msg.id)
+        clearTimeout(timer)
+        pending.delete(msg.id)
+        resolve(msg)
+      }
+    }
+  })
+  c.on('error', err => {
+    process.stderr.write(`[laya-sidecar] worker error: ${err.message}\n`)
+    child = null
+  })
+  c.on('close', code => {
+    if (code != null && code !== 0) {
+      process.stderr.write(`[laya-sidecar] worker exited with code ${code}\n`)
+    }
+    child = null
+    for (const [, p] of pending) {
+      clearTimeout(p.timer)
+      p.resolve({ ok: false, error: 'laya worker closed' })
+    }
+    pending.clear()
+  })
+}
+
+function ensureChild() {
+  if (child && !child.killed) return true
+  if (restartCount >= MAX_RESTARTS) return false
+  if (!fs.existsSync(WORKER_PATH)) return false
+  let py
+  try {
+    py = resolvePython()
+  } catch (e) {
+    process.stderr.write(`[laya-sidecar] ${e.message}\n`)
+    return false
+  }
+  try {
+    child = spawn(py, [WORKER_PATH], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env },
+    })
+    restartCount += 1
+    attachChild(child)
+    return true
+  } catch (e) {
+    process.stderr.write(`[laya-sidecar] failed to spawn worker: ${e.message}\n`)
+    child = null
+    return false
+  }
+}
+
+/**
+ * Verify Laya is provisioned and warm the sidecar with a real ping so the
+ * checkpoint is in memory before the first user turn.
+ *
+ * Provisioning happens at npm install time via scripts/postinstall.mjs.
+ * If the marker is missing, the user is directed to re-run provisioning
+ * rather than attempting a silent download mid-session.
+ *
+ * Throws on failure — Laya is mandatory, not optional.
+ */
+export async function ensureLayaReady() {
+  if (_provisionDone) return
+  if (_provisionError) throw _provisionError
+
+  const markerExists = fs.existsSync(LAYA_READY_MARKER) && fs.existsSync(VENV_PYTHON)
+
+  if (!markerExists) {
+    const msg =
+      `[laya-sidecar] Laya is not provisioned.\n` +
+      `  The postinstall step did not complete successfully.\n` +
+      `  Re-run provisioning manually:\n` +
+      `    bash ${ENSURE_SCRIPT}\n` +
+      `  Or reinstall the package:\n` +
+      `    npm install @asobacloud/nehanda`
+    process.stderr.write(msg + '\n')
+    _provisionError = new Error(msg)
+    throw _provisionError
+  }
+
+  // Warm the sidecar: spawn worker + send a real predict so the checkpoint
+  // loads into memory before the first user turn.
+  process.stderr.write('[laya-sidecar] warming Laya sidecar...\n')
+  const warm = await pingLaya(60_000)
+  if (!warm.ok) {
+    const msg = `[laya-sidecar] Laya warm-up failed: ${warm.error}`
+    process.stderr.write(msg + '\n')
+    _provisionError = new Error(msg)
+    throw _provisionError
+  }
+
+  process.stderr.write('[laya-sidecar] Laya ready.\n')
+  _provisionDone = true
+}
+
+/**
+ * Send a request to the Laya stdio worker.
+ * @returns {Promise<{ok:boolean, result?:any, error?:string}>}
+ */
+export function layaRequest(method, params = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  return new Promise(resolve => {
+    if (!ensureChild()) {
+      resolve({ ok: false, error: 'laya worker unavailable' })
+      return
+    }
+    const id = reqId++
+    const payload = JSON.stringify({ id, method, params }) + '\n'
+    const timer = setTimeout(() => {
+      pending.delete(id)
+      resolve({ ok: false, error: `laya timeout after ${timeoutMs}ms` })
+    }, timeoutMs)
+    pending.set(id, { resolve, timer })
+    try {
+      child.stdin.write(payload, 'utf8')
+    } catch (e) {
+      clearTimeout(timer)
+      pending.delete(id)
+      resolve({ ok: false, error: String(e) })
+    }
+  })
+}
+
+/** Warm ping (longer timeout for cold start). */
+export async function pingLaya(timeoutMs = 30_000) {
+  restartCount = 0
+  return layaRequest('ping', {}, timeoutMs)
+}
+
+export async function shutdownLaya() {
+  if (!child) return
+  await layaRequest('shutdown', {}, 2000)
+  try { child.kill() } catch { /* */ }
+  child = null
+  restartCount = 0
+}
+
+/** Test helper: reset restart budget. */
+export function resetLayaSidecar() {
+  if (child) {
+    try { child.kill() } catch { /* */ }
+  }
+  child = null
+  restartCount = 0
+  pending.clear()
+  buffer = ''
+  _provisionDone = false
+  _provisionError = null
+}
+
+export const LAYA_DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_MS

package/lib/mcp-config.mjs

@@ -0,0 +1,189 @@
+/**
+ * mcp-config.mjs
+ *
+ * Reads mcp.json and merges configured servers into settings.mcp_servers.
+ *
+ * Search order (first found wins, then merged in priority order):
+ *   1. <project-root>/mcp.json       — project-local, highest priority
+ *   2. ~/.config/nehanda/mcp.json    — user global
+ *
+ * Expected mcp.json schema (standard Anthropic/Claude Desktop format):
+ * {
+ *   "mcpServers": {
+ *     "server-name": {
+ *       "command": "npx",
+ *       "args": ["-y", "@some/mcp-server"],
+ *       "env": { "API_KEY": "..." }
+ *     }
+ *   }
+ * }
+ *
+ * The resulting entries are mapped into settings.mcp_servers using the
+ * same shape that lib/tools.mjs and lib/mcp.mjs already consume:
+ * { [name]: { command, args, env } }
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+
+const GLOBAL_MCP_PATH = path.join(os.homedir(), '.config', 'nehanda', 'mcp.json')
+
+/**
+ * Resolve candidate mcp.json paths for a given project root.
+ * Returns them in priority order (highest first).
+ */
+function candidatePaths(projectRoot) {
+  const candidates = []
+  if (projectRoot) candidates.push(path.join(projectRoot, 'mcp.json'))
+  candidates.push(GLOBAL_MCP_PATH)
+  return candidates
+}
+
+/**
+ * Parse a single mcp.json file. Returns { servers: {name: config}, path } or null.
+ * Tolerates missing files and bad JSON gracefully.
+ */
+function parseMcpFile(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8')
+    const parsed = JSON.parse(raw)
+    const servers = parsed?.mcpServers
+    if (!servers || typeof servers !== 'object' || Array.isArray(servers)) return null
+    // Normalise each server entry
+    const normalised = {}
+    for (const [name, cfg] of Object.entries(servers)) {
+      if (!cfg?.command || typeof cfg.command !== 'string') continue // skip invalid
+      normalised[name] = {
+        command: cfg.command,
+        args: Array.isArray(cfg.args) ? cfg.args : [],
+        env: (cfg.env && typeof cfg.env === 'object' && !Array.isArray(cfg.env)) ? cfg.env : {},
+      }
+    }
+    return { servers: normalised, path: filePath }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Load all mcp.json files for the given project root and return a merged
+ * server map. Project-local entries override global ones for the same name.
+ *
+ * @param {string} projectRoot  - Absolute path to the project working directory
+ * @returns {{ servers: Record<string, {command:string, args:string[], env:object}>, sources: string[] }}
+ */
+export function loadMcpConfig(projectRoot) {
+  const candidates = candidatePaths(projectRoot)
+  const layers = []
+
+  for (const p of candidates) {
+    const result = parseMcpFile(p)
+    if (result) layers.push(result)
+  }
+
+  // Merge layers: first found (project-local) wins
+  const merged = {}
+  // Iterate in reverse so the highest-priority (project-local, index 0) overwrites
+  for (let i = layers.length - 1; i >= 0; i--) {
+    Object.assign(merged, layers[i].servers)
+  }
+
+  return {
+    servers: merged,
+    sources: layers.map(l => l.path),
+  }
+}
+
+/**
+ * Merge mcp.json servers into an existing settings object in-place.
+ * Settings object must have (or will receive) a `mcp_servers` key.
+ * Existing programmatic entries (e.g. set via /config) are preserved;
+ * mcp.json entries for the same name are overwritten by the file.
+ *
+ * @param {object} settings     - Effective settings object (mutated in place)
+ * @param {string} projectRoot  - Absolute path to the project working directory
+ * @returns {string[]} List of mcp.json files that were loaded
+ */
+export function applyMcpConfig(settings, projectRoot) {
+  const { servers, sources } = loadMcpConfig(projectRoot)
+  if (!settings.mcp_servers || typeof settings.mcp_servers !== 'object') {
+    settings.mcp_servers = {}
+  }
+  Object.assign(settings.mcp_servers, servers)
+  return sources
+}
+
+/**
+ * Return the path where a new global mcp.json should be written.
+ */
+export function globalMcpConfigPath() {
+  return GLOBAL_MCP_PATH
+}
+
+/**
+ * Write a new or updated global mcp.json.  Creates parent dirs as needed.
+ *
+ * @param {Record<string, {command:string, args:string[], env:object}>} servers
+ */
+export function writeGlobalMcpConfig(servers) {
+  const dir = path.dirname(GLOBAL_MCP_PATH)
+  fs.mkdirSync(dir, { recursive: true })
+  const content = JSON.stringify({ mcpServers: servers }, null, 2)
+  fs.writeFileSync(GLOBAL_MCP_PATH, content, 'utf8')
+}
+
+/**
+ * Find which mcp.json file a server is defined in (project-local first).
+ * Returns { server, path } or null.
+ */
+export function getMcpServerSource(serverName, projectRoot) {
+  const candidates = candidatePaths(projectRoot)
+  for (const filePath of candidates) {
+    const result = parseMcpFile(filePath)
+    if (result && result.servers[serverName]) {
+      return { server: result.servers[serverName], path: filePath }
+    }
+  }
+  return null
+}
+
+/**
+ * Set (or clear) an environment variable for an MCP server.
+ * Updates the mcp.json file where the server is defined and reloads.
+ *
+ * @param {string} serverName  - Server name
+ * @param {string} key         - Env var name (e.g. ASOBA_API_KEY)
+ * @param {string} value       - Value to set (empty string clears the key)
+ * @param {string} projectRoot - Project working directory
+ * @returns {{ ok: boolean, path?: string, key?: string, set?: boolean, error?: string }}
+ */
+export function updateMcpServerEnv(serverName, key, value, projectRoot) {
+  const candidates = candidatePaths(projectRoot)
+
+  for (const filePath of candidates) {
+    const result = parseMcpFile(filePath)
+    if (result && result.servers[serverName]) {
+      const raw = JSON.parse(fs.readFileSync(filePath, 'utf8'))
+      const srv = raw.mcpServers[serverName]
+      if (!srv.env) srv.env = {}
+      if (value === '') {
+        delete srv.env[key]
+      } else {
+        srv.env[key] = value
+      }
+      fs.writeFileSync(filePath, JSON.stringify(raw, null, 2) + '\n', 'utf8')
+      return { ok: true, path: filePath, key, set: value !== '' }
+    }
+  }
+
+  return { ok: false, error: `Server "${serverName}" not found in any mcp.json` }
+}
+
+/**
+ * Read the current global mcp.json server map (empty object if not present).
+ */
+export function readGlobalMcpConfig() {
+  const result = parseMcpFile(GLOBAL_MCP_PATH)
+  return result?.servers ?? {}
+}