@theronap/agnoclast-mcp 0.9.214 → 0.9.216

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', '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',
   // live authoring core
   'authoring_context', 'author', 'log_session',

package/lib/filing_obligations.mjs

@@ -0,0 +1,96 @@
+// OBLIGATION 53bfd283 — A TEXT ANSWERS "DOES THIS ASK ANYONE FOR ANYTHING?" WHEN IT IS FILED.
+//
+// No extractor reads a text: extraction runs on session transcripts and handoffs (ADR-0059 §5.1), and a
+// text is opened for the first time by the agent that files it. Volunteering `propose_obligation` from
+// there was measured at ~10% for the same kind of ask (§5.6). So `intake_materialize` now carries the
+// answer itself, and the server refuses to file a text from this release on until it has one. `[]` is a
+// complete answer; silence is what is refused.
+//
+// The server checks every quote against the text it just unsealed, so a paraphrase is never written. This
+// file only does what the server cannot: split one call's list across the units of a batch, and refuse
+// loudly — with the reason — what the server would otherwise drop silently.
+
+import { buildProposal } from './propose_obligation.mjs'
+
+/**
+ * PURE. `obligations` as passed to intake_materialize → each unit's own list.
+ *
+ * `byUnit` is null when the caller passed no `obligations` at all, so the request carries no field and an
+ * older server behaves exactly as before. Otherwise EVERY unit gets a list, `[]` included: answering for
+ * the batch answers for each text in it. A quote must name its unit when the call files more than one —
+ * guessing which text a sentence came from is how it would be checked against the wrong one and dropped.
+ */
+export function obligationsForUnits(batch, list) {
+  if (list === undefined || list === null) return { byUnit: null, errors: [], notes: [] }
+  const byUnit = new Map(batch.map((id) => [id, []]))
+  const errors = []
+  const notes = []
+  for (const [i, o] of (Array.isArray(list) ? list : []).entries()) {
+    const id = o?.intakeItemId ?? (batch.length === 1 ? batch[0] : null)
+    if (!id) {
+      errors.push(`obligations[${i}]: name its intakeItemId — this call files ${batch.length} texts and a quote belongs to exactly one`)
+      continue
+    }
+    if (!byUnit.has(id)) {
+      errors.push(`obligations[${i}]: ${id} is not one of the units this call files`)
+      continue
+    }
+    const built = buildProposal(o)
+    if (built.error) {
+      errors.push(`obligations[${i}]: ${built.error}`)
+      continue
+    }
+    if (built.note) notes.push(`obligations[${i}]: ${built.note}`)
+    byUnit.get(id).push(built.candidate)
+  }
+  return { byUnit, errors, notes }
+}
+
+/** What the server says when a text was filed with no answer. Written for the agent holding the text. */
+export const OBLIGATIONS_UNANSWERED_TEXT =
+  'Not filed yet — a text must answer whether it asks anyone for anything. Read it, then call again with ' +
+  '`obligations`: one entry per ask, with `evidence` copied word for word from the text and `obligated_party` ' +
+  'self (the person whose texts these are), other, or none. Pass `[]` when it asks nothing. Nothing was written.'
+
+/**
+ * PURE. What a filing reports about its obligations answer, in words. Empty when the server sent nothing
+ * (no answer was given, or the server predates this), so an older server never reads as "asks nothing".
+ */
+export function renderFilingObligations(o) {
+  if (!o || typeof o !== 'object') return []
+  const lines = []
+  if (o.write === null) {
+    lines.push('⚠ The obligations write FAILED — the record was filed but nothing was proposed. Propose them again with propose_obligation.')
+  }
+  const proposed = o.write?.proposed ?? 0
+  const refreshed = o.write?.refreshed ?? 0
+  if (o.sent === 0) {
+    lines.push('Obligations: none — answered that this asks nothing of anyone.')
+  } else if (proposed || refreshed) {
+    lines.push(
+      `Obligations: proposed ${proposed}${refreshed ? `, updated ${refreshed}` : ''} — PROPOSALS the person confirms or ` +
+      'dismisses (my_obligations), never commitments they made.',
+    )
+  }
+  if (o.write?.undated) lines.push(`⚠ ${o.write.undated} of them has no date, so nothing will raise it by time.`)
+  if (o.write?.unhomed) lines.push(`⚠ ${o.write.unhomed} could not be placed: the record is on no page.`)
+  if (Array.isArray(o.unverified) && o.unverified.length) {
+    lines.push(
+      `⚠ NOT written — not in this text word for word: ${o.unverified.map((e) => `"${e}"`).join('; ')}. ` +
+      "Quote the text's own sentence (propose_obligation with this record id).",
+    )
+  }
+  if (o.malformed) lines.push(`⚠ ${o.malformed} malformed obligation(s) were dropped.`)
+  return lines
+}
+
+/** PURE. The same, folded onto one line for a batch's per-unit detail. */
+export function filingObligationsBrief(o) {
+  if (!o || typeof o !== 'object') return ''
+  if (o.write === null) return ' · ⚠ obligations write FAILED'
+  const bits = []
+  if (o.sent === 0) bits.push('asks nothing')
+  else if (o.write?.proposed) bits.push(`${o.write.proposed} obligation(s) proposed`)
+  if (Array.isArray(o.unverified) && o.unverified.length) bits.push(`⚠ ${o.unverified.length} quote(s) not in the text, not written`)
+  return bits.length ? ` · ${bits.join(', ')}` : ''
+}

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/server.mjs

@@ -25,6 +25,8 @@ import { renderObligations, renderPageObligations, tierReads, who } from './obli
 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'
 
 // PAGE tiers (ADR-0071). Six for a PAGE; a RECORD keeps three (`privacy` on log_session and
