clavarium-tether 0.1.0-next.21 → 0.1.0-next.23

package/bin/cli.mjs

@@ -41,12 +41,15 @@ export const HELP = `${NAME}: act on the targets you were given (machines, folde
   ${NAME} mail TARGET move UID MAILBOX                 move a message to a folder
   ${NAME} mail TARGET flag UID read|unread|flagged|unflagged
   ${NAME} mail TARGET delete UID                       delete a message (to Trash / Deleted Items)
-  ${NAME} mail TARGET send --to "a@b,c@d" --subject "..." --body "..." [--cc "..."] [--attach FILE]
+  ${NAME} mail TARGET send --to "a@b,c@d" --subject "..." --body "..." [--cc "..."] [--attach FILE ...]   (--attach repeats, or --attach A,B)
   ${NAME} calendar TARGET list [--from DATE] [--to DATE]   events in a window (default: from now on)
   ${NAME} calendar TARGET read ID
-  ${NAME} calendar TARGET create --title "..." --start ISO --end ISO [--where "..."]
-  ${NAME} calendar TARGET update EVENT_ID [--title "..."] [--start ISO] [--end ISO] [--where "..."]  (Microsoft)
-  ${NAME} calendar TARGET attach EVENT_ID FILE             join a file to an event (Microsoft)
+  ${NAME} calendar TARGET freebusy "a@b,c@d" [--from DATE] [--to DATE]   when others are busy (Microsoft)
+  ${NAME} calendar TARGET create --title "..." --start ISO --end ISO [--where "..."] [--notes "..."] [--with "a@b,c@d"] [--category "Internal"]
+  ${NAME} calendar TARGET update EVENT_ID [--title] [--start] [--end] [--where] [--notes] [--with] [--category NAME|none]  (Microsoft)
+  ${NAME} calendar TARGET categories                      the mailbox's categories (name, colour; Microsoft)
+  ${NAME} calendar TARGET list --category "Travel"        only the events of one category (Microsoft)
+  ${NAME} calendar TARGET attach EVENT_ID FILE [--share]   join a file to an event (Microsoft); --share if a participant is external
   ${NAME} calendar TARGET detach EVENT_ID NAME|N           remove an attachment from an event (Microsoft)
   ${NAME} calendar TARGET delete EVENT_ID                  delete an event
   ${NAME} calendar TARGET respond EVENT_ID accept|decline|tentative   answer an invitation (Microsoft)
@@ -69,7 +72,7 @@ ${NAME} ${VERSION}`;
 const FILE_VERBS = ['list', 'read', 'search', 'write', 'move', 'delete'];
 const BROWSER_VERBS = ['tabs', 'open', 'shot', 'html', 'console', 'eval', 'click', 'type', 'key', 'scroll', 'drag'];
 const MAIL_VERBS = ['list', 'read', 'source', 'attachment', 'search', 'move', 'flag', 'delete', 'send'];
-const CAL_VERBS = ['list', 'read', 'create', 'update', 'attach', 'detach', 'delete', 'respond'];
+const CAL_VERBS = ['list', 'read', 'freebusy', 'create', 'update', 'attach', 'detach', 'delete', 'respond', 'categories'];
 const CONTACT_VERBS = ['list', 'search', 'read', 'create', 'update', 'delete', 'attach'];
 const baseName = (p) => String(p).split('/').pop();
 const readB64 = (p) => { try { return readFileSync(p).toString('base64'); } catch { return null; } };
@@ -82,6 +85,10 @@ export function read(argv) {
         const a = argv[i];
         if (a === '--enter') { flags.enter = true; continue; }
         if (a === '--readable') { flags.readable = true; continue; }
+        if (a === '--share') { flags.share = true; continue; }
+        /* --attach may be given several times, and each value may list files with commas. */
+        if (a === '--attach') { if (argv[i + 1] === undefined) return { refused: '--attach needs a file' }; (flags.attach ??= []).push(...String(argv[++i]).split(',').map((x) => x.trim()).filter(Boolean)); continue; }
+        if (a === '--category') { if (argv[i + 1] === undefined) return { refused: '--category needs a name (or none)' }; (flags.category ??= []).push(...String(argv[++i]).split(',').map((x) => x.trim()).filter(Boolean)); continue; }
         if (a.startsWith('--')) { if (argv[i + 1] === undefined) return { refused: `${a} needs a value` }; flags[a.slice(2)] = argv[++i]; continue; }
         words.push(a);
     }
@@ -144,7 +151,11 @@ export function read(argv) {
                     const bad = need(flags.to !== undefined && flags.subject !== undefined && flags.body !== undefined, 'mail TARGET send --to "a@b" --subject "..." --body "..." [--cc "..."] [--attach FILE]');
                     if (bad) return bad;
                     let att = {};
-                    if (flags.attach !== undefined) { const b = readB64(flags.attach); if (b === null) return { refused: `cannot read the file to attach: ${flags.attach}` }; att = { attach: b, attachName: flags['attach-name'] || baseName(flags.attach) }; }
+                    if (flags.attach !== undefined) {
+                        const files = [];
+                        for (const path of flags.attach) { const b = readB64(path); if (b === null) return { refused: `cannot read the file to attach: ${path}` }; files.push({ name: baseName(path), bytes: b }); }
+                        att = { attachments: files };
+                    }
                     return ['mail.send', { target, to: flags.to, subject: flags.subject, body: flags.body, ...(flags.cc !== undefined ? { cc: flags.cc } : {}), ...att, ...why }];
                 }
             }
