Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
17.6 KB
Raw Blame
/**
 * GST-2670 (GBRA-502): the pages every member's key can read on a brain that serves several people. A page is open
 * when no readable_by names readers and no applied or pending folder or page rule covers it: a key bound to a member
 * reads it like an unbound one (requester-scope.ts gates who may ask; only labels decide what a member reads). The
 * count is the read path's own floor (accessAllowedSql with an empty identity, built outside any caller record, so it
 * never depends on who asks), split into the pages members read and the visibility: private pages they do not
 * (unless this process sees remote privacy relaxed, or a reading member's grant opens that source's private pages). "Members" are the enabled members other than the owner;
 * a labelled-only member reads no open page, and each other member reads the sources its bound tokens and OAuth
 * clients read. Read-only and best effort everywhere it is shown: access serves several (preview and receipt),
 * gbrain access serves, doctor open_shared_pages and post-upgrade. Callers gate on brainServes first, so a
 * one-person brain, or one pinned to access.serves one, never runs it. Everything is database state, so a repo-less
 * brain gets it unchanged. gbrain repair visibility --propose (commands/repair-propose.ts) reads the same pages through
 * withOpenScope, openPageSql and membersReadOpen.
 */
import type { BrainEngine } from '../engine.ts';
import { accessAllowedSql, privacyPartSql, readHonorAliases, remotePrivacyRelaxed, withoutCallerAccess } from '../search/private-visibility.ts';
import { credentialReadSources, SENSITIVE_PAGE_TYPES, stdioReadSources } from '../grants/shared-exposure.ts';
import { grantFromClient, grantFromRow, grantFromTokenRow, privatePagesSources, type PrincipalGrant } from '../grants/model.ts';
import { stdioMemberId } from './caller.ts';
import { localFederatedSourceIds } from '../source-resolver.ts';
import { isStatementTimeout } from '../persistence/bounded-reads.ts';
import { agentBlock } from '../agent-markers.ts';
import { ownerMemberId } from './owner.ts';
import { brainServes } from './serves.ts';

export const OPEN_PAGES_TOP = 10;
export const OPEN_PAGES_TIMEOUT_MS = 30_000;
const RETRY = 'gbrain doctor --only open_shared_pages --json';

export interface OpenFolder { source: string; folder: string; pages: number; sensitive: number }
export interface OpenPages {
  /** The brain owner (access.owner_member), whom every printed reader list starts with; null when none is set. */
  owner: string | null;
  /** reading: members other than the owner, not labelled-only, whose keys (or config mcp.stdio_member binding) read a source; counted: members other than the owner. */
  members: { reading: number; counted: number };
  /** The sources counted: those the reading members read, or every source when no member reads one. */
  sources: string[];
  total: number;
  /** Open pages of a DM, chat, conversation or mail type (SENSITIVE_PAGE_TYPES). */
  sensitive: number;
  /** Open pages that visibility: private (or a privacy alias) keeps from members; counted in total instead where remote privacy is relaxed or a reading member's grant opens private pages. */
  private: number;
  /** GBRA-585 C: open pages in the conversation archive (conversations/), also counted in total. */
  archive: number;
  folders: OpenFolder[];
  other: { folders: number; pages: number; sensitive: number };
  top_sensitive: { source: string; type: string; pages: number } | null;
}
export interface OpenPagesError { code: string; message: string; retry: string }
export interface OpenPagesRead { open_pages: OpenPages | null; open_pages_error?: OpenPagesError }

export interface OpenPagesOptions {
  /** Members a run is about to add or keep, the source their new keys write (access serves several), whether it marks them labelled-only, and the owner once the run is done. */
  planned?: { members: readonly string[]; source: string; labelledOnly: boolean; owner?: string | null };
  /** Prefixes a rule the run adds will cover, left out of the count. */
  exclude?: ReadonlyArray<{ source: string; prefix: string }>;
}

/** The source the company shape adds (setup-brain-layout.ts COMPANY_SOURCE). */
export const COMPANY_SOURCE_ID = 'company';

/**
 * GBRA-585 A: the sources a member key `gbrain access serves several` mints for `source` reads, as a fixed list (the
 * federated grant kind, readSources[0] = the write source): that source, the `company` source when it exists, and
 * every source federated now. A source federated later is added only by a re-run (labelSeveral adds, never removes).
 */
