@theronap/cortex-mcp 0.9.89 → 0.9.90

package/lib/server.mjs

@@ -192,62 +192,179 @@ export async function runServer(version) {
     'log_session',
     {
       title: 'Log this session to Agnoclast',
-      description: 'Persist a CURATED summary of this work session as its durable Agnoclast record (authoritative — supersedes the auto-capture hook). Call at session close after composing the summary. Pass sessionId (the Claude Code session id) if you have it so this dedupes with the auto-capture of the same session. If you belong to more than one brain, pass `brain` — without it a session log has no route and is STAGED rather than recorded.',
+      description: 'Persist a CURATED summary of this work session as its durable Agnoclast record (authoritative — supersedes the auto-capture hook). Call at session close after composing the summary. Pass sessionId (the Claude Code session id) so this dedupes with the auto-capture of the same session. If you belong to more than one brain you MUST name one — without a brain a session log has no route and is STAGED rather than recorded. **If the session touched work belonging to different brains, pass `segments` instead of `summary` and split it** — one segment per brain, each summary standing on its own and never alluding to the others. Reports every segment individually; a partial result is reported as PARTIAL, never as success.',
       inputSchema: {
-        summary: z.string().describe('the curated session summary (what was done, decided, left open) — becomes the durable record'),
+        summary: z.string().optional().describe('the curated session summary — the single-brain form. Omit when passing `segments`'),
+        segments: z.array(z.object({
+          brain: z.string().describe('destination brain for this half of the session (name or org id)'),
+          summary: z.string().describe('a summary that stands ON ITS OWN. It must not mention, allude to, or imply that other segments exist — "the rest of this session covered personal projects" leaks in prose exactly what splitting was meant to contain'),
+          title: z.string().optional(),
+          project: z.string().optional(),
+        })).optional().describe('SPLIT the log, one entry per brain. Use whenever a session touched work belonging to different brains: a session is a container of time, not a topic, and every single-brain answer is wrong — filing it all in the org brain exposes personal work to colleagues, filing it all in the personal one denies the org its record, and summarizing half silently drops the other half. Max ONE segment per brain (they share this session\'s dedupe key, so two aimed at the same brain would overwrite each other). When a chunk is ambiguous, put it in the MORE PRIVATE brain — a misfile there is private, a misfile the other way is visible to everyone in the org.'),
         project: z.string().optional().describe('project key/name this session worked in'),
         title: z.string().optional().describe('short title for the session'),
-        sessionId: z.string().optional().describe('the Claude Code session id (dedupes with the auto-capture hook of the same session)'),
+        sessionId: z.string().optional().describe('the Claude Code session id — shared by every segment, and the only thing pairing them. Deliberately NOT a link: segments never reference each other, so a reader cleared for one brain cannot tell the others exist, while you can join on it across brains'),
         brain: z.string().optional().describe('which brain to record this session in (name or org id, one of your own). REQUIRED IN EFFECT for a multi-brain member: session-class sources route only by an explicit brain or a sole membership, so omitting it stages the log instead of recording it.'),
         privacy: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('tier this record AT WRITE TIME. Use when the summary names confidential work (a candidate evaluation, a security finding) — safer than letting it land org-visible and re-tiering after, which leaves it readable in between.'),
       },
     },
-    async ({ summary, project, title, sessionId, brain, privacy }) => {
-      const res = await fetchCortex(`${BASE}/api/ingest`, {
-        method: 'POST',
-        headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          source: 'claude-code',
-          captureSource: 'skill',
-          summary,
-          ...(project ? { project } : {}),
-          ...(title ? { title } : {}),
-          ...(sessionId ? { sessionId } : {}),
-          // ADR-0022 deleted the write pointer, so a session-class source routes ONLY by an explicit
-          // brain or a sole membership — anything else STAGES. This tool never sent one, so every
-          // close-out from a multi-brain member landed in staged_records instead of the org. Measured
-          // 2026-08-09: 86 staged rows, and the pile is not drainable by /api/staged/promote because
-          // promote resolves through the same branch session-class sources skip.
-          ...(brain ? { brain } : {}),
-          ...(privacy ? { privacy } : {}),
-          payload: { via: 'log_session' },
-        }),
-      })
-      if (!res.ok) {
-        const body = await res.text()
-        throw new Error(classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message)
+    async ({ summary, segments, project, title, sessionId, brain, privacy }) => {
+      // A session is a container of TIME, not a topic (ADR-0029 step 4). Normalize to a list of
+      // segments; the single-brain call is just a one-segment list.
+      const list = Array.isArray(segments) && segments.length
+        ? segments.map((s) => ({ brain: s.brain, summary: s.summary, title: s.title ?? title, project: s.project ?? project }))
+        : (summary ? [{ brain, summary, title, project }] : null)
+      if (!list) {
+        return toolError('Pass `summary` (single brain) or a non-empty `segments` array (one entry per brain).')
+      }
+
+      // Records are unique on the ORG-SCOPED (org_id, dedupe_key) and every segment carries this
+      // session's dedupe key. Cross-brain segments therefore never collide — that constraint is what
+      // makes the whole design work — but two aimed at the SAME brain would silently merge and lose
+      // one. Refuse instead of letting that happen quietly.
+      const seenBrain = new Set()
+      for (const s of list) {
+        const k = String(s.brain ?? '').trim().toLowerCase()
+        if (seenBrain.has(k)) {
+          return toolError(`Two segments target the same brain (${s.brain}). They share this session's dedupe key, so the second would overwrite the first — merge them into one segment.`)
+        }
+        seenBrain.add(k)
+      }
+
+      let brainIndex = null
+      const orgIdFor = async (nameOrId) => {
+        if (!nameOrId) return null
+        if (!brainIndex) {
+          try {
+            const r = await fetchCortex(`${BASE}/api/brains`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+            brainIndex = r.ok ? ((await r.json().catch(() => ({}))).brains ?? []) : []
+          } catch {
+            brainIndex = []
+          }
+        }
+        const q = String(nameOrId).trim().toLowerCase()
+        const hit = brainIndex.find(
+          (b) => String(b.orgId ?? '').toLowerCase() === q || String(b.name ?? '').toLowerCase() === q,
+        )
+        return hit?.orgId ?? null
       }
-      const j = await res.json().catch(() => ({}))
 
-      // NEVER report a non-record as "logged". `staged` and `skipped` are 200 OK responses that wrote
-      // no record, and this line used to print "Logged to Agnoclast (authoritative) … updated existing"
-      // for both — `j.inserted` is merely falsy on a staged write, which reads as an UPDATE. That is
-      // how a session close-out was reported as saved when it had not been (2026-08-09), and it is the
-      // same failure shape the cortex-log skill warns about for `author`: a success string over a write
-      // that did not land. The caller cannot tell the difference, so the message has to.
-      if (j.staged) {
-        const why = j.reason === 'no_route_for_source' && !brain
-          ? 'no brain was named and you belong to more than one, so it had nowhere to route'
-          : `reason: ${j.reason ?? 'unknown'}`
-        return { content: [{ type: 'text', text: `NOT LOGGED — STAGED, not recorded (${why}). Re-run log_session with brain:"<name>" to record it. Staged session logs cannot currently be drained by /api/staged/promote.` }] }
-      }
-      if (j.skipped) {
-        return { content: [{ type: 'text', text: `NOT LOGGED — the server skipped this write: ${j.skipped}` }] }
-      }
-      if (!j.id) {
-        return { content: [{ type: 'text', text: `NOT LOGGED — the server returned no record id. Raw response: ${JSON.stringify(j).slice(0, 300)}` }] }
+      const lines = []
+      let failures = 0
+
+      for (const seg of list) {
+        const where = seg.brain ?? '(no brain named)'
+        let res
+        try {
+          res = await fetchCortex(`${BASE}/api/ingest`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              source: 'claude-code',
+              captureSource: 'skill',
+              summary: seg.summary,
+              ...(seg.project ? { project: seg.project } : {}),
+              ...(seg.title ? { title: seg.title } : {}),
+              ...(sessionId ? { sessionId } : {}),
+              // ADR-0022 deleted the write pointer, so a session-class source routes ONLY by an
+              // explicit brain or a sole membership — anything else STAGES. This tool never sent one,
+              // so every close-out from a multi-brain member landed in staged_records instead of the
+              // org. Measured 2026-08-09: 86 staged rows, not drainable by /api/staged/promote.
+              ...(seg.brain ? { brain: seg.brain } : {}),
+              ...(privacy ? { privacy } : {}),
+              payload: { via: 'log_session' },
+            }),
+          })
+        } catch (e) {
+          failures++
+          lines.push(`✗ ${where}: ${e.message}`)
+          continue
+        }
+        if (!res.ok) {
+          const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+          failures++
+          lines.push(`✗ ${where}: ${d.message}`)
+          continue
+        }
+        const j = await res.json().catch(() => ({}))
+
+        // NEVER report a non-record as "logged". `staged` and `skipped` are 200 OK responses that
+        // wrote no record, and this used to print "Logged … updated existing" for both, because
+        // `j.inserted` is merely falsy on a staged write.
+        if (j.staged) {
+          const why = j.reason === 'no_route_for_source' && !seg.brain
+            ? 'no brain named and you belong to more than one, so it had nowhere to route'
+            : `reason: ${j.reason ?? 'unknown'}`
+          failures++
+          lines.push(`✗ ${where}: NOT LOGGED — staged, not recorded (${why}). Re-run this segment with brain:"<name>" — staged session logs cannot be drained by /api/staged/promote.`)
+          continue
+        }
+        if (j.skipped) {
+          failures++
+          lines.push(`✗ ${where}: NOT LOGGED — server skipped the write: ${j.skipped}`)
+          continue
+        }
+
+        // Gate 4 routes a session log into PRIVATE INTAKE rather than straight to records, answering
+        // `via:"private_intake"` with an intakeItemId and no id. The previous check fell through to
+        // "no record id" and reported NOT LOGGED over a write that had landed — a false negative that
+        // drives retries, and retries against ingest make duplicates.
+        //
+        // Materializing here is not an optimization. Close-out is the ONLY moment the destination
+        // brain is known; a unit left in intake goes cleanup-due in a day and becomes an item no later
+        // session has the authority to route, because deciding which brain half of someone's session
+        // belongs in is exactly the judgment a stranger cannot make.
+        if (!j.id && j.via === 'private_intake' && j.intakeItemId) {
+          const orgId = await orgIdFor(seg.brain)
+          if (!orgId) {
+            failures++
+            lines.push(`✗ ${where}: captured to intake as ${j.intakeItemId}, but that brain did not resolve to an org id — materialize it by hand`)
+            continue
+          }
+          let m
+          try {
+            m = await fetchCortex(`${BASE}/api/intake/materialize`, {
+              method: 'POST',
+              headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+              body: JSON.stringify({
+                intakeItemId: j.intakeItemId,
+                orgId,
+                title: seg.title,
+                summary: seg.summary,
+                source: 'claude-code',
+                recordType: 'ai_session',
+                origin: 'session',
+              }),
+            })
+          } catch (e) {
+            failures++
+            lines.push(`✗ ${where}: intake ${j.intakeItemId} NOT materialized — ${e.message}`)
+            continue
+          }
+          const mj = await m.json().catch(() => ({}))
+          if (!m.ok || !mj.recordId) {
+            failures++
+            lines.push(`✗ ${where}: intake ${j.intakeItemId} NOT materialized — ${mj.error ?? m.status}`)
+            continue
+          }
+          lines.push(`✓ ${where}: record ${mj.recordId}`)
+          continue
+        }
+
+        if (!j.id) {
+          failures++
+          lines.push(`✗ ${where}: NOT LOGGED — no record id. Raw: ${JSON.stringify(j).slice(0, 200)}`)
+          continue
+        }
+        lines.push(`✓ ${where}: record ${j.id}${j.inserted ? '' : ' (updated existing)'}`)
       }
-      return { content: [{ type: 'text', text: `Logged to Agnoclast (authoritative): "${j.title ?? title ?? 'session'}" — ${j.inserted ? 'new record' : 'updated existing'} (id ${j.id}).` }] }
+
+      // Partial success is a real outcome once there is more than one segment, and "3 of 4 landed"
+      // must never read as done — that is the same silent-loss shape this whole path was repaired for.
+      const head = failures === 0
+        ? `Logged ${lines.length} segment${lines.length === 1 ? '' : 's'}.`
+        : `PARTIAL — ${lines.length - failures} of ${lines.length} segments logged, ${failures} FAILED. A partly-logged session is not a logged session; re-run the failed segments.`
+      return { content: [{ type: 'text', text: `${head}\n${lines.join('\n')}` }] }
     },
   )
 
