Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
9.9 KB
Raw Blame
/**
 * `recall` composes `entity`, `session_id` and `since` into ONE engine query.
 *
 * The op used to branch `entity` > `session_id` > `since` as an if / else-if
 * chain: with `entity` set the `since` window was never applied (the entity
 * arm called listFactsByEntity without a cutoff), and `session_id` + `since`
 * had the same shape. A caller asking for "facts about X since T" silently
 * got every fact about X. An unparseable `since` was swallowed the same way
 * (an empty or unfiltered result instead of an error).
 *
 * Pinned here, through the real op via dispatchToolCall and through the CLI's
 * local fetch path:
 *  - entity + since excludes facts older than the cutoff
 *  - session_id + since likewise, and entity + session_id + since AND together
 *  - the window is EVENT time (COALESCE(valid_from, created_at)), same as the
 *    since-only arm, so a backdated row drops out even though it was written now
 *  - the boundary is inclusive at the cutoff
 *  - the cutoff lands before the SQL LIMIT: a limit never refills with rows
 *    from outside the window
 *  - an unparseable since is rejected with invalid_params
 *  - the CLI's entity-TEXT fallback (a bare positional that resolves to no
 *    entity is retried as a fact-text grep, #4720) keeps the window: an
 *    explicit `--since` on event time, `--since-last-run` on the cursor's
 *    creation-time watermark. Without it a windowed recall for an unknown
 *    term returned the term's whole history.
 */
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { rmSync } from 'node:fs';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import { runRecall } from '../src/commands/recall.ts';
import { writeCursor } from '../src/core/recall-cursor-state.ts';
import { withEnv, emptyHome } from './helpers/with-env.ts';

let engine: PGLiteEngine;

const HOUR = 60 * 60 * 1000;
const DAY = 24 * HOUR;
const NOW = Date.now();
// Fixed cutoff for the boundary test (well inside every "48 hours ago" window).
const CUTOFF = new Date(NOW - 2 * HOUR);
// GBRAIN_HOME for the --since-last-run case (the cursor file lives under it).
const cursorHome = emptyHome();

async function seed(fact: string, opts: { entity?: string; session?: string; validFrom: Date }): Promise<void> {
  await engine.insertFact(
    {
      fact,
      kind: 'fact',
      entity_slug: opts.entity,
      source: 'test',
      source_session: opts.session,
      valid_from: opts.validFrom,
      visibility: 'world',
    },
    { source_id: 'default' },
  );
}

async function recallFacts(params: Record<string, unknown>): Promise<string[]> {
  const result = await dispatchToolCall(engine, 'recall', params, { remote: false, sourceId: 'default' });
  expect(result.isError).toBeFalsy();
  const payload = JSON.parse(result.content[0].text);
  return (payload.facts as { fact: string }[]).map((f) => f.fact);
}

async function recallCli(args: string[], home = emptyHome()): Promise<string[]> {
  const origWrite = process.stdout.write;
  let captured = '';
  process.stdout.write = ((chunk: string | Uint8Array) => {
    captured += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString();
    return true;
  }) as typeof process.stdout.write;
  try {
    await withEnv({ GBRAIN_HOME: home }, async () => {
      await runRecall(engine, [...args, '--json']);
    });
  } finally {
    process.stdout.write = origWrite;
  }
  const payload = JSON.parse(captured.trim());
  return (payload.facts as { fact: string }[]).map((f) => f.fact);
}

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();

  // Every row is CREATED now; only valid_from (event time) differs, so a
  // creation-time window would keep all of them.
  await seed('window-entity-recent', { entity: 'ent-window', validFrom: new Date(NOW - HOUR) });
  await seed('window-entity-old', { entity: 'ent-window', validFrom: new Date(NOW - 30 * DAY) });

  await seed('window-session-recent', { session: 'sess-window', validFrom: new Date(NOW - HOUR) });
  await seed('window-session-old', { session: 'sess-window', validFrom: new Date(NOW - 30 * DAY) });

  await seed('triple-match', { entity: 'ent-triple', session: 'sess-a', validFrom: new Date(NOW - HOUR) });
  await seed('triple-other-session', { entity: 'ent-triple', session: 'sess-b', validFrom: new Date(NOW - HOUR) });
  await seed('triple-old', { entity: 'ent-triple', session: 'sess-a', validFrom: new Date(NOW - 30 * DAY) });

  await seed('boundary-at-cutoff', { entity: 'ent-boundary', validFrom: CUTOFF });
  await seed('boundary-before-cutoff', { entity: 'ent-boundary', validFrom: new Date(CUTOFF.getTime() - 1000) });

  await seed('page-in-window', { entity: 'ent-page', validFrom: new Date(NOW - HOUR) });
  await seed('page-old-1', { entity: 'ent-page', validFrom: new Date(NOW - 10 * DAY) });
  await seed('page-old-2', { entity: 'ent-page', validFrom: new Date(NOW - 20 * DAY) });
  await seed('page-old-3', { entity: 'ent-page', validFrom: new Date(NOW - 30 * DAY) });

  // Entity-text fallback rows: no entity, the query term only appears in the
  // TEXT. Same event-time split as above; the old row's created_at is also
  // backdated so the creation-time (--since-last-run) window excludes it.
  await seed('textfb-zebrule recent', { validFrom: new Date(NOW - HOUR) });
  await seed('textfb-zebrule old', { validFrom: new Date(NOW - 10 * DAY) });
  await engine.executeRaw(
    `UPDATE facts SET created_at = now() - interval '10 days' WHERE fact = 'textfb-zebrule old'`,
  );
});