@@ -1273,6 +1275,18 @@ function renderNudge(payload) {
           'ADR-0077: one answer per open folder question from a refused call — exactly one of claim, decline or defer each. ' +
           'Send only after the server has listed the questions; claims and declines are written when the unit is filed.',
         ),
+        obligations: z.array(z.object({
+          intakeItemId: z.string().optional().describe('which unit the quote is from — required when this call files more than one'),
+          subject: z.string().describe('what must be done, one short phrase'),
+          evidence: z.string().describe('the sentence that asks for it, copied WORD FOR WORD from that text — the server checks'),
+          due_phrase: z.string().optional().describe('the words in the evidence that say WHEN ("before 5 tomorrow") — the server dates it from the text'),
+          due_at: z.string().optional().describe('YYYY-MM-DD only when the text states a date'),
+          obligated_party: z.enum(['self', 'other', 'none']).optional().describe('self (default) = the person whose texts these are owes it'),
+        })).optional().describe(
+          'REQUIRED FOR TEXTS: does this ask anyone for anything? One entry per ask — a request to the person, a ' +
+          'yes they gave, a time they agreed to. `[]` when it asks nothing. A text filed without it is refused. ' +
+          'Lands as PROPOSALS; a quote the text does not contain is reported and not written. Any other unit may send it too.',
+        ),
       },
     },
     async (args) => {
@@ -1280,6 +1294,11 @@ function renderNudge(payload) {
       // are looked up once and handled together, but "it shouldn't file all of them as one record". The
       // loop lives here, as it does for place_staged_record's batch: the route stays one unit per call.
       const batch = [...new Set([args.intakeItemId, ...(args.intakeItemIds ?? [])])].slice(0, 50)
+      // Obligation 53bfd283 — each unit's own answer. Refused HERE, before anything is filed, rather than
+      // sent for the server to drop: an agent told nothing believes the ask was surfaced.
+      const ob = obligationsForUnits(batch, args.obligations)
+      if (ob.errors.length) return toolError(`Nothing was filed — fix these obligations first:\n${ob.errors.map((e) => `  · ${e}`).join('\n')}`)
+      const obligationsFor = (id) => (ob.byUnit ? { obligations: ob.byUnit.get(id) ?? [] } : {})
       if (batch.length > 1 && args.mode !== 'preview') {
         const results = []
         for (const id of batch) {
@@ -1298,15 +1317,20 @@ function renderNudge(payload) {
                 // One placement is a decision about ONE conversation: the server refuses any id whose
                 // batch differs from the first id's, so a stray id is never filed onto these pages.
                 sameBatchAs: batch[0],
+                ...obligationsFor(id),
               }),
             })
             const o = await r.json().catch(() => null)
-            results.push({ id, ok: r.ok, detail: r.ok ? (o?.recordId ?? 'filed') : (o?.error ?? `HTTP ${r.status}`) })
+            const why = o?.error === 'obligations_unanswered'
+              ? 'not filed — a text needs `obligations` ([] when it asks nothing)'
+              : (o?.error ?? `HTTP ${r.status}`)
+            results.push({ id, ok: r.ok, detail: r.ok ? `${o?.recordId ?? 'filed'}${filingObligationsBrief(o?.obligations)}` : why })
           } catch (e) {
             results.push({ id, ok: false, detail: e.message })
           }
         }
-        return { content: [{ type: 'text', text: renderMaterializeBatch(results) }] }
+        const notes = ob.notes.length ? `\n${ob.notes.map((n) => `⚠ ${n}`).join('\n')}` : ''
+        return { content: [{ type: 'text', text: `${renderMaterializeBatch(results)}${notes}` }] }
       }
       // A preview goes to its OWN route: a server too old to know it answers 404, where the materialize
       // route would ignore a `mode` it does not know and publish.
@@ -1329,6 +1353,7 @@ function renderNudge(payload) {
           ...(args.governingPage ? { governingDocumentId: args.governingPage } : {}),
           ...(args.searchedForOtherHomes ? { searchedForOtherHomes: true } : {}),
           ...(args.folderDecisions?.length ? { folderDecisions: args.folderDecisions } : {}),
+          ...obligationsFor(args.intakeItemId),
         }),
       })
       if (!res.ok) {
@@ -1348,6 +1373,7 @@ function renderNudge(payload) {
               'Not filed yet — every page named is one this unit gets anyway, so this would publish it without adding anything of your judgment.',
             ))
           }
+          if (err === 'obligations_unanswered') return toolError(OBLIGATIONS_UNANSWERED_TEXT)
         }
         if (preview && res.status === 404) {
           return toolError('This server cannot preview a materialization yet — nothing was written. Materialize without mode, or wait for the server to update.')
@@ -1413,6 +1439,7 @@ function renderNudge(payload) {
       // filed onto. Never claimed by the server; the session decides.
       lines.push(...renderFolderDecisionsApplied(body?.folderDecisions))
       lines.push(...renderFolderClaimOffers(body?.folderClaimOffers))
+      lines.push(...renderFilingObligations(body?.obligations), ...ob.notes.map((n) => `⚠ ${n}`))
       if (body?.containerSkipped) {
         lines.push(`⚠ CONTAINER NOT APPLIED — ${body.containerSkipped}. The record exists but is not inside the event you named; place it with contain_record or leave it out.`)
       } else if (body?.contained === true) {
@@ -4496,10 +4523,12 @@ 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'),
       },
     },
-    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 }) => {
       const qs = new URLSearchParams()
+      if (container) qs.set('container', container)
       if (page) qs.set('page', page)
       if (match) qs.set('match', match)
       if (source) qs.set('source', source)
@@ -4525,6 +4554,41 @@ 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)) }] }
+    },
+  )
+
   // ── 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.214",
+  "version": "0.9.216",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {