Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
17.4 KB
Raw Blame
/**
 * Ambient-writeback Stop-hook lane (WP4): file-plane gated, deterministic
 * zero-LLM salience gate, content-addressed banking, IPC prompt-harvest ask,
 * fail-open always (exit 0 whatever happens — the conversational path is
 * never blocked; requirement/test bullet 11). Serve-side extraction is
 * covered in test/checkpoint-harvest.serial.test.ts; THIS file covers the
 * hook child.
 */
import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { tmpdir } from 'node:os';
import type net from 'node:net';

import { runHook } from '../src/commands/hook.ts';
import { readHeartbeatTail } from '../src/core/context/hook-heartbeat.ts';
import { CLAUDE_CLI_CWD_PREFIX } from '../src/core/ai/providers/claude-cli-scratch.ts';
import { startResolveIpcServer, ensureIpcSecret, resolveSocketPath, type ContextPackRequest, } from '../src/core/context/resolve-ipc.ts';
import type { TurnContextResult } from '../src/core/context/turn-context.ts';

const ENV_KEYS = ['GBRAIN_HOME', 'GBRAIN_SOURCE', 'GBRAIN_HOOKS', 'GBRAIN_STOP_PUSH', 'DATABASE_URL', 'GBRAIN_DATABASE_URL'] as const;

let tmp: string;
let saved: Record<string, string | undefined>;
let servers: net.Server[] = [];

beforeEach(() => {
  tmp = mkdtempSync(join(tmpdir(), 'gb-wbstop-'));
  saved = {};
  for (const k of ENV_KEYS) { saved[k] = process.env[k]; delete process.env[k]; }
  process.env.GBRAIN_HOME = tmp;
});

afterEach(() => {
  for (const s of servers) { try { s.close(); } catch { /* noop */ } }
  servers = [];
  for (const k of ENV_KEYS) {
    if (saved[k] === undefined) delete process.env[k];
    else process.env[k] = saved[k];
  }
  rmSync(tmp, { recursive: true, force: true });
});

const home = () => join(tmp, '.gbrain');
// #6268: turn files land in the corpus spool; without GBRAIN_SOURCE or a serve the stamp is unresolved.
const corpus = () => join(home(), 'transcripts', 'corpus', 'sourced');

function writeConfig(opts: { writeback?: string; dataDir?: string }): string {
  mkdirSync(home(), { recursive: true });
  const dataDir = opts.dataDir ?? join(tmp, 'pglite-data');
  writeFileSync(join(home(), 'config.json'), JSON.stringify({
    engine: 'pglite',
    database_path: dataDir,
    ...(opts.writeback ? { memory: { auto_writeback: opts.writeback } } : {}),
  }));
  return dataDir;
}

/** Minimal claude-code JSONL transcript with one user turn (+ assistant reply). */
function writeTranscript(userText: string, opts: { assistantOnly?: boolean; assistantFillerChars?: number } = {}): { path: string; root: string } {
  const root = join(tmp, 'projects-root');
  mkdirSync(root, { recursive: true });
  const p = join(root, 'session.jsonl');
  const lines = [
    ...(opts.assistantOnly ? [] : [JSON.stringify({
      parentUuid: null, isSidechain: false, type: 'user',
      message: { role: 'user', content: userText },
      uuid: 'u-1', sessionId: 's-wb', timestamp: '2026-09-01T10:00:00.000Z',
    })]),
    JSON.stringify({
      parentUuid: 'u-1', isSidechain: false, type: 'assistant',
      message: {
        role: 'assistant',
        content: [{
          type: 'text',
          text: opts.assistantFillerChars ? 'x'.repeat(opts.assistantFillerChars) : 'Done — noted.',
        }],
      },
      uuid: 'a-1', sessionId: 's-wb', timestamp: '2026-09-01T10:00:05.000Z',
    }),
  ];
  writeFileSync(p, lines.join('\n') + '\n');
  return { path: p, root };
}

