@theronap/cortex-mcp 0.9.66 → 0.9.68

package/lib/server.mjs

@@ -59,7 +59,7 @@ export async function runServer(version) {
   // PGL-21 fix: "one MCP process = one AI session" is an assumption, not a guarantee — the HOST
   // (Claude Code) can restart this stdio process mid-conversation (reconnects, tool-loading events),
   // and a fresh randomUUID() on every restart silently orphaned the PRIOR process's session-scoped
-  // write-pointer row (session_write_pointers): an explicit set_active_brain(scope:'session') would
+  // ADR-0022 deleted the write pointer, so a session no longer carries a brain of its own.
   // stop taking effect one restart later, falling back to the account pointer with no visible cause
   // — reproduced live 2026-07-27. Claude Code sets CLAUDE_CODE_SESSION_ID for the lifetime of one
   // logical conversation across any number of subprocess restarts, so prefer it as the session key;
@@ -556,7 +556,7 @@ export async function runServer(version) {
         // retype silently deleted a sentence, a [[link]] (a graph edge), a command list and the
         // word "today" from sections it was never meant to touch. This footer renders on EVERY
         // page read in the system, so it was the single widest surface pointing the wrong way.
-        let footer = `— Follow any [[links]] above with read_page to go deeper.\n— If you hold fresher FIRST-HAND truth than this page — something you established THIS session (ran the command, made the change, hold the artifact) that a section here gets concretely wrong — fix just that passage with \`edit_page\`: quote the wrong text as old_string and pass this page's \`version\` as base_version (any node you are permitted to edit; concise; a material contradiction, not merely extra detail). If the save comes back stale the page changed under you — the conflict hands back what changed, so re-anchor from that instead of re-reading. Reading a stale page you can fix IS the trigger to fix it. Editing is pre-authorized — do NOT ask the user before updating (edits are versioned + reversible via page_history/rollback_page); update, then briefly report it. Use \`author\` only to CREATE a page or rewrite one wholesale: it re-emits every section, so untouched sections get retyped on the way through and drift.\n— Citing code? Use a SYMBOL and file (\`formConnections\` in \`web/app/api/ingest/route.ts\`), never a line number — line numbers drift with every commit above them. And cite only what you opened THIS session; re-emitting a reference you read on another page is how a stale claim gains a second source and starts looking corroborated.`
+        let footer = `— Follow any [[links]] above with read_page to go deeper.\n— If you hold fresher FIRST-HAND truth than this page — something you established THIS session (ran the command, made the change, hold the artifact) that a section here gets concretely wrong — fix just that passage with \`edit_page\`: quote the wrong text as old_string and pass this page's \`version\` as base_version (any node you are permitted to edit; concise; a material contradiction, not merely extra detail). If the save comes back stale the page changed under you — the conflict hands back what changed, so re-anchor from that instead of re-reading. Reading a stale page you can fix IS the trigger to fix it. Editing is pre-authorized — do NOT ask the user before updating (edits are versioned + reversible via page_history/rollback_page); update, then briefly report it. If what went false is the SUMMARY at the top rather than a section, use \`set_summary\` — \`edit_page\` cannot reach it, and worse, it carries the old summary FORWARD into every revision it writes, so fixing a section silently re-certifies a summary that already contradicts it. Use \`author\` only to CREATE a page or rewrite one wholesale: it re-emits every section, so untouched sections get retyped on the way through and drift.\n— Citing code? Use a SYMBOL and file (\`formConnections\` in \`web/app/api/ingest/route.ts\`), never a line number — line numbers drift with every commit above them. And cite only what you opened THIS session; re-emitting a reference you read on another page is how a stale claim gains a second source and starts looking corroborated.`
         // ADDRESSING (2026-08-04). The server accepts `ref` on every page/node route and its ambiguity
         // 409s hand refs back — but read_page never PRINTED one, so the only way to obtain a ref was to
         // trigger the error first. That made ID addressing reachable in principle and unusable in
@@ -770,6 +770,49 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'set_summary',
+    {
+      title: 'Rewrite a wiki page summary without touching its sections',
+      description: 'Replace a page\'s SUMMARY — the one-sentence line at the top — in place, leaving every section untouched. Use this the moment you notice a summary that no longer matches the page: `edit_page` structurally CANNOT reach it (it edits section bodies; the summary is not one), and `author` reaches it only by retyping every section on the way through, which is how a 2026-07-30 write silently deleted a sentence and a [[link]] from a section nobody meant to touch. Correcting a body with `edit_page` actively carries the OLD summary forward into the new revision, so a stale summary does not decay quietly — each unrelated fix re-certifies it. Fixing it matters more than it looks: page retrieval FTS-matches on title + summary ALONE (section bodies are not in that index) and session context prints the summary as "Why this was chosen", so a stale summary decides whether the page is found at all and what a future session believes before it reads a word. Requires base_version (the `version` read_page prints) — that is also how it finds the right brain, so it can never write to the wrong one. Recorded in page_history as a correction, and reversible with rollback_page.',
+      inputSchema: {
+        name: z.string().describe('the exact page name, as read_page shows it'),
+        summary: z.string().describe('the new summary: one sentence saying what this is and where it stands. May contain [[links]]. Max 2,000 chars — detail belongs in a section.'),
+        base_version: z.string().describe('the `version` read_page prints for this page (64-hex). REQUIRED — it is the concurrency check AND how the right brain is resolved. A per-SECTION hash is not valid here.'),
+        reason: z.string().optional().describe('WHY the summary was wrong, in one short phrase — recorded in page_history. Say what changed ("blocker resolved 08-04; was still claiming BLOCKED"), not what you did.'),
+        tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('only when the page exists at MORE THAN ONE tier — which one to rewrite. This never moves content between tiers.'),
+      },
+    },
+    async ({ name, summary, base_version, reason, tier }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/set-summary`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            name, summary, base_version,
+            ...(tier ? { tier } : {}), ...(reason ? { reason } : {}),
+          }),
+        })
+      } catch (e) {
+        return toolError(`Could not set the summary: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        // Surface the server's hint AND the disambiguators it named, so a 409 is directly actionable
+        // rather than something to retry blindly.
+        const extra = [
+          out?.detail ? `detail: ${out.detail}` : '',
+          Array.isArray(out?.tiers) ? `tiers: ${out.tiers.join(', ')}` : '',
+          out?.currentVersion ? `current version: ${out.currentVersion}` : '',
+        ].filter(Boolean).join(' · ')
+        const hint = out?.hint ? `\n${out.hint}` : ''
+        return toolError(`Could not set the summary on "${name}": ${out?.error ?? res.status}${extra ? `\n${extra}` : ''}${hint}`)
+      }
+      return { content: [{ type: 'text', text: `Summary rewritten on "${name}" (${out.brain} · ${out.tier} tier). Every section kept its body, position and as-of date.\nwas: ${out.previousSummary}\nnow: ${out.summary}\nNew version: ${out.version}` }] }
+    },
+  )
+
   server.registerTool(
     'edit_page',
     {
@@ -1126,50 +1169,11 @@ export async function runServer(version) {
     },
   )
 
-  server.registerTool(
-    'set_active_brain',
-    {
-      title: 'Set the default brain for NEW pages',
-      description: "RARELY NEEDED — do not reach for this reflexively. Editing an EXISTING page routes itself: author/set_page_validity/rollback resolve the brain from the page (via base_version, ref, or name), so switching first is unnecessary and switching WRONG is now impossible to cause. This only sets the default for creating a page that exists in NO brain yet, and for log_session/capture. If you find yourself about to call this so an edit lands correctly, don't — just author; it will find the page. Pass org_id = null to clear. SCOPE: 'session' (default) changes ONLY this session; 'account' changes the person-wide pointer and redirects every other open 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, 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, scope: scope ?? 'session' }),
-        })
-      } catch (e) {
-        return toolError(`Could not set active brain: ${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 toolError(`Could not set active brain: ${d.message}`)
-      }
-      const r = await res.json()
-      // 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}.` }] }
-    },
-  )
-
   server.registerTool(
     'create_brain',
     {
       title: 'Create a new brain under your existing account',
-      description: 'Create a brand-new brain (org/workspace) — a fully independent knowledge graph — under your EXISTING account. No new login, no new email/password: this adds a second membership to the account you are already using. Reads never cross brains; new pages default to your active brain, so use set_active_brain if you want NEW pages to land in this one; edits to existing pages always route to whichever brain holds them.',
+      description: 'Create a brand-new brain (org/workspace) — a fully independent knowledge graph — under your EXISTING account. No new login, no new email/password: this adds a second membership to the account you are already using. Reads never cross brains; new pages default to your active brain, so use pass `brain` when an operation needs one named',
       inputSchema: { name: z.string().describe('display name for the new brain, e.g. "Cortex Codebase"') },
     },
     async ({ name }) => {
@@ -1188,7 +1192,7 @@ export async function runServer(version) {
         return toolError(`Could not create brain: ${d.message}`)
       }
       const r = await res.json()
-      return { content: [{ type: 'text', text: `Created brain "${name}" [${r.orgId}]. Reads already span it. Edits to pages in it route themselves; set_active_brain only if you want NEW pages to default here.` }] }
+      return { content: [{ type: 'text', text: `Created brain "${name}" [${r.orgId}]. Reads already span it. Edits to pages in it route themselves from the page, so nothing needs pointing at it; pass brain="${name}" on an operation that creates something new here.` }] }
     },
   )
 
