Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.0 KB
Raw Blame
/**
 * BrainBench Claude Code adapter — seam: 'production' (v0.46.15, TODOS:556 P1).
 *
 * Drives the REAL shipped integration end-to-end: the fixture turn becomes
 * `UserPromptSubmit` hook stdin JSON, `runHook(['user-prompt'], io)` executes
 * the production hook (stdin parse → transcript-window parse → IPC
 * turn_context → additionalContext), and a run-scoped resolve-IPC server —
 * the SAME `startResolveIpcServer` + `assembleTurnContext` pair `gbrain
 * serve` registers — answers over a real unix socket with the real shared
 * secret. What used to be an in-process contract simulation is now the
 * shipped wire, transcript window, cross-turn dedupe, and IPC auth path.
 *
 * Production-fidelity notes:
 *   - The transcript for each turn is synthesized in the Claude Code JSONL
 *     shape (prior turns + our OWN previously-injected blocks as
 *     `hook_additional_context` attachments), so the hook's 4-turn window
 *     and cross-turn dedupe are exercised for real — the old contract row's
 *     `suppression: 'none'` re-injection cost is replaced by the shipped
 *     dedupe behavior.
 *   - `HookIo.configOverride` + `disablePushBanner` are documented TEST
 *     SEAMS: they point the hook at the bench brain without mutating
 *     process-global GBRAIN_HOME (parallel-test safe) and keep the
 *     operator's push-status files out of the measurement.
 *   - `userPromptDeadlineMs` is pinned generous (10s): the production 800ms
 *     deadline on a loaded CI runner would read as intermittent know-to-ask
 *     misses (flake, not signal). Deadline behavior itself is hook-suite
 *     territory (test/hook-user-prompt.test.ts).
 *   - injectedSlugs = the `→ \`slug\`` references in the rendered block
 *     (reflex pointers + volunteered pages — both are per-turn injection
 *     decisions). Hot-fact entity refs (`[slug]`) are deliberately NOT
 *     counted: hot memory fires on every turn regardless of the prompt, so
 *     counting it would saturate false_fire with a signal the know-to-ask
 *     metric doesn't own.
 */

import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import type { Server } from 'node:net';
import type { BrainEngine } from '../../../core/engine.ts';
import type { GBrainConfig } from '../../../core/config.ts';
import { runHook } from '../../../commands/hook.ts';
import {
  ensureIpcSecret,
  resolveSocketPath,
  startResolveIpcServer,
} from '../../../core/context/resolve-ipc.ts';
import { assembleTurnContext, type TurnContextResult } from '../../../core/context/turn-context.ts';
import { resolveEntitiesToPointers } from '../../../core/context/retrieval-reflex.ts';
import type {
  AdapterFixtureView,
  HarnessAdapter,
  HarnessTurnResult,
  PublicTurn,
} from '../types.ts';
import { estimateTokens } from './shared.ts';

/** stdin JSON the real UserPromptSubmit hook receives. */
export interface UserPromptSubmitHookInput {
  prompt: string;
  session_id: string;
  cwd: string;
  transcript_path?: string;
}

/** stdout JSON the real UserPromptSubmit hook emits. */
export interface UserPromptSubmitHookOutput {
  hookSpecificOutput: {
    hookEventName: 'UserPromptSubmit';
    additionalContext: string;
  };
}

/**
 * Kept for scoreboard continuity: the production hook path has no per-seam
 * pointer budget knob (the server's DEFAULT_MAX_POINTERS governs); this
 * constant now only documents the historical contract-row budget.
 */
export const CLAUDE_CODE_MAX_POINTERS = 2;

/** Generous bench deadline — see the header's flake-class note. */
export const BENCH_USER_PROMPT_DEADLINE_MS = 10_000;

