Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
12.1 KB
Raw Blame
/**
 * codex-hooks writer — hooks.json + the config.toml trust-state entry, the
 * two-file write the 0.147.0 trust gate demands (a hooks entry without its
 * trusted_hash is listed and silently never executed).
 *
 * The load-bearing properties: fail-closed on an unparseable hooks.json,
 * fresh-install APPEND + re-run REPLACE-IN-PLACE so foreign groups' trust
 * indexes never shift, idempotent re-runs, foreign trust entries preserved
 * byte-for-byte outside the managed block, refusal on a foreign definition
 * of our table key, and clean removal of exactly what we wrote.
 */
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import {
  buildCodexSessionEndCommand,
  codexTrustHash,
  removeCodexHooks,
  writeCodexHooks,
} from '../src/core/bootstrap/codex-hooks.ts';

let dir: string;
let hooksPath: string;
let configPath: string;

beforeEach(() => {
  dir = mkdtempSync(join(tmpdir(), 'gb-cdx-hooks-'));
  mkdirSync(dir, { recursive: true });
  hooksPath = join(dir, 'hooks.json');
  configPath = join(dir, 'config.toml');
});
afterEach(() => {
  rmSync(dir, { recursive: true, force: true });
});

const BIN = '/usr/local/bin/gbrain';

function readHooks(): { description?: string; hooks?: Record<string, Array<{ hooks: Array<{ command: string; timeout?: number }> }>> } {
  return JSON.parse(readFileSync(hooksPath, 'utf8'));
}

describe('writeCodexHooks', () => {
  test('fresh write: hooks.json created with description + our entry; trust entry with the recipe hash', () => {
    const res = writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    expect(res.ok).toBe(true);
    expect(res.trustKey).toBe(`${hooksPath}:session_end:0:0`);

    const doc = readHooks();
    expect(doc.description).toContain('gbrain');
    const groups = doc.hooks!.SessionEnd!;
    expect(groups).toHaveLength(1);
    const handler = groups[0]!.hooks[0]!;
    expect(handler.command).toContain('hook session-end --harness codex');
    // The 3s hard-kill posture: stdin captured, grandchild detached.
    expect(handler.command).toContain('mktemp');
    expect(handler.command).toContain('nohup');
    expect(handler.timeout).toBe(3);
    // No baked source — runtime payload resolution only [OV2].
    expect(handler.command).not.toContain('GBRAIN_SOURCE');

    const cfg = readFileSync(configPath, 'utf8');
    expect(cfg).toContain(`[hooks.state.${JSON.stringify(res.trustKey)}]`);
    expect(cfg).toContain(`trusted_hash = ${JSON.stringify(codexTrustHash(handler.command))}`);
    expect(codexTrustHash(handler.command)).toMatch(/^sha256:[0-9a-f]{64}$/);
  });

  test('idempotent: a re-run replaces our entry (one group, one trust block), never accumulates', () => {
    writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    const res2 = writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    expect(res2.ok).toBe(true);
    expect(res2.replacedPrior).toBe(true);
    expect(readHooks().hooks!.SessionEnd!).toHaveLength(1);
    const cfg = readFileSync(configPath, 'utf8');
    expect(cfg.match(/gbrain:codex-hooks-trust \(managed/g)).toHaveLength(1);
    expect(cfg.match(/trusted_hash/g)).toHaveLength(1);
  });

  test('foreign SessionEnd groups keep their positions (ours appends LAST, key index shifts to match)', () => {
    const foreign = { description: 'mine', hooks: { SessionEnd: [{ hooks: [{ type: 'command', command: 'my-own-tool --flag', timeout: 2 }] }] } };
    writeFileSync(hooksPath, JSON.stringify(foreign));
    writeFileSync(configPath, `[hooks.state."${hooksPath}:session_end:0:0"]\ntrusted_hash = "sha256:user-owned"\n`);

    const res = writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    expect(res.ok).toBe(true);
    expect(res.trustKey).toBe(`${hooksPath}:session_end:1:0`); // AFTER the foreign group
    const doc = readHooks();
    expect(doc.description).toBe('mine'); // never clobber a user description
    expect(doc.hooks!.SessionEnd![0]!.hooks[0]!.command).toBe('my-own-tool --flag');
    expect(doc.hooks!.SessionEnd![1]!.hooks[0]!.command).toContain('gbrain');
    const cfg = readFileSync(configPath, 'utf8');
    // The user's own trust entry survives byte-for-byte outside our block.
    expect(cfg).toContain('sha256:user-owned');
    expect(cfg).toContain(`:session_end:1:0`);
  });

  test('fail-closed: an unparseable hooks.json is never touched', () => {
    writeFileSync(hooksPath, '{definitely not json');
    const res = writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    expect(res.ok).toBe(false);
    expect(res.reason).toBe('hooks_json_unparseable');
    expect(readFileSync(hooksPath, 'utf8')).toBe('{definitely not json');
    expect(existsSync(configPath)).toBe(false); // trust entry not written either
  });

  test('refusal: our exact table key already defined outside the managed block (double-define bricks codex)', () => {
    writeFileSync(configPath, `[hooks.state."${hooksPath}:session_end:0:0"]\ntrusted_hash = "sha256:foreign"\n`);
    const res = writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    expect(res.ok).toBe(false);
    expect(res.reason).toBe('foreign_trust_entry');
    expect(readFileSync(configPath, 'utf8')).toContain('sha256:foreign');
    expect(existsSync(hooksPath)).toBe(false);
  });

  test('foreign config.toml content outside the block survives byte-for-byte across write + rewrite', () => {
    const userCfg = '# my codex config\nmodel = "gpt-5.6-sol"\n\n[mcp_servers.other]\nurl = "http://x"\n';
    writeFileSync(configPath, userCfg);
    writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    const cfg = readFileSync(configPath, 'utf8');
    expect(cfg.startsWith('# my codex config\nmodel = "gpt-5.6-sol"')).toBe(true);
    expect(cfg).toContain('[mcp_servers.other]');
  });
});

describe('removeCodexHooks', () => {
  test('removes exactly ours: foreign groups + foreign trust entries survive; our block goes', () => {
    const foreign = { hooks: { SessionEnd: [{ hooks: [{ type: 'command', command: 'my-own-tool', timeout: 2 }] }] } };
    writeFileSync(hooksPath, JSON.stringify(foreign));
    writeFileSync(configPath, '[hooks.state."x:session_end:0:0"]\ntrusted_hash = "sha256:user-owned"\n');
    writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });

    const res = removeCodexHooks({ hooksPath, configPath });
    expect(res.removed).toBe(true);
    const doc = readHooks();
    expect(doc.hooks!.SessionEnd!).toHaveLength(1);
    expect(doc.hooks!.SessionEnd![0]!.hooks[0]!.command).toBe('my-own-tool');
    const cfg = readFileSync(configPath, 'utf8');
    expect(cfg).toContain('sha256:user-owned');
    expect(cfg).not.toContain('gbrain:codex-hooks-trust');
    expect(cfg).not.toContain('gbrain');
  });

  test('absent files and unparseable hooks.json are calm non-destructive no-ops', () => {
    expect(removeCodexHooks({ hooksPath, configPath }).removed).toBe(false);
    writeFileSync(hooksPath, '{broken');
    const res = removeCodexHooks({ hooksPath, configPath });
    expect(res.removed).toBe(false);
    expect(readFileSync(hooksPath, 'utf8')).toBe('{broken');
    expect(res.notes.join(' ')).toContain('left untouched');
  });
});

describe('buildCodexSessionEndCommand', () => {
  test('a path needing quoting stays intact through the $0 seam', () => {
    const cmd = buildCodexSessionEndCommand("/opt/my tools/gbrain");
    expect(cmd).toContain("'/opt/my tools/gbrain'");
    expect(cmd).toContain('"$GBRAIN_BIN" hook session-end --harness codex');
  });

  test('the TOP level is a single sh -c invocation ($SHELL may be fish/csh — only /bin/sh parses the POSIX script)', () => {
    const cmd = buildCodexSessionEndCommand('/usr/local/bin/gbrain');
    expect(cmd.startsWith("sh -c '")).toBe(true);
    // the bin rides as the outer sh's $0, referenced (never re-quoted) inside
    expect(cmd.endsWith(' /usr/local/bin/gbrain')).toBe(true);
    expect(cmd).toContain('GBRAIN_BIN="$0"');
  });
});