export async function memberKeyReadSources(engine: BrainEngine, source: string): Promise<string[]> {
  const federated = await localFederatedSourceIds(engine, source, 'seed_default').catch(() => undefined) ?? [source];
  const company = source !== COMPANY_SOURCE_ID && (await engine.executeRaw<{ id: string }>('SELECT id FROM sources WHERE id = $1 AND archived IS NOT TRUE', [COMPANY_SOURCE_ID])).length > 0;
  return [...new Set([source, ...(company ? [COMPANY_SOURCE_ID] : []), ...federated])];
}

/**
 * Each counted member (enabled, not the owner) with the sources its keys and a config mcp.stdio_member binding read
 * (empty for a labelled-only member), and the sources whose private pages some reading member's grant opens. A harness
 * entry's serve --stdio-member is not in the database, so it is not seen here.
 */
async function memberReads(engine: BrainEngine, owner: string | null, planned: OpenPagesOptions['planned']): Promise<{ reads: Map<string, Set<string>>; privateSources: Set<string> }> {
  const reads = new Map<string, Set<string>>();
  const privateOf = new Map<string, Set<string>>();
  const labelledOnly = new Set<string>();
  for (const m of await engine.executeRaw<{ id: string; labelled_only: unknown }>(
    'SELECT id, labelled_only FROM access_members WHERE disabled_at IS NULL AND tombstoned_at IS NULL ORDER BY id')) {
    if (m.id === owner) continue;
    reads.set(m.id, new Set());
    if (m.labelled_only === true) labelledOnly.add(m.id);
  }
  const memo = new Map<string, Promise<string[]>>();
  const sourcesOf = (grant: PrincipalGrant) => {
    const key = JSON.stringify([grant.principal.kind, grant.scopes, grant.sources]);
    if (!memo.has(key)) memo.set(key, credentialReadSources(engine, grant));
    return memo.get(key)!;
  };
  const credentials: Array<{ member: string; grant: PrincipalGrant }> = [
    ...(await engine.executeRaw<Record<string, unknown>>('SELECT * FROM access_tokens WHERE revoked_at IS NULL AND member_id IS NOT NULL'))
      .map(row => ({ member: String(row.member_id), grant: grantFromTokenRow(row as never) })),
    ...(await engine.executeRaw<Record<string, unknown>>('SELECT * FROM oauth_clients WHERE deleted_at IS NULL AND member_id IS NOT NULL'))
      .map(row => ({ member: String(row.member_id), grant: grantFromClient(grantFromRow(row)) })),
  ];
  for (const { member, grant } of credentials) {
    const set = reads.get(member);
    if (!set) continue;
    for (const s of await sourcesOf(grant)) set.add(s);
    const priv = privateOf.get(member) ?? new Set<string>();
    privateOf.set(member, priv);
    for (const s of privatePagesSources(grant)) priv.add(s);
  }
  const stdio = await stdioMemberId(engine);
  const stdioSet = stdio ? reads.get(stdio) : undefined;
  if (stdioSet) for (const s of await stdioReadSources(engine)) stdioSet.add(s);
  if (planned) {
    const minted = await memberKeyReadSources(engine, planned.source);
    for (const id of planned.members) {
      if (id === owner) continue;
      const set = reads.get(id) ?? new Set<string>();
      reads.set(id, set);
      for (const s of minted) set.add(s);
      if (planned.labelledOnly) labelledOnly.add(id);
    }
  }
  for (const id of labelledOnly) reads.get(id)?.clear();
  const privateSources = new Set<string>();
  for (const [id, set] of reads) if (set.size) for (const s of privateOf.get(id) ?? []) privateSources.add(s);
  return { reads, privateSources };
}

async function bounded<T>(engine: BrainEngine, fn: (e: BrainEngine) => Promise<T>): Promise<T> {
  if (engine.kind !== 'postgres') return fn(engine);
  return engine.transaction(async (tx) => {
    await tx.executeRaw(`SET LOCAL statement_timeout = ${OPEN_PAGES_TIMEOUT_MS}`);
    return fn(tx);
  }, { readOnly: true });
}

/** Who reads the open pages: the owner, the counted members, the sources their keys read, and how private pages read. */
export interface OpenScope {
  owner: string | null;
  members: { reading: number; counted: number };
  /** The sources the reading members read, or every source when no member reads one. */
  sources: string[];
  /** Remote privacy is relaxed, so members read visibility: private pages too. */
  relaxed: boolean;
  /** Sources whose private pages some reading member's grant opens. */
  privateSources: string[];
}

/** The open-page predicate over pages alias `p`: live, and the read path's floor with an empty identity admits it. */
export const openPageSql = (p: string) => `${p}.deleted_at IS NULL AND ${accessAllowedSql(p, [], [])}`;

