@theronap/cortex-mcp 0.9.124 → 0.9.126

package/lib/server.mjs

@@ -1883,13 +1883,123 @@ 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(
+    'discard_staged',
+    {
+      title: 'Discard staged arrivals in bulk — reversibly',
+      description: "Mark staged arrivals as discarded, addressed BY IDENTIFIER (every arrival that address is holding) or by explicit staged ids. The counterpart to `place_staged_record`, which takes one row at a time and needs pages — right for an arrival worth keeping, wrong for a queue where one unclaimed address holds 68-199 arrivals and most of them are simply not wanted. ⚠ REVERSIBLE, unlike `intake_discard`: this sets a state and destroys NOTHING (the row keeps its raw_body and the message is still in the source mailbox), so pass `restore: true` to undo. That is what makes a bulk verb safe here — classifying thousands of correspondents guarantees being wrong about some. ⚠ DRY-RUN BY DEFAULT: it reports what it WOULD change and changes nothing until you pass `apply: true`, and the dry-run count is the same set the apply writes. Use `staged_records` first to see the ranking.",
+      inputSchema: {
+        identifiers: z.array(z.string()).optional().describe('discard every pending arrival blocked on any of these, e.g. ["email:venmo@venmo.com"]'),
+        staged_ids: z.array(z.string()).optional().describe('discard these specific arrivals'),
+        apply: z.boolean().optional().describe('false/absent = dry run (default). true actually writes.'),
+        restore: z.boolean().optional().describe('true = put previously discarded arrivals back in the queue'),
+      },
+    },
+    async ({ identifiers, staged_ids, apply, restore }) => {
+      if (!identifiers?.length && !staged_ids?.length) {
+        return toolError('Pass `identifiers` or `staged_ids` — an empty call is refused rather than treated as "everything".')
+      }
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/staged/discard`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ identifiers, stagedIds: staged_ids, apply: apply === true, restore: restore === true }),
+        })
+      } catch (e) {
+        return toolError(`Could not reach the staged queue: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return toolError(`Could not ${restore ? 'restore' : 'discard'}: ${out?.hint ?? out?.error ?? res.status}`)
+      if (!out) return toolError('The server returned no body.')
+
+      const verb = out.restore ? 'restore' : 'discard'
+      const lines = []
+      if (out.mode === 'dry-run') {
+        lines.push(`DRY RUN — nothing changed. Would ${verb} ${out.matched} arrival(s).`)
+        lines.push('Re-run with apply: true to do it.')
+      } else {
+        lines.push(`${out.changed} arrival(s) ${out.restore ? 'restored to the queue' : 'discarded'}.`)
+        if (!out.restore) lines.push('Reversible — discard_staged with restore: true puts them back.')
+      }
+      if (out.unmatchedIdentifiers?.length) {
+        lines.push('', `⚠ matched NOTHING (already drained, or a typo): ${out.unmatchedIdentifiers.join(', ')}`)
+      }
+      if (out.sample?.length) {
+        lines.push('', 'Sample:')
+        for (const r of out.sample.slice(0, 10)) {
+          lines.push(`  ${r.occurredAt?.slice(0, 10) ?? ''}  ${r.title ?? '(no subject)'}`)
+        }
+        if (out.matched > out.sample.length) lines.push(`  … and ${out.matched - out.sample.length} more`)
+      }
+      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.126",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {