@theronap/agnoclast-mcp 0.9.215 → 0.9.217

package/lib/editors/claude.mjs

@@ -30,8 +30,10 @@ 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', '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', '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',
   // live authoring core
   'authoring_context', 'author', 'log_session',
   // routine, reversible maintenance

package/lib/record_render.mjs

@@ -0,0 +1,53 @@
+// read_record — ONE record in full (Theron, 2026-10-07: "there's really no way to see what's inside a
+// container like a class for the transcript or any other associated records").
+//
+// list_records gives a title and a summary per row. That is the right shape for a list and the wrong one
+// for "what did the professor say": the transcript itself was not on the record at all until 2026-10-07,
+// and even now it lives in the record's content, which only GET /api/records/:id returns. This renders
+// that response — content, the pages it is filed on, the container around it, and, for a container, what
+// is inside — so an agent can walk a class session the way a person does on /record.
+
+/** Default cap on the content shown. A lecture runs ~50,000 characters; the client's reply budget is finite. */
+export const READ_RECORD_DEFAULT_CHARS = 40_000
+
+const SOURCE_LABEL = {
+  github: 'GitHub', email: 'Email', 'email-in': 'Email', gmail: 'Email', 'claude-code': 'Claude Code session',
+  imessage: 'Text messages', 'google-calendar': 'Calendar', 'agnoclast-calendar': 'Calendar',
+  handoff: 'Transcript or document', meeting: 'Meeting',
+}
+
+const label = (source) => SOURCE_LABEL[source] ?? source
+const line = (e) => `  · ${e.title || '(untitled)'} — ${label(e.source)} · ${e.occurredAt} — id ${e.id}`
+
+/** PURE. The tool's reply for one record. `maxChars` caps the content and says how much was left out. */
+export function renderRecord(rec, maxChars = READ_RECORD_DEFAULT_CHARS) {
+  if (!rec || typeof rec !== 'object') return 'No record came back.'
+  const cap = Number.isFinite(maxChars) && maxChars > 0 ? Math.trunc(maxChars) : READ_RECORD_DEFAULT_CHARS
+  const out = []
+  out.push(`# ${rec.title || '(untitled record)'}`)
+  out.push(`${label(rec.source)} · ${rec.occurredAt} · brain ${rec.brain?.name ?? rec.brain ?? '?'}${rec.superseded ? ' · ⚠ superseded by a newer version' : ''}`)
+  out.push(`id: ${rec.id}`)
+  out.push('')
+  const content = typeof rec.content === 'string' ? rec.content : ''
+  if (!content.trim()) {
+    out.push('(No content was captured for this record.)')
+  } else if (content.length > cap) {
+    out.push(content.slice(0, cap))
+    out.push(`\n… ${content.length - cap} more characters. Call read_record again with max_chars: ${content.length} to read all of it.`)
+  } else {
+    out.push(content)
+  }
+  out.push('')
+  const pages = Array.isArray(rec.pages) ? rec.pages : []
+  out.push(pages.length
+    ? `Filed on: ${pages.map((p) => `“${p.title}” (ref ${p.ref})`).join(' · ')}`
+    : 'Filed on: no page you can see.')
+  const inside = Array.isArray(rec.containedIn) ? rec.containedIn : []
+  if (inside.length) out.push(`Inside:\n${inside.map(line).join('\n')}`)
+  if (Array.isArray(rec.contains)) {
+    out.push(rec.contains.length
+      ? `Contains (${rec.contains.length}) — read any with read_record:\n${rec.contains.map(line).join('\n')}`
+      : 'Contains: nothing has been filed inside this container yet.')
+  }
+  return out.join('\n')
+}

package/lib/sends_render.mjs

@@ -0,0 +1,69 @@
+// `my_sends` — "did my email / text actually go out?" Rendered from GET /api/gmail/send-requests, which
+// lists only the CALLER's own requests (owner_auth_id), email and texts alike (ADR-0076: one table).
+//
+// WHY THIS EXISTS. Agents answered it with SQL against outbound_email_requests (Agnoclast page "Agent SQL
+// gap", 2026-10-07), because request_send_email hands back a review link and then goes silent: nothing
+// an agent could call said whether the send was approved, went out, failed, or expired.
+//
+// The message copy (`snapshot`) is deleted after 7 days (Privacy §11), so an old request legitimately
+// has no recipients or subject. That is said, not left blank.
+
+const STATE_WORD = {
+  pending: 'WAITING FOR YOUR APPROVAL',
+  approved: 'approved, about to send',
+  sending: 'sending now',
+  sent: 'SENT',
+  unconfirmed: 'sent, but delivery could not be confirmed',
+  refused: 'REFUSED by the send checks',
+  denied: 'you said no',
+  expired: 'EXPIRED unanswered',
+  discarded: 'discarded',
+}
+
+const OPEN = new Set(['pending', 'approved', 'sending'])
+const FAILED = new Set(['refused', 'unconfirmed', 'expired'])
+
+const when = (iso) => (iso ? String(iso).slice(0, 16).replace('T', ' ') + 'Z' : '—')
+
+/** Pure. Narrow the list the way the tool's arguments ask. */
+export function filterSends(requests, { state, channel } = {}) {
+  const list = Array.isArray(requests) ? requests : []
+  return list.filter((r) => {
+    if (channel && (r.channel ?? 'email') !== channel) return false
+    if (state === 'open') return OPEN.has(r.state)
+    if (state === 'failed') return FAILED.has(r.state)
+    if (state) return r.state === state
+    return true
+  })
+}
+
+/** Pure. One line per request, newest first, with what the person actually needs: where it stands. */
+export function formatSends(requests, opts = {}) {
+  const list = filterSends(requests, opts)
+  if (!list.length) {
+    return opts.state || opts.channel
+      ? 'No sends of yours match that filter.'
+      : 'You have no email or text send requests through Agnoclast.'
+  }
+  const waiting = list.filter((r) => r.state === 'pending').length
+  const lines = []
+  if (waiting) lines.push(`⚠ ${waiting} waiting for your approval — open https://agnoclast.com/email to decide.`, '')
+  for (const r of list) {
+    const s = r.snapshot
+    const kind = r.channel === 'imessage' ? 'text' : 'email'
+    const to = s?.to?.length ? s.to.join(', ') : `${r.recipientCount ?? '?'} recipient(s)`
+    const what = s
+      ? (kind === 'text' ? `"${String(s.text ?? '').replace(/\s+/g, ' ').slice(0, 60)}"` : `"${s.subject || '(no subject)'}"`)
+      : '(message copy deleted after 7 days)'
+    const head = `- [${kind}] ${STATE_WORD[r.state] ?? r.state} · to ${to} · ${what}`
+    const meta = [`asked ${when(r.createdAt)}`]
+    if (r.sentAt) meta.push(`sent ${when(r.sentAt)}`)
+    else if (r.state === 'pending') meta.push(`expires ${when(r.expiresAt)}`)
+    if (r.autoRule) meta.push(`auto-approved by your rule (${r.autoRule})`)
+    if (r.claimedBy) meta.push(`via ${r.claimedBy}`)
+    if (r.error) meta.push(`error: ${String(r.error).slice(0, 160)}`)
+    meta.push(`from ${r.account}`, `id:${r.id}`)
+    lines.push(head, `  ${meta.join(' · ')}`)
+  }
+  return lines.join('\n')
+}

package/lib/server.mjs

@@ -26,7 +26,9 @@ import { renderRemovalQuestion, renderRemoved } from './member_remove_render.mjs
 import { renderSettings } from './settings_render.mjs'
 import { renderConversationOffer, renderMaterializeBatch } from './intake_batch_render.mjs'
 import { obligationsForUnits, renderFilingObligations, filingObligationsBrief, OBLIGATIONS_UNANSWERED_TEXT } from './filing_obligations.mjs'
+import { renderRecord, READ_RECORD_DEFAULT_CHARS } from './record_render.mjs'
 import { formatCreated, formatDryRun, formatSources, homeFromArgs, pickSource, renderHomeProblem } from './custom_sources.mjs'
