@theronap/cortex-mcp 0.9.49 → 0.9.51

package/lib/diagnose.mjs

@@ -69,7 +69,19 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 export function classify(status, contentType, bodyText, requestId) {
   const isJson = (contentType ?? '').includes('application/json')
   let appError = null
-  if (isJson) { try { appError = JSON.parse(bodyText)?.error ?? null } catch { /* not json after all */ } }
+  let appHint = null
+  if (isJson) {
+    try {
+      const parsed = JSON.parse(bodyText)
+      appError = parsed?.error ?? null
+      // `hint` carries the RECOVERY instruction for the errors an agent is meant to act on, not
+      // just report: 409 would_drop ("re-author including the dropped sections…") and 413 too_large
+      // ("split the section…"). It used to be dropped here — only `error` survived — so the agent
+      // saw a bare code like "would_drop_sections" and had no idea what to do with it. The routes
+      // were writing careful self-heal guidance that never reached anyone.
+      appHint = typeof parsed?.hint === 'string' && parsed.hint.trim() ? parsed.hint.trim() : null
+    } catch { /* not json after all */ }
+  }
   const rid = requestId ? ` [request id: ${requestId}]` : ''
 
   if (status === 401 || (isJson && appError === 'invalid token')) {
@@ -90,7 +102,7 @@ export function classify(status, contentType, bodyText, requestId) {
   }
   return {
     kind: 'app', retriable: status >= 500,
-    message: `Cortex API ${status}: ${appError ?? 'unknown error'}.${rid}`,
+    message: `Cortex API ${status}: ${appError ?? 'unknown error'}.${appHint ? ` ${appHint}` : ''}${rid}`,
   }
 }
 
@@ -104,8 +116,22 @@ export function classify(status, contentType, bodyText, requestId) {
 // WORSE — 3 unbounded attempts stacked. Now worst case = (retries+1) * timeoutMs + backoff, and a
 // timed-out attempt is treated as transient (retried, then surfaced as the reach error the callers
 // already swallow). Tunable via CORTEX_HTTP_TIMEOUT_MS; per-call override via opts.timeoutMs.
+// ADR-0020 Stage 2 — this process's session identity, stamped on every request so the server can
+// resolve THIS session's write pointer instead of the person-wide one. Set once by the MCP server at
+// startup (setSessionKey); left null in the one-shot hook processes (capture, context_log), which
+// have no session of their own and correctly fall back to the account pointer.
+//
+// Injected HERE rather than at each call site because fetchCortex is the single chokepoint every
+// caller already funnels through — ~30 call sites pass their own `headers` object, and a header this
+// load-bearing must not depend on remembering it at each one.
+let SESSION_KEY = null
+export function setSessionKey(key) { SESSION_KEY = key || null }
+
 export async function fetchCortex(url, opts = {}, { retries = 2, baseDelayMs = 400 } = {}) {
-  const { timeoutMs: optTimeout, signal: callerSignal, ...fetchOpts } = opts
+  const { timeoutMs: optTimeout, signal: callerSignal, ...rest } = opts
+  const fetchOpts = SESSION_KEY
+    ? { ...rest, headers: { ...(rest.headers ?? {}), 'x-cortex-session-key': SESSION_KEY } }
+    : rest
   const timeoutMs = optTimeout ?? (Number(process.env.CORTEX_HTTP_TIMEOUT_MS) || 15_000)
   let lastErr
   for (let attempt = 0; attempt <= retries; attempt++) {

package/lib/server.mjs

@@ -5,7 +5,7 @@ import { writeFileSync, mkdirSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { createHash, randomUUID } from 'crypto'
-import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
+import { fetchCortex, classify, resolveBase, setSessionKey } from './diagnose.mjs'
 import { runSendImessage } from './imessage_send.mjs'
 import { formatGrepHits } from './grep_cli.mjs'
 import { renderTriage } from './red_link_triage.mjs'
@@ -43,6 +43,10 @@ export async function runServer(version) {
   // working dir identify this session; we heartbeat /api/session-ping while alive so the user can see
   // all THEIR sessions via my_sessions. Self-only on the server; best-effort (never breaks serving).
   const SESSION_KEY = randomUUID()
+  // ADR-0020 Stage 2: stamp this key on every outbound request (fetchCortex injects it) so writes
+  // resolve THIS session's brain pointer. Must be set BEFORE the first fetchCortex call below —
+  // otherwise the opening requests of a session would silently resolve by the account pointer.
+  setSessionKey(SESSION_KEY)
   async function pingSession() {
     try {
       await fetchCortex(`${BASE}/api/session-ping`, {
@@ -646,28 +650,83 @@ 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 list brains: ${d.message}` }] }
       }
-      const { brains, activeIsExplicit } = await res.json()
+      const { brains, activeIsExplicit, activeSource, sessionOrgId, accountOrgId } = await res.json()
       if (!brains?.length) return { content: [{ type: 'text', text: 'You have no brains.' }] }
-      const lines = brains.map((b) => `${b.isActive ? '▶' : ' '} ${b.name}  (${b.role}${b.status !== 'active' ? `, ${b.status}` : ''})  [${b.orgId}]`)
-      const note = activeIsExplicit ? '' : '\n(active brain is the default — you have one brain; set_active_brain once you hold more.)'
+      // Show CONTENTS, not just the name (ADR-0020 §7 corollary): a brain named TTO that holds 4
+      // pages while the real TTO inventory sits in Personal reads as correct and is exactly
+      // backwards. The page count and a couple of titles make that visible at the moment of choosing.
+      const lines = brains.map((b) => {
+        const inv = b.pageCount === 0
+          ? 'EMPTY'
+          : `${b.pageCount} page${b.pageCount === 1 ? '' : 's'}${b.sampleTitles?.length ? `: ${b.sampleTitles.slice(0, 2).join(', ')}` : ''}`
+        return `${b.isActive ? '▶' : ' '} ${b.name}  (${b.role}${b.status !== 'active' ? `, ${b.status}` : ''})  — ${inv}  [${b.orgId}]`
+      })
+      // Which layer is deciding, and what clearing it would fall back to — otherwise the pointer
+      // confusion simply reappears one level down.
+      const note = !activeIsExplicit
+        ? '\n(active brain is the default — you have one brain; set_active_brain once you hold more.)'
+        : activeSource === 'session'
+          ? `\n(this SESSION's override — your other sessions are unaffected${accountOrgId && accountOrgId !== sessionOrgId ? `; clearing it falls back to ${accountOrgId}` : ''}.)`
+          : activeSource === 'account'
+            ? '\n(account-wide pointer — shared by every session that has not set its own.)'
+            : ''
       return { content: [{ type: 'text', text: `Your brains (▶ = writes land here):\n${lines.join('\n')}${note}` }] }
     },
   )
 
+  server.registerTool(
+    'list_brain_pages',
+    {
+      title: 'List every authored page in one brain',
+      description: 'Enumerate ALL authored pages in ONE brain, by its org id (from my_brains). Unlike my_brains — which ships only a count plus a few sample titles — this returns the FULL page list: one row per node with its kind, validity, tier(s), last-updated date and content hash. Use it to audit a brain, or to VERIFY a brain-to-brain migration — list BOTH brains, diff the page sets, and compare freshness before retiring any original. You can only list a brain you are a member of; reads never widen past your own brains.',
+      inputSchema: {
+        org_id: z.string().describe('the org id of the brain to enumerate (from my_brains)'),
+      },
+    },
+    async ({ org_id }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brains/pages?orgId=${encodeURIComponent(org_id)}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not list pages: ${e.message}` }] }
+      }
+      if (!res.ok) {
+        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 list pages: ${d.message}` }] }
+      }
+      const { nodeCount, rowCount, pages } = await res.json()
+      if (!pages?.length) return { content: [{ type: 'text', text: `Brain ${org_id} has no authored pages.` }] }
+      // One terse line per node: name ·kind· date [NON-CURRENT validity] {non-default tiers}. A migration
+      // diff needs the name, the freshness date, and whether a page is already retired or multi-tier.
+      const lines = pages.map((p) => {
+        const flag = p.validity && p.validity !== 'current' ? ` [${String(p.validity).toUpperCase()}]` : ''
+        const tiers = p.tiers?.length && !(p.tiers.length === 1 && p.tiers[0] === 'accessible') ? ` {${p.tiers.join('+')}}` : ''
+        const day = p.updatedAt ? String(p.updatedAt).slice(0, 10) : '????-??-??'
+        return `${p.name ?? '(unnamed)'}  ·${p.kind}·  ${day}${flag}${tiers}`
+      })
+      const header = `${nodeCount} page${nodeCount === 1 ? '' : 's'} in brain ${org_id} (${rowCount} digest rows across tiers):`
+      return { content: [{ type: 'text', text: `${header}\n${lines.join('\n')}` }] }
+    },
+  )
+
   server.registerTool(
     'set_active_brain',
     {
       title: 'Choose the brain your writes go to',
-      description: 'Point your writes (author / log_session / capture) at one of your brains, by its org id (from my_brains). Sticky — it stays until you change it. Pass org_id = null to clear it and fall back to the default. You can only select a brain you are a member of.',
-      inputSchema: { org_id: z.string().nullable().describe('the org id of the brain to write to (from my_brains), or null to clear the pointer') },
+      description: "Point your writes (author / log_session / capture) at one of your brains, by its org id (from my_brains). Pass org_id = null to clear it. You can only select a brain you are a member of. SCOPE: 'session' (default) changes ONLY this session — other windows you have open keep writing where they were, which is almost always what you want. 'account' changes the sticky person-wide pointer, which redirects every other session that has not set its own.",
+      inputSchema: {
+        org_id: z.string().nullable().describe('the org id of the brain to write to (from my_brains), or null to clear the pointer'),
+        scope: z.enum(['session', 'account']).optional()
+          .describe("'session' (default) = this window only; 'account' = person-wide, affects your other open sessions too"),
+      },
     },
-    async ({ org_id }) => {
+    async ({ org_id, scope }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/brains`, {
           method: 'PUT',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ orgId: org_id ?? null }),
+          body: JSON.stringify({ orgId: org_id ?? null, scope: scope ?? 'session' }),
         })
       } catch (e) {
         return { content: [{ type: 'text', text: `Could not set active brain: ${e.message}` }] }
@@ -677,7 +736,15 @@ export async function runServer(version) {
         return { content: [{ type: 'text', text: `Could not set active brain: ${d.message}` }] }
       }
       const r = await res.json()
-      return { content: [{ type: 'text', text: r.activeOrgId ? `Writes now land in brain ${r.activeOrgId}.` : 'Cleared your active-brain pointer (writes fall back to your default brain).' }] }
+      // Always say WHICH scope changed. The default is session-only, so a caller expecting the old
+      // person-wide stickiness must be able to see that it did NOT change their other windows.
+      const where = r.scope === 'session' ? 'this session only' : 'ALL your sessions (person-wide)'
+      if (!r.activeOrgId) {
+        return { content: [{ type: 'text', text: r.scope === 'session'
+          ? 'Cleared this session\'s brain override — writes fall back to your account pointer.'
+          : 'Cleared your account-wide active-brain pointer (writes fall back to your default brain).' }] }
+      }
+      return { content: [{ type: 'text', text: `Writes now land in brain ${r.activeOrgId} — ${where}.` }] }
     },
   )
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.49",
+  "version": "0.9.51",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
     "bin",
     "lib",
     "skills",
-    "!lib/**/*.test.mjs"
+    "!lib/**/*.test.mjs",
+    "!scripts"
   ],
   "engines": {
     "node": ">=18"
@@ -26,5 +27,10 @@
     "ai",
     "org-intelligence"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "scripts": {
+    "release": "node scripts/release.mjs release",
+    "promote": "node scripts/release.mjs promote",
+    "rollback": "node scripts/release.mjs rollback"
+  }
 }