@theronap/agnoclast-mcp 0.9.239 → 0.9.241

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/editors/claude.mjs

@@ -30,7 +30,7 @@ export function mergeClaudeMcp(existing, spec, token) {
 export const ALLOWED_TOOL_NAMES = [
   // read surface
   'grep', 'read_page', 'my_context', 'project_status', 'session_context', 'search_org',
-  'list_records', 'read_record', 'page_history', 'page_diff', 'timeline_pull', 'my_brains', 'my_sessions', 'writing_style',
+  'list_records', 'read_record', 'page_history', 'page_diff', 'timeline_pull', 'my_brains', 'my_sessions', 'token_activity', 'writing_style',
   'code_graph_query', 'my_retier_notices', 'list_page_grants', 'list_project_members', 'file_requests',
   // the questions agents used to answer with SQL (2026-10-07) — read-only, the caller's own view
   'record_status', 'my_connectors', 'brain_stats', 'my_sends', 'find_arrivals',

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
@@ -2363,7 +2364,9 @@ function renderNudge(payload) {
       const revs = out.revisions ?? []
       if (!revs.length) return { content: [{ type: 'text', text: `"${name}" (${k}) has no recorded version history yet.` }] }
       const lines = revs.map((r) => {
-        const who = r.actor_name ? ` · ${r.actor_name}` : ''
+        // "Theron via Frack" — the label only ever reaches the token's owner (bdb2339b phase 2).
+        const via = r.via_token_label ? ` via ${r.via_token_label}` : ''
+        const who = r.actor_name ? ` · ${r.actor_name}${via}` : (via ? ` ·${via}` : '')
         // change_kind first and bracketed so a column of [correct] is scannable — the whole point is
         // that a page with repeated corrections looks different at a glance from one that only grew.
         const what = r.change_kind ? ` · [${r.change_kind}]` : ''
@@ -2418,7 +2421,7 @@ function renderNudge(payload) {
         ? `# ${name} — rev ${d.to.revNo} (first version)`
         : `# ${name} — rev ${d.from.revNo} → rev ${d.to.revNo}`
       const meta = []
-      meta.push(`${String(d.to.createdAt).slice(0, 10)} · ${d.to.op}${d.to.changeKind ? ` · [${d.to.changeKind}]` : ''}${d.to.actorName ? ` · ${d.to.actorName}` : ''}`)
+      meta.push(`${String(d.to.createdAt).slice(0, 10)} · ${d.to.op}${d.to.changeKind ? ` · [${d.to.changeKind}]` : ''}${d.to.actorName ? ` · ${d.to.actorName}${d.to.viaTokenLabel ? ` via ${d.to.viaTokenLabel}` : ''}` : ''}`)
       if (d.to.reason) meta.push(`reason: ${d.to.reason}`)
       if (d.to.sessionKey) meta.push(`session: ${String(d.to.sessionKey).slice(0, 24)}`)
       const body = []
@@ -4165,6 +4168,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',
     {
@@ -5299,6 +5372,46 @@ function renderNudge(payload) {
     },
   )
 
+  server.registerTool(
+    'token_activity',
+    {
+      title: 'What this agent token has done',
+      description: "Audit YOUR OWN recent activity through the token you are connected with: tool calls, wiki page edits, record placements and intake discards, newest first. Use it to report back what you did (\"what did I discard today?\"), or to check a run before handing off. Self-only: it reads the CALLING token's activity and never another agent's — the person audits all their tokens from Connect → Agent tokens. Discards are content-free by design, so they name the source, not the item. Errors if you are not connected with an agent token (console sessions have none).",
+      inputSchema: {
+        days: z.number().int().optional().describe('how far back (default 7, max 30)'),
+        kinds: z.array(z.enum(['call', 'edit', 'placement', 'discard'])).optional().describe('only these kinds (default all)'),
+        limit: z.number().int().optional().describe('max items (default 100, max 500)'),
+      },
+    },
+    async ({ days, kinds, limit }) => {
+      let res
+      try {
+        const qs = new URLSearchParams({
+          ...(days ? { days: String(days) } : {}), ...(limit ? { limit: String(limit) } : {}),
+          ...(kinds?.length ? { kinds: kinds.join(',') } : {}),
+        })
+        res = await fetchCortex(`${BASE}/api/me/token-activity?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      } catch (e) {
+        return toolError(`Could not read this token's activity: ${e.message}`)
+      }
+      if (res.status === 400) return { content: [{ type: 'text', text: 'You are not connected with an agent token, so there is no per-token activity to show. The person can see every token\'s activity under Connect → Agent tokens.' }] }
+      if (!res.ok) {
+        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+        return toolError(`Could not read this token's activity: ${d.message}`)
+      }
+      const out = await res.json()
+      const name = out.token?.label ?? 'this token'
+      const items = out.items ?? []
+      if (!items.length) return { content: [{ type: 'text', text: `${name}: no activity in the last ${days ?? 7} day(s).` }] }
+      const counts = {}
+      for (const i of items) counts[i.kind] = (counts[i.kind] ?? 0) + 1
+      const lines = items.map((i) =>
+        `- ${String(i.at).slice(0, 16).replace('T', ' ')} · ${i.kind} · ${i.what ?? '—'}${i.detail ? ` · ${i.detail}` : ''}${i.reason ? ` — ${i.reason}` : ''}`)
+      const summary = Object.entries(counts).map(([k, n]) => `${n} ${k}`).join(' · ')
+      return { content: [{ type: 'text', text: `# ${name} — activity, last ${days ?? 7} day(s), newest first (UTC)\n${summary}\n\n${lines.join('\n')}` }] }
+    },
+  )
+
   server.registerTool(
     'my_sessions',
     {
@@ -5516,23 +5629,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 +5675,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.239",
+  "version": "0.9.241",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {