@theronap/cortex-mcp 0.9.159 → 0.9.160

package/lib/server.mjs

@@ -2151,6 +2151,51 @@ function renderNudge(payload) {
     },
   )
 
+  server.registerTool(
+    'staged_look',
+    {
+      title: 'Read a staged arrival before deciding where it goes',
+      description: 'Read ONE staged arrival\'s envelope — sender, subject, recipients, thread, the generated summary, and the identifiers holding it — without claiming or changing anything. Use it before `place_staged_record` whenever the subject alone does not tell you WHAT KIND of thing this is. ⚠ THE SUBJECT LIES MORE OFTEN THAN YOU WOULD THINK: `staged_records` lists subjects only, and a message reading `Re: [owner/repo] fix(triage)…` is as likely to be a bot\'s deployment-status comment as a human discussing the PR — measured 2026-09-21, `vercel[bot]` accounts for 26 of the pending arrivals whose subject names that repo. The `from` header settles it in one look. ⚠ THIS IS THE ENVELOPE, NOT THE LETTER. A staged arrival stores headers and a generated summary; the message BODY is not persisted, so `bodyStored` is always false. Do not describe an arrival as something you READ — you saw who sent it and what it was titled. Looking is free, changes nothing, and needs no release.',
+      inputSchema: {
+        stagedId: z.string().describe('staged arrival id, from `staged_records` or the session-start arrivals block'),
+      },
+    },
+    async ({ stagedId }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/staged/look?stagedId=${encodeURIComponent(stagedId)}`, {
+          headers: { Authorization: `Bearer ${TOKEN}` },
+        })
+      } catch (e) {
+        return toolError(`Could not read that staged arrival: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (res.status === 404) {
+        return toolError(`No staged arrival ${stagedId} of yours. Staged rows are per-person and in no brain, so this means it is not yours or does not exist — the two are deliberately indistinguishable.`)
+      }
+      if (!res.ok) return toolError(`Could not read staged arrival ${stagedId}: ${out?.error ?? res.status}`)
+
+      const l = out?.look ?? {}
+      const line = (label, v) => (v ? `  ${label.padEnd(9)} ${v}\n` : '')
+      const held = Array.isArray(l.blockingIdentifiers) && l.blockingIdentifiers.length
+        ? `\n⚠ HELD ON UNCLAIMED IDENTIFIERS — no page claims these, so it cannot finish until they are dispositioned:\n${l.blockingIdentifiers.map((i) => `  · ${i}`).join('\n')}\n`
+        : ''
+      return {
+        content: [{
+          type: 'text',
+          text:
+            `${l.title ?? '(untitled)'}\n` +
+            `  ${l.sourceType} · arrived ${l.receivedAt ?? '?'} · occurred ${l.occurredAt ?? '?'}\n\n` +
+            line('from', l.from) + line('subject', l.subject) + line('to', l.to) +
+            line('account', l.account) + line('thread', l.threadId) +
+            (l.summary ? `\n  summary  ${l.summary}\n` : '') +
+            held +
+            `\n⚠ This is the ENVELOPE. The message body was never stored (bodyStored: ${l.bodyStored === true}), so you have seen who sent it and what it was called — not what it says. Judge accordingly, and do not report having read it.`,
+        }],
+      }
+    },
+  )
+
   server.registerTool(
     'discard_staged',
     {

package/package.json

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