Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.9 KB
Raw Blame
/**
 * traverse_graph `hops` (agent-structured typed chains), through the real MCP
 * dispatcher for remote callers and the op handler for trusted local callers.
 *
 * Protects: a 1-3 hop chain returns answers with evidence edges; bad hops are
 * `invalid_params`, and depth/link_type/direction beside hops are set aside and
 * named in `set_aside` (GST-2214), never silently ignored; a chain that
 * finds nothing distinguishes an invisible start page from missing edges and
 * names the next call; remote callers never see private pages or raw context
 * beyond the sanitized excerpt; a granted token cannot reach another source.
 * Regression it catches: hops ignored (plain traversal returned), depth/type
 * silently dropped, private evidence leaking to remote callers.
 */
import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { operations, operationsByName, type AuthInfo, type OperationContext } from '../src/core/operations.ts';
import { filterOpsForSurface } from '../src/mcp/surface.ts';
import { dispatchToolCall, type DispatchOpts } from '../src/mcp/dispatch.ts';
import type { Notice } from '../src/core/agent-output.ts';
import { buildRelationalArm } from '../src/core/search/relational-recall.ts';
import { installFixtureChunks } from './helpers/page-projection.ts';

let engine: PGLiteEngine;

const HOPS = [{ link_type: 'invested_in', toward: 'object' }, { link_type: 'founded', toward: 'subject' }];

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
  const page = (slug: string, type: string, frontmatter?: Record<string, unknown>, body = `${slug} body`) =>
    engine.putPage(slug, { type: type as 'person', title: slug.split('/')[1], compiled_truth: body, timeline: '', ...(frontmatter ? { frontmatter } : {}) });
  await page('people/alice-example', 'person');
  await page('people/bob-example', 'person');
  await page('people/priv-example', 'person', { visibility: 'private' });
  // GST-2957: a world-only remote caller sees a body-excerpt context only when the page still holds it.
  await page('companies/acme-example', 'company', undefined, `companies/acme-example body. founded by bob ${'x'.repeat(400)}`);
  await page('companies/lonely-example', 'company');
  await engine.addLink('people/alice-example', 'companies/acme-example', 'alice backed acme', 'invested_in', 'markdown');
  await engine.addLink('companies/acme-example', 'people/bob-example', `founded by bob ${'x'.repeat(400)}`, 'founded', 'markdown');
  await engine.addLink('people/priv-example', 'companies/acme-example', 'priv cofounded acme', 'founded', 'markdown');
}, 60_000);

afterAll(async () => {
  await engine.disconnect();
});

function localCtx(notices: Notice[] = []): OperationContext {
  return {
    engine: engine as never, config: {} as never, dryRun: false, remote: false, sourceId: 'default',
    logger: { info: () => {}, warn: () => {}, error: () => {} },
    emitNotice: (n: Notice) => { notices.push(n); },
  };
}

function remoteOpts(): DispatchOpts {
  const auth = { token: '', clientId: 'client-a', scopes: ['read'], sourceId: 'default', allowedSources: ['default'], principal: { kind: 'oauth_client', id: 'client-a' } } as AuthInfo;
  return { remote: true, transport: 'http', sourceId: 'default', auth, localFederatedSourceIds: ['default'] };
}

const runLocal = (params: Record<string, unknown>, notices?: Notice[]) =>
  operationsByName.traverse_graph.handler(localCtx(notices), params) as Promise<any>;

