Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.0 KB
Raw Blame
/**
 * #6007: put_pages — the batch write path for remote agents, plus put_page's
 * transport-only wait_ms. Every page is an ordinary put_page write request
 * admitted with the others in one transaction; a replay of the identical
 * batch writes nothing new, a changed batch is refused, and put_pages with
 * only its request_id reads progress without resending content.
 */
import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
import { randomUUID } from 'node:crypto';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { operations, type OperationContext } from '../src/core/operations.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
import { pageBatchChildRequestId, PAGE_BATCH_MAX_PAGES } from '../src/core/persistence/page-batch.ts';
import { journalLimitKey } from '../src/core/persistence/limits.ts';
import { pendingWriteHint } from '../src/core/persistence/health.ts';
import { buildMcpInstructions } from '../src/mcp/instructions.ts';

const putPages = operations.find(op => op.name === 'put_pages')!;
const putPage = operations.find(op => op.name === 'put_page')!;
let engine: PGLiteEngine;

const ctx = (extra: Partial<OperationContext> = {}): OperationContext => ({
  engine, config: { engine: 'pglite', embedding_disabled: true } as any,
  logger: { info() {}, warn() {}, error() {} }, dryRun: false, remote: true, sourceId: 'default', ...extra,
} as OperationContext);
const page = (slug: string, body = 'Body text.') => ({ slug, content: `---\ntype: note\ntitle: ${slug}\n---\n\n${body}\n` });
const requestCount = async () => Number((await engine.executeRaw<{ n: number }>('SELECT count(*)::int AS n FROM persistence_requests'))[0]!.n);

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
}, 60_000);
afterAll(async () => { await disposePersistenceConsumer(engine); await engine.disconnect(); });
beforeEach(async () => { await disposePersistenceConsumer(engine); await resetPgliteState(engine); });

