Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBRA-156: `whois` — exact identity lookup for triage agents ("is this
* sender a known contact?"). Semantic search can rank the wrong person first,
* and `entity` resolves fuzzy name variants on purpose; this op answers only
* on an exact match: a frontmatter `email` / `emails` value, the page title,
* or a declared alias equal to the query, ignoring case, accents (NFKD with
* marks stripped, stroke letters folded), compatibility width forms and
* surrounding whitespace or quotes. An email query compares whole addresses
* case-insensitively, with no accent folding. No nickname, typo, prefix or
* semantic matching, and no search fallback: no match is an empty list.
*
* Candidates come from index-served equality probes
* (engine-sql/exact-identity.ts); every candidate is verified here.
*/
import type { Operation, OperationContext } from './contract.ts';
import { invalidParam } from './op-fix.ts';
import { assertExplicitSourceLive, federatedSearchScope, parseSourceIdParam } from './context.ts';
import { foldNonDecomposingLatin } from '../latin-fold.ts';
import { normalizeAlias, normalizeAliasList } from '../search/alias-normalize.ts';
import { slugify } from '../entities/resolve.ts';
import { slugifySegment } from '../sync.ts';
import { exactIdentityStatement, type ExactIdentityProbes, type ExactIdentityRow } from '../engine-sql/exact-identity.ts';
export const WHOIS_MAX_QUERY_CHARS = 320;
export const WHOIS_MAX_TYPES = 20;
/** Candidate rows verified per call; past it the answer says truncated. */
export const WHOIS_CANDIDATE_CAP = 100;
export type IdentityMatchKind = 'email' | 'title' | 'alias';
const MATCH_RANK: Record<IdentityMatchKind, number> = { email: 0, title: 1, alias: 2 };
const TYPE_NAME = /^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,63}$/;
const EMAIL = /^[^\s@]+@[^\s@]+$/;
const EDGE_QUOTES = /^[\s"'`\u2018\u2019\u201c\u201d\u00ab\u00bb]+|[\s"'`\u2018\u2019\u201c\u201d\u00ab\u00bb]+$/g;
/** NFKC, lowercase, whitespace collapsed, surrounding quotes and brackets dropped. */
function displayKey(raw: string): string {
return normalizeAlias(raw).replace(EDGE_QUOTES, '');
}
/** displayKey with accents stripped (NFKD, combining marks removed) and stroke letters folded. */
export function identityNameKey(raw: string): string {
return foldNonDecomposingLatin(displayKey(raw).normalize('NFKD').replace(/\p{M}/gu, '')).replace(/\s+/g, ' ').trim();
}
/** The whole address, lowercased, or null when the value is not one email address. */
export function identityEmailKey(raw: string): string | null {
const key = displayKey(raw).replace(/^<|>$/g, '');
return EMAIL.test(key) ? key : null;
}
interface IdentityQuery { email: string | null; name: string }
/** A jsonb column as read: drivers hand it back parsed or as JSON text. */
function decoded(value: unknown): unknown {
if (typeof value !== 'string' || !/^[[{"]/.test(value)) return value;
try { return JSON.parse(value) as unknown; } catch { return value; }
}
function strings(value: unknown): string[] {
const v = decoded(value);
return (Array.isArray(v) ? v : [v]).filter((s): s is string => typeof s === 'string');
}
/** The strongest exact match of the query on one candidate page, or null. */
export function identityMatchKind(query: IdentityQuery, row: Pick<ExactIdentityRow, 'title' | 'email' | 'emails' | 'aliases'>): IdentityMatchKind | null {
const same = (v: string) => (query.email ? identityEmailKey(v) === query.email : identityNameKey(v) === query.name);
if (query.email && [...strings(row.email), ...strings(row.emails)].some(same)) return 'email';
if (row.title && same(row.title)) return 'title';
return normalizeAliasList(decoded(row.aliases)).some(same) ? 'alias' : null;
}
function probesFor(raw: string, query: IdentityQuery): ExactIdentityProbes {
const uniq = (values: string[]) => [...new Set(values.filter(Boolean))];
const written = displayKey(raw);
if (query.email) {
const asGiven = raw.normalize('NFKC').replace(EDGE_QUOTES, '').replace(/^<|>$/g, '');
return { titleKeys: [query.email], titleRaw: asGiven, basenames: [], aliasKeys: [query.email], emails: uniq([asGiven, query.email]) };
}
const nfkc = raw.normalize('NFKC').replace(EDGE_QUOTES, '').replace(/\s+/g, ' ');
return {
titleKeys: uniq([written, query.name]),
titleRaw: nfkc,
basenames: uniq([slugify(nfkc), slugifySegment(nfkc)]),
aliasKeys: uniq([written, query.name]),
emails: [],
};
}
function parseParams(ctx: OperationContext, p: Record<string, unknown>) {
const bad = (param: string, message: string, example: unknown) =>
invalidParam(ctx, 'whois', param, 'whois: ' + message, { def: whois.params[param], example });
const raw = typeof p.query === 'string' ? p.query : '';
if (raw.length > WHOIS_MAX_QUERY_CHARS) throw bad('query', 'query must be at most ' + WHOIS_MAX_QUERY_CHARS + ' characters', '[email protected]');
const query: IdentityQuery = { email: identityEmailKey(raw), name: identityNameKey(raw) };
if (!query.name) throw bad('query', 'query must be an email address or a name', '[email protected]');
let types: string[] | undefined;
if (p.types !== undefined) {
const ok = Array.isArray(p.types) && p.types.length >= 1 && p.types.length <= WHOIS_MAX_TYPES && p.types.every(t => typeof t === 'string' && TYPE_NAME.test(t));
if (!ok) throw bad('types', 'types must be a list of 1-' + WHOIS_MAX_TYPES + ' page type names', ['person']);
types = [...new Set(p.types as string[])].sort();
}
return { raw, query, types };
}
const whois: Operation = {
name: 'whois',
mutating: false,
idempotent: true,
outputRedaction: 'retrieval',
scope: 'read',
description: 'Exact identity lookup: entity pages whose email, title or declared alias equals an email address or name, ignoring case, accents and quotes. '
+ 'Never fuzzy: empty matches means no exact match; ambiguous means several.',
params: {
query: { type: 'string', required: true, description: "Email address or name, e.g. '[email protected]'." },
types: { type: 'array', minItems: 1, items: { type: 'string' }, description: "Page types; default: the schema pack's entity types." },
source_id: { type: 'string', description: "One source; '__all__' spans your sources." },
},
handler: async (ctx, p) => {
const params = parseParams(ctx, p);
const sourceIdParam = parseSourceIdParam(p.source_id, 'whois', { allowAll: true });
const scope = federatedSearchScope(ctx, sourceIdParam);
await assertExplicitSourceLive(ctx, sourceIdParam);
const sourceIds = scope.sourceIds ?? (scope.sourceId !== undefined
? [scope.sourceId]
: (await ctx.engine.executeRaw<{ id: string }>('SELECT id FROM sources WHERE archived IS NOT TRUE ORDER BY id')).map(r => r.id));
const { resolveEntityTypes } = await import('../schema-pack/entity-types.ts');
const resolution = params.types
? { status: 'explicit' as const, filter: { types: params.types, per_source: [] } }
: await resolveEntityTypes(ctx.engine, sourceIds);
const { resolveExcludePrivatePages } = await import('../search/private-visibility.ts');
const excludePrivate = await resolveExcludePrivatePages(ctx.engine, ctx.remote);
const { text, params: values } = exactIdentityStatement({
probes: probesFor(params.raw, params.query),
sourceIds,
types: resolution.filter,
...(ctx.remote !== false ? { remote: { excludePrivate } } : {}),
limit: WHOIS_CANDIDATE_CAP + 1,
});
const rows = await ctx.engine.executeRaw<ExactIdentityRow>(text, values);
const matches = rows.slice(0, WHOIS_CANDIDATE_CAP)
.map(r => ({ slug: r.slug, source_id: r.source_id, title: r.title, type: r.type, match: identityMatchKind(params.query, r) }))
.filter((m): m is typeof m & { match: IdentityMatchKind } => m.match !== null)
.sort((a, b) => MATCH_RANK[a.match] - MATCH_RANK[b.match] || (a.source_id < b.source_id ? -1 : a.source_id > b.source_id ? 1 : 0) || (a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0));
const notes: string[] = [];
if (resolution.status === 'pack_unavailable') notes.push('The schema pack did not load, so no entity types are known: pass types explicitly, e.g. ["person"].');
if (rows.length > WHOIS_CANDIDATE_CAP) notes.push('More candidates than ' + WHOIS_CANDIDATE_CAP + ' share this key, so matches may be incomplete: narrow with source_id or types.');
return {
query: params.raw.trim(),
query_kind: params.query.email ? 'email' : 'name',
types: params.types ?? 'schema_pack_entity_types',
types_status: resolution.status,
matches,
ambiguous: matches.length > 1,
...(rows.length > WHOIS_CANDIDATE_CAP ? { truncated: true } : {}),
...(notes.length ? { note: notes.join(' ') } : {}),
};
},
cliHints: { name: 'whois', positional: ['query'] },
};
export const whoisOperations: Operation[] = [whois];