Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* list_pages silent-truncation seal.
*
* The op defaults limit to 50 and clamps remote callers to max 100 (local
* explicit limits are honored since #3322 — pinned in
* test/list-clamp-local-trust.test.ts). Pre-fix, a caller whose limit was
* defaulted (or remotely clamped) received a full-looking array with NO
* signal that rows were dropped, and with the default updated_desc sort the
* dropped rows are always the OLDEST — precisely what exhaustive consumers
* (audits, scans, backfills) exist to find.
*
* Covers, at the op-handler layer (engine listPages surface unchanged —
* the handler only probes limit+1):
* - default-limit truncation returns exactly 50 rows and warns on stderr
* (local ctx only)
* - an explicit, honored limit does NOT warn (ordinary pagination)
* - a clamped-but-complete result (requested > cap, rows ≤ cap) does NOT
* warn — nothing was dropped
* - remote ctx never writes to stderr (MCP server logs stay clean)
* - the pagination recipe in LIST_PAGES_DESCRIPTION (sort=updated_asc +
* updated_after cursor) actually enumerates every row to completion
* - remote callers get the same facts on the `pagination` response meta
* (truncated, limit, clamped_from, next), and MCP dispatch adds the
* model-visible `listing_truncated` notice while content[0] stays the
* bare array (#5954, agent contract v1 F3b)
*
* Runs against PGLite in-memory (both engines share the SQL surface; the
* handler change touches no engine code).
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach, spyOn } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { resetPgliteState } from './helpers/reset-pglite.ts';
import { operations, type OperationContext } from '../src/core/operations.ts';
import { dispatchToolCall, __resetBackupNoticeForTests } from '../src/mcp/dispatch.ts';
import { __resetFactsDrainNoticesForTests } from '../src/core/facts/drain.ts';
import { withEnv } from './helpers/with-env.ts';
import { __resetBehaviorNoticeForTests } from '../src/core/behavior-change-notice.ts';
import { mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { ListPagesPagination } from '../src/core/ops/list-pages-pagination.ts';
const list_pages = operations.find(o => o.name === 'list_pages')!;
let engine: PGLiteEngine;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({});
await engine.initSchema();
});
afterAll(async () => { await engine.disconnect(); });
beforeEach(async () => { await resetPgliteState(engine); });
function ctxOf(overrides: Partial<OperationContext> = {}): OperationContext {
return {
engine: engine as any,
config: {} as any,
logger: console as any,
dryRun: false,
remote: false,
sourceId: 'default',
...overrides,
};
}
const page = (n: number) => ({
type: 'note' as const,
title: `Note ${String(n).padStart(3, '0')}`,
compiled_truth: `Body of note ${n}.`,
timeline: '',
frontmatter: {},
});
async function seed(count: number) {
for (let i = 1; i <= count; i++) {
await engine.putPage(`notes/note-${String(i).padStart(3, '0')}`, page(i), { sourceId: 'default' });
}
}
/** Run the handler while capturing stderr writes made through console.error. */
async function runCapturing(ctx: OperationContext, params: Record<string, unknown>) {
const spy = spyOn(console, 'error').mockImplementation(() => {});
try {
const result = await list_pages.handler(ctx, params) as any[];
const warnings = spy.mock.calls.map(args => args.join(' ')).filter(s => s.includes('[list_pages]'));
return { result, warnings };
} finally {
spy.mockRestore();
}
}
describe('list_pages truncation signal', () => {
test('default limit: 51 rows → exactly 50 returned + stderr warning', async () => {
await seed(51);
const { result, warnings } = await runCapturing(ctxOf(), {});
expect(result.length).toBe(50);
expect(warnings.length).toBe(1);
expect(warnings[0]).toContain('truncated at 50 rows');
expect(warnings[0]).toContain('updated_after_slug');
}, 30_000);
test('explicit honored limit: no warning even when more rows exist', async () => {
await seed(12);
const { result, warnings } = await runCapturing(ctxOf(), { limit: 10 });
expect(result.length).toBe(10);
expect(warnings.length).toBe(0);
}, 30_000);
test('clamped but complete: requested > cap with rows ≤ cap → all rows, no warning', async () => {
await seed(12);
const { result, warnings } = await runCapturing(ctxOf(), { limit: 200 });
expect(result.length).toBe(12);
expect(warnings.length).toBe(0);
}, 30_000);
test('local explicit limit above 100 is honored (#3322) — all rows, no warning', async () => {
await seed(101);
const { result, warnings } = await runCapturing(ctxOf(), { limit: 200 });
expect(result.length).toBe(101);
expect(warnings.length).toBe(0);
}, 60_000);
test('remote requested above cap: clamped to 100, truncation stays off stderr', async () => {
await seed(101);
const { result, warnings } = await runCapturing(ctxOf({ remote: true }), { limit: 200 });
expect(result.length).toBe(100);
// The #3322 clamp warning goes through ctx.logger.warn; the [list_pages]
// truncation hint is local-only, so console.error stays clean here.
expect(warnings.length).toBe(0);
}, 60_000);
test('remote ctx: truncation stays silent on stderr (MCP logs clean)', async () => {
await seed(51);
const { result, warnings } = await runCapturing(ctxOf({ remote: true }), {});
expect(result.length).toBe(50);
expect(warnings.length).toBe(0);
}, 30_000);
test('documented cursor recipe enumerates all rows to completion', async () => {
await seed(23);
// Spread updated_at deterministically: back-to-back putPage calls can land
// on identical timestamps, and a strict `updated_at > cursor` walk would
// then skip the tied rows — that would be a flake in THIS test, not a
// property of the recipe (real corpora update over time).
await engine.executeRaw(
`UPDATE pages SET updated_at = now() - (interval '1 minute' * (100 - id)) WHERE slug LIKE 'notes/note-%'`,
);
const seen = new Set<string>();
let cursor: string | undefined;
// sort=updated_asc + updated_after=<last row's updated_at>, stop when a
// page returns fewer rows than the limit — verbatim the recipe in
// LIST_PAGES_DESCRIPTION.
for (let guard = 0; guard < 10; guard++) {
const params: Record<string, unknown> = { limit: 10, sort: 'updated_asc' };
if (cursor !== undefined) params.updated_after = cursor;
const { result } = await runCapturing(ctxOf(), params);
for (const row of result) seen.add(row.slug);
if (result.length < 10) break;
cursor = result[result.length - 1].updated_at instanceof Date
? result[result.length - 1].updated_at.toISOString()
: String(result[result.length - 1].updated_at);
}
expect(seen.size).toBe(23);
}, 30_000);
});
// The stderr notice above is local-only and the remote clamp warning goes to
// the server log, so before #5954 a remote caller holding exactly `limit`
// rows could not tell a full page from a complete listing.
describe('list_pages pagination meta for remote callers', () => {
function remote(params: Record<string, unknown>) {
const meta: Record<string, unknown> = {};
const notices: unknown[] = [];
const ctx = ctxOf({ remote: true, emitResponseMeta: (key, value) => { meta[key] = value; }, emitNotice: n => { notices.push(n); } });
return runCapturing(ctx, params).then(({ result }) => ({ result, notices, pagination: meta.pagination as ListPagesPagination }));
}
test('limit below the row count: truncated, with an offset continuation', async () => {
await seed(12);
const { result, pagination } = await remote({ limit: 10 });
expect(result.length).toBe(10);
expect(pagination).toEqual({ truncated: true, limit: 10, next: { offset: 10 } });
}, 30_000);
test('limit above the remote cap: clamped_from carries the requested limit', async () => {
await seed(101);
const { result, pagination } = await remote({ limit: 200 });
expect(result.length).toBe(100);
expect(pagination).toEqual({ truncated: true, limit: 100, clamped_from: 200, next: { offset: 100 } });
}, 60_000);
test('complete listing: truncated false, no next, no notice', async () => {
await seed(5);
const { result, pagination, notices } = await remote({ limit: 10 });
expect(result.length).toBe(5);
expect(pagination).toEqual({ truncated: false, limit: 10 });
expect(notices).toEqual([]);
}, 30_000);
test('updated_asc: next is the keyset of the last row', async () => {
await seed(12);
const { result, pagination } = await remote({ limit: 10, sort: 'updated_asc' });
const last = result[result.length - 1];
expect(pagination.next).toEqual({ sort: 'updated_asc', updated_after: last.updated_at_iso, updated_after_slug: last.slug });
}, 30_000);
test('following the notice fix until no notice comes back enumerates every row exactly once', async () => {
await seed(23);
// updated_asc pages a bulk-sync cluster (one shared timestamp) through the
// keyset; offset under updated_desc needs distinct timestamps, which has
// no tiebreaker.
const cases: Array<[Record<string, unknown>, string]> = [
[{ sort: 'updated_asc' }, `UPDATE pages SET updated_at = '2026-08-10T12:00:00.000123Z'::timestamptz WHERE slug LIKE 'notes/note-%'`],
[{}, `UPDATE pages SET updated_at = now() - (interval '1 minute' * (100 - id)) WHERE slug LIKE 'notes/note-%'`],
];
for (const [base, spread] of cases) {
await engine.executeRaw(spread);
const seen: string[] = [];
let params: Record<string, unknown> = { ...base, limit: 10 };
for (let guard = 0; guard < 10; guard++) {
const { result, notices } = await remote(params);
seen.push(...result.map(r => r.slug as string));
const notice = notices[0] as { code: string; fix: { mcp: { tool: string; arguments: Record<string, unknown> } } } | undefined;
if (!notice) break;
expect(notice.code).toBe('listing_truncated');
expect(notice.fix.mcp.tool).toBe('list_pages');
params = notice.fix.mcp.arguments;
}
expect(seen.length).toBe(23);
expect(new Set(seen).size).toBe(23);
}
}, 60_000);
test('local CLI callers get no notice (stderr stays their channel)', async () => {
await seed(12);
const notices: unknown[] = [];
await runCapturing(ctxOf({ remote: false, emitNotice: n => { notices.push(n); } }), { limit: 10 });
expect(notices).toEqual([]);
}, 30_000);
test('MCP dispatch: content[0] stays the bare array; the listing_truncated notice names the next call', async () => {
__resetBackupNoticeForTests();
__resetFactsDrainNoticesForTests();
await seed(12);
// Once-per-process notices (backup coverage, post-upgrade, a pending facts-drain notice) depend on what other tests
// in the same shard leave behind; switch them off or clear them so this test counts only the listing notice.
// The one-time behavior_changes disclosure fires on a brain older than its fresh-install grace (the restored PGLite
// snapshot is), once per brain per GBRAIN_HOME; a fresh brain in its own GBRAIN_HOME never owes it.
await engine.executeRaw('UPDATE sources SET created_at = now()');
__resetBehaviorNoticeForTests();
const noticeHome = mkdtempSync(join(tmpdir(), 'gbrain-list-pages-notice-'));
await withEnv({ GBRAIN_BACKUP_CHECK: 'off', GBRAIN_NO_ONBOARD_NUDGE: '1', GBRAIN_HOME: noticeHome }, async () => {
const opts = { remote: true, transport: 'stdio' as const, sourceId: 'default' };
const res = await dispatchToolCall(engine as any, 'list_pages', { limit: 10, type: 'note' }, opts);
expect(res.isError).toBeUndefined();
expect(JSON.parse(res.content[0].text)).toHaveLength(10);
expect(res.content).toHaveLength(2);
expect(res.content[1].text.split('\n')[0]).toBe('[gbrain notice listing_truncated kind=info]');
expect(res.content[1].text).toContain('fix: list_pages {"type":"note","limit":10,"offset":10}');
expect(res.content[1].text).toContain('next: run');
expect(res._meta?.pagination).toEqual({ truncated: true, limit: 10, next: { offset: 10 } });
// Per-call notice: never deduped, so the second truncated page carries it too.
const again = await dispatchToolCall(engine as any, 'list_pages', { limit: 10, type: 'note' }, opts);
expect(again.content).toHaveLength(2);
const complete = await dispatchToolCall(engine as any, 'list_pages', { limit: 20 }, opts);
expect(complete.content).toHaveLength(1);
expect(complete._meta?.pagination).toEqual({ truncated: false, limit: 20 });
});
}, 30_000);
});