Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.7 KB
Raw Blame
/**
 * Guest notes, slice 3 (GBRA-504): stamps the guest warning onto an op's output. Runs on every op that returns stored
 * text, wrapped once at registration (operation-load.ts finalizeOperation), so every remote, stdio and enforced-member
 * dispatch, the local CLI and in-process callers all get it. The shared page-item walker (access/page-items.ts) finds
 * every page-bearing item; the batched trust load (eligibility/stamp.ts loadPageTrust) decides per row whether its
 * source is a guest source and reads the marks; each guest item gains `trust_tier: external_untrusted`,
 * `origin: "guest"` and its `guest` object, and a remote quote fence around its text names the guest. Only a page the
 * caller's own read policy admits is stamped (guests/stamp-readable.ts); output redaction runs after the stamp
 * (operation-load.ts). The stamp is on the handler's result, so dispatch's response-cap fallback, which drops room
 * marks, never drops it.
 */
import type { OperationContext } from '../ops/contract.ts';
import { currentCallerAccess } from '../search/private-visibility.ts';
import { exemptGuestWriter } from '../search/output-redaction.ts';
import { collectPageItems, refKey, type PageRef, type Ref } from '../access/page-items.ts';
import { loadPageTrust } from '../eligibility/stamp.ts';
import { relabelGuestQuote } from '../search/transcript-quote.ts';
import { brainHasGuestSource, GUEST_ORIGIN, guestQuoteLabel } from './marker.ts';
import { readableGuestRefs } from './stamp-readable.ts';

/** An owner caller sees the guest note's writer: the trusted local CLI, or a credential bound to the owner speaking for no one else. */
export function guestViewerIsOwner(ctx: Pick<OperationContext, 'remote'>): boolean {
  if (ctx.remote === false) return true;
  const access = currentCallerAccess();
  return access.owner && !access.audience?.length;
}

/** A copy of `value` the stamp may mark; refuses the read when it cannot copy, so a handler's own (possibly cached) object is never marked. */
function detachedCopy<T>(value: T): T {
  let copy: T;
  try { copy = structuredClone(value); } catch (e) {
    throw new Error(`The guest-note stamp could not copy this result (${e instanceof Error ? e.message : String(e)}), so the read was refused rather than mark the handler's own object or return a guest note unmarked.`);
  }
  if (value && typeof value === 'object' && copy && typeof copy === 'object') {
    for (const key of Object.getOwnPropertySymbols(value)) (copy as Record<symbol, unknown>)[key] = (value as Record<symbol, unknown>)[key];
  }
  return copy;
}

const refSlug = (r: Ref) => (r.kind === 'page' ? r.slug : undefined);

/**
 * `result` with every guest item stamped, on a detached copy (handlers may return cached objects), or `result` itself
 * when nothing in it is a guest row the caller may read. The trust load is skipped only when no source is a guest source
 * (marker.ts brainHasGuestSource, which answers yes when it cannot tell); a failed trust or readability load fails the
 * read rather than return a guest note unmarked.
 */
export async function stampGuestNotes(ctx: OperationContext, result: unknown): Promise<unknown> {
  if (!result || typeof result !== 'object') return result;
  const found = collectPageItems(result, ctx.sourceId ?? 'default').filter(s => s.ref !== null && s.ref.kind !== 'fact');
  if (!found.length || !(await brainHasGuestSource(ctx.engine))) return result;
  const refs = found.map(s => s.ref!).map(r => r.kind === 'page' ? { source_id: r.source_id, slug: r.slug } : { page_id: (r as { id: number }).id, slug: '' });
  const trust = await loadPageTrust(ctx.engine, refs, { guestWriter: guestViewerIsOwner(ctx), includeDeleted: true });
  const markOf = (r: Ref) => (r.kind === 'page' ? trust.byKey.get(`${r.source_id}\u0000${r.slug}`) : r.kind === 'page_id' ? trust.byId.get(r.id) : undefined)?.guest;
  const marked = found.map(s => s.ref as PageRef).filter(r => markOf(r));
  if (!marked.length) return result;
  const readable = await readableGuestRefs(ctx, marked);
  const guestOf = (r: Ref) => (readable.has(refKey(r)) ? markOf(r) : undefined);
  if (!marked.some(guestOf)) return result;
  const copy = detachedCopy(result);
  for (const slot of collectPageItems(copy, ctx.sourceId ?? 'default')) {
    const guest = slot.ref ? guestOf(slot.ref) : undefined;
    if (!guest) continue;
    const h = slot.holder;
    h.trust_tier = 'external_untrusted';
    h.origin = GUEST_ORIGIN;
    h.guest = exemptGuestWriter(guest);
    const slug = refSlug(slot.ref!) ?? (typeof h.slug === 'string' ? h.slug : undefined);
    if (!slug) continue;
    for (const [k, v] of Object.entries(h)) if (typeof v === 'string') h[k] = relabelGuestQuote(v, slug, guestQuoteLabel(guest));
  }
  return copy;
}