Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.1 KB
Raw Blame
import { expect } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { BrainEngine } from '../../src/core/engine.ts';
import type { GBrainConfig } from '../../src/core/config.ts';
import { claimWorktree } from '../../src/core/persistence/ownership.ts';
import { disposePersistenceConsumer, waitForWrites } from '../../src/core/persistence/service.ts';
import { TERMINAL_STATES, type WriteRequest } from '../../src/core/persistence/model.ts';
import { isolatedPersistencePostgres } from './persistence-postgres.ts';
import { syncLockId } from '../../src/core/db-lock.ts';
import { testBackends } from './test-backends.ts';
import { CONNECTOR_WAIT_BUDGET_MS, connectorWaitBudget } from '../../src/core/persistence/connector-sync.ts';
import { testWaitMs } from './wait-for.ts';
import { connectTemplateBrain } from './brain-template.ts';
import { readManagedConnectorState } from '../../src/core/persistence/connector-state.ts';

export const options = { noEmbed: true, noExtract: true, noSchemaPack: true };
export const json = (body: unknown, status = 200, headers = {}) => new Response(JSON.stringify(body), {
  status, headers: { 'content-type': 'application/json', ...headers },
});
export const googleConfig = { kind: 'google', g_account: '[email protected]', g_services: 'contacts', g_access: 'env', g_token_env: 'CONNECTOR_TEST_TOKEN' };
export const githubConfig = { kind: 'github', gh_scope: 'repos', gh_repos: 'acme-example/app', gh_token_env: 'CONNECTOR_TEST_TOKEN' };
export const contact = (id: string, name: string) => ({ resourceName: `people/${id}`, names: [{ displayName: name }], emailAddresses: [{ value: `${id}@example.invalid` }] });
export const issueFixture = { number: 1, title: 'Example issue', state: 'open', body: 'A useful synthetic issue body.', created_at: '2026-01-01T00:00:00Z', updated_at: '2026-01-02T00:00:00Z', labels: [], assignees: [], user: { login: 'example-user' }, html_url: 'https://github.com/acme-example/app/issues/1' };

export function githubFetch(opts: { failDetail?: boolean; failSecondPage?: boolean; deleted?: boolean; calls?: string[] } = {}) {
  return async (url: string) => {
    opts.calls?.push(url);
    const u = new URL(url);
    const path = u.pathname;
    if (path.endsWith('/issues')) {
      if (opts.failSecondPage && u.searchParams.has('page')) return json({ message: 'fixture listing failure' }, 400);
      return json(opts.deleted ? [] : [issueFixture], 200, opts.failSecondPage ? { link: '<https://api.github.com/repos/acme-example/app/issues?page=2>; rel="next"' } : {});
    }
    if (path.endsWith('/pulls') || path.endsWith('/comments')) return json([]);
    if (path.endsWith('/issues/1')) return opts.failDetail ? json({ message: 'fixture detail failure' }, 400) : json(issueFixture);
    if (path === '/repos/acme-example/app') return json({ full_name: 'acme-example/app', private: true, default_branch: 'main' });
    throw new Error('Unexpected external fixture route');
  };
}

/**
 * A baseline sweep that finished: re-run `run` until the source has no
 * accepted-pending connector writes and no unfinished write request. A sweep
 * whose writes outlast its wait budget ends partial (its cursor is saved by the
 * next run), so a test that snapshots the cursor right after one `run()` could
 * read the state before the cursor moved and then see the next run move it.
 */
export async function completeBaselineSweep(engine: BrainEngine, sourceId: string, run: () => Promise<unknown>, attempts = 5): Promise<void> {
  for (let i = 0; i < attempts; i++) {
    await run();
    const unfinished = await engine.executeRaw<{ n: number }>(
      'SELECT count(*)::int AS n FROM persistence_requests WHERE source_id=$1 AND NOT (state = ANY($2::text[]))', [sourceId, [...TERMINAL_STATES]]);
    if ((await connectorPendingSet(engine, sourceId)).length === 0 && unfinished[0]!.n === 0) return;
  }
  throw new Error(`baseline sweep of ${sourceId} still had pending connector writes after ${attempts} runs`);
}

