Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.5 KB
Raw Blame
/**
 * Ambient-writeback WP2: the instruction section builder (single source for
 * MCP instructions AND the bootstrap-managed blocks), buildMcpInstructions'
 * byte-identity when off, and transport parity — the legacy bearer transport
 * must serve exactly what the shared builder produces, per request, with the
 * last-known-good bundle riding out a mid-session config blip.
 *
 * (stdio + OAuth enabled-state coverage rides the hermetic e2e fixture,
 * test/e2e/ambient-writeback-lifecycle.serial.test.ts — those transports need
 * a real subprocess/app boot. The three existing byte-exact OFF pins are
 * test/serve-stdio-roundtrip.test.ts, test/http-transport.test.ts, and
 * test/connect-bearer.test.ts and run unchanged.)
 */
import { describe, test, expect, afterAll } from 'bun:test';
import { createHash } from 'node:crypto';

import { buildAmbientWritebackSection } from '../src/core/facts/writeback-instructions.ts';
import { GBRAIN_MCP_INSTRUCTIONS, buildMcpInstructions } from '../src/mcp/instructions.ts';
import { contractFor } from './helpers/instructions-parity.ts';
import { startHttpTransport } from '../src/mcp/http-transport.ts';
import { RateLimiter } from '../src/mcp/rate-limit.ts';
import { emptyHome, withEnv } from './helpers/with-env.ts';

const BASE_OPTS = {
  mode: 'salient' as const,
  transientTtl: '3d',
  visibility: 'world' as const,
  extractFactsAvailable: true,
};

describe('buildAmbientWritebackSection (F1 leaf — the single source)', () => {
  test('GST-2243: a member caller is told to omit visibility and share team facts with share: true', () => {
    for (const visibility of ['world', 'private'] as const) {
      const s = buildAmbientWritebackSection({ ...BASE_OPTS, visibility, member: true });
      expect(s).not.toContain('Pass visibility:');
      expect(s).toContain('share: true');
      expect(s).toContain('only the brain host can withdraw it');
    }
  });

  test('salient mode carries the durable-only candidate policy', () => {
    const s = buildAmbientWritebackSection(BASE_OPTS);
    expect(s).toContain('mode: salient');
    expect(s).toContain('preferences, corrections, decisions, commitments, relationships');
    expect(s).not.toContain('every direct factual statement');
  });

  test('all mode saves every direct statement but keeps the exclusions (req 4 "all" definition)', () => {
    const s = buildAmbientWritebackSection({ ...BASE_OPTS, mode: 'all' });
    expect(s).toContain('mode: all');
    expect(s).toContain('every direct factual statement');
    expect(s).toContain('operational chatter');
    expect(s).toContain('secrets or credentials');
    expect(s).toContain('quoted third-party material');
  });

  test('the resolved transient TTL is embedded literally', () => {
    expect(buildAmbientWritebackSection({ ...BASE_OPTS, transientTtl: '12h' })).toContain('ttl: "12h"');
    // With extract_facts advertised, the transient line must ALSO warn that
    // extract_facts has no ttl parameter (a transient claim batched through
    // it would become permanent — adversarial review, this wave).
    expect(buildAmbientWritebackSection({ ...BASE_OPTS, transientTtl: '12h', extractFactsAvailable: true }))
      .toContain('never batch them through extract_facts');
    expect(buildAmbientWritebackSection({ ...BASE_OPTS, transientTtl: '12h', extractFactsAvailable: false }))
      .toContain('pass ttl: "12h"');
  });

  test('extract_facts is only named when actually callable (OV2-14)', () => {
    expect(buildAmbientWritebackSection(BASE_OPTS)).toContain('extract_facts');
    const without = buildAmbientWritebackSection({ ...BASE_OPTS, extractFactsAvailable: false });
    expect(without).not.toContain('extract_facts');
    expect(without).toContain('distill them yourself');
  });

  test('visibility postures: world names the agents-on-this-brain semantics; private names the widen trap + recall trade-off (F5/req 6)', () => {
    const world = buildAmbientWritebackSection(BASE_OPTS);
    expect(world).toContain('visibility: "world"');
    expect(world).toContain('not the public internet');
    expect(world).toContain('Never widen a private fact on your own.');
    const priv = buildAmbientWritebackSection({ ...BASE_OPTS, visibility: 'private' });
    expect(priv).toContain('visibility: "private"');
    expect(priv).toContain('omitting visibility would silently widen');
    expect(priv).toContain('not by remote sessions');
  });

  test('#5671 private posture states the remote read-back consequence in the instruction itself', () => {
    const priv = buildAmbientWritebackSection({ ...BASE_OPTS, visibility: 'private' });
    expect(priv).toContain('you, and every other MCP or HTTP session, cannot recall or forget a fact you save as private');
    expect(buildAmbientWritebackSection(BASE_OPTS)).not.toContain('cannot recall');
  });

  test('every requirement-3 bullet is present (skip-list, no assistant inference, no raw transcripts, provenance, one claim, scope, silence, durable-no-ttl)', () => {
    const s = buildAmbientWritebackSection(BASE_OPTS);
    expect(s).toContain('ONE claim per call');
    expect(s).toContain('provenance');
    expect(s).toContain('omit ttl');
    expect(s).toContain('greetings, acknowledgements, questions that carry no new facts');
    expect(s).toContain('unless the user explicitly asks');
    expect(s).toContain('Never store your own inference, diagnosis, speculation, or interpretation');
    expect(s).toContain('Never store raw transcripts');
    expect(s).toContain('authenticated brain and source scope');
    expect(s).toContain('Write silently');
  });

  test('stays lean: ≤ 15 lines (OV2/Codex#15 acceptance)', () => {
    expect(buildAmbientWritebackSection(BASE_OPTS).split('\n').length).toBeLessThanOrEqual(15);
  });
});

