Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.1 KB
Raw Blame
export interface TemporalWindow {
  startMs: number | null;
  endMs: number | null;
}

export class TemporalWindowError extends Error {
  constructor(message: string) {
    super(message);
    this.name = 'TemporalWindowError';
  }
}

const DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
const MONTH = /^(\d{4})-(\d{2})$/;

function parseBound(raw: string, end: boolean, label: string): number {
  const value = raw.trim();
  const day = DAY.exec(value);
  if (day) {
    const [, year, month, date] = day;
    const ms = Date.UTC(+year, +month - 1, +date, end ? 23 : 0, end ? 59 : 0, end ? 59 : 0, end ? 999 : 0);
    const parsed = new Date(ms);
    if (parsed.getUTCFullYear() !== +year || parsed.getUTCMonth() !== +month - 1 || parsed.getUTCDate() !== +date) {
      throw new TemporalWindowError(`THINK_INVALID_WINDOW: ${label} is not a real calendar date: "${raw}"`);
    }
    return ms;
  }
  const month = MONTH.exec(value);
  if (month) {
    const [, year, number] = month;
    if (+number < 1 || +number > 12) {
      throw new TemporalWindowError(`THINK_INVALID_WINDOW: ${label} has an invalid month: "${raw}"`);
    }
    return end
      ? Date.UTC(+year, +number, 0, 23, 59, 59, 999)
      : Date.UTC(+year, +number - 1, 1);
  }
  const ms = Date.parse(value);
  if (!Number.isFinite(ms)) {
    throw new TemporalWindowError(`THINK_INVALID_WINDOW: ${label} is not a parseable date: "${raw}"`);
  }
  return ms;
}

export function parseTemporalWindow(since?: string | null, until?: string | null): TemporalWindow | null {
  const lower = since?.trim();
  const upper = until?.trim();
  if (!lower && !upper) return null;
  const startMs = lower ? parseBound(lower, false, 'since') : null;
  const endMs = upper ? parseBound(upper, true, 'until') : null;
  if (startMs !== null && endMs !== null && startMs > endMs) {
    throw new TemporalWindowError(`THINK_INVALID_WINDOW: since (${since}) is after until (${until})`);
  }
  return { startMs, endMs };
}

export interface DatedPage { slug?: string; effective_date?: string | Date | null }

export function resolvePageDateMs(page: DatedPage): number | null {
  const value = page.effective_date;
  if (value instanceof Date) return Number.isFinite(value.getTime()) ? value.getTime() : null;
  if (typeof value === 'string' && value.trim()) {
    const day = DAY.exec(value.trim());
    if (day) {
      const parsed = new Date(12 * 3600_000); // setUTCFullYear, not Date.UTC: Date.UTC maps years 0-99 to 1900-1999
      parsed.setUTCFullYear(+day[1], +day[2] - 1, +day[3]);
      return parsed.getUTCFullYear() === +day[1] && parsed.getUTCMonth() === +day[2] - 1 && parsed.getUTCDate() === +day[3]
        ? parsed.getTime() : null;
    }
    const ms = Date.parse(value);
    if (Number.isFinite(ms)) return ms;
  }
  const match = page.slug?.match(/(\d{4})-(\d{2})-(\d{2})/);
  if (!match) return null;
  const ms = Date.UTC(+match[1], +match[2] - 1, +match[3], 12);
  const parsed = new Date(ms);
  return parsed.getUTCFullYear() === +match[1] && parsed.getUTCMonth() === +match[2] - 1 && parsed.getUTCDate() === +match[3]
    ? ms : null;
}

export function filterPagesToWindow<T extends DatedPage>(pages: T[], window: TemporalWindow) {
  const kept: T[] = [];
  const dropped: T[] = [];
  let undatedKept = 0;
  for (const page of pages) {
    const ms = resolvePageDateMs(page);
    if (ms === null) { undatedKept++; kept.push(page); continue; }
    if ((window.startMs !== null && ms < window.startMs) || (window.endMs !== null && ms > window.endMs)) {
      dropped.push(page);
    } else kept.push(page);
  }
  return { kept, dropped, droppedOutOfWindow: dropped.length, undatedKept };
}