function writeTranscriptWithToolResult(userText: string, resultChars: number): { path: string; root: string } {
  const root = join(tmp, 'projects-root');
  mkdirSync(root, { recursive: true });
  const p = join(root, 'session.jsonl');
  const lines = [
    JSON.stringify({
      parentUuid: null, isSidechain: false, type: 'user',
      message: { role: 'user', content: userText },
      uuid: 'u-1', sessionId: 's-wb', timestamp: '2026-09-01T10:00:00.000Z',
    }),
    JSON.stringify({
      parentUuid: 'u-1', isSidechain: false, type: 'assistant',
      message: { role: 'assistant', content: [{ type: 'tool_use', id: 'tool-1', name: 'Read', input: { file_path: '/tmp/a' } }] },
      uuid: 'a-1', sessionId: 's-wb', timestamp: '2026-09-01T10:00:01.000Z',
    }),
    JSON.stringify({
      parentUuid: 'a-1', isSidechain: false, type: 'user',
      message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: 'tool-1', content: 'x'.repeat(resultChars) }] },
      uuid: 'u-tool-1', sessionId: 's-wb', timestamp: '2026-09-01T10:00:02.000Z',
    }),
    JSON.stringify({
      parentUuid: 'u-tool-1', isSidechain: false, type: 'assistant',
      message: { role: 'assistant', content: [{ type: 'text', text: 'Done — noted.' }] },
      uuid: 'a-2', sessionId: 's-wb', timestamp: '2026-09-01T10:00:03.000Z',
    }),
  ];
  writeFileSync(p, lines.join('\n') + '\n');
  return { path: p, root };
}

/** A claude-code JSONL transcript of alternating turns under `<root>/<project>/session.jsonl`. */
function writeTurns(turns: Array<{ role: 'user' | 'assistant'; text: string }>, project = 'app'): { path: string; root: string } {
  const root = join(tmp, 'projects-root');
  mkdirSync(join(root, project), { recursive: true });
  const p = join(root, project, 'session.jsonl');
  writeFileSync(p, turns.map((t, i) => JSON.stringify({
    parentUuid: i === 0 ? null : `t-${i - 1}`, isSidechain: false, type: t.role,
    message: { role: t.role, content: t.role === 'user' ? t.text : [{ type: 'text', text: t.text }] },
    uuid: `t-${i}`, sessionId: 's-wb', timestamp: `2026-09-01T10:00:0${i}.000Z`,
  })).join('\n') + '\n');
  return { path: p, root };
}

const PASTE = '<pasted_content id="2830">\nForwarded: the offsite moves to March and the budget is final.\n</pasted_content id="2830">';

function bankedTexts(): string[] {
  if (!existsSync(corpus())) return [];
  return readdirSync(corpus()).filter((f) => f.includes('.wb-')).map((f) => readFileSync(join(corpus(), f), 'utf8'));
}

const io = { write: () => {} };

async function wbHeartbeats() {
  return (await readHeartbeatTail(20)).filter((e) => e.event === 'writeback-bank');
}