+import { formatSends } from './sends_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
@@ -4522,10 +4524,14 @@ function renderNudge(payload) {
         order: z.enum(['newest', 'oldest']).optional().describe('newest first (default), or oldest first to read a series in sequence'),
         offset: z.number().optional().describe('skip this many records — page through more than 50 by calling again with offset 50, 100…'),
         match: z.string().optional().describe('only records whose title or text contains this (case-insensitive, literal) — e.g. one book on a channel that carries several, one ticket in a queue'),
+        container: z.string().optional().describe('a container\'s record id (a class session, a meeting) — lists the records INSIDE it. read_record on the container shows the same list with its own content'),
+        person: z.string().optional().describe('a member\'s exact display name or email — only the records they created (within what you can see)'),
       },
     },
-    async ({ type, project, since_days, limit, session, page, source, order, offset, match }) => {
+    async ({ type, project, since_days, limit, session, page, source, order, offset, match, container, person }) => {
       const qs = new URLSearchParams()
+      if (container) qs.set('container', container)
+      if (person) qs.set('person', person)
       if (page) qs.set('page', page)
       if (match) qs.set('match', match)
       if (source) qs.set('source', source)
@@ -4551,6 +4557,128 @@ function renderNudge(payload) {
     },
   )
 
+  // read_record — ONE record in full, with what it sits inside and what sits inside it (Theron,
+  // 2026-10-07: "there's really no way to see what's inside a container"). Rendering: record_render.mjs.
+  server.registerTool(
+    'read_record',
+    {
+      title: 'Read one record in full',
+      description:
+        'Read ONE record by id: its full content as captured (a lecture or meeting transcript, a text thread, ' +
+        'an email\'s headers, a commit), the pages it is filed on, the container it sits inside (a class ' +
+        'session, a meeting), and, when it IS a container, every record inside it. Use it to open what ' +
+        'list_records, my_day or timeline_pull only summarize, and to walk a class session: read the session, ' +
+        'then read_record each id it lists. A record you may not read answers "not found", exactly like one ' +
+        'that does not exist.',
+      inputSchema: {
+        id: z.string().describe('the record id, from list_records, my_day, timeline_pull or another read_record'),
+        max_chars: z.number().optional().describe(`cap on the content shown (default ${READ_RECORD_DEFAULT_CHARS}); the reply says how much was left out`),
+      },
+    },
+    async ({ id, max_chars }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/records/${encodeURIComponent(id)}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      } catch (e) {
+        return toolError(`Could not read the record: ${e.message}`)
+      }
+      if (res.status === 404 || res.status === 400) return toolError(`No record ${id} that you can read.`)
+      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 the record: ${d.message}`)
+      }
+      const body = await res.json().catch(() => null)
+      return { content: [{ type: 'text', text: withAskNotice(renderRecord(body?.record, max_chars)) }] }
+    },
+  )
+
+  // ── the questions agents used to answer with SQL (Agnoclast page "Agent SQL gap", 2026-10-07) ──────
+  // Theron, 2026-10-07: "any information that I have felt the need to get about my own brains, but was
+  // not able to do it with Agnoclast tools … we either need to make tools for that, or …". Measured the
+  // same day: 3,967 owner-connection execute_sql calls since 2026-07-04, a recurring minority of them
+  // these four questions. Each tool answers as the caller (RLS), never wider.
+  const readText = async (what, url) => {
+    let res
+    try {
+      res = await fetchCortex(url, { headers: { Authorization: `Bearer ${TOKEN}` } })
+    } catch (e) {
+      return { error: toolError(`Could not ${what}: ${e.message}`) }
+    }
+    if (!res.ok) {
+      const body = await res.text()
+      let j = null
+      try { j = JSON.parse(body) } catch { /* not JSON */ }
+      if (res.status === 404 && j) return { error: toolError(`Could not ${what}: ${j.detail ?? j.error ?? 'not found'}`) }
+      return { error: toolError(`Could not ${what}: ${classify(res.status, res.headers.get('content-type'), body, res.headers.get('x-vercel-id')).message}`) }
+    }
+    return { json: await res.json() }
+  }
+
+  server.registerTool(
+    'record_status',
+    {
+      title: 'One record: where it landed and who can read it',
+      description: 'Where ONE record you can see LANDED and WHO CAN READ IT: the pages it is filed on and which one governs who can read it, who can read it in plain words and why YOU can, the class session or meeting it sits inside (or, if it IS one, how many records and recordings it holds), whether anything replaced it, and whether anyone has claimed it. Use it to answer "did my capture / filing land, and where?", "why can I see this?", "who else can read this?". To READ a record\'s text, use read_record. A record you cannot read is reported as not found — the same answer as one that does not exist.',
+      inputSchema: {
+        record_id: z.string().describe('the record id (uuid)'),
+      },
+    },
+    async ({ record_id }) => {
+      const r = await readText('read that record', `${BASE}/api/records/${encodeURIComponent(String(record_id).trim())}/status`)
+      if (r.error) return r.error
+      return { content: [{ type: 'text', text: r.json?.text ?? '' }] }
+    },
+  )
+
+  server.registerTool(
+    'my_connectors',
+    {
+      title: 'Is my data flowing? Connectors, what is landing, what is held',
+      description: 'Your data sources and whether they are working: each connector YOU connected (Gmail, Outlook, calendar, GitHub, Slack…) with its status, last sync and — leading the reply — any that are NOT syncing and how to fix it; what has actually LANDED per source per brain in the last 24h / 7d / 30d (counted over records you can read); and what ARRIVED but is held in no brain yet (staged or sealed). Use it for "is my email coming in?", "did Outlook come back after I reconnected?", "why haven\'t my texts shown up?". Counts and times only — never a title or body.',
+      inputSchema: {},
+    },
+    async () => {
+      const r = await readText('check your connectors', `${BASE}/api/connectors/health`)
+      if (r.error) return r.error
+      return { content: [{ type: 'text', text: r.json?.text ?? '' }] }
+    },
+  )
+
+  server.registerTool(
+    'brain_stats',
+    {
+      title: 'Usage stats for one brain',
+      description: 'The numbers about ONE brain you are in — the same ones its /stats page shows: pages and records, which features are used (meetings recorded, calendar, obligations, email and texts captured or sent, AI sessions…) all-time and in the last 30 days, what each member has done, obligations on time vs late vs overdue, and your own sends. Every number is counted over what YOU can open there; a brain owner/admin also gets whole-brain totals that include everyone\'s private items as numbers, never names. Use it for "how much have I captured this month?", "how many obligations did I finish late?", "who is actually using this brain?".',
+      inputSchema: {
+        brain: z.string().describe('the brain\'s name or org id, from my_brains'),
+      },
+    },
+    async ({ brain }) => {
+      const r = await readText('read brain stats', `${BASE}/api/brain-stats?brain=${encodeURIComponent(String(brain).trim())}`)
+      if (r.error) return r.error
+      return { content: [{ type: 'text', text: r.json?.text ?? '' }] }
+    },
+  )
+
+  server.registerTool(
+    'my_sends',
+    {
+      title: 'Did my email / text go out?',
+      description: 'Your send requests through Agnoclast — emails from your mailbox and texts from your Mac — and where each stands: waiting for your approval, sent (and when), refused by the checks, expired unanswered, or denied. Use it after request_send_email or send_imessage, or for "did that email to Dave actually go out?". Only your own requests. The message copy is deleted after 7 days, so older ones show recipients as a count.',
+      inputSchema: {
+        state: z.string().optional().describe("'open' (waiting / about to send), 'failed' (refused, unconfirmed, expired), or one exact state: pending, sent, denied, expired, refused…"),
+        channel: z.enum(['email', 'imessage']).optional().describe('only emails, or only texts'),
+        limit: z.number().optional().describe('how many recent requests to look through (default 50, max 200)'),
+      },
+    },
+    async ({ state, channel, limit }) => {
+      const n = Math.max(1, Math.min(Math.trunc(Number(limit ?? 50)) || 50, 200))
+      const r = await readText('list your sends', `${BASE}/api/gmail/send-requests?limit=${n}`)
+      if (r.error) return r.error
+      return { content: [{ type: 'text', text: formatSends(r.json?.requests, { state, channel }) }] }
+    },
+  )
+
   // ── custom sources: set up, list, re-home (Theron, 2026-09-29) ─────────────────────────────────
   // "I don't think it's that good of an idea to let the user do the whole setup without having an agent
   // involved." The agent can read the system being connected, describe what its data is ABOUT, and judge

package/package.json

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