describe('put_pages', () => {
  test('commits every page with one receipt and deterministic child request ids', async () => {
    const batch = randomUUID();
    const result = await putPages.handler(ctx(), { request_id: batch, pages: [page('notes/a'), page('notes/b'), page('notes/c')] }) as any;
    expect(result).toMatchObject({ batch_request_id: batch, state: 'committed', terminal: true,
      counts: { total: 3, committed: 3, pending: 0, failed: 0 }, next: { action: 'done' } });
    expect(result.pages.map((p: any) => [p.index, p.slug, p.state, p.request_id])).toEqual(
      ['notes/a', 'notes/b', 'notes/c'].map((slug, index) => [index, slug, 'committed', pageBatchChildRequestId(batch, index)]));
    for (const slug of ['notes/a', 'notes/b', 'notes/c']) expect(await engine.readPageSnapshot(slug, { sourceId: 'default' })).not.toBeNull();
  });

  test('an identical replay writes nothing new; status-only reads the same receipt', async () => {
    const batch = randomUUID();
    const pages = [page('notes/r1'), page('notes/r2')];
    const first = await putPages.handler(ctx(), { request_id: batch, pages }) as any;
    const count = await requestCount();
    const replay = await putPages.handler(ctx(), { request_id: batch, pages, wait_ms: 1000 }) as any;
    expect(await requestCount()).toBe(count);
    expect(replay.pages.map((p: any) => p.revision)).toEqual(first.pages.map((p: any) => p.revision));
    const status = await putPages.handler(ctx(), { request_id: batch }) as any;
    expect(status).toMatchObject({ state: 'committed', counts: { total: 2, committed: 2 } });
    expect(status.pages.map((p: any) => p.slug)).toEqual(['notes/r1', 'notes/r2']);
  });

  test('a changed replay is refused and admits nothing', async () => {
    const batch = randomUUID();
    await putPages.handler(ctx(), { request_id: batch, pages: [page('notes/c1'), page('notes/c2')] });
    const count = await requestCount();
    await expect(putPages.handler(ctx(), { request_id: batch, pages: [page('notes/c1'), page('notes/c2', 'Changed.')] }))
      .rejects.toMatchObject({ code: 'idempotency_conflict', message: expect.stringContaining('notes/c2') });
    await expect(putPages.handler(ctx(), { request_id: batch, pages: [page('notes/c1'), page('notes/c2'), page('notes/c3')] }))
      .rejects.toMatchObject({ code: 'idempotency_conflict', message: expect.stringContaining('2 pages') });
    expect(await requestCount()).toBe(count);
    expect(await engine.readPageSnapshot('notes/c3', { sourceId: 'default' })).toBeNull();
  });

  test('a page refused before admission does not stop the others', async () => {
    const result = await putPages.handler(ctx(), { request_id: randomUUID(), pages: [page('notes/ok'), page('../escape')] }) as any;
    expect(result).toMatchObject({ state: 'partial', terminal: true, counts: { committed: 1, failed: 1 }, next: { action: 'fix_pages' } });
    expect(result.pages[1]).toMatchObject({ slug: '../escape', state: 'refused', error: { code: expect.any(String) } });
    expect(await engine.readPageSnapshot('notes/ok', { sourceId: 'default' })).not.toBeNull();
  });

  test('caps and a missing request_id refuse before anything is written', async () => {
    const count = await requestCount();
    const tooMany = Array.from({ length: PAGE_BATCH_MAX_PAGES + 1 }, (_, i) => page(`notes/m${i}`));
    await expect(putPages.handler(ctx(), { request_id: randomUUID(), pages: tooMany })).rejects.toMatchObject({ code: 'invalid_params' });
    await expect(putPages.handler(ctx(), { request_id: randomUUID(), pages: [page('notes/huge', 'x'.repeat(9 * 1024 * 1024))] }))
      .rejects.toMatchObject({ code: 'invalid_params', message: expect.stringContaining('bytes') });
    await expect(putPages.handler(ctx(), { request_id: randomUUID(), pages: [{ ...page('notes/k'), kind: 'managed_file_import' }] }))
      .rejects.toMatchObject({ code: 'invalid_params' });
    await expect(putPages.handler(ctx(), { pages: [page('notes/n')] })).rejects.toMatchObject({ code: 'invalid_params' });
    await expect(putPages.handler(ctx(), { request_id: randomUUID() })).rejects.toMatchObject({ code: 'not_found' });
    expect(await requestCount()).toBe(count);
  });

  test('a byte-identical repeat of a slug is one write; status and replay report it as a repeat', async () => {
    const batch = randomUUID();
    const pages = [page('notes/same', 'One session.'), page('notes/other'), page('notes/same', 'One session.')];
    const before = await requestCount();
    const result = await putPages.handler(ctx(), { request_id: batch, pages }) as any;
    expect(result).toMatchObject({ state: 'committed', terminal: true, counts: { total: 3, committed: 3, failed: 0 }, next: { action: 'done' } });
    expect(result.pages[2]).toMatchObject({ index: 2, slug: 'notes/same', state: 'committed', repeat_of: 0, request_id: result.pages[0].request_id, revision: result.pages[0].revision });
    expect(result.pages[0].repeat_of).toBeUndefined();
    expect(await requestCount()).toBe(before + 2);
    const status = await putPages.handler(ctx(), { request_id: batch }) as any;
    expect(status.pages.map((p: any) => [p.index, p.slug, p.state, p.repeat_of])).toEqual([[0, 'notes/same', 'committed', undefined], [1, 'notes/other', 'committed', undefined], [2, 'notes/same', 'committed', 0]]);
    await putPages.handler(ctx(), { request_id: batch, pages, wait_ms: 1000 });
    expect(await requestCount()).toBe(before + 2);
  });

  test('repeats of a slug that differ are each refused with their own error; the rest of the batch is written', async () => {
    const result = await putPages.handler(ctx(), { request_id: randomUUID(), pages: [page('notes/x', 'First.'), page('notes/y'), page('notes/x', 'Second.'), page('Notes/X', 'First.')] }) as any;
    expect(result).toMatchObject({ state: 'partial', terminal: true, counts: { total: 4, committed: 1, failed: 3 }, next: { action: 'fix_pages' } });
    expect(result.pages[1]).toMatchObject({ slug: 'notes/y', state: 'committed' });
    for (const index of [0, 2, 3]) {
      expect(result.pages[index]).toMatchObject({ state: 'refused', error: { code: 'invalid_params' } });
      expect(result.pages[index].error.message).toContain(`pages[${index}]`);
    }
    expect(result.pages[0].error.message).toContain('pages[2], pages[3]');
    expect(await engine.readPageSnapshot('notes/x', { sourceId: 'default' })).toBeNull();
    expect(await engine.readPageSnapshot('notes/y', { sourceId: 'default' })).not.toBeNull();
  });

  test('capacity is reserved for the whole batch or none of it', async () => {
    await engine.setConfig(journalLimitKey('principalOutstanding'), '2');
    try {
      await expect(putPages.handler(ctx(), { request_id: randomUUID(), wait_ms: 0, pages: [page('notes/q1'), page('notes/q2'), page('notes/q3')] }))
        .rejects.toMatchObject({ code: 'queue_capacity', message: expect.stringContaining('No page of batch') });
      expect(await engine.executeRaw("SELECT 1 FROM persistence_requests WHERE slug LIKE 'notes/q%'")).toEqual([]);
    } finally {
      await engine.unsetConfig(journalLimitKey('principalOutstanding'));
    }
  });

  test('#6696 (A6): a batch past a cumulative cap refuses write_quota_exhausted with the host raise, not the outstanding wait', async () => {
    const [{ used }] = await engine.executeRaw<{ used: number }>("SELECT COALESCE(max(lifetime_ids),0)::int AS used FROM persistence_counters WHERE key LIKE 'principal:%'");
    await engine.setConfig(journalLimitKey('principalLifetimeIds'), String(used + 2));
    try {
      const refusal = await putPages.handler({ ...ctx(), admissionOrigin: 'interactive' }, { request_id: randomUUID(), wait_ms: 0,
        pages: [page('notes/w1'), page('notes/w2'), page('notes/w3')] }).then(() => null, error => error);
      expect(refusal).toMatchObject({ code: 'write_quota_exhausted', reason: 'lifetime_ids', fix: { actor: 'host_admin' } });
      expect(refusal.suggestion).not.toContain('Wait for this connection');
      expect(await engine.executeRaw("SELECT 1 FROM persistence_requests WHERE slug LIKE 'notes/w%'")).toEqual([]);
    } finally {
      await engine.unsetConfig(journalLimitKey('principalLifetimeIds'));
    }
  });

  test('every page needs put_page permission', async () => {
    const clientId = 'put-pages-batch-only';
    await engine.executeRaw(`INSERT INTO oauth_clients(client_id,client_name,scope,source_id,allowed_operations)
      VALUES($1,'Batch-only fixture','read write','default',$2)`, [clientId, ['put_pages']]);
    const caller = ctx({ auth: { token: 'synthetic', clientId, principal: { kind: 'oauth_client', id: clientId },
      sourceId: 'default', scopes: ['read', 'write'], allowedOperations: ['put_pages'] } as any });
    await expect(putPages.handler(caller, { request_id: randomUUID(), pages: [page('notes/denied'), page('notes/denied-2')] }))
      .rejects.toMatchObject({ code: 'permission_denied' });
    expect(await engine.readPageSnapshot('notes/denied', { sourceId: 'default' })).toBeNull();
  });
});