@@ -1398,7 +1402,10 @@ export async function runServer(version) {
       const out = await res.json().catch(() => null)
       if (!res.ok) return toolError(`Could not snooze "${name}": ${out?.error ?? res.status}`)
       if (!out) return { content: [{ type: 'text', text: `Snoozed "${name}", but the server returned no body.` }] }
-      return { content: [{ type: 'text', text: `Snoozed "${out.name}" for ${out.days} day${out.days === 1 ? '' : 's'} — it won't surface until then.` }] }
+      // Name the brains when there is more than one: a snooze that quieted the same wanted name in two
+      // brains you steward is a multi-row write, and reporting it as a single one hides that.
+      const where = out.brains?.length > 1 ? ` in ${out.brains.map((b) => b.brain).join(' and ')}` : ''
+      return { content: [{ type: 'text', text: `Snoozed "${out.name}"${where} for ${out.days} day${out.days === 1 ? '' : 's'} — it won't surface until then.` }] }
     },
   )
 
@@ -1719,13 +1726,14 @@ export async function runServer(version) {
         '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)'),
+        brain: z.string().optional().describe('which brain\'s namespace to describe — pass the SAME brain you will pass to `author`, so the namespace you plan against is the one your write lands in. Unnecessary when you only have one brain.'),
       },
     },
