Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.8 KB
Raw Blame
/**
 * CLI→MCP gap-closure wave — the capture op (D2A). Pins: default-slug
 * determinism, the NUL/empty guards, the frontmatter merge (single block),
 * put_page delegation (provenance server-stamped mcp:put_page for remote —
 * honest CV6 delegation), the [EV7] bound-prefix default for fenced clients,
 * and content_hash stability.
 */

import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { dispatchToolCall } from '../src/mcp/dispatch.ts';
import type { AuthInfo } from '../src/core/operations.ts';

let engine: PGLiteEngine;

const STDIO = { remote: true, transport: 'stdio' as const, sourceId: 'default' };

function parsed(result: { content: Array<{ text: string }> }) {
  return JSON.parse(result.content[0].text);
}

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
  // #4655: pin the active pack via the DB plane (tier-4) so the write-time
  // vocabulary checks resolve gbrain-base regardless of the host's file config.
  await engine.setConfig('schema_pack', 'gbrain-base');
});

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

describe('capture op', () => {
  test('captures a note under a stable inbox/ slug and stamps provenance server-side', async () => {
    const content = 'Decided to use PGLite as the default engine: zero-config wins.';
    const request_id = randomUUID();
    const res = await dispatchToolCall(engine, 'capture', { content, request_id }, { ...STDIO });
    expect(res.isError ?? false).toBe(false);
    const body = parsed(res);
    expect(body.slug).toMatch(/^inbox\/\d{4}-\d{2}-\d{2}-[0-9a-f]{8}$/);
    expect(body.channel).toBe('capture');
    expect(typeof body.content_hash).toBe('string');

    const page = await engine.getPage(body.slug);
    expect(page).toBeTruthy();
    // CV6: remote provenance is frozen server-side at capture admission.
    expect(page?.source_kind).toBe('mcp:capture');
    // Frontmatter merged as a single stamped block.
    expect(page?.frontmatter?.captured_at).toBeDefined();

    // Same-ID replay retains the accepted target and timestamp. A fresh
    // create-only request cannot silently replace that existing target: since
    // #5385 the refusal is `revision_required` (the page exists and the call
    // named no expected_revision), no longer the stale-revision code.
    const again = parsed(await dispatchToolCall(engine, 'capture', { content, request_id }, { ...STDIO }));
    expect(again.slug).toBe(body.slug);
    expect(again.content_hash).toBe(body.content_hash);
    const fresh = await dispatchToolCall(engine, 'capture', { content: `  ${content}\r\n` }, { ...STDIO });
    expect(fresh.isError).toBe(true);
    expect(parsed(fresh).write_error).toBe('revision_required');
  });

  test('type routes the default slug prefix (diary → life/diary/)', async () => {
    const body = parsed(await dispatchToolCall(engine, 'capture', {
      content: 'Long day, good demo.', type: 'diary',
    }, { ...STDIO }));
    expect(body.slug).toMatch(/^life\/diary\/\d{4}-\d{2}-\d{2}-[0-9a-f]{8}$/);
  });

  // #4655: EXPLICIT undeclared page types are rejected fail-loud, naming the
  // pack and its declared vocabulary. STDIO carries remote: true, so these
  // double as the remote-caller negative tests for the changed op.
  test('rejects an undeclared explicit page type before writing (remote)', async () => {
    const slug = 'inbox/capture-bad-explicit-type';
    const body = parsed(await dispatchToolCall(engine, 'capture', {
      content: 'This should not be written.',
      slug,
      type: 'definitely_not_a_type',
    }, { ...STDIO }));
    expect(body.error).toBe('invalid_params');
    expect(body.message).toContain("page type 'definitely_not_a_type' is not declared");
    expect(body.message).toContain('gbrain-base');
    // The suggestion names the declared vocabulary so agents self-correct.
    expect(body.suggestion).toContain('Use a declared page type');
    expect(body.suggestion).toContain('analysis');
    expect(await engine.getPage(slug)).toBeNull();
  });

  test('rejects an undeclared frontmatter page type before writing (remote)', async () => {
    const slug = 'inbox/capture-bad-frontmatter-type';
    const body = parsed(await dispatchToolCall(engine, 'capture', {
      content: '---\ntype: definitely_not_a_type\n---\n\nThis should not be written.',
      slug,
    }, { ...STDIO }));
    expect(body.error).toBe('invalid_params');
    expect(body.message).toContain("page type 'definitely_not_a_type' is not declared");
    expect(await engine.getPage(slug)).toBeNull();
  });

  // Ship-review fix on the #4721 rework: with no `type` param the handler
  // used to validate the frontmatter's explicit type against the pack, then
  // hand the defaulted 'note' to mergeCaptureFrontmatter (opts.type wins) —
  // so a capture APPROVED as 'person' was STORED as 'note'. The effective
  // type is the validated explicit/frontmatter type when present, else
  // 'note', and it drives both the stamp and the default-slug prefix.
  test('frontmatter type is the stored type when no type param is given', async () => {
    const slug = 'inbox/capture-frontmatter-type-kept';
    const body = parsed(await dispatchToolCall(engine, 'capture', {
      content: '---\ntype: person\ntitle: Alice Example\n---\n\nDeclared frontmatter type, no explicit param.',
      slug,
    }, { ...STDIO }));
    expect(body.error).toBeUndefined();
    const page = await engine.getPage(slug);
    // put_page lifts the stamped frontmatter `type` into the type column.
    expect(page?.type).toBe('person');
  });

  test('the default-slug prefix follows the frontmatter type (diary → life/diary/)', async () => {
    const body = parsed(await dispatchToolCall(engine, 'capture', {
      content: '---\ntype: diary\n---\n\nFrontmatter diary, no explicit param.',
    }, { ...STDIO }));
    expect(body.error).toBeUndefined();
    expect(body.slug).toMatch(/^life\/diary\/\d{4}-\d{2}-\d{2}-[0-9a-f]{8}$/);
    expect((await engine.getPage(body.slug))?.type).toBe('diary');
  });

  test('no frontmatter and no type param still stamps note; an explicit type param beats frontmatter', async () => {
    const plain = parsed(await dispatchToolCall(engine, 'capture', {
      content: 'Plain body, nothing declared.', slug: 'inbox/capture-plain-note',
    }, { ...STDIO }));
    expect((await engine.getPage(plain.slug))?.type).toBe('note');
    const explicit = parsed(await dispatchToolCall(engine, 'capture', {
      content: '---\ntype: person\n---\n\nParam wins over frontmatter.',
      slug: 'inbox/capture-param-beats-frontmatter',
      type: 'meeting',
    }, { ...STDIO }));
    expect(explicit.error).toBeUndefined();
    expect((await engine.getPage(explicit.slug))?.type).toBe('meeting');
  });

  test('NUL byte and empty content are refused with named errors', async () => {
    const nul = parsed(await dispatchToolCall(engine, 'capture', { content: 'ab\u0000cd' }, { ...STDIO }));
    expect(nul.error).toBe('invalid_params');
    expect(nul.message).toContain('NUL');
    const empty = parsed(await dispatchToolCall(engine, 'capture', { content: '   \n  ' }, { ...STDIO }));
    expect(empty.error).toBe('invalid_params');
    expect(empty.message).toContain('empty');
  });

  test('[EV7] fenced client: default slug nests under the first bound prefix', async () => {
    const auth: AuthInfo = { token: 't', clientId: 'fenced-agent', scopes: ['write'], boundSlugPrefixes: ['wiki/agents/x/'] };
    const body = parsed(await dispatchToolCall(engine, 'capture', { content: 'fenced note' }, {
      ...STDIO, auth,
    }));
    expect(body.slug).toMatch(/^wiki\/agents\/x\/inbox\/\d{4}-\d{2}-\d{2}-[0-9a-f]{8}$/);
    // An explicit out-of-fence slug still denies via the inherited fence.
    const denied = parsed(await dispatchToolCall(engine, 'capture', {
      content: 'escape attempt', slug: 'inbox/escape',
    }, { ...STDIO, auth }));
    expect(denied.error).toBe('permission_denied');
  });

  test('[EV7] fenced client + typed capture: the ENTIRE default slug (type prefix included) nests under the bound prefix', async () => {
    const auth: AuthInfo = { token: 't', clientId: 'fenced-agent', scopes: ['write'], boundSlugPrefixes: ['wiki/agents/x/'] };
    const body = parsed(await dispatchToolCall(engine, 'capture', {
      content: 'fenced diary note', type: 'diary',
    }, { ...STDIO, auth }));
    expect(body.slug).toMatch(/^wiki\/agents\/x\/life\/diary\/\d{4}-\d{2}-\d{2}-[0-9a-f]{8}$/);
    expect(body.slug).not.toContain('diary/diary');
  });

  test('dry_run short-circuits before any write', async () => {
    const body = parsed(await dispatchToolCall(engine, 'capture', { content: 'dry note', dry_run: true }, { ...STDIO }));
    expect(body.dry_run).toBe(true);
    const page = await engine.getPage(body.slug);
    expect(page).toBeNull();
  });
});