@theronap/agnoclast-mcp 0.9.96

package/lib/resolve.mjs

@@ -0,0 +1,153 @@
+import { spawnSync } from 'child_process'
+import { fetchCortex, resolveBase, resolveEnvToken, classify } from './diagnose.mjs'
+import { edgeSafeEnv } from './edge_extract.mjs'
+
+// `cortex-mcp resolve` — the JUDGE half of entity identity dedup (Grey harvest). The server FLAGS the
+// fuzzy band of near-duplicate non-person entities (GET /api/resolve-candidates); this command judges
+// each pair LOCALLY via `claude -p` (the engine preference — the server never calls the metered API)
+// and pushes decisions back (POST /api/resolve-apply): confident-same → entity_merges, else → rejected
+// so the pair never re-flags. Conservative by construction. Always exits cleanly.
+
+// Which brains to sweep. BOTH endpoints require the brain to be NAMED (ADR-0022 requireBrain —
+// answering a scoped read out of an ARBITRARY brain is the defect that whole class exists to
+// prevent). Until 2026-08-09 this command named none, so a multi-brain caller got 409 on step 1 and
+// the dedup sweep did nothing at all, silently, forever.
+//
+// Naming ONE brain would have been the smaller fix and the wrong one: `resolve` is a MAINTENANCE
+// SWEEP over the user's entities, so doing one brain and reporting success is ADR-0022's other
+// failure — "silently truncating a result set and presenting it as complete". With no --brain we
+// enumerate the caller's brains and sweep EACH, naming it explicitly. Not a guess: every request
+// still names exactly one brain, and all of them actually get done.
+//
+// A sole-brain caller sees today's behaviour: one pass, no flag, no prompt.
+export async function brainsToSweep(base, token, wanted, deps = {}) {
+  const fetchFn = deps.fetchCortex ?? fetchCortex
+  if (wanted) return [{ orgId: wanted, name: wanted }] // explicit: pass through (name or org id)
+  const res = await fetchFn(`${base}/api/brains`, { headers: { Authorization: `Bearer ${token}` } })
+  if (!res.ok) {
+    const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+    throw new Error(`could not list your brains — ${d.message}`)
+  }
+  const j = await res.json().catch(() => ({}))
+  const brains = Array.isArray(j.brains) ? j.brains : []
+  // Carry the ORG ID, never the name: brain names are NOT unique (this account holds two called
+  // "Personal"), and a duplicate name comes back as unknown_brain.
+  return brains.filter((b) => b?.orgId).map((b) => ({ orgId: b.orgId, name: b.name ?? b.orgId }))
+}
+
+export async function runResolve(argv = []) {
+  // recursion guard (we spawn `claude --print`; if its Stop hook fires capture, that no-ops on this flag)
+  if (process.env.CORTEX_SUMMARIZING) { process.stderr.write('cortex: summarizer subprocess, skipping\n'); return }
+  const token = resolveEnvToken().token
+  if (!token) { process.stderr.write('cortex: CORTEX_TOKEN not set, skipping\n'); return }
+  const base = resolveBase(process.env.CORTEX_URL)
+
+  const bIdx = argv.indexOf('--brain')
+  const wanted = bIdx === -1 ? null : argv[bIdx + 1]
+  if (bIdx !== -1 && (!wanted || wanted.startsWith('-'))) {
+    process.stderr.write('Usage: resolve [--brain <name-or-org-id>]\n'); return
+  }
+
+  let targets
+  try {
+    targets = await brainsToSweep(base, token, wanted)
+  } catch (e) { process.stderr.write(`cortex: resolve — ${e.message}\n`); return }
+  if (!targets.length) { process.stderr.write('cortex: no brains to sweep\n'); return }
+
+  for (const t of targets) {
+    // Label each line with the brain when sweeping several: an unlabelled "merged 3" cannot be acted
+    // on, because you cannot tell WHERE three entities just merged.
+    await resolveOneBrain(base, token, t, targets.length > 1)
+  }
+}
+
+async function resolveOneBrain(base, token, brain, labelled) {
+  const tag = labelled ? `[${brain.name}] ` : ''
+  const qs = `?brain=${encodeURIComponent(brain.orgId)}`
+
+  // 1. pull the flagged candidate pairs
+  let candidates = []
+  try {
+    const res = await fetchCortex(`${base}/api/resolve-candidates${qs}`, { headers: { Authorization: `Bearer ${token}` } })
+    if (!res.ok) {
+      const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+      process.stderr.write(`cortex: ${tag}resolve-candidates failed — ${d.message}\n`); return
+    }
+    const j = await res.json().catch(() => ({}))
+    candidates = Array.isArray(j.candidates) ? j.candidates : []
+  } catch (e) { process.stderr.write(`cortex: ${tag}resolve fetch failed — ${e.message}\n`); return }
+
+  if (!candidates.length) { process.stderr.write(`cortex: ${tag}no duplicate candidates to judge\n`); return }
+  process.stderr.write(`cortex: ${tag}judging ${candidates.length} candidate pair(s) locally…\n`)
+
+  // 2. judge locally on the subscription
+  const decisions = judgeCandidates(candidates)
+  if (decisions === null) { process.stderr.write(`cortex: ${tag}judge unavailable (is \`claude\` on PATH?) — skipping\n`); return }
+
+  // 3. apply — SAME brain the candidates came from, or the merges land in the wrong graph
+  try {
+    const res = await fetchCortex(`${base}/api/resolve-apply${qs}`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ decisions }),
+    })
+    if (res.ok) {
+      const j = await res.json().catch(() => ({}))
+      process.stderr.write(`cortex: ${tag}dedup — merged ${j.merged ?? 0}, rejected ${j.rejected ?? 0}, skipped ${j.skipped ?? 0}\n`)
+    } else {
+      const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+      process.stderr.write(`cortex: ${tag}resolve-apply failed — ${d.message}\n`)
+    }
+  } catch (e) { process.stderr.write(`cortex: ${tag}resolve-apply failed — ${e.message}\n`) }
+}
+
+// ONE `claude --print` call judges every pair. Returns DedupDecision[] for the apply endpoint, or null
+// if the CLI is unavailable. Every judged pair (merge AND non-merge) is returned so non-merges get
+// recorded as rejected and never re-flag.
+function judgeCandidates(candidates) {
+  const list = candidates.map((c, i) =>
+    `[${i}] kind=${c.kind}\n` +
+    `  A: "${c.aName}" (e.g. record: ${c.aSample ?? 'n/a'}; ${c.aMentions} mentions)\n` +
+    `  B: "${c.bName}" (e.g. record: ${c.bSample ?? 'n/a'}; ${c.bMentions} mentions)\n` +
+    `  shared records: ${c.sharedRecords}; name similarity: ${Number(c.sim).toFixed(2)}`,
+  ).join('\n')
+  const prompt =
+    'You are deduplicating an organization knowledge graph. For each candidate pair below, decide ' +
+    'whether A and B are the SAME real-world entity (a spelling/abbreviation/variant of ONE thing) or ' +
+    'DIFFERENT things that merely have similar names. Be CONSERVATIVE: only merge when confident; when ' +
+    'in doubt, do NOT merge. Same kind only.\n' +
+    'Return ONLY a minified JSON array — one object per pair: ' +
+    '{"i":<index>,"merge":<true|false>,"confidence":<0..1>,"reason":"<short>"}.\n\n' + list
+  try {
+    const r = spawnSync(
+      'claude',
+      ['--print', '--model', process.env.CORTEX_SUMMARY_MODEL ?? 'claude-haiku-4-5', prompt],
+      { env: edgeSafeEnv(process.env, { CORTEX_SUMMARIZING: '1' }), encoding: 'utf8', timeout: 120_000, maxBuffer: 4 * 1024 * 1024 },
+    )
+    if (r.status !== 0 || !r.stdout) return null
+    return parseDecisions(r.stdout, candidates)
+  } catch {
+    return null
+  }
+}
+
+function parseDecisions(out, candidates) {
+  const start = out.indexOf('[')
+  const end = out.lastIndexOf(']')
+  if (start < 0 || end <= start) return []
+  let arr
+  try { arr = JSON.parse(out.slice(start, end + 1)) } catch { return [] }
+  if (!Array.isArray(arr)) return []
+  const decisions = []
+  for (const d of arr) {
+    const c = candidates[Number(d?.i)]
+    if (!c) continue
+    decisions.push({
+      aId: c.aId, bId: c.bId, kind: c.kind,
+      merge: !!d.merge,
+      confidence: Number(d.confidence) || 0,
+      reason: typeof d.reason === 'string' ? d.reason.slice(0, 200) : undefined,
+    })
+  }
+  return decisions
+}