afterAll(async () => {
  await engine.disconnect();
  rmSync(cursorHome, { recursive: true, force: true });
});

describe('recall op: entity / session_id / since compose before the SQL LIMIT', () => {
  test('entity + since excludes facts whose event time is older than the cutoff', async () => {
    const facts = await recallFacts({ entity: 'ent-window', since: '48 hours ago' });
    expect(facts).toContain('window-entity-recent');
    expect(facts).not.toContain('window-entity-old');
  });

  test('entity without since keeps the full entity card', async () => {
    const facts = await recallFacts({ entity: 'ent-window' });
    expect(facts).toContain('window-entity-recent');
    expect(facts).toContain('window-entity-old');
  });

  test('session_id + since excludes facts whose event time is older than the cutoff', async () => {
    const facts = await recallFacts({ session_id: 'sess-window', since: '48 hours ago' });
    expect(facts).toContain('window-session-recent');
    expect(facts).not.toContain('window-session-old');
  });

  test('entity + session_id + since AND together', async () => {
    const facts = await recallFacts({ entity: 'ent-triple', session_id: 'sess-a', since: '48 hours ago' });
    expect(facts).toEqual(['triple-match']);
  });

  test('boundary: a fact whose event time equals the cutoff is included, one second earlier is not', async () => {
    const facts = await recallFacts({ entity: 'ent-boundary', since: CUTOFF.toISOString() });
    expect(facts).toContain('boundary-at-cutoff');
    expect(facts).not.toContain('boundary-before-cutoff');
  });

  test('limit never refills from outside the window (cutoff lands before LIMIT)', async () => {
    const facts = await recallFacts({ entity: 'ent-page', since: '48 hours ago', limit: 2 });
    expect(facts).toEqual(['page-in-window']);
    // Without the window the same limit returns the two newest by event time.
    const unbounded = await recallFacts({ entity: 'ent-page', limit: 2 });
    expect(unbounded).toEqual(['page-in-window', 'page-old-1']);
  });

  test('an unparseable since is rejected with invalid_params instead of widening the window', async () => {
    for (const params of [
      { entity: 'ent-window', since: 'sometime last week' },
      { session_id: 'sess-window', since: 'sometime last week' },
      { since: 'sometime last week' },
    ]) {
      const result = await dispatchToolCall(engine, 'recall', params, { remote: false, sourceId: 'default' });
      expect(result.isError).toBe(true);
      const err = JSON.parse(result.content[0].text);
      expect(err.error).toBe('invalid_params');
      expect(String(err.message)).toContain('since');
    }
  });
});

describe('engine: listFactsSince composes sessionId in SQL', () => {
  test('sessionId ANDs onto the event-time window', async () => {
    const rows = await engine.listFactsSince('default', new Date(NOW - 2 * DAY), {
      eventTime: true,
      sessionId: 'sess-a',
    });
    expect(rows.map((r) => r.fact)).toEqual(['triple-match']);
  });
});

describe('gbrain recall CLI (local path) composes the same way', () => {
  test('<entity> --since excludes older facts', async () => {
    const facts = await recallCli(['ent-window', '--since', '48 hours ago']);
    expect(facts).toContain('window-entity-recent');
    expect(facts).not.toContain('window-entity-old');
  });

  test('--session-id --since excludes older facts', async () => {
    const facts = await recallCli(['--session-id', 'sess-window', '--since', '48 hours ago']);
    expect(facts).toContain('window-session-recent');
    expect(facts).not.toContain('window-session-old');
  });
});

describe('gbrain recall CLI entity-text fallback honors the window', () => {
  test('unknown positional + --since matches by text but only inside the event-time window', async () => {
    // Sanity: without a window the fallback returns the term's full history.
    expect((await recallCli(['zebrule'])).sort()).toEqual(['textfb-zebrule old', 'textfb-zebrule recent']);
    expect(await recallCli(['zebrule', '--since', '48 hours ago'])).toEqual(['textfb-zebrule recent']);
  });

  test('unknown positional + --since-last-run keeps the cursor watermark (creation time)', async () => {
    await withEnv({ GBRAIN_HOME: cursorHome }, () => writeCursor('default', new Date(NOW - 2 * DAY)));
    expect(await recallCli(['zebrule', '--since-last-run'], cursorHome)).toEqual(['textfb-zebrule recent']);
  });
});