Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.5 KB
Raw Blame
/**
 * Temporal typed edges: the relationship note shared by every surface that
 * shows a page summary (entity cards, context_pack, ambient turn context,
 * compiled context). One batched read of relationship state per call.
 *
 * "now: works_at widget-co (since 2025-03-01); ended: works_at acme-example
 * (2025-03-01)"; "(by 2025-03-01)" when only the nightly check's inferred closure dates the end, an upper
 * bound. Ended relationships the summary still names always appear
 * (with a stale-summary warning); other ended ones are capped at the latest
 * three. Only state relations (works_at, advises, …) take part, and a page
 * with no ended relationship gets no note.
 */

import {
  annotateTemporalRow, temporalLinkJoinSql, TEMPORAL_LINK_SELECT_SQL, type RelationshipStatus,
} from './link-validity.ts';
import { privatePagesFilterForCaller, privateLinkOriginFilterForCaller } from './search/private-visibility.ts';

const NOTE_ENDED_CAP = 3;

type RawExec = { executeRaw<R = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<R[]> };

export interface NoteSubject { slug: string; source_id: string; summary?: string | null }

interface NoteEdge { type: string; slug: string; title: string; status: RelationshipStatus | 'reference'; since: string | null; until: string | null; untilUpperBound: boolean }

export const relationshipNoteKey = (sourceId: string, slug: string): string => `${sourceId}\u0000${slug}`;

function renderNote(summary: string, edges: NoteEdge[]): string | undefined {
  const live = edges.filter(e => e.status === 'live' || e.status === 'disputed');
  const ended = edges.filter(e => e.status === 'ended' || e.status === 'ended_unknown_date');
  if (ended.length === 0) return undefined;
  const lower = summary.toLowerCase();
  const named = (e: NoteEdge) => {
    const title = e.title.trim().toLowerCase();
    return (title.length >= 3 && lower.includes(title)) || lower.includes(e.slug.split('/').pop()!.replace(/-/g, ' '));
  };
  const short = (e: NoteEdge) => e.slug.split('/').pop()!;
  const stale = ended.filter(named);
  const others = ended.filter(e => !named(e)).sort((a, b) => (b.until ?? '').localeCompare(a.until ?? '')).slice(0, NOTE_ENDED_CAP);
  const parts = [
    ...(live.length ? [`now: ${live.map(e => `${e.type} ${short(e)}${e.since ? ` (since ${e.since})` : ''}`).join(', ')}`] : []),
    `ended: ${[...stale, ...others].map(e => `${e.type} ${short(e)} (${e.until ? `${e.untilUpperBound ? 'by ' : ''}${e.until}` : 'date unknown'})`).join(', ')}`,
  ];
  if (stale.length) parts.push(`summary may be stale: it still names ${stale.map(short).join(', ')}`);
  return parts.join('; ');
}

/**
 * Notes keyed by `relationshipNoteKey(source_id, slug)`; subjects without an
 * ended relationship are absent. `excludePrivate` reads the world-scope state
 * and hides private targets and private-origin links, like remote graph reads.
 */
export async function loadRelationshipNotes(
  engine: RawExec,
  subjects: readonly NoteSubject[],
  opts: { excludePrivate: boolean },
): Promise<Map<string, string>> {
  const notes = new Map<string, string>();
  if (subjects.length === 0) return notes;
  const privacy = opts.excludePrivate ? ` AND ${privatePagesFilterForCaller('t')} AND ${privateLinkOriginFilterForCaller('l')}` : '';
  // The evidence the relationship projection counts for this scope (link-relationships.ts): an origin that is gone or in
  // another source never counts, and a private origin does not count toward the world scope.
  const endBy = (producer: string) => `EXISTS (SELECT 1 FROM link_transitions x LEFT JOIN pages xo ON xo.id = x.origin_page_id
        WHERE x.from_page_id = l.from_page_id AND x.to_page_id = l.to_page_id AND x.link_type = l.link_type AND x.kind = 'end'
        AND x.occurred_on = lr_t.last_end AND x.producer ${producer}
        AND (x.origin_page_id IS NULL OR xo.deleted_at IS NULL AND xo.source_id = f.source_id${opts.excludePrivate ? ` AND ${privatePagesFilterForCaller('xo')}` : ''}))`;
  const rows = await engine.executeRaw<{ from_slug: string; source_id: string; to_slug: string; to_title: string | null; link_type: string; last_end: string | null; end_upper_bound: boolean | null }>(
    `SELECT f.slug AS from_slug, f.source_id, t.slug AS to_slug, t.title AS to_title, l.link_type, lr_t.last_end::text AS last_end,
        (${endBy("= 'dream'")} AND NOT ${endBy("<> 'dream'")}) AS end_upper_bound${TEMPORAL_LINK_SELECT_SQL}
       FROM links l
       JOIN pages f ON f.id = l.from_page_id
       JOIN pages t ON t.id = l.to_page_id
       ${temporalLinkJoinSql('l', opts.excludePrivate)}
      WHERE (f.source_id, f.slug) IN (SELECT s.source_id, s.slug FROM unnest($1::text[], $2::text[]) AS s(source_id, slug))
        AND lr_t.semantics = 'state' AND t.deleted_at IS NULL${privacy}`,
    [subjects.map(s => s.source_id), subjects.map(s => s.slug)],
  );
  const bySubject = new Map<string, Map<string, NoteEdge>>();
  for (const raw of rows) {
    const r = annotateTemporalRow(raw);
    const key = relationshipNoteKey(r.source_id, r.from_slug);
    const edges = bySubject.get(key) ?? new Map<string, NoteEdge>();
    const last = r.stints?.[r.stints.length - 1];
    edges.set(`${r.link_type}\u0000${r.to_slug}`, {
      type: r.link_type, slug: r.to_slug, title: r.to_title ?? '', status: r.status,
      since: last?.from ?? null, until: last?.until ?? null,
      untilUpperBound: r.end_upper_bound === true && last?.until != null && last.until === String(r.last_end).slice(0, 10),
    });
    bySubject.set(key, edges);
  }
  for (const s of subjects) {
    const key = relationshipNoteKey(s.source_id, s.slug);
    const edges = bySubject.get(key);
    const note = edges ? renderNote(s.summary ?? '', [...edges.values()]) : undefined;
    if (note) notes.set(key, note);
  }
  return notes;
}

/**
 * Ambient turn context: fold each page's note into its synopsis (world scope),
 * so the budget trimmer prices the rendered line. Fail-soft: an error leaves
 * the synopses unchanged.
 */
export async function appendRelationshipNotes(
  engine: RawExec,
  items: Array<{ slug: string; source_id: string; synopsis: string }>,
): Promise<void> {
  if (items.length === 0) return;
  const notes = await loadRelationshipNotes(engine, items.map(i => ({ slug: i.slug, source_id: i.source_id, summary: i.synopsis })), { excludePrivate: true })
    .catch(() => new Map<string, string>());
  for (const item of items) {
    const note = notes.get(relationshipNoteKey(item.source_id, item.slug));
    if (note) item.synopsis = item.synopsis ? `${item.synopsis} [${note}]` : `[${note}]`;
  }
}