@theronap/cortex-mcp 0.9.55 → 0.9.57

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/capture.mjs

@@ -1,5 +1,5 @@
 import { readFileSync } from 'fs'
-import { spawn } from 'child_process'
+import { spawn, execFileSync } from 'child_process'
 import { homedir } from 'os'
 import { resolve, dirname, join } from 'path'
 import { fileURLToPath } from 'url'
@@ -37,6 +37,45 @@ export function projectFrom(cwd) {
 
 // Claude Code Stop hook → POSTs a session digest to Cortex cloud, which
 // summarizes server-side and upserts ONE record per session. Node-native
+// SHR-01/T6 — parse a git remote URL into GitHub 'owner/name', or null.
+//
+// Handles the four remote forms git emits: scp-like ssh (git@github.com:o/n.git), ssh://, https://,
+// git://. The HOST CHECK IS LOAD-BEARING, not cosmetic: this string becomes a clearance key, and
+// 'owner/name' on gitlab.com or a self-hosted forge would collide in the identifier namespace with an
+// unrelated GitHub repo of the same name — granting its members read access to each other's sessions.
+export function githubFullName(url) {
+  if (!url) return null
+  const m = String(url).trim()
+    .match(/^(?:git\+)?(?:https?:\/\/|ssh:\/\/|git:\/\/)?(?:[^@/]+@)?github\.com[:/]+([^/]+)\/(.+?)(?:\.git)?\/?$/i)
+  if (!m) return null
+  const owner = m[1].toLowerCase()
+  const name = m[2].toLowerCase()
+  if (!owner || !name || name.includes('/')) return null
+  return `${owner}/${name}`
+}
+
+// SHR-01/T6 — the repo this session is working in, as 'owner/name', or null.
+//
+// D2, FAIL CLOSED: anything that is not unambiguously a GitHub worktree — no repo, no origin remote,
+// a non-GitHub host, git not installed — returns null, and the session is then stamped with NO
+// identifier and stays private. There is deliberately no fallback: a brain-level or hostname-level
+// identifier would be held by every member of the org, so overlap would ALWAYS succeed. That is an
+// accidental org-wide grant, i.e. the default-tier flip that was explicitly declined.
+//
+// `git config --get` is local and does no network I/O. Bounded and swallowed regardless: capture must
+// never break a session, and a missing identifier is a private session, not a broken one.
+export function repoFullNameFrom(cwd) {
+  if (!cwd) return null
+  try {
+    const url = execFileSync('git', ['-C', String(cwd), 'config', '--get', 'remote.origin.url'], {
+      encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return githubFullName(url)
+  } catch {
+    return null
+  }
+}
+
 // (no bun, no repo clone). Always exits 0 — capture must never break a session.
 
 function readStdin() {
@@ -159,6 +198,10 @@ async function captureWork(stdinRaw) {
   // summarizer (which has been the silent point of failure). Fall back to shipping the transcript
   // tail only if local extraction is unavailable (e.g. `claude` not on PATH) so we never drop a
   // session. The server re-validates people/entities — the edge is not trusted.
+  // SHR-01/T6: the repo identifier is what lets a PEER read this session (see 0096). Omitted entirely
+  // when the cwd is not a GitHub worktree — the record still lands, it just stays private (D2).
+  const repoFullName = repoFullNameFrom(hook.cwd)
+
   const common = {
     source: 'claude-code',
     project: repo,
@@ -166,6 +209,7 @@ async function captureWork(stdinRaw) {
     title: `Worked in ${repo}`,
     payload: { session_id: hook.session_id, cwd: hook.cwd },
     captureSource: 'hook', // T8: fallback writer — never clobbers a cortex-log ('skill') record
+    ...(repoFullName ? { repoFullName } : {}),
     ...(hydratedFrom.length ? { hydratedFrom } : {}),
   }
   const extracted = transcript ? extractSession(transcript) : null

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

@@ -867,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")'),
@@ -957,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'),
       },
     },
@@ -1263,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 }) => {

package/package.json

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