/** `→ \`slug\`` references in a rendered block (pointers + volunteered). */
const INJECTED_SLUG_RE = /→ `([^`\n]+)`/g;

export class ClaudeCodeAdapter implements HarnessAdapter {
  readonly name = 'claude-code' as const;
  readonly seam = 'production' as const;

  private engine: BrainEngine | null = null;
  private sourceId = 'default';
  private sessionId = '';
  private fixtureSeq = 0;

  // ── run-scoped state (setupRun/teardownRun own the server + temp home) ──
  private tmpHome: string | null = null;
  private transcriptRoot: string | null = null;
  private server: Server | null = null;
  private dbPath = '';
  private secret = '';

  // ── per-conversation state ──
  private turns: PublicTurn[] = [];
  private injectionByTurnId = new Map<number, string>();
  /** System One S6 meta from the turn_context handler this turn (present only when recall_needed is not off). */
  private turnDecide: TurnContextResult['decide'];

  async setupRun(): Promise<void> {
    this.tmpHome = mkdtempSync(join(tmpdir(), 'brainbench-cc-'));
    this.transcriptRoot = join(this.tmpHome, 'projects');
    mkdirSync(this.transcriptRoot, { recursive: true });
    // database_path is the IPC data dir: socket + secret live beside it,
    // exactly where the hook's resolveSocketPath/readIpcSecret look.
    this.dbPath = join(this.tmpHome, 'brain.pglite');
    mkdirSync(this.dbPath, { recursive: true });
    this.secret = ensureIpcSecret(this.dbPath);
    this.server = await startResolveIpcServer(
      resolveSocketPath(this.dbPath),
      {
        // The resolve kind mirrors the serve wiring; the hook lane uses
        // turn_context, but a v1 client probing the socket must not crash it.
        // Null-engine guards (adversarial F13b): endConversation nulls the
        // engine while the socket server stays up for the next fixture — a
        // deadline-abandoned in-flight request must degrade to empty, not
        // crash the server on `this.engine!`.
        resolve: (req) =>
          this.engine
            ? resolveEntitiesToPointers(this.engine, this.sourceId, req.candidates ?? [], {
                priorContextText: req.priorContextText,
                maxPointers: req.maxPointers,
                suppression: req.suppression,
                lexicalArms: req.lexicalArms,
              })
            : Promise.resolve(null),
        // The SAME handler shape gbrain serve registers (mcp/server.ts):
        // always assembles against the adapter's active source.
        turn_context: (req) =>
          this.engine
            ? assembleTurnContext(this.engine, {
                sourceId: this.sourceId,
                window: req.window ?? [],
                priorContextText: req.priorContextText,
                sessionId: req.sessionId,
                maxBytes: req.maxBytes,
              }).then((r) => { this.turnDecide = r.decide; return r; })
            : Promise.resolve(null),
      },
      { secret: this.secret },
    );
    if (!this.server) {
      throw new Error('claude-code adapter: could not start the resolve IPC server');
    }
  }

  async teardownRun(): Promise<void> {
    if (this.server) {
      await new Promise<void>((res) => this.server!.close(() => res()));
      this.server = null;
    }
    if (this.tmpHome) {
      rmSync(this.tmpHome, { recursive: true, force: true });
      this.tmpHome = null;
    }
  }

  async beginConversation(engine: BrainEngine, fixture: AdapterFixtureView): Promise<void> {
    if (!this.server) {
      // Legacy single-fixture construction (tests) — own the run lifecycle.
      await this.setupRun();
    }
    this.engine = engine;
    this.sourceId = fixture.active_source;
    this.fixtureSeq += 1;
    this.sessionId = `brainbench-${fixture.fixture_id}-${this.fixtureSeq}`;
    this.turns = fixture.turns;
    this.injectionByTurnId = new Map();
  }

  /**
   * Synthesize the session transcript in the Claude Code JSONL shape: every
   * fixture turn BEFORE the one being replayed (user AND assistant — the
   * harness only replays user turns, but the shipped 4-turn window sees
   * both), with our own prior injections recorded as
   * hook_additional_context attachments right after their user turn.
   */
  private writeTranscript(beforeTurnId: number): string {
    const path = join(this.transcriptRoot!, `${this.sessionId}.jsonl`);
    let body = '';
    for (const t of this.turns) {
      if (t.turn_id >= beforeTurnId) break;
      body += JSON.stringify({ type: t.role, message: { role: t.role, content: t.text } }) + '\n';
      const injected = this.injectionByTurnId.get(t.turn_id);
      if (injected) {
        body += JSON.stringify({
          type: 'attachment',
          attachment: { type: 'hook_additional_context', content: [injected] },
        }) + '\n';
      }
    }
    writeFileSync(path, body);
    return path;
  }

  async replayTurn(turn: PublicTurn, _priorContextText: string): Promise<HarnessTurnResult> {
    if (!this.engine || !this.tmpHome) {
      throw new Error('claude-code adapter: beginConversation not called');
    }
    const started = performance.now();
    this.turnDecide = undefined;

    const transcriptPath = this.writeTranscript(turn.turn_id);
    const wireIn: UserPromptSubmitHookInput = {
      prompt: turn.role === 'user' ? turn.text : '',
      session_id: this.sessionId,
      cwd: this.tmpHome,
      transcript_path: transcriptPath,
    };

    let stdout = '';
    const cfg = { engine: 'pglite', database_path: this.dbPath } as GBrainConfig;
    const exit = await runHook(['user-prompt'], {
      stdin: JSON.stringify(wireIn),
      write: (s) => {
        stdout += s;
      },
      cwd: this.tmpHome,
      transcriptRoot: this.transcriptRoot!,
      userPromptDeadlineMs: BENCH_USER_PROMPT_DEADLINE_MS,
      configOverride: cfg,
      disablePushBanner: true,
      turnRule: null,
      // Telemetry paths resolve from GBRAIN_HOME/homedir, not configOverride
      // — without this, every fixture turn appends to the OPERATOR's real
      // hook heartbeat history (codex ship-review).
      disableTelemetry: true,
    });
    if (exit !== 0) {
      // The hook is fail-open by design (exit 0 on degraded paths); a nonzero
      // exit is a harness bug — fail loud, not as a silent know-to-ask miss.
      throw new Error(`claude-code adapter: hook exit ${exit}`);
    }

    let injected: string | null = null;
    if (stdout.trim()) {
      const parsed = JSON.parse(stdout) as UserPromptSubmitHookOutput;
      injected = parsed.hookSpecificOutput?.additionalContext || null;
    }

    const injectedSlugs: string[] = [];
    if (injected) {
      for (const m of injected.matchAll(INJECTED_SLUG_RE)) {
        if (!injectedSlugs.includes(m[1])) injectedSlugs.push(m[1]);
      }
    }

    const latencyMs = performance.now() - started;
    // Feed the shipped cross-turn dedupe: what we injected THIS turn appears
    // in later turns' transcripts as a hook_additional_context attachment.
    if (injected) this.injectionByTurnId.set(turn.turn_id, injected);

    return {
      injectedText: injected,
      injectedSlugs,
      // The production wire carries rendered text, not pointer objects —
      // metrics score injectedSlugs; receipts show the wire text.
      pointers: [],
      injectedTokens: estimateTokens(injected),
      latencyMs,
      ...(this.turnDecide ? { decide: this.turnDecide } : {}),
    };
  }

  async endConversation(): Promise<void> {
    this.engine = null;
    this.turns = [];
    this.injectionByTurnId = new Map();
  }
}