describe('hook stop — ambient writeback banking', () => {
  test('gate off (no memory config): exit 0, no wb file, no writeback-bank heartbeat', async () => {
    writeConfig({});
    const t = writeTranscript('I prefer dark mode in every editor, please set it up.');
    const code = await runHook(['stop'], {
      ...io, transcriptRoot: t.root,
      stdin: JSON.stringify({ session_id: 's-wb', transcript_path: t.path, last_assistant_message: 'ok' }),
    });
    expect(code).toBe(0);
    expect(existsSync(corpus())).toBe(false);
    expect((await wbHeartbeats()).length).toBe(0);
  });

  test('"Thanks" produces NOTHING: no file, zero LLM — the typed too_short skip is the only trace', async () => {
    writeConfig({ writeback: 'salient' });
    const t = writeTranscript('Thanks');
    const code = await runHook(['stop'], {
      ...io, transcriptRoot: t.root,
      stdin: JSON.stringify({ session_id: 's-wb', transcript_path: t.path }),
    });
    expect(code).toBe(0);
    const files = existsSync(corpus()) ? readdirSync(corpus()).filter((f) => f.includes('.wb-')) : [];
    expect(files).toEqual([]);
    const hb = await wbHeartbeats();
    expect(hb.length).toBe(1);
    expect(hb[0].reason).toBe('too_short');
    // A deterministic gate skip is BY DESIGN, not an infra fault — 'ok'
    // keeps doctor's skipped/failed counters (and any alerting on
    // 'degraded') from firing on every "Thanks" (adversarial review).
    expect(hb[0].outcome).toBe('ok');
  });

  test('assistant-only stop payload → no_user_turn skip', async () => {
    writeConfig({ writeback: 'salient' });
    const t = writeTranscript('', { assistantOnly: true });
    expect(await runHook(['stop'], {
      ...io, transcriptRoot: t.root,
      stdin: JSON.stringify({ session_id: 's-wb', transcript_path: t.path }),
    })).toBe(0);
    expect((await wbHeartbeats())[0]?.reason).toBe('no_user_turn');
  });

  test('tool_result user entries do not shadow the genuine user prompt', async () => {
    writeConfig({ writeback: 'salient' });
    const prompt = 'I prefer dark mode in every editor, and I want weekly summaries.';
    const t = writeTranscriptWithToolResult(prompt, 20);
    expect(await runHook(['stop'], {
      ...io, transcriptRoot: t.root,
      stdin: JSON.stringify({ session_id: 's-wb', transcript_path: t.path }),
    })).toBe(0);
    const file = readdirSync(corpus()).find((f) => /^s-wb\.wb-[0-9a-f]{24}\.src-_unresolved\.txt$/.test(f));
    expect(file).toBeDefined();
    expect(await Bun.file(join(corpus(), file!)).text()).toBe(prompt + '\n');
  });

  test('tool_result beyond the cheap tail triggers the wide retry for the genuine prompt', async () => {
    writeConfig({ writeback: 'salient' });
    const prompt = 'I prefer dark mode in every editor, and I want weekly summaries.';
    const t = writeTranscriptWithToolResult(prompt, 140_000);
    expect(await runHook(['stop'], {
      ...io, transcriptRoot: t.root,
      stdin: JSON.stringify({ session_id: 's-wb', transcript_path: t.path }),
    })).toBe(0);
    const file = readdirSync(corpus()).find((f) => /^s-wb\.wb-[0-9a-f]{24}\.src-_unresolved\.txt$/.test(f));
    expect(file).toBeDefined();
    expect(await Bun.file(join(corpus(), file!)).text()).toBe(prompt + '\n');
  });

  test('user turn pushed past the 128KB tail by ONE huge assistant payload: wide retry finds it — banked, NOT no_user_turn', async () => {
    writeConfig({ writeback: 'salient' });
    // The assistant turn between the last user turn and EOF exceeds
    // WRITEBACK_TRANSCRIPT_TAIL_BYTES (128KB), so the cheap tail parse sees
    // only a partial assistant line and NO user turn (turn OFFSET from EOF ≠
    // turn SIZE). The one-shot retry at the 2MB user-prompt cap must recover
    // the turn instead of skipping with no_user_turn.
    const t = writeTranscript(
      'I am allergic to peanuts and I prefer dark mode in every editor, please remember this context',
      { assistantFillerChars: 140_000 },
    );
    const code = await runHook(['stop'], {
      ...io, transcriptRoot: t.root,
      stdin: JSON.stringify({ session_id: 's-wb', transcript_path: t.path }),
    });
    expect(code).toBe(0);
    // The durable artifact exists — the user turn WAS found and banked.
    const files = readdirSync(corpus()).filter((f) => /^s-wb\.wb-[0-9a-f]{24}\.src-_unresolved\.txt$/.test(f));
    expect(files.length).toBe(1);
    const hb = await wbHeartbeats();
    expect(hb.length).toBe(1);
    const reason = String(hb[0].reason);
    expect(reason).not.toBe('no_user_turn');
    // Serve is down in this hermetic setup, so post-bank the infra lane
    // reports no_serve; any banked/scheduled-family reason is acceptable —
    // what this test pins is that the turn was FOUND and banked.
    expect(
      ['wb_banked', 'wb_scheduled', 'wb_dup', 'no_serve', 'ipc_unavailable', 'stale_serve'].includes(reason) ||
        reason.startsWith('flush_skip_'),
    ).toBe(true);
  });

  test('substantive turn, serve DOWN: wb file banked (redacted, content-addressed), degraded no_serve, exit 0 — sweep picks it up later', async () => {
    writeConfig({ writeback: 'salient' });
    const t = writeTranscript('I prefer dark mode in every editor, and I want weekly summaries.');
    const code = await runHook(['stop'], {
      ...io, transcriptRoot: t.root,
      stdin: JSON.stringify({ session_id: 's-wb', transcript_path: t.path }),
    });
    expect(code).toBe(0);
    const files = readdirSync(corpus()).filter((f) => /^s-wb\.wb-[0-9a-f]{24}\.src-_unresolved\.txt$/.test(f));
    expect(files.length).toBe(1);
    const hb = await wbHeartbeats();
    expect(hb[0].reason).toBe('no_serve');
    expect(hb[0].outcome).toBe('degraded');
  });

  test('duplicate turn re-fire: same wb filename, second run is wb_dup — no second file, no re-submit storm', async () => {
    writeConfig({ writeback: 'salient' });
    const t = writeTranscript('I decided to consolidate the staging environments next week.');
    const payload = JSON.stringify({ session_id: 's-wb', transcript_path: t.path });
    expect(await runHook(['stop'], { ...io, transcriptRoot: t.root, stdin: payload })).toBe(0);
    expect(await runHook(['stop'], { ...io, transcriptRoot: t.root, stdin: payload })).toBe(0);
    const files = readdirSync(corpus()).filter((f) => f.includes('.wb-'));
    expect(files.length).toBe(1);
    const hb = await wbHeartbeats();
    expect(hb.length).toBe(2);
    expect(hb.map((e) => e.reason).sort()).toEqual(['no_serve', 'wb_dup']);
  });

  test('serve UP: prompt-harvest ask rides the compact-bank IPC lane with bankOnly + wb basename + trigger + GBRAIN_SOURCE (OV-A6)', async () => {
    const dataDir = writeConfig({ writeback: 'salient' });
    process.env.GBRAIN_SOURCE = 'wiki';
    mkdirSync(dataDir, { recursive: true });
    const secret = ensureIpcSecret(dataDir);
    const seen: ContextPackRequest[] = [];
    const server = await startResolveIpcServer(
      resolveSocketPath(dataDir),
      {
        resolve: async () => null,
        turn_context: async () => null,
        context_pack: async (req: ContextPackRequest) => {
          seen.push(req);
          return { text: '', pointers: [], factsCount: 0, checkpointFlush: { status: 'scheduled' } } as unknown as TurnContextResult;
        },
      },
      { secret },
    );
    expect(server).not.toBeNull();
    servers.push(server!);

    const t = writeTranscript('I moved our weekly sync to Tuesdays at 10am going forward.');
    const code = await runHook(['stop'], {
      ...io, transcriptRoot: t.root,
      stdin: JSON.stringify({ session_id: 's-wb', transcript_path: t.path }),
    });
    expect(code).toBe(0);
    expect(seen.length).toBe(1);
    expect(seen[0].bankOnly).toBe(true);
    expect(seen[0].trigger).toBe('writeback-bank');
    expect(seen[0].sourceId).toBe('wiki');
    // `.src-wiki` banks GBRAIN_SOURCE in the NAME so the sweep fallback
    // files the turn into the same source the IPC lane carries here
    // (source-isolation invariant — adversarial review, this wave).
    expect(seen[0].flushCorpusFile).toMatch(/^s-wb\.wb-[0-9a-f]{24}\.src-wiki\.txt$/);
    const hb = await wbHeartbeats();
    expect(hb.some((e) => e.reason === 'wb_scheduled' && e.outcome === 'ok')).toBe(true);
  });
});

