@theronap/cortex-mcp 0.9.124 → 0.9.125

package/lib/server.mjs

@@ -1883,13 +1883,70 @@ function renderNudge(payload) {
     },
   )
 
+  server.registerTool(
+    'staged_records',
+    {
+      title: 'List staged arrivals — the ones in no brain yet, with their ids',
+      description: "List arrivals that are STAGED: held in no brain at all, because nothing could decide which brain they belong to, or because they carry identifiers the graph has never seen. This is the ONLY way to obtain a `staged_id`. `pending_records` structurally cannot see these (it reads records, and a staged row is not one); `intake_changes` returns ids from a different queue that `place_staged_record` rejects; and the session-start block prints titles without ids. Until this existed, placing a staged arrival required a human to read a uuid off a screen. Returns each arrival's id, title, age and the identifiers BLOCKING it, plus `blocking_summary` — the unclaimed identifiers ranked by how many arrivals each one holds, so you can see which single `set_routing_identifier` releases the most. ⚠ Claiming an identifier UNBLOCKS but does not place: which pages an arrival lands on decides its brain, and therefore who can read it, so that stays a decision someone makes.",
+      inputSchema: {
+        limit: z.number().optional().describe('max arrivals to return (default 50, max 200). `total` always reports the WHOLE queue regardless.'),
+        source: z.string().optional().describe("narrow to one connector kind, e.g. 'email' or 'github'"),
+      },
+    },
+    async ({ limit, source }) => {
+      const qs = new URLSearchParams()
+      if (limit) qs.set('limit', String(limit))
+      if (source) qs.set('source', source)
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/staged${qs.toString() ? `?${qs}` : ''}`, {
+          headers: { Authorization: `Bearer ${TOKEN}` },
+        })
+      } catch (e) {
+        return toolError(`Could not list staged arrivals: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return toolError(`Could not list staged arrivals: ${out?.error ?? res.status}`)
+      if (!out) return toolError('The server returned no body.')
+
+      if (!out.total) {
+        return { content: [{ type: 'text', text: 'Nothing staged — every arrival has reached a brain.' }] }
+      }
+      const lines = [`${out.total} staged arrival(s) — in NO brain yet:`, '']
+      for (const a of out.arrivals ?? []) {
+        // The id goes FIRST on its own line. It is the argument place_staged_record needs and the
+        // entire reason this tool exists; burying it after prose is how the session-start block
+        // managed to list these rows for weeks without making one of them actionable.
+        lines.push(`  ${a.stagedId}`)
+        lines.push(`    ${a.title ?? '(no subject)'}  ·  ${a.sourceType}  ·  ${a.occurredAt?.slice(0, 10) ?? ''}`)
+        if (a.blockingIdentifiers?.length) {
+          lines.push(`    blocked by: ${a.blockingIdentifiers.join(', ')}`)
+        } else {
+          lines.push('    held because no brain could be determined (no unknown identifiers)')
+        }
+      }
+      if ((out.arrivals ?? []).length < out.total) {
+        lines.push('', `  … ${out.total - out.arrivals.length} more not shown — raise \`limit\` to see them.`)
+      }
+      if (out.blockingSummary?.length) {
+        lines.push('', 'Unclaimed identifiers holding the most arrivals — claim one and that many unblock:')
+        for (const b of out.blockingSummary.slice(0, 10)) {
+          lines.push(`  ${b.arrivals}x  ${b.identifier}`)
+        }
+        lines.push('', 'Claim with set_routing_identifier on the page whose subject HAS that identifier.')
+      }
+      lines.push('', 'Place one with place_staged_record (staged_id + pages). The pages decide the brain, which decides who can read it.')
+      return { content: [{ type: 'text', text: lines.join('\n') }] }
+    },
+  )
+
   server.registerTool(
     'place_staged_record',
     {
       title: 'Place a staged arrival onto pages — the pages decide its brain',
       description: "Place a STAGED arrival — one that is in no brain at all — onto the pages it belongs to, which is also what decides its brain. Session-start lists these separately as `[staged]`, and they are the only rows route_record CANNOT take, because there is no record yet to route: nothing upstream chose a brain for them, deliberately. That is the point (ADR-0038) — the connector used to pick the brain from which mailbox the message arrived through, which is a fact about your email plumbing rather than about the message, and it decided WHO COULD READ IT before anyone had read it. Here the pages decide instead. ⚠ PLACING IS A DISCLOSURE DECISION, not just filing: a brain is the confidentiality boundary, so putting a staged message into a shared brain makes it readable by every member of that brain. Say so when you offer, and never place a personal message into a shared brain without the owner\'s explicit answer. All the pages must live in ONE brain — a record exists in exactly one — and pages spanning two brains are refused by name rather than resolved by picking. On success the content is replayed through the real ingest pipeline into that brain, so the record it produces is identical to one that had landed there directly, and then it is attached.",
       inputSchema: {
-        staged_id: z.string().describe('the staged id, as the [staged] rows at session start show it'),
+        staged_id: z.string().describe('the staged id — get it from `staged_records`, which is the only surface that prints one (session-start lists these arrivals but not their ids)'),
         pages: z.array(z.string()).describe("pages to place it on — a brain_documents id or the `ref:` read_page prints. They must all be in ONE brain; that brain is where the record lands."),
         reason: z.string().describe('WHY these pages — recorded with the attachment, and the one thing that cannot be inferred later'),
       },

package/package.json

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