Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* codex-hook-lane — the hook-lane view of codex rollouts: confinement ladder
* (pinned root, symlink/traversal/cap refusals), ParsedTranscript-shaped
* parsing with tool calls (observed keys only) and boundary positions, the
* bounded discovery fallback, and the capture-spec dispatch golden rule
* (undefined/unknown → claude spec, byte-for-byte today's behavior).
*/
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import { mkdirSync, mkdtempSync, rmSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { CAPTURE_SPECS, captureSpecFor } from '../src/core/transcripts/capture-spec.ts';
import {
confineCodexTranscriptPath,
discoverNewestCodexRollout,
parseCodexHookTranscript,
} from '../src/core/transcripts/codex-hook-lane.ts';
import { mapCodexLine } from '../src/core/transcripts/codex.ts';
let dir: string;
beforeEach(() => {
dir = mkdtempSync(join(tmpdir(), 'gb-cdx-lane-'));
});
afterEach(() => {
rmSync(dir, { recursive: true, force: true });
});
const meta = JSON.stringify({
timestamp: 't0',
type: 'session_meta',
payload: { id: 'r-1', session_id: 'cdx-sess-1', timestamp: 't0', cwd: '/repo', cli_version: '0.147.0' },
});
const user = (text: string) => JSON.stringify({ timestamp: 't1', type: 'event_msg', payload: { type: 'user_message', message: text } });
const assistant = (text: string) =>
JSON.stringify({ timestamp: 't2', type: 'response_item', payload: { type: 'message', role: 'assistant', content: [{ type: 'output_text', text }] } });
const injected = JSON.stringify({ timestamp: 't1', type: 'response_item', payload: { type: 'message', role: 'developer', content: [{ type: 'input_text', text: 'INJECTED-NEVER' }] } });
const customCall = JSON.stringify({ timestamp: 't3', type: 'response_item', payload: { type: 'custom_tool_call', id: 'ri-4', name: 'search_brain', input: '{"query":"widget-co seed"}' } });
const fnCall = JSON.stringify({ timestamp: 't4', type: 'response_item', payload: { type: 'function_call', id: 'ri-6', call_id: 'c-1', name: 'shell', arguments: '{"command":["bash","-lc","bun test"]}' } });
const callOutput = JSON.stringify({ timestamp: 't5', type: 'response_item', payload: { type: 'custom_tool_call_output', id: 'ri-5', call_id: 'c-1', output: 'TOOL-OUTPUT-NEVER' } });
const boundary = JSON.stringify({ timestamp: 't6', type: 'compacted', payload: { message: 'compacted' } });
describe('parseCodexHookTranscript', () => {
test('fixture parses: turns exclude injected context and tool output; calls carry observed args keys, span-stamped', () => {
const p = join(dir, 'rollout-1.jsonl');
writeFileSync(p, [meta, injected, user('fix the failing order tests'), customCall, callOutput, assistant('done — pushed the fix'), '{torn'].join('\n') + '\n');
const parsed = parseCodexHookTranscript(p, { collectToolCalls: true });
expect(parsed.sessionId).toBe('r-1'); // payload.id, the id codex embeds in the rollout filename (#4981)
expect(parsed.cwd).toBe('/repo');
expect(parsed.turns.map((t) => t.text)).toEqual(['fix the failing order tests', 'done — pushed the fix']);
// custom_tool_call args key is `input` (fixture-verified), a JSON string → parsed.
expect(parsed.toolCalls).toEqual([{ name: 'search_brain', input: { query: 'widget-co seed' } }]);
// Stamped between turn 0 and turn 1 — the slot it precedes.
expect(parsed.toolCallTurnIndexes).toEqual([1]);
expect(parsed.skippedLines).toBe(1); // the torn line
// No result join: 0.147.0 persists no success flag on *_output rows.
expect('result' in (parsed.toolCalls[0] as unknown as Record<string, unknown>)).toBe(false);
});
test('function_call args key is `arguments` (source-verified); non-JSON args stay the raw string', () => {
const p = join(dir, 'rollout-2.jsonl');
const rawArgs = JSON.stringify({ timestamp: 't', type: 'response_item', payload: { type: 'function_call', name: 'shell', arguments: 'not json at all' } });
writeFileSync(p, [meta, user('run it'), fnCall, rawArgs].join('\n') + '\n');
const parsed = parseCodexHookTranscript(p, { collectToolCalls: true });
// Same opt-in contract as the claude parser: the bare parse collects nothing.
expect(parseCodexHookTranscript(p).toolCalls).toEqual([]);
expect(parsed.toolCalls).toEqual([
{ name: 'shell', input: { command: ['bash', '-lc', 'bun test'] } },
{ name: 'shell', input: 'not json at all' },
]);
});
test('observed args are bounded by the shared cap — one receipt-size ceiling for every harness', () => {
const p = join(dir, 'rollout-cap.jsonl');
const body = 'C'.repeat(40_000); // over TOOL_CALL_VALUE_MAX_CHARS (32k)
const fatCall = JSON.stringify({
timestamp: 't',
type: 'response_item',
payload: { type: 'function_call', name: 'shell', arguments: JSON.stringify({ command: body }) },
});
writeFileSync(p, [meta, user('write it'), fatCall].join('\n') + '\n');
const parsed = parseCodexHookTranscript(p, { collectToolCalls: true });
const input = parsed.toolCalls[0]!.input as { command: string };
expect(input.command).toContain('…[8000 chars omitted]');
expect(input.command.length).toBeLessThan(40_000);
});
test('compacted rows record boundary positions in turn space', () => {
const p = join(dir, 'rollout-3.jsonl');
writeFileSync(p, [meta, user('one'), boundary, user('two'), assistant('three')].join('\n') + '\n');
const parsed = parseCodexHookTranscript(p);
expect(parsed.compactBoundaries).toBe(1);
expect(parsed.boundaryTurnIndexes).toEqual([1]);
expect(parsed.turns).toHaveLength(3);
});
// #4981: a forked/subagent rollout carries its own payload.id plus the ROOT
// session_id and an inherited parent session_meta later in the file. The
// hook fallback id must be the child's own (first header, payload.id) so it
// matches the rollout filename discoverNewestCodexRollout substring-matches.
test('forked rollout keeps its own payload.id; an inherited parent header does not overwrite it (#4981)', () => {
const p = join(dir, 'rollout-child.jsonl');
const inheritedParent = JSON.stringify({
timestamp: 't0',
type: 'session_meta',
payload: { id: 'r-parent', session_id: 'cdx-sess-1', timestamp: 't0', cwd: '/repo-parent', cli_version: '0.147.0' },
});
writeFileSync(p, [meta, inheritedParent, user('child turn'), assistant('child reply')].join('\n') + '\n');
const parsed = parseCodexHookTranscript(p);
expect(parsed.sessionId).toBe('r-1');
expect(parsed.cwd).toBe('/repo');
expect(parsed.turns.map((t) => t.text)).toEqual(['child turn', 'child reply']);
});
test('over-budget read keeps session_meta identity (head) and the newest turns (tail)', () => {
const p = join(dir, 'rollout-big.jsonl');
const lines = [meta];
for (let i = 0; i < 2000; i++) lines.push(user(`turn-${i} ${'x'.repeat(400)}`));
writeFileSync(p, lines.join('\n') + '\n');
const parsed = parseCodexHookTranscript(p, { maxBytes: 128 * 1024 });
expect(parsed.sessionId).toBe('r-1'); // head window preserved identity
expect(parsed.turns[parsed.turns.length - 1]!.text).toContain('turn-1999'); // newest tail kept
expect(parsed.bytesRead).toBeLessThanOrEqual(128 * 1024);
});
});
describe('confineCodexTranscriptPath — the S3#8 ladder on the codex root', () => {
test('accepts a rollout inside the pinned root; refuses everything the ladder names', () => {
const root = join(dir, 'sessions');
const day = join(root, '2026', '08', '25');
mkdirSync(day, { recursive: true });
const ok = join(day, 'rollout-x.jsonl');
writeFileSync(ok, meta + '\n');
expect(confineCodexTranscriptPath(ok, { root })).toEqual({ ok: true, path: ok, size: expect.any(Number) });
expect(confineCodexTranscriptPath(undefined, { root })).toEqual({ ok: false, reason: 'missing_path' });
expect(confineCodexTranscriptPath(join(day, 'x.txt'), { root })).toEqual({ ok: false, reason: 'not_jsonl' });
// A path that simply is not there is `missing_path`, NOT `unreadable` —
// hook.ts gates its discovery fallback on that rung, and `unreadable` is
// reserved for a real permission/IO fault.
expect(confineCodexTranscriptPath(join(day, 'absent.jsonl'), { root })).toEqual({ ok: false, reason: 'missing_path' });
const outside = join(dir, 'outside.jsonl');
writeFileSync(outside, meta + '\n');
expect(confineCodexTranscriptPath(outside, { root })).toEqual({ ok: false, reason: 'outside_projects_dir' });
// Traversal out of the root is still outside after realpath.
expect(confineCodexTranscriptPath(join(day, '..', '..', '..', '..', 'outside.jsonl'), { root })).toEqual({ ok: false, reason: 'outside_projects_dir' });
const link = join(day, 'link.jsonl');
symlinkSync(outside, link);
expect(confineCodexTranscriptPath(link, { root })).toEqual({ ok: false, reason: 'symlink' });
const fat = join(day, 'rollout-fat.jsonl');
writeFileSync(fat, 'x'.repeat(64));
expect(confineCodexTranscriptPath(fat, { root, maxBytes: 16 })).toEqual({ ok: false, reason: 'too_large' });
});
// #5701: same split as the claude lane — this parser reads a bounded
// HEAD+TAIL window, so the opt-in skips ONLY the size gate.
test('allowOversize skips only the size gate (mirrors the claude lane)', () => {
const root = mkdtempSync(join(tmpdir(), 'gb-cdx-oversize-'));
const fat = join(root, 'rollout-fat.jsonl');
writeFileSync(fat, 'x'.repeat(64));
expect(confineCodexTranscriptPath(fat, { root, maxBytes: 16 })).toEqual({ ok: false, reason: 'too_large' });
const r = confineCodexTranscriptPath(fat, { root, maxBytes: 16, allowOversize: true });
expect(r.ok).toBe(true);
if (r.ok) expect(r.size).toBe(64);
// Root containment is not relaxed by the opt-in.
const outside = join(root, '..', `gb-codex-outside-${process.pid}.jsonl`);
writeFileSync(outside, '{}\n');
try {
expect(confineCodexTranscriptPath(outside, { root, maxBytes: 16, allowOversize: true })).toEqual({
ok: false,
reason: 'outside_projects_dir',
});
} finally {
rmSync(outside, { force: true });
}
});
});
describe('discoverNewestCodexRollout — bounded, id-matched, symlink-rejecting', () => {
function seedStore(root: string): { newest: string; older: string } {
const d1 = join(root, '2026', '08', '24');
const d2 = join(root, '2026', '08', '25');
mkdirSync(d1, { recursive: true });
mkdirSync(d2, { recursive: true });
const older = join(d1, 'rollout-2026-08-24-aaa-sess-old.jsonl');
const newest = join(d2, 'rollout-2026-08-25-bbb-sess-new.jsonl');
writeFileSync(older, meta + '\n');
writeFileSync(newest, meta + '\n');
const past = new Date(Date.now() - 60_000);
utimesSync(older, past, past);
return { newest, older };
}
test('id match wins; degrade names the match kind; no id falls back to newest mtime', () => {
const root = join(dir, 'store');
const { newest, older } = seedStore(root);
expect(discoverNewestCodexRollout('sess-old', { root })).toEqual({ path: older, degrade: 'transcript_discovered' });
expect(discoverNewestCodexRollout('sess-new', { root })).toEqual({ path: newest, degrade: 'transcript_discovered' });
expect(discoverNewestCodexRollout(null, { root })).toEqual({ path: newest, degrade: 'transcript_discovered_newest' });
expect(discoverNewestCodexRollout('no-such-session', { root })).toBeNull();
expect(discoverNewestCodexRollout('x', { root: join(dir, 'absent-store') })).toBeNull();
});
test('symlinked rollouts are never returned', () => {
const root = join(dir, 'store2');
const day = join(root, '2026', '08', '25');
mkdirSync(day, { recursive: true });
const target = join(dir, 'evil.jsonl');
writeFileSync(target, meta + '\n');
symlinkSync(target, join(day, 'rollout-linked-sess-x.jsonl'));
expect(discoverNewestCodexRollout('sess-x', { root })).toBeNull();
});
});
describe('captureSpecFor — the dispatch golden rule', () => {
test('undefined/unknown/opencode resolve to the claude spec (today\'s behavior); codex resolves to codex', () => {
expect(captureSpecFor(undefined)).toBe(CAPTURE_SPECS['claude-code']);
expect(captureSpecFor('claude-code')).toBe(CAPTURE_SPECS['claude-code']);
expect(captureSpecFor('opencode')).toBe(CAPTURE_SPECS['claude-code']);
expect(captureSpecFor('anything-else')).toBe(CAPTURE_SPECS['claude-code']);
expect(captureSpecFor('codex')).toBe(CAPTURE_SPECS.codex);
// Only the codex lane has a discovery fallback.
expect(captureSpecFor('codex').discover).toBeDefined();
expect(captureSpecFor('claude-code').discover).toBeUndefined();
});
});
describe('mapCodexLine — the shared mapper stays honest on edge shapes', () => {
test('nameless calls, non-object lines, unknown payloads: skip, never throw', () => {
expect(mapCodexLine(null)).toEqual({ kind: 'skip' });
expect(mapCodexLine('str')).toEqual({ kind: 'skip' });
expect(mapCodexLine({ type: 'response_item', payload: { type: 'custom_tool_call', input: '{}' } })).toEqual({ kind: 'skip' });
expect(mapCodexLine({ type: 'world_state', payload: {} })).toEqual({ kind: 'skip' });
expect(mapCodexLine({ type: 'response_item', payload: { type: 'custom_tool_call_output', output: 'x' } })).toEqual({ kind: 'skip' });
});
});