ofw-mcp 2.19.2 → 2.19.4

package/dist/tools/calendar.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { jsonResponse, textResponse } from './_shared.js';
+import { jsonResponse, requestWrite, textResponse, UnconfirmedWriteError, unconfirmedWriteResponse } from './_shared.js';
+import { CONFIRM_NOTE, confirmTokenParam, confirmWrite, stateRevision } from './_confirm.js';
 import { getCalendarWritesAllowed } from '../config.js';
 import { parseLenient } from '@chrischall/mcp-utils';
 // OFW's real event-write API (reverse-engineered from the web app bundle):
@@ -104,6 +105,47 @@ function detailToWriteArgs(d) {
         pickUpParentId: d.pickUpParent?.userId,
     };
 }
+const SHARED = 'shared with co-parent';
+const PRIVATE = 'private (only you)';
+/**
+ * The human-readable form of an event for a confirmation preview: the fields
+ * a person checks (title, when, where, who sees it), with tagged users named
+ * wherever OFW's own event detail named them. An id OFW gave no name for is
+ * reported with `name: null` — never an invented one.
+ */
+function describeEvent(a, names = new Map()) {
+    const who = (id) => ({ userId: id, name: names.get(id) ?? null });
+    const out = {
+        title: a.title,
+        startDate: a.startDate,
+        endDate: a.endDate ?? a.startDate,
+        ...(a.allDay ? { allDay: true } : { startTime: a.startTime, endTime: a.endTime }),
+        visibility: a.privateEvent ? PRIVATE : SHARED,
+    };
+    if (a.location)
+        out.location = a.location;
+    if (a.notes)
+        out.notes = a.notes;
+    if (a.children !== undefined)
+        out.children = a.children.map((id) => who(id));
+    if (a.eventParentId !== undefined)
+        out.eventParent = who(a.eventParentId);
+    if (a.dropOffParentId !== undefined)
+        out.dropOffParent = who(a.dropOffParentId);
+    if (a.pickUpParentId !== undefined)
+        out.pickUpParent = who(a.pickUpParentId);
+    return out;
+}
+/** userId → name for every tagged person the event detail names. */
+function namesIn(d) {
+    const names = new Map();
+    for (const ref of [...(d.children ?? []), d.eventParent, d.dropOffParent, d.pickUpParent]) {
+        const name = ref?.name;
+        if (ref && typeof name === 'string' && name)
+            names.set(ref.userId, name);
+    }
+    return names;
+}
 export function registerCalendarTools(server, client) {
     // Calendar writes land on the court-visible record with no draft stage, but
     // events are reversible — 'all' mode, or 'drafts' + OFW_CALENDAR_WRITES=true.
@@ -123,14 +165,48 @@ export function registerCalendarTools(server, client) {
     });
     if (allowWrites)
         server.registerTool('ofw_create_event', {
-            description: 'Create a calendar event in OurFamilyWizard. Unless privateEvent is true, the event is immediately visible to the co-parent — there is no draft stage.',
-            annotations: { destructiveHint: false },
+            description: 'Create a calendar event in OurFamilyWizard. Unless privateEvent is true, the event is immediately visible to the co-parent — there is no draft stage — so a shared event is confirmed first (a private one is not). If the request fails without a definitive answer the result is EVENT_UNCONFIRMED: the event may already exist, so do NOT retry until ofw_list_events shows it did not land. ' + CONFIRM_NOTE,
+            // Additive, so not destructive — but it lands on a shared calendar
+            // outside this machine, which openWorldHint says to the host.
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
             inputSchema: z.object({
                 title: z.string(),
                 ...eventWriteFields,
+                confirmToken: confirmTokenParam,
             }),
-        }, async (args) => {
-            const raw = await client.request('POST', '/pub/v3/events', buildEventPayload(args));
+        }, async (args, ctx) => {
+            const { confirmToken, ...fields } = args;
+            const payload = buildEventPayload(fields);
+            if (!fields.privateEvent) {
+                const gate = await confirmWrite(ctx, {
+                    tool: 'ofw_create_event',
+                    action: 'ofw.event.create',
+                    message: 'Review and confirm this OurFamilyWizard calendar event. It is shared with the co-parent and appears on their calendar immediately.',
+                    target: 'event:new',
+                    payload,
+                    preview: {
+                        action: 'Create shared OurFamilyWizard calendar event',
+                        event: describeEvent(fields),
+                        warning: 'Visible to the co-parent immediately; part of the court-visible record.',
+                    },
+                    confirmToken,
+                });
+                if (gate)
+                    return gate;
+            }
+            let raw;
+            try {
+                raw = await requestWrite(client, 'POST', '/pub/v3/events', payload);
+            }
+            catch (e) {
+                if (!(e instanceof UnconfirmedWriteError))
+                    throw e;
+                return unconfirmedWriteResponse(e, {
+                    result: 'EVENT_UNCONFIRMED',
+                    what: 'create this event',
+                    checkWith: `ofw_list_events for ${fields.startDate} (look for "${fields.title}")`,
+                });
+            }
             const event = parseLenient(eventDetailSchema, raw, { label: 'ofw-mcp', context: 'POST /pub/v3/events', mode: 'strict' });
             return jsonResponse({
                 note: `Event created. Use eventRecurrenceId ${event.eventRecurrenceId} as eventId for ofw_update_event/ofw_delete_event.`,
@@ -139,7 +215,7 @@ export function registerCalendarTools(server, client) {
         });
     if (allowWrites)
         server.registerTool('ofw_update_event', {
-            description: 'Update an existing OurFamilyWizard calendar event. Fetches the event, applies the given changes, and writes the merged result back (OFW has no partial update).',
+            description: 'Update an existing OurFamilyWizard calendar event. Fetches the event, applies the given changes, and writes the merged result back (OFW has no partial update). A change to an event the co-parent can see (shared before or after the change) is confirmed first; the confirmation is bound to the event exactly as read, so if it changes on OFW in between (say the co-parent edited it) the update is refused instead of overwriting their edit. ' + CONFIRM_NOTE,
             annotations: { destructiveHint: true },
             inputSchema: z.object({
                 eventId: z.string().describe('Event id — the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event'),
@@ -157,15 +233,41 @@ export function registerCalendarTools(server, client) {
                 eventParentId: eventWriteFields.eventParentId,
                 dropOffParentId: eventWriteFields.dropOffParentId,
                 pickUpParentId: eventWriteFields.pickUpParentId,
+                confirmToken: confirmTokenParam,
             }),
-        }, async (args) => {
-            const { eventId, ...changes } = args;
+        }, async (args, ctx) => {
+            const { eventId, confirmToken, ...changes } = args;
             const id = encodeURIComponent(eventId);
+            // Re-read on EVERY call (phase 1 and phase 2 alike): the merge base and
+            // the confirmation's revision both come from this read.
             const rawDetail = await client.request('GET', `/pub/v3/events/${id}`);
             const current = parseLenient(eventDetailSchema, rawDetail, { label: 'ofw-mcp', context: `GET /pub/v3/events/${eventId}`, mode: 'strict' });
             const defined = Object.fromEntries(Object.entries(changes).filter(([, v]) => v !== undefined));
-            const merged = { ...detailToWriteArgs(current), ...defined };
-            await client.request('PUT', `/pub/v3/events/${id}`, buildEventPayload(merged));
+            const base = detailToWriteArgs(current);
+            const merged = { ...base, ...defined };
+            const payload = buildEventPayload(merged);
+            if (current.publicFlag || !merged.privateEvent) {
+                const names = namesIn(current);
+                const gate = await confirmWrite(ctx, {
+                    tool: 'ofw_update_event',
+                    action: 'ofw.event.update',
+                    message: `Review and confirm this change to the OurFamilyWizard event "${current.title}". The co-parent sees the updated event on their calendar.`,
+                    target: `event:${eventId}`,
+                    revision: stateRevision(base),
+                    payload,
+                    preview: {
+                        action: 'Update OurFamilyWizard calendar event',
+                        eventId,
+                        before: describeEvent(base, names),
+                        after: describeEvent(merged, names),
+                        warning: 'The co-parent sees this change; part of the court-visible record.',
+                    },
+                    confirmToken,
+                });
+                if (gate)
+                    return gate;
+            }
+            await client.request('PUT', `/pub/v3/events/${id}`, payload);
             // PUT responses aren't documented — re-fetch the detail as authoritative state.
             const rawAfter = await client.request('GET', `/pub/v3/events/${id}`);
             const event = parseLenient(eventDetailSchema, rawAfter, { label: 'ofw-mcp', context: `GET /pub/v3/events/${eventId} (post-update)`, mode: 'strict' });
@@ -173,15 +275,41 @@ export function registerCalendarTools(server, client) {
         });
     if (allowWrites)
         server.registerTool('ofw_delete_event', {
-            description: 'Delete an OurFamilyWizard calendar event',
-            annotations: { destructiveHint: true },
+            description: 'Delete an OurFamilyWizard calendar event. Reads the event first; deleting one the co-parent can see is confirmed first, with a preview of exactly which event (title, date, time) is removed, and is refused if the event changed on OFW after that preview. ' + CONFIRM_NOTE,
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
             inputSchema: z.object({
                 eventId: z.string().describe('Event id — the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event'),
                 includeFuture: z.boolean().describe('For repeating events: also delete future occurrences (default false)').optional(),
+                confirmToken: confirmTokenParam,
             }),
-        }, async (args) => {
+        }, async (args, ctx) => {
             const includeFuture = args.includeFuture ?? false;
-            await client.request('DELETE', `/pub/v3/events/${encodeURIComponent(args.eventId)}?includeFuture=${includeFuture}`);
-            return textResponse(`Event ${args.eventId} deleted`);
+            const id = encodeURIComponent(args.eventId);
+            const rawDetail = await client.request('GET', `/pub/v3/events/${id}`);
+            const current = parseLenient(eventDetailSchema, rawDetail, { label: 'ofw-mcp', context: `GET /pub/v3/events/${args.eventId}`, mode: 'strict' });
+            if (current.publicFlag) {
+                const base = detailToWriteArgs(current);
+                const gate = await confirmWrite(ctx, {
+                    tool: 'ofw_delete_event',
+                    action: 'ofw.event.delete',
+                    message: `Review and confirm deleting the OurFamilyWizard event "${current.title}". It disappears from the co-parent's calendar.`,
+                    target: `event:${args.eventId}`,
+                    revision: stateRevision(base),
+                    payload: { eventId: args.eventId, includeFuture },
+                    preview: {
+                        action: 'Delete shared OurFamilyWizard calendar event',
+                        eventId: args.eventId,
+                        event: describeEvent(base, namesIn(current)),
+                        includeFuture,
+                        ...(includeFuture ? { note: 'Future occurrences of this repeating event are deleted too.' } : {}),
+                        warning: 'Removed from the co-parent\'s calendar.',
+                    },
+                    confirmToken: args.confirmToken,
+                });
+                if (gate)
+                    return gate;
+            }
+            await client.request('DELETE', `/pub/v3/events/${id}?includeFuture=${includeFuture}`);
+            return textResponse(`Event ${args.eventId} ("${current.title}") deleted`);
         });
 }

package/dist/tools/draft-freshness.js

@@ -11,7 +11,7 @@ export class DraftFreshnessError extends Error {
 const FNV_OFFSET = 0xcbf29ce484222325n;
 const FNV_PRIME = 0x100000001b3n;
 const MASK64 = 0xffffffffffffffffn;
-function fnv1a64(s) {
+export function fnv1a64(s) {
     let h = FNV_OFFSET;
     for (let i = 0; i < s.length; i++) {
         h = (h ^ BigInt(s.charCodeAt(i))) * FNV_PRIME & MASK64;

package/dist/tools/expenses.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { jsonResponse } from './_shared.js';
+import { jsonResponse, requestWrite, UnconfirmedWriteError, unconfirmedWriteResponse } from './_shared.js';
+import { CONFIRM_NOTE, confirmTokenParam, confirmWrite } from './_confirm.js';
 import { offsetState, readUpstreamPaging, withPaginationFirst } from './pagination.js';
 import { getWriteMode } from '../config.js';
 export function registerExpenseTools(server, client) {
@@ -44,14 +45,47 @@ export function registerExpenseTools(server, client) {
     });
     if (allowWrites)
         server.registerTool('ofw_create_expense', {
-            description: 'Log a new expense in OurFamilyWizard',
-            annotations: { destructiveHint: false },
+            description: 'Log a new expense in OurFamilyWizard. The expense is a money claim that appears in the shared ledger in front of the co-parent immediately, and this server cannot delete it. If the request fails without a definitive answer the result is EXPENSE_UNCONFIRMED: the expense may already exist, so do NOT retry until ofw_list_expenses shows it did not land. ' + CONFIRM_NOTE,
+            // Not a harmless local write: the claim is co-parent-visible at once and
+            // this server has no way to take it back. destructiveHint keeps a host
+            // that auto-approves "non-destructive" tools from running it silently.
+            annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
             inputSchema: z.object({
                 amount: z.number().describe('Expense amount'),
                 description: z.string().describe('Expense description'),
+                confirmToken: confirmTokenParam,
             }),
-        }, async (args) => {
-            const data = await client.request('POST', '/pub/v2/expense/expenses', args);
+        }, async (args, ctx) => {
+            const { confirmToken, ...payload } = args;
+            const gate = await confirmWrite(ctx, {
+                tool: 'ofw_create_expense',
+                action: 'ofw.expense.create',
+                message: 'Review and confirm this OurFamilyWizard expense. It is logged in the shared ledger the co-parent sees immediately, and cannot be deleted through this server.',
+                target: 'expense:new',
+                payload,
+                preview: {
+                    action: 'Log OurFamilyWizard expense',
+                    amount: payload.amount,
+                    description: payload.description,
+                    warning: 'Visible to the co-parent immediately as a claim in the shared expense ledger; part of the court-visible record.',
+                },
+                confirmToken,
+            });
+            if (gate)
+                return gate;
+            let data;
+            try {
+                data = await requestWrite(client, 'POST', '/pub/v2/expense/expenses', payload);
+            }
+            catch (e) {
+                if (!(e instanceof UnconfirmedWriteError))
+                    throw e;
+                return unconfirmedWriteResponse(e, {
+                    result: 'EXPENSE_UNCONFIRMED',
+                    what: 'log this expense',
+                    checkWith: 'ofw_list_expenses (look for this amount and description among the newest expenses)',
+                });
+            }
             return jsonResponse(data);
         });
 }

package/dist/tools/journal.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { jsonResponse } from './_shared.js';
+import { jsonResponse, requestWrite, UnconfirmedWriteError, unconfirmedWriteResponse } from './_shared.js';
 import { offsetState, readUpstreamPaging, withPaginationFirst } from './pagination.js';
 import { getWriteMode } from '../config.js';
 export function registerJournalTools(server, client) {
@@ -45,7 +45,19 @@ export function registerJournalTools(server, client) {
                 body: z.string().describe('Entry text content'),
             }),
         }, async (args) => {
-            const data = await client.request('POST', '/pub/v1/journals', args);
+            let data;
+            try {
+                data = await requestWrite(client, 'POST', '/pub/v1/journals', args);
+            }
+            catch (e) {
+                if (!(e instanceof UnconfirmedWriteError))
+                    throw e;
+                return unconfirmedWriteResponse(e, {
+                    result: 'JOURNAL_UNCONFIRMED',
+                    what: 'create this journal entry',
+                    checkWith: 'ofw_list_journal_entries (look for this title among the newest entries)',
+                });
+            }
             return jsonResponse(data);
         });
 }