Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
23.8 KB
Raw Blame
/**
 * Derived and retried writes never land broader than their source (fail closed).
 *
 * - Facts auto-extracted from a `visibility: private` page were stamped with the
 *   brain default; with `facts.default_visibility=world` they came out world, and
 *   a fact with no fence page was then returned to remote callers by recall and the
 *   entity card. They are private now, on the page-write backstop and on
 *   extract_facts with a private `source_slug`.
 * - `remember` with no visibility hard-defaulted to world: a reworded retry that
 *   dropped the parameter widened a private save. It now resolves private for a
 *   private target page or an explicit private brain default, and stays world
 *   otherwise (the v1 contract).
 * - A page marked private only by a privacy alias (`access`, `confidentiality`)
 *   counts as private for everything derived from it; remote page reads honor the
 *   aliases by default; `visibility.honor_aliases false` opts out.
 * - Connector re-renders keep a page's private label; Google private events render private.
 * - The doctor check lists what is already labelled wider than its source, and the
 *   visibility repair previews it and changes it only with --apply.
 *
 * PGLite and Postgres (DATABASE_URL); stub transports, zero model calls; synthetic names.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { configureGateway, resetGateway, __setChatTransportForTests, __setEmbedTransportForTests, type ChatResult } from '../src/core/ai/gateway.ts';
import { runFactsBackstop } from '../src/core/facts/backstop.ts';
import { operationsByName } from '../src/core/operations.ts';
import type { OperationContext } from '../src/core/ops/contract.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { registerLocalWriter } from '../src/core/persistence/identity.ts';
import { withCoordinatedWrite } from '../src/core/persistence/context.ts';
import { derivedVisibilityCheck } from '../src/commands/doctor/checks/derived-visibility.ts';
import { visibilityRepair } from '../src/core/repair/visibility.ts';
import { resolveRepairScope, runRepair } from '../src/core/repair/core.ts';
import { __resetPrivateVisibilityCacheForTests, effectiveVisibility, isDerivationPrivate } from '../src/core/search/private-visibility.ts';
import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { testBackends } from './helpers/test-backends.ts';
import { withEnv } from './helpers/with-env.ts';
import { renderCalendarEventPage, withPrivateVisibility } from '../src/core/google/google-render.ts';
import { importRendered } from '../src/core/google/sweep-shared.ts';
import type { CalendarEventData } from '../src/core/google/types.ts';
import { segmentedRememberRefusal } from '../src/core/persistence/verb-errors.ts';

const DIMS = 1536;
const PERSON = 'people/alice-example';
const PRIVATE_PERSON = 'people/dana-example';
const NOTE = 'notes/private-session-example';
const BODY = 'Alice Example shared the confidential acquisition terms of the example company during a private session. '.repeat(2);
const CLAIM = 'Alice Example shared the confidential acquisition terms';

const engines: BrainEngine[] = [];
let closePostgres: (() => Promise<void>) | undefined;

beforeAll(async () => {
  configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: DIMS, env: { OPENAI_API_KEY: 'test' } });
  for (const backend of testBackends()) {
    if (backend === 'pglite') {
      const engine = new PGLiteEngine();
      await engine.connect({});
      await engine.initSchema();
      engines.push(engine);
    } else {
      const isolated = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
      engines.push(isolated.engine);
      closePostgres = isolated.close;
    }
  }
}, 120_000);
afterAll(async () => {
  __setChatTransportForTests(null); __setEmbedTransportForTests(null);
  for (const engine of engines) { await disposePersistenceConsumer(engine); await engine.disconnect(); }
  await closePostgres?.();
  resetGateway();
});

function stubExtraction(fact: string) {
  __setChatTransportForTests(async (): Promise<ChatResult> => ({
    text: JSON.stringify({ facts: [{ fact, kind: 'fact', entity: PERSON, confidence: 1, notability: 'high' }] }),
    blocks: [], stopReason: 'end', usage: { input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, cache_creation_tokens: 0 }, model: 'test:stub', providerId: 'test' }));
  __setEmbedTransportForTests((async ({ values }: { values: string[] }) => ({
    embeddings: values.map(() => Array.from({ length: DIMS }, (_, i) => (i === 0 ? 1 : 0))) })) as never);
}

const ctxFor = (engine: BrainEngine, sourceId: string, remote: boolean) => ({ engine, config: { engine: engine.kind }, remote, sourceId, dryRun: false,
  logger: { info() {}, warn() {}, error() {} } }) as unknown as OperationContext;

/** A fresh source holding a world person page, a private person page and a private note mentioning the world person. */
async function source(engine: BrainEngine, managed: boolean) {
  const sourceId = `vis-${randomUUID().slice(0, 8)}`;
  await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
  await engine.executeRaw('INSERT INTO sources(id,name) VALUES($1,$1)', [sourceId]);
  await registerLocalWriter(engine, 'cli');
  await engine.executeRaw('UPDATE persistence_brain SET enabled=$1 WHERE singleton=1', [managed]);
  const put = (slug: string, type: string, title: string, body: string, frontmatter: Record<string, unknown>) =>
    engine.transaction(tx => withCoordinatedWrite(tx, [sourceId], () => tx.putPage(slug, { type, title, compiled_truth: body, timeline: '', frontmatter }, { sourceId }), TEST_WRITE_ATTRIBUTION));
  await put(PERSON, 'person', 'Alice Example', 'Alice Example is a person.', {});
  await put(PRIVATE_PERSON, 'person', 'Dana Example', 'Dana Example is a person.', { visibility: 'private' });
  await put(NOTE, 'note', 'Session notes', BODY, { visibility: 'private' });
  return { sourceId, local: ctxFor(engine, sourceId, false), remote: ctxFor(engine, sourceId, true) };
}