describe('put_pages links', () => {
  test('forward references inside a batch become mention links without a status poll', async () => {
    const batch = randomUUID();
    const result = await putPages.handler(ctx(), { request_id: batch, pages: [
      page('notes/fwd-a', 'See [[notes/fwd-b]] for details.'), page('notes/fwd-b', 'Back to [[notes/fwd-a]].')] }) as any;
    expect(result.state).toBe('committed');
    const edges = async () => engine.executeRaw<{ edge: string }>(`SELECT f.slug || '>' || t.slug AS edge FROM links l
      JOIN pages f ON f.id=l.from_page_id JOIN pages t ON t.id=l.to_page_id WHERE l.link_source='mcp-remote-mention' ORDER BY 1`);
    const deadline = Date.now() + 15_000;
    while ((await edges()).length < 2 && Date.now() < deadline) await Bun.sleep(100);
    expect((await edges()).map(row => row.edge)).toEqual(['notes/fwd-a>notes/fwd-b', 'notes/fwd-b>notes/fwd-a']);
    // The last page's publication re-armed every page's links pass once, so an
    // earlier page whose pass ran before its target existed is linked anyway.
    const rearmed = await engine.executeRaw<{ n: number }>("SELECT count(*)::int AS n FROM persistence_effects WHERE kind='links' AND data ? 'batch_reconciled'");
    expect(rearmed[0]!.n).toBe(2);
  }, 30_000);
});

