Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.8 KB
Raw Blame
/**
 * GST-2243: a member's remember stays private by default, and share: true saves the fact for every reader of the source.
 *
 * 1. Protects: a member-bound credential's fact saved with share: true lands world on the subject's page and another
 *    member recalls it; one saved without share stays on the saver's member page, recalled by the saver alone; every
 *    reply names the page and visibility; an explicit visibility "world" from a member is refused (member_share_required)
 *    instead of being made private; QM's attested memory_write, which passes no share, still saves on the member page.
 * 2. Fails when: share is ignored, a member's world request is silently overridden, the reply hides where the fact
 *    went, or memory_write's per-person contract moves.
 * 3. Existing coverage: test/access-member-facts.test.ts (GST-359 C2) pins the private default.
 * 4. Real seams: OAuth client-credentials tokens bound to members, MCP dispatch as remote callers, a repo-less brain.
 */
import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import type { BrainEngine } from '../src/core/engine.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { importFromContent } from '../src/core/import-file.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 { dispatchToolCall, type ToolResult } from '../src/mcp/dispatch.ts';
import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
import { __resetHotMemoryCacheForTests, getBrainHotMemoryMeta } from '../src/core/facts/meta-hook.ts';
import { addMember, bindCredential } from '../src/core/access/members.ts';
import { prepareMemoryMutation } from '../src/core/persistence/memory-prepare.ts';
import { linkMember } from '../src/core/access/actor.ts';
import type { AuthInfo } from '../src/core/ops/contract.ts';
import { ambientOptsFrom, writebackCaller } from '../src/core/facts/writeback-config.ts';
import { buildAmbientWritebackSection } from '../src/core/facts/writeback-instructions.ts';
import { testBackends } from './helpers/test-backends.ts';
import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';

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 SRC = 'qm-members';
const ALICE_ID = 'U0ALICE';
const BOB_ID = '[email protected]';
const ACME = 'companies/acme-example';
const TEAM_PAGE = 'companies/globex-example';
const ATTEST_OPS = ['memory_write', 'cancel_write_request', 'context_pack', 'delta', 'get_page', 'get_write_request', 'list_write_requests', 'recall', 'remember', 'search', 'whoami'];

