@theronap/agnoclast-mcp 0.9.238 → 0.9.240

package/lib/arrivals_notice.mjs

@@ -59,6 +59,8 @@ import { fetchCortex, resolveBase, resolveTokenSource } from './diagnose.mjs'
 // Enough to hold a session's own recent output in full; small enough that the notice is READ rather
 // than spilled to a file, which is what happened at 49 KB.
 const MAX_YOURS = 25
+/** Assigned groups listed per prompt; the server hands out at most 5 new groups per prompt anyway. */
+const MAX_ASSIGNED = 8
 
 // A title is somebody else's text — anyone can send a calendar invite — and this prints into a
 // session's context. One line, bounded, and quoted so it reads as the name of a thing.
@@ -176,6 +178,21 @@ export function formatNotice(signals) {
   const total = Number(signals?.settling?.total ?? offers.length)
   const delta = Number(signals?.arrival?.count ?? 0)
 
+  // ⭐ ADR-0083 §2.3 — arrivals ASSIGNED to this session. Not an offer: this session is their one owner, and
+  // it is told at a prompt boundary so it handles them before the user's request. A conversation stays with
+  // this session for its lifetime, so its later texts come here too.
+  const assigned = Array.isArray(signals?.assigned) ? signals.assigned : []
+  if (assigned.length) {
+    const n = assigned.reduce((t, g) => t + (Number(g?.count) || 1), 0)
+    lines.push(`📥 ${n} arrival${n === 1 ? ' is' : 's are'} ASSIGNED TO THIS SESSION — you are ${n === 1 ? 'its' : 'their'} only owner. Handle ${n === 1 ? 'it' : 'them'} before the user's request, then answer the user:`)
+    for (const g of assigned.slice(0, MAX_ASSIGNED)) {
+      const many = Number(g?.count) > 1 ? ` ×${g.count}` : ''
+      const ids = (g?.ids ?? []).slice(0, 3).join(', ') + ((g?.ids ?? []).length > 3 ? ', …' : '')
+      lines.push(`     ${g?.source ?? '?'}${many} — ${g?.title ?? '(unreadable)'} · ${g?.hoursAgo ?? '?'}h · ids: ${ids}`)
+    }
+    if (assigned.length > MAX_ASSIGNED) lines.push(`     … and ${assigned.length - MAX_ASSIGNED} more groups`)
+    lines.push('   `intake_claim {intakeItemIds}` → `intake_materialize` (or `intake_discard` for junk) · `not_mine` hands one to the next session · only what only the user can decide → `intake_defer`.')
+  }
   if (delta) {
     lines.push(`⚡ ${delta} new arrival${delta === 1 ? '' : 's'} in the pile since this session was last told.`)
   }

package/lib/contacts_render.mjs

@@ -0,0 +1,114 @@
+// `my_contacts` and `contact` — AGNOCLAST'S OWN CONTACT BOOK (ADR-0084; Theron, 2026-10-17).
+//
+// Rendered from GET /api/contacts (or POST /api/contacts/search) and POST /api/contacts/briefing. The
+// book is the caller's alone: every person page they can read, in every brain they are in, merged into
+// one contact when pages share a phone or email the caller can see. A same-name match is NEVER a merge.
+//
+// The contact LIST (app and website) shows names and identifiers only. `contact` is the AI's view: the
+// identifiers AND every page of theirs, told apart by brain, plus the ONE page an outreach is filed on.
+
+/** Pure. `(801) 555-0123` for a US number; anything else as stored. */
+export function displayPhone(e164) {
+  const m = /^\+1(\d{3})(\d{3})(\d{4})$/.exec(String(e164 ?? ''))
+  return m ? `(${m[1]}) ${m[2]}-${m[3]}` : String(e164 ?? '')
+}
+
+/** Pure. One identifier, saying who can see it. */
+export function identifierLine(i) {
+  const v = i.kind === 'phone' ? displayPhone(i.value) : i.value
+  const who = i.shared ? '' : i.mine ? ' (private — only you)' : ''
+  return `${v}${who}`
+}
+
+/** Pure. Where reaching out to this contact files the record. */
+export function fileToLine(fileTo) {
+  if (!fileTo) return ''
+  if (fileTo.ok) {
+    const why = fileTo.why === 'context' ? 'the brain you are acting in' : 'the only brain they are in'
+    return `files to ${fileTo.page.brain} → "${fileTo.page.title}" (${why})`
+  }
+  if (fileTo.reason === 'ambiguous') return `files to: ASK which brain — ${fileTo.options.map((o) => o.brain).join(' or ')}`
+  return 'no page to file on'
+}
+
+function reachLine(reach, ringing) {
+  if (!reach) return ''
+  const bits = []
+  if (ringing && reach.call === true) bits.push('Call')
+  else if (ringing && reach.call === null) bits.push('Call? (not checked)')
+  if (reach.text) bits.push('Text an invite')
+  if (reach.email) bits.push('Email')
+  return bits.length ? bits.join(' · ') : 'no way to reach them yet'
+}
+
+/** Pure. The contact list. */
+export function renderContactList(out, { query } = {}) {
+  const contacts = Array.isArray(out?.contacts) ? out.contacts : []
+  const brains = Array.isArray(out?.brains) ? out.brains.map((b) => b.brain) : []
+  const lines = []
+  if (!contacts.length) {
+    lines.push(query
+      ? `No contact of yours matches "${query}". Your book is every person page you can read${brains.length ? ` in ${brains.join(', ')}` : ''}.`
+      : 'Your contact book is empty: no person page you can read has been written yet.')
+  } else {
+    const total = typeof out.total === 'number' ? out.total : contacts.length
+    lines.push(`${total} contact(s)${query ? ` matching "${query}"` : ''}${total > contacts.length ? `, showing ${contacts.length}` : ''} — person pages you can read${brains.length ? ` in ${brains.join(', ')}` : ''}, merged on a shared phone/email:`)
+    for (const c of contacts) {
+      const ids = (c.identifiers ?? []).map(identifierLine)
+      const where = [...new Set((c.pages ?? []).map((p) => p.brain))]
+      const parts = [`· ${c.name}`]
+      if (ids.length) parts.push(ids.join(' · '))
+      parts.push(`in ${where.join(', ')}${(c.pages ?? []).length > 1 ? ` (${c.pages.length} pages)` : ''}`)
+      const reach = reachLine(c.reach, out.ringing === true)
+      if (reach) parts.push(reach)
+      parts.push(fileToLine(c.fileTo))
+      lines.push(parts.filter(Boolean).join(' — '))
+      lines.push(`    page: ${c.id}`)
+    }
+  }
+  const sug = Array.isArray(out?.suggestions) ? out.suggestions : []
+  if (sug.length) {
+    const nameOf = new Map(contacts.map((c) => [c.id, c]))
+    lines.push('', 'SAME NAME, NOT MERGED — no phone or email in common. Ask the person before treating them as one:')
+    for (const s of sug) {
+      const [a, b] = s.contactIds.map((id) => nameOf.get(id))
+      const label = (c, id) => (c ? `${c.name} (${[...new Set(c.pages.map((p) => p.brain))].join(', ')})` : `page ${id}`)
+      lines.push(`  ${label(a, s.contactIds[0])}  /  ${label(b, s.contactIds[1])}`)
+    }
+  }
+  for (const e of out?.errors ?? []) lines.push(`⚠ ${e.brain}: could not be read (${e.error}) — its contacts are missing above.`)
+  lines.push('', '— Read one with `contact` (page: …) before reaching out: it returns their pages too. A phone number is for showing and "Text an invite" only; a call reaches an account by its email.')
+  return lines.join('\n')
+}
+
+/** Pure. The AI's briefing on one contact. */
+export function renderContactBriefing(out) {
+  const c = out?.contact
+  if (!c) return 'No such contact.'
+  const lines = [`${c.name}`]
+  const phones = (c.identifiers ?? []).filter((i) => i.kind === 'phone')
+  const emails = (c.identifiers ?? []).filter((i) => i.kind === 'email')
+  lines.push(phones.length ? `Phone: ${phones.map(identifierLine).join(' · ')}` : 'Phone: none you can see')
+  lines.push(emails.length ? `Email: ${emails.map(identifierLine).join(' · ')}` : 'Email: none you can see')
+  const pages = Array.isArray(out.pages) ? out.pages : []
+  const brains = [...new Set(pages.map((p) => p.brain))]
+  lines.push(`Reaching out: ${fileToLine(out.fileTo)}`)
+  if (out.fileTo && !out.fileTo.ok && out.fileTo.reason === 'ambiguous') {
+    lines.push('  → ask the person which brain this is for (or pass `brain`). File the record on that ONE page, not on all of them.')
+  }
+  lines.push('', pages.length > 1
+    ? `${pages.length} pages in ${brains.length} brain(s) — the same person (they share a phone or email), kept as separate pages. Say which brain a fact came from:`
+    : 'Their page:')
+  for (const p of pages) {
+    lines.push('', `## ${p.brain} — "${p.title}"  [ref: ${p.ref} · tier: ${p.tier}]`)
+    for (const s of p.sections ?? []) lines.push(`### ${s.heading}`, s.body ?? '')
+  }
+  return lines.join('\n')
+}
+
+/** Pure. A name that fits several contacts. */
+export function renderContactCandidates(candidates, name) {
+  const list = Array.isArray(candidates) ? candidates : []
+  return [`"${name}" fits ${list.length} contacts — pass \`page\` for the one you mean:`,
+    ...list.map((c) => `  · ${c.name} (${(c.brains ?? []).join(', ')}) — page: ${c.id}`)].join('\n')
+}

package/lib/server.mjs

@@ -32,6 +32,7 @@ import { formatSeriesRefusal, formatSeriesUpdated } from './series_render.mjs'
 import { formatSends } from './sends_render.mjs'
 import { applyLock, fetchLockState, lockedAnswerFor, lockStateWithin } from './locked_tools.mjs'
 import { filterUnshownSettling } from './settling_shown.mjs'
+import { renderContactBriefing, renderContactCandidates, renderContactList } from './contacts_render.mjs'
 
 // PAGE tiers (ADR-0071). Six for a PAGE; a RECORD keeps three (`privacy` on log_session and
 // set_record_privacy below) — an owner-relative tier is applied to a page's records when they are read
@@ -4165,6 +4166,76 @@ function renderNudge(payload) {
     },
   )
 