/** A window's trajectory points: those inside it plus each metric's latest reading before it, the value in force when it opens, unless its validity ended by then (GST-731). */
export function trajectoryPointsInWindow<T extends { valid_from: Date; valid_until: Date | null; metric: string | null }>(points: T[], window: TemporalWindow): { kept: T[]; excluded: number } {
  const inForce = new Map<string, T>();
  for (const point of points) {
    if (point.metric === null || window.startMs === null || point.valid_from.getTime() >= window.startMs) continue;
    const prior = inForce.get(point.metric);
    if (!prior || point.valid_from >= prior.valid_from) inForce.set(point.metric, point);
  }
  for (const [metric, point] of inForce) {
    if (point.valid_until !== null && point.valid_until.getTime() <= window.startMs!) inForce.delete(metric);
  }
  const kept = points.filter(point => {
    const ms = point.valid_from.getTime();
    if (window.endMs !== null && ms > window.endMs) return false;
    return window.startMs === null || ms >= window.startMs || inForce.get(point.metric ?? '') === point;
  });
  return { kept, excluded: points.length - kept.length };
}

// PR #5086 (@tarush1989), wave 14 P3.17: a window from exactly one explicit date in the question.
const MONTH_NAMES = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december'];
const MONTH_NAME_YEAR = new RegExp(`\\b(${MONTH_NAMES.join('|')})\\s+(\\d{4})\\b`, 'gi');

/**
 * The one explicit date a question names, as `since`/`until` bounds spanning it: an ISO day (`2026-09-15`), an ISO
 * month (`2026-09`) or an English month name with a four-digit year ("September 2026"). Fail closed to null on
 * anything else: no token, a bare year ("in 2026", "GPT-4"), two or more distinct tokens (a range the caller must
 * spell out), a token `parseTemporalWindow` refuses (`2026-13`, `2026-02-30`), a relative phrase ("next week").
 * Deterministic: no clock, no timezone.
 */
export function parseQuestionWindow(question: string | null | undefined): { since: string; until: string } | null {
  if (typeof question !== 'string' || !question) return null;
  const tokens = new Set<string>();
  for (const m of question.matchAll(/\b(\d{4}-\d{2}-\d{2})\b/g)) tokens.add(m[1]);
  for (const m of question.matchAll(/\b(\d{4}-\d{2})\b(?!-\d)/g)) tokens.add(m[1]);
  for (const m of question.matchAll(MONTH_NAME_YEAR)) tokens.add(`${m[2]}-${String(MONTH_NAMES.indexOf(m[1].toLowerCase()) + 1).padStart(2, '0')}`);
  if (tokens.size !== 1) return null;
  const [token] = tokens;
  try { parseTemporalWindow(token, token); } catch { return null; }
  return { since: token, until: token };
}

export interface ResolvedThinkWindow {
  window: TemporalWindow;
  /** Who bounded the synthesis: the caller's `since`/`until`, or the one explicit date the question named. */
  source: 'caller' | 'question';
  since: string | undefined;
  until: string | undefined;
}

/** `runThink`'s window: a caller bound is authoritative (and still validated); only when both are absent does the question's one explicit date apply. */
export function resolveThinkWindow(question: string, since?: string | null, until?: string | null): ResolvedThinkWindow | null {
  const caller = parseTemporalWindow(since, until);
  if (caller) return { window: caller, source: 'caller', since: since?.trim() || undefined, until: until?.trim() || undefined };
  const derived = parseQuestionWindow(question);
  if (!derived) return null;
  return { window: parseTemporalWindow(derived.since, derived.until)!, source: 'question', ...derived };
}