@theronap/cortex-mcp 0.9.132 → 0.9.134

package/lib/server.mjs

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod'
-import { writeFileSync, mkdirSync } from 'fs'
+import { writeFileSync, mkdirSync, readFileSync, statSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { createHash, randomUUID } from 'crypto'
@@ -927,8 +927,13 @@ function renderNudge(payload) {
       //   attached: [...] filed under N pages
       //
       // Reporting only a count would make the first indistinguishable from the second, which is how
-      // a broken write hides inside a normal-looking result. `undefined` means the server has not
-      // shipped this field yet, so nothing is said rather than something wrong.
+      // a broken write hides inside a normal-looking result.
+      //
+      // ⚠ AND `undefined` IS A FOURTH STATE: NOT ATTEMPTED. Session-page attachment only runs for
+      // claude-code sources — a handoff, an email, a calendar event has no session to join on. The
+      // server used to send null in that case, having never tried, and this reported a FAILURE for
+      // the ordinary case (observed 2026-09-03 on the first handoff record materialised). Silence is
+      // correct here, and it also covers a server too old to send the field at all.
       const lines = []
       const sa = body?.sessionAttachments
       if (sa === null) {
@@ -943,6 +948,19 @@ function renderNudge(payload) {
           lines.push(`${sa.droppedCrossBrain} page(s) this session wrote live in another brain and were skipped — a record belongs to one brain.`)
         }
       }
+      // Containment carried from capture. Three states, and they are not interchangeable:
+      //   true            placed in the container the capture named
+      //   false           the edge already existed — a re-materialise, not a failure
+      //   null/undefined  no container was ever requested (say nothing)
+      // containerSkipped is the only one that needs a warning: it means a container WAS asked for and
+      // did not happen, which is exactly the silence this whole path exists to remove.
+      if (body?.containerSkipped) {
+        lines.push(`⚠ CONTAINER NOT APPLIED — ${body.containerSkipped}. The record exists but is not inside the event you named; place it with contain_record or leave it out.`)
+      } else if (body?.contained === true) {
+        lines.push('Placed inside the container named at capture.')
+      } else if (body?.contained === false) {
+        lines.push('Already inside the container named at capture (no change).')
+      }
       const text = lines.length
         ? `${lines.join('\n')}\n\n${JSON.stringify(body, null, 2)}`
         : JSON.stringify(body, null, 2)
@@ -2235,6 +2253,45 @@ function renderNudge(payload) {
     },
   )
 
+  server.registerTool(
+    'supersede_record',
+    {
+      title: 'Mark a record as no longer the answer',
+      description: "Say that a record is wrong, outdated or replaced — WITHOUT deleting it. Use it when you re-capture something properly and the old copy should stop showing up: a transcript filed with a bad occurred_at, a duplicate capture, a low-fidelity copy replaced by a content_path one. \u26a0 NOTHING IS DESTROYED AND THIS IS REVERSIBLE (`restore: true`). The row, its page attachments and its containment all stay exactly as they were; only the READS change — it disappears from its pages, from its container's contents, and from the \"holds N\" count on find_sessions. It stays SEARCHABLE on purpose: hiding a record from search would be most of the way to deleting it without the audit trail. \u26a0 THERE IS NO DELETE, DELIBERATELY (ADR-0049) — 13 of the 15 foreign keys to a record CASCADE, so a real delete would unfile everything inside a container, drop clearance anchors and rewrite the claim ledger, while still leaving revision rows behind. If you actually need content destroyed rather than hidden, say so to the user rather than reaching for this. \u26a0 REFUSED ON A CONTAINER (a class session, a meeting): hiding an event that still holds other records leaves their placements pointing at nothing. Supersede the records INSIDE it instead.",
+      inputSchema: {
+        record_id: z.string().describe('the record that is no longer the answer'),
+        reason: z.string().optional().describe('WHY it is no longer right — required unless restoring, and the one thing that cannot be inferred later'),
+        superseded_by: z.string().optional().describe('the record that REPLACES it, if there is one. Must be in the same brain. Optional: "this is wrong" is a complete statement on its own.'),
+        restore: z.boolean().optional().describe('true = undo a previous supersede and make it current again'),
+      },
+    },
+    async ({ record_id, reason, superseded_by, restore }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/records/supersede`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ recordId: record_id, reason, supersededBy: superseded_by, restore }),
+        })
+      } catch (e) {
+        return toolError(`Could not reach Agnoclast: ${e.message}`)
+      }
+      const body = await res.json().catch(() => ({}))
+      if (!res.ok || !body?.ok) {
+        return toolError(`Could not supersede ${record_id}: ${body?.error ?? res.status}${body?.detail ? ` \u2014 ${body.detail}` : ''}`)
+      }
+      if (restore) {
+        return { content: [{ type: 'text', text: `Restored ${record_id} — it is a current record again and reappears on its pages and in its container.` }] }
+      }
+      const l = [`Superseded ${record_id}.`]
+      if (body.supersededBy) l.push(`Replaced by ${body.supersededBy}.`)
+      // \u26a0 SAY WHAT DID NOT HAPPEN. The caller's next question is always whether this deleted
+      // something. It did not, and a reader who assumes it did will not think to restore.
+      l.push('Nothing was deleted — the row, its page attachments and its containment are intact. It is hidden from its pages, its container contents and session holds-counts, and stays searchable. `restore: true` reverses this.')
+      return { content: [{ type: 'text', text: l.join('\n') }] }
+    },
+  )
+
   server.registerTool(
     'find_sessions',
     {
@@ -2276,10 +2333,11 @@ function renderNudge(payload) {
     'capture_record',
     {
       title: 'Hand something over and get it into the brain',
-      description: "Put a document, transcript, notes or any pasted content into the brain as a real record, routed to where it belongs. USE THIS WHEN THERE IS NO CONNECTOR — a lecture recording, an export from a tool nobody has wired up, something a person just handed you. ⚠ `identifiers` IS HOW IT REACHES A PAGE: a record routes to whatever page CLAIMS an identifier it carries (series:… for a class or recurring meeting, repo:owner/name, project:slug, email:someone@example.com). WITHOUT ONE IT REACHES NO PAGE — that is not an error, but it means nobody will find it, so say so rather than reporting success. `occurred_at` is WHEN THE THING HAPPENED, not now: a transcript handed over today may belong to yesterday's class, and filing it under today puts it in the wrong interval invisibly. `container_record_id` additionally places it INSIDE a specific event (a class session, a meeting) — that is an explicit human decision and is recorded as one; overlap alone never places anything.",
+      description: "Put a document, transcript, notes or any pasted content into the brain as a real record, routed to where it belongs. USE THIS WHEN THERE IS NO CONNECTOR — a lecture recording, an export from a tool nobody has wired up, something a person just handed you. ⚠ `identifiers` IS HOW IT REACHES A PAGE: a record routes to whatever page CLAIMS an identifier it carries (series:… for a class or recurring meeting, repo:owner/name, project:slug, email:someone@example.com). WITHOUT ONE IT REACHES NO PAGE — that is not an error, but it means nobody will find it, so say so rather than reporting success. `occurred_at` is WHEN THE THING HAPPENED, not now: a transcript handed over today may belong to yesterday's class, and filing it under today puts it in the wrong interval invisibly. `container_record_id` additionally places it INSIDE a specific event (a class session, a meeting) — that is an explicit human decision and is recorded as one; overlap alone never places anything. \u26a0 PASS `content_path` FOR ANYTHING LONG: a file is read and sent verbatim, whereas retyping a transcript into `content` routes every character through a model that is not guaranteed to reproduce it exactly. Use `content` only for something short you are composing yourself.",
       inputSchema: {
         title: z.string().describe('a short name for this record'),
-        content: z.string().describe('the actual content — transcript, notes, document text. Summarized server-side.'),
+        content: z.string().optional().describe('the actual content, inline. For anything long prefer content_path — see below.'),
+        content_path: z.string().optional().describe('ABSOLUTE PATH to a file whose contents become the record, read and sent verbatim. USE THIS FOR TRANSCRIPTS AND DOCUMENTS: it is the only way the stored text is guaranteed byte-identical to the source. Exactly one of content / content_path.'),
         occurred_at: z.string().describe('when the thing HAPPENED, ISO 8601 — not when you are uploading it'),
         ends_at: z.string().optional().describe('when it ended, ISO 8601. Omit if unknown; NEVER guess one.'),
         identifiers: z.array(z.string()).optional().describe('routing identifiers — how it reaches a page. e.g. ["series:geol-100-001-f2026"]'),
@@ -2289,14 +2347,34 @@ function renderNudge(payload) {
         brain: z.string().optional().describe('which brain, by name or org id. REQUIRED if you belong to more than one — placing a record IS a disclosure decision.'),
       },
     },
-    async ({ title, content, occurred_at, ends_at, identifiers, container_record_id, summary, source, brain }) => {
+    async ({ title, content, content_path, occurred_at, ends_at, identifiers, container_record_id, summary, source, brain }) => {
+      // 🔴 A FILE IS READ HERE RATHER THAN RETYPED UPSTREAM, AND THAT IS A FIDELITY GUARANTEE,
+      // NOT A CONVENIENCE. Passing a 39,000-character lecture transcript through `content` means the
+      // caller has to emit every character of it, and a model reproducing a long document verbatim is
+      // likely-correct, never certain-correct. Measured 2026-09-03: the first real transcript captured
+      // this way had to carry a note in its own body saying it was re-entered and unverified. Reading
+      // the file makes byte-identity structural instead of a matter of care.
+      if ((content == null || content === '') === (content_path == null || content_path === '')) {
+        return toolError('Pass exactly one of content or content_path.')
+      }
+      let text = content
+      if (content_path) {
+        try {
+          const st = statSync(content_path)
+          if (!st.isFile()) return toolError(`Not a file: ${content_path}`)
+          text = readFileSync(content_path, 'utf8')
+        } catch (e) {
+          return toolError(`Could not read ${content_path}: ${e.message}`)
+        }
+        if (!text.trim()) return toolError(`${content_path} is empty — nothing to capture.`)
+      }
       let res
       try {
         res = await fetchCortex(`${BASE}/api/records/capture`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
           body: JSON.stringify({
-            title, content, occurredAt: occurred_at, endsAt: ends_at, identifiers,
+            title, content: text, occurredAt: occurred_at, endsAt: ends_at, identifiers,
             containerRecordId: container_record_id, summary, source, brain,
           }),
         })
@@ -2317,6 +2395,13 @@ function renderNudge(payload) {
         if (body.duplicate) l.push('This matched an existing unit rather than creating a new one.')
         if (body.routed_by?.length) l.push(`Carries: ${body.routed_by.join(', ')} — it will route on those once materialised.`)
         else l.push('⚠ NO IDENTIFIERS — once materialised it will reach no page.')
+        // ⚠ A CONTAINER THE CALLER ASKED FOR MUST NOT VANISH FROM THE REPORT. It cannot be applied
+        // yet — there is no record — but it IS carried in the sealed payload and applied at
+        // materialisation. Saying nothing here is what made a caller re-derive a placement they had
+        // already specified (observed 2026-09-03).
+        if (body.containerDeferred) {
+          l.push(`Container ${body.containerRecordId} is carried with it and applied when you materialise — you do not need to place it again.`)
+        }
         return { content: [{ type: 'text', text: l.join('\n') }] }
       }
       const lines = [`Captured "${title}" as record ${body.id}.`]

package/package.json

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