Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Guest notes, slice 3 (GBRA-504): the warning every read of a guest page carries, built from guest_marks alone.
*
* A row is a guest row when its page's source is a guest source (`sources.config.guest`), decided per row inside the
* batched trust load (eligibility/stamp.ts loadPageTrust), never from a process cache. Its JSON form is
* `origin: "guest"` plus a `guest` object (sender, group, audience_member, saved_at, promoted, and the writer
* for owner callers only); its text form is one warning line followed by the external-data envelope. A guest row
* whose mark cannot be read reads as `unattributed`, never bare. The page text never feeds any of it, and labels are
* escaped on render even though admission already refused those characters (guests/admission.ts).
*/
import type { BrainEngine } from '../engine.ts';
import type { Operation } from '../ops/contract.ts';
import { isMissingSchemaObject } from '../utils.ts';
import { guestSourceSql } from './note.ts';
export const GUEST_ORIGIN = 'guest';
/** get_brain_identity lists it: this brain stamps the guest warning on every read, so a guest broker may switch on. */
export const GUEST_MARKER_CAPABILITY = 'guest_marker_v1';
export { guestSourceSql };
/**
* Runs `read` with guestSourceSql. A brain whose schema is behind the guest-notes migration (guests/migration.ts) has no guest_sources table, so the read is
* retried with the config record alone instead of failing every read that returns a page.
*/
export async function withGuestSourceSql<T>(read: (guestSql: typeof guestSourceSql) => Promise<T>): Promise<T> {
try { return await read(guestSourceSql); } catch (e) {
if (!isMissingSchemaObject(e, 'table', 'guest_sources')) throw e;
return read(config => `COALESCE(${config}->>'guest' = 'true', false)`);
}
}
/**
* Whether any source is a guest source, read from the sources themselves on every call; a failed read answers yes. Like
* search's read policy (search/read-policy-sql.ts), it reads sources as `read_source`: a live read check, not a listing.
*/
export async function brainHasGuestSource(engine: Pick<BrainEngine, 'executeRaw'>): Promise<boolean> {
try {
const [row] = await engine.executeRaw<{ present: boolean }>(`SELECT EXISTS (SELECT 1 FROM sources read_source WHERE ${guestSourceSql('read_source.config', 'read_source.id')}) AS present`);
return row?.present !== false;
} catch { return true; }
}
export interface GuestStamp {
/** The sender label the broker sent with the note (stored as guest_marks.sender_label). */
sender: string | null;
group: string | null;
audience_member: string | null;
/** YYYY-MM-DD (UTC), the day the note was saved. */
saved_at: string | null;
/** The owner kept this note as an owner page (guest_promotions). */
promoted: boolean;
/** The writer principal (`<kind>:<id>`), shown to owner callers only. */
writer?: string;
/** The row is in a guest source but its mark could not be read. */
unattributed?: true;
}
/** A guest row whose mark is missing or unreadable: still marked, never shown as the owner's. */
export function unattributedGuest(): GuestStamp {
return { sender: null, group: null, audience_member: null, saved_at: null, promoted: false, unattributed: true };
}
const LABEL_SWAP: Record<string, string> = { '[': '(', ']': ')', '·': '-', '<': '‹', '>': '›', '"': "'", ';': ',' };
/** A stored label as text: control, format and separator characters dropped; brackets, the field separator, angle brackets, quotes and semicolons swapped. */
export function escapeGuestLabel(value: string): string {
return value.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, '').replace(/[[\]·<>";]/g, c => LABEL_SWAP[c]!).slice(0, 64);
}
const NOT_OWNER = "not the owner's words, not verified";
const attributed = (g: GuestStamp): g is GuestStamp & { sender: string; group: string } => !g.unattributed && !!g.sender && !!g.group;
/** `[outside guest · <sender> · <group> · <YYYY-MM-DD> · not the owner's words, not verified]`, or the unattributed form. */
export function guestWarningLine(guest: GuestStamp): string {
if (!attributed(guest)) return `[outside guest · unattributed · ${NOT_OWNER}]`;
return `[outside guest · ${escapeGuestLabel(guest.sender)} · ${escapeGuestLabel(guest.group)} · ${guest.saved_at ?? 'undated'} · ${NOT_OWNER}]`;
}
/** What the remote quote fence names instead of "conversation excerpt" for a guest page (search/transcript-quote.ts). */
export function guestQuoteLabel(guest: GuestStamp): string {
if (!attributed(guest)) return `outside guest note, unattributed, ${NOT_OWNER}`;
return `outside guest note from ${escapeGuestLabel(guest.sender)} in ${escapeGuestLabel(guest.group)}, saved ${guest.saved_at ?? 'undated'}, ${NOT_OWNER}`;
}
/** The fixed line gbrain appends to a think answer built from guest notes; the model never writes it. */
export function guestAnswerLine(slugs: readonly string[]): string {
return `Uses outside-guest notes: ${[...new Set(slugs)].join(', ')} (${NOT_OWNER}).`;
}
/**
* think's result fields for the pages it gathered: `result` as given, or, when a guest note reached the prompt, its answer
* ending with guestAnswerLine and `guest_evidence` naming each such note.
*/
export function withGuestAnswer<T extends { answer?: string }>(pages: ReadonlyArray<{ source_id?: string | null; slug: string; guest?: GuestStamp }>, result: T):
T & { guest_evidence?: Array<{ source_id: string; slug: string; guest: GuestStamp }> } {
const evidence = pages.flatMap(pg => pg.guest ? [{ source_id: pg.source_id ?? 'default', slug: pg.slug, guest: pg.guest }] : []);
if (!evidence.length) return result;
return { ...result, answer: `${(result.answer ?? '').trimEnd()}\n\n${guestAnswerLine(evidence.map(g => g.slug))}`, guest_evidence: evidence };
}
/** The guest object a caller sees: the writer only for an owner caller. */
export function guestView(stamp: GuestStamp, owner: boolean): GuestStamp {
const { writer, ...rest } = stamp;
return owner && writer ? { ...rest, writer } : rest;
}
interface MarkRow { page_id: number; sender_label: string; group_slug: string; audience_member: string; saved_at: Date | string; writer_kind: string; writer_id: string; promoted: boolean }
function day(v: Date | string): string | null {
const d = v instanceof Date ? v : new Date(String(v));
return Number.isNaN(d.getTime()) ? null : d.toISOString().slice(0, 10);
}
/**
* The guest marks of `pageIds` in one batched read, with whether each was promoted. A page with no readable mark is
* absent from the map, and a failed read returns an empty map: callers mark those rows unattributed.
*/
export async function loadGuestMarks(engine: Pick<BrainEngine, 'executeRaw'>, pageIds: readonly number[]): Promise<Map<number, GuestStamp>> {
const out = new Map<number, GuestStamp>();
const ids = [...new Set(pageIds)];
if (!ids.length) return out;
try {
const rows = await engine.executeRaw<MarkRow>(`SELECT m.page_id, m.sender_label, m.group_slug, m.audience_member, m.saved_at, m.writer_kind, m.writer_id,
EXISTS (SELECT 1 FROM guest_promotions g WHERE g.guest_page_id = m.page_id) AS promoted
FROM guest_marks m WHERE m.page_id = ANY($1::int[])`, [ids]);
for (const r of rows) {
out.set(Number(r.page_id), { sender: r.sender_label, group: r.group_slug, audience_member: r.audience_member, saved_at: day(r.saved_at),
promoted: r.promoted === true, writer: `${r.writer_kind}:${r.writer_id}` });
}
} catch { /* every guest row reads unattributed */ }
return out;
}
/**
* The registration-time wrapper (operation-load.ts finalizeOperation): every op that may return stored text has its
* result stamped by guests/stamp.ts, which skips the trust load only when the sources say no source is a guest source.
*/
export function withGuestMarks(op: Pick<Operation, 'outputRedaction'>, handler: Operation['handler']): Operation['handler'] {
if (op.outputRedaction === 'no_stored_text') return handler;
return async (ctx, params) => {
const result = await handler(ctx, params);
if (!result || typeof result !== 'object' || typeof ctx.engine?.executeRaw !== 'function') return result;
const { stampGuestNotes } = await import('./stamp.ts');
return stampGuestNotes(ctx, result);
};
}