describe('hook stop — pasted content (#5812)', () => {
  const OWN = 'I prefer dark roast coffee and I want it on every order.';

  test('a mixed last turn banks only the user\'s own words', async () => {
    writeConfig({ writeback: 'salient' });
    const t = writeTurns([{ role: 'user', text: `Please remember this note I got: \n\n${PASTE}\n\n ${OWN}` }, { role: 'assistant', text: 'Saved.' }]);
    expect(await runHook(['stop'], { ...io, transcriptRoot: t.root, stdin: JSON.stringify({ session_id: 's-wb', transcript_path: t.path }) })).toBe(0);
    expect(bankedTexts()).toEqual([`Please remember this note I got: ${OWN}\n`]);
  });

  test('a paste-only last turn banks nothing new: the previous genuine turn is the candidate (wb_dup)', async () => {
    writeConfig({ writeback: 'salient' });
    const first = [{ role: 'user' as const, text: OWN }, { role: 'assistant' as const, text: 'Saved.' }];
    let t = writeTurns(first);
    const payload = () => JSON.stringify({ session_id: 's-wb', transcript_path: t.path });
    expect(await runHook(['stop'], { ...io, transcriptRoot: t.root, stdin: payload() })).toBe(0);
    t = writeTurns([...first, { role: 'user', text: `\n\n${PASTE}\n` }, { role: 'assistant', text: 'Is this the same email?' }]);
    expect(await runHook(['stop'], { ...io, transcriptRoot: t.root, stdin: payload() })).toBe(0);
    expect(bankedTexts()).toEqual([`${OWN}\n`]);
    expect((await wbHeartbeats()).map((e) => e.reason)).toEqual(['no_serve', 'wb_dup']);
  });

  test('a session whose only user turn is a paste → no_user_turn, no file', async () => {
    writeConfig({ writeback: 'salient' });
    const t = writeTurns([{ role: 'user', text: PASTE }, { role: 'assistant', text: 'Got it.' }]);
    expect(await runHook(['stop'], { ...io, transcriptRoot: t.root, stdin: JSON.stringify({ session_id: 's-wb', transcript_path: t.path }) })).toBe(0);
    expect(bankedTexts()).toEqual([]);
    expect((await wbHeartbeats())[0]?.reason).toBe('no_user_turn');
  });
});