describe('trust-hash golden vector', () => {
  test('pins the 0.147.0-verified canonical recipe against silent drift', () => {
    // Captured from the recipe proven live against codex 0.147.0 (the
    // observation-run hook actually fired under this identity shape). Any
    // change to canonicalJson, the identity fields, async:false, or the 3s
    // timeout fails HERE instead of shipping machine-wide silent non-capture.
    expect(codexTrustHash('golden-fixed-command --x')).toBe(
      'sha256:352b9ab177175c5d6e83c83f2bb3f42187e0791647292bd43291fa7122ac3cc4',
    );
  });
});

describe('re-run with foreign groups AFTER ours (the index-shift class)', () => {
  test('replaces in place: the foreign index and OUR trust key both survive, no refusal', () => {
    const first = writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    expect(first.trustKey).toBe(`${hooksPath}:session_end:0:0`);
    // User appends their own group AFTER ours and trusts it at index 1.
    const doc = readHooks();
    doc.hooks!.SessionEnd!.push({ hooks: [{ command: 'user-tool --own' }] });
    writeFileSync(hooksPath, JSON.stringify(doc, null, 2));
    const userTrust = `[hooks.state.${JSON.stringify(`${hooksPath}:session_end:1:0`)}]\ntrusted_hash = "sha256:user-owned"\n`;
    writeFileSync(configPath, readFileSync(configPath, 'utf8') + userTrust);

    const rerun = writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    expect(rerun.ok).toBe(true); // NOT a foreign_trust_entry refusal of the user's own valid entry
    expect(rerun.trustKey).toBe(`${hooksPath}:session_end:0:0`); // ours stayed at its index
    const after = readHooks();
    expect(after.hooks!.SessionEnd!).toHaveLength(2);
    expect(after.hooks!.SessionEnd![0]!.hooks[0]!.command).toContain('hook session-end --harness codex');
    expect(after.hooks!.SessionEnd![1]!.hooks[0]!.command).toBe('user-tool --own'); // foreign index unshifted
    // The user's own trust entry survives byte-for-byte outside our block.
    expect(readFileSync(configPath, 'utf8')).toContain('sha256:user-owned');
  });

  test('a TOML-variant foreign header for OUR key is still refused (tolerant guard, not byte-exact)', () => {
    writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    // Strip our managed block, then hand-write the same key with extra
    // whitespace — the pre-fix byte-exact guard missed this spelling and the
    // append produced a duplicate table (a hard TOML parse error in codex).
    removeCodexHooks({ hooksPath, configPath });
    const variant = `[ hooks.state.${JSON.stringify(`${hooksPath}:session_end:0:0`)} ]\ntrusted_hash = "sha256:foreign"\n`;
    writeFileSync(configPath, variant, { mode: 0o600 });
    const res = writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    expect(res.ok).toBe(false);
    expect(res.reason).toBe('foreign_trust_entry');
  });
});

describe('removeCodexHooks description hygiene', () => {
  test('deletes the description only when it is byte-identical to ours', () => {
    writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    removeCodexHooks({ hooksPath, configPath });
    expect(readHooks().description).toBeUndefined();
  });

  test('a user-authored description survives removal', () => {
    writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    const doc = readHooks();
    doc.description = 'my own hooks file';
    writeFileSync(hooksPath, JSON.stringify(doc, null, 2));
    removeCodexHooks({ hooksPath, configPath });
    expect(readHooks().description).toBe('my own hooks file');
  });

  test('removal warns when foreign groups sat after ours (their trust indexes shift)', () => {
    writeCodexHooks({ gbrainBin: BIN, hooksPath, configPath });
    const doc = readHooks();
    doc.hooks!.SessionEnd!.push({ hooks: [{ command: 'user-tool --own' }] });
    writeFileSync(hooksPath, JSON.stringify(doc, null, 2));
    const res = removeCodexHooks({ hooksPath, configPath });
    expect(res.removed).toBe(true);
    expect(res.notes.join(' ')).toContain('shifted');
    expect(readHooks().hooks!.SessionEnd![0]!.hooks[0]!.command).toBe('user-tool --own');
  });
});