@theronap/agnoclast-mcp 0.9.248 → 0.9.250

package/lib/calendar_events.mjs

@@ -85,6 +85,87 @@ export function describeEventTime(t, tz) {
   return `${day}, ${time(t.startsAt)}${t.endsAt ? `–${time(t.endsAt)}` : ''}`
 }
 
+// ── a repeating event (event_time.ts, same names) ───────────────────────────────────────────────
+
+export const WEEKDAYS = ['MO', 'TU', 'WE', 'TH', 'FR', 'SA', 'SU']
+
+function localDateTime(d, 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',
+  }).formatToParts(d)
+  const v = (t) => parts.find((p) => p.type === t)?.value ?? ''
+  return { date: `${v('year')}-${v('month')}-${v('day')}`, time: `${v('hour')}:${v('minute')}` }
+}
+
+function weekday(raw) {
+  const two = typeof raw === 'string' ? raw.trim().slice(0, 2).toUpperCase() : ''
+  return WEEKDAYS.includes(two) ? two : null
+}
+
+/** A repeating event's schedule: the first meeting's start/end, the days, and the last date. */
+export function resolveSeriesPlacement(input, tz) {
+  const start = typeof input.start === 'string' ? input.start.trim() : ''
+  if (input.allDay === true || DATE_RE.test(start)) {
+    return { ok: false, error: 'A repeating event needs a time of day — give `start` and `end` with times (e.g. 2026-09-03T15:30). Repeating all-day events are not supported yet.' }
+  }
+  const t = resolveEventTimes({ start: input.start, end: input.end }, tz)
+  if (!t.ok) return t
+  if (!t.endsAt) return { ok: false, error: 'A repeating event needs an `end`, because every meeting is that long. If the person did not say how long it lasts, ASK.' }
+
+  const raw = Array.isArray(input.days) ? input.days : []
+  const bad = raw.filter((d) => weekday(d) === null)
+  if (bad.length) return { ok: false, error: `Not a day of the week: ${bad.map(String).join(', ')}. Use MO TU WE TH FR SA SU.` }
+  const picked = new Set(raw.map(weekday))
+  const byday = WEEKDAYS.filter((d) => picked.has(d))
+  if (byday.length === 0) return { ok: false, error: '`repeat.days` is required: the days of the week it repeats on, e.g. ["TU","TH"].' }
+
+  const durationMinutes = Math.round((Date.parse(t.endsAt) - Date.parse(t.startsAt)) / 60000)
+  if (durationMinutes > 24 * 60) return { ok: false, error: 'Each meeting of a repeating event has to fit in one day — check `end`.' }
+
+  const first = localDateTime(new Date(t.startsAt), tz)
+  const from = typeof input.from === 'string' && input.from.trim() ? input.from.trim() : first.date
+  if (!DATE_RE.test(from) || Number.isNaN(Date.parse(`${from}T00:00:00Z`))) return { ok: false, error: `repeat.from is not a date: ${from}` }
+  const until = typeof input.until === 'string' ? input.until.trim() : ''
+  if (!until) return { ok: false, error: '`repeat.until` is required: the last date it can meet (YYYY-MM-DD), e.g. the end of the semester. Ask the person if they did not say.' }
+  if (!DATE_RE.test(until) || Number.isNaN(Date.parse(`${until}T00:00:00Z`))) return { ok: false, error: `repeat.until is not a date: ${until}` }
+  if (until < from) return { ok: false, error: `repeat.until (${until}) is before the first meeting (${from}).` }
+
+  return { ok: true, placement: { byday, startsTime: first.time, durationMinutes, windowFrom: from, windowUntil: until, timezone: tz } }
+}
+
+export function seriesKeyFor(title, windowFrom) {
+  const slug = title.toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'event'
+  return `${slug}-${windowFrom.replace(/-/g, '')}`
+}
+
+/** POST /api/series body for create_event with `repeat` — the same shape the connector sends. */
+export function seriesRequestBody(args, p) {
+  return {
+    title: args.title,
+    seriesKey: seriesKeyFor(args.title, p.windowFrom),
+    page: args.page,
+    brain: args.brain,
+    location: args.location ?? null,
+    containerType: args.containerType ?? 'appointment',
+    placement: p,
+    materialize: true,
+  }
+}
+
+const DAY_NAMES = { MO: 'Mon', TU: 'Tue', WE: 'Wed', TH: 'Thu', FR: 'Fri', SA: 'Sat', SU: 'Sun' }
+
+export function describeSeriesPlacement(p) {
+  const [h, m] = p.startsTime.split(':').map(Number)
+  const clock = (mins) => new Intl.DateTimeFormat('en-US', { timeZone: 'UTC', hour: 'numeric', minute: '2-digit' })
+    .format(new Date(Date.UTC(2000, 0, 1, 0, mins % (24 * 60))))
+  const startMin = h * 60 + m
+  const date = (ymd) => new Intl.DateTimeFormat('en-US', { timeZone: 'UTC', weekday: 'short', month: 'short', day: 'numeric' })
+    .format(new Date(`${ymd}T12:00:00Z`))
+  const names = p.byday.map((d) => DAY_NAMES[d])
+  const days = names.length > 1 ? `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}` : names[0]
+  return `every ${days}, ${clock(startMin)}–${clock(startMin + p.durationMinutes)}, ${date(p.windowFrom)} to ${date(p.windowUntil)}`
+}
+
 // ── mcp_remote_render.ts ────────────────────────────────────────────────────────────────────────
 
 function dayLabel(d, tz) {
@@ -131,6 +212,29 @@ export function renderEventCreated(title, when, tz, body) {
     (body?.id ? `\nEvent id: ${body.id} — if anything about it changes, fix it with update_event; do not save a second copy.` : '')
 }
 
+export const CREATE_EVENT_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. For something that REPEATS weekly (a class, a standing meeting), call this ONCE with `repeat` {days, until} and `page`, e.g. start "2026-09-03T15:30", end "2026-09-03T16:45", repeat {days:["TU","TH"], until:"2026-12-10"}, page "STRAT 421" — never one call per meeting. 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.'
+
+/** create_event's answer for a repeating event. */
+export function renderSeriesCreated(title, when, tz, body) {
+  const n = body?.generated ?? 0
+  const lines = [`Added a repeating event to the Agnoclast calendar: "${oneLine(title, 200)}", ${when} (${tz}).`]
+  if (n > 0) {
+    const first = body?.firstStartsAt
+      ? ` The first is ${dayLabel(new Date(body.firstStartsAt), tz)}, ${timeLabel(new Date(body.firstStartsAt), tz)}${body.firstEndsAt ? `–${timeLabel(new Date(body.firstEndsAt), tz)}` : ''}.`
+      : ''
+    lines.push(`${n} meeting${n === 1 ? ' is' : 's are'} on the calendar${body?.through ? ` through ${allDayLabel(body.through)}` : ''}.${first}`)
+    if (body?.through && body?.windowUntil && body.through < body.windowUntil) {
+      lines.push(`⚠ Only the meetings through ${allDayLabel(body.through)} were added; the later ones (to ${allDayLabel(body.windowUntil)}) are not on the calendar.`)
+    }
+  } else {
+    lines.push('⚠ No meetings were added: none of the chosen days falls between the first date and `until`. Check the days and dates with the person.')
+  }
+  if (body?.page?.title) lines.push(`Filed to the page "${oneLine(body.page.title, 120)}", so anything from those meetings lands there.`)
+  lines.push(`It shows on ${CONSOLE}/calendar and in upcoming. Nothing was added to Google or Outlook, and no one was invited.`)
+  lines.push(`To move ONE meeting, use update_event with that meeting's event id from upcoming. Changing the whole series' days or times is not possible yet${body?.identifier ? ` (series ${body.identifier})` : ''}.`)
+  return lines.join('\n')
+}
+
 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)}` : ''

package/lib/server.mjs

@@ -35,7 +35,10 @@ 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'
+import {
+  CREATE_EVENT_DESCRIPTION, captureEventBody, describeEventTime, describeSeriesPlacement, renderEventCreated, renderEventUpdated,
+  renderSeriesCreated, renderUpcoming, resolveEventTimes, resolveSeriesPlacement, seriesRequestBody, 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
@@ -1948,7 +1951,7 @@ function renderNudge(payload) {
     {
       title: 'Ask to send an email from the user\'s mailbox (Gmail or Outlook)',
       description:
-        'Send an email from the USER\'S OWN connected mailbox, Gmail or Outlook. By default this does NOT send immediately: it creates a request that WAITS for the user to approve it in Agnoclast, and it goes out at once only if their own send rule allows it. The message is frozen when the request is made, so write the final wording. Always show the user what you are about to send and get their agreement first. Returns either an approval link to relay to them, or confirmation that it already went. ⚠ NEVER call this twice for the same email — it is not idempotent, and a retry can send twice.',
+        'Send an email from the USER\'S OWN connected mailbox, Gmail or Outlook. By default this does NOT send immediately: it creates a request that WAITS for the user to approve it in Agnoclast, and it goes out at once only if their own send rule allows it. The message is frozen when the request is made, so write the final wording. Always show the user what you are about to send and get their agreement first. Returns either an approval link to relay to them, or confirmation that it already went. ⚠ NEVER call this twice for the same email — it is not idempotent, and a retry can send twice. IF YOU ARE AN AI AGENT WITH YOUR OWN IDENTITY (a member agent): you send from YOUR OWN address, labelled as an AI agent of your owner, and one of your overseers approves unless their rule for you allows it; a line saying an AI wrote it is added for you. Pass from: \'overseer\' only if an overseer has opened their mailbox to you.',
       inputSchema: {
         to: z.array(z.string()).min(1).describe('recipient email addresses'),
         subject: z.string().min(1).describe('the subject line'),
@@ -1958,9 +1961,11 @@ function renderNudge(payload) {
         replyToRecordId: z.string().optional().describe('reply in the thread of this Agnoclast email record'),
         replyToMessageId: z.string().optional().describe('reply in the thread of this message id (Gmail or Outlook)'),
         account: z.string().email().optional().describe('which connected mailbox (Gmail or Outlook) to send from, when the user has more than one'),
+        from: z.enum(['own', 'overseer']).optional().describe("AI member agents only: 'own' (default) = your own address; 'overseer' = the mailbox an overseer opened to you"),
+        brain: z.string().optional().describe('AI member agents only: which brain this email is for, when you are in more than one'),
       },
     },
-    async ({ to, subject, text, cc, bcc, replyToRecordId, replyToMessageId, account }) => {
+    async ({ to, subject, text, cc, bcc, replyToRecordId, replyToMessageId, account, from, brain }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/gmail/send-requests`, {
@@ -1972,6 +1977,8 @@ function renderNudge(payload) {
             ...(replyToRecordId ? { replyToRecordId } : {}),
             ...(replyToMessageId ? { replyToMessageId } : {}),
             ...(account ? { account } : {}),
+            ...(from ? { from } : {}),
+            ...(brain ? { brain } : {}),
           }),
         }, { idempotent: false, retries: 0 })
       } catch (e) {
@@ -1988,6 +1995,12 @@ function renderNudge(payload) {
       const reviewUrl = body?.reviewUrl
       const acct = body?.request?.account ?? 'your mailbox'
       const n = body?.request?.recipientCount ?? to.length
+      // ADR-0092: a member agent's request waits for one of its OVERSEERS, not for "you".
+      if (reviewUrl && body?.waitingFor) {
+        return { content: [{ type: 'text', text:
+          `Email request created from ${acct} to ${n} recipient${n === 1 ? '' : 's'}. It is NOT sent yet: it waits for ` +
+          `${body.waitingFor} to approve it in Agnoclast (${reviewUrl}). Do not send it again.` }] }
+      }
       if (reviewUrl) {
         // Relayed VERBATIM — this exact sentence is the contract the create route records.
         return { content: [{ type: 'text', text:
@@ -5603,21 +5616,54 @@ function renderNudge(payload) {
     '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.",
+      description: CREATE_EVENT_DESCRIPTION,
       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'),
+        start: z.string().describe('ISO 8601, e.g. "2026-10-08T15:00"; a date (YYYY-MM-DD) for an all-day event. With `repeat`, the FIRST meeting.'),
+        end: z.string().optional().describe("ISO 8601 end; omit if unknown — never guess one. With `repeat`, the first meeting's end (required)."),
         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'),
+        repeat: z.object({
+          days: z.array(z.string()).describe('the days it meets: MO TU WE TH FR SA SU'),
+          until: z.string().describe('the last date it can meet, YYYY-MM-DD (e.g. the end of the semester) — ask if unknown'),
+          from: z.string().optional().describe('first date, YYYY-MM-DD (default: the date of `start`)'),
+        }).optional().describe("make it repeat weekly, like a class: every meeting has the first one's time and length"),
+        page: z.string().optional().describe('with `repeat`: the page its meetings file to (e.g. the class page), by name or ref — required; ask if unclear'),
+        container_type: z.enum(['meeting', 'work_block', 'deadline', 'appointment']).optional().describe('with `repeat`: what each meeting owes — appointment (default, nothing), meeting (a transcript or note), work_block, deadline'),
         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 }) => {
+    async ({ title, start, end, all_day, location, notes, repeat, page, container_type, brain }) => {
       const name = String(title ?? '').trim()
       if (!name) return toolError('title is required.')
       const tz = await personTz()
+      if (repeat) {
+        // One call, a whole series (POST /api/series with materialize) — same body as the connector.
+        const s = resolveSeriesPlacement({ start, end, allDay: all_day, days: repeat.days, until: repeat.until, from: repeat.from }, tz)
+        if (!s.ok) return toolError(s.error)
+        const pg = page?.trim()
+        if (!pg) return toolError('A repeating event needs `page`: the page its meetings file to (e.g. the class page). Ask the person which page — or create one first with author — then call again.')
+        let res
+        try {
+          res = await fetchCortex(`${BASE}/api/series`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify(seriesRequestBody({
+              title: name, page: pg, brain: brain?.trim() || undefined, location: location?.trim() || undefined, containerType: container_type,
+            }, s.placement)),
+          })
+        } 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 (!res.ok || body?.ok !== true) {
+          return toolError(body?.detail ? `Not added: ${body.detail}` : `Could not add "${name}": ${body?.error ?? res.status}`)
+        }
+        const text = renderSeriesCreated(name, describeSeriesPlacement(s.placement), tz, body)
+        return { content: [{ type: 'text', text: notes?.trim() ? `${text}\nThe notes were not saved: a repeating event has nowhere to keep them yet — put them on the page.` : text }] }
+      }
       const t = resolveEventTimes({ start, end, allDay: all_day }, tz)
       if (!t.ok) return toolError(t.error)
       const when = describeEventTime(t, tz)

package/package.json

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