describe('hook stop — gbrain claude-cli self-capture (#5820)', () => {
  const PROMPT = 'Extract the facts from the following page and return them as JSON objects.';

  test('a Stop payload from a claude-cli scratch session banks nothing: by-design self_capture', async () => {
    writeConfig({ writeback: 'salient' });
    const t = writeTurns([{ role: 'user', text: PROMPT }, { role: 'assistant', text: '{"facts":[]}' }], `-tmp-${CLAUDE_CLI_CWD_PREFIX}4242`);
    expect(await runHook(['stop'], { ...io, transcriptRoot: t.root, stdin: JSON.stringify({ session_id: 's-wb', transcript_path: t.path }) })).toBe(0);
    expect(bankedTexts()).toEqual([]);
    const hb = await wbHeartbeats();
    expect(hb.map((e) => [e.reason, e.outcome])).toEqual([['self_capture', 'ok']]);
  });

  test('the payload cwd fingerprint alone is enough', async () => {
    writeConfig({ writeback: 'salient' });
    const t = writeTurns([{ role: 'user', text: PROMPT }, { role: 'assistant', text: '{"facts":[]}' }]);
    const cwd = join(tmpdir(), `${CLAUDE_CLI_CWD_PREFIX}4242`);
    expect(await runHook(['stop'], { ...io, transcriptRoot: t.root, stdin: JSON.stringify({ session_id: 's-wb', transcript_path: t.path, cwd }) })).toBe(0);
    expect(bankedTexts()).toEqual([]);
    expect((await wbHeartbeats())[0]?.reason).toBe('self_capture');
  });
});