Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Atoms-array ANCHOR SCAN (`parseAtomsOutcomeInner`).
*
* The extractor used to commit to `cleaned.indexOf('[')` — the FIRST left
* bracket anywhere in the response. Any bracket in a preamble hijacked that
* anchor, so a response carrying a perfectly good atoms array was reported as
* `unparseable JSON array` and the page counted a deterministic failure.
*
* This is not a hypothetical: a brain whose house style mandates inline
* `[Source: …]` citations and `[[wikilink]]` backlinks, and whose transcripts
* carry `[user]` / `[assistant]` / `[tool: …]` role markers, hands the model
* bracketed prose to echo while it narrates its answer.
*
* THE HAZARD the scan must avoid: `atomsFromParsedArray` skips every element
* failing the shape gate, so a parseable-but-wrong array (say an array of
* strings lifted out of prose) yields `ok: true, atoms: []`. A zero-yield
* result is what TOMBSTONES a page (#2144), so a shape-blind scan would
* permanently retire pages that still had real content — worse than the bug.
* Acceptance therefore requires >= 1 atom-shaped element, not mere parseability.
*
* NOTE: assertions go through the PUBLIC `parseAtomsOutcome` entry point, which
* exists pre-fix, so a reverted-source run fails on BEHAVIOUR rather than dying
* with a module-load SyntaxError (the vacuous failure class in CONTRIBUTING.md).
*/
import { describe, expect, test } from 'bun:test';
import { parseAtomsOutcome } from '../src/core/cycle/extract-atoms.ts';
/** A minimally valid atom: title + atom_type (in ATOM_TYPES) + body. */
const ATOM = {
title: 'Brackets in prose hijack the parse anchor',
atom_type: 'insight',
body: 'The extractor anchored on the first bracket, not the first array.',
};
const ATOM_ARRAY = JSON.stringify([ATOM]);
function atomsOf(raw: string) {
const outcome = parseAtomsOutcome(raw);
if (!outcome.ok) throw new Error(`expected ok, got reason: ${outcome.reason}`);
return outcome.atoms;
}
describe('anchor scan — bracketed preamble no longer hijacks the parse', () => {
test('recovers the array after a preamble carrying a [Source: …] citation', () => {
const raw =
'Looking at the page, the claim is supported by ' +
'[Source: alice-example, agent session, 2026-09-03], so here are the atoms:\n' +
ATOM_ARRAY;
expect(atomsOf(raw)).toHaveLength(1);
expect(atomsOf(raw)[0]!.title).toBe(ATOM.title);
});
test('recovers the array after a preamble naming a [[wikilink]]', () => {
const raw = 'The page backlinks [[people/alice-example]] and [[companies/acme-example]].\n' + ATOM_ARRAY;
expect(atomsOf(raw)).toHaveLength(1);
});
test('recovers the array after a transcript [user] role marker in the preamble', () => {
const raw = 'The [user] turn sets up the problem and [assistant] answers it.\n' + ATOM_ARRAY;
expect(atomsOf(raw)).toHaveLength(1);
});
test('preamble recovery: a parseable-but-WRONG array ahead of the real one is skipped', () => {
// `["a","b"]` parses cleanly but yields no atom, so the scan moves on and
// recovers the real payload below. The first-bracket offset parses on its
// own (bounded to `["a","b"]`) and the SHAPE GATE rejects it, so this pins
// recovery; the gate itself is pinned directly further down.
const raw = 'Candidate labels were ["a","b"] before I settled on:\n' + ATOM_ARRAY;
const atoms = atomsOf(raw);
expect(atoms).toHaveLength(1);
expect(atoms[0]!.title).toBe(ATOM.title);
});
test('preamble recovery: an array of atom-shaped-but-empty objects ahead of the real one is skipped', () => {
// Objects, but every one fails the shape gate (no title/atom_type/body).
const raw = 'Draft skeleton: [{"note":"tbd"},{"note":"tbd"}] — final answer:\n' + ATOM_ARRAY;
expect(atomsOf(raw)).toHaveLength(1);
});
});
describe('anchor scan — the shape gate is what accepts a candidate (atoms.length > 0)', () => {
// THE HAZARD, pinned directly. In each case a later offset holds an array
// that PARSES but yields zero atoms, and no offset holds a real one. A scan
// that accepted mere parseability would return `ok: true, atoms: []` — the
// zero-yield that tombstones a page — instead of the FIRST offset's failure.
test('a parseable array of strings after bracketed prose is NOT accepted', () => {
const outcome = parseAtomsOutcome('see [Source: X] then candidate labels ["a","b"]');
expect(outcome).toEqual({ ok: false, reason: 'unparseable JSON array' });
});
test('a parseable array of shape-failing objects after bracketed prose is NOT accepted', () => {
const outcome = parseAtomsOutcome('see [Source: X] then [{"note":"tbd"}]');
expect(outcome).toEqual({ ok: false, reason: 'unparseable JSON array' });
});
});
describe('anchor scan — MAX_ARRAY_ANCHOR_CANDIDATES bounds the scan at 64 offsets', () => {
// Each `[tN]` token is one failing `[` offset; the atoms array itself holds
// exactly one `[`, so 63 tokens put it at the 64th (last tried) offset and
// 64 tokens push it past the cap.
const preamble = (n: number) => Array.from({ length: n }, (_, i) => `[t${i}]`).join(' ');
test('63 bracketed preamble tokens: the array at the 64th offset is still recovered', () => {
expect(atomsOf(preamble(63) + ' ' + ATOM_ARRAY)).toHaveLength(1);
});
test("64 bracketed preamble tokens: cap reached, the FIRST offset's failure is returned", () => {
const outcome = parseAtomsOutcome(preamble(64) + ' ' + ATOM_ARRAY);
expect(outcome).toEqual({ ok: false, reason: 'unparseable JSON array' });
});
});
describe('anchor scan — preserved behaviour', () => {
test('an honest empty array is still a zero-yield SUCCESS, not malformed output', () => {
// #4148 keeps "malformed output" and "the model found nothing" distinct:
// only the latter is a legitimate tombstone. The scan must not blur that
// by reclassifying `[]` as a parse failure just because it yields no atom.
const outcome = parseAtomsOutcome('[]');
expect(outcome.ok).toBe(true);
if (outcome.ok) expect(outcome.atoms).toEqual([]);
});
test('an empty array after prose is still a zero-yield success', () => {
const outcome = parseAtomsOutcome('Nothing worth extracting here.\n[]');
expect(outcome.ok).toBe(true);
if (outcome.ok) expect(outcome.atoms).toEqual([]);
});
test('a clean array with no preamble is unchanged', () => {
expect(atomsOf(ATOM_ARRAY)).toHaveLength(1);
});
test('a fenced array is unchanged', () => {
expect(atomsOf('```json\n' + ATOM_ARRAY + '\n```')).toHaveLength(1);
});
test('trailing prose after a valid array is still recovered', () => {
expect(atomsOf(ATOM_ARRAY + '\n\nThose are the atoms I found.')).toHaveLength(1);
});
test('trailing prose containing a bracketed citation does not hijack the recovery boundary', () => {
// Last-`]` trim-back included the citation in the re-parse, so a valid
// array was reported `unparseable JSON array`.
const raw = ATOM_ARRAY + '\nSee [Source: alice-example, agent session, 2026-09-03].';
expect(atomsOf(raw)).toHaveLength(1);
expect(atomsOf(raw)[0]!.title).toBe(ATOM.title);
});
test('trailing prose with an unmatched trailing bracket after a valid array is still recovered', () => {
const raw = ATOM_ARRAY + '\nas noted above]';
expect(atomsOf(raw)).toHaveLength(1);
});
test('recovery still finds the true boundary when the array body has escaped quotes, brackets inside strings, and a nested array', () => {
const nestedAtom = {
title: 'Escapes and nesting inside the array body',
atom_type: 'insight' as const,
body: 'She said \\"data is in [brackets]\\" and listed refs [1, 2].',
tags: ['[a]', '[b]'],
};
const raw = JSON.stringify([nestedAtom]) + '\nSee [Source: alice-example, 2026-09-03].';
const atoms = atomsOf(raw);
expect(atoms).toHaveLength(1);
expect(atoms[0]!.title).toBe(nestedAtom.title);
});
test('two complete top-level arrays: the FIRST one wins, pinning the anchor scan precedence', () => {
// Not a prompted shape, but the anchor scan's first-candidate-wins policy
// now applies because each candidate ends at its own closing bracket.
const secondAtom = { ...ATOM, title: 'A later, different array' };
const raw = ATOM_ARRAY + '\nCorrected answer:\n' + JSON.stringify([secondAtom]);
const atoms = atomsOf(raw);
expect(atoms).toHaveLength(1);
expect(atoms[0]!.title).toBe(ATOM.title);
});
test('an empty array after BRACKETED prose is a zero-yield success (#4948 rule holds at any offset)', () => {
// The #4948 prompt tells the model to answer exactly `[]` when nothing is
// extractable. A model that first echoes a bracketed citation and then
// obeys used to lose the `[]` to the shape gate: the first offset failed
// to parse, no later offset yielded an atom, so the FIRST offset's failure
// was returned — three strikes and the transcript was tombstoned + the
// phase halted for content that was honestly empty.
expect(parseAtomsOutcome('[Source: x] nothing here.\n[]')).toEqual({ ok: true, atoms: [] });
expect(parseAtomsOutcome('Checked [[people/alice-example]] — no atoms.\n\n[]')).toEqual({ ok: true, atoms: [] });
});
test('a NON-empty array with no atom-shaped element is a counted failure, not a zero-yield success', () => {
// Pre-fix this returned `ok: true, atoms: []` — the zero-yield shape that
// tombstones the item FOREVER on the first try — for output that was
// simply malformed (wrong keys). Malformed output rides the failure streak
// (retries, then the bounded MAX_DETERMINISTIC_FAILURES tombstone), like
// every other parse failure; only a literal `[]` is an honest zero-yield.
expect(parseAtomsOutcome('[{"claim":"Water is wet","kind":"fact"}]')).toEqual({
ok: false,
reason: 'array had no atom-shaped elements',
});
expect(parseAtomsOutcome('["a","b"]')).toEqual({ ok: false, reason: 'array had no atom-shaped elements' });
});
});
describe('anchor scan — failure reasons still describe the FIRST bracket', () => {
test('no bracket at all', () => {
const outcome = parseAtomsOutcome('I could not extract anything from this content.');
expect(outcome.ok).toBe(false);
if (!outcome.ok) expect(outcome.reason).toBe('no JSON array in response');
});
test('an opened-but-never-closed array reports unterminated, not unparseable', () => {
const outcome = parseAtomsOutcome('here goes [{"title":"a"');
expect(outcome.ok).toBe(false);
if (!outcome.ok) expect(outcome.reason).toBe('unterminated JSON array');
});
test('bracketed prose with no recoverable array anywhere still reports unparseable', () => {
// The scan exhausts every candidate and falls back to the FIRST offset's
// reason — never a later offset's, which would silently change the string
// the drain surfaces as `last_error`.
const outcome = parseAtomsOutcome('see [Source: X] and [[people/alice-example]] for details]');
expect(outcome.ok).toBe(false);
if (!outcome.ok) expect(outcome.reason).toBe('unparseable JSON array');
});
});