Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
22.7 KB
Raw Blame
/**
 * Conversation archive pages written while a brain was personal name no readers. The commands that turn the brain
 * shared (gbrain access member add and member enable to a second enabled member, gbrain config set brain.audience
 * shared, gbrain access owner set on a shared brain) keep those pages to the owner at once, so a second member never
 * reads them remotely in the window before the next archive run or maintenance pass (maintenance.auto is off here).
 * Each case drives the brain shared through the CLI handler alone, then reads over the http dispatch as the second
 * member, as the owner and with an unbound token. In the owner set case the second member is added first on a brain
 * with no owner, so member add says why the pages wait (archive_rescope_owner_unset) and owner set applies it.
 * A member add while an archive run holds the source keeps the pages archived so far to the owner at once and leaves the
 * audience recorded personal, so the source's next run re-scopes what the run in flight wrote with no readers. Repo-less; synthetic values only.
 */
import { afterAll, beforeAll, describe, expect, spyOn, test } from 'bun:test';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { configureGateway, resetGateway, __setEmbedTransportForTests } from '../src/core/ai/gateway.ts';
import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';
import { sqlQueryForEngine } from '../src/core/sql-query.ts';
import { mintLegacyToken } from '../src/core/token-mint.ts';
import { noGrantFederatedScope } from '../src/core/source-resolver.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
import { addMember, bindCredential, disableMember, getMember } from '../src/core/access/members.ts';
import * as policy from '../src/core/access/policy.ts';
import { setOwner } from '../src/core/access/owner.ts';
import { tryAcquireDbLock } from '../src/core/db-lock.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { ARCHIVE_TIMEZONE_KEY, archiveRescopeSkipped, runTranscriptArchive, setArchiveEnabled } from '../src/core/transcripts/archive.ts';
import { runAccess } from '../src/commands/access.ts';
import { runConfig } from '../src/commands/config.ts';
import type { AuthInfo } from '../src/core/ops/contract.ts';
import { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
import { emptyHome, withEnv } from './helpers/with-env.ts';
import { archivedPages, conversation, staticReader } from './helpers/transcript-archive.ts';

const SRC = 'conversations';
const OWNER = 'alice-example';
const OTHER = 'bob-example';
const CANARIES = ['canaryharborqzx', 'canaryledgerwvk'] as const;
/** Words only the page body or its derived fact holds, never a query, so an echoed query is never read as a leak. */
const BODY_ONLY = { canaryharborqzx: 'bodyonlyharborjtq', canaryledgerwvk: 'bodyonlyledgerpfn' } as const;
const FACT_ONLY = { canaryharborqzx: 'factonlyharborxkd', canaryledgerwvk: 'factonlyledgerhmz' } as const;
const DIMS = 1536;

function vectorFor(text: string): number[] {
  const v = new Array<number>(DIMS).fill(0);
  for (const w of text.toLowerCase().match(/[a-z]+/g) ?? []) {
    let h = 0;
    for (const ch of w) h = (h * 31 + ch.charCodeAt(0)) >>> 0;
    v[h % DIMS] += 1;
  }
  const n = Math.hypot(...v) || 1;
  return v.map(x => x / n);
}

const readsFor = (slug: string, canary: string): Array<[string, string, Record<string, unknown>]> => [
  ['get_page', 'get_page', { slug }],
  ['search keyword', 'search', { query: canary, match: 'keyword', fields: 'full', limit: 20 }],
  ['search hybrid', 'search', { query: 'planning notes ' + canary, fields: 'full', limit: 20 }],
  ['query', 'query', { query: 'planning notes ' + canary, expand: false, fields: 'full', limit: 20 }],
  ['recall (newest)', 'recall', { query: 'planning notes' }],
  ['recall (since)', 'recall', { since: '2000-01-01' }],
];

type Trigger = 'member add' | 'member enable' | 'config set brain.audience' | 'owner set' | 'member add during an archive run';
const TRIGGERS: Trigger[] = ['member add', 'member enable', 'config set brain.audience', 'owner set', 'member add during an archive run'];

for (const kind of testBackends()) {
  for (const trigger of TRIGGERS) {
    describe('archive pages turn owner-only when ' + trigger + ' makes the brain shared (' + kind + ')', () => {
      let engine: BrainEngine;
      let close: () => Promise<void>;
      const home = emptyHome();
      const pages: Array<{ slug: string; canary: typeof CANARIES[number] }> = [];
      const tokens: Record<string, string> = {};
      const ownerBefore: Record<string, boolean> = {};
      const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
      const inHome = <T>(fn: () => Promise<T>) => withEnv({ GBRAIN_HOME: home }, fn);

      async function bind(name: string, member: string | null): Promise<void> {
        const minted = await mintLegacyToken(engine, { name: 'tok-' + name, scopes: ['read'], takesHolders: ['world'], sourceGrant: [SRC] });
        tokens[name] = minted.token;
        if (member) await bindCredential(engine, { kind: 'token', id: minted.id }, { member });
      }

      async function reads(who: string, canary: typeof CANARIES[number], op: string, params: Record<string, unknown>): Promise<boolean> {
        const auth = await provider().verifyAccessToken(tokens[who]!) as unknown as AuthInfo;
        const sourceId = auth.sourceId ?? 'default';
        const localFederated = await noGrantFederatedScope(engine, auth.hasSourceGrant, sourceId);
        const out = await dispatchToolCall(engine, op, { ...params }, {
          remote: true, transport: 'http', auth, sourceId, takesHoldersAllowList: auth.takesHoldersAllowList ?? ['world'],
          ...(localFederated ? { localFederatedSourceIds: localFederated } : {}),
        });
        const text = out.content.map(c => c.text ?? '').join('\n');
        return text.includes(BODY_ONLY[canary]) || text.includes(FACT_ONLY[canary]);
      }

      async function readMatrix(who: string): Promise<Record<string, boolean>> {
        __resetPrivateVisibilityCacheForTests();
        const out: Record<string, boolean> = {};
        for (const { slug, canary } of pages) {
          for (const [label, op, params] of readsFor(slug, canary)) out[canary + ' ' + label] = await reads(who, canary, op, params);
        }
        return out;
      }

      beforeAll(async () => {
        configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: DIMS, env: { OPENAI_API_KEY: 'test' } });
        __setEmbedTransportForTests((async ({ values }: { values: string[] }) => ({ embeddings: values.map(vectorFor) })) as never);
        if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
        else { engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema(); close = () => engine.disconnect(); }
        __resetPrivateVisibilityCacheForTests();
        await engine.setConfig('maintenance.auto', 'false');
        await engine.setConfig(ARCHIVE_TIMEZONE_KEY, 'UTC');
        await setArchiveEnabled(engine, true);

        await addMember(engine, OWNER);
        if (trigger === 'member enable') { await addMember(engine, OTHER); await disableMember(engine, OTHER); }
        if (trigger !== 'owner set') await setOwner(engine, OWNER);

        const reader = staticReader('openclaw', [
          conversation('openclaw', 'agent:main:main', [['user', '2026-10-01T10:00:00.000Z', 'harbor planning notes ' + CANARIES[0] + ' private ' + BODY_ONLY[CANARIES[0]]]], { chatType: 'direct', verified: true }),
          conversation('openclaw', 'agent:main:other', [['user', '2026-10-02T10:00:00.000Z', 'ledger planning notes ' + CANARIES[1] + ' private ' + BODY_ONLY[CANARIES[1]]]], { chatType: 'direct', verified: true }),
        ]);
        const first = await inHome(() => runTranscriptArchive(engine, { mode: 'backfill', from: '2026-10-01', to: '2026-10-02', readers: [reader], now: new Date('2026-10-05T00:00:00Z') }));
        expect(first.privacy).toBe('personal');
        const archived = await archivedPages(engine, SRC);
        for (const canary of CANARIES) {
          const page = archived.find(p => p.body.includes(canary));
          expect(page?.frontmatter.readable_by).toBeUndefined();
          pages.push({ slug: page!.slug, canary });
          await engine.insertFact({ fact: 'planning notes ' + FACT_ONLY[canary], kind: 'fact', source: 'test', visibility: 'world' }, { source_id: SRC });
          await engine.executeRaw('UPDATE facts SET source_markdown_slug = $1 WHERE fact LIKE $2', [page!.slug, '%' + FACT_ONLY[canary]]);
        }

        await bind('owner', OWNER);
        if (trigger !== 'owner set') Object.assign(ownerBefore, await readMatrix('owner'));

        await inHome(async () => {
          if (trigger === 'member add') await runAccess(engine, ['member', 'add', OTHER]);
          if (trigger === 'member add during an archive run') {
            const lock = await tryAcquireDbLock(engine, 'transcripts-archive:' + SRC);
            const stderr: string[] = [];
            const spy = spyOn(console, 'error').mockImplementation((...line: unknown[]) => { stderr.push(line.join(' ')); });
            try { await runAccess(engine, ['member', 'add', OTHER]); } finally { spy.mockRestore(); await lock!.release(); }
            expect(stderr.join('\n')).toContain('pages archived so far are kept to the owner, but an archive run that started while this brain was personal is writing source ' + SRC + ' now');
          }
          if (trigger === 'member enable') await runAccess(engine, ['member', 'enable', OTHER]);
          if (trigger === 'config set brain.audience') await runConfig(engine, ['set', 'brain.audience', 'shared']);
          if (trigger === 'owner set') {
            const stderr: string[] = [];
            const spy = spyOn(console, 'error').mockImplementation((...line: unknown[]) => { stderr.push(line.join(' ')); });
            try { await runAccess(engine, ['member', 'add', OTHER]); } finally { spy.mockRestore(); }
            expect(stderr.join('\n')).toContain('the shared brain names no owner; run gbrain access owner set <member>, which applies the owner-only rules at once.');
            expect(await archiveRescopeSkipped(engine)).toMatchObject({ code: 'archive_rescope_owner_unset' });
            await runAccess(engine, ['owner', 'set', OWNER]);
          }
        });
        if (trigger === 'config set brain.audience') await addMember(engine, OTHER);
        await bind('other', OTHER);
        await bind('unbound', null);
      }, 240_000);

      afterAll(async () => {
        __setEmbedTransportForTests(null);
        resetGateway();
        await disposePersistenceConsumer(engine).catch(() => {});
        await close?.();
      }, 60_000);

      test('the re-scope has run: nothing pending and the archive records the brain as shared', async () => {
        if (trigger === 'member add during an archive run') {
          expect(await inHome(() => archiveRescopeSkipped(engine))).toMatchObject({ code: 'archive_rescope_pending' });
          expect(await engine.getConfig('transcripts.archive.audience.' + SRC)).toBe('personal');
          return;
        }
        expect(await inHome(() => archiveRescopeSkipped(engine))).toBeNull();
        expect(await engine.getConfig('transcripts.archive.audience.' + SRC)).toBe('shared');
      }, 60_000);

      test('the second member reads nothing from the personal-era pages through get_page, search, query or recall', async () => {
        const matrix = await readMatrix('other');
        expect(Object.entries(matrix).filter(([, read]) => read).map(([k]) => k)).toEqual([]);
        expect(Object.keys(matrix)).toHaveLength(CANARIES.length * 6);
      }, 240_000);

      test('a token bound to no member reads nothing from them either', async () => {
        const matrix = await readMatrix('unbound');
        expect(Object.entries(matrix).filter(([, read]) => read).map(([k]) => k)).toEqual([]);
      }, 240_000);

      test('the owner reads every archive page through every path, before and after', async () => {
        const after = await readMatrix('owner');
        expect(Object.entries(after).filter(([, read]) => !read).map(([k]) => k)).toEqual([]);
        if (trigger !== 'owner set') expect(ownerBefore).toEqual(after);
      }, 240_000);

      if (trigger === 'member add during an archive run') {
        test('the next archive run finishes the re-scope, and the second member still reads nothing', async () => {
          await inHome(() => runTranscriptArchive(engine, { mode: 'run', readers: [staticReader('openclaw', [])], now: new Date('2026-10-05T00:00:00Z') }));
          expect(await inHome(() => archiveRescopeSkipped(engine))).toBeNull();
          expect(await engine.getConfig('transcripts.archive.audience.' + SRC)).toBe('shared');
          const matrix = await readMatrix('other');
          expect(Object.entries(matrix).filter(([, read]) => read).map(([k]) => k)).toEqual([]);
        }, 240_000);
      }
    });
  }
}

/**
 * Order: access member add (--bind-token) and member enable keep the personal-era pages to the owner before the member
 * is added, enabled or bound, so its credentials never read them; a re-scope that throws leaves the member not enabled
 * and the token not bound. proposeRevision is the step that writes the owner-only rules.
 */
class Exited extends Error {}

for (const kind of testBackends()) {
  for (const door of ['member add --bind-token', 'member enable'] as const) {
    for (const mode of ['rules before the member', 'a failed re-scope changes nothing'] as const) {
      describe('archive re-scope order: ' + door + ', ' + mode + ' (' + kind + ')', () => {
        let engine: BrainEngine;
        let close: () => Promise<void>;
        let tokenId = '';
        const home = emptyHome();

        beforeAll(async () => {
          if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
          else { engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema(); close = () => engine.disconnect(); }
          await engine.setConfig('maintenance.auto', 'false');
          await engine.setConfig(ARCHIVE_TIMEZONE_KEY, 'UTC');
          await setArchiveEnabled(engine, true);
          await addMember(engine, OWNER);
          await setOwner(engine, OWNER);
          const reader = staticReader('openclaw', [conversation('openclaw', 'agent:main:main', [['user', '2026-10-01T10:00:00.000Z', 'harbor planning notes ' + CANARIES[0]]], { chatType: 'direct', verified: true })]);
          await withEnv({ GBRAIN_HOME: home }, () => runTranscriptArchive(engine, { mode: 'backfill', from: '2026-10-01', to: '2026-10-01', readers: [reader], now: new Date('2026-10-05T00:00:00Z') }));
          const minted = await mintLegacyToken(engine, { name: 'tok-other', scopes: ['read'], takesHolders: ['world'], sourceGrant: [SRC] });
          tokenId = minted.id;
          if (door === 'member enable') {
            await addMember(engine, OTHER);
            await bindCredential(engine, { kind: 'token', id: minted.id }, { member: OTHER });
            await disableMember(engine, OTHER);
          }
        }, 240_000);

        afterAll(async () => {
          await disposePersistenceConsumer(engine).catch(() => {});
          await close?.();
        }, 60_000);

        const boundTo = async () => (await engine.executeRaw<{ member_id: string | null }>('SELECT member_id FROM access_tokens WHERE id::text = $1', [tokenId]))[0]?.member_id ?? null;
        const argv = door === 'member enable' ? ['member', 'enable', OTHER] : ['member', 'add', OTHER, '--bind-token', 'tok-other'];

        test(mode, async () => {
          const original = policy.proposeRevision;
          const seen: Array<{ status: string | null; bound: string | null }> = [];
          const revision = spyOn(policy, 'proposeRevision').mockImplementation((async (...a: Parameters<typeof original>) => {
            seen.push({ status: (await getMember(engine, OTHER))?.status ?? null, bound: await boundTo() });
            if (mode === 'a failed re-scope changes nothing') throw new Error('rule store unavailable');
            return original(...a);
          }) as typeof original);
          const exit = spyOn(process, 'exit').mockImplementation(((code?: number) => { throw new Exited(String(code)); }) as never);
          const stderr = spyOn(console, 'error').mockImplementation(() => {});
          let exited: unknown = null;
          try {
            await withEnv({ GBRAIN_HOME: home }, () => runAccess(engine, argv));
          } catch (e) {
            exited = e;
          } finally {
            revision.mockRestore();
            exit.mockRestore();
            stderr.mockRestore();
          }
          expect(seen.length).toBeGreaterThan(0);
          expect(seen[0]).toEqual(door === 'member enable' ? { status: 'disabled', bound: OTHER } : { status: null, bound: null });
          if (mode === 'rules before the member') {
            expect(exited).toBeNull();
            expect((await getMember(engine, OTHER))?.status).toBe('enabled');
            expect(await boundTo()).toBe(OTHER);
            expect(await withEnv({ GBRAIN_HOME: home }, () => archiveRescopeSkipped(engine))).toBeNull();
            return;
          }
          expect(exited).toBeInstanceOf(Exited);
          expect((exited as Exited).message).not.toBe('0');
          expect((await getMember(engine, OTHER))?.status ?? null).toBe(door === 'member enable' ? 'disabled' : null);
          expect(await boundTo()).toBe(door === 'member enable' ? OTHER : null);
          expect(await engine.getConfig('transcripts.archive.audience.' + SRC)).toBe('personal');
        }, 240_000);
      });
    }
  }
}

/**
 * A member add that its own input checks refuse (a bad --kind, a malformed --email, an ill-formed group) changes nothing:
 * the access rules, the archive pages, the members table and an unbound token's archive reads stay exactly as they were,
 * because addMember runs the re-scope (beforeWrite) only after every input check has passed.
 */
for (const kind of testBackends()) {
  for (const [reason, extra] of [['a bad --kind', ['--kind', 'typo']], ['a malformed --email', ['--email', 'not-an-email']], ['an ill-formed group', ['--groups', 'Bad Group!']]] as const) {
    describe('a refused member add changes nothing: ' + reason + ' (' + kind + ')', () => {
      let engine: BrainEngine;
      let close: () => Promise<void>;
      let token = '';
      let slug = '';
      const home = emptyHome();
      const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });

      async function unboundReads(): Promise<Record<string, boolean>> {
        __resetPrivateVisibilityCacheForTests();
        const auth = await provider().verifyAccessToken(token) as unknown as AuthInfo;
        const sourceId = auth.sourceId ?? 'default';
        const localFederated = await noGrantFederatedScope(engine, auth.hasSourceGrant, sourceId);
        const out: Record<string, boolean> = {};
        for (const [label, op, params] of readsFor(slug, CANARIES[0]).filter(([l]) => l === 'get_page' || l === 'search keyword')) {
          const res = await dispatchToolCall(engine, op, { ...params }, {
            remote: true, transport: 'http', auth, sourceId, takesHoldersAllowList: auth.takesHoldersAllowList ?? ['world'],
            ...(localFederated ? { localFederatedSourceIds: localFederated } : {}),
          });
          out[label] = res.content.map(c => c.text ?? '').join('\n').includes(BODY_ONLY[CANARIES[0]]);
        }
        return out;
      }

      const snapshot = async () => ({
        rules: JSON.stringify(await policy.appliedRules(engine, SRC)),
        pages: await engine.executeRaw<{ j: string }>("SELECT row_to_json(p)::text AS j FROM pages p WHERE slug LIKE 'conversations/%' ORDER BY slug"),
        members: await engine.executeRaw<{ j: string }>('SELECT row_to_json(m)::text AS j FROM access_members m ORDER BY id'),
        audience: await engine.getConfig('transcripts.archive.audience.' + SRC),
        reads: await unboundReads(),
      });

      beforeAll(async () => {
        if (kind === 'postgres') ({ engine, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!));
        else { engine = new PGLiteEngine(); await engine.connect({ engine: 'pglite' } as never); await engine.initSchema(); close = () => engine.disconnect(); }
        __resetPrivateVisibilityCacheForTests();
        await engine.setConfig('maintenance.auto', 'false');
        await engine.setConfig(ARCHIVE_TIMEZONE_KEY, 'UTC');
        await setArchiveEnabled(engine, true);
        await addMember(engine, OWNER);
        await setOwner(engine, OWNER);
        const reader = staticReader('openclaw', [conversation('openclaw', 'agent:main:main', [['user', '2026-10-01T10:00:00.000Z', 'harbor planning notes ' + CANARIES[0] + ' private ' + BODY_ONLY[CANARIES[0]]]], { chatType: 'direct', verified: true })]);
        await withEnv({ GBRAIN_HOME: home }, () => runTranscriptArchive(engine, { mode: 'backfill', from: '2026-10-01', to: '2026-10-01', readers: [reader], now: new Date('2026-10-05T00:00:00Z') }));
        slug = (await archivedPages(engine, SRC)).find(pg => pg.body.includes(CANARIES[0]))!.slug;
        token = (await mintLegacyToken(engine, { name: 'tok-unbound', scopes: ['read'], takesHolders: ['world'], sourceGrant: [SRC] })).token;
      }, 240_000);

      afterAll(async () => {
        await disposePersistenceConsumer(engine).catch(() => {});
        await close?.();
      }, 60_000);

      test('the rules, the archive pages, the members and an unbound token\'s reads stay as they were', async () => {
        const before = await snapshot();
        expect(before.audience).toBe('personal');
        const exit = spyOn(process, 'exit').mockImplementation(((code?: number) => { throw new Exited(String(code)); }) as never);
        const stderr = spyOn(console, 'error').mockImplementation(() => {});
        let exited: unknown = null;
        try {
          await withEnv({ GBRAIN_HOME: home }, () => runAccess(engine, ['member', 'add', OTHER, ...extra]));
        } catch (e) {
          exited = e;
        } finally {
          exit.mockRestore();
          stderr.mockRestore();
        }
        expect(exited).toBeInstanceOf(Exited);
        expect((exited as Exited).message).not.toBe('0');
        expect(await getMember(engine, OTHER)).toBeNull();
        expect(await snapshot()).toEqual(before);
      }, 240_000);
    });
  }
}