Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.2 KB
Raw Blame
/**
 * #7161: names that only appear in page text. Entity resolution reads pages,
 * aliases and the mention index; while mention extraction is behind, a name
 * that only sits in notes, calendar pages or transcripts resolves to nothing,
 * and a thin stub page hides the fresh mention in a recent note. This probe
 * is one bounded keyword read of the exact name as a phrase, under the same
 * read policy as search (source grant, private pages, safe chunks for
 * untrusted callers, quarantined pages left out), verified against the chunk
 * text, so every listed page really contains the name. The result is
 * labelled as unlinked text matches: it says the name appears there, not
 * that those pages are waiting for extraction.
 */

import type { BrainEngine } from '../engine.ts';
import type { SearchResult } from '../types.ts';
import { isQuarantined } from '../quarantine.ts';
import { nameWords } from '../entities/name-variants.ts';

/** Keyword rows read for one name; a full read reports the total as a floor (`capped`). */
export const TEXT_MENTION_POOL = 50;
/** Pages listed, newest first. */
export const TEXT_MENTION_SHOWN = 5;
/** The probe's wall-clock budget; past it the card reports `unread: 'deadline'` instead of waiting. */
export const TEXT_MENTION_DEADLINE_MS = 1500;
const MAX_NAME_WORDS = 5;

export interface TextMentionPage { slug: string; title: string; type: string | null; source_id: string; date: string | null }

export interface TextMentions {
  /** Pages whose text contains the name, newest first. */
  pages: TextMentionPage[];
  /** Distinct pages found; a floor when `capped`. */
  total: number;
  capped: boolean;
  /** The probe could not finish (TEXT_MENTION_DEADLINE_MS) or failed: the name was not checked, which is not "no matches". */
  unread?: 'deadline' | 'read_failed';
}

/** Whether `name` is worth a text probe: one to five words with a letter, not a slug. */
export function textProbeApplies(name: string): boolean {
  const words = nameWords(name);
  return !name.includes('/') && words.length >= 1 && words.length <= MAX_NAME_WORDS && words.some(w => /\p{L}/u.test(w) && w.length >= 2);
}

const containsName = (text: string, words: string[]) => {
  const hay = ` ${nameWords(text).join(' ')} `;
  return hay.includes(` ${words.join(' ')} `);
};

/**
 * Pages in `sources` whose text contains `name` as a phrase (null when
 * the probe does not apply or the read failed). `exclude` drops pages the
 * caller already shows (the card's own page).
 */
export async function readTextMentions(
  engine: BrainEngine,
  sources: readonly string[],
  name: string,
  opts: { remote: boolean; excludePrivate: boolean; omitQuarantined?: boolean; exclude?: readonly string[] },
): Promise<TextMentions | null> {
  if (!textProbeApplies(name) || !sources.length) return null;
  let timer: ReturnType<typeof setTimeout> | undefined;
  const deadline = new Promise<TextMentions>(resolve => {
    timer = setTimeout(() => resolve({ pages: [], total: 0, capped: false, unread: 'deadline' }), TEXT_MENTION_DEADLINE_MS);
  });
  try {
    return await Promise.race([probe(engine, sources, name, opts), deadline]);
  } finally {
    clearTimeout(timer);
  }
}

async function probe(
  engine: BrainEngine,
  sources: readonly string[],
  name: string,
  opts: { remote: boolean; excludePrivate: boolean; omitQuarantined?: boolean; exclude?: readonly string[] },
): Promise<TextMentions> {
  const words = nameWords(name);
  let rows: SearchResult[];
  try {
    rows = await engine.searchKeyword(`"${name.replace(/"/g, ' ').trim()}"`, {
      limit: TEXT_MENTION_POOL,
      ...(sources.length === 1 ? { sourceId: sources[0] } : { sourceIds: [...sources] }),
      excludePrivate: opts.excludePrivate,
      requireSafeChunks: opts.remote,
    });
  } catch {
    return { pages: [], total: 0, capped: false, unread: 'read_failed' };
  }
  const exclude = new Set(opts.exclude ?? []);
  const capped = rows.length >= TEXT_MENTION_POOL;
  const hits = new Map<string, SearchResult>();
  for (const r of rows) {
    const key = `${r.source_id ?? ''}:${r.slug}`;
    if (r.keyword_relaxed || exclude.has(r.slug) || hits.has(key) || !containsName(r.chunk_text ?? '', words)) continue;
    hits.set(key, r);
  }
  if (!hits.size) return { pages: [], total: 0, capped: false };
  const meta = await engine.executeRaw<{ slug: string; source_id: string; title: string | null; type: string | null; frontmatter: Record<string, unknown> | null; date: Date | string | null }>(
    `SELECT slug, source_id, title, type, frontmatter, COALESCE(effective_date, updated_at) AS date
       FROM pages WHERE deleted_at IS NULL AND source_id = ANY($1::text[]) AND slug = ANY($2::text[])`,
    [[...sources], [...new Set([...hits.values()].map(h => h.slug))]]).catch(() => []);
  const pages = meta
    .filter(m => hits.has(`${m.source_id}:${m.slug}`) && !(opts.omitQuarantined && isQuarantined(m.frontmatter)))
    .map(m => ({ slug: m.slug, title: m.title ?? m.slug, type: m.type, source_id: m.source_id,
      date: m.date == null ? null : new Date(m.date as string).toISOString().slice(0, 10) }))
    .sort((a, b) => (b.date ?? '').localeCompare(a.date ?? '') || a.slug.localeCompare(b.slug));
  return { pages: pages.slice(0, TEXT_MENTION_SHOWN), total: pages.length, capped };
}