@theronap/cortex-mcp 0.9.54 → 0.9.56

package/bin/cortex-mcp.mjs

@@ -52,6 +52,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  docs-scan       detect new/changed local docs pending Cortex authoring (used by /cortex-author-docs)\n` +
     `  graphify-sync [path]  rebuild the local code graph (graphify) + log an evidence-tier timeline event\n` +
     `  snapshot-context save the exact startup context Cortex served to a local snapshot\n` +
+    `  hydrate         UserPromptSubmit hook — inject query-centered context on the first substantive turn\n` +
     `  capture         Stop-hook capturer (invoked by Claude Code)\n` +
     `  ingest-folder <path>   ingest a local markdown folder as your authored records\n` +
     `  (no args)       run the MCP server (used by your Claude config)\n\n` +
@@ -141,6 +142,14 @@ if (cmd === 'setup') {
   process.exitCode = await runSnapshotContext()
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'hydrate') {
+  // UserPromptSubmit hook (① discovery): hydrate the model with query-centered Cortex context on the
+  // FIRST substantive turn, before it answers — then never again this session (topic-shift refresh stays
+  // the cortex-context skill's job). Synchronous by necessity, but once-per-session + 8s + fail-open.
+  const { runHydrate } = await import('../lib/hydrate.mjs')
+  process.exitCode = await runHydrate()
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
 } else if (cmd === 'skills') {
   // Install / repair the managed Cortex skills — bundled + org-published (`skills push` publishes).
   // Org sync is network-fail-soft so the SessionStart hook stays safe offline.

package/lib/hydrate.mjs

@@ -0,0 +1,159 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, statSync, unlinkSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { fetchCortex, classify, resolveBase, readWiredToken } from './diagnose.mjs'
+import { redactSecrets } from './redact.mjs'
+
+// UserPromptSubmit hook (① discovery): on the FIRST substantive turn of a session, hydrate the model
+// with query-centered Cortex context BEFORE it answers — then never again this session. It closes the
+// gap that read-triggered authoring can't: an agent that never READS the wiki (works from code + memory)
+// never triggers a currency update, and re-derives already-authored truth. cortex-context is a SKILL the
+// model may forget to invoke; this makes the first hydration non-discretionary (the same move that made
+// authoring pre-authorized). Mid-session topic-shift refresh stays the cortex-context skill's job — a
+// hook can't cheaply judge a semantic topic change.
+//
+// It MUST be synchronous: the value is being in-context before the reply, so it cannot be detached like
+// capture. That cost is bounded — once per session, an 8s timeout, and FAIL-OPEN: any miss injects
+// nothing and never holds up the user's first message. Always exits 0; hydration must never break a turn.
+
+const HYDRATE_TIMEOUT_MS = 8_000
+const MAX_ATTEMPTS = 2 // give up after N failed tries so a dead endpoint isn't re-hit every turn
+const MIN_SUBSTANTIVE_CHARS = 15
+// Bare greetings/affirmations are not a real opening query — skip WITHOUT marking done, so the first
+// substantive prompt still hydrates. Anchored to the whole string so "go" skips but "go build X" does not.
+const TRIVIAL_RE = /^(hi|hey|hello|yo|sup|thanks|thank you|ty|ok|okay|k|kk|yes|yep|yup|yeah|no|nope|nah|sure|go|go ahead|do it|continue|next|please)\b[\s!.?]*$/i
+const STATE_RETENTION_DAYS = 7
+
+function hydrationDir() {
+  return join(homedir(), '.cortex', 'hydration')
+}
+function stateFile(sessionId) {
+  return join(hydrationDir(), `${sessionId}.json`)
+}
+
+function readState(sessionId) {
+  try {
+    return JSON.parse(readFileSync(stateFile(sessionId), 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+function writeState(sessionId, state) {
+  try {
+    const dir = hydrationDir()
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+    writeFileSync(stateFile(sessionId), JSON.stringify(state))
+  } catch {
+    /* best-effort — a state write failure must never break the turn */
+  }
+}
+
+// Drop state files older than the retention window so per-session markers can't grow unbounded.
+// Best-effort, silent (mirrors the snapshot/beacon prune discipline).
+function pruneState() {
+  try {
+    const dir = hydrationDir()
+    if (!existsSync(dir)) return
+    const cutoff = Date.now() - STATE_RETENTION_DAYS * 24 * 3600 * 1000
+    for (const f of readdirSync(dir)) {
+      try {
+        if (statSync(join(dir, f)).mtimeMs < cutoff) unlinkSync(join(dir, f))
+      } catch {
+        /* ignore individual failures */
+      }
+    }
+  } catch {
+    /* ignore — never break the turn */
+  }
+}
+
+// A real opening question, not chit-chat. Cheap heuristic (length + a trivial-phrase guard); the point is
+// only to avoid burning the once-per-session hydration on "hi". Anything borderline hydrates.
+export function isSubstantive(prompt) {
+  const p = (prompt || '').trim()
+  if (p.length < MIN_SUBSTANTIVE_CHARS) return false
+  if (TRIVIAL_RE.test(p)) return false
+  return true
+}
+
+// Pure gate decision, extracted so it is unit-testable without stdin/network. Returns one of:
+//   'skip-no-session' | 'skip-done' | 'skip-attempts' | 'skip-trivial' | 'go'
+export function decideHydrate({ hasSessionId, done, attempts = 0, prompt, maxAttempts = MAX_ATTEMPTS }) {
+  if (!hasSessionId) return 'skip-no-session' // can't gate without an id → do nothing, never fire every turn
+  if (done) return 'skip-done' // the gate: hydrate exactly once per session
+  if (attempts >= maxAttempts) return 'skip-attempts' // stop retrying a dead endpoint
+  if (!isSubstantive(prompt)) return 'skip-trivial' // wait for a real query; do NOT mark done
+  return 'go'
+}
+
+// UserPromptSubmit sends a JSON payload on stdin: { session_id, prompt, cwd, ... }.
+function readHook() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+export async function runHydrate() {
+  pruneState()
+
+  const hook = readHook()
+  const sessionId = hook.session_id || process.env.CLAUDE_SESSION_ID || ''
+  const prompt = hook.prompt ?? hook.user_prompt ?? ''
+  const state = readState(sessionId)
+
+  const action = decideHydrate({
+    hasSessionId: Boolean(sessionId),
+    done: Boolean(state.done),
+    attempts: state.attempts ?? 0,
+    prompt,
+  })
+  if (action !== 'go') return 0
+
+  const token = process.env.CORTEX_TOKEN || readWiredToken()
+  if (!token) return 0 // not wired → silent no-op (don't mark done; a later session may be wired)
+  const base = resolveBase(process.env.CORTEX_URL)
+
+  const bumpAttempt = () => writeState(sessionId, { ...state, attempts: (state.attempts ?? 0) + 1 })
+
+  let res
+  try {
+    res = await fetchCortex(
+      `${base}/api/session-context`,
+      {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        // Redact credential-shaped strings before the prompt leaves the machine (a pasted key must never
+        // be transmitted, same discipline as capture).
+        body: JSON.stringify({ question: redactSecrets(prompt) }),
+        timeoutMs: HYDRATE_TIMEOUT_MS,
+      },
+      { retries: 1 },
+    )
+  } catch (e) {
+    process.stderr.write(`cortex: hydrate skipped — ${e?.message ?? String(e)}\n`)
+    bumpAttempt()
+    return 0 // fail-open: never hold the user's first message hostage to hydration
+  }
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '')
+    process.stderr.write(
+      `cortex: hydrate skipped — ${classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message}\n`,
+    )
+    bumpAttempt()
+    return 0
+  }
+
+  const { context } = await res.json().catch(() => ({}))
+  if (context && typeof context === 'string' && context.trim()) {
+    // stdout from a UserPromptSubmit hook is injected into THIS turn's context, before the model answers.
+    process.stdout.write(context.trimEnd() + '\n')
+    writeState(sessionId, { done: true, at: new Date().toISOString() })
+  } else {
+    bumpAttempt() // empty body — treat as a miss, allow one bounded retry next turn
+  }
+  return 0
+}

package/lib/server.mjs

@@ -499,7 +499,15 @@ export async function runServer(version) {
       const day = (d) => (d ? String(d).slice(0, 10) : '')
       const renderMatch = (m, tagBrain) => {
         const blocks = m.tiers.map((t) => {
-          const secs = (t.sections ?? []).map((s) => `### ${s.heading}\n${s.body}`).join('\n\n')
+          const secs = (t.sections ?? []).map((s) => {
+            // Undefined is an older-server response during a rolling deploy: do
+            // not invent a currency verdict until this server has computed one.
+            const currency = s.hasExplicitDate === false
+              ? '\n⚠ **Undated section — verify before relying on its claims.**\n'
+              : ''
+            const asOf = s.asOf ? ` · as of ${day(s.asOf)}` : ''
+            return `### ${s.heading}${asOf}${currency}${s.body}`
+          }).join('\n\n')
           // ADR-0018: a null version isn't "nothing to show" — it means this variant predates content-
           // hash tracking (a 2026-06-29 import scar) and CANNOT be re-authored via base_version until an
           // admin backfills it. Silently omitting the line here is exactly what sent callers into an