@@ -485,7 +602,7 @@ export async function runServer(version) {
         source: z.string().optional(),
         recordType: z.string().optional(),
         dedupeKey: z.string().optional(),
-        origin: z.enum(['deterministic', 'llm', 'user']).optional(),
+        origin: z.enum(['deterministic', 'llm', 'user', 'session']).optional(),
       },
     },
     async (args) => {
@@ -553,11 +670,89 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'intake_defer',
+    {
+      title: 'Defer a private intake item to the owner',
+      description:
+        'The THIRD terminal outcome, and the right one whenever the honest answer is "this is not mine to decide." Use it when a claimed unit is someone else\'s private content, when the destination brain is a real judgment call rather than a lookup, or when publishing and destroying are both wrong — a stranger\'s message thread, a photo you cannot place, an email whose brain depends on context only the owner has. Destroys NOTHING: the unit stays encrypted and intact, its state becomes `awaiting_user`, and your `question` is what the owner actually sees. Prefer this over letting a lease lapse — a lapsed lease says nothing, increments `attempts`, and hands the identical dead end to the next session. Requires the claim, one item per call.',
+      inputSchema: {
+        intakeItemId: z.string().describe('intake item uuid from intake_claim'),
+        question: z.string().describe('what you need the owner to decide, in their words not yours — this is the entire message they get, so "which brain should this iMessage thread go to, if any?" beats "needs triage"'),
+      },
+    },
+    async ({ intakeItemId, question }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/intake/defer`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ intakeItemId, question }),
+        })
+      } catch (e) {
+        return toolError(`Could not defer: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        if (out?.error === 'not_claimed') {
+          return toolError('You do not hold a claim on that item — intake_claim it first, so the question follows from having read it.')
+        }
+        if (out?.error === 'already_terminal') {
+          return toolError(`Nothing left to ask about: ${out?.detail ?? 'the unit is already materialized or discarded'}.`)
+        }
+        return toolError(`Could not defer: ${out?.error ?? res.status}${out?.detail ? ` — ${out.detail}` : ''}`)
+      }
+      if (out?.alreadyDeferred) {
+        return { content: [{ type: 'text', text: 'Already awaiting the owner — nothing to do.' }] }
+      }
+      return { content: [{ type: 'text', text: 'Deferred to the owner. Content preserved, question queued in intake_cleanup_status.openQuestions, and the unit no longer gates cleanup.' }] }
+    },
+  )
+
+  server.registerTool(
+    'intake_release',
+    {
+      title: 'Hand an intake claim back',
+      description:
+        'Give a claimed unit back to the queue WITHOUT deciding anything. This is not a fourth outcome — materialize, discard and defer resolve a unit; release just ends your hold on it. Use it when you claimed more than you can act on, or when the unit turns out to belong to work you are not doing. Prefer it over letting the lease expire: a lapse and a crash are indistinguishable in the ledger, so silently timing out costs the pile the one signal that says a session looked and chose to pass. Use intake_defer instead when the unit needs the OWNER to decide — release puts it back in front of the next session, which will hit whatever wall you did.',
+      inputSchema: {
+        intakeItemId: z.string().describe('intake item uuid from intake_claim'),
+        reason: z.string().describe('why you are handing it back — "claimed too broadly", "not related to this session\'s work". Recorded on the claim, and the only thing distinguishing this from a lapsed lease'),
+      },
+    },
+    async ({ intakeItemId, reason }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/intake/release`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ intakeItemId, reason }),
+        })
+      } catch (e) {
+        return toolError(`Could not release: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        if (out?.error === 'not_claimed') {
+          return toolError('You do not hold a claim on that item — there is nothing to hand back.')
+        }
+        if (out?.error === 'awaiting_user') {
+          return toolError('That unit is already deferred to the owner. Releasing it would orphan the open question — leave it, or have the owner answer it.')
+        }
+        if (out?.error === 'already_terminal') {
+          return toolError(`Nothing to release: ${out?.detail ?? 'the unit is already materialized or discarded'}.`)
+        }
+        return toolError(`Could not release: ${out?.error ?? res.status}${out?.detail ? ` — ${out.detail}` : ''}`)
+      }
+      return { content: [{ type: 'text', text: 'Released. The unit is back in the queue as pending, and your lease is gone.' }] }
+    },
+  )
+
   server.registerTool(
     'intake_cleanup_status',
     {
       title: 'Private intake cleanup status',
-      description: 'Counts of pending/claimed/awaiting/cleanup-due intake items plus open clarifying questions for the owner.',
+      description: 'Counts of pending/claimed/awaiting/cleanup-due intake items, open clarifying questions for the owner, and `needsAttention` — units that keep coming back, with attempts / releases / deferrals / lapses each broken out. A high `lapses` means sessions claimed that unit and neither resolved it nor handed it back; a `deferrals` above 1 means the owner has already been asked more than once. Both are the OWNER\'s signal to act on, not yours — surface them rather than trying to clear them yourself.',
       inputSchema: {},
     },
     async () => {
@@ -1517,14 +1712,16 @@ export async function runServer(version) {
         project: z.string().optional().describe('project key to filter to (e.g. "cortex")'),
         since_days: z.number().optional().describe('only records from the last N days'),
         limit: z.number().optional().describe('max rows (1-50, default 20)'),
+        session: z.string().optional().describe('a session id — returns every record that session produced, INCLUDING the separate halves of a log that was split across brains. Segmented logs share a sessionId and never link to each other, so this is the only way to reassemble one. RLS-scoped: you get the halves you are cleared for and cannot tell whether others exist'),
       },
     },
-    async ({ type, project, since_days, limit }) => {
+    async ({ type, project, since_days, limit, session }) => {
       const qs = new URLSearchParams()
       if (type) qs.set('type', type)
       if (project) qs.set('project', project)
       if (since_days != null) qs.set('since_days', String(since_days))
       if (limit != null) qs.set('limit', String(limit))
+      if (session) qs.set('session', session)
       let res
       try {
         res = await fetchCortex(`${BASE}/api/records?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })

package/package.json

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