@theronap/agnoclast-mcp 0.9.243 → 0.9.244

package/lib/calendar_events.mjs

@@ -0,0 +1,173 @@
+// The Agnoclast calendar on the stdio server: upcoming, create_event, update_event.
+//
+// ⚠ WHY THIS FILE EXISTS. Those three tools shipped on the claude.ai connector only (web/lib/mcp/tools.ts,
+// 2026-10-06), so a person set up through the desktop app or Claude Code — the stdio server — could track
+// obligations but had no way to read or add calendar events. Found at David Morgan's setup, 2026-10-19.
+//
+// ⚠ THIS IS A PORT, PINNED BY A PARITY TEST. resolveEventTimes / describeEventTime are
+// web/lib/engine/event_time.ts and the three renderers are web/lib/engine/mcp_remote_render.ts. This
+// package ships to npm on its own and cannot import the web app's TypeScript, so the logic is copied —
+// and calendar_events.parity.test.mjs runs both copies on the same inputs, so an edit to one without the
+// other fails CI instead of silently putting a Denver 3pm class at 9am on one surface.
+
+export const CONSOLE = 'https://agnoclast.com'
+export const NATIVE_EVENT_SOURCE = 'agnoclast-calendar'
+
+const oneLine = (s, max = 140) => String(s ?? '').replace(/\s+/g, ' ').trim().slice(0, max)
+
+// ── event_time.ts ───────────────────────────────────────────────────────────────────────────────
+
+const OFFSET_RE = /(Z|[+-]\d{2}:?\d{2})$/i
+const NAIVE_RE = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?$/
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/
+
+function offsetMinutes(utcMs, tz) {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone: tz, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit',
+  }).formatToParts(new Date(utcMs))
+  const n = (t) => Number(parts.find((p) => p.type === t)?.value)
+  const asUtc = Date.UTC(n('year'), n('month') - 1, n('day'), n('hour'), n('minute'), n('second'))
+  return Math.round((asUtc - utcMs) / 60000)
+}
+
+/** An ISO-ish time to a UTC instant. Without an offset it is the wall-clock time in `tz`. */
+export function toInstant(raw, tz) {
+  const s = raw.trim()
+  if (OFFSET_RE.test(s)) {
+    const d = new Date(s)
+    return Number.isNaN(d.getTime()) ? null : d
+  }
+  const m = NAIVE_RE.exec(s)
+  if (!m) return null
+  const wallAsUtc = Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +(m[6] ?? 0))
+  let utc = wallAsUtc - offsetMinutes(wallAsUtc, tz) * 60000
+  utc = wallAsUtc - offsetMinutes(utc, tz) * 60000
+  return new Date(utc)
+}
+
+/** Validate and resolve an event's start/end, in the person's timezone. */
+export function resolveEventTimes(input, tz) {
+  const start = typeof input.start === 'string' ? input.start.trim() : ''
+  const end = typeof input.end === 'string' && input.end.trim() ? input.end.trim() : null
+  if (!start) return { ok: false, error: 'start is required (ISO 8601, e.g. 2026-10-08T15:00, or a date for an all-day event).' }
+
+  if (input.allDay === true || DATE_RE.test(start)) {
+    const date = start.slice(0, 10)
+    if (!DATE_RE.test(date) || Number.isNaN(Date.parse(`${date}T00:00:00Z`))) return { ok: false, error: `Not a date: ${start}` }
+    const endDate = end ? end.slice(0, 10) : null
+    if (endDate && (!DATE_RE.test(endDate) || endDate < date)) return { ok: false, error: 'An all-day event cannot end before it starts.' }
+    return {
+      ok: true, allDay: true, date,
+      startsAt: `${date}T00:00:00.000Z`,
+      endsAt: endDate && endDate !== date ? `${endDate}T23:59:59.000Z` : null,
+    }
+  }
+
+  const s = toInstant(start, tz)
+  if (!s) return { ok: false, error: `Could not read the start time: ${start}` }
+  let e = null
+  if (end) {
+    e = toInstant(end, tz)
+    if (!e) return { ok: false, error: `Could not read the end time: ${end}` }
+    if (e.getTime() <= s.getTime()) return { ok: false, error: 'The event has to end after it starts.' }
+  }
+  return { ok: true, allDay: false, startsAt: s.toISOString(), endsAt: e ? e.toISOString() : null }
+}
+
+/** "Thu, Oct 8, 3:00–4:00 PM" in the person's timezone, or "Tue, Oct 20 (all day)". */
+export function describeEventTime(t, tz) {
+  if (t.allDay) {
+    const d = new Intl.DateTimeFormat('en-US', { timeZone: 'UTC', weekday: 'short', month: 'short', day: 'numeric' }).format(new Date(`${t.date}T12:00:00Z`))
+    return `${d} (all day)`
+  }
+  const day = new Intl.DateTimeFormat('en-US', { timeZone: tz, weekday: 'short', month: 'short', day: 'numeric' }).format(new Date(t.startsAt))
+  const time = (iso) => new Intl.DateTimeFormat('en-US', { timeZone: tz, hour: 'numeric', minute: '2-digit' }).format(new Date(iso))
+  return `${day}, ${time(t.startsAt)}${t.endsAt ? `–${time(t.endsAt)}` : ''}`
+}
+
+// ── mcp_remote_render.ts ────────────────────────────────────────────────────────────────────────
+
+function dayLabel(d, tz) {
+  return new Intl.DateTimeFormat('en-US', { timeZone: tz, weekday: 'short', month: 'short', day: 'numeric' }).format(d)
+}
+function timeLabel(d, tz) {
+  return new Intl.DateTimeFormat('en-US', { timeZone: tz, hour: 'numeric', minute: '2-digit' }).format(d)
+}
+function allDayLabel(ymd) {
+  return dayLabel(new Date(`${ymd}T12:00:00Z`), 'UTC')
+}
+
+/** The calendar, in the person's own timezone. An ALL-DAY event renders from `allDayDate`, never `startsAt`. */
+export function renderUpcoming(items, tz, incomplete = false) {
+  if (!items.length) {
+    return 'Nothing on the calendar in that window.' + (incomplete ? ' (One brain could not be read, so this may be missing events.)' : '') +
+      ' If the person expected events, their calendar may not be connected — that is set up at ' + CONSOLE + '/connectors.'
+  }
+  const lines = [`Coming up (times in ${tz}):`]
+  let lastDay = ''
+  for (const it of items) {
+    const start = new Date(it.startsAt)
+    const day = it.allDayDate ? allDayLabel(it.allDayDate) : dayLabel(start, tz)
+    if (day !== lastDay) { lines.push('', day); lastDay = day }
+    const when = it.allDayDate
+      ? 'all day'
+      : `${timeLabel(start, tz)}${it.endsAt ? `–${timeLabel(new Date(it.endsAt), tz)}` : ''}`
+    const more = it.furtherOccurrences > 0 ? `  (+${it.furtherOccurrences} more this series)` : ''
+    const where = it.location ? ` · ${oneLine(it.location, 80)}` : ''
+    const id = it.source === NATIVE_EVENT_SOURCE && it.recordId ? `  [event id ${it.recordId}]` : ''
+    lines.push(`  ${when}  ${oneLine(it.title ?? '(untitled)', 140)}${where}${more}${id}`)
+  }
+  if (incomplete) lines.push('', '(One brain could not be read, so this may be missing events.)')
+  return lines.join('\n')
+}
+
+/** create_event's answer. A SEALED event (private-intake accounts) is not on the calendar yet — say so. */
+export function renderEventCreated(title, when, tz, body) {
+  if (body?.sealed) {
+    return `Saved "${oneLine(title, 200)}" (${when}), but it is NOT on the calendar yet: this account holds new items until they are filed from its intake pile, which an Agnoclast session in Claude Code or the desktop app does. It shows on the calendar once filed.` +
+      (body.intakeItemId ? `\nEvent id: ${body.intakeItemId} — if anything about it is wrong (time, end, place, name), fix it with update_event; do not save a second copy.` : '')
+  }
+  return `Added to the Agnoclast calendar: "${oneLine(title, 200)}", ${when} (${tz}). It shows on ${CONSOLE}/calendar and in upcoming. Nothing was added to Google or Outlook, and no one was invited.` +
+    (body?.id ? `\nEvent id: ${body.id} — if anything about it changes, fix it with update_event; do not save a second copy.` : '')
+}
+
+export function renderEventUpdated(b) {
+  const changed = (b?.changed ?? []).filter((c) => ['title', 'start', 'end', 'location'].includes(c))
+  const where = b?.location ? `, at ${oneLine(b.location, 120)}` : ''
+  const head = changed.length
+    ? `Updated "${oneLine(b?.title, 200)}": now ${b?.when ?? ''}${where} (${b?.tz ?? 'UTC'}). Changed: ${changed.join(', ')}.`
+    : `Nothing to change: "${oneLine(b?.title, 200)}" is already ${b?.when ?? ''}${where}.`
+  return b?.kind === 'sealed'
+    ? `${head} It is still held in this account's intake pile and shows on the calendar once filed.`
+    : `${head} Nothing in Google or Outlook was touched.`
+}
+
+// ── request bodies ──────────────────────────────────────────────────────────────────────────────
+
+/** POST /api/records/capture body for a new Agnoclast-calendar event — the same shape create_event sends on claude.ai. */
+export function captureEventBody({ title, location, notes, brain }, t, when) {
+  return {
+    title,
+    content: [title, when, location, notes].filter(Boolean).join('\n'),
+    summary: notes ? `${title} — ${notes}` : title,
+    source: NATIVE_EVENT_SOURCE,
+    recordType: 'event',
+    occurredAt: t.startsAt,
+    ...(t.endsAt ? { endsAt: t.endsAt } : {}),
+    location,
+    eventStart: t.allDay ? t.date : t.startsAt,
+    ...(t.endsAt ? { eventEnd: t.allDay ? t.endsAt.slice(0, 10) : t.endsAt } : {}),
+    brain,
+  }
+}
+
+/** POST /api/events/update body, or null when nothing would change. "" for end/location removes it. */
+export function updateEventBody(args) {
+  const body = { eventId: String(args.event_id ?? '').trim() }
+  if (typeof args.title === 'string' && args.title.trim()) body.title = args.title.trim()
+  if (typeof args.start === 'string' && args.start.trim()) body.start = args.start.trim()
+  if (args.end !== undefined) body.end = typeof args.end === 'string' && args.end.trim() ? args.end.trim() : null
+  if (typeof args.all_day === 'boolean') body.allDay = args.all_day
+  if (args.location !== undefined) body.location = typeof args.location === 'string' && args.location.trim() ? args.location.trim() : null
+  return Object.keys(body).length === 1 ? null : body
+}