describe('buildMcpInstructions composition', () => {
  test('off/absent → BYTE-IDENTICAL to the frozen base (the three transport pins depend on this)', () => {
    expect(buildMcpInstructions()).toBe(GBRAIN_MCP_INSTRUCTIONS);
    expect(buildMcpInstructions({})).toBe(GBRAIN_MCP_INSTRUCTIONS);
    expect(buildMcpInstructions({ writeback: null })).toBe(GBRAIN_MCP_INSTRUCTIONS);
  });
  // #6170 replaced the "base untouched" pin on purpose: capped harnesses read only
  // the first 2,048 characters, so the base carries a short writeback line.
  test('enabled → base = contract with the writeback line in place of the opt-in line, then a blank line and the section last', () => {
    const out = buildMcpInstructions({ writeback: BASE_OPTS });
    const line = `Ambient writeback is ON (${BASE_OPTS.mode}): unprompted, \`remember\` the user's preferences, corrections, decisions and commitments`;
    const head = out.slice(0, out.length - buildAmbientWritebackSection(BASE_OPTS).length);
    expect(head.endsWith('\n\n')).toBe(true);
    expect(head.trimEnd()).toBe(GBRAIN_MCP_INSTRUCTIONS.replace('Automatic capture is opt-in.', `${line} (rules below).`));
    expect(out.endsWith(buildAmbientWritebackSection(BASE_OPTS))).toBe(true);
  });
});

// ── legacy bearer transport: enabled state + LKG, per request ──────────────

function hash(token: string): string {
  return createHash('sha256').update(token).digest('hex');
}

describe('legacy bearer transport serves the shared builder output (parity)', () => {
  const TOKEN = 'wb-instr-token';
  let stop: (() => void) | null = null;
  afterAll(() => stop?.());

  // The transport reads the process config (loadConfig) for its readiness tail. In a Postgres lane DATABASE_URL alone
  // yields an env-derived config, so the tail ("Setup now …") appeared and parity broke whenever DATABASE_URL was set.
  // This fake engine has no process config: pin that, independent of the lane's environment.
  test('enabled config → initialize carries base+section; config blip → last-known-good bundle; fresh engine off → base', () =>
    withEnv({ DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined, GBRAIN_HOME: emptyHome() }, async () => {
    const rows = new Map<string, string>([
      ['memory.auto_writeback', 'salient'],
      ['memory.auto_writeback_transient_ttl', '12h'],
      ['facts.default_visibility', 'private'],
    ]);
    let dbHealthy = true;
    const validTokens = new Map([[hash(TOKEN), { id: 'tok-wb', name: 'wb-test' }]]);
    const engine = {
      kind: 'postgres',
      executeRaw: async (sql: string, params?: unknown[]) => {
        const norm = sql.replace(/\s+/g, ' ').trim().toLowerCase();
        if (norm.startsWith('select id, name') || norm.startsWith('select * from access_tokens')) {
          const row = validTokens.get(params?.[0] as string);
          return row ? [{ ...row, permissions: { takes_holders: ['world'] } }] : [];
        }
        return [];
      },
      getConfig: async (k: string) => {
        if (!dbHealthy) throw new Error('db blip');
        return rows.get(k) ?? null;
      },
    };
    const server = await startHttpTransport({
      port: 0,
      engine: engine as never,
      limiters: {
        ip: new RateLimiter({ limit: 1000, windowMs: 60_000, lruCap: 100 }),
        token: new RateLimiter({ limit: 1000, windowMs: 60_000, lruCap: 100 }),
      },
    });
    stop = () => (server as { stop: (b: boolean) => void }).stop(true);
    const url = `http://localhost:${(server as { port: number }).port}/mcp`;

    const init = async () => {
      const r = await fetch(url, {
        method: 'POST',
        headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 't', version: '1' } } }),
      });
      expect(r.status).toBe(200);
      const body = (await r.json()) as { result?: { instructions?: string } };
      return body.result?.instructions;
    };

    // F1: the contract is generated for this token's tools/list.
    const listed = await fetch(url, {
      method: 'POST',
      headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }),
    }).then(r => r.json() as Promise<{ result: { tools: Array<{ name: string }> } }>);
    const expected = contractFor(listed.result.tools.map(t => t.name),
      { mode: 'salient', transientTtl: '12h', visibility: 'private', extractFactsAvailable: true });
    expect(await init()).toBe(expected);

    // Mid-session config blip: the FULL last-known-good bundle keeps serving
    // (never base, never a mixed default) — OV2-8/F3 on a live transport.
    dbHealthy = false;
    expect(await init()).toBe(expected);
  }));
});