describe('traverse_graph hops', () => {
  test('two-hop chain returns answers with evidence, oriented across stored direction', async () => {
    const res = await runLocal({ slug: 'people/alice-example', hops: HOPS });
    expect(res.diagnostics.status).toBe('fired');
    expect(res.answers.map((a: any) => a.slug).sort()).toEqual(['people/bob-example', 'people/priv-example']);
    const bob = res.paths[res.answers.findIndex((a: any) => a.slug === 'people/bob-example')];
    expect(bob.nodes).toEqual(['people/alice-example', 'companies/acme-example', 'people/bob-example']);
    expect(bob.edges[1]).toMatchObject({ link_type: 'founded', stored_from: 'companies/acme-example', orientation: 'flipped' });
  });

  test('remote callers: private pages hidden; context only from sealed pages, sanitized and bounded', async () => {
    const remote = async () => JSON.parse((await dispatchToolCall(engine, 'traverse_graph', { slug: 'people/alice-example', hops: HOPS }, remoteOpts())).content[0].text);
    const unsealed = await remote();
    expect(unsealed.answers.map((a: any) => a.slug)).toEqual(['people/bob-example']);
    expect(unsealed.paths[0].edges[1].context).toBeNull();
    const before = await engine.executeRaw<{ v: number }>(`SELECT chunker_version AS v FROM pages WHERE slug = 'companies/acme-example'`);
    await engine.executeRaw(`UPDATE pages SET chunker_version = 4 WHERE slug = 'companies/acme-example'`);
    const body = await remote();
    await engine.executeRaw(`UPDATE pages SET chunker_version = $1 WHERE slug = 'companies/acme-example'`, [before[0].v]);
    const ctx = body.paths[0].edges[1].context as string;
    expect(ctx.startsWith('founded by bob')).toBe(true);
    expect(ctx.length).toBeLessThanOrEqual(160);
  });

  test('invalid hops are invalid_params with the exact problem', async () => {
    await expect(runLocal({ slug: 'people/alice-example', hops: [{ link_type: 'mentions', toward: 'object' }] }))
      .rejects.toMatchObject({ code: 'invalid_params', message: expect.stringContaining('hops[0].link_type') });
    await expect(runLocal({ slug: 'people/alice-example', hops: [{ link_type: 'founded', toward: 'in' }] }))
      .rejects.toMatchObject({ code: 'invalid_params', message: expect.stringContaining('hops[0].toward') });
    await expect(runLocal({ slug: 'people/alice-example', hops: [...HOPS, ...HOPS] }))
      .rejects.toMatchObject({ code: 'invalid_params', message: expect.stringContaining('at most 3 hops') });
  });

  test('depth and link_type beside hops walk the same chain and are named in set_aside, never silently dropped', async () => {
    const chain = await runLocal({ slug: 'people/alice-example', hops: HOPS });
    const { set_aside, ...rest } = await runLocal({ slug: 'people/alice-example', hops: HOPS, depth: 2, link_type: 'founded' });
    expect(rest).toEqual(chain);
    expect(chain.set_aside).toBeUndefined();
    expect(set_aside).toEqual({ ignored: ['depth', 'link_type'],
      note: 'Walked the hops chain; ignored depth and link_type: each hop names its link type and direction (toward), and the chain length is the number of hops.' });
  });

  test('anchor_not_found, no_edges and empty_hop each carry a notice with the next call', async () => {
    const notices: Notice[] = [];
    const missing = await runLocal({ slug: 'people/nobody-example', hops: HOPS }, notices);
    expect(missing.diagnostics.status).toBe('anchor_not_found');
    expect(notices.pop()).toMatchObject({ code: 'relational_chain', fix: { mcp: { tool: 'search' } } });
    const none = await runLocal({ slug: 'companies/lonely-example', hops: [{ link_type: 'founded', toward: 'subject' }] }, notices);
    expect(none.diagnostics.status).toBe('no_edges');
    expect(notices.pop()).toMatchObject({ fix: { mcp: { tool: 'traverse_graph', arguments: { slug: 'companies/lonely-example', depth: 1 } } } });
    const later = await runLocal({ slug: 'people/alice-example', hops: [HOPS[0], { link_type: 'advises', toward: 'subject' }] }, notices);
    expect(later.diagnostics).toMatchObject({ status: 'empty_hop', empty_hop: 2 });
    expect(notices.pop()).toMatchObject({ fix: { mcp: { tool: 'traverse_graph', arguments: { hops: [HOPS[0]] } } } });
    await runLocal({ slug: 'companies/lonely-example', hops: [{ link_type: 'founded', toward: 'subject' }] }, notices);
    const unscoped = (notices.pop() as any).fix.mcp.arguments;
    expect(unscoped).not.toHaveProperty('source_id');
    expect(unscoped).not.toHaveProperty('all_sources');
    for (const scope of [{ source_id: 'default' }, { all_sources: true }]) {
      await runLocal({ slug: 'companies/lonely-example', hops: [{ link_type: 'founded', toward: 'subject' }], ...scope }, notices);
      expect(notices.pop()).toMatchObject({ fix: { mcp: { tool: 'traverse_graph', arguments: { depth: 1, ...scope } } } });
      await runLocal({ slug: 'people/alice-example', hops: [HOPS[0], { link_type: 'advises', toward: 'subject' }], ...scope }, notices);
      expect(notices.pop()).toMatchObject({ fix: { mcp: { tool: 'traverse_graph', arguments: { hops: [HOPS[0]], ...scope } } } });
    }
  });

  test('hops is advertised on the full surface only; the starter list stays inside its budget', () => {
    const on = (surface: 'full' | 'starter') => filterOpsForSurface(operations, surface).find(o => o.name === 'traverse_graph')!.params;
    expect(on('full')).toHaveProperty('hops');
    expect(on('starter')).not.toHaveProperty('hops');
    expect(on('starter')).toHaveProperty('depth');
  });

  test('without hops the op keeps its existing shape', async () => {
    const res = await runLocal({ slug: 'people/alice-example', link_type: 'invested_in', direction: 'out' });
    expect(Array.isArray(res)).toBe(true);
  });
});

describe('traverse_graph hops: relationship validity', () => {
  test('an ended state relationship is not walked; a "formerly" question walks it', async () => {
    await engine.putPage('people/carol-example', { type: 'person', title: 'carol', compiled_truth: 'carol', timeline: '' });
    await engine.putPage('companies/old-example', { type: 'company', title: 'old', compiled_truth: 'old', timeline: '' });
    await engine.addLink('companies/old-example', 'people/bob-example', 'founded by bob', 'founded', 'markdown');
    await operationsByName.add_link.handler(localCtx(), {
      from: 'people/carol-example', to: 'companies/old-example', link_type: 'advises', valid_from: '2019-01-01', valid_until: '2021-06-30',
    });
    const hops = [{ link_type: 'advises', toward: 'object' }, { link_type: 'founded', toward: 'subject' }];
    const live = await runLocal({ slug: 'people/carol-example', hops });
    expect(live.answers).toEqual([]);
    expect(live.diagnostics.status).toBe('no_edges');

    // The search arm: present tense walks live relationships, "formerly" walks the ended one.
    for (const slug of ['people/bob-example', 'companies/old-example']) {
      await installFixtureChunks(engine, slug, [{ chunk_index: 0, chunk_source: 'compiled_truth', chunk_text: `${slug} body` }]);
    }
    const arm = async (q: string) => {
      let meta: any;
      const list = await buildRelationalArm(engine, q, { planner: true, onMeta: m => { meta = m; } });
      return { answers: list.filter(r => r.relational?.role === 'answer').map(r => r.slug), status: meta.plan?.status };
    };
    expect(await arm('Who founded the companies Carol Example advises?')).toEqual({ answers: [], status: 'no_edges' });
    expect(await arm('Who founded the companies Carol Example formerly advised?')).toEqual({ answers: ['people/bob-example'], status: 'fired' });
  });
});