@@ -152,19 +163,23 @@ export function read(argv) {
         case 'calendar': {
             const [what, ...p] = rest;
             if (!target || !CAL_VERBS.includes(what)) return { refused: `${NAME} calendar TARGET ${CAL_VERBS.join('|')} ...` };
+            /* --category is repeatable (an event may wear several); "--category none" clears them. */
+            const catArr = flags.category ? (flags.category.length === 1 && flags.category[0].toLowerCase() === 'none' ? [] : flags.category) : undefined;
             switch (what) {
-                case 'list': return ['calendar.list', { target, ...(flags.from !== undefined ? { from: flags.from } : {}), ...(flags.to !== undefined ? { to: flags.to } : {}) }];
+                case 'categories': return ['calendar.categories', { target }];
+                case 'list': return ['calendar.list', { target, ...(flags.from !== undefined ? { from: flags.from } : {}), ...(flags.to !== undefined ? { to: flags.to } : {}), ...(catArr && catArr.length ? { category: catArr[0] } : {}) }];
                 case 'read': return need(p[0], 'calendar TARGET read ID') ?? ['calendar.read', { target, id: p[0] }];
+                case 'freebusy': return need(p[0], 'calendar TARGET freebusy "a@b,c@d" [--from DATE] [--to DATE]') ?? ['calendar.freebusy', { target, who: p.join(','), ...(flags.from !== undefined ? { from: flags.from } : {}), ...(flags.to !== undefined ? { to: flags.to } : {}) }];
                 case 'attach': {
                     if (p.length < 2) return { refused: 'calendar TARGET attach EVENT_ID FILE' };
                     const b = readB64(p[1]); if (b === null) return { refused: `cannot read the file to attach: ${p[1]}` };
-                    return ['calendar.attach', { target, id: p[0], attach: b, attachName: flags['attach-name'] || baseName(p[1]), ...why }];
+                    return ['calendar.attach', { target, id: p[0], attach: b, attachName: flags['attach-name'] || baseName(p[1]), ...(flags.share !== undefined ? { share: true } : {}), ...why }];
                 }
                 case 'detach': return need(p.length >= 2, 'calendar TARGET detach EVENT_ID NAME|N') ?? ['calendar.detach', { target, id: p[0], which: p.slice(1).join(' '), ...why }];
                 case 'delete': return need(p[0], 'calendar TARGET delete EVENT_ID') ?? ['calendar.delete', { target, id: p[0], ...why }];
                 case 'respond': return need(p.length >= 2, 'calendar TARGET respond EVENT_ID accept|decline|tentative [--comment "..."]') ?? ['calendar.respond', { target, id: p[0], answer: p[1], ...(flags.comment !== undefined ? { comment: flags.comment } : {}), ...why }];
-                case 'update': return need(p[0], 'calendar TARGET update EVENT_ID [--title "..."] [--start ISO] [--end ISO] [--where "..."]') ?? ['calendar.update', { target, id: p[0], ...(flags.title !== undefined ? { title: flags.title } : {}), ...(flags.start !== undefined ? { start: flags.start } : {}), ...(flags.end !== undefined ? { end: flags.end } : {}), ...(flags.where !== undefined ? { where: flags.where } : {}), ...why }];
-                default: return need(flags.title !== undefined && flags.start !== undefined && flags.end !== undefined, 'calendar TARGET create --title "..." --start ISO --end ISO [--where "..."]') ?? ['calendar.create', { target, title: flags.title, start: flags.start, end: flags.end, ...(flags.where !== undefined ? { where: flags.where } : {}), ...why }];
+                case 'update': return need(p[0], 'calendar TARGET update EVENT_ID [--title] [--start] [--end] [--where] [--notes] [--with] [--category NAME|none]') ?? ['calendar.update', { target, id: p[0], ...(flags.title !== undefined ? { title: flags.title } : {}), ...(flags.start !== undefined ? { start: flags.start } : {}), ...(flags.end !== undefined ? { end: flags.end } : {}), ...(flags.where !== undefined ? { where: flags.where } : {}), ...(flags.notes !== undefined ? { notes: flags.notes } : {}), ...(flags.with !== undefined ? { with: flags.with } : {}), ...(catArr !== undefined ? { categories: catArr } : {}), ...why }];
+                default: return need(flags.title !== undefined && flags.start !== undefined && flags.end !== undefined, 'calendar TARGET create --title "..." --start ISO --end ISO [--where "..."] [--notes "..."] [--with "a@b,c@d"] [--category NAME]') ?? ['calendar.create', { target, title: flags.title, start: flags.start, end: flags.end, ...(flags.where !== undefined ? { where: flags.where } : {}), ...(flags.notes !== undefined ? { notes: flags.notes } : {}), ...(flags.with !== undefined ? { with: flags.with } : {}), ...(catArr && catArr.length ? { categories: catArr } : {}), ...why }];
             }
         }
         case 'contacts': {

package/host/connectors/calendar.mjs

@@ -9,7 +9,7 @@
  *   target.secrets.refresh   the NAME of the refresh token in the host's secret store
  *   target.secrets.secret    optional: the NAME of an own client secret
  *
- * Reads (watch): calendar.list, calendar.read. Acts (above watch): calendar.create.
+ * Reads (watch): calendar.list, calendar.read, calendar.freebusy. Acts (above watch): calendar.create.
  * `fetch` is injected for tests. (Note: the Thunderbird client covers Google calendar
  * cleanly; a Microsoft calendar needs the right Graph scope on the connected account.)
  */
@@ -17,6 +17,9 @@ import { no, Refused } from '../../server/verbs.mjs';
 import { refreshAccess, thunderbird, PROVIDERS } from '../oauth.mjs';
 
 const LIST_MAX = 200;           /* events a list returns at most, then it says so (a year holds many) */
+const TZ = 'Europe/Paris';      /* the person's timezone: events are shown and created in it, not UTC */
+/* A Graph/ISO datetime, shown short and local: "2026-11-10 16:00". */
+const shortWhen = (dt) => { const m = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})/.exec(String(dt || '')); return m ? `${m[1]}-${m[2]}-${m[3]} ${m[4]}:${m[5]}` : (dt || '?'); };
 const READ_MAX = 256 * 1024;
 const dateField = (s) => (/^\d{4}-\d{2}-\d{2}$/.test(s) ? { date: s } : { dateTime: s });
 
@@ -33,15 +36,34 @@ const API = {
         /* calendarView, not /events: /events orders over the WHOLE calendar, so it
            returns the oldest events, not the next ones. calendarView takes a window
            (from now on) and expands recurrences, so "list" means what is coming. */
-        list: (n, { from, to } = {}) => `https://graph.microsoft.com/v1.0/me/calendarView?startDateTime=${encodeURIComponent(from)}&endDateTime=${encodeURIComponent(to)}&$top=${n}&$orderby=start/dateTime&$select=id,subject,start,end,location`,
+        list: (n, { from, to } = {}) => `https://graph.microsoft.com/v1.0/me/calendarView?startDateTime=${encodeURIComponent(from)}&endDateTime=${encodeURIComponent(to)}&$top=${n}&$orderby=start/dateTime&$select=id,subject,start,end,location,categories`,
         event: (id) => `https://graph.microsoft.com/v1.0/me/events/${encodeURIComponent(id)}`,
         create: 'https://graph.microsoft.com/v1.0/me/events',
         items: (j) => j.value ?? [],
-        brief: (e) => `${e.id}\n  ${e.start?.dateTime ?? '?'} — ${e.subject ?? '(no title)'}${e.location?.displayName ? `  @ ${e.location.displayName}` : ''}`,
-        body: ({ title, start, end, where }) => ({ subject: title, start: { dateTime: start, timeZone: 'UTC' }, end: { dateTime: end, timeZone: 'UTC' }, ...(where ? { location: { displayName: where } } : {}) }),
+        brief: (e) => `${e.id}\n  ${shortWhen(e.start?.dateTime)} — ${e.subject ?? '(no title)'}${e.location?.displayName ? `  @ ${e.location.displayName}` : ''}${e.categories?.length ? `  [${e.categories.join(', ')}]` : ''}`,
+        body: ({ title, start, end, where, notes, attendees, categories }) => ({
+            subject: title,
+            start: { dateTime: start, timeZone: TZ }, end: { dateTime: end, timeZone: TZ },
+            ...(where ? { location: { displayName: where } } : {}),
+            ...(notes ? { body: { contentType: 'text', content: String(notes) } } : {}),
+            ...(attendees?.length ? { attendees: attendees.map((a) => ({ emailAddress: { address: a }, type: 'required' })) } : {}),
+            ...(categories?.length ? { categories } : {}),
+        }),
     },
 };
 
