Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.9 KB
Raw Blame
/**
 * Which calendar events a google source keeps pages for (#5442).
 *
 * The source mirrors one rolling range: from `historyDays` back to
 * `futureDays` ahead (`g_future_days`, default `CALENDAR_HORIZON_DAYS`). Google can only apply that range to a
 * windowed list; a syncToken delta carries no timeMin/timeMax, and with
 * singleEvents=true a single edit to a recurring series brings back every
 * expanded instance of it, years in both directions. So the sweep checks each
 * listed event against the range itself, on every kind of list.
 *
 * `CalendarSyncWindow` is computed once per sweep and answers three questions:
 * - which side of the range an event falls on (`side`), matching Google's own
 *   rule: timeMin is compared with an event's end, timeMax with its start;
 * - what a delta cannot tell us: the range's leading edge moves forward every
 *   day, and an unchanged instance that crosses it never appears in a delta.
 *   `GoogleSourceState.calendar_horizon_ms` records how far ahead the calendar
 *   was last listed, and `coverageStartMs` says where the next catch-up list
 *   must begin;
 * - which existing pages a complete `--full` list should drop
 *   (`staleCalendarPages`): sweep pages whose event starts inside the listed
 *   range but was not listed, and sweep pages whose event starts at or past
 *   the ceiling (a windowed list never names those, so they are only ever
 *   reconciled here). Pages older than the floor (for example after
 *   historyDays shrinks) are never removed by a reconcile.
 *
 * `planCalendarPage` turns one listed event into a page change; google-source
 * performs it with its own write and delete primitives.
 */
import type { CalendarEventData } from './types.ts';

/** How far ahead of now calendar pages are kept, in days, unless `g_future_days` says otherwise. */
export const CALENDAR_HORIZON_DAYS = 60;
/** The largest `g_future_days` a source may ask for. */
export const CALENDAR_FUTURE_DAYS_MAX = 3650;

const DAY_MS = 24 * 60 * 60 * 1000;

export type CalendarWindowSide = 'before' | 'inside' | 'after';

export class CalendarSyncWindow {
  readonly floorMs: number;
  readonly ceilMs: number;

  constructor(readonly nowMs: number, historyDays: number, readonly futureDays: number = CALENDAR_HORIZON_DAYS) {
    this.floorMs = nowMs - historyDays * DAY_MS;
    this.ceilMs = nowMs + futureDays * DAY_MS;
  }

  /** timeMin/timeMax for a windowed list that starts at `fromMs` (the floor unless given). */
  listBounds(fromMs: number = this.floorMs): { timeMinIso: string; timeMaxIso: string } {
    return { timeMinIso: new Date(fromMs).toISOString(), timeMaxIso: new Date(this.ceilMs).toISOString() };
  }

  /**
   * An event is `after` the range when it starts at or past the ceiling and
   * `before` it when it ends at or before the floor (its start stands in for an
   * end that does not parse). A date that does not parse never moves an event
   * out of the range, so a cancelled skeleton with no dates stays `inside`.
   */
  side(startIso: string, endIso: string): CalendarWindowSide {
    const start = Date.parse(startIso);
    if (start >= this.ceilMs) return 'after';
    const end = Date.parse(endIso);
    const finish = Number.isNaN(end) ? start : end;
    return finish <= this.floorMs ? 'before' : 'inside';
  }

  /**
   * Where the catch-up list for unchanged instances should start, or null when
   * none is due. A sweep that listed the whole window already saw them. State
   * with no recorded horizon (saved before it existed) is listed from now, as
   * its last full list is of unknown age; a recorded horizon is listed from
   * once the ceiling has moved at least a day past it.
   */
  coverageStartMs(horizonMs: number | null | undefined, listedWholeWindow: boolean): number | null {
    if (listedWholeWindow) return null;
    if (typeof horizonMs !== 'number') return this.nowMs;
    return this.ceilMs - horizonMs >= DAY_MS ? horizonMs : null;
  }

  /** Whether an event starting at `startIso` begins inside [floor, ceiling). */
  startsInside(startIso: string | null): boolean {
    const start = Date.parse(startIso ?? '');
    return start >= this.floorMs && start < this.ceilMs;
  }

  /** Whether an event starting at `startIso` begins at or past the ceiling (an unparseable start never does). */
  startsAfter(startIso: string | null): boolean {
    return Date.parse(startIso ?? '') >= this.ceilMs;
  }
}

/** The page change one listed event calls for. */
export type CalendarPageChange =
  | { kind: 'write'; removeFirst: string | null }
  | { kind: 'remove'; relPath: string }
  | { kind: 'ignore' };

/**
 * Decide the page change for one listed event.
 *
 * `targetPath` is where the event renders, or null for a cancellation.
 * `currentPath` is the page already holding this event id, if any. Ids are
 * stable while paths derive from the date and title. A cancellation removes
 * the event's page wherever the event sits in time. An event that ended
 * before the floor is ignored, so history imported while it was in range is
 * kept as it is. One that now starts past the ceiling loses its page; the
 * catch-up list brings it back once it is in range. Anything else is
 * written, after removing a copy at an older path.
 */
export function planCalendarPage(side: CalendarWindowSide, targetPath: string | null, currentPath: string | null,
  fallbackPath: string): CalendarPageChange {
  if (targetPath === null) return { kind: 'remove', relPath: currentPath ?? fallbackPath };
  if (side === 'before') return { kind: 'ignore' };
  if (side === 'after') return currentPath ? { kind: 'remove', relPath: currentPath } : { kind: 'ignore' };
  return { kind: 'write', removeFirst: currentPath !== null && currentPath !== targetPath ? currentPath : null };
}

/**
 * Pages written by the sweep (they carry an event id) whose event starts
 * inside `window` but which a complete `--full` list of that window did not
 * name: deleted or cancelled upstream since the last list.
 */
export function unlistedCalendarPages<T extends { event_id: string | null; start_iso: string | null }>(pages: T[],
  listedIds: ReadonlySet<string>, window: CalendarSyncWindow): T[] {
  return pages.filter(page => page.event_id !== null && !listedIds.has(page.event_id) && window.startsInside(page.start_iso));
}

/**
 * Every sweep page a complete `--full` list should remove: the unlisted
 * in-window pages above, plus sweep pages whose event starts at or past the
 * ceiling (#5442). A windowed list cannot name an event past its timeMax, so
 * pages written beyond the horizon (before the window existed, or under a
 * wider `g_future_days`) are reconciled here and nowhere else. Pages without
 * an event id (hand-written) are never touched.
 */
export function staleCalendarPages<T extends { event_id: string | null; start_iso: string | null }>(pages: T[],
  listedIds: ReadonlySet<string>, window: CalendarSyncWindow): T[] {
  return pages.filter(page => page.event_id !== null
    && (window.startsAfter(page.start_iso) || (!listedIds.has(page.event_id) && window.startsInside(page.start_iso))));
}