async function factRows(engine: BrainEngine, sourceId: string) {
  return engine.executeRaw<{ id: number; fact: string; visibility: string }>('SELECT id,fact,visibility FROM facts WHERE source_id=$1 AND expired_at IS NULL ORDER BY id', [sourceId]);
}

/** What a remote (MCP) caller can read about the world person: recall's facts and the entity card's recent facts. */
async function remoteReadable(remote: OperationContext) {
  const recall = await operationsByName.recall!.handler(remote, { entity: PERSON }) as { facts: Array<{ fact: string }> };
  const card = await operationsByName.entity!.handler(remote, { name: PERSON }) as { card?: { recent_facts?: Array<{ fact: string }> } };
  return [...recall.facts.map(f => f.fact), ...(card.card?.recent_facts ?? []).map(f => f.fact)];
}

async function onEachEngine(body: (engine: BrainEngine) => Promise<void>) {
  for (const engine of engines) {
    const home = mkdtempSync(join(tmpdir(), 'gbrain-visibility-'));
    try { await withEnv({ GBRAIN_HOME: home }, () => body(engine)); }
    finally {
      await disposePersistenceConsumer(engine);
      await engine.executeRaw("DELETE FROM config WHERE key='facts.default_visibility'");
      await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
      rmSync(home, { recursive: true, force: true });
    }
  }
}

describe('facts extracted from a private page stay private', () => {
  test('page-write backstop on a world-default brain: the fact is private and remote callers cannot read it', async () => {
    await onEachEngine(async engine => {
      const s = await source(engine, false);
      await engine.setConfig('facts.default_visibility', 'world');
      stubExtraction(CLAIM);
      const result = await runFactsBackstop({ slug: NOTE, type: 'note', compiled_truth: BODY, frontmatter: { visibility: 'private' } },
        { engine, config: { engine: engine.kind } as never, sourceId: s.sourceId, sessionId: null, source: 'mcp:put_page', mode: 'inline', visibility: 'world' });
      expect((result as { inserted?: number }).inserted).toBe(1);
      expect((await factRows(engine, s.sourceId)).map(r => [r.fact, r.visibility])).toEqual([[CLAIM, 'private']]);
      expect(await remoteReadable(s.remote)).not.toContain(CLAIM);
      expect((await derivedVisibilityCheck(engine, s.sourceId)).details).toMatchObject({ world_facts_from_private_sources: 0 });
    });
  }, 120_000);

  test('a world page still yields world facts under a world default (no over-tightening)', async () => {
    await onEachEngine(async engine => {
      const s = await source(engine, false);
      await engine.setConfig('facts.default_visibility', 'world');
      stubExtraction(CLAIM);
      await runFactsBackstop({ slug: 'notes/open-example', type: 'note', compiled_truth: BODY, frontmatter: {} },
        { engine, config: { engine: engine.kind } as never, sourceId: s.sourceId, sessionId: null, source: 'mcp:put_page', mode: 'inline', visibility: 'world' });
      expect((await factRows(engine, s.sourceId)).map(r => r.visibility)).toEqual(['world']);
    });
  }, 120_000);

  test('extract_facts on a managed brain with a private source_slug writes private even when world was asked for', async () => {
    await onEachEngine(async engine => {
      const s = await source(engine, true);
      stubExtraction(CLAIM);
      const r = await operationsByName.extract_facts!.handler(s.local, { turn_text: BODY, visibility: 'world', source_slug: NOTE }) as { inserted: number };
      expect(r.inserted).toBe(1);
      expect((await factRows(engine, s.sourceId)).map(row => [row.fact, row.visibility])).toEqual([[CLAIM, 'private']]);
      expect(await remoteReadable(s.remote)).not.toContain(CLAIM);
    });
  }, 120_000);

  test('remote extract_facts: a private or unseen source_slug writes private alike; a world source keeps world', async () => {
    await onEachEngine(async engine => {
      const s = await source(engine, true);
      const extract = async (claim: string, source_slug: string) => {
        stubExtraction(claim);
        await operationsByName.extract_facts!.handler(s.remote, { turn_text: BODY, visibility: 'world', source_slug });
        return (await factRows(engine, s.sourceId)).find(r => r.fact === claim)?.visibility;
      };
      expect(await extract(CLAIM, NOTE)).toBe('private');
      expect(await extract('Alice Example joined the example board', 'notes/never-written-example')).toBe('private');
      expect(await extract('Alice Example moved to the example city', PERSON)).toBe('world');
      expect(await remoteReadable(s.remote)).not.toContain(CLAIM);
    });
  }, 120_000);
});

describe('remember without a visibility never widens', () => {
  const remember = (ctx: OperationContext, params: Record<string, unknown>) =>
    operationsByName.remember!.handler(ctx, { provenance: 'synthetic test', infer_entity: false, ...params }) as Promise<{ id: string; status: string }>;
  const visibilityOf = async (engine: BrainEngine, id: string) =>
    (await engine.executeRaw<{ visibility: string }>('SELECT visibility FROM facts WHERE id=$1', [Number(id)]))[0]?.visibility;

  test('onto a private entity page it saves private; an explicit world is honored; a world page keeps the world default', async () => {
    await onEachEngine(async engine => {
      const s = await source(engine, true);
      const onPrivate = await remember(s.local, { fact: 'Dana Example prefers morning meetings', entity: PRIVATE_PERSON });
      expect(await visibilityOf(engine, onPrivate.id)).toBe('private');
      const onWorld = await remember(s.local, { fact: 'Alice Example prefers morning meetings', entity: PERSON });
      expect(await visibilityOf(engine, onWorld.id)).toBe('world');
      const explicit = await remember(s.local, { fact: 'Dana Example uses a standing desk', entity: PRIVATE_PERSON, visibility: 'world' });
      expect(await visibilityOf(engine, explicit.id)).toBe('world');
    });
  }, 120_000);

  test('an explicit private brain default applies to remember; the same request_id replays the same private fact', async () => {
    await onEachEngine(async engine => {
      const s = await source(engine, true);
      await engine.setConfig('facts.default_visibility', 'private');
      const request_id = randomUUID();
      const first = await remember(s.local, { fact: 'Alice Example signed the renewal', entity: PERSON, request_id });
      expect(await visibilityOf(engine, first.id)).toBe('private');
      const replay = await remember(s.local, { fact: 'Alice Example signed the renewal', entity: PERSON, request_id });
      expect(replay.id).toBe(first.id);
      expect((await factRows(engine, s.sourceId)).filter(r => r.fact === 'Alice Example signed the renewal')).toHaveLength(1);
      expect(await remoteReadable(s.remote)).not.toContain('Alice Example signed the renewal');
    });
  }, 120_000);
});

describe('privacy aliases (access, confidentiality) count for everything derived', () => {
  const putAliased = (engine: BrainEngine, sourceId: string, slug: string, type: string, frontmatter: Record<string, unknown>, body = 'Synthetic body.') =>
    engine.transaction(tx => withCoordinatedWrite(tx, [sourceId], () => tx.putPage(slug, { type, title: slug, compiled_truth: body, timeline: '', frontmatter },
      { sourceId }), TEST_WRITE_ATTRIBUTION));

  test('the shared helper reads the alias values case-insensitively and nothing else', () => {
    for (const fm of [{ access: 'private' }, { access: ' Restricted ' }, { access: 'CONFIDENTIAL' }, { confidentiality: 'secret' }, { confidentiality: 'Private' }]) {
      expect(isDerivationPrivate({ type: 'meeting', frontmatter: fm })).toBe(true);
      expect(effectiveVisibility({ kind: 'page', page: { type: 'meeting', frontmatter: fm } })).toBe('private');
    }
    for (const fm of [{ access: 'work' }, { access: 'public' }, { confidentiality: 'internal' }, {}]) {
      expect(isDerivationPrivate({ type: 'meeting', frontmatter: fm })).toBe(false);
    }
  });

  test('remember onto an aliased entity page and extraction from an aliased page both write private', async () => {
    await onEachEngine(async engine => {
      const s = await source(engine, true);
      await putAliased(engine, s.sourceId, 'people/erin-example', 'person', { access: 'private', confidentiality: 'confidential' });
      const saved = await operationsByName.remember!.handler(s.local, { fact: 'Erin Example agreed to the term sheet', entity: 'people/erin-example',
        provenance: 'synthetic test', infer_entity: false }) as { id: string };
      expect((await engine.executeRaw<{ visibility: string }>('SELECT visibility FROM facts WHERE id=$1', [Number(saved.id)]))[0]!.visibility).toBe('private');
      await putAliased(engine, s.sourceId, 'meetings/session-example', 'meeting', { access: 'restricted' }, BODY);
      stubExtraction(CLAIM);
      await operationsByName.extract_facts!.handler(s.local, { turn_text: BODY, visibility: 'world', source_slug: 'meetings/session-example' });
      expect((await factRows(engine, s.sourceId)).find(r => r.fact === CLAIM)?.visibility).toBe('private');
    });
  }, 120_000);

  test('remote page reads hide alias-private pages by default; local reads are unchanged; honor_aliases false opts out', async () => {
    await onEachEngine(async engine => {
      const s = await source(engine, false);
      __resetPrivateVisibilityCacheForTests();
      await putAliased(engine, s.sourceId, 'meetings/aliased-example', 'meeting', { access: 'private' }, 'Zephyrquill synthetic agenda.');
      await putAliased(engine, s.sourceId, 'meetings/open-example', 'meeting', { access: 'public' }, 'Zephyrquill open agenda.');
      const read = (ctx: OperationContext, slug: string) => operationsByName.get_page!.handler(ctx, { slug }).then(() => true, () => false);
      const found = async (ctx: OperationContext) => {
        const listed = await operationsByName.list_pages!.handler(ctx, { type: 'meeting' }) as unknown;
        const rows = (Array.isArray(listed) ? listed : (listed as { pages: unknown[] }).pages) as Array<{ slug: string }>;
        return rows.map(row => row.slug).filter(slug => slug.startsWith('meetings/')).sort();
      };
      expect(await read(s.remote, 'meetings/aliased-example')).toBe(false);
      expect(await read(s.remote, 'meetings/open-example')).toBe(true);
      expect(await found(s.remote)).toEqual(['meetings/open-example']);
      expect(await read(s.local, 'meetings/aliased-example')).toBe(true);
      expect(await found(s.local)).toEqual(['meetings/aliased-example', 'meetings/open-example']);
      await engine.setConfig('visibility.honor_aliases', 'false');
      __resetPrivateVisibilityCacheForTests();
      try {
        expect(await read(s.remote, 'meetings/aliased-example')).toBe(true);
        expect(await found(s.remote)).toEqual(['meetings/aliased-example', 'meetings/open-example']);
      } finally { await engine.executeRaw("DELETE FROM config WHERE key='visibility.honor_aliases'"); __resetPrivateVisibilityCacheForTests(); }
      expect(await read(s.remote, 'meetings/aliased-example')).toBe(false);
    });
  }, 120_000);
});

describe('already-affected rows: listed by doctor, previewed by the repair, changed only with --apply', () => {
  test('aliased page, its world chronicle event and a world fact extracted from it', async () => {
    await onEachEngine(async engine => {
      const s = await source(engine, false);
      const meeting = 'meetings/aliased-session-example';
      await engine.transaction(tx => withCoordinatedWrite(tx, [s.sourceId], async () => {
        await tx.putPage(meeting, { type: 'meeting', title: 'Session', compiled_truth: 'A session.', timeline: '', frontmatter: { access: 'private' } }, { sourceId: s.sourceId });
        await tx.putPage('chronicle/2026/10/session-example', { type: 'event', title: 'Session', compiled_truth: 'A session.', timeline: '',
          frontmatter: { captured_via: 'life-chronicle:auto', visibility: 'world', event: { depth: meeting } } }, { sourceId: s.sourceId });
      }, TEST_WRITE_ATTRIBUTION));
      const [fact] = await engine.executeRaw<{ id: number }>(`INSERT INTO facts (source_id, fact, kind, entity_slug, visibility, source, context, valid_from)
        VALUES ($1, $2, 'fact', $3, 'world', 'mcp:put_page', $4, now()) RETURNING id`, [s.sourceId, CLAIM, PERSON, meeting]);
      expect(await remoteReadable(s.remote)).toContain(CLAIM);

      const check = await derivedVisibilityCheck(engine, s.sourceId);
      expect(check.status).toBe('warn');
      expect(check.details).toMatchObject({ alias_pages_without_visibility: 1, looser_events: 1, world_facts_from_private_sources: 1,
        world_facts_remotely_readable: 1, remotely_readable_fact_ids: [String(fact!.id)] });
      expect(check.message).not.toContain(meeting);
      expect(check.message).toContain('Remote page reads hide them (to show them: gbrain config set visibility.honor_aliases false).');

      const home = mkdtempSync(join(tmpdir(), 'gbrain-visibility-repair-'));
      try {
        await withEnv({ GBRAIN_HOME: home }, async () => {
          const ctx = { ...s.local, config: { engine: engine.kind, embedding_disabled: true } } as OperationContext;
          const scope = await resolveRepairScope(engine, s.sourceId);
          const preview = await runRepair(ctx, visibilityRepair, scope, { apply: false });
          expect(preview.affected).toBe(3);
          expect((await engine.executeRaw<{ visibility: string }>('SELECT visibility FROM facts WHERE id=$1', [fact!.id]))[0]!.visibility).toBe('world');
          expect((await engine.readPageSnapshot(meeting, { sourceId: s.sourceId }))!.page.frontmatter.visibility).toBeUndefined();
          const applied = await runRepair(ctx, visibilityRepair, scope, { apply: true });
          expect(applied).toMatchObject({ applied: 3, complete: true });
        });
      } finally { rmSync(home, { recursive: true, force: true }); }
      expect((await engine.readPageSnapshot(meeting, { sourceId: s.sourceId }))!.page.frontmatter.visibility).toBe('private');
      expect((await engine.readPageSnapshot('chronicle/2026/10/session-example', { sourceId: s.sourceId }))!.page.frontmatter.visibility).toBe('private');
      expect((await engine.executeRaw<{ visibility: string }>('SELECT visibility FROM facts WHERE id=$1', [fact!.id]))[0]!.visibility).toBe('private');
      expect(await remoteReadable(s.remote)).not.toContain(CLAIM);
      expect((await derivedVisibilityCheck(engine, s.sourceId)).status).toBe('ok');
    });
  }, 120_000);
});

describe('connector pages keep a private label', () => {
  const event: CalendarEventData = { id: 'ev-example', summary: 'Private appointment', description: '', startIso: '2026-10-01T10:00:00Z',
    endIso: '2026-10-01T11:00:00Z', allDay: false, organizer: null, attendees: [], location: null, hangoutLink: null, htmlLink: null,
    status: 'confirmed', account: '[email protected]' };

  test('a Google private event renders visibility: private; a default one renders no label', () => {
    expect(renderCalendarEventPage({ ...event, private: true })!.markdown).toContain('\nvisibility: private\n---');
    expect(renderCalendarEventPage(event)!.markdown).not.toContain('visibility:');
    expect(withPrivateVisibility('---\ntitle: x\nvisibility: world\n---\n\nbody\n')).toBe('---\ntitle: x\nvisibility: private\n---\n\nbody\n');
  });

  test('a re-render of a page the owner made private keeps it private (tighten-only)', async () => {
    await onEachEngine(async engine => {
      const s = await source(engine, false);
      const dir = mkdtempSync(join(tmpdir(), 'gbrain-connector-'));
      try {
        const deps = { engine, sourceId: s.sourceId, cfg: { account: '[email protected]', dir }, opts: {}, log() {}, tick() {} } as never;
        const summary = { pagesAffected: [], chunksCreated: 0, added: 0, modified: 0 } as never;
        const rendered = renderCalendarEventPage(event)!;
        const slug = (await importRendered(deps, rendered.relPath, rendered.markdown, undefined as never, summary, new Set()))!;
        const page = (await engine.readPageSnapshot(slug, { sourceId: s.sourceId }))!.page;
        expect(page.frontmatter.visibility).toBeUndefined();
        await engine.transaction(tx => withCoordinatedWrite(tx, [s.sourceId], () => tx.putPage(slug, { ...page, frontmatter: { ...page.frontmatter, visibility: 'private' } },
          { sourceId: s.sourceId }), TEST_WRITE_ATTRIBUTION));
        const moved = renderCalendarEventPage({ ...event, summary: 'Private appointment (moved)' })!;
        await importRendered(deps, rendered.relPath, moved.markdown, undefined as never, summary, new Set());
        const after = (await engine.readPageSnapshot(slug, { sourceId: s.sourceId }))!.page;
        expect(after.title).toBe('Private appointment (moved)');
        expect(after.frontmatter.visibility).toBe('private');
      } finally { rmSync(dir, { recursive: true, force: true }); }
    });
  }, 120_000);
});

describe('the segmented-entity retry keeps the original call', () => {
  test('its fix carries the resolved visibility, kind and ttl; without them visibility is an input, never the world default', () => {
    const carried = segmentedRememberRefusal(PRIVATE_PERSON, 'default', false, { visibility: 'private', kind: 'preference', ttl: '30d' }).fix!;
    expect(carried.mcp!.arguments).toMatchObject({ visibility: 'private', kind: 'preference', ttl: '30d', infer_entity: false });
    expect(carried.argv).toEqual(expect.arrayContaining(['--visibility', 'private']));
    const bare = segmentedRememberRefusal(PRIVATE_PERSON, 'default', false).fix!;
    expect(bare.mcp!.arguments).toMatchObject({ visibility: '<VISIBILITY>' });
    expect(bare.inputs!.map(i => i.name)).toContain('VISIBILITY');
  });
});