+/* Outlook's own category colours (Graph preset ids), shown by name when the
+ * mailbox's categories are listed. Reference data, not a setting. */
+const COLOR_NAME = {
+    none: 'no colour', preset0: 'red', preset1: 'orange', preset2: 'brown', preset3: 'yellow', preset4: 'green',
+    preset5: 'teal', preset6: 'olive', preset7: 'blue', preset8: 'purple', preset9: 'cranberry', preset10: 'steel',
+    preset11: 'dark steel', preset12: 'grey', preset13: 'dark grey', preset14: 'black', preset15: 'dark red',
+    preset16: 'dark orange', preset17: 'dark brown', preset18: 'dark yellow', preset19: 'dark green', preset20: 'dark teal',
+    preset21: 'dark olive', preset22: 'dark blue', preset23: 'dark purple', preset24: 'dark cranberry',
+};
+/* The categories asked for, as a clean list (empty array clears them). */
+const catsOf = (a) => (Array.isArray(a.categories) ? a.categories.map((c) => String(c).trim()).filter(Boolean) : (a.categories ? [String(a.categories).trim()].filter(Boolean) : null));
+
 export function calendar({ fetch: fetchImpl = globalThis.fetch } = {}) {
     const tokens = new Map();
     const providerOf = (target) => { const p = String(target.config?.provider ?? ''); if (!API[p] || !PROVIDERS[p]) no(`${target.title}: set its provider to google or microsoft`); return p; };
@@ -63,7 +85,9 @@ export function calendar({ fetch: fetchImpl = globalThis.fetch } = {}) {
 
     async function call(target, ctx, method, url, json) {
         const token = await access(target, ctx);
-        const headers = { Authorization: `Bearer ${token}` };
+        /* Ask Microsoft to answer in the person's timezone, not UTC, so a 4pm
+           meeting reads 16:00 and not 15:00. Harmless for the Google REST path. */
+        const headers = { Authorization: `Bearer ${token}`, Prefer: `outlook.timezone="${TZ}"` };
         if (json !== undefined) headers['Content-Type'] = 'application/json';
         let res;
         try { res = await fetchImpl(url, { method, headers, ...(json !== undefined ? { body: JSON.stringify(json) } : {}) }); }
@@ -144,12 +168,15 @@ export function calendar({ fetch: fetchImpl = globalThis.fetch } = {}) {
                 return { text, size: Buffer.byteLength(text) };
             };
             /* Google over CalDAV (the REST API its client cannot use); Microsoft over Graph. */
-            if (provider === 'google') return pack(await googleList(target, ctx, { from, to }));
+            if (provider === 'google') { if (a.category) no(`${target.title}: filtering by category is Microsoft-only`); return pack(await googleList(target, ctx, { from, to })); }
             const api = API[provider];
             const res = await call(target, ctx, 'GET', api.list(LIST_MAX, { from, to }));
             if (!res.ok) no(`${target.title}: ${res.status} ${await bodyError(res)}`.trim());
             const json = await res.json();
-            return pack(api.items(json).map(api.brief), Boolean(json['@odata.nextLink']));
+            let items = api.items(json);
+            /* Only one category's events, matched by name without case: all this month's travel, say. */
+            if (a.category) { const want = String(a.category).toLowerCase(); items = items.filter((e) => (e.categories ?? []).some((c) => String(c).toLowerCase() === want)); }
+            return pack(items.map(api.brief), Boolean(json['@odata.nextLink']));
         },
         /* One event in full, by its id. */
         async 'calendar.read'(target, a, ctx) {
@@ -162,12 +189,53 @@ export function calendar({ fetch: fetchImpl = globalThis.fetch } = {}) {
             const text = JSON.stringify(await res.json(), null, 1).slice(0, READ_MAX);
             return { text, size: Buffer.byteLength(text) };
         },
+        /* See when others are busy, to find a time together. A read: it returns
+           only busy/free blocks (and a title only where the person already shares
+           it), never the contents of their calendars. `who` is a comma-separated
+           list of addresses; `from`/`to` bound the window (default: the next 7
+           days). Microsoft over Graph getSchedule; a Google free/busy query comes
+           with parity (its REST path needs the account's own OAuth app). */
+        async 'calendar.freebusy'(target, a, ctx) {
+            const provider = providerOf(target);
+            if (provider !== 'microsoft') no(`${target.title}: reading others' availability is Microsoft-only for now`);
+            const who = String(a.who ?? '').split(',').map((x) => x.trim()).filter(Boolean);
+            if (!who.length) no('freebusy needs at least one address (comma-separated)');
+            if (who.length > 20) no('freebusy looks at up to 20 people at once');
+            /* A window in the person's own wall-clock (Europe/Paris), passed with
+               that timezone so "09:00" means 09:00 there. Default: now → +7 days. */
+            const localISO = (d) => { const p = Object.fromEntries(new Intl.DateTimeFormat('en-CA', { timeZone: TZ, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hour12: false }).formatToParts(d).filter((x) => x.type !== 'literal').map((x) => [x.type, x.value])); return `${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}:00`; };
+            const norm = (s) => { const t = String(s).trim(); if (/^\d{4}-\d{2}-\d{2}$/.test(t)) return `${t}T00:00:00`; if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/.test(t)) return `${t}:00`; return t; };
+            const now = new Date();
+            const from = a.from ? norm(a.from) : localISO(now);
+            const to = a.to ? norm(a.to) : localISO(new Date(now.getTime() + 7 * 86_400_000));
+            const res = await call(target, ctx, 'POST', 'https://graph.microsoft.com/v1.0/me/calendar/getSchedule', {
+                schedules: who,
+                startTime: { dateTime: from, timeZone: TZ }, endTime: { dateTime: to, timeZone: TZ },
+                availabilityViewInterval: 60,
+            });
+            if (!res.ok) no(`${target.title}: availability could not be read (${res.status} ${await bodyError(res)})`.trim());
+            const value = (await res.json()).value ?? [];
+            const label = { tentative: 'tentative', busy: 'busy', oof: 'out of office', workingElsewhere: 'working elsewhere' };
+            const blocks = value.map((s) => {
+                const id = s.scheduleId || '(unknown)';
+                if (s.error) return `${id}\n  could not be read (no access, or unknown address)`;
+                const items = (s.scheduleItems ?? []).filter((it) => it.status && it.status !== 'free');
+                if (!items.length) return `${id}\n  free for the whole window`;
+                return `${id}\n` + items.map((it) => `  ${label[it.status] || it.status}  ${shortWhen(it.start?.dateTime)} — ${shortWhen(it.end?.dateTime)}${it.subject ? `  (${it.subject})` : ''}`).join('\n');
+            });
+            const text = value.length ? `Availability ${shortWhen(from)} → ${shortWhen(to)} (${TZ}):\n\n${blocks.join('\n\n')}` : 'No availability returned.';
+            return { text, size: Buffer.byteLength(text) };
+        },
         /* Create an event. An act: the start and end are ISO times (a bare date is all-day). */
         async 'calendar.create'(target, a, ctx) {
-            const api = API[providerOf(target)];
+            const provider = providerOf(target);
+            const api = API[provider];
             if (!a.title) no('an event needs a title');
-            if (!a.start || !a.end) no('an event needs a start and an end (ISO times, e.g. 2030-01-02T09:00:00Z)');
-            const res = await call(target, ctx, 'POST', api.create, api.body({ title: a.title, start: a.start, end: a.end, where: a.where }));
+            if (!a.start || !a.end) no('an event needs a start and an end (local ISO times, e.g. 2026-11-10T16:00:00)');
+            const categories = catsOf(a);
+            if (categories && provider !== 'microsoft') no(`${target.title}: event categories are Microsoft-only`);
+            const attendees = String(a.with ?? '').split(',').map((x) => x.trim()).filter(Boolean);
+            const res = await call(target, ctx, 'POST', api.create, api.body({ title: a.title, start: a.start, end: a.end, where: a.where, notes: a.notes, attendees, categories: categories ?? undefined }));
             if (!res.ok) no(`${target.title}: the event was not created (${res.status} ${await bodyError(res)})`.trim());
             const made = await res.json().catch(() => ({}));
             return { text: `Created: ${a.title} (${a.start}). Its id is ${made.id ?? '(unknown)'}.`, size: 0 };
@@ -180,10 +248,32 @@ export function calendar({ fetch: fetchImpl = globalThis.fetch } = {}) {
             if (provider !== 'microsoft') no(`${target.title}: joining a file to an event is Microsoft-only for now`);
             if (!a.id) no('attach needs the event id (from the list)');
             if (!a.attach) no('attach needs the file (its base64 bytes)');
+            const ev = encodeURIComponent(String(a.id));
+            /* Who would receive the file: an event attachment reaches every participant
+               on the next invitation update or resend. Split internal from external by
+               the organiser's domain, and refuse an external audience unless `share`. */
+            const internals = []; const externals = [];
+            const info = await call(target, ctx, 'GET', `https://graph.microsoft.com/v1.0/me/events/${ev}?$select=attendees,organizer`);
+            if (info.ok) {
+                const j = await info.json().catch(() => ({}));
+                const org = (j.organizer?.emailAddress?.address || target.config?.user || '').toLowerCase();
+                const dom = org.split('@')[1] || '';
+                for (const at of (j.attendees ?? [])) {
+                    const addr = at.emailAddress?.address; if (!addr || addr.toLowerCase() === org) continue;
+                    (dom && addr.toLowerCase().endsWith('@' + dom) ? internals : externals).push(addr);
+                }
+            }
+            if (externals.length && a.share !== true) {
+                no(`${externals.length} external participant(s): ${externals.join(', ')}. The file would reach them on the next invitation update/resend. Add --share (CLI) or share:true (MCP) to attach anyway.`);
+            }
             const att = { '@odata.type': '#microsoft.graph.fileAttachment', name: String(a.attachName || 'attachment'), contentBytes: String(a.attach) };
-            const res = await call(target, ctx, 'POST', `https://graph.microsoft.com/v1.0/me/events/${encodeURIComponent(String(a.id))}/attachments`, att);
+            const res = await call(target, ctx, 'POST', `https://graph.microsoft.com/v1.0/me/events/${ev}/attachments`, att);
             if (!res.ok) no(`${target.title}: the file was not attached (${res.status} ${await bodyError(res)})`.trim());
-            return { text: `Attached ${a.attachName || 'the file'} to the event.`, size: 0 };
+            const all = internals.length + externals.length;
+            const who = all
+                ? ` It will reach ${all} participant(s) on the next invitation update/resend:${internals.length ? ` ${internals.join(', ')} (internal)` : ''}${externals.length ? `${internals.length ? ';' : ''} ${externals.join(', ')} (external)` : ''}.`
+                : ' Visible to you alone (the event has no participants).';
+            return { text: `Attached ${a.attachName || 'the file'} to the event.${who}`, size: 0 };
         },
         /* Remove a file from an event, by its name or 1-based number. An act.
            Microsoft only, like attaching (Graph deletes the attachment by id). */
@@ -247,12 +337,28 @@ export function calendar({ fetch: fetchImpl = globalThis.fetch } = {}) {
             if (a.start !== undefined) patch.start = { dateTime: String(a.start), timeZone: 'UTC' };
             if (a.end !== undefined) patch.end = { dateTime: String(a.end), timeZone: 'UTC' };
             if (a.where !== undefined) patch.location = { displayName: String(a.where) };
-            if (!Object.keys(patch).length) no('update needs at least one of: title, start, end, where');
+            if (a.notes !== undefined) patch.body = { contentType: 'text', content: String(a.notes) };
+            if (a.with !== undefined) patch.attendees = String(a.with).split(',').map((x) => x.trim()).filter(Boolean).map((e) => ({ emailAddress: { address: e }, type: 'required' }));
+            if (a.categories !== undefined) patch.categories = catsOf(a) ?? []; /* --category none clears them */
+            if (!Object.keys(patch).length) no('update needs at least one of: title, start, end, where, notes, with, category');
             const res = await call(target, ctx, 'PATCH', API.microsoft.event(String(a.id)), patch);
             if (res.status === 404) no('no such event');
             if (!res.ok) no(`${target.title}: the event was not changed (${res.status} ${await bodyError(res)})`.trim());
             return { text: 'Updated the event.', size: 0 };
         },
+        /* The mailbox's own categories (name and colour), so the agent knows which
+           ones exist before it tags an event. A read. Microsoft only; a category is
+           a personal label, invisible to the other participants. */
+        async 'calendar.categories'(target, a, ctx) {
+            const provider = providerOf(target);
+            if (provider !== 'microsoft') no(`${target.title}: calendar categories are Microsoft-only`);
+            const res = await call(target, ctx, 'GET', 'https://graph.microsoft.com/v1.0/me/outlook/masterCategories');
+            if (!res.ok) no(`${target.title}: the categories could not be read (${res.status} ${await bodyError(res)})`.trim());
+            const cats = (await res.json()).value ?? [];
+            if (!cats.length) return { text: 'No category set in this mailbox yet (add them in Outlook, then tag events with --category).', size: 0 };
+            const text = cats.map((c) => `${c.displayName}  (${COLOR_NAME[c.color] ?? c.color ?? 'no colour'})`).join('\n');
+            return { text, size: Buffer.byteLength(text) };
+        },
     };
 
     return {

package/host/connectors/graphmail.mjs

@@ -15,6 +15,7 @@
 import { no, asDate } from '../../server/verbs.mjs';
 
 const GRAPH = 'https://graph.microsoft.com/v1.0';
+const TZ = 'Europe/Paris';   /* answer in the person's timezone, not UTC */
 const LIST_MAX = 30;
 const READ_MAX = 512 * 1024;
 const SOURCE_MAX = 4 * 1024 * 1024;
@@ -36,13 +37,15 @@ export function graphMail({ fetch: fetchImpl = globalThis.fetch, token }) {
         const access = await token(target, ctx);
         const r = await fetchImpl(`${GRAPH}${path}`, {
             method,
-            headers: { authorization: `Bearer ${access}`, ...(body ? { 'content-type': 'application/json' } : {}) },
+            headers: { authorization: `Bearer ${access}`, prefer: `outlook.timezone="${TZ}"`, ...(body ? { 'content-type': 'application/json' } : {}) },
             ...(body ? { body: JSON.stringify(body) } : {}),
         });
         if (r.status === 401 || r.status === 403) no(`${target.title}: not authorized -- reconnect the account (the Microsoft mail scope may be missing)`);
         if (!r.ok) { let m = ''; try { m = (await r.json())?.error?.message ?? ''; } catch { /* no json */ } no(`${target.title}: ${m || `the mail request failed (${r.status})`}`); }
-        if (r.status === 204) return null;
-        return r.json();
+        /* Some acts answer with no body (sendMail is 202, a delete is 204): parse the
+           body only if there is one, so a successful send is not a JSON-parse error. */
+        const text = await r.text();
+        return text ? JSON.parse(text) : null;
     }
 
     const brief = (m) => `#${m.id}\n  ${m.receivedDateTime ?? ''}\n  From: ${addrsOf([m.from])}\n  Subject: ${m.subject ?? ''}`;
@@ -159,18 +162,20 @@ export function graphMail({ fetch: fetchImpl = globalThis.fetch, token }) {
             const to = String(a.to ?? '').split(',').map((x) => x.trim()).filter(Boolean);
             if (!to.length) no('send needs a recipient (to)');
             const cc = String(a.cc ?? '').split(',').map((x) => x.trim()).filter(Boolean);
-            /* A file joined to the message: its bytes, already base64 (what Graph
-               wants), and a name. One attachment for now (the common need). */
-            const attach = String(a.attach ?? '');
+            /* Files joined to the message: bytes already base64 (what Graph wants)
+               and a name. Several possible: an `attachments` array, or one
+               `attach`+`attachName` (back-compat). */
+            const files = (Array.isArray(a.attachments) ? a.attachments : (a.attach ? [{ name: a.attachName, bytes: a.attach }] : []))
+                .map((f) => ({ name: String(f?.name || 'attachment'), bytes: String(f?.bytes ?? '') })).filter((f) => f.bytes);
             const message = {
                 subject: String(a.subject ?? ''),
                 body: { contentType: 'text', content: String(a.body ?? '') },
                 toRecipients: to.map((address) => ({ emailAddress: { address } })),
                 ...(cc.length ? { ccRecipients: cc.map((address) => ({ emailAddress: { address } })) } : {}),
-                ...(attach ? { attachments: [{ '@odata.type': '#microsoft.graph.fileAttachment', name: String(a.attachName || 'attachment'), contentBytes: attach }] } : {}),
+                ...(files.length ? { attachments: files.map((f) => ({ '@odata.type': '#microsoft.graph.fileAttachment', name: f.name, contentBytes: f.bytes })) } : {}),
             };
             await call(target, ctx, 'POST', '/me/sendMail', { message, saveToSentItems: true });
-            return { text: `Sent to ${to.join(', ')}${attach ? ` with ${a.attachName || 'an attachment'}` : ''}.`, size: 0 };
+            return { text: `Sent to ${to.join(', ')}${files.length ? ` with ${files.map((f) => f.name).join(', ')}` : ''}.`, size: 0 };
         },
     };
 }

package/host/connectors/mail.mjs

@@ -405,10 +405,11 @@ export function mail({ fetch: fetchImpl = globalThis.fetch, connect = tlsConnect
             if (Number(target.config?.smtpPort) > 0) port = Number(target.config.smtpPort);
             let sent;
             try {
-                sent = await smtpSend({ host, port, auth, from: user, to, subject: a.subject, body: a.body, attach: a.attach, attachName: a.attachName,
+                sent = await smtpSend({ host, port, auth, from: user, to, subject: a.subject, body: a.body, attach: a.attach, attachName: a.attachName, attachments: a.attachments,
                     ...(smtpConnect ? { connect: smtpConnect } : {}), ...(smtpSecure ? { secure: smtpSecure } : {}) });
             } catch (e) { if (e instanceof Refused) throw e; no(`${target.title}: ${e?.message ?? 'the message could not be sent'}`); }
-            return { text: `Sent to ${sent.join(', ')}${a.attach ? ` with ${a.attachName || 'an attachment'}` : ''}.`, size: 0 };
+            const names = Array.isArray(a.attachments) ? a.attachments.map((f) => f.name) : (a.attach ? [a.attachName || 'an attachment'] : []);
+            return { text: `Sent to ${sent.join(', ')}${names.length ? ` with ${names.join(', ')}` : ''}.`, size: 0 };
         },
     };
 

package/host/smtp.mjs

@@ -19,22 +19,30 @@ export function address(a) {
     return s;
 }
 
-/* An RFC-822 message from plain fields; headers come only from here. With an
-   `attach` (base64 bytes) + `attachName`, a multipart/mixed message: the text and
-   then the file, so a message can carry one joined file. */
-export function buildMessage({ from, to, subject, body, attach, attachName, date = new Date() }) {
+/* Several files joined to a message, as {name, bytes(base64)}. Takes an
+   `attachments` array, or a single `attach` + `attachName` (back-compat). */
+export function joinedFiles({ attach, attachName, attachments } = {}) {
+    const list = Array.isArray(attachments) ? attachments : (attach ? [{ name: attachName, bytes: attach }] : []);
+    return list.map((f) => ({ name: String(f?.name || 'attachment').replace(/[\r\n"\\]/g, ''), bytes: String(f?.bytes ?? '') })).filter((f) => f.bytes);
+}
+
+/* An RFC-822 message from plain fields; headers come only from here. With one or
+   more joined files (`attachments`, or a single `attach`+`attachName`), a
+   multipart/mixed message: the text, then each file. */
+export function buildMessage({ from, to, subject, body, attach, attachName, attachments, date = new Date() }) {
     const header = (name, value) => `${name}: ${String(value).replace(/[\r\n]+/g, ' ').trim()}`;
     const top = [header('From', from), header('To', to.join(', ')), header('Subject', subject ?? ''), header('Date', date.toUTCString()), 'MIME-Version: 1.0'];
     const text = String(body ?? '').replace(/\r?\n/g, '\r\n');
-    if (attach) {
-        const name = String(attachName || 'attachment').replace(/[\r\n"\\]/g, '');
+    const files = joinedFiles({ attach, attachName, attachments });
+    if (files.length) {
         const b = `b_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
-        const b64 = String(attach).replace(/\s+/g, '').replace(/(.{76})/g, '$1\r\n');
-        return [...top,
-            `Content-Type: multipart/mixed; boundary="${b}"`, '',
-            `--${b}`, 'Content-Type: text/plain; charset=utf-8', 'Content-Transfer-Encoding: 8bit', '', text,
-            `--${b}`, `Content-Type: application/octet-stream; name="${name}"`, 'Content-Transfer-Encoding: base64', `Content-Disposition: attachment; filename="${name}"`, '', b64,
-            `--${b}--`, ''].join('\r\n');
+        const parts = [`--${b}`, 'Content-Type: text/plain; charset=utf-8', 'Content-Transfer-Encoding: 8bit', '', text];
+        for (const f of files) {
+            const b64 = f.bytes.replace(/\s+/g, '').replace(/(.{76})/g, '$1\r\n');
+            parts.push(`--${b}`, `Content-Type: application/octet-stream; name="${f.name}"`, 'Content-Transfer-Encoding: base64', `Content-Disposition: attachment; filename="${f.name}"`, '', b64);
+        }
+        parts.push(`--${b}--`, '');
+        return [...top, `Content-Type: multipart/mixed; boundary="${b}"`, '', ...parts].join('\r\n');
     }
     const lines = [...top, 'Content-Type: text/plain; charset=utf-8', 'Content-Transfer-Encoding: 8bit', '', text];
     return lines.join('\r\n');
@@ -72,7 +80,7 @@ class Line {
 /* Send one message. `auth` is { xoauth2 } for a provider, or { user, password } for
    a classic box. `connect` opens the plain socket, `secure` upgrades it after
    STARTTLS (tls.connect wrapping the same socket). */
-export async function send({ host, port = 587, auth, from, to, subject, body, attach, attachName, connect = netConnect, secure = (opts) => tlsConnect(opts) }) {
+export async function send({ host, port = 587, auth, from, to, subject, body, attach, attachName, attachments, connect = netConnect, secure = (opts) => tlsConnect(opts) }) {
     const sender = address(from);
     const rcpts = (Array.isArray(to) ? to : [to]).map(address);
     if (!rcpts.length) throw new Error('no recipient');
@@ -98,7 +106,7 @@ export async function send({ host, port = 587, auth, from, to, subject, body, at
         await step(`MAIL FROM:<${sender}>`, 250);
         for (const r of rcpts) await step(`RCPT TO:<${r}>`, 250);
         await step('DATA', 354);
-        const message = buildMessage({ from: sender, to: rcpts, subject, body, attach, attachName })
+        const message = buildMessage({ from: sender, to: rcpts, subject, body, attach, attachName, attachments })
             .split('\r\n').map((l) => (l.startsWith('.') ? `.${l}` : l)).join('\r\n'); /* dot-stuffing */
         io.write(`${message}\r\n.\r\n`);
         const done = await io.reply();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavarium-tether",
-  "version": "0.1.0-next.21",
+  "version": "0.1.0-next.23",
   "description": "Clavarium Tether: an AI agent acts outside its own machine on a tether: levels per target, a person's approval, a journal and a stop (a command and an MCP server for agents, a keeper and a screen for the application). One dependency: ssh2, for the SSH connector.",
   "license": "MIT",
   "homepage": "https://github.com/clavarium/clavarium-tether#readme",

package/server/mcp.mjs

@@ -76,6 +76,7 @@ export async function ask(dir, verb, args = {}, { wait = WAIT_MS, grace = GRACE_
 
 /* ---- MCP ---- */
 const S = (description) => ({ type: 'string', description });
+const CATS = { type: 'array', description: 'personal Outlook categories (colour labels, invisible to the other participants), e.g. ["Internal"]; on update, [] clears them', items: { type: 'string' } };
 const TARGET = S('a target you were given (see targets)');
 const WHY = S('one short line for the person: why you do this');
 const TAB = { type: 'number', description: 'which granted tab (its id from browser-tabs); your active one by default' };
@@ -112,15 +113,17 @@ export const TOOLS = [
     tool('mail-move', 'Move a message to another folder. A person may approve: say why.', { target: TARGET, uid: S('the message id from a list'), mailbox: S('the destination folder'), why: WHY }, ['target', 'uid', 'mailbox']),
     tool('mail-flag', 'Mark a message read/unread or flagged/unflagged. A person may approve: say why.', { target: TARGET, uid: S('the message id from a list'), flag: S('read, unread, flagged or unflagged'), why: WHY }, ['target', 'uid', 'flag']),
     tool('mail-delete', 'Delete a message (to Trash / Deleted Items) by its number (uid). A person may approve: say why.', { target: TARGET, uid: S('the message id from a list'), mailbox: S('a folder; INBOX by default'), why: WHY }, ['target', 'uid']),
-    tool('mail-send', 'Send a message from the mailbox, optionally with one file joined. A person may approve: say why.', { target: TARGET, to: S('recipients, comma-separated'), subject: { type: 'string' }, body: { type: 'string' }, cc: S('cc recipients, comma-separated, optional'), attach: S("a file to join, as base64 bytes (<=~750KB); read a file in your machine and base64 it"), attachName: S('the file name for the attachment'), why: WHY }, ['target', 'to', 'subject', 'body']),
-    tool('calendar-list', 'Events of a calendar target, soonest first. By default from now on; give from and/or to (ISO date or date-time) to look at any past or future window, e.g. a given week or month.', { target: TARGET, from: S('start of the window, ISO date or date-time; now by default'), to: S('end of the window, ISO; a year after "from" by default') }, ['target']),
+    tool('mail-send', 'Send a message from the mailbox, optionally with one or more files joined (all of them go, or the send is refused). A person may approve: say why.', { target: TARGET, to: S('recipients, comma-separated'), subject: { type: 'string' }, body: { type: 'string' }, cc: S('cc recipients, comma-separated, optional'), attachments: { type: 'array', description: 'files to join, each { name, bytes } with bytes base64-encoded', items: { type: 'object', properties: { name: S('the file name'), bytes: S('the file as base64') }, required: ['bytes'] } }, attach: S("a single file to join, as base64 bytes (shorthand for one attachment)"), attachName: S('the file name, with attach'), why: WHY }, ['target', 'to', 'subject', 'body']),
+    tool('calendar-list', 'Events of a calendar target, soonest first. By default from now on; give from and/or to (ISO date or date-time) to look at any past or future window, e.g. a given week or month. Each event shows its categories. Give category to keep only one category\'s events (Microsoft).', { target: TARGET, from: S('start of the window, ISO date or date-time; now by default'), to: S('end of the window, ISO; a year after "from" by default'), category: S('only the events of this category (Microsoft)') }, ['target']),
+    tool('calendar-categories', "The calendar mailbox's own categories — their names and colours (Microsoft). A read. A category is a personal label, invisible to the other participants.", { target: TARGET }, ['target']),
     tool('calendar-read', 'One event in full by its id.', { target: TARGET, id: { type: 'string' } }, ['target', 'id']),
-    tool('calendar-create', 'Create an event. A person may approve: say why.', { target: TARGET, title: { type: 'string' }, start: S('ISO date-time, or a date for all-day'), end: S('ISO date-time, or a date'), where: S('a place, optional'), why: WHY }, ['target', 'title', 'start', 'end']),
-    tool('calendar-attach', 'Join a file to an event (Microsoft). A person may approve: say why.', { target: TARGET, id: S('the event id from a list'), attach: S('the file as base64 bytes'), attachName: S('the file name'), why: WHY }, ['target', 'id', 'attach']),
+    tool('calendar-freebusy', "See when other people are busy, to find a time together (Microsoft). Returns only busy/free blocks over the window, never their calendar contents. A read.", { target: TARGET, who: S('the people, comma-separated email addresses (up to 20)'), from: S('start of the window, local ISO date or date-time; now by default'), to: S('end of the window, local ISO; 7 days after "from" by default') }, ['target', 'who']),
+    tool('calendar-create', 'Create an event, with notes and invitees. Times are the person\'s local time. A person may approve: say why.', { target: TARGET, title: { type: 'string' }, start: S('local ISO date-time, or a date for all-day'), end: S('local ISO date-time, or a date'), where: S('a place, optional'), notes: S('the event body/notes, optional'), with: S('invitees, comma-separated emails, optional (they get an invitation)'), categories: CATS, why: WHY }, ['target', 'title', 'start', 'end']),
+    tool('calendar-attach', 'Join a file to an event (Microsoft). It reaches every participant on the next invitation update/resend; the result says who. Refused if a participant is external, unless share:true. A person may approve: say why.', { target: TARGET, id: S('the event id from a list'), attach: S('the file as base64 bytes'), attachName: S('the file name'), share: { type: 'boolean', description: 'attach even though a participant is external' }, why: WHY }, ['target', 'id', 'attach']),
     tool('calendar-detach', 'Remove an attachment from an event (Microsoft), by its file name or 1-based number. A person may approve: say why.', { target: TARGET, id: S('the event id from a list'), which: S('the attachment file name, or its number'), why: WHY }, ['target', 'id', 'which']),
     tool('calendar-delete', 'Delete an event. A person may approve: say why.', { target: TARGET, id: S('the event id from a list'), why: WHY }, ['target', 'id']),
     tool('calendar-respond', 'Answer a meeting invitation — accept, decline or tentative (Microsoft). A person may approve: say why.', { target: TARGET, id: S('the event id from a list'), answer: S('accept, decline or tentative'), comment: S('a short note to the organiser, optional'), why: WHY }, ['target', 'id', 'answer']),
-    tool('calendar-update', 'Change an event — any of title, start, end, where (Microsoft). A person may approve: say why.', { target: TARGET, id: S('the event id from a list'), title: S('new title, optional'), start: S('new start, ISO, optional'), end: S('new end, ISO, optional'), where: S('new place, optional'), why: WHY }, ['target', 'id']),
+    tool('calendar-update', 'Change an event — any of title, start, end, where, notes, invitees (Microsoft). A person may approve: say why.', { target: TARGET, id: S('the event id from a list'), title: S('new title, optional'), start: S('new start, local ISO, optional'), end: S('new end, local ISO, optional'), where: S('new place, optional'), notes: S('new body/notes, optional'), with: S('invitees, comma-separated emails, optional'), categories: CATS, why: WHY }, ['target', 'id']),
     tool('contacts-list', 'The contacts of an address-book target: name, emails, phones.', { target: TARGET }, ['target']),
     tool('contacts-search', 'Contacts whose name or email matches a word, briefly.', { target: TARGET, text: S('a name or part of one to look for') }, ['target', 'text']),
     tool('contacts-read', 'One contact in full by its id.', { target: TARGET, id: { type: 'string' } }, ['target', 'id']),

package/server/name.mjs

@@ -6,7 +6,7 @@
 export const NAME = 'tether';
 export const PRODUCT = 'Clavarium Tether';
 export const PACKAGE = `clavarium-${NAME}`;
-export const VERSION = '0.1.0-next.21';
+export const VERSION = '0.1.0-next.23';
 /* The agent's folder: where its asks and the keeper's answers are written. */
 export const FOLDER = `.${NAME}`;
 /* $TETHER_DIR: the agent's folder; $TETHER_STORE: the keeper's store (serve). */

package/server/verbs.mjs

@@ -17,6 +17,8 @@ const FOLDERS = ['computer', 'ssh', 'files'];
 /* Sizes an agent may send. What a target sends back is capped by its connector. */
 export const COMMAND_MAX = 4000;
 export const TEXT_MAX = 1_000_000;
+/* The total base64 of a message's attachments (~22 MB of real files). Over it, the send is refused, not sent short. */
+export const ATTACH_MAX = 30 * 1024 * 1024;
 export const PATH_MAX = 1000;
 export const WHY_MAX = 300;
 
@@ -70,12 +72,14 @@ export const VERBS = Object.freeze({
     'mail.send': { reads: false, kinds: ['mail'], needs: ['to', 'subject', 'body'] },
     'calendar.list': { reads: true, kinds: ['calendar'], needs: [] },
     'calendar.read': { reads: true, kinds: ['calendar'], needs: ['id'] },
+    'calendar.freebusy': { reads: true, kinds: ['calendar'], needs: ['who'] },
     'calendar.create': { reads: false, kinds: ['calendar'], needs: ['title', 'start', 'end'] },
     'calendar.attach': { reads: false, kinds: ['calendar'], needs: ['id', 'attach'] },
     'calendar.detach': { reads: false, kinds: ['calendar'], needs: ['id', 'which'] },
     'calendar.delete': { reads: false, kinds: ['calendar'], needs: ['id'] },
     'calendar.respond': { reads: false, kinds: ['calendar'], needs: ['id', 'answer'] },
     'calendar.update': { reads: false, kinds: ['calendar'], needs: ['id'] },
+    'calendar.categories': { reads: true, kinds: ['calendar'], needs: [] },
     'contacts.list': { reads: true, kinds: ['contacts'], needs: [] },
     'contacts.search': { reads: true, kinds: ['contacts'], needs: ['text'] },
     'contacts.read': { reads: true, kinds: ['contacts'], needs: ['id'] },
@@ -118,6 +122,9 @@ export function check(verb, a = {}) {
     };
     /* Which granted tab a browser verb acts on (optional: none means the agent's active one). */
     const tab = () => { if (a.tab !== undefined && a.tab !== null && a.tab !== '') out.tab = typeof a.tab === 'number' ? Math.trunc(a.tab) : oneLine(a.tab, 100); };
+    /* Event categories: a clean list, up to 25, each short. An empty list is kept
+       (it clears the categories on an update); undefined leaves them untouched. */
+    const cats = () => { if (a.categories === undefined || a.categories === null) return; out.categories = (Array.isArray(a.categories) ? a.categories : [a.categories]).map((c) => oneLine(c, 200)).filter(Boolean).slice(0, 25); };
     const num = (k) => { if (a[k] !== undefined && a[k] !== null && a[k] !== '') { const n = Number(a[k]); if (Number.isFinite(n)) out[k] = Math.trunc(n); } };
     switch (verb) {
         case 'terminal.read': if (a.lines !== undefined) out.lines = Math.max(1, Math.min(2000, Math.trunc(Number(a.lines)) || 0)); break;
@@ -163,15 +170,26 @@ export function check(verb, a = {}) {
         case 'mail.move': str('uid', 1024); str('mailbox', 200); break;
         case 'mail.flag': str('uid', 1024); str('flag', 40); break;
         case 'mail.delete': str('uid', 1024); str('mailbox', 200); break;
-        case 'mail.send': str('to', 1000); str('subject', 400); str('body', TEXT_MAX, true); str('cc', 1000); str('attach', TEXT_MAX, true); str('attachName', 200); break;
-        case 'calendar.list': str('from', 64); str('to', 64); break;
+        case 'mail.send': {
+            str('to', 1000); str('subject', 400); str('body', TEXT_MAX, true); str('cc', 1000); str('attach', TEXT_MAX, true); str('attachName', 200);
+            if (Array.isArray(a.attachments)) {
+                let total = 0;
+                const files = a.attachments.slice(0, 50).map((f) => ({ name: oneLine(f?.name, 200) || 'attachment', bytes: String(f?.bytes ?? '') })).filter((f) => f.bytes);
+                for (const f of files) total += f.bytes.length;
+                if (total > ATTACH_MAX) no(`the attachments are too large to send together (over ${Math.round(ATTACH_MAX / 1024 / 1024)} MB of files)`);
+                if (files.length) out.attachments = files;
+            }
+            break;
+        }
+        case 'calendar.list': str('from', 64); str('to', 64); str('category', 200); break;
         case 'calendar.read': str('id', 1024); break;
-        case 'calendar.create': str('title', 400); str('start', 64); str('end', 64); str('where', 400); break;
-        case 'calendar.attach': str('id', 1024); str('attach', TEXT_MAX, true); str('attachName', 200); break;
+        case 'calendar.freebusy': str('who', 2000); str('from', 64); str('to', 64); break;
+        case 'calendar.create': str('title', 400); str('start', 64); str('end', 64); str('where', 400); str('notes', TEXT_MAX, true); str('with', 1000); cats(); break;
+        case 'calendar.attach': str('id', 1024); str('attach', TEXT_MAX, true); str('attachName', 200); if (a.share === true || a.share === 'true') out.share = true; break;
         case 'calendar.detach': str('id', 1024); str('which', 400); break;
         case 'calendar.delete': str('id', 1024); break;
         case 'calendar.respond': str('id', 1024); str('answer', 40); str('comment', 400); break;
-        case 'calendar.update': str('id', 1024); str('title', 400); str('start', 64); str('end', 64); str('where', 400); break;
+        case 'calendar.update': str('id', 1024); str('title', 400); str('start', 64); str('end', 64); str('where', 400); str('notes', TEXT_MAX, true); str('with', 1000); cats(); break;
         case 'contacts.attach': str('id', 1024); str('attach', TEXT_MAX, true); str('attachName', 200); break;
         case 'contacts.search': str('text', 200); break;
         case 'contacts.read': str('id', 1024); break;
@@ -211,22 +229,29 @@ export function detail(verb, a = {}) {
         case 'mail.list': return a.mailbox ?? '';
         case 'mail.read': return `#${a.uid}`;
         case 'mail.search': return a.text;
-        case 'mail.move': return `#${a.uid} → ${a.mailbox}`;
-        case 'mail.flag': return `#${a.uid} ${a.flag}`;
-        case 'mail.delete': return `delete message #${a.uid}`;
-        case 'mail.send': return `to ${a.to}: ${a.subject ?? ''}${a.attach ? ` + ${a.attachName || 'a file'}` : ''}`;
+        /* Ids from Graph are long and opaque; the approval says the ACTION, and the
+           agent's "why" names the thing. So no raw id dumped into the one line. */
+        case 'mail.move': return `move a message → ${a.mailbox}`;
+        case 'mail.flag': return `mark a message ${a.flag}`;
+        case 'mail.delete': return 'delete a message';
+        case 'mail.send': {
+            const kb = (b64) => Math.max(1, Math.round((String(b64).length * 3 / 4) / 1024));
+            const files = Array.isArray(a.attachments) ? a.attachments.map((f) => `${f.name} (${kb(f.bytes)} KB)`) : (a.attach ? [`${a.attachName || 'a file'} (${kb(a.attach)} KB)`] : []);
+            return `to ${a.to}: ${a.subject ?? ''}${files.length ? ` + ${files.join(', ')}` : ''}`;
+        }
         case 'calendar.read': return a.id;
+        case 'calendar.freebusy': return a.who;
         case 'calendar.create': return `${a.title} (${a.start})`;
-        case 'calendar.attach': return `${a.attachName || 'a file'} → event ${a.id}`;
-        case 'calendar.detach': return `remove ${a.which} from event ${a.id}`;
-        case 'calendar.delete': return `delete event ${a.id}`;
-        case 'calendar.respond': return `${a.answer} invitation ${a.id}`;
-        case 'calendar.update': return `event ${a.id}${a.title ? `: ${a.title}` : ''}`;
+        case 'calendar.attach': return `${a.attachName || 'a file'} → an event`;
+        case 'calendar.detach': return `remove ${a.which || 'a file'} from an event`;
+        case 'calendar.delete': return 'delete an event';
+        case 'calendar.respond': return `${a.answer} an invitation`;
+        case 'calendar.update': return `change an event${a.title ? ` → ${a.title}` : ''}`;
         case 'contacts.read': return a.id;
         case 'contacts.create': return `add ${a.name || a.email || 'a contact'}`;
-        case 'contacts.update': return `contact ${a.id}`;
-        case 'contacts.delete': return `delete contact ${a.id}`;
-        case 'contacts.attach': return `a photo → contact ${a.id}`;
+        case 'contacts.update': return 'change a contact';
+        case 'contacts.delete': return 'delete a contact';
+        case 'contacts.attach': return "set a contact's photo";
         default: return '';
     }
 }