Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.0 KB
Raw Blame
/**
 * Dated evidence blocks (C1, `search.evidence_date_header`): the one-line
 * date header evidence delivery puts at the top of every delivered block, and
 * the day formatter it shares with think's page dates.
 *
 * Header grammar (fixed, one line, parsed by agents and eval harnesses):
 *
 *   page block:  [observed 2026-03-05]
 *   fact:        [observed unknown; valid 2026-03-01 to unknown]
 *   fact, asked about one date (GBRA-574 B3, the query facts block):
 *                [observed 2026-06-30; valid 2026-02-15 to unknown; told after 2026-04-01]
 *                [observed unknown; valid 2026-03-01 to unknown; learn date unknown]
 *
 * Each date is YYYY-MM-DD or the literal `unknown`. `observed` is when the
 * source text was written or said (date grounding's observation time,
 * #6020): the page's filename/slug date,
 * frontmatter `date`, `published` or a created key, in effective-date
 * precedence with `event_date` removed. An event date is when something
 * happened, not when the note was written, and row timestamps are when GBrain
 * stored it, so neither is ever shown as observed. A fact's `observed` is the
 * observation date of the page it was taken from (`source_markdown_slug`),
 * read under the caller's page read policy (GBRA-574 A1); `unknown` when that
 * page states no date, is its own entity page, or is one the caller may not
 * read. Its validity window (`valid_from` to `valid_until`, an open end shown
 * as `unknown`) follows. A failed read also renders `unknown`, and the caller
 * marks the response degraded.
 *
 * Seam: `pageObservationDate` mirrors `resolveObservationDate` from
 * src/core/ai/date-grounding.ts (#6020); once that lands, call it here
 * instead. Days render through `formatBrainDay` (effective-date.ts), the
 * same function think's `<page date>` attribute uses, so both surfaces print
 * the same day. The header's `observed` is when the text was written or
 * said, never the event date think shows as content date.
 */
import { computeEffectiveDate, formatBrainDay } from '../effective-date.ts';
import type { PageReadScope } from '../types.ts';
import { pageReadFilter } from './read-policy-sql.ts';

export const EVIDENCE_DATE_HEADER_KEY = 'search.evidence_date_header';
/** GBRA-205: with the date header on, a page block's header line also carries its title (default off). */
export const EVIDENCE_TITLES_KEY = 'search.evidence_titles';
export const UNKNOWN_DATE = 'unknown';

const OBSERVATION_SOURCES = new Set(['filename', 'date', 'published', 'created']);

/** When the page's text was written or said; null when it states no such date. Never a row timestamp. */
export function pageObservationDate(page: {
  slug: string;
  frontmatter?: Record<string, unknown> | null;
  filename?: string | null;
  timeZone?: string | null;
}): Date | null {
  const { event_date: _eventDate, ...frontmatter } = page.frontmatter ?? {};
  const invalid = new Date(Number.NaN);
  const result = computeEffectiveDate({
    slug: page.slug,
    frontmatter,
    filename: page.filename ?? page.slug.split('/').pop() ?? null,
    timeZone: page.timeZone ?? undefined,
    createdAt: invalid,
    updatedAt: invalid,
  });
  return result.date && result.source && OBSERVATION_SOURCES.has(result.source) ? result.date : null;
}

export function pageDateHeader(observed: string | null): string {
  return `[observed ${observed ?? UNKNOWN_DATE}]`;
}

/** A valid_from within this of created_at is the write-time default, not a known start of validity. */
const WRITE_TIME_DEFAULT_MS = 60_000;

/**
 * `observed` is when the fact was said: the observation date of the page it
 * came from, when the caller supplies it. `valid FROM` is the fact's
 * valid_from, except a valid_from that only records the write time (the
 * default when `remember` gets no date) renders `unknown`: the header never
 * presents when a fact was written as when it became true. With `askedDate`
 * (the one day a question names, YYYY-MM-DD), a fact said after it ends
 * `; told after <askedDate>` and one whose saying date is unknown ends
 * `; learn date unknown`, so neither reads as known on that day.
 */
export function factDateHeader(
  fact: { valid_from?: Date | string | null; valid_until?: Date | string | null; created_at?: Date | string | null },
  timeZone?: string | null,
  observed?: string | null,
  askedDate?: string | null,
): string {
  const writeTimeDefault = fact.valid_from && fact.created_at
    && Math.abs(new Date(fact.valid_from).getTime() - new Date(fact.created_at).getTime()) < WRITE_TIME_DEFAULT_MS;
  const from = (writeTimeDefault ? null : formatBrainDay(fact.valid_from, timeZone)) ?? UNKNOWN_DATE;
  const until = formatBrainDay(fact.valid_until, timeZone) ?? UNKNOWN_DATE;
  const told = !askedDate ? '' : !observed ? '; learn date unknown' : observed > askedDate ? `; told after ${askedDate}` : '';
  return `[observed ${observed ?? UNKNOWN_DATE}; valid ${from} to ${until}${told}]`;
}

