@theronap/agnoclast-mcp 0.9.220 → 0.9.222

package/lib/arrivals_notice.mjs

@@ -101,6 +101,20 @@ export function formatPressing(pressing) {
       const more = count > names.length ? ` … and ${count - names.length} more` : ''
       lines.push(`⏰ Due today (${count}): ${names.join(' · ')}${more}`)
     }
+    // 2026-10-08 — WHAT TO BE WORKING ON: obligations whose work window is open, soonest deadline first.
+    // Theron: "that is the thing that they should be working on in the time frame in advance of that
+    // thing." Once a day. A window that opened in the last day is marked so the start is not missed.
+    else if (p?.kind === 'work_now') {
+      const count = Number(p.count) || 0
+      if (!count) continue
+      const names = (Array.isArray(p.names) ? p.names : []).map((n) => {
+        const due = String(n?.due ?? '').replace(/\s+/g, ' ').trim().slice(0, 40)
+        const done = n?.maybeDone ? ' — may ALREADY BE DONE; ask' : ''
+        return `${named(n?.text)} (${n?.opened ? 'starts today — ' : ''}${due ? `due ${due}` : 'due soon'})${done}`
+      })
+      const more = count > names.length ? ` … and ${count - names.length} more` : ''
+      lines.push(`🧭 Work on now (${count}): ${names.join(' · ')}${more}`)
+    }
     // ADR-0073 §2.7 — a hand-off, said once to the one person it concerns. Names and notes are other
     // people's text: quoted and bounded like every title above.
     else if (p?.kind === 'asked') {
@@ -140,7 +154,8 @@ export function pressingAcks(pressing) {
   for (const p of Array.isArray(pressing) ? pressing : []) {
     if (typeof p?.subject !== 'string' || typeof p?.bucket !== 'string') continue
     const handoff = p.kind === 'asked' || p.kind === 'given' || p.kind === 'declined' || p.kind === 'lapsed'
-    if (p.kind === 'event' || p.kind === 'due_soon' || handoff || (p.kind === 'due_today' && Number(p.count) > 0)) {
+    const rollup = (p.kind === 'due_today' || p.kind === 'work_now') && Number(p.count) > 0
+    if (p.kind === 'event' || p.kind === 'due_soon' || handoff || rollup) {
       out.push({ subject: p.subject, bucket: p.bucket })
     }
   }

package/lib/obligations_render.mjs

@@ -152,5 +152,11 @@ function describeDue(o, now) {
   const what = o.dueAllDay ? `${day} (all day)` : `${day} ${o.dueAt.slice(11, 16)}`
   if (after <= now) return `OVERDUE ${what}`
   if (o.dueAllDay && at <= now) return `DUE TODAY ${what}`
-  return `due ${what}`
+  return `due ${what}${windowNote(o.workFrom, now)}`
+}
+
+// 2026-10-08 — when work should start. Absent on a server older than work windows: nothing is said.
+function windowNote(workFrom, now) {
+  if (!workFrom) return ''
+  return new Date(workFrom).getTime() <= now ? ` · IN ITS WORK WINDOW since ${String(workFrom).slice(0, 10)}` : ` · work from ${String(workFrom).slice(0, 10)}`
 }

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.')
@@ -2976,25 +2985,26 @@ function renderNudge(payload) {
     'track_obligation',
     {
       title: 'Record something you owe',
-      description: "Record something you owe: a subject, the page or pages it is about, optionally when it comes due, optionally whose reply would discharge it. ⚠ EVERY OBLIGATION LIVES ON A PAGE, CHOSEN NOW. `pages` is required: READ the page this is about first (read_page prints its `ref:`), then pass that ref — several when it genuinely belongs on several. Never guess a page to get past the check, and never default to the person's own page: if you cannot tell where it belongs, ask them. A page says where the obligation is FOUND, not who can see it: it is visible to its owner only unless the person later widens it (`set_obligation_tier`). ⚠ ONLY A DATE MAKES IT COME BACK. A DATED obligation is raised to the person's sessions by time, unasked, BEFORE it lapses: counted on the day it is due, and named when a stated clock time is within the hour. Once late it is never raised again, and an UNDATED one is never raised by anything — it surfaces only when someone asks with my_obligations. ⚠ NEVER INVENT A DUE DATE — and that matters more now, because an invented date will interrupt someone. Omit due_at when there genuinely is no deadline (a standing obligation); a guessed date is indistinguishable from a real one the moment it is stored, and it is the direct route to nagging about something that was never actually late. `anchor_identifier` is the useful part: give it the counterparty's address as `email:someone@example.com` and any record arriving from them is automatically offered as evidence that this may be done — computed when the record lands, not by a scanner.",
+      description: "Record something you owe: a subject, the page or pages it is about, optionally when it comes due, optionally whose reply would discharge it. ⚠ EVERY OBLIGATION LIVES ON A PAGE, CHOSEN NOW. `pages` is required: READ the page this is about first (read_page prints its `ref:`), then pass that ref — several when it genuinely belongs on several. Never guess a page to get past the check, and never default to the person's own page: if you cannot tell where it belongs, ask them. A page says where the obligation is FOUND, not who can see it: it is visible to its owner only unless the person later widens it (`set_obligation_tier`). ⚠ ONLY A DATE MAKES IT COME BACK. A DATED obligation is raised to the person's sessions by time, unasked, BEFORE it lapses: counted on the day it is due, and named when a stated clock time is within the hour. ⚠ A DEADLINE IS NOT WHEN TO START: pass `work_from` when the work needs lead time (a 10-day project opens 10 days ahead; an exam, days of study). From then it is named daily as \"work on now\", and once on the desktop when it opens. Once late it is never raised again, and an UNDATED one is never raised by anything — it surfaces only when someone asks with my_obligations. ⚠ NEVER INVENT A DUE DATE — and that matters more now, because an invented date will interrupt someone. Omit due_at when there genuinely is no deadline (a standing obligation); a guessed date is indistinguishable from a real one the moment it is stored, and it is the direct route to nagging about something that was never actually late. `anchor_identifier` is the useful part: give it the counterparty's address as `email:someone@example.com` and any record arriving from them is automatically offered as evidence that this may be done — computed when the record lands, not by a scanner.",
       inputSchema: {
         subject: z.string().describe('what is owed, in your own words'),
         pages: z.array(z.string()).min(1).describe('REQUIRED. The `ref:` of each page this obligation is about, exactly as read_page prints it. Read the page first; do not guess.'),
         for: z.string().optional().describe('ONLY when it is someone ELSE who should owe this: their email address, or their name as it appears in this brain. Omit for something the person owes themselves. You do not choose whether it is assigned or requested — the reporting line does.'),
         note: z.string().optional().describe('with `for`: a short note to the person it is given to'),
         due_at: z.string().optional().describe('ISO 8601. OMIT when there is no real deadline — never guess one.'),
+        work_from: z.string().optional().describe('ISO 8601: when work should START — the window opens (a bare date = the start of that day). Needs due_at, and must come before it. Estimate it from what the work involves; omit for things needing no lead time.'),
         anchor_identifier: z.string().optional().describe('e.g. "email:ben@example.com" — records from them become evidence this may be done'),
         source_record_id: z.string().optional().describe('the record this came from, if any'),
         brain: z.string().optional().describe('required only if you belong to more than one brain'),
       },
     },
-    async ({ subject, pages, due_at, anchor_identifier, source_record_id, brain, for: giveTo, note: giveNote }) => {
+    async ({ subject, pages, due_at, work_from, anchor_identifier, source_record_id, brain, for: giveTo, note: giveNote }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/obligations`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ subject, pages, dueAt: due_at, anchorIdentifier: anchor_identifier, sourceRecordId: source_record_id, brain, for: giveTo, note: giveNote }),
+          body: JSON.stringify({ subject, pages, dueAt: due_at, workFrom: work_from, anchorIdentifier: anchor_identifier, sourceRecordId: source_record_id, brain, for: giveTo, note: giveNote }),
         })
       } catch (e) { return toolError(`Could not reach obligations: ${e.message}`) }
       const out = await res.json().catch(() => null)
@@ -3002,7 +3012,8 @@ function renderNudge(payload) {
       // What will actually happen, stated per case: a promise of a nudge that never comes is worse
       // than no promise, and so is "nothing will nudge you" over something that now will.
       const nudge = due_at
-        ? 'It will be raised to your sessions on the day it is due' + (/T\d{2}:\d{2}/.test(due_at) ? ', and again when it is within the hour.' : '.')
+        ? (work_from ? `From ${work_from.slice(0, 10)} it is named daily as "work on now" (and once on the desktop). ` : '')
+          + 'It will be raised to your sessions on the day it is due' + (/T\d{2}:\d{2}/.test(due_at) ? ', and again when it is within the hour.' : '.')
         : 'It has no date, so nothing will raise it \u2014 ask with my_obligations.'
       const note = anchor_identifier
         ? `\nRecords carrying ${anchor_identifier} will be offered as evidence this is done. ${nudge}`
@@ -3020,6 +3031,38 @@ function renderNudge(payload) {
     },
   )
 
+  server.registerTool(
+    'set_obligation_window',
+    {
+      title: 'Set when work on an obligation should start',
+      description: "Open, move or remove an obligation's WORK WINDOW — when work on it should start, not when it is due (2026-10-08). From that moment until it is late, it is named once a day in the person's sessions as \"work on now\", soonest deadline first, and announced once on the desktop when the window opens. Use it when you learn what the work involves after it was recorded: \"it needs ten consecutive days of observation\" opens the window ten days before the deadline, whatever was guessed at capture; \"study for the final\" might open five days ahead. A bare date opens it at the start of that day in the owner's zone. It needs a due date and must come before it. Pass work_from null to remove the window. Only the owner can set it, and only while the obligation is open. A proposal (unconfirmed) is never raised by its window.",
+      inputSchema: {
+        obligation_id: z.string().describe('from my_obligations'),
+        work_from: z.string().nullable().describe('ISO 8601 date or date-time when work should start; null removes the window'),
+      },
+    },
+    async ({ obligation_id, work_from }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/obligations/window`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ obligationId: obligation_id, workFrom: work_from ?? null }),
+        })
+      } catch (e) { return toolError(`Could not reach obligations: ${e.message}`) }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return toolError(`Could not set the window: ${out?.detail ?? out?.error ?? res.status}`)
+      return {
+        content: [{
+          type: 'text',
+          text: out.workFrom
+            ? `Window set: work on it from ${out.workFrom}. From then until it is due it is named daily as "work on now".`
+            : 'Window removed: it is raised only on the day it is due.',
+        }],
+      }
+    },
+  )
+
   server.registerTool(
     'give_obligation',
     {
@@ -4571,13 +4614,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 +4641,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.220",
+  "version": "0.9.222",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {