@theronap/agnoclast-mcp 0.9.219 → 0.9.221

package/lib/record_render.mjs

@@ -10,6 +10,12 @@
 /** 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
 
+/** What read_record returns of a transcript (Theron, 2026-10-08: "the agent should first look at the notes"). */
+export const READ_RECORD_PARTS = ['notes', 'transcript', 'all']
+
+/** Sources whose content is a transcript (web/lib/engine/transcript_retention.ts TRANSCRIPT_KEPT_SOURCES). */
+const TRANSCRIPT_SOURCES = new Set(['handoff', 'meeting'])
+
 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',
@@ -19,8 +25,15 @@ const SOURCE_LABEL = {
 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) {
+/**
+ * PURE. The tool's reply for one record. `maxChars` caps the content and says how much was left out.
+ *
+ * TWO LAYERS ON A TRANSCRIPT (Theron, 2026-10-08): a meeting or lecture carries NOTES (the gist, decisions,
+ * action items, written by whoever filed it) and the full transcript. By default a record WITH notes returns
+ * the notes and says how long the transcript is, so a session gets the gist without reading 50,000
+ * characters; `part: "transcript"` or `"all"` returns the text. A record without notes is unchanged.
+ */
+export function renderRecord(rec, maxChars = READ_RECORD_DEFAULT_CHARS, part = 'notes') {
   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 = []
@@ -29,14 +42,28 @@ export function renderRecord(rec, maxChars = READ_RECORD_DEFAULT_CHARS) {
   out.push(`id: ${rec.id}`)
   out.push('')
   const content = typeof rec.content === 'string' ? rec.content : ''
-  if (!content.trim()) {
+  const notes = typeof rec.notes === 'string' && rec.notes.trim() ? rec.notes.trim() : null
+  const want = READ_RECORD_PARTS.includes(part) ? part : 'notes'
+  if (notes && want !== 'transcript') {
+    out.push('## Notes')
+    out.push(notes)
+    out.push('')
+  }
+  if (notes && want === 'notes') {
+    out.push(`Full transcript: ${content.length.toLocaleString('en-US')} characters, not shown. Call read_record with part: "transcript" when you need the exact words; grep and search already cover it.`)
+  } else if (!content.trim()) {
     out.push('(No content was captured for this record.)')
   } else if (content.length > cap) {
+    if (notes) out.push('## Full transcript')
     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 {
+    if (notes) out.push('## Full transcript')
     out.push(content)
   }
+  if (!notes && TRANSCRIPT_SOURCES.has(rec.source) && content.length > 2000) {
+    out.push(`\n(No notes on this transcript yet. If it is yours, write them with set_record_notes: the gist, decisions and action items, names spelled right.)`)
+  }
   out.push('')
   const pages = Array.isArray(rec.pages) ? rec.pages : []
   out.push(pages.length

package/lib/server.mjs

@@ -26,7 +26,7 @@ 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 { renderRecord, READ_RECORD_DEFAULT_CHARS, READ_RECORD_PARTS } from './record_render.mjs'
 import { formatCreated, formatDryRun, formatSources, homeFromArgs, pickSource, renderHomeProblem } from './custom_sources.mjs'
 import { formatSends } from './sends_render.mjs'
 
@@ -1234,6 +1234,7 @@ function renderNudge(payload) {
         'Name the governing page with governingPage (one of documentIds, never a person page) — otherwise the ranking picks it. ' +
         'Pass mode "preview" first when your choice differs from the claim\'s proposal: it returns the pages, the governing page and the tier this exact call would produce, and writes nothing. Never writes private intake into search/history before this call. ' +
         '⚠ ADR-0051: a unit does not finish until you looked for its OTHER homes. A call whose documentIds add nothing beyond the deterministic homes it gets anyway is REFUSED once — name the pages this unit is about (the design it implements, the project, the person), or go look, or say you looked with searchedForOtherHomes. ' +
+        '⚠ A meeting or lecture TRANSCRIPT files with NOTES in `summary` (Theron, 2026-10-08): the gist, decisions, action items and dates, names spelled right. Without them the call is REFUSED; the transcript itself is kept on the record unchanged. ' +
         '⚠ ADR-0077: a GitHub commit or PR does not finish until every changed path has an answer. If a changed file\'s deepest folder (or, in a grab-bag folder like web/lib/engine/ or db/supabase/, the file itself) has no claim and no decline, the call is REFUSED with the open questions; answer each in folderDecisions and call again.',
       inputSchema: {
         intakeItemId: z.string().describe('intake item uuid'),
@@ -1246,7 +1247,10 @@ function renderNudge(payload) {
         orgId: z.string().describe('destination brain org uuid'),
         documentIds: z.array(z.string()).optional().describe('additional pages in orgId — each a page `ref:` exactly as read_page shows it, or a brain_documents id (deterministic homes are merged automatically)'),
         title: z.string().optional(),
-        summary: z.string().optional(),
+        summary: z.string().optional().describe(
+          'what future retrieval reads first. For a meeting or lecture TRANSCRIPT these are its NOTES, and they are required: ' +
+          'a few lines of gist, then decisions, action items and dates, with names spelled right. The transcript is kept as it is.',
+        ),
         source: z.string().optional(),
         recordType: z.string().optional(),
         dedupeKey: z.string().optional(),
@@ -1375,6 +1379,11 @@ function renderNudge(payload) {
             ))
           }
           if (err === 'obligations_unanswered') return toolError(OBLIGATIONS_UNANSWERED_TEXT)
+          if (err === 'notes_required') {
+            let parsed = null
+            try { parsed = JSON.parse(body) } catch { /* handled above */ }
+            return toolError(`Not filed yet: this unit is a transcript and ${parsed?.problem ?? 'it has no notes'}. ${parsed?.detail ?? 'Pass summary as the notes and call again.'}`)
+          }
         }
         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.')
@@ -4571,13 +4580,21 @@ function renderNudge(payload) {
         '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.',
+        'that does not exist. ' +
+        'A meeting or lecture transcript has TWO LAYERS: notes (the gist, decisions, action items) and the full ' +
+        'transcript. By default you get the NOTES and the transcript\'s length; read the notes first, and ask for ' +
+        'part: "transcript" only when you need the exact words. To FIND something said in a meeting, grep and ' +
+        'search already cover the transcript.',
       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`),
+        part: z.enum(READ_RECORD_PARTS).optional().describe(
+          'for a transcript with notes: "notes" (default) = the notes only; "transcript" = the full text only; "all" = both. ' +
+          'A record without notes always returns its content.',
+        ),
       },
     },
-    async ({ id, max_chars }) => {
+    async ({ id, max_chars, part }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/records/${encodeURIComponent(id)}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
@@ -4590,7 +4607,46 @@ function renderNudge(payload) {
         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)) }] }
+      return { content: [{ type: 'text', text: withAskNotice(renderRecord(body?.record, max_chars, part)) }] }
+    },
+  )
+
+  // set_record_notes — write the NOTES layer of one of your own transcripts (Theron, 2026-10-08: "two
+  // layers … a summary and notes from the transcript … the full transcript"). The server keeps the
+  // before-state in record history and refuses anything that is not your own kept transcript.
+  server.registerTool(
+    'set_record_notes',
+    {
+      title: 'Write the notes on a transcript record',
+      description:
+        'Write or rewrite the NOTES on one of your own meeting or lecture transcripts: the layer read_record shows ' +
+        'before the transcript. Read the transcript first (read_record part: "transcript"). Good notes: a few lines of ' +
+        'gist, then decisions, action items and dates, with people\'s names spelled correctly (check them against person ' +
+        'pages; speech recognition misspells names). Never change the transcript itself: obligations quote it word for ' +
+        'word. Only your own records, and only transcripts; anything else answers not found or not a transcript.',
+      inputSchema: {
+        record_id: z.string().describe('the transcript record id'),
+        notes: z.string().describe('the notes, in plain text or simple markdown; the short layer, so well under 12,000 characters'),
+      },
+    },
+    async ({ record_id, notes }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/records/${encodeURIComponent(record_id)}/notes`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ notes }),
+        })
+      } catch (e) {
+        return toolError(`Could not reach Agnoclast: ${e.message}`)
+      }
+      const body = await res.json().catch(() => ({}))
+      if (res.ok && body?.ok) return { content: [{ type: 'text', text: `Notes saved on ${record_id}. read_record now shows them before the transcript.` }] }
+      if (res.status === 404 && !body?.error) return toolError('This server does not take transcript notes yet. Nothing was written.')
+      if (res.status === 404) return toolError(`No transcript ${record_id} of yours. Notes go only on your own records.`)
+      if (res.status === 409) return toolError(`${record_id} is not a transcript (${body?.detail ?? 'no kept text'}). Nothing was written.`)
+      if (res.status === 422) return toolError(`Not saved: ${body?.detail ?? 'the notes were refused'}.`)
+      return toolError(`Could not save the notes: HTTP ${res.status} ${JSON.stringify(body)}`)
     },
   )
 

package/package.json

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