/**
 * The page header for each page id: one read of the stored frontmatter and
 * import filename (only the derived day leaves this function) plus
 * `brain.timezone`. Ids missing from the result render `unknown`.
 */
export async function loadPageDateHeaders(
  engine: { executeRaw<T>(sql: string, params?: unknown[]): Promise<T[]>; getConfig(key: string): Promise<string | null> },
  pageIds: number[],
): Promise<Map<number, string>> {
  const out = new Map<number, string>();
  const ids = [...new Set(pageIds.filter(id => Number.isInteger(id) && id > 0))];
  if (ids.length === 0) return out;
  const timeZone = (await engine.getConfig('brain.timezone').catch(() => null))?.trim() || null;
  const rows = await engine.executeRaw<{ id: number; slug: string; frontmatter: unknown; import_filename: string | null }>(
    'SELECT id, slug, frontmatter, import_filename FROM pages WHERE id = ANY($1::int[])', [ids]);
  for (const r of rows) {
    const fm = typeof r.frontmatter === 'string' ? JSON.parse(r.frontmatter) : r.frontmatter;
    const observed = pageObservationDate({ slug: String(r.slug), frontmatter: fm && typeof fm === 'object' ? fm as Record<string, unknown> : null, filename: r.import_filename, timeZone });
    out.set(Number(r.id), pageDateHeader(formatBrainDay(observed, timeZone)));
  }
  return out;
}

/**
 * `recall` fact rows plus `date_header` when `search.evidence_date_header` is on; unchanged otherwise. `scope` is
 * the caller's page read policy for the observation dates; a failed read renders `unknown` and calls `onUnavailable`.
 */
export async function withFactDateHeaders<T extends { id: number; valid_from: string | null; valid_until: string | null; created_at?: string | null; entity_slug?: string | null; source_id?: string }>(
  engine: { getConfig(key: string): Promise<string | null>; executeRaw<R>(sql: string, params?: unknown[]): Promise<R[]> },
  facts: T[],
  scope: PageReadScope | undefined,
  onUnavailable: () => void,
): Promise<Array<T & { date_header?: string }>> {
  if (!await evidenceDateHeaderEnabled(engine)) return facts;
  const timeZone = (await engine.getConfig('brain.timezone').catch(() => null))?.trim() || null;
  const observed = await factObservationDates(engine, facts, timeZone, scope).catch(() => { onUnavailable(); return new Map<number, string>(); });
  return facts.map(f => ({ ...f, date_header: factDateHeader(f, timeZone, observed.get(f.id)) }));
}

/**
 * When each fact was said: the observation date of the page the fact came
 * from (`facts.source_markdown_slug`, e.g. the conversation it was extracted
 * from), read under `scope` (the caller's page read policy), so a page the
 * caller may not read dates nothing. A fact stored in its own entity page's
 * facts fence has no such page, so it stays unknown. One pages read per call,
 * plus one facts read for rows that do not carry `source_markdown_slug`.
 * Throws on a database error; the caller marks the response degraded.
 */
export async function factObservationDates(
  engine: { executeRaw<R>(sql: string, params?: unknown[]): Promise<R[]> },
  facts: Array<{ id: number; entity_slug?: string | null; source_id?: string; source_markdown_slug?: string | null }>,
  timeZone: string | null,
  scope: PageReadScope | undefined,
): Promise<Map<number, string>> {
  const out = new Map<number, string>();
  const valid = facts.filter(f => Number.isInteger(f.id) && f.id > 0);
  if (!valid.length) return out;
  const carried = valid.filter(f => f.source_markdown_slug !== undefined && f.source_id !== undefined);
  const missing = valid.filter(f => !carried.includes(f)).map(f => f.id);
  const rows = [
    ...carried.map(f => ({ id: f.id, source_id: f.source_id!, slug: f.source_markdown_slug ?? null, entity_slug: f.entity_slug ?? null })),
    ...(missing.length ? await engine.executeRaw<{ id: number; source_id: string; slug: string | null; entity_slug: string | null }>(
      'SELECT id, source_id, source_markdown_slug AS slug, entity_slug FROM facts WHERE id = ANY($1::bigint[])', [missing]) : []),
  ];
  const wanted = rows.filter(r => r.slug && r.slug !== r.entity_slug);
  if (!wanted.length) return out;
  const params: unknown[] = [wanted.map(r => r.source_id), wanted.map(r => r.slug!)];
  const policy = pageReadFilter('p', scope, params, true);
  const pages = await engine.executeRaw<{ source_id: string; slug: string; frontmatter: unknown; import_filename: string | null }>(
    `SELECT p.source_id, p.slug, p.frontmatter, p.import_filename FROM pages p
     JOIN unnest($1::text[], $2::text[]) AS w(source_id, slug) ON p.source_id = w.source_id AND p.slug = w.slug WHERE ${policy}`, params);
  const byKey = new Map(pages.map(p => {
    const fm = typeof p.frontmatter === 'string' ? JSON.parse(p.frontmatter) : p.frontmatter;
    const day = formatBrainDay(pageObservationDate({ slug: p.slug, frontmatter: fm && typeof fm === 'object' ? fm as Record<string, unknown> : null, filename: p.import_filename, timeZone }), timeZone);
    return [`${p.source_id}\u0000${p.slug}`, day] as const;
  }));
  for (const r of wanted) {
    const day = byKey.get(`${r.source_id}\u0000${r.slug}`);
    if (day) out.set(Number(r.id), day);
  }
  return out;
}

/**
 * A page title as one inert line: bidi overrides, isolates and marks (U+202A-U+202E, U+2066-U+2069, U+200E, U+200F,
 * U+061C) are removed so a title cannot reorder how the header renders; angle brackets and C0/C1 control characters
 * become spaces, double quotes single quotes, whitespace runs one space.
 */
export function evidenceTitle(title: string | null | undefined): string {
  return (title ?? '').replace(/[\u202A-\u202E\u2066-\u2069\u200E\u200F\u061C]/g, '').replace(/[<>\u0000-\u001F\u007F-\u009F]/g, ' ')
    .replace(/"/g, "'").replace(/\s+/g, ' ').trim();
}

/** A page header line with the page's title after the bracket, on one line; an empty title adds nothing. */
export function titledPageHeader(header: string, title: string | null | undefined): string {
  const clean = evidenceTitle(title);
  return clean ? `${header} ${clean}` : header;
}

type HeaderHit = { page_id: number; title?: string | null; chunk_text?: string | null; fact_row?: { valid_from: string; valid_until: string | null; observed?: string } };

/**
 * The date header line (with its newline) for each delivered block, read for
 * every hit page in one query. A failed read renders `unknown` for every page
 * and calls `onUnavailable` once. A facts-arm row gets its fact header unless
 * its text already starts with one. With `titles`, a page block's line ends
 * with its title (`search.evidence_titles`); fact headers never change.
 */
export async function blockDateHeaders(engine: Parameters<typeof loadPageDateHeaders>[0],
  hits: HeaderHit[], onUnavailable: () => void, opts: { titles?: boolean } = {}): Promise<(hit: HeaderHit) => string> {
  let headers: Map<number, string>;
  try { headers = await loadPageDateHeaders(engine, hits.map(h => h.page_id)); } catch { headers = new Map(); onUnavailable(); }
  return hit => {
    if (hit.fact_row) return hit.chunk_text?.startsWith('[observed ') ? '' : `${factDateHeader(hit.fact_row, undefined, hit.fact_row.observed)}\n`;
    const header = headers.get(hit.page_id) ?? pageDateHeader(null);
    return `${opts.titles ? titledPageHeader(header, hit.title) : header}\n`;
  };
}

/** A config flag value is on: 'true' | 'on' | '1' | 'yes', case-insensitive. */
export function configFlagOn(raw: string | null | undefined): boolean {
  const v = raw?.trim().toLowerCase();
  return v === 'true' || v === 'on' || v === '1' || v === 'yes';
}

/** `search.evidence_date_header` is on ('true' | 'on' | '1' | 'yes'); off by default and on any read error. */
export async function evidenceDateHeaderEnabled(engine: { getConfig(key: string): Promise<string | null> }): Promise<boolean> {
  try {
    return configFlagOn(await engine.getConfig(EVIDENCE_DATE_HEADER_KEY));
  } catch {
    return false;
  }
}

/** `search.evidence_titles` is on ('true' | 'on' | '1' | 'yes'); off by default and on any read error. */
export async function evidenceTitlesEnabled(engine: { getConfig(key: string): Promise<string | null> }): Promise<boolean> {
  try {
    return configFlagOn(await engine.getConfig(EVIDENCE_TITLES_KEY));
  } catch {
    return false;
  }
}