for (const kind of testBackends()) {
  describe('remember share for member credentials (' + kind + ', repo-less)', () => {
    let engine: BrainEngine;
    let close: () => Promise<void>;
    const provider = () => new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
    const tokens: Record<string, string> = {};
    const verify = async (bearer: string) => await provider().verifyAccessToken(bearer) as unknown as AuthInfo;

    type Who = { token: string; actor?: string };
    const who = {
      alice: (): Who => ({ token: 'qm', actor: ALICE_ID }),
    };
    async function call(as: Who, op: string, params: Record<string, unknown>, extra: { sessionId?: string } = {}) {
      const out: ToolResult = await dispatchToolCall(engine, op, { ...params }, {
        remote: true, transport: 'http', auth: await verify(tokens[as.token]!), sourceId: SRC, takesHoldersAllowList: ['world'],
        ...(as.actor !== undefined ? { actor: { header: as.actor } } : {}),
        ...(extra.sessionId ? { sessionId: extra.sessionId } : {}),
        metaHook: (name, ctx) => getBrainHotMemoryMeta(name, ctx),
      });
      const text = out.content.map(c => c.text).join('\n');
      let json: Record<string, any> = {};
      try { json = JSON.parse(text); } catch { /* prose */ }
      return { isError: out.isError === true, text, json, meta: out._meta, all: text + JSON.stringify(out._meta ?? {}) + JSON.stringify(out.structuredContent ?? {}) };
    }
    const remember = (as: Who, fact: string, extra: Record<string, unknown> = {}) => call(as, 'remember', { fact, provenance: 'qm test', ...extra });

    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();
      __resetHotMemoryCacheForTests();
      await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1) ON CONFLICT (id) DO NOTHING', [SRC]);
      for (const id of ['alice-example', 'bob-example']) await addMember(engine, id);
      await importFromContent(engine, ACME, '---\ntype: company\ntitle: Acme Example\n---\n# Acme Example\n\nAcme example builds harbor ledgers.', { sourceId: SRC });
      await importFromContent(engine, TEAM_PAGE, '---\ntype: company\ntitle: Globex Example\nreadable_by: [alice-example]\n---\n# Globex Example\n\nGlobex example runs a private pilot.', { sourceId: SRC });
      const register = async (name: string) => {
        const c = await provider().registerClientManual('c2-' + name + '-' + randomUUID().slice(0, 8), ['client_credentials'], 'read write', [], SRC);
        return { id: c.clientId, secret: c.clientSecret ?? '' };
      };
      const qm = await register('qm');
      await bindCredential(engine, { kind: 'client', id: qm.id }, { attestActor: 'qm', attestOps: ATTEST_OPS, readsUnscoped: true });
      const alice = await register('alice');
      await bindCredential(engine, { kind: 'client', id: alice.id }, { member: 'alice-example' });
      const bob = await register('bob');
      await bindCredential(engine, { kind: 'client', id: bob.id }, { member: 'bob-example' });
      const plain = await register('plain');
      await bindCredential(engine, { kind: 'client', id: plain.id }, { readsUnscoped: true });
      for (const [name, c] of [['qm', qm], ['alice', alice], ['bob', bob], ['plain', plain]] as const) tokens[name] = (await provider().exchangeClientCredentials(c.id, c.secret)).access_token;
      await linkMember(engine, 'alice-example', 'qm', ALICE_ID);
      await linkMember(engine, 'bob-example', 'qm', BOB_ID);
    }, 120_000);

    afterAll(async () => { __setEmbedTransportForTests(null); resetGateway(); await close?.(); });
    const A = { token: 'alice' }, B = { token: 'bob' }, U = { token: 'plain' };
    const factRow = async (canary: string) => (await engine.executeRaw<Record<string, unknown>>('SELECT visibility, source_markdown_slug, entity_slug FROM facts WHERE fact LIKE $1', ['%' + canary + '%']))[0];

    test('share: true lands world on the subject page and another member recalls it; without share it stays private to the saver', async () => {
      const shared = await remember(A, 'Acme renewed for 40 seats canarysharedfact', { entity: ACME, share: true });
      const kept = await remember(A, 'Acme renewal worried me canarykeptfact', { entity: ACME });
      expect([shared.isError, shared.json.page, shared.json.visibility]).toEqual([false, ACME, 'world']);
      expect([kept.isError, kept.json.page, kept.json.visibility]).toEqual([false, 'memory/members/alice-example', 'private']);
      expect(await factRow('canarysharedfact')).toMatchObject({ visibility: 'world', source_markdown_slug: ACME, entity_slug: ACME });
      expect(await factRow('canarykeptfact')).toMatchObject({ visibility: 'private', source_markdown_slug: 'memory/members/alice-example', entity_slug: ACME });
      for (const params of [{ query: 'Acme renewed seats' }, { entity: ACME }]) {
        const b = await call(B, 'recall', params);
        expect([b.all.includes('canarysharedfact'), b.all.includes('canarykeptfact')]).toEqual([true, false]);
        const u = await call(U, 'recall', params);
        expect([u.all.includes('canarysharedfact'), u.all.includes('canarykeptfact')]).toEqual([true, false]);
        const a = await call(A, 'recall', params);
        expect([a.all.includes('canarysharedfact'), a.all.includes('canarykeptfact')]).toEqual([true, true]);
      }
    }, 120_000);

    test('a member asking for visibility "world" is refused with member_share_required and nothing is saved; share with visibility "private" is refused', async () => {
      const world = await remember(A, 'Acme asked for SSO canaryworldrefused', { entity: ACME, visibility: 'world' });
      expect(world.isError).toBe(true);
      expect(world.all).toContain('member_share_required');
      expect(world.all).toContain('pass share: true');
      const both = await remember(A, 'Acme wants invoices canaryboth', { entity: ACME, share: true, visibility: 'private' });
      expect([both.isError, both.all.includes('invalid_params')]).toEqual([true, true]);
      expect(await factRow('canaryworldrefused')).toBeUndefined();
      expect(await factRow('canaryboth')).toBeUndefined();
      const own = await remember(A, 'Acme note canaryownprivate', { entity: ACME, visibility: 'private' });
      expect([own.isError, own.json.page, own.json.visibility]).toEqual([false, 'memory/members/alice-example', 'private']);
    }, 120_000);

    test('share onto a page whose facts are kept private is refused with share_target_restricted and nothing is saved', async () => {
      const out = await remember(A, 'Globex pilot ends in March canaryrestricted', { entity: TEAM_PAGE, share: true });
      expect(out.isError).toBe(true);
      expect(out.all).toContain('share_target_restricted');
      expect(await factRow('canaryrestricted')).toBeUndefined();
      const explicitWorld = await remember(U, 'Globex pilot ends in May canaryrestrictedworld', { entity: TEAM_PAGE, share: true, visibility: 'world' });
      expect(explicitWorld.isError).toBe(true);
      expect(await factRow('canaryrestrictedworld')).toBeUndefined();
      const [page] = await engine.executeRaw<{ id: number }>('SELECT id FROM pages WHERE source_id = $1 AND slug = $2', [SRC, TEAM_PAGE]);
      const row = { operation: 'remember', request_id: 'gst2243-prepare-' + randomUUID().slice(0, 6), source_id: SRC, slug: TEAM_PAGE, page_id: page!.id,
        intent: { fact: 'Globex pilot ends in June canaryprepshare', kind: 'fact', visibility: 'world', visibility_defaulted: true, share: true, entity_slug: TEAM_PAGE, fence: true, valid_from: new Date().toISOString() } };
      await expect(prepareMemoryMutation(engine, row as never, {} as never)).rejects.toMatchObject({ code: 'invalid_params' });
    }, 120_000);

    test('a replayed remember and a non-member remember both name page and visibility', async () => {
      const request_id = randomUUID();
      const first = await remember(A, 'Acme signs in April canaryreplay', { entity: ACME, share: true, request_id });
      const again = await remember(A, 'Acme signs in April canaryreplay', { entity: ACME, share: true, request_id });
      expect([again.isError, again.json.page, again.json.visibility]).toEqual([false, first.json.page, first.json.visibility]);
      expect([first.json.page, first.json.visibility]).toEqual([ACME, 'world']);
      const plain = await remember(U, 'Acme ships weekly canaryplain', { entity: ACME });
      expect([plain.isError, plain.json.page, plain.json.visibility]).toEqual([false, ACME, 'world']);
    }, 120_000);

    test('a batch shares every item with a top-level share: true', async () => {
      const out = await call(A, 'remember', { items: [{ fact: 'Acme pays net 30 canarybatchone', entity: ACME }, { fact: 'Acme has 3 sites canarybatchtwo', entity: ACME }], provenance: 'qm test', share: true });
      expect(out.isError).toBe(false);
      expect(await factRow('canarybatchone')).toMatchObject({ visibility: 'world', source_markdown_slug: ACME });
      expect(await factRow('canarybatchtwo')).toMatchObject({ visibility: 'world', source_markdown_slug: ACME });
      expect((out.json.items as Array<Record<string, unknown>>).map(r => [r.page, r.visibility])).toEqual([[ACME, 'world'], [ACME, 'world']]);
      const mixed = await call(A, 'remember', { items: [{ fact: 'Acme uses SSO canarymixedone', entity: ACME }, { fact: 'Acme uses SAML canarymixedtwo', entity: ACME, visibility: 'world' }], provenance: 'qm test' });
      expect(mixed.isError).toBe(true);
      expect(mixed.all).toContain('member_share_required');
      expect(await factRow('canarymixedone')).toBeUndefined();
      expect(await factRow('canarymixedtwo')).toBeUndefined();
    }, 120_000);

    test('a QM service acting for a member is told both cases, and its plain remember with visibility "world" is refused with the exact retry', async () => {
      const opts = ambientOptsFrom({ enabled: true, mode: 'salient', transient_ttl: '3d', visibility: 'world' } as never, { remember: true, extractFacts: true, ...writebackCaller(await verify(tokens.qm!)) });
      const section = buildAmbientWritebackSection(opts!);
      expect(section).toContain('share: true');
      expect(section).toContain('visibility: "world"');
      expect(writebackCaller(await verify(tokens.plain!))).toEqual({});
      expect(writebackCaller(await verify(tokens.alice!))).toEqual({ member: true });
      const world = await remember(who.alice(), 'Acme asked for audit logs canaryactorworld', { entity: ACME, visibility: 'world' });
      expect(world.isError).toBe(true);
      // GST-2249 W1: a save made for a person never shares, so both are refused and point at the owner's approval instead.
      expect(world.all).toContain('attested_share_refused');
      expect(world.all).toContain('memory_propose');
      expect(await factRow('canaryactorworld')).toBeUndefined();
      const retried = await remember(who.alice(), 'Acme asked for audit logs canaryactorworld', { entity: ACME, share: true });
      expect([retried.isError, retried.all.includes('attested_share_refused')]).toEqual([true, true]);
      expect(await factRow('canaryactorworld')).toBeUndefined();
      const kept = await remember(who.alice(), 'Acme audit worried me canaryactorkept', { entity: ACME });
      expect([kept.isError, kept.json.page, kept.json.visibility]).toEqual([false, 'memory/members/alice-example', 'private']);
    }, 120_000);

    test('QM memory_write, which takes no share, still saves on the member page, and share is on the starter surface', async () => {
      const out = await call(who.alice(), 'memory_write', { facts: [{ fact: 'Alice prefers async standups canaryqmwrite', provenance: 'qm test' }], idempotency_key: randomUUID() });
      expect(out.isError).toBe(false);
      expect(await factRow('canaryqmwrite')).toMatchObject({ visibility: 'private', source_markdown_slug: 'memory/members/alice-example' });
      const refused = await call(who.alice(), 'memory_write', { facts: [{ fact: 'x canaryqmshare', provenance: 'qm test', share: true }], idempotency_key: randomUUID() });
      expect(refused.isError).toBe(true);
      const { operationsByName } = await import('../src/core/operations.ts');
      expect(operationsByName.remember!.params.share).toMatchObject({ type: 'boolean' });
      expect(operationsByName.remember!.params.share!.fullSurfaceOnly).toBeUndefined();
    }, 120_000);
  });
}