+  // ⭐ AGNOCLAST'S OWN CONTACT BOOK (ADR-0084; Theron, 2026-10-17). The person's book is every person page
+  // they can read, merged on a shared phone/email; `contact` is the briefing an AI reads before reaching out.
+  server.registerTool(
+    'my_contacts',
+    {
+      title: 'Your contacts — person pages you can read, merged',
+      description: 'The person\'s OWN Agnoclast contact book: every person page they can read, in every brain they are in. Pages in several brains that share a phone or email are ONE contact (same person, pages kept separate); a same-NAME match is listed as a question, never merged. Shows each contact\'s phone numbers and emails (marked when private to the person), the brains they are in, Call / Text an invite / Email, and where reaching out would be filed. Page text is not included — call `contact` for that before you reach out. Pass `query` to search by name, email or digits of a number. A phone number never rings anyone: a call reaches an Agnoclast account by its email.',
+      inputSchema: {
+        query: z.string().optional().describe('a name, an email address, or digits of a phone number'),
+        brain: z.string().optional().describe('the brain you are acting in (name or id) — decides where outreach files for a contact in several brains'),
+        limit: z.number().optional().describe('max contacts (default 50, max 200)'),
+        offset: z.number().optional().describe('skip this many (paging)'),
+        reach: z.boolean().optional().describe('also check who can be CALLED (uses the person\'s call-lookup budget; default false)'),
+      },
+    },
+    async ({ query, brain, limit, offset, reach }) => {
+      const q = typeof query === 'string' ? query.trim() : ''
+      let res
+      try {
+        res = q
+          ? await fetchCortex(`${BASE}/api/contacts/search`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ q, brain, limit, offset, reach: reach === true }),
+          })
+          : await fetchCortex(`${BASE}/api/contacts?${new URLSearchParams({
+            ...(brain ? { brain } : {}), ...(limit ? { limit: String(limit) } : {}), ...(offset ? { offset: String(offset) } : {}),
+            ...(reach ? { reach: '1' } : {}),
+          })}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      } catch (e) {
+        return toolError(`Could not read your contacts: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (res.status === 404) return toolError('This Agnoclast server has no contact book yet (it predates ADR-0084). Use grep / read_page for person pages.')
+      if (!res.ok) return toolError(`Could not read your contacts: ${out?.error ?? res.status}`)
+      return { content: [{ type: 'text', text: renderContactList(out, { query: q }) }] }
+    },
+  )
+
+  server.registerTool(
+    'contact',
+    {
+      title: 'One contact — identifiers AND their pages, before you reach out',
+      description: 'Brief yourself on one contact before a call, invite or email: their phone numbers and emails the person may see, EVERY person page of theirs the person can read (one per brain, labelled — the same person, kept separate, so say which brain a fact came from), and the ONE page the outreach should be filed on. If they are in several brains and none is obvious it says ASK: ask the person which brain this is for, then file the record on that one page only. Address them by `page` (from my_contacts, or a person page ref) or by `name`.',
+      inputSchema: {
+        page: z.string().optional().describe('a page id from my_contacts, or a person page ref from read_page'),
+        name: z.string().optional().describe('their name, when you have no page id'),
+        brain: z.string().optional().describe('the brain you are acting in (name or id), if any'),
+      },
+    },
+    async ({ page, name, brain }) => {
+      if (!page && !name) return toolError('Pass page or name')
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/contacts/briefing`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ page, name, brain }),
+        })
+      } catch (e) {
+        return toolError(`Could not read that contact: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (res.status === 409 && out?.error === 'ambiguous') return { content: [{ type: 'text', text: renderContactCandidates(out.candidates, name ?? page) }] }
+      if (res.status === 404 && out?.error === 'not_found') return { content: [{ type: 'text', text: `No contact of yours matches "${name ?? page}". my_contacts lists them; a person you have never written a page for is not a contact yet.` }] }
+      if (!res.ok) return toolError(`Could not read that contact: ${out?.error ?? res.status}`)
+      return { content: [{ type: 'text', text: renderContactBriefing(out) }] }
+    },
+  )
+
   server.registerTool(
     'set_summary',
     {
@@ -5516,23 +5587,27 @@ function renderNudge(payload) {
     {
       title: 'Claim a routing identifier on a page',
       description: 'Declare that a page is a Gate 4 attach HOME for an identifier (repo:owner/name or file:owner/name:path). Body [[repo:…]] stamps are navigation only and do NOT drive attach — use this instead. Prefer the narrowest id: mother pages own repo:; feature pages own file: paths. Do not copy every body mention into a routing claim. ' +
-        'PRIVATE CONTACT CLAIMS (ADR-0079): on a PERSON page you may claim `phone:<number>` (normalized to E.164, US default — `phone:(801) 636-7505` stores `phone:+18016367505`) or `email:<address>` (lowercased). These are visible ONLY to you — never in the page body, grep, or to other brain members — and they make your captured texts / mail from that contact propose that person page. This is the right place for a contact\'s number; never put it in page text.',
+        'CONTACT IDENTIFIERS (ADR-0079, ADR-0084): on a PERSON page you may claim `phone:<number>` (E.164, US default — `phone:(801) 636-7505` stores `phone:+18016367505`) or `email:<address>`. A NEW one is SHARED with everyone who can read that page, like a shared CRM (Theron, 2026-10-17), unless you pass `private: true` — then only you see it. Pass `private` explicitly to change one you added before; without it an existing claim keeps its visibility. Either way it is never in the page body or grep, and it files only YOUR captured texts/mail onto the page. This is the right place for a contact\'s number; never put it in page text.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the page kind'),
         name: z.string().optional().describe('page title (or pass ref)'),
         ref: z.string().optional().describe('node ref from read_page — prefer over name when available'),
         brain: z.string().optional().describe('brain label when the title is ambiguous across brains'),
-        identifier: z.string().describe('canonical identifier, e.g. repo:theronap/cortex, file:theronap/cortex:web/lib/engine/github_intake.ts, or on a person page phone:+18015550123 / email:someone@example.com (private to you)'),
+        identifier: z.string().describe('canonical identifier, e.g. repo:theronap/cortex, file:theronap/cortex:web/lib/engine/github_intake.ts, or on a person page phone:+18015550123 / email:someone@example.com'),
+        private: z.boolean().optional().describe('person-page phone:/email: only. true = only you see it; false = everyone who can read the page. Omit for a new one to be shared and an existing one to stay as it is.'),
       },
     },
-    async ({ kind, name, ref, brain, identifier }) => {
+    async ({ kind, name, ref, brain, identifier, private: isPrivate }) => {
       if (!name && !ref) return toolError('Pass name or ref')
+      // ADR-0084: a person page's phone/email is shared with its readers unless the person says private.
+      const contactClaim = kind === 'person' && /^(phone|email):/i.test(String(identifier).trim())
+      const sharing = contactClaim ? { shared: isPrivate !== true, sharing_explicit: typeof isPrivate === 'boolean' } : {}
       let res
       try {
         res = await fetchCortex(`${BASE}/api/brain/routing-identifiers`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ kind, name, ref, brain, identifier }),
+          body: JSON.stringify({ kind, name, ref, brain, identifier, ...sharing }),
         })
       } catch (e) {
         return toolError(`Could not set routing identifier: ${e.message}`)
@@ -5558,9 +5633,12 @@ function renderNudge(payload) {
           ? ` ${healed} existing record(s) ALREADY attached to this page as a result.`
           : ' 0 existing records attached — either nothing carries this identifier yet, or records do but belong to another owner (an identity claim only attaches your own).'
       const isContact = /^(phone|email):/.test(String(out?.set?.[0] ?? identifier).toLowerCase())
-      const privacyLine = isContact
-        ? ' This contact claim is PRIVATE to you: no other brain member can see it, and it is never rendered in the page. Your captured texts/mail from this contact will now propose this page.'
-        : ''
+      // Say what the SERVER did: one older than ADR-0084 ignores `shared` and keeps every claim private.
+      const privacyLine = !isContact
+        ? ''
+        : out?.shared === true
+          ? ` Everyone who can read this page can see and use this ${kind === 'person' ? 'contact detail' : 'identifier'} (shared; pass private: true to make a new one yours alone). It is never rendered in the page text, and it files only YOUR captured texts/mail here.`
+          : ' This contact claim is PRIVATE to you: no other brain member can see it, and it is never rendered in the page. Your captured texts/mail from this contact will now propose this page.'
       return { content: [{ type: 'text', text: `Routing identifier set on document ${out?.documentId ?? '?'}: ${set}.${healedLine} Future matching events will attach here too (body mentions alone will not).${privacyLine}` }] }
     },
   )

package/package.json

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