-    async ({ kind }) => {
+    async ({ kind, brain }) => {
       const k = kind ?? 'project'
       let res
       try {
-        res = await fetchCortex(`${BASE}/api/brain/authoring-context?kind=${k}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+        res = await fetchCortex(`${BASE}/api/brain/authoring-context?kind=${k}${brain ? `&brain=${encodeURIComponent(brain)}` : ''}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       } catch (e) {
         return toolError(`Could not fetch authoring context: ${e.message}`)
       }
@@ -1755,7 +1763,7 @@ export async function runServer(version) {
     {
       title: 'Author a wiki node (live, while it is hot)',
       description:
-        'Write your CURRENT understanding of a project/person/org/you into the org wiki as a maintained page. Call `authoring_context` FIRST. Author from your own synthesis of the session — the compiled mental model, not a transcript dump: what it IS, where it stands, dated decisions, open threads, key people. Weave inline [[links]] to other nodes (canonical names from the namespace; red-links for wanted-but-absent nodes). The server re-authorizes the tier and resolves links. CREATES the node if it does not exist yet (project/person/org) — the conversation IS the evidence, so a brand-new entity that surfaced only in this session is authorable on the spot; you do NOT need prior records. Because such a node has nothing external to corroborate it, author it DELIBERATELY: only when you genuinely understand it is a real, distinct entity, and use its exact canonical name so it does not duplicate one already in the namespace (`user` nodes are never created). Use this continuously whenever your understanding of a node meaningfully advanced, and at session end (/log). Authoring is PRE-AUTHORIZED — never ask the user "should I update the page?" before calling this (every edit is versioned + reversible via page_history/rollback_page); update, then briefly report what you updated. ⚠ WHICH BRAIN A NEW PAGE GOES IN IS A CONTENT DECISION, SO MAKE IT FROM THE CONTENT. Only a page that exists in NO brain needs this — an update resolves its brain from the page itself. If you hold more than one brain, call `my_brains` (it returns each brain\'s name, page count and sample titles, which is enough to tell what each one is FOR) and pass `brain` explicitly rather than letting the write pointer decide; the pointer is stale out-of-band state that knows nothing about what you are writing. State which brain you picked and why in one short line, then proceed — do NOT ask when the answer is obvious from the content. DO ask when it is genuinely ambiguous: brains are a confidentiality boundary, so a page born in the wrong one can expose private work to a teammate, and that is not a filing error you can quietly fix later.',
+        'Write your CURRENT understanding of a project/person/org/you into the org wiki as a maintained page. Call `authoring_context` FIRST. Author from your own synthesis of the session — the compiled mental model, not a transcript dump: what it IS, where it stands, dated decisions, open threads, key people. Weave inline [[links]] to other nodes (canonical names from the namespace; red-links for wanted-but-absent nodes). The server re-authorizes the tier and resolves links. CREATES the node if it does not exist yet (project/person/org) — the conversation IS the evidence, so a brand-new entity that surfaced only in this session is authorable on the spot; you do NOT need prior records. Because such a node has nothing external to corroborate it, author it DELIBERATELY: only when you genuinely understand it is a real, distinct entity, and use its exact canonical name so it does not duplicate one already in the namespace (`user` nodes are never created). Use this continuously whenever your understanding of a node meaningfully advanced, and at session end (/log). Authoring is PRE-AUTHORIZED — never ask the user "should I update the page?" before calling this (every edit is versioned + reversible via page_history/rollback_page); update, then briefly report what you updated. ⚠ WHICH BRAIN A NEW PAGE GOES IN IS A CONTENT DECISION, SO MAKE IT FROM THE CONTENT. Only a page that exists in NO brain needs this — an update resolves its brain from the page itself. If you hold more than one brain, the server REFUSES a create it cannot attribute (409 `create_needs_brain`) rather than letting the write pointer decide — the pointer is stale out-of-band state that knows nothing about what you are writing. So call `my_brains` (it returns each brain\'s name, page count and sample titles, which is enough to tell what each one is FOR) and pass `brain` up front; that turns a refused round trip into a single call. State which brain you picked and why in one short line, then proceed — do NOT ask when the answer is obvious from the content. DO ask when it is genuinely ambiguous: brains are a confidentiality boundary, so a page born in the wrong one can expose private work to a teammate, and that is not a filing error you can quietly fix later.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the node type'),
         name: z.string().describe('the canonical node name — an EXACT existing name from the namespace to update it, or a new name to create the node (project/person/org). e.g. "Cortex" or "Theron Peterson"'),
@@ -1789,7 +1797,28 @@ export async function runServer(version) {
         return toolError(`Could not author "${name}": ${e.message}`)
       }
       if (!res.ok) {
-        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+        // Read the body ONCE — classify() consumes it as text, so parsing after it is a spent stream.
+        const raw = await res.text()
+        let err = null
+        try { err = JSON.parse(raw) } catch { /* not JSON; classify handles it below */ }
+        // BRAIN-RESOLUTION REFUSALS carry the only thing that makes them actionable: which brains, and
+        // what is in each. classify() flattens a response to a generic status message, so routing these
+        // through it would drop the payload and leave the agent to guess a brain — the exact guess the
+        // 409 exists to prevent. Page counts and sample titles matter more than the names: per
+        // brain_identity.ts a brain's NAME is actively misleading about its contents.
+        if (err?.error === 'create_needs_brain' || err?.error === 'ambiguous_brain' || err?.error === 'unknown_brain') {
+          const list = (err.brains ?? []).map((b) => {
+            const count = b.pageCount != null ? ` — ${b.pageCount} page${b.pageCount === 1 ? '' : 's'}` : ''
+            const sample = b.sampleTitles?.length ? `: ${b.sampleTitles.slice(0, 4).join(', ')}` : ''
+            return `  • ${b.name ?? b.brain} (${b.orgId})${count}${sample}`
+          }).join('\n')
+          return toolError(
+            `Could not author "${name}": ${err.message ?? err.error}` +
+            (list ? `\n\nYour brains:\n${list}` : '') +
+            `\n\nRe-run author with brain:"<name>" — choose by what each brain HOLDS, not by its name.`,
+          )
+        }
+        const d = classify(res.status, res.headers.get('content-type'), raw, res.headers.get('x-vercel-id'))
         return toolError(`Could not author "${name}": ${d.message}`)
       }
       const out = await res.json()

package/package.json

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