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

package/bin/cli.mjs

@@ -44,9 +44,10 @@ export const HELP = `${NAME}: act on the targets you were given (machines, folde
   ${NAME} mail TARGET send --to "a@b,c@d" --subject "..." --body "..." [--cc "..."] [--attach FILE]
   ${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"]
+  ${NAME} calendar TARGET update EVENT_ID [--title] [--start] [--end] [--where] [--notes] [--with]  (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 +70,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'];
 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 +83,7 @@ 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; }
         if (a.startsWith('--')) { if (argv[i + 1] === undefined) return { refused: `${a} needs a value` }; flags[a.slice(2)] = argv[++i]; continue; }
         words.push(a);
     }
@@ -155,16 +157,17 @@ export function read(argv) {
             switch (what) {
                 case 'list': return ['calendar.list', { target, ...(flags.from !== undefined ? { from: flags.from } : {}), ...(flags.to !== undefined ? { to: flags.to } : {}) }];
                 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]') ?? ['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 } : {}), ...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"]') ?? ['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 } : {}), ...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 });
 
@@ -37,8 +40,14 @@ const API = {
         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}` : ''}`,
+        body: ({ title, start, end, where, notes, attendees }) => ({
+            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' })) } : {}),
+        }),
     },
 };
 
@@ -63,7 +72,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) } : {}) }); }
@@ -162,12 +173,50 @@ 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)];
             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 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 }));
             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 +229,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,7 +318,9 @@ 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 (!Object.keys(patch).length) no('update needs at least one of: title, start, end, where, notes, with');
             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());

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 ?? ''}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavarium-tether",
-  "version": "0.1.0-next.21",
+  "version": "0.1.0-next.22",
   "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

@@ -115,12 +115,13 @@ export const TOOLS = [
     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('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)'), 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'), 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.22';
 /* 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

@@ -70,6 +70,7 @@ 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'] },
@@ -166,12 +167,13 @@ export function check(verb, a = {}) {
         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 '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); 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); 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 +213,25 @@ 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}`;
+        /* 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': return `to ${a.to}: ${a.subject ?? ''}${a.attach ? ` + ${a.attachName || 'a file'}` : ''}`;
         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 '';
     }
 }