/** Whether the members read an open page of `source` whose privacyPartSql value is `visible`. */
export const membersReadOpen = (scope: OpenScope, source: string, visible: unknown) => visible === true || scope.relaxed || scope.privateSources.includes(source);

/**
 * The OpenScope; throws open_pages_unknown when the folder-rule state cannot be read. `read` then runs a query built on
 * openPageSql under the same statement bound, outside any caller record, so it never depends on who asks.
 */
export async function withOpenScope<T>(engine: BrainEngine, opts: OpenPagesOptions, read: (scope: OpenScope, bounded: <R>(fn: (e: BrainEngine) => Promise<R>) => Promise<R>) => Promise<T>): Promise<T> {
  return withoutCallerAccess(async () => {
    const [state] = await engine.executeRaw<{ unreadable: unknown }>('SELECT gbrain_access_state_unreadable() AS unreadable');
    if (state?.unreadable === true) {
      throw Object.assign(new Error('the folder-rule state cannot be read, so every page reads as covered and a count would say 0'), { code: 'open_pages_unknown' });
    }
    const owner = opts.planned?.owner !== undefined ? opts.planned.owner : await ownerMemberId(engine);
    const { reads, privateSources } = await memberReads(engine, owner, opts.planned);
    const reading = [...reads.values()].filter(s => s.size > 0);
    const readSources = [...new Set(reading.flatMap(s => [...s]))].sort();
    const sources = readSources.length ? readSources : (await engine.executeRaw<{ id: string }>('SELECT id FROM sources ORDER BY id')).map(s => s.id);
    if (sources.length) await readHonorAliases(engine);
    const relaxed = sources.length ? await remotePrivacyRelaxed(engine) : false;
    const scope: OpenScope = { owner, members: { reading: reading.length, counted: reads.size }, sources, relaxed, privateSources: [...privateSources].sort() };
    return read(scope, fn => bounded(engine, fn));
  });
}

/** The open pages the counted members' keys read (OpenPages); throws when the access state cannot be read. */
export async function openPages(engine: BrainEngine, opts: OpenPagesOptions = {}): Promise<OpenPages> {
  return withOpenScope(engine, opts, async (scope, boundedRead) => {
    const { owner, sources } = scope;
    const result: OpenPages = { owner, members: scope.members, sources, total: 0, sensitive: 0, private: 0, archive: 0,
      folders: [], other: { folders: 0, pages: 0, sensitive: 0 }, top_sensitive: null };
    if (!sources.length) return result;
    const params: unknown[] = [sources];
    const exclude = (opts.exclude ?? []).map(x => {
      params.push(x.source, x.prefix);
      return ` AND NOT (p.source_id = $${params.length - 1} AND starts_with(p.slug, $${params.length}))`;
    }).join('');
    const rows = await boundedRead(e => e.executeRaw<{ source: string; folder: string; type: string | null; visible: unknown; pages: number | string }>(
      `SELECT p.source_id AS source, CASE WHEN strpos(p.slug, '/') > 0 THEN split_part(p.slug, '/', 1) ELSE '(root)' END AS folder,
              p.type AS type, (${privacyPartSql('p')}) AS visible, count(*)::int AS pages
         FROM pages p
        WHERE ${openPageSql('p')} AND p.source_id = ANY($1::text[])${exclude}
        GROUP BY 1, 2, 3, 4`, params));
    const folders = new Map<string, OpenFolder>();
    const byType = new Map<string, { source: string; type: string; pages: number }>();
    for (const row of rows) {
      const n = Number(row.pages);
      if (!membersReadOpen(scope, row.source, row.visible)) { result.private += n; continue; }
      const key = `${row.source}/${row.folder}`;
      const f = folders.get(key) ?? { source: row.source, folder: row.folder, pages: 0, sensitive: 0 };
      folders.set(key, f);
      f.pages += n;
      result.total += n;
      if (row.folder === 'conversations') result.archive += n;
      if (!row.type || !SENSITIVE_PAGE_TYPES.includes(row.type)) continue;
      f.sensitive += n;
      result.sensitive += n;
      const t = byType.get(`${row.source}/${row.type}`) ?? { source: row.source, type: row.type, pages: 0 };
      byType.set(`${row.source}/${row.type}`, t);
      t.pages += n;
    }
    const sorted = [...folders.values()].sort((a, b) => b.pages - a.pages || a.source.localeCompare(b.source) || a.folder.localeCompare(b.folder));
    result.folders = sorted.slice(0, OPEN_PAGES_TOP);
    for (const f of sorted.slice(OPEN_PAGES_TOP)) { result.other.folders++; result.other.pages += f.pages; result.other.sensitive += f.sensitive; }
    result.top_sensitive = [...byType.values()].sort((a, b) => b.pages - a.pages || a.type.localeCompare(b.type))[0] ?? null;
    return result;
  });
}

/** openPages that never throws: the count, or null with what went wrong and the command that retries it. */
export async function readOpenPages(engine: BrainEngine, opts: OpenPagesOptions = {}): Promise<OpenPagesRead> {
  try {
    return { open_pages: await openPages(engine, opts) };
  } catch (e) {
    const code = (e as { code?: string }).code === 'open_pages_unknown' ? 'open_pages_unknown' : isStatementTimeout(e) ? 'open_pages_timeout' : 'open_pages_failed';
    return { open_pages: null, open_pages_error: { code, message: e instanceof Error ? e.message : String(e), retry: RETRY } };
  }
}

const folderName = (f: OpenFolder) => f.folder === '(root)' ? `${f.source}:(root)` : `${f.source}:${f.folder}/`;

/** The headline: whose keys read how many open pages. */
export function openPagesHeadline(o: OpenPages): string {
  if (!o.total) return "Every page the members' keys read names its readers (readable_by or a rule).";
  const pages = `${o.total} ${o.total === 1 ? 'page' : 'pages'}, and the facts drawn from them, that no rule or readable_by restricts`;
  const sensitive = o.sensitive ? `, ${o.sensitive} of them DMs, chat or mail` : '';
  return o.members.reading
    ? `The keys of ${o.members.reading} of ${o.members.counted} members can read ${pages}${sensitive}.`
    : `No member's key reads the ${pages}${sensitive}: every member other than the owner is labelled-only or has no key.`;
}

/**
 * The lines that show the open pages and the commands that label them, the owner first in every reader list.
 * labelledOnly: the command that keeps members to labelled pages where the lines are shown.
 */
export function openPagesLines(read: OpenPagesRead, opts: { prefix?: string; labelledOnly?: string } = {}): string[] {
  const head = opts.prefix ?? '  open pages ';
  const pad = ' '.repeat(head.length);
  const o = read.open_pages;
  if (!o) return [`${head}count unknown (${read.open_pages_error?.message ?? 'not read'}); retry with ${read.open_pages_error?.retry ?? RETRY}`];
  if (!o.total) return [head + openPagesHeadline(o)];
  const readers = `${o.owner ? `${o.owner},` : ''}<list>`;
  const shared = o.folders.find(f => !f.sensitive && f.folder !== '(root)' && f.folder !== 'people');
  const where = [...o.folders.map(f => `${folderName(f)} ${f.pages}${f.sensitive ? ` (${f.sensitive} of them DMs, chat or mail)` : ''}`),
    ...(o.other.folders ? [`${o.other.folders} more ${o.other.folders === 1 ? 'folder' : 'folders'} ${o.other.pages}`] : [])].join(', ');
  return [
    head + openPagesHeadline(o),
    `${pad}${where}.`,
    ...(o.top_sensitive ? [`${pad}DMs, chat and mail: keep members to pages labelled for them (${opts.labelledOnly ?? 'gbrain access member labelled-only <member> on'}), then name each page set's readers: gbrain repair visibility --source ${o.top_sensitive.source} --slugs-file <file> --readers ${readers} (preview, then --apply --expect <hash>).`] : []),
    ...(shared ? [`${pad}A folder its readers share: gbrain access rule add --prefix ${shared.folder}/ --readers ${readers} --source ${shared.source} (preview, then --yes).`] : []),
    `${pad}New pages: put readable_by: [${o.owner ? `${o.owner}, ` : ''}<list>] in their frontmatter.`,
  ];
}

/** gbrain post-upgrade: the open DM, chat and mail pages on a brain that serves several people. Best effort; prints nothing otherwise. */
export async function printOpenPagesUpgradeNotice(engine: BrainEngine): Promise<void> {
  try {
    if ((await brainServes(engine)).serves !== 'several') return;
    const read = await readOpenPages(engine);
    if (!read.open_pages?.sensitive || !read.open_pages.members.reading) return;
    console.log('');
    console.log(agentBlock({
      why: `This brain serves several people. ${openPagesHeadline(read.open_pages)} A key bound to a member reads a page with no readers like any other key.`,
      actor: 'user',
      next: 'Relay the list below to the user and ask who should read each folder. Nothing was changed; each command previews first.',
      verify: RETRY,
    }).trimEnd());
    for (const line of openPagesLines(read, { prefix: '  ' })) console.log(line);
  } catch { /* cosmetic; never blocks the upgrade */ }
}