export async function sourceCheckpoint(engine: BrainEngine, id: string) {
  return engine.executeRaw("SELECT completed_keys FROM op_checkpoints WHERE op='managed-connector' AND fingerprint IN (SELECT intent->>'checkpointKey' FROM persistence_requests WHERE source_id=$1)", [id]);
}

export function createConnectorFixture() {
  const backends = testBackends();
  const home = mkdtempSync(join(tmpdir(), 'gbrain-connector-parity-'));
  const engines: BrainEngine[] = [];
  let closePostgres: (() => Promise<void>) | undefined;
  const env = { GBRAIN_HOME: home, CONNECTOR_TEST_TOKEN: 'synthetic-local-fixture' };
  const setup = async () => {
    connectorWaitBudget.ms = CONNECTOR_WAIT_BUDGET_MS;
    if (backends.includes('pglite')) {
      engines.push(await connectTemplateBrain(join(home, 'database')));
    }
    if (backends.includes('postgres')) {
      const pg = await isolatedPersistencePostgres(process.env.DATABASE_URL!);
      engines.push(pg.engine);
      closePostgres = pg.close;
    }
  };
  const teardown = async () => {
    connectorWaitBudget.ms = CONNECTOR_WAIT_BUDGET_MS;
    for (const engine of engines) { await disposePersistenceConsumer(engine); await engine.disconnect(); }
    await closePostgres?.();
    rmSync(home, { recursive: true, force: true });
  };

  async function source(engine: BrainEngine, config: Record<string, unknown>) {
    await disposePersistenceConsumer(engine);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    const id = `connector-${randomUUID().slice(0, 8)}`;
    const dir = join(home, id);
    mkdirSync(dir);
    await engine.executeRaw('INSERT INTO sources(id,name,local_path,config) VALUES($1,$1,$2,$3::text::jsonb)', [id, dir, JSON.stringify(config)]);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    return { id, dir };
  }

  async function boundSource(engine: BrainEngine, config: Record<string, unknown>) {
    const f = await source(engine, config);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
    const binding = await claimWorktree(engine, f.id, f.dir);
    await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
    return { ...f, binding };
  }

  async function standaloneConnector(engine: BrainEngine, f: { id: string; dir: string }, sourceConfig: Record<string, unknown>, crash = false, retryFailed = false) {
    let database: GBrainConfig & { poolSize?: number } = { engine: 'pglite', database_path: join(home, 'database') };
    if (engine.kind === 'postgres') {
      const [row] = await engine.executeRaw<{ name: string }>('SELECT current_database() AS name');
      const url = new URL(process.env.DATABASE_URL!);
      url.pathname = `/${row.name}`;
      database = { engine: 'postgres', database_url: url.toString(), poolSize: 4 };
    }
    await disposePersistenceConsumer(engine);
    await engine.disconnect();
    let childPid: number | undefined;
    try {
      const child = Bun.spawn([process.execPath, 'run', join(import.meta.dir, 'connector-restart.ts')], {
        env: { ...process.env, ...env, GBRAIN_TEST_CONNECTOR_RESTART: JSON.stringify({ database, sourceId: f.id,
          root: f.dir, sourceConfig, body: 'Updated organization after interruption', crash, retryFailed }) }, stdout: 'pipe', stderr: 'pipe',
      });
      childPid = child.pid;
      const timer = setTimeout(() => child.kill('SIGKILL'), 30_000);
      try {
        const [stdout, stderr, exitCode] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
        return { stdout, stderr, exitCode };
      } finally { clearTimeout(timer); if (child.exitCode === null) child.kill('SIGKILL'); await child.exited; }
    } finally {
      await engine.connect(database);
      if (crash && childPid !== undefined) await engine.executeRaw(`UPDATE gbrain_cycle_locks
        SET acquired_at=now()-interval '2 minutes',last_refreshed_at=now()-interval '1 hour',ttl_expires_at=now()-interval '1 hour'
        WHERE id=$1 AND holder_pid=$2`, [syncLockId(f.id), childPid]);
    }
  }

  return { home, engines, env, backends, setup, teardown, source, boundSource, standaloneConnector };
}