package/lib/server.mjs

@@ -35,6 +35,7 @@ import { applyRelease, fetchReleaseState, releaseStateWithin } from './release_g
 import { filterUnshownSettling } from './settling_shown.mjs'
 import { renderContactBriefing, renderContactCandidates, renderContactList } from './contacts_render.mjs'
 import { renderConversation, renderMessageInbox } from './messages_render.mjs'
+import { captureEventBody, describeEventTime, renderEventCreated, renderEventUpdated, renderUpcoming, resolveEventTimes, updateEventBody } from './calendar_events.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
@@ -5510,6 +5511,125 @@ function renderNudge(payload) {
     },
   )
 
+  // ── The Agnoclast calendar: upcoming, create_event, update_event (lib/calendar_events.mjs) ──────────
+  // These shipped on the claude.ai connector only, so a desktop / Claude Code seat could track
+  // obligations but never read or add an event (David Morgan's setup, 2026-10-19). Same routes, same
+  // bodies, same words as web/lib/mcp/tools.ts; the parity test pins the copied logic.
+
+  // The person's STORED timezone (Settings), as the connector uses — else this machine's.
+  const personTz = async () => {
+    try {
+      const res = await fetchCortex(`${BASE}/api/settings`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      const out = res.ok ? await res.json().catch(() => null) : null
+      if (typeof out?.timezone === 'string' && out.timezone) return out.timezone
+    } catch { /* fall through to the local zone */ }
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'
+  }
+
+  server.registerTool(
+    'upcoming',
+    {
+      title: "What's coming up",
+      description: "The person's calendar. Use it FIRST whenever they ask what is on their calendar or schedule — today, tonight, tomorrow, this week, their classes or meetings — even when another calendar tool (such as Google Calendar) is connected. It is the one combined view: events from every calendar they connected to Agnoclast, their classes, and events made in Agnoclast, which a single calendar's own tool does not have. Next 14 days by default, in their own timezone; a recurring class is listed once with how many more times it meets. Agnoclast-calendar events carry an event id for update_event.",
+      inputSchema: {
+        days: z.number().int().min(1).max(60).optional().describe('how many days ahead (default 14)'),
+        limit: z.number().int().min(1).max(50).optional().describe('max events (default 15)'),
+      },
+    },
+    async ({ days, limit }) => {
+      const qs = new URLSearchParams({ days: String(days ?? 14), limit: String(limit ?? 15) })
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/upcoming?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      } catch (e) { return toolError(`Could not load the calendar: ${e.message}`) }
+      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 load the calendar: ${d.message}`)
+      }
+      const out = await res.json().catch(() => null)
+      const tz = await personTz()
+      return { content: [{ type: 'text', text: renderUpcoming(out?.items ?? [], tz, out?.incomplete === true) }] }
+    },
+  )
+
+  server.registerTool(
+    'create_event',
+    {
+      title: 'Add to my Agnoclast calendar',
+      description: "Put an event on the person's calendar — a class, meeting, deadline, appointment or reminder — whenever they ask to add, schedule or put something on their calendar. Agnoclast is their calendar: use this rather than another calendar tool (such as Google Calendar) unless they name that other calendar. Give `start` as ISO 8601 (a time with no offset is read in their own timezone), an `end`, or `all_day: true` with a date. If they gave no end or length for a timed event, ASK how long before saving rather than leaving it open. It appears on their Agnoclast calendar and in `upcoming`; it is not copied to Google or Outlook and invites no one. To change it later, use update_event — never save a second copy.",
+      inputSchema: {
+        title: z.string().describe('what the event is, e.g. "Study group — STRAT 421"'),
+        start: z.string().describe('ISO 8601, e.g. "2026-10-08T15:00"; a date (YYYY-MM-DD) for an all-day event'),
+        end: z.string().optional().describe('ISO 8601 end; omit if unknown — never guess one'),
+        all_day: z.boolean().optional().describe('true for an all-day event or deadline'),
+        location: z.string().optional().describe('where, if known'),
+        notes: z.string().optional().describe('anything else the person said about it'),
+        brain: z.string().optional().describe('which brain, by name or org id. Required only when the person belongs to more than one — ask them; placing something in a brain decides who can see it.'),
+      },
+    },
+    async ({ title, start, end, all_day, location, notes, brain }) => {
+      const name = String(title ?? '').trim()
+      if (!name) return toolError('title is required.')
+      const tz = await personTz()
+      const t = resolveEventTimes({ start, end, allDay: all_day }, tz)
+      if (!t.ok) return toolError(t.error)
+      const when = describeEventTime(t, tz)
+      const loc = location?.trim() || undefined
+      const note = notes?.trim() || undefined
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/records/capture`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify(captureEventBody({ title: name, location: loc, notes: note, brain: brain?.trim() || undefined }, t, when)),
+        })
+      } catch (e) { return toolError(`Could not reach Agnoclast to add "${name}": ${e.message}`) }
+      const body = await res.json().catch(() => ({}))
+      if (res.status === 400 && body?.error === 'brain_required') {
+        return toolError(`You belong to more than one brain, so say which one "${name}" goes in (my_brains lists them) and call again with \`brain\`. The brain decides who can see it — ask the person if they did not say.`)
+      }
+      if (body?.sealed) return { content: [{ type: 'text', text: renderEventCreated(name, when, tz, body) }] }
+      if (!res.ok || body?.ok !== true) {
+        return toolError(`Could not add "${name}": ${body?.error ?? res.status}${body?.detail ? ` — ${body.detail}` : ''}`)
+      }
+      return { content: [{ type: 'text', text: renderEventCreated(name, when, tz, body) }] }
+    },
+  )
+
+  server.registerTool(
+    'update_event',
+    {
+      title: 'Change an event on my Agnoclast calendar',
+      description: "Fix or move an event the person made on their Agnoclast calendar — a new time, an end or length, a new name or place — when they ask. Pass `event_id` (create_event and upcoming print it) and ONLY what changes. Moving the start keeps the event's length unless you also give `end`; a time with no offset is read in their own timezone. Pass \"\" as `end` or `location` to remove it. Only events made on the Agnoclast calendar can be changed — never Google or Outlook ones — and this cannot cancel an event.",
+      inputSchema: {
+        event_id: z.string().describe('the event id create_event or upcoming printed'),
+        title: z.string().optional().describe('a new name'),
+        start: z.string().optional().describe('new start, ISO 8601 (e.g. "2026-10-09T12:00"); a date for an all-day event'),
+        end: z.string().optional().describe('new end, ISO 8601; "" removes the end'),
+        all_day: z.boolean().optional().describe('true to make it all-day, false to make it timed (then give start)'),
+        location: z.string().optional().describe('new place; "" removes it'),
+      },
+    },
+    async (args) => {
+      if (!String(args.event_id ?? '').trim()) return toolError('event_id is required — create_event and upcoming print it.')
+      const body = updateEventBody(args)
+      if (!body) return toolError('Say what to change: title, start, end, all_day or location.')
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/events/update`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify(body),
+        })
+      } catch (e) { return toolError(`Could not reach Agnoclast to change the event: ${e.message}`) }
+      const b = await res.json().catch(() => null)
+      if (res.status === 404) return toolError(b?.detail ? `Not changed: ${b.detail}` : 'No event of theirs on the Agnoclast calendar has that id.')
+      if (res.status === 409 || res.status === 400) return toolError(`Not changed: ${b?.detail ?? b?.error ?? 'the request was refused'}`)
+      if (!res.ok) return toolError(`Could not change the event: ${b?.error ?? res.status}${b?.detail ? ` — ${b.detail}` : ''}`)
+      return { content: [{ type: 'text', text: renderEventUpdated(b) }] }
+    },
+  )
+
   server.registerTool(
     'token_activity',
     {

package/package.json

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