@theronap/cortex-mcp 0.9.126 → 0.9.128

package/lib/server.mjs

@@ -1993,6 +1993,231 @@ function renderNudge(payload) {
     },
   )
 
+  server.registerTool(
+    'obligations_from_calendar',
+    {
+      title: 'Meetings that ended and were never written up',
+      description: 'Turn meetings that have already ENDED into "capture what came out of this" obligations. ⚠ THE OBLIGATION IS NOT "ATTEND" — your calendar already does that, and putting every scheduled meeting into your obligations list would bury it (90 of 120 calendar records are recurring birthdays). The gap this fills is real and documented: meeting substance lands wherever the session that heard about it happened to be working, and a walkthrough with no note at all is the normal outcome. ⚠ DRY-RUN BY DEFAULT — it reports what it WOULD create, including every meeting it skipped and why, and writes nothing until apply: true. Excluded on purpose: meetings with no attendee but you (a birthday or a solo hold owes nobody anything), all-day markers, cancelled events, anything with no recorded end, and anything outside the lookback window — no backfill, because obligations nobody will ever action are how a list stops being read. Each one is discharged by a captured transcript ARRIVING, never by one being absent.',
+      inputSchema: {
+        lookback_days: z.number().optional().describe('how far back to sweep (default 14, max 90)'),
+        apply: z.boolean().optional().describe('false/absent = dry run (default). true actually creates them.'),
+      },
+    },
+    async ({ lookback_days, apply }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/obligations/from-calendar`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ lookbackDays: lookback_days, apply: apply === true }),
+        })
+      } catch (e) { return toolError(`Could not reach the producer: ${e.message}`) }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return toolError(`Could not run: ${out?.error ?? res.status}`)
+
+      const cands = out?.candidates ?? []
+      const eligible = cands.filter((c) => !c.skipped)
+      const lines = []
+      if (out.mode === 'dry-run') {
+        lines.push(`DRY RUN \u2014 nothing written. ${out.scanned} meeting(s) scanned, ${eligible.length} would become obligations.`)
+      } else {
+        lines.push(`${out.created} obligation(s) created from ${out.scanned} meeting(s) scanned.`)
+      }
+      if (eligible.length) {
+        lines.push('', 'Would track:')
+        for (const c of eligible.slice(0, 15)) {
+          lines.push(`  ${c.endedAt.slice(0, 10)}  ${c.title ?? '(untitled)'}  \u2014 ${c.attendees.length} attendee(s)`)
+        }
+      }
+      // \u26a0 THE SKIPS ARE PRINTED, NOT SUMMARISED AWAY. A producer that silently drops most of its
+      // input reads as "there was nothing to do", which is indistinguishable from a broken filter.
+      const skipped = cands.filter((c) => c.skipped)
+      if (skipped.length) {
+        const byReason = {}
+        for (const c of skipped) byReason[c.skipped] = (byReason[c.skipped] ?? 0) + 1
+        lines.push('', `Skipped ${skipped.length}:`)
+        for (const [reason, n] of Object.entries(byReason).sort((a, b) => b[1] - a[1])) {
+          lines.push(`  ${n}  ${reason}`)
+        }
+      }
+      if (out.mode === 'dry-run' && eligible.length) lines.push('', 'Re-run with apply: true to create them.')
+      return { content: [{ type: 'text', text: lines.join('\n') }] }
+    },
+  )
+
+  server.registerTool(
+    'my_obligations',
+    {
+      title: 'What I owe',
+      description: 'What you owe — every open obligation across your brains, soonest-due first. The answer to "what am I on the hook for", which until now was spread across four unrelated mechanisms (red-links, the unclaimed backlog, "Open threads" prose in ~367 page sections, and session logs) with no way to query any of them as work. ⚠ READ THE EVIDENCE LINE. An obligation may carry records that MIGHT mean it is already done — a reply from the person you were waiting on, a merged PR. Evidence never closes anything, because passive signals only ever observe successes and failure emits silence, so treating them as proof would close work that never happened. It is there so you ASK "a reply came in — is this done?" instead of telling someone they still owe something they finished last week. Nagging about finished work is the expensive error: it teaches the reader the whole channel is noise.',
+      inputSchema: {
+        closed: z.boolean().optional().describe('true = also show discharged/cancelled ones'),
+        limit: z.number().optional().describe('default 50'),
+      },
+    },
+    async ({ closed, limit }) => {
+      let res
+      try {
+        const qs = new URLSearchParams()
+        if (closed) qs.set('closed', 'true')
+        if (limit) qs.set('limit', String(limit))
+        res = await fetchCortex(`${BASE}/api/obligations?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      } catch (e) { return toolError(`Could not reach obligations: ${e.message}`) }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return toolError(`Could not list: ${out?.error ?? res.status}`)
+      const obs = out?.obligations ?? []
+      if (!obs.length) return { content: [{ type: 'text', text: 'Nothing open.' }] }
+
+      const now = Date.now()
+      const lines = [`${obs.length} open:`, '']
+      for (const o of obs) {
+        const overdue = o.dueAt && new Date(o.dueAt).getTime() <= now
+        const when = o.dueAt ? `${overdue ? 'OVERDUE ' : 'due '}${o.dueAt.slice(0, 10)}` : 'no deadline'
+        lines.push(`${o.id}`)
+        lines.push(`  ${o.subject}  \u2014 ${when}${o.state === 'snoozed' ? ' (snooze expired)' : ''}`)
+        // \u26a0 EVIDENCE IS RENDERED AS A QUESTION, NEVER AS A VERDICT. The phrasing is the feature:
+        // "is this done?" costs the reader a second, "you still owe this" about finished work costs
+        // the channel its credibility.
+        if (o.evidence?.length) {
+          lines.push(`  \u2753 ${o.evidence.length} record(s) suggest this may already be done \u2014 check, then resolve_obligation:`)
+          for (const e of o.evidence.slice(0, 3)) {
+            lines.push(`      ${e.occurredAt.slice(0, 10)}  ${e.title ?? '(untitled)'}${e.viaIdentifier ? `  [${e.viaIdentifier}]` : ''}`)
+          }
+        }
+        lines.push('')
+      }
+      return { content: [{ type: 'text', text: lines.join('\n') }] }
+    },
+  )
+
+  server.registerTool(
+    'track_obligation',
+    {
+      title: 'Record something you owe',
+      description: "Record something you owe: a subject, optionally when it comes due, optionally whose reply would discharge it. ⚠ RECORDING IS NOT REMINDING — this stores an obligation and schedules nothing; nothing will nudge you about it. ⚠ NEVER INVENT A DUE DATE. 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'),
+        due_at: z.string().optional().describe('ISO 8601. OMIT when there is no real deadline — never guess one.'),
+        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, due_at, anchor_identifier, source_record_id, brain }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/obligations`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ subject, dueAt: due_at, anchorIdentifier: anchor_identifier, sourceRecordId: source_record_id, brain }),
+        })
+      } catch (e) { return toolError(`Could not reach obligations: ${e.message}`) }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return toolError(`Could not record: ${out?.detail ?? out?.error ?? res.status}`)
+      const note = anchor_identifier
+        ? `\nRecords carrying ${anchor_identifier} will be offered as evidence this is done. Nothing will nudge you.`
+        : '\nNothing will nudge you \u2014 ask with my_obligations.'
+      return { content: [{ type: 'text', text: `Recorded: ${subject}${due_at ? ` (due ${due_at.slice(0, 10)})` : ' (no deadline)'}\n${out.id}${note}` }] }
+    },
+  )
+
+  server.registerTool(
+    'resolve_obligation',
+    {
+      title: 'Close, cancel or defer an obligation',
+      description: 'Close, cancel or defer an obligation. `discharged` = it happened. `cancelled` = it stopped mattering. These are DIFFERENT FACTS and both require a `resolution` saying how it ended — an obligation closed with no reason is a row nobody can reconstruct later, and "stopped mattering" is the one that gets lost first. `snoozed` needs `snoozed_until`; a snooze with no deadline is a permanent silent drop wearing a deferral\'s clothes, and it is refused. An expired snooze returns to my_obligations on its own.',
+      inputSchema: {
+        obligation_id: z.string().describe('from my_obligations'),
+        state: z.enum(['discharged', 'cancelled', 'snoozed']).describe('discharged = it happened; cancelled = it stopped mattering; snoozed = ask me later'),
+        resolution: z.string().optional().describe('REQUIRED for discharged/cancelled — how it ended'),
+        snoozed_until: z.string().optional().describe('REQUIRED for snoozed — ISO 8601'),
+      },
+    },
+    async ({ obligation_id, state, resolution, snoozed_until }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/obligations/resolve`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ obligationId: obligation_id, state, resolution, snoozedUntil: snoozed_until }),
+        })
+      } catch (e) { return toolError(`Could not reach obligations: ${e.message}`) }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return toolError(`Could not resolve: ${out?.error ?? res.status}`)
+      return { content: [{ type: 'text', text: state === 'snoozed' ? `Snoozed until ${snoozed_until}. It comes back on its own.` : `Marked ${state}: ${resolution}` }] }
+    },
+  )
+
+  server.registerTool(
+    'capture_meeting',
+    {
+      title: 'Capture a meeting transcript, joined to its calendar event',
+      description: "Capture a meeting transcript you were given — a paste, an export, notes — as a real record joined to the calendar event it came from. ⚠ CALL IT TWICE. Without `calendar_record_id` it WRITES NOTHING and returns candidate calendar events near that time; you pick one and call again. Overlap alone is not an answer — 90 of 120 calendar records are recurring birthdays and an all-day event overlaps its whole day, so each candidate carries `caveats` saying why it might be wrong. Read them before choosing. WHY THE JOIN MATTERS: a pasted transcript has no attendee list, so on its own it is reachable from nobody. The calendar event's attendee list is authoritative, and the captured meeting inherits it — that is what makes the transcript findable from the people who were in it. The brain follows from the matched event; you never pick one. Attendees who have no page come back as `unclaimed` — each is a person in the room nobody has authored, and authoring one reaches every past event they were in, not just this meeting. Meetings are stored `scoped`, never org-wide.",
+      inputSchema: {
+        occurred_at: z.string().describe('when the meeting STARTED, ISO 8601. Required for both the proposal and the capture.'),
+        ends_at: z.string().optional().describe('when it ended, ISO 8601. Omit and the calendar event\'s end is inherited. NEVER guess one — unknown must stay unknown.'),
+        calendar_record_id: z.string().optional().describe('the chosen candidate from a previous call. ABSENT = propose only, nothing is written.'),
+        transcript: z.string().optional().describe('the raw transcript. Summarized server-side; secrets are redacted before storage.'),
+        summary: z.string().optional().describe('your own summary. If given it is stored as-is and the transcript is not sent for summarization.'),
+        title: z.string().optional().describe('defaults to the calendar event title.'),
+        participants: z.array(z.string()).optional().describe('extra attendee emails ADDED to the inherited list — someone who joined but was not invited.'),
+      },
+    },
+    async ({ occurred_at, ends_at, calendar_record_id, transcript, summary, title, participants }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/meetings/capture`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            occurredAt: occurred_at, endsAt: ends_at, calendarRecordId: calendar_record_id,
+            transcript, summary, title, participants,
+          }),
+        })
+      } catch (e) {
+        return toolError(`Could not reach the capture endpoint: ${e.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) return toolError(`Could not capture: ${out?.detail ?? out?.error ?? res.status}`)
+      if (!out) return toolError('The server returned no body.')
+
+      const lines = []
+      if (!out.captured) {
+        // The proposal half. Caveats are printed WITH each candidate rather than summarized, because
+        // the whole point is that the nearest event is often the wrong one.
+        if (!out.matches?.length) {
+          lines.push('No calendar event overlaps that time — nothing was written.')
+          lines.push(out.detail ?? '')
+        } else {
+          lines.push(`${out.matches.length} candidate event(s). NOTHING WAS WRITTEN — re-call with calendar_record_id.`, '')
+          for (const m of out.matches) {
+            lines.push(`${m.recordId}`)
+            lines.push(`  ${m.title ?? '(untitled)'} — ${m.occurredAt}${m.endsAt ? ` → ${m.endsAt}` : ''}`)
+            lines.push(`  ${m.attendeeCount} attendee identifier(s) to inherit`)
+            for (const c of m.caveats ?? []) lines.push(`  \u26a0 ${c}`)
+            lines.push('')
+          }
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] }
+      }
+
+      lines.push(`Captured as record ${out.recordId} (scoped).`)
+      lines.push(`  ${out.occurredAt}${out.endsAt ? ` \u2192 ${out.endsAt}` : ' \u2014 no end recorded'}`)
+      if (out.extentDropped) lines.push(`  \u26a0 the end was REFUSED (${out.extentDropped}) and stored as unknown`)
+      const p = out.participants ?? { claimed: [], unclaimed: [] }
+      if (p.claimed?.length) {
+        lines.push('', 'Reaches these pages:')
+        for (const c of p.claimed) lines.push(`  ${c.title}  (${c.identifier})`)
+      }
+      if (p.unclaimed?.length) {
+        lines.push('', `\u26a0 ${p.unclaimed.length} attendee(s) with NO page — this meeting is not reachable from them:`)
+        for (const u of p.unclaimed) lines.push(`  ${u}`)
+        lines.push('Author a page and claim the address, and every past event they were in reaches it too.')
+      }
+      return { content: [{ type: 'text', text: lines.join('\n') }] }
+    },
+  )
+
   server.registerTool(
     'place_staged_record',
     {

package/package.json

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