/** #7490: the People reachability probe (one connection, email addresses only), told apart from a contacts sweep page. */
export function isPeopleAccessProbe(url: string): boolean {
  const u = new URL(url);
  return u.pathname.endsWith('/people/me/connections') && u.searchParams.get('pageSize') === '1' && u.searchParams.get('personFields') === 'emailAddresses';
}

/**
 * #5686: a managed Google run resolves the credential's account (People
 * reachability, Calendar primary, Gmail profile, then OAuth userinfo) before
 * any service runs. Fixture fetchers that only model sweep routes get those
 * identity routes answered here.
 */
export function withGoogleAccount(fetcher: ((url: string, init?: RequestInit) => Promise<Response>) | undefined, account = googleConfig.g_account) {
  return async (url: string, init?: RequestInit) => {
    const path = new URL(url).pathname;
    if (path.endsWith('/people/me')) return json({ resourceName: 'people/me', emailAddresses: [{ value: account, metadata: { primary: true } }] });
    if (isPeopleAccessProbe(url)) return json({ connections: [] });
    if (path.endsWith('/v1/userinfo')) return json({ email: account });
    if (path.endsWith('/calendars/primary')) return json({ id: account });
    if (!fetcher) throw new Error('Unexpected external fixture route');
    return fetcher(url, init);
  };
}

/**
 * A managed sweep returns with an accepted write still pending once its wait
 * budget runs out; the cursor stays put and the write publishes later. A seed
 * that reads its imported pages, or stops the consumer and hands the database
 * to a child, first waits for every write the source admitted to commit.
 */
export async function settleConnectorWrites(engine: BrainEngine, sourceId: string) {
  const rows = await engine.executeRaw<WriteRequest>('SELECT * FROM persistence_requests WHERE source_id=$1 ORDER BY created_at', [sourceId]);
  const settled = await waitForWrites(engine, rows, { engine: engine.kind }, testWaitMs(30_000));
  expect(settled.map(row => [row.slug, row.state])).toEqual(rows.map(row => [row.slug, 'committed']));
}

/**
 * The fixture's 1.5 s wait budget is for runs against a paused owner. A run whose assertions need every write
 * published (a healthy owner) runs on the production budget, so a slow host waits for the owner instead of
 * stopping the sweep `writer_pending`. A committed write returns at once, so this costs nothing on a fast host.
 */
/** A run that expects `writer_pending` against a paused owner stops on a 1.5 s budget instead of the production 30 s. */
export async function withPausedOwnerBudget<T>(run: () => Promise<T>): Promise<T> {
  const budget = connectorWaitBudget.ms;
  connectorWaitBudget.ms = testWaitMs(1_500);
  try { return await run(); } finally { connectorWaitBudget.ms = budget; }
}

/** #5600: the pending set a managed connector run ended with (connector state row). */
export async function connectorPendingSet(engine: BrainEngine, sourceId: string) {
  const [source] = await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text FROM sources WHERE id=$1', [sourceId]);
  return (await readManagedConnectorState(engine, sourceId, source.incarnation)).pending;
}

/**
 * Fix wave 4: the connector cursor a checkpoint row carries, without its item
 * holds or generation. A failed or partial run may publish updated holds, but
 * never moves this cursor.
 */
export async function sourceCursor(engine: BrainEngine, id: string) {
  return cursorOf(await sourceCheckpoint(engine, id));
}
export function cursorOf(rows: Array<{ completed_keys?: unknown }> | Record<string, unknown>[]) {
  return (rows as Array<{ completed_keys?: Array<{ state?: Record<string, unknown> | null }> }>).map(row => (row.completed_keys ?? []).map(entry => {
    if (!entry?.state) return { state: entry?.state ?? null };
    const { item_holds: _holds, ...cursor } = entry.state;
    return { state: cursor };
  }));
}