forge-openclaw-plugin 0.2.27 → 0.2.29

package/dist/server/server/src/services/calendar-runtime.js

@@ -2,13 +2,21 @@ import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { CryptoProvider, PublicClientApplication } from "@azure/msal-node";
 import ical from "node-ical";
 import { logForgeDebug } from "../debug.js";
+import { buildMacOSLocalCalendarUrl, deleteMacOSLocalEvent, discoverMacOSLocalCalendars, ensureMacOSLocalForgeCalendar, getMacOSCalendarAuthStatus, openMacOSCalendarPrivacySettings, parseMacOSLocalCalendarUrl, requestMacOSCalendarAccess, upsertMacOSLocalEvent, listMacOSLocalEvents } from "./macos-calendar-helper.js";
 import { getGoogleCalendarOauthCallbackPath, isGoogleCalendarOriginAllowed, isGoogleCalendarLoopbackOrigin, resolveGoogleCalendarOauthPrivateConfig } from "./google-calendar-oauth-config.js";
 import { createDAVClient, DAVNamespaceShort } from "tsdav";
 import { getSettings } from "../repositories/settings.js";
-import { createCalendarConnectionRecord, deleteCalendarConnectionRecord, deleteEncryptedSecret, deleteExternalEventsForConnection, detachConnectionFromForgeEvents, getCalendarById, getCalendarConnectionById, getCalendarEventStorageRecord, getCalendarOverview, listCalendarConnections, listCalendarEventSources, listCalendars, listTaskTimeboxes, markCalendarEventSourcesSyncState, readEncryptedSecret, registerCalendarEventSourceProjection, recordCalendarActivity, storeEncryptedSecret, updateCalendarConnectionRecord, updateTaskTimebox, upsertCalendarEventRecord, upsertCalendarRecord } from "../repositories/calendar.js";
+import { createCalendarConnectionRecord, deleteCalendarConnectionRecord, deleteEncryptedSecret, deleteExternalEventsForConnection, detachConnectionFromForgeEvents, getCalendarById, getCalendarConnectionById, getCalendarEventStorageRecord, getCalendarOverview, isSupersededCalendarConnection, listCalendarConnections, listCalendarEventSources, listCalendars, listTaskTimeboxes, markCalendarEventSourcesSyncState, readEncryptedSecret, registerCalendarEventSourceProjection, recordCalendarActivity, storeEncryptedSecret, rehomeCalendarConnectionReferences, updateCalendarConnectionRecord, updateTaskTimebox, upsertCalendarEventRecord, upsertCalendarRecord } from "../repositories/calendar.js";
 function isWritableCalendarCredentials(credentials) {
     return credentials.provider !== "microsoft";
 }
+function normalizeOptionalUrl(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? normalizeUrl(trimmed) : null;
+}
 const GOOGLE_CALDAV_URL = "https://apidata.googleusercontent.com/caldav/v2/";
 const GOOGLE_OAUTH_AUTHORIZE_URL = "https://accounts.google.com/o/oauth2/v2/auth";
 const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
@@ -41,6 +49,14 @@ export class CalendarConnectionConflictError extends Error {
         this.connectionId = connectionId;
     }
 }
+export class CalendarConnectionOverlapError extends Error {
+    connectionIds;
+    constructor(message, connectionIds) {
+        super(message);
+        this.name = "CalendarConnectionOverlapError";
+        this.connectionIds = connectionIds;
+    }
+}
 function requireSecretRecord(secrets, secretId) {
     const cipherText = readEncryptedSecret(secretId);
     if (!cipherText) {
@@ -349,6 +365,13 @@ function normalizeUrl(value) {
 function normalizeAccountIdentity(value) {
     return value.trim().toLowerCase();
 }
+function normalizeCalendarKey(value) {
+    return value.trim().replace(/\s+/g, " ").toLowerCase();
+}
+function accountIdentityKeyForMacOSSource(input) {
+    const normalizedTitle = normalizeAccountIdentity(input.sourceTitle);
+    return `${input.sourceType}:${normalizedTitle}`;
+}
 function buildGoogleCalendarCollectionUrl(calendarId) {
     return normalizeUrl(new URL(`${encodeURIComponent(calendarId)}/events`, GOOGLE_CALDAV_URL).toString());
 }
@@ -691,6 +714,29 @@ function mapMicrosoftEventToSyncInput(calendarId, event) {
     };
 }
 async function createProviderClient(credentials) {
+    if (credentials.provider === "macos_local") {
+        const discovery = await discoverMacOSLocalCalendars();
+        const source = discovery.sources.find((entry) => entry.sourceId === credentials.sourceId);
+        if (!source) {
+            throw new Error("Forge could not find that macOS calendar source anymore. Reconnect it from Settings -> Calendar.");
+        }
+        return {
+            mode: "macos_local",
+            accountLabel: source.accountLabel,
+            serverUrl: "forge-macos-local://eventkit/",
+            principalUrl: null,
+            homeUrl: null,
+            sourceId: source.sourceId,
+            sourceTitle: source.sourceTitle,
+            sourceType: source.sourceType,
+            accountIdentityKey: credentials.accountIdentityKey,
+            calendars: source.calendars.map((calendar) => ({
+                ...calendar,
+                url: buildMacOSLocalCalendarUrl(source.sourceId, calendar.calendarId)
+            })),
+            credentials
+        };
+    }
     if (credentials.provider === "microsoft") {
         const client = createMicrosoftPublicClient({
             clientId: credentials.clientId,
@@ -815,6 +861,32 @@ async function createProviderClient(credentials) {
     };
 }
 function mapDiscoveryPayload(provider, state) {
+    if (state.mode === "macos_local") {
+        return {
+            provider,
+            accountLabel: state.accountLabel,
+            serverUrl: state.serverUrl,
+            principalUrl: null,
+            homeUrl: null,
+            calendars: state.calendars.map((calendar) => ({
+                url: calendar.url,
+                displayName: safeDisplayName(calendar.title, "Calendar"),
+                description: calendar.description,
+                color: calendar.color,
+                timezone: normalizeTimezone(calendar.timezone),
+                isPrimary: calendar.isPrimary,
+                canWrite: calendar.canWrite,
+                selectedByDefault: !isForgeName(calendar.title),
+                isForgeCandidate: isForgeName(calendar.title),
+                sourceId: calendar.sourceId,
+                sourceTitle: calendar.sourceTitle,
+                sourceType: calendar.sourceType,
+                calendarType: calendar.calendarType,
+                hostCalendarId: calendar.calendarId,
+                canonicalKey: `${state.accountIdentityKey}:${normalizeCalendarKey(calendar.title)}`
+            }))
+        };
+    }
     if (state.mode === "microsoft") {
         return {
             provider,
@@ -833,7 +905,13 @@ function mapDiscoveryPayload(provider, state) {
                 isPrimary: state.primaryCalendarId === calendar.id,
                 canWrite: false,
                 selectedByDefault: true,
-                isForgeCandidate: false
+                isForgeCandidate: false,
+                sourceId: null,
+                sourceTitle: null,
+                sourceType: null,
+                calendarType: null,
+                hostCalendarId: null,
+                canonicalKey: null
             }))
         };
     }
@@ -854,7 +932,13 @@ function mapDiscoveryPayload(provider, state) {
                 isPrimary: false,
                 canWrite: canWriteDavCalendar(calendar),
                 selectedByDefault: !isForgeName(displayName),
-                isForgeCandidate: isForgeName(displayName)
+                isForgeCandidate: isForgeName(displayName),
+                sourceId: null,
+                sourceTitle: null,
+                sourceType: null,
+                calendarType: null,
+                hostCalendarId: null,
+                canonicalKey: null
             };
         })
     };
@@ -1348,6 +1432,32 @@ function mapDavObjectToEvents(calendarUrl, object, ownership) {
     return events;
 }
 function mapCalendarRecord(calendar, options) {
+    if ("calendarId" in calendar) {
+        const forgeCalendarUrl = options.forgeCalendarUrl
+            ? normalizeUrl(options.forgeCalendarUrl)
+            : null;
+        return {
+            remoteId: normalizeUrl(calendar.url),
+            title: safeDisplayName(calendar.title, "Calendar"),
+            description: calendar.description,
+            color: calendar.color,
+            timezone: normalizeTimezone(calendar.timezone),
+            isPrimary: calendar.isPrimary,
+            canWrite: calendar.canWrite,
+            selectedForSync: forgeCalendarUrl
+                ? normalizeUrl(calendar.url) !== forgeCalendarUrl
+                : true,
+            forgeManaged: forgeCalendarUrl
+                ? normalizeUrl(calendar.url) === forgeCalendarUrl
+                : false,
+            sourceId: calendar.sourceId,
+            sourceTitle: calendar.sourceTitle,
+            sourceType: calendar.sourceType,
+            calendarType: calendar.calendarType,
+            hostCalendarId: calendar.calendarId,
+            canonicalKey: `${options.accountIdentityKey ?? ""}:${normalizeCalendarKey(calendar.title)}`
+        };
+    }
     if ("url" in calendar) {
         const forgeCalendarUrl = options.forgeCalendarUrl ? normalizeUrl(options.forgeCalendarUrl) : null;
         const title = safeDisplayName(calendar.displayName, "Calendar");
@@ -1361,7 +1471,13 @@ function mapCalendarRecord(calendar, options) {
             isPrimary: false,
             canWrite: canWriteDavCalendar(calendar),
             selectedForSync: forgeCalendarUrl ? remoteUrl !== forgeCalendarUrl : true,
-            forgeManaged: forgeCalendarUrl ? remoteUrl === forgeCalendarUrl : false
+            forgeManaged: forgeCalendarUrl ? remoteUrl === forgeCalendarUrl : false,
+            sourceId: null,
+            sourceTitle: null,
+            sourceType: null,
+            calendarType: null,
+            hostCalendarId: null,
+            canonicalKey: remoteUrl
         };
     }
     return {
@@ -1375,11 +1491,73 @@ function mapCalendarRecord(calendar, options) {
         isPrimary: options.primaryCalendarId === calendar.id,
         canWrite: false,
         selectedForSync: true,
-        forgeManaged: false
+        forgeManaged: false,
+        sourceId: null,
+        sourceTitle: null,
+        sourceType: null,
+        calendarType: null,
+        hostCalendarId: null,
+        canonicalKey: microsoftCalendarUrl(calendar.id)
+    };
+}
+function mapMacOSLocalEventToSyncInput(calendarUrl, event, ownership) {
+    return {
+        calendarRemoteId: normalizeUrl(calendarUrl),
+        remoteId: event.eventId,
+        remoteHref: null,
+        remoteEtag: null,
+        ownership,
+        status: "confirmed",
+        title: event.title,
+        description: event.notes,
+        location: event.location,
+        startAt: event.startAt,
+        endAt: event.endAt,
+        isAllDay: event.allDay,
+        availability: event.availability,
+        eventType: "",
+        categories: [],
+        rawPayload: {
+            externalId: event.externalId,
+            occurrenceDate: event.occurrenceDate
+        },
+        remoteUpdatedAt: event.lastModifiedAt,
+        deletedAt: null
     };
 }
 async function publishTaskTimeboxes(state, forgeCalendarUrl, connectionId) {
-    if (state.mode !== "dav" || !forgeCalendarUrl) {
+    if (!forgeCalendarUrl) {
+        return;
+    }
+    if (state.mode === "macos_local") {
+        const forgeCalendar = state.calendars.find((calendar) => normalizeUrl(calendar.url) === normalizeUrl(forgeCalendarUrl));
+        if (!forgeCalendar || !forgeCalendar.canWrite) {
+            return;
+        }
+        const horizon = {
+            from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(),
+            to: new Date(Date.now() + 180 * 24 * 60 * 60 * 1000).toISOString()
+        };
+        const timeboxes = listTaskTimeboxes(horizon);
+        for (const timebox of timeboxes) {
+            const { event } = await upsertMacOSLocalEvent({
+                calendarId: forgeCalendar.calendarId,
+                eventId: timebox.remoteEventId,
+                title: timebox.title,
+                startAt: timebox.startsAt,
+                endAt: timebox.endsAt,
+                notes: timebox.overrideReason ?? ""
+            });
+            const localForgeCalendar = listCalendars(connectionId).find((entry) => normalizeUrl(entry.remoteId) === normalizeUrl(forgeCalendar.url));
+            updateTaskTimebox(timebox.id, {
+                connectionId,
+                calendarId: localForgeCalendar?.id ?? null,
+                remoteEventId: event.eventId
+            });
+        }
+        return;
+    }
+    if (state.mode !== "dav") {
         return;
     }
     const forgeCalendar = state.calendars.find((calendar) => normalizeUrl(calendar.url) === normalizeUrl(forgeCalendarUrl));
@@ -1425,6 +1603,55 @@ async function publishTaskTimeboxes(state, forgeCalendarUrl, connectionId) {
 }
 async function syncDiscoveredState(connectionId, credentials) {
     const state = await createProviderClient(credentials);
+    if (state.mode === "macos_local") {
+        const selected = new Set(credentials.selectedCalendarUrls.map((value) => normalizeUrl(value)));
+        const forgeCalendarUrl = normalizeOptionalUrl(credentials.forgeCalendarUrl);
+        for (const calendar of state.calendars) {
+            const normalized = normalizeUrl(calendar.url);
+            upsertCalendarRecord(connectionId, {
+                ...mapCalendarRecord(calendar, {
+                    forgeCalendarUrl,
+                    accountIdentityKey: state.accountIdentityKey
+                }),
+                selectedForSync: selected.has(normalized)
+            });
+            if (!selected.has(normalized) && normalized !== forgeCalendarUrl) {
+                continue;
+            }
+        }
+        const calendarIds = state.calendars
+            .filter((calendar) => {
+            const normalized = normalizeUrl(calendar.url);
+            return (selected.has(normalized) ||
+                normalized === forgeCalendarUrl);
+        })
+            .map((calendar) => calendar.calendarId);
+        if (calendarIds.length > 0) {
+            const now = new Date();
+            const start = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000).toISOString();
+            const end = new Date(now.getTime() + 180 * 24 * 60 * 60 * 1000).toISOString();
+            const { events } = await listMacOSLocalEvents({
+                calendarIds,
+                start,
+                end
+            });
+            const calendarsById = new Map(state.calendars.map((calendar) => [calendar.calendarId, calendar]));
+            for (const event of events) {
+                const calendar = calendarsById.get(event.calendarId);
+                if (!calendar) {
+                    continue;
+                }
+                const ownership = forgeCalendarUrl && normalizeUrl(calendar.url) === forgeCalendarUrl
+                    ? "forge"
+                    : "external";
+                upsertCalendarEventRecord(connectionId, mapMacOSLocalEventToSyncInput(calendar.url, event, ownership));
+            }
+        }
+        return {
+            state,
+            forgeCalendarUrl
+        };
+    }
     if (!isWritableCalendarCredentials(credentials)) {
         if (state.mode !== "microsoft") {
             throw new Error("Forge expected a Microsoft provider state for this calendar connection.");
@@ -1460,17 +1687,19 @@ async function syncDiscoveredState(connectionId, credentials) {
         throw new Error("Forge expected a DAV provider state for this writable calendar connection.");
     }
     const selected = new Set(credentials.selectedCalendarUrls.map((value) => normalizeUrl(value)));
-    const forgeCalendarUrl = normalizeUrl(credentials.forgeCalendarUrl);
+    const forgeCalendarUrl = normalizeOptionalUrl(credentials.forgeCalendarUrl);
     const calendarsToSync = state.calendars.filter((calendar) => {
         const normalized = normalizeUrl(calendar.url);
         if (selected.has(normalized)) {
             return true;
         }
-        if (credentials.provider === "google" && normalized === forgeCalendarUrl) {
+        if (credentials.provider === "google" &&
+            forgeCalendarUrl &&
+            normalized === forgeCalendarUrl) {
             logForgeDebug(`[forge-calendar-sync] skip_forge_readback connectionId=${JSON.stringify(connectionId)} provider=${JSON.stringify(credentials.provider)} calendarUrl=${JSON.stringify(normalized)}`);
             return false;
         }
-        return normalized === forgeCalendarUrl;
+        return forgeCalendarUrl ? normalized === forgeCalendarUrl : false;
     });
     for (const calendar of state.calendars) {
         const normalized = normalizeUrl(calendar.url);
@@ -1483,7 +1712,9 @@ async function syncDiscoveredState(connectionId, credentials) {
     const start = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000).toISOString();
     const end = new Date(now.getTime() + 180 * 24 * 60 * 60 * 1000).toISOString();
     for (const calendar of calendarsToSync) {
-        const ownership = normalizeUrl(calendar.url) === forgeCalendarUrl ? "forge" : "external";
+        const ownership = forgeCalendarUrl && normalizeUrl(calendar.url) === forgeCalendarUrl
+            ? "forge"
+            : "external";
         const calendarUrl = normalizeUrl(calendar.url);
         logForgeDebug(`[forge-calendar-sync] fetch_calendar_objects_start connectionId=${JSON.stringify(connectionId)} provider=${JSON.stringify(credentials.provider)} calendarUrl=${JSON.stringify(calendarUrl)} ownership=${JSON.stringify(ownership)}`);
         if (credentials.provider === "google") {
@@ -1529,7 +1760,7 @@ function toStoredCredentials(input, forgeCalendarUrl) {
             username: input.username,
             password: input.password,
             selectedCalendarUrls: input.selectedCalendarUrls.map(normalizeUrl),
-            forgeCalendarUrl: normalizeUrl(forgeCalendarUrl)
+            forgeCalendarUrl: normalizeOptionalUrl(forgeCalendarUrl)
         };
     }
     return {
@@ -1538,7 +1769,7 @@ function toStoredCredentials(input, forgeCalendarUrl) {
         username: input.username,
         password: input.password,
         selectedCalendarUrls: input.selectedCalendarUrls.map(normalizeUrl),
-        forgeCalendarUrl: normalizeUrl(forgeCalendarUrl)
+        forgeCalendarUrl: normalizeOptionalUrl(forgeCalendarUrl)
     };
 }
 function credentialsMatch(existing, incoming) {
@@ -1569,6 +1800,73 @@ function findExistingCalendarConnection(incoming, secrets) {
         }
     });
 }
+function readConnectionAccountIdentityKey(connection, secrets) {
+    const configuredKey = typeof connection.config.accountIdentityKey === "string"
+        ? connection.config.accountIdentityKey.trim()
+        : "";
+    if (configuredKey) {
+        return normalizeAccountIdentity(configuredKey);
+    }
+    try {
+        const existing = requireSecretRecord(secrets, connection.credentialsSecretId);
+        if (existing.provider === "macos_local") {
+            return normalizeAccountIdentity(existing.accountIdentityKey);
+        }
+        if ("username" in existing && typeof existing.username === "string") {
+            return normalizeAccountIdentity(existing.username);
+        }
+    }
+    catch {
+        // Fall back to account label below.
+    }
+    return normalizeAccountIdentity(connection.accountLabel);
+}
+function findOverlappingConnectionsForAccount(accountIdentityKey, secrets) {
+    const target = normalizeAccountIdentity(accountIdentityKey);
+    return listCalendarConnections().filter((connection) => {
+        if (typeof connection.config.replacedByConnectionId === "string" &&
+            connection.config.replacedByConnectionId.trim().length > 0) {
+            return false;
+        }
+        return readConnectionAccountIdentityKey(connection, secrets) === target;
+    });
+}
+function findExistingForgeWriteTarget(options) {
+    const excluded = new Set(options?.excludeConnectionIds ?? []);
+    return listCalendarConnections().find((connection) => {
+        if (excluded.has(connection.id)) {
+            return false;
+        }
+        if (typeof connection.config.replacedByConnectionId === "string" &&
+            connection.config.replacedByConnectionId.trim().length > 0) {
+            return false;
+        }
+        return normalizeOptionalUrl(typeof connection.config.forgeCalendarUrl === "string"
+            ? connection.config.forgeCalendarUrl
+            : null) !== null;
+    });
+}
+function supersedeCalendarConnections(connectionIds, replacingConnectionId) {
+    for (const connectionId of connectionIds) {
+        const connection = getCalendarConnectionById(connectionId);
+        if (!connection) {
+            continue;
+        }
+        updateCalendarConnectionRecord(connectionId, {
+            status: "needs_attention",
+            config: {
+                ...connection.config,
+                replacedByConnectionId: replacingConnectionId,
+                replacementTransport: "macos_local"
+            }
+        });
+    }
+}
+function requireActiveConnection(connectionId) {
+    if (isSupersededCalendarConnection(connectionId)) {
+        throw new Error("This calendar connection has been replaced by a newer canonical connection and can no longer be synced directly.");
+    }
+}
 function toDiscoveryCredentials(input) {
     if (input.provider === "microsoft" || input.provider === "google") {
         throw new Error(`${input.provider === "google" ? "Google Calendar" : "Exchange Online"} discovery now uses the guided OAuth sign-in flow.`);
@@ -1592,7 +1890,72 @@ export async function discoverCalendarConnection(input) {
     const state = await createProviderClient(toDiscoveryCredentials(input));
     return mapDiscoveryPayload(input.provider, state);
 }
+export async function getMacOSLocalCalendarAccessStatus() {
+    return getMacOSCalendarAuthStatus();
+}
+export async function requestMacOSLocalCalendarAccess() {
+    const result = await requestMacOSCalendarAccess();
+    if (result.granted) {
+        return result;
+    }
+    if (result.status === "not_determined") {
+        const settings = await openMacOSCalendarPrivacySettings();
+        return {
+            ...result,
+            promptSuppressed: true,
+            openedSystemSettings: settings.opened,
+            message: settings.opened
+                ? "macOS did not present the Calendar permission prompt from the Forge background service. Forge opened System Settings > Privacy & Security > Calendars so you can allow access there, then return here and click Check access."
+                : "macOS did not present the Calendar permission prompt from the Forge background service. Open System Settings > Privacy & Security > Calendars, allow Forge, then return here and click Check access."
+        };
+    }
+    if (result.status === "denied" || result.status === "restricted") {
+        return {
+            ...result,
+            message: "Calendar access is blocked for Forge. Open System Settings > Privacy & Security > Calendars, allow Forge, then return here and click Check access."
+        };
+    }
+    return result;
+}
+export async function discoverMacOSLocalCalendarSources() {
+    const discovery = await discoverMacOSLocalCalendars();
+    return {
+        status: discovery.status,
+        requestedAt: discovery.requestedAt,
+        sources: discovery.sources.map((source) => ({
+            sourceId: source.sourceId,
+            sourceTitle: source.sourceTitle,
+            sourceType: source.sourceType,
+            accountLabel: source.accountLabel,
+            accountIdentityKey: accountIdentityKeyForMacOSSource({
+                sourceTitle: source.sourceTitle,
+                sourceType: source.sourceType
+            }),
+            calendars: source.calendars.map((calendar) => ({
+                url: buildMacOSLocalCalendarUrl(source.sourceId, calendar.calendarId),
+                displayName: calendar.title,
+                description: calendar.description,
+                color: calendar.color,
+                timezone: normalizeTimezone(calendar.timezone),
+                isPrimary: calendar.isPrimary,
+                canWrite: calendar.canWrite,
+                selectedByDefault: !isForgeName(calendar.title),
+                isForgeCandidate: isForgeName(calendar.title),
+                sourceId: source.sourceId,
+                sourceTitle: source.sourceTitle,
+                sourceType: source.sourceType,
+                calendarType: calendar.calendarType,
+                hostCalendarId: calendar.calendarId,
+                canonicalKey: `${accountIdentityKeyForMacOSSource({
+                    sourceTitle: source.sourceTitle,
+                    sourceType: source.sourceType
+                })}:${normalizeCalendarKey(calendar.title)}`
+            }))
+        }))
+    };
+}
 export async function discoverExistingCalendarConnection(connectionId, secrets) {
+    requireActiveConnection(connectionId);
     const connection = getCalendarConnectionById(connectionId);
     if (!connection) {
         throw new Error(`Unknown calendar connection ${connectionId}`);
@@ -1602,6 +1965,103 @@ export async function discoverExistingCalendarConnection(connectionId, secrets)
     return mapDiscoveryPayload(connection.provider, state);
 }
 export async function createCalendarConnection(input, secrets, activity = { source: "ui" }) {
+    const cleanupFailedConnectionCreation = (connectionId, secretId) => {
+        try {
+            deleteCalendarConnectionRecord(connectionId);
+        }
+        catch {
+            // Best-effort cleanup for partially-created connections.
+        }
+        try {
+            deleteEncryptedSecret(secretId);
+        }
+        catch {
+            // Best-effort cleanup for partially-created credentials.
+        }
+    };
+    if (input.provider === "macos_local") {
+        const discovery = await discoverMacOSLocalCalendars();
+        if (discovery.status !== "full_access") {
+            throw new Error("Forge needs Calendar full access before it can connect the calendars already configured on this Mac.");
+        }
+        const source = discovery.sources.find((entry) => entry.sourceId === input.sourceId);
+        if (!source) {
+            throw new Error("Forge could not find that macOS calendar source anymore. Discover again and retry.");
+        }
+        const accountIdentityKey = accountIdentityKeyForMacOSSource({
+            sourceTitle: source.sourceTitle,
+            sourceType: source.sourceType
+        });
+        const overlaps = findOverlappingConnectionsForAccount(accountIdentityKey, secrets);
+        const replaceIds = new Set(input.replaceConnectionIds ?? []);
+        const unresolvedOverlaps = overlaps.filter((connection) => !replaceIds.has(connection.id));
+        if (unresolvedOverlaps.length > 0) {
+            throw new CalendarConnectionOverlapError(`Forge already syncs ${source.accountLabel || source.sourceTitle} through another calendar connection. Replace the older connection instead of keeping two copies of the same calendar account.`, unresolvedOverlaps.map((connection) => connection.id));
+        }
+        const discoveredCalendars = source.calendars.map((calendar) => ({
+            ...calendar,
+            url: buildMacOSLocalCalendarUrl(source.sourceId, calendar.calendarId)
+        }));
+        const sharedWriteTarget = findExistingForgeWriteTarget({
+            excludeConnectionIds: Array.from(replaceIds)
+        });
+        let forgeCalendarUrl = input.forgeCalendarUrl?.trim() ||
+            (!sharedWriteTarget
+                ? discoveredCalendars.find((calendar) => isForgeName(calendar.title))?.url
+                : null) ||
+            null;
+        if (!forgeCalendarUrl && input.createForgeCalendar && !sharedWriteTarget) {
+            const created = await ensureMacOSLocalForgeCalendar(source.sourceId);
+            forgeCalendarUrl = buildMacOSLocalCalendarUrl(created.calendar.sourceId, created.calendar.calendarId);
+        }
+        if (!forgeCalendarUrl && !sharedWriteTarget) {
+            throw new Error("Select the calendar Forge should write into, ask Forge to create one, or keep using the existing shared Forge write target.");
+        }
+        const secretId = `calendar_secret_${randomUUID().replaceAll("-", "").slice(0, 10)}`;
+        const storedCredentials = {
+            provider: "macos_local",
+            sourceId: source.sourceId,
+            sourceTitle: source.sourceTitle,
+            sourceType: source.sourceType,
+            accountIdentityKey,
+            selectedCalendarUrls: input.selectedCalendarUrls.map(normalizeUrl),
+            forgeCalendarUrl: normalizeOptionalUrl(forgeCalendarUrl)
+        };
+        storeEncryptedSecret(secretId, secrets.sealJson(storedCredentials), `${input.label} macOS local calendar credentials`);
+        const connection = createCalendarConnectionRecord({
+            provider: "macos_local",
+            label: input.label,
+            accountLabel: source.accountLabel,
+            config: {
+                serverUrl: "forge-macos-local://eventkit/",
+                transportKind: "macos_local",
+                sourceId: source.sourceId,
+                sourceType: source.sourceType,
+                accountIdentityKey,
+                selectedCalendarCount: storedCredentials.selectedCalendarUrls.length,
+                forgeCalendarUrl: storedCredentials.forgeCalendarUrl
+            },
+            credentialsSecretId: secretId
+        });
+        try {
+            await syncCalendarConnection(connection.id, secrets, activity);
+        }
+        catch (error) {
+            cleanupFailedConnectionCreation(connection.id, secretId);
+            throw error;
+        }
+        if (replaceIds.size > 0) {
+            for (const replacedConnectionId of replaceIds) {
+                rehomeCalendarConnectionReferences({
+                    fromConnectionId: replacedConnectionId,
+                    toConnectionId: connection.id
+                });
+            }
+            supersedeCalendarConnections(Array.from(replaceIds), connection.id);
+        }
+        recordCalendarActivity("calendar_connection_created", "calendar_connection", connection.id, `Calendar connection created: ${connection.label}`, "Forge is now mirroring the calendars already configured on this Mac through EventKit.", activity, { provider: input.provider });
+        return getCalendarConnectionById(connection.id);
+    }
     if (input.provider === "google") {
         pruneGoogleOauthSessions();
         const session = googleOauthSessions.get(input.authSessionId);
@@ -1626,21 +2086,24 @@ export async function createCalendarConnection(input, secrets, activity = { sour
         if (state.mode !== "dav") {
             throw new Error("Forge expected a writable DAV provider state for this Google Calendar connection.");
         }
+        const sharedWriteTarget = findExistingForgeWriteTarget();
         let forgeCalendarUrl = input.forgeCalendarUrl?.trim() ||
-            session.discovery.calendars.find((calendar) => calendar.isForgeCandidate)?.url ||
+            (!sharedWriteTarget
+                ? session.discovery.calendars.find((calendar) => calendar.isForgeCandidate)?.url
+                : null) ||
             null;
-        if (!forgeCalendarUrl && input.createForgeCalendar) {
+        if (!forgeCalendarUrl && input.createForgeCalendar && !sharedWriteTarget) {
             const created = await ensureForgeCalendar(state);
             forgeCalendarUrl = created.forgeCalendarUrl;
         }
-        if (!forgeCalendarUrl) {
-            throw new Error("Select the calendar Forge should write into, or create a new calendar named Forge.");
+        if (!forgeCalendarUrl && !sharedWriteTarget) {
+            throw new Error("Select the calendar Forge should write into, ask Forge to create one, or keep using the existing shared Forge write target.");
         }
         const secretId = `calendar_secret_${randomUUID().replaceAll("-", "").slice(0, 10)}`;
         const storedCredentials = {
             ...session.credentials,
             selectedCalendarUrls: input.selectedCalendarUrls.map(normalizeUrl),
-            forgeCalendarUrl: normalizeUrl(forgeCalendarUrl)
+            forgeCalendarUrl: normalizeOptionalUrl(forgeCalendarUrl)
         };
         // The app credentials belong to Forge itself. Only user-specific OAuth tokens
         // are stored per calendar connection.
@@ -1652,11 +2115,17 @@ export async function createCalendarConnection(input, secrets, activity = { sour
             config: {
                 serverUrl: session.discovery.serverUrl,
                 selectedCalendarCount: storedCredentials.selectedCalendarUrls.length,
-                forgeCalendarUrl: normalizeUrl(storedCredentials.forgeCalendarUrl)
+                forgeCalendarUrl: normalizeOptionalUrl(storedCredentials.forgeCalendarUrl)
             },
             credentialsSecretId: secretId
         });
-        await syncCalendarConnection(connection.id, secrets, activity);
+        try {
+            await syncCalendarConnection(connection.id, secrets, activity);
+        }
+        catch (error) {
+            cleanupFailedConnectionCreation(connection.id, secretId);
+            throw error;
+        }
         session.status = "consumed";
         recordCalendarActivity("calendar_connection_created", "calendar_connection", connection.id, `Calendar connection created: ${connection.label}`, "Google Calendar is now connected to Forge through the Authorization Code + PKCE flow.", activity, { provider: input.provider });
         return getCalendarConnectionById(connection.id);
@@ -1699,7 +2168,13 @@ export async function createCalendarConnection(input, secrets, activity = { sour
             },
             credentialsSecretId: secretId
         });
-        await syncCalendarConnection(connection.id, secrets, activity);
+        try {
+            await syncCalendarConnection(connection.id, secrets, activity);
+        }
+        catch (error) {
+            cleanupFailedConnectionCreation(connection.id, secretId);
+            throw error;
+        }
         session.status = "consumed";
         recordCalendarActivity("calendar_connection_created", "calendar_connection", connection.id, `Calendar connection created: ${connection.label}`, "Exchange Online is now connected to Forge through Microsoft sign-in in read-only mode.", activity, { provider: input.provider });
         return getCalendarConnectionById(connection.id);
@@ -1714,17 +2189,20 @@ export async function createCalendarConnection(input, secrets, activity = { sour
         throw new Error("Forge expected a writable DAV provider state for this calendar connection.");
     }
     const discovery = mapDiscoveryPayload(input.provider, state);
+    const sharedWriteTarget = findExistingForgeWriteTarget();
     let forgeCalendarUrl = null;
     forgeCalendarUrl =
         input.forgeCalendarUrl?.trim() ||
-            discovery.calendars.find((calendar) => calendar.isForgeCandidate)?.url ||
+            (!sharedWriteTarget
+                ? discovery.calendars.find((calendar) => calendar.isForgeCandidate)?.url
+                : null) ||
             null;
-    if (!forgeCalendarUrl && input.createForgeCalendar) {
+    if (!forgeCalendarUrl && input.createForgeCalendar && !sharedWriteTarget) {
         const created = await ensureForgeCalendar(state);
         forgeCalendarUrl = created.forgeCalendarUrl;
     }
-    if (!forgeCalendarUrl) {
-        throw new Error("Select the calendar Forge should write into, or create a new calendar named Forge.");
+    if (!forgeCalendarUrl && !sharedWriteTarget) {
+        throw new Error("Select the calendar Forge should write into, ask Forge to create one, or keep using the existing shared Forge write target.");
     }
     const secretId = `calendar_secret_${randomUUID().replaceAll("-", "").slice(0, 10)}`;
     const storedCredentials = toStoredCredentials(input, forgeCalendarUrl);
@@ -1736,11 +2214,17 @@ export async function createCalendarConnection(input, secrets, activity = { sour
         config: {
             serverUrl: discovery.serverUrl,
             selectedCalendarCount: storedCredentials.selectedCalendarUrls.length,
-            forgeCalendarUrl: normalizeUrl(storedCredentials.forgeCalendarUrl)
+            forgeCalendarUrl: normalizeOptionalUrl(storedCredentials.forgeCalendarUrl)
         },
         credentialsSecretId: secretId
     });
-    await syncCalendarConnection(connection.id, secrets, activity);
+    try {
+        await syncCalendarConnection(connection.id, secrets, activity);
+    }
+    catch (error) {
+        cleanupFailedConnectionCreation(connection.id, secretId);
+        throw error;
+    }
     recordCalendarActivity("calendar_connection_created", "calendar_connection", connection.id, `Calendar connection created: ${connection.label}`, `${input.provider === "apple" ? "Apple Calendar" : "Custom CalDAV"} is now connected to Forge.`, activity, { provider: input.provider });
     return getCalendarConnectionById(connection.id);
 }
@@ -1757,6 +2241,7 @@ export async function removeCalendarConnection(connectionId, secrets, activity =
     return connection;
 }
 export async function syncCalendarConnection(connectionId, secrets, activity = { source: "system" }) {
+    requireActiveConnection(connectionId);
     const connection = getCalendarConnectionById(connectionId);
     if (!connection) {
         throw new Error(`Unknown calendar connection ${connectionId}`);
@@ -1775,7 +2260,9 @@ export async function syncCalendarConnection(connectionId, secrets, activity = {
             forgeCalendarId: forgeCalendar?.id ?? null,
             status: "connected",
             config: {
-                serverUrl: credentials.serverUrl,
+                serverUrl: credentials.provider === "macos_local"
+                    ? "forge-macos-local://eventkit/"
+                    : credentials.serverUrl,
                 selectedCalendarCount: credentials.selectedCalendarUrls.length,
                 ...(credentials.provider === "microsoft"
                     ? {
@@ -1783,9 +2270,17 @@ export async function syncCalendarConnection(connectionId, secrets, activity = {
                         tenantId: credentials.tenantId,
                         writeMode: "read_only"
                     }
-                    : {
-                        forgeCalendarUrl: normalizeUrl(credentials.forgeCalendarUrl)
-                    })
+                    : credentials.provider === "macos_local"
+                        ? {
+                            transportKind: "macos_local",
+                            sourceId: credentials.sourceId,
+                            sourceType: credentials.sourceType,
+                            accountIdentityKey: credentials.accountIdentityKey,
+                            forgeCalendarUrl: normalizeOptionalUrl(credentials.forgeCalendarUrl)
+                        }
+                        : {
+                            forgeCalendarUrl: normalizeOptionalUrl(credentials.forgeCalendarUrl)
+                        })
             },
             lastSyncedAt: new Date().toISOString(),
             lastSyncError: null
@@ -1793,7 +2288,9 @@ export async function syncCalendarConnection(connectionId, secrets, activity = {
         await publishTaskTimeboxes(state, forgeCalendarUrl, connectionId);
         recordCalendarActivity("calendar_connection_synced", "calendar_connection", connectionId, `Calendar synced: ${connection.label}`, credentials.provider === "microsoft"
             ? "Exchange Online calendars were mirrored into Forge in read-only mode."
-            : "Provider events and Forge timeboxes were synchronized.", activity);
+            : forgeCalendarUrl
+                ? "Provider events and Forge timeboxes were synchronized."
+                : "Provider events were synchronized. Forge keeps publishing work blocks and timeboxes through the existing shared write target.", activity);
         return getCalendarConnectionById(connectionId);
     }
     catch (error) {
@@ -1805,6 +2302,7 @@ export async function syncCalendarConnection(connectionId, secrets, activity = {
     }
 }
 export async function updateCalendarConnectionSelection(connectionId, input, secrets, activity = { source: "ui" }) {
+    requireActiveConnection(connectionId);
     const connection = getCalendarConnectionById(connectionId);
     if (!connection) {
         throw new Error(`Unknown calendar connection ${connectionId}`);
@@ -1875,6 +2373,42 @@ export async function syncForgeCalendarEvent(eventId, secrets) {
                 continue;
             }
             const { connection, state } = await resolveProviderStateForConnection(source.connectionId, secrets);
+            if (state.mode === "macos_local") {
+                const localCalendar = getCalendarById(source.calendarId);
+                if (!localCalendar || localCalendar.canWrite === false) {
+                    continue;
+                }
+                const hostCalendarId = localCalendar.hostCalendarId ??
+                    parseMacOSLocalCalendarUrl(localCalendar.remoteId).calendarId;
+                const { event: remoteEvent } = await upsertMacOSLocalEvent({
+                    calendarId: hostCalendarId,
+                    eventId: source.remoteEventId,
+                    title: event.title,
+                    startAt: event.start_at,
+                    endAt: event.end_at,
+                    notes: event.description,
+                    location: event.location,
+                    allDay: Boolean(event.is_all_day)
+                });
+                registerCalendarEventSourceProjection({
+                    forgeEventId: eventId,
+                    provider: connection.provider,
+                    connectionId: connection.id,
+                    calendarId: source.calendarId,
+                    remoteCalendarId: getCalendarById(source.calendarId)?.remoteId ?? null,
+                    remoteEventId: remoteEvent.eventId,
+                    remoteUid: remoteEvent.externalId,
+                    recurrenceInstanceId: remoteEvent.occurrenceDate,
+                    isMasterRecurring: false,
+                    syncState: "synced",
+                    rawPayloadJson: JSON.stringify({
+                        externalId: remoteEvent.externalId,
+                        occurrenceDate: remoteEvent.occurrenceDate
+                    }),
+                    lastSyncedAt: new Date().toISOString()
+                });
+                continue;
+            }
             if (state.mode !== "dav") {
                 continue;
             }
@@ -1921,6 +2455,40 @@ export async function syncForgeCalendarEvent(eventId, secrets) {
         return;
     }
     const { connection, state } = await resolveProviderStateForConnection(event.preferred_connection_id, secrets);
+    if (state.mode === "macos_local") {
+        const localCalendar = getCalendarById(event.preferred_calendar_id);
+        if (!localCalendar || localCalendar.canWrite === false) {
+            throw new Error(`Unknown local calendar for event ${eventId}`);
+        }
+        const hostCalendarId = localCalendar.hostCalendarId ??
+            parseMacOSLocalCalendarUrl(localCalendar.remoteId).calendarId;
+        const { event: remoteEvent } = await upsertMacOSLocalEvent({
+            calendarId: hostCalendarId,
+            title: event.title,
+            startAt: event.start_at,
+            endAt: event.end_at,
+            notes: event.description,
+            location: event.location,
+            allDay: Boolean(event.is_all_day)
+        });
+        registerCalendarEventSourceProjection({
+            forgeEventId: eventId,
+            provider: connection.provider,
+            connectionId: connection.id,
+            calendarId: event.preferred_calendar_id,
+            remoteCalendarId: getCalendarById(event.preferred_calendar_id)?.remoteId ?? null,
+            remoteEventId: remoteEvent.eventId,
+            remoteUid: remoteEvent.externalId,
+            recurrenceInstanceId: remoteEvent.occurrenceDate,
+            syncState: "synced",
+            rawPayloadJson: JSON.stringify({
+                externalId: remoteEvent.externalId,
+                occurrenceDate: remoteEvent.occurrenceDate
+            }),
+            lastSyncedAt: new Date().toISOString()
+        });
+        return;
+    }
     if (state.mode !== "dav") {
         throw new Error(`Connection ${connection.id} is read-only, so Forge cannot publish this event there.`);
     }
@@ -1966,6 +2534,10 @@ export async function deleteCalendarEventProjection(eventId, secrets) {
             continue;
         }
         const { connection, state } = await resolveProviderStateForConnection(source.connectionId, secrets);
+        if (state.mode === "macos_local") {
+            await deleteMacOSLocalEvent(source.remoteEventId);
+            continue;
+        }
         if (state.mode !== "dav") {
             continue;
         }
@@ -2010,9 +2582,18 @@ export function listCalendarProviderMetadata() {
             label: "Custom CalDAV",
             supportsDedicatedForgeCalendar: true,
             connectionHelp: "Use a CalDAV base server URL plus account credentials. Forge discovers the calendars available under that account before you pick what to sync."
+        },
+        {
+            provider: "macos_local",
+            label: "Calendars On This Mac",
+            supportsDedicatedForgeCalendar: true,
+            connectionHelp: "Use EventKit to access the calendars already configured in Calendar.app on this Mac. When the same account is already connected remotely, Forge replaces the older connection instead of showing duplicate copies."
         }
     ];
 }
 export function listConnectedCalendarConnections() {
-    return listCalendarConnections().map(({ credentialsSecretId: _secret, ...connection }) => connection);
+    return listCalendarConnections()
+        .filter((connection) => !(typeof connection.config.replacedByConnectionId === "string" &&
+        connection.config.replacedByConnectionId.trim().length > 0))
+        .map(({ credentialsSecretId: _secret, ...connection }) => connection);
 }