describe('put_page wait_ms', () => {
  test('is not part of the write identity: a replay with another wait is not a conflict', async () => {
    const request_id = randomUUID();
    const first = await putPage.handler(ctx(), { ...page('notes/w'), request_id, wait_ms: 20000 }) as any;
    const replay = await putPage.handler(ctx(), { ...page('notes/w'), request_id }) as any;
    expect(replay.revision ?? replay.write_request?.revision).toBe(first.revision ?? first.write_request?.revision);
    const [row] = await engine.executeRaw<{ intent: Record<string, unknown> }>('SELECT intent FROM persistence_requests WHERE request_id=$1::uuid', [request_id]);
    expect(row!.intent).not.toHaveProperty('wait_ms');
  });

  test('out of range refuses with invalid_write_wait before admission', async () => {
    const request_id = randomUUID();
    await expect(putPage.handler(ctx(), { ...page('notes/wx'), request_id, wait_ms: 30_001 })).rejects.toMatchObject({ code: 'invalid_write_wait' });
    await expect(putPage.handler(ctx(), { ...page('notes/wx'), request_id, wait_ms: -1 })).rejects.toMatchObject({ code: 'invalid_write_wait' });
    expect(await engine.executeRaw('SELECT 1 FROM persistence_requests WHERE request_id=$1::uuid', [request_id])).toEqual([]);
  });

  test('a caller cannot forge batch membership through put_page', async () => {
    const request_id = randomUUID();
    await putPage.handler(ctx(), { ...page('notes/forged'), request_id, page_batch: { id: randomUUID(), index: 0, size: 1 } });
    const [row] = await engine.executeRaw<{ intent: Record<string, unknown> }>('SELECT intent FROM persistence_requests WHERE request_id=$1::uuid', [request_id]);
    expect(row!.intent).not.toHaveProperty('page_batch');
  });
});

describe('agent guidance', () => {
  const all = (name: string) => name !== '__none__';
  test('instructions name put_pages and wait_ms only when callable', () => {
    expect(buildMcpInstructions({ tools: { callable: all } })).toContain('use put_pages');
    expect(buildMcpInstructions({ tools: { callable: all } })).toContain('wait_ms');
    const pageOnly = buildMcpInstructions({ tools: { callable: name => name !== 'put_pages' } });
    expect(pageOnly).not.toContain('put_pages');
    expect(pageOnly).toContain('wait_ms');
    const readOnly = buildMcpInstructions({ tools: { callable: name => !['put_page', 'put_pages'].includes(name) } });
    expect(readOnly).not.toContain('wait_ms');
  });

  test('a pending put_page names wait_ms and put_pages; other verbs do not', () => {
    const receipt = { request_id: randomUUID(), state: 'queued', retry_after_ms: 800 } as any;
    expect(pendingWriteHint(receipt, 'put_page')).toContain('wait_ms');
    expect(pendingWriteHint(receipt, 'put_page')).toContain('put_pages');
    expect(pendingWriteHint(receipt, 'remember')).not.toContain('put_pages');
  });
});