@@ -859,7 +867,7 @@ export async function runServer(version) {
     'list_records',
     {
       title: 'List activity records (filtered)',
-      description: 'List recent activity records you can see, filtered by type, project, and recency. RLS-scoped. Use to enumerate "what happened on project X this week" or "recent meetings". Returns titles + ids (use an id with story/request_file).',
+      description: 'List recent activity records you can see, filtered by type, project, and recency. RLS-scoped. Use to enumerate "what happened on project X this week" or "recent meetings". Returns each record\'s FULL summary + id — never a truncated preview, so what you get back is the whole record you are permitted to read (use an id with request_file to ask its owner for the original file).',
       inputSchema: {
         type: z.string().optional().describe("record type, e.g. 'meeting', 'comm', 'activity', 'ai_session', 'doc', 'note'"),
         project: z.string().optional().describe('project key to filter to (e.g. "cortex")'),
@@ -949,9 +957,9 @@ export async function runServer(version) {
     'set_record_privacy',
     {
       title: 'Set a record\'s privacy tier',
-      description: 'Reclassify the access tier of one of YOUR OWN records: "accessible" (anyone in the org), "scoped" (you + your management chain), or "confidential" (you + people you explicitly grant access). Get record_id from a `story` result\'s Sources list. Only affects records you own — others return an error.',
+      description: 'Reclassify the access tier of one of YOUR OWN records: "accessible" (anyone in the org), "scoped" (you + your management chain), or "confidential" (you + people you explicitly grant access). Get record_id from a `list_records` result or the "id:" on a `my_context` activity line. Only affects records you own — others return an error.',
       inputSchema: {
-        record_id: z.string().describe('the record id (uuid), taken from a story result source'),
+        record_id: z.string().describe('the record id (uuid), e.g. the "id:" on a list_records line'),
         privacy: z.enum(['accessible', 'scoped', 'confidential']).describe('the new access tier'),
       },
     },
@@ -1255,7 +1263,7 @@ export async function runServer(version) {
     'request_file',
     {
       title: 'Request the full original of a record',
-      description: 'You have a record\'s SUMMARY but want the full original file (it lives on the owner\'s machine). This asks the owner to share it; once they approve, fetch it with get_file. Get record_id from a story Sources list or the "id:" on a my_context activity line.',
+      description: 'You have a record\'s SUMMARY but want the full original file (it lives on the owner\'s machine). This asks the owner to share it; once they approve, fetch it with get_file. Get record_id from a `list_records` result or the "id:" on a `my_context` activity line.',
       inputSchema: { record_id: z.string().describe('the record id (uuid)') },
     },
     async ({ record_id }) => {
@@ -1375,7 +1383,7 @@ export async function runServer(version) {
     {
       title: 'Authoring context (call before author)',
       description:
-        'Fetch the scaffolding to author a Cortex wiki node: the canonical NAMESPACE (existing node names — link to these with the EXACT name inside [[ ]]) and the node-type CONNECTION RULES (what kinds of links to look for). ALWAYS call this BEFORE `author` so the page links to real nodes by their established names instead of minting synonyms. Reference a node in the namespace as [[Name]]; if you reference something real that is NOT in the namespace, still write [[Name]] — that is a red-link marking a node worth creating. If the page IS about a specific code repo or chat channel, also stamp it once — [[repo:owner/name]] or [[channel:name]] (lowercase, no #) — identifier join keys, not page links.',
+        'Fetch the scaffolding to author a Cortex wiki node: the canonical NAMESPACE (current node names — link to these with the EXACT name inside [[ ]]), any deliberately RETIRED page names and their successors, and the node-type CONNECTION RULES. ALWAYS call this BEFORE `author` so the page links to current knowledge rather than minting synonyms or reviving a retired page. Reference a node in the namespace as [[Name]]; if you reference something real that is NOT in the namespace, still write [[Name]] — that is a red-link marking a node worth creating. If the page IS about a specific code repo or chat channel, also stamp it once — [[repo:owner/name]] or [[channel:name]] (lowercase, no #) — identifier join keys, not page links.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).optional().describe('the node type you are about to author (default project)'),
       },
@@ -1392,12 +1400,17 @@ export async function runServer(version) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
         return { content: [{ type: 'text', text: `Could not fetch authoring context: ${d.message}` }] }
       }
-      const { connectionRules, namespace } = await res.json()
+      const { connectionRules, namespace, retiredLinks } = await res.json()
       const ns = Array.isArray(namespace) ? namespace : []
       const nsList = ns.map((n) => `[[${n}]]`).join(', ')
+      const retired = Array.isArray(retiredLinks) ? retiredLinks : []
+      const retiredList = retired.length
+        ? `\n\nRETIRED PAGES — do not treat these as current or author over them: ${retired.map((r) => `[[${r.name}]] (${r.validity}${r.supersededBy ? ` → [[${r.supersededBy}]]` : ''})`).join(', ')}`
+        : ''
       const text =
         `Authoring a "${k}" node. Connection rules (kinds of links to look for):\n${connectionRules}\n\n` +
         `NAMESPACE — ${ns.length} existing nodes; link with the EXACT name inside [[ ]]:\n${nsList}\n\n` +
+        retiredList +
         `Now author the page (summary + sections) with inline [[links]] woven into the prose. Link, do not restate. ` +
         `For something real that is not in this namespace, still write [[Name]] (a red-link). Then call \`author\`.`
       return { content: [{ type: 'text', text }] }
@@ -1444,11 +1457,13 @@ export async function runServer(version) {
       }
       const out = await res.json()
       const blue = out?.links?.blue ?? 0
+      const retired = out?.links?.retired ?? 0
       const red = out?.links?.red ?? 0
       const redList = Array.isArray(out?.redLinks) && out.redLinks.length ? `\nRed-links (wanted nodes): ${out.redLinks.map((r) => `[[${r}]]`).join(', ')}` : ''
+      const retiredList = Array.isArray(out?.retiredLinks) && out.retiredLinks.length ? `\nRetired links (not current or wanted): ${out.retiredLinks.map((r) => `[[${r}]]`).join(', ')}` : ''
       const stamps = Array.isArray(out?.identifiers) && out.identifiers.length ? `\nIdentifier stamps (join keys): ${out.identifiers.map((i) => `[[${i}]]`).join(', ')}` : ''
       const verb = out?.created ? 'Created + authored' : 'Authored'
-      const note = out?.built ? `${verb} "${name}" (${out.built} tier${out.built === 1 ? '' : 's'}). Links: ${blue} resolved, ${red} red.${redList}${stamps}`
+      const note = out?.built ? `${verb} "${name}" (${out.built} tier${out.built === 1 ? '' : 's'}). Links: ${blue} resolved, ${retired} retired, ${red} red.${retiredList}${redList}${stamps}`
         : `No change to "${name}"${out?.skipped?.length ? ` (${out.skipped.join(', ')})` : ''}.`
       return { content: [{ type: 'text', text: note }] }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.54",
+  "version": "0.9.56",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {