Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
13.9 KB
Raw Blame
/**
 * codex-hook-lane.ts — the HOOK-LANE view of codex rollouts.
 *
 * The import adapter (codex.ts) is an AsyncGenerator TranscriptAdapter with
 * whole-session ParsedSession semantics; the session-end hook needs the
 * claude parser's shape instead (ParsedTranscript: WindowTurn[] + tool calls
 * + boundary positions, bounded reads, engine-free). Line→row mapping is
 * DELEGATED to codex.ts's exported mapCodexLine, so the dated
 * CODEX_SPEC_TARGET stays the single source of truth — the openclaw
 * precedent (mapOpenclawLine / readOpenclawBoundaryTail) exactly.
 *
 * Confinement [S3#8]: the SessionEnd stdin payload is codex-supplied and an
 * agent-steerable input; `transcript_path` is confined to the pinned rollout
 * stores (codexSessionsDir AND codexArchivedSessionsDir — both CODEX_HOME-
 * resolved, since the spawner IS codex) with the same ladder as the claude
 * root. Archived rollouts are inside the fence because codex MOVES a rollout
 * there on archive: fencing only the live store refused a still-valid path as
 * outside_projects_dir. No WSL cross-OS branch v1 (uncharacterized for codex;
 * the reason codes are shared so widening later is additive).
 *
 * Engine-free by construction: node:fs/path + host-specs + codex.ts only —
 * never discover.ts (it imports BrainEngine); discovery is reimplemented
 * fs-only and bounded below.
 *
 * SessionEnd payload spec (observation run, codex-cli 0.147.0, 2026-08-25,
 * live capture): exactly {session_id, transcript_path, cwd, hook_event_name,
 * reason} — transcript_path absolute (null when no local rollout), cwd
 * absolute, reason always "other" in 0.147.0 (never match on it). The
 * rollout is flushed before the hook fires; SessionEnd fires on normal exit,
 * API-error exit, and SIGINT — not SIGKILL (the discovery fallback plus the
 * sweep lane cover that).
 */

import { closeSync, lstatSync, openSync, readdirSync, readFileSync, readSync, statSync } from 'node:fs';
import { join } from 'node:path';
import { codexArchivedSessionsDir, codexSessionsDir } from '../bootstrap/host-specs.ts';
import { isPathContained } from '../path-confine.ts';
import type { ConfineTranscriptResult, ParsedTranscript, ToolCallRecord } from './claude-code-jsonl.ts';
import { capToolCallInput, TRANSCRIPT_HARD_CAP_BYTES, TRANSCRIPT_MAX_BYTES_DEFAULT } from './claude-code-jsonl.ts';
import type { WindowTurn } from '../context/entity-salience.ts';
import { isRepeatedCodexUserTurn, mapCodexLine } from './codex.ts';

/** Head window kept on over-budget reads: session_meta is byte 0 of a rollout
 * and carries the identity a pure tail read would lose (codex.ts rationale). */
const HOOK_HEAD_WINDOW_BYTES = 256 * 1024;

/**
 * Validate an untrusted codex `transcript_path` from hook stdin — the same
 * ladder as claude's confineTranscriptPath, rooted at the codex rollout
 * stores (live + archived). `opts.root` / `opts.archivedRoot` are a TEST SEAM
 * only; production callers use the pinned defaults.
 */
export function confineCodexTranscriptPath(
  p: unknown,
  opts: { root?: string; archivedRoot?: string; maxBytes?: number; allowOversize?: boolean } = {},
): ConfineTranscriptResult {
  if (typeof p !== 'string' || p.length === 0) return { ok: false, reason: 'missing_path' };
  if (!p.endsWith('.jsonl')) return { ok: false, reason: 'not_jsonl' };
  let st: ReturnType<typeof lstatSync>;
  try {
    st = lstatSync(p);
  } catch (err) {
    // ENOENT (nothing at the path) and ENOTDIR (a path component is a file,
    // so the path cannot exist AS GIVEN) both mean "no such transcript",
    // which is the rung hook.ts gates its discovery fallback on. Collapsing
    // them into `unreadable` — a permission/IO fault the caller must NOT
    // paper over — is what left a moved rollout unrecoverable. Discovery is
    // itself id-filtered and root-confined, so routing ENOTDIR there bounds
    // the blast radius of a malformed payload.
    const code = (err as NodeJS.ErrnoException | null)?.code;
    if (code === 'ENOENT' || code === 'ENOTDIR') return { ok: false, reason: 'missing_path' };
    return { ok: false, reason: 'unreadable' };
  }
  if (st.isSymbolicLink()) return { ok: false, reason: 'symlink' };
  if (!st.isFile()) return { ok: false, reason: 'not_file' };
  // #5701: same split as the claude lane — this parser reads a bounded
  // HEAD+TAIL window, so the size gate belongs to the caller that opts out of
  // it, not to the confinement.
  const cap = opts.maxBytes ?? TRANSCRIPT_HARD_CAP_BYTES;
  if (!opts.allowOversize && st.size > cap) return { ok: false, reason: 'too_large' };
  const [root, archivedRoot] = codexRootsFor(opts);
  const contained =
    isPathContained(p, root) || (archivedRoot !== undefined && isPathContained(p, archivedRoot));
  if (!contained) return { ok: false, reason: 'outside_projects_dir' };
  return { ok: true, path: p, size: st.size };
}

/**
 * The confinement/discovery roots for a call. Production (no pinned `root`)
 * gets BOTH codex-owned stores — live and archived. An explicitly pinned
 * `root` stays single-root unless `archivedRoot` is pinned too, so the test
 * seam can never be widened by the widening itself.
 */
function codexRootsFor(opts: {
  root?: string;
  archivedRoot?: string;
}): [live: string, archived: string | undefined] {
  if (opts.root) return [opts.root, opts.archivedRoot];
  return [codexSessionsDir(), opts.archivedRoot ?? codexArchivedSessionsDir()];
}

export interface ParsedCodexTranscript extends ParsedTranscript {
  /** From session_meta (byte 0), surviving even head+tail reads — the stdin
   * fallback when the payload's own session_id is missing. */
  sessionId: string;
  cwd?: string;
}

/**
 * Parse a codex rollout for the hook lane. Under budget: whole-file read.
 * Over budget: HEAD + TAIL (head keeps session_meta identity, tail keeps the
 * newest turns; both torn join lines land in skippedLines — codex.ts's
 * documented accounting). Throws only on filesystem errors — callers confine
 * first and fail open.
 */
/**
 * #8016: Codex bookkeeping events that carry no turn but are expected in a
 * session that opened and closed with no prompt. A named allowlist, so an
 * unknown record type still reads as drift.
 */
const CODEX_BOOKKEEPING_EVENTS = new Set(['thread_settings_applied']);
function isCodexBookkeeping(entry: unknown): boolean {
  const e = entry as { type?: unknown; payload?: { type?: unknown } } | null;
  return e?.type === 'event_msg' && typeof e.payload?.type === 'string' && CODEX_BOOKKEEPING_EVENTS.has(e.payload.type);
}

export function parseCodexHookTranscript(
  path: string,
  opts: { maxBytes?: number; collectToolCalls?: boolean } = {},
): ParsedCodexTranscript {
  // Same contract as parseTranscript's collectToolCalls: the data exists only
  // for the memorable receipt, so collection is OPT-IN — the session-end lane
  // asks only when the memorable gate is open.
  const collectToolCalls = opts.collectToolCalls === true;
  const budget = Math.max(1, Math.floor(opts.maxBytes ?? TRANSCRIPT_MAX_BYTES_DEFAULT));
  const size = statSync(path).size;
  let raw: string;
  let bytesRead: number;
  if (size <= budget) {
    raw = readFileSync(path, 'utf8');
    bytesRead = size;
  } else {
    const head = Math.min(HOOK_HEAD_WINDOW_BYTES, Math.floor(budget / 4));
    const tailBytes = budget - head;
    const fd = openSync(path, 'r');
    try {
      const hbuf = Buffer.alloc(head);
      const hn = readSync(fd, hbuf, 0, head, 0);
      const tbuf = Buffer.alloc(tailBytes);
      const tn = readSync(fd, tbuf, 0, tailBytes, size - tailBytes);
      raw = hbuf.subarray(0, hn).toString('utf8') + '\n' + tbuf.subarray(0, tn).toString('utf8');
      bytesRead = hn + tn;
    } finally {
      closeSync(fd);
    }
  }

  const turns: WindowTurn[] = [];
  const genuineUserTurnIndexes: number[] = [];
  const toolCalls: ToolCallRecord[] = [];
  const toolCallTurnIndexes: number[] = [];
  const boundaryTurnIndexes: number[] = [];
  let sessionId = '';
  let cwd: string | undefined;
  let parsedLines = 0;
  let skippedLines = 0;
  let headerLines = 0;

  for (const line of raw.split('\n')) {
    const t = line.trim();
    if (!t) continue;
    let entry: unknown;
    try {
      entry = JSON.parse(t);
    } catch {
      skippedLines++; // includes head/tail torn join lines
      continue;
    }
    parsedLines++;
    const mapped = mapCodexLine(entry);
    switch (mapped.kind) {
      case 'session':
        headerLines++;
        // #4981: first header wins (a forked rollout inherits its parent's header
        // later in the file); identity is payload.id, the id in the rollout filename.
        if (!sessionId && mapped.sessionId) sessionId = mapped.sessionId;
        if (!cwd && mapped.cwd) cwd = mapped.cwd;
        break;
      case 'user':
        if (isRepeatedCodexUserTurn(turns.at(-1), mapped.message.text)) break;
        genuineUserTurnIndexes.push(turns.length);
        turns.push({ role: mapped.message.role, text: mapped.message.text });
        break;
      case 'assistant':
        turns.push({ role: mapped.message.role, text: mapped.message.text });
        break;
      case 'tool_call':
        // Stamped at the slot it precedes — the claude parser's semantics, so
        // the receipt writer's span filter shares the corpus's origin. No
        // `result`: 0.147.0 persists no success flag on *_output rows and an
        // inferred ok would be a lie (see mapCodexLine).
        if (collectToolCalls) {
          // Same per-string bound as the claude lane's record — one ceiling
          // for every harness, or the receipt-size cap only holds for one.
          toolCalls.push({ name: mapped.name, input: capToolCallInput(mapped.input) });
          toolCallTurnIndexes.push(turns.length);
        }
        break;
      case 'boundary':
        boundaryTurnIndexes.push(turns.length);
        break;
      case 'skip':
        if (isCodexBookkeeping(entry)) headerLines++; // #8016: recognized, carries no turn
        break;
    }
  }

  return {
    turns,
    genuineUserTurnIndexes,
    injectedContextBlocks: [], // codex's injected context is dropped at mapCodexLine, not surfaced
    bytesRead,
    parsedLines,
    skippedLines,
    compactBoundaries: boundaryTurnIndexes.length,
    boundaryTurnIndexes,
    toolCalls,
    toolCallTurnIndexes,
    sessionId,
    cwd,
    recognizedOnly: parsedLines > 0 && skippedLines === 0 && headerLines === parsedLines,
  };
}

/** Total directory entries the discovery walk may touch — a hard cap, not a
 * heuristic (a pathological store degrades to "not found", never a hang). */
const DISCOVERY_DIRENT_CAP = 4096;

/**
 * Bounded newest-first discovery over the rollout stores — the fallback for a
 * SessionEnd payload whose transcript_path is null or has MOVED (archived),
 * and the sweep seam for SIGKILL'd sessions (SessionEnd never fires on
 * SIGKILL). Fs-only walk of the live store: newest 2 year dirs → newest 2
 * month dirs → newest 3 day dirs → rollout-*.jsonl files (symlinks
 * rejected), then a FLAT pass over the archived store, both under one dirent
 * budget. With a session id, the filename must contain it (codex embeds the
 * id in rollout filenames — verified 0.147.0); without one, newest mtime
 * wins across BOTH stores and the caller's degrade names the weaker match.
 * An id-matched archived hit is a MATCH, not a guess — hook.ts reads
 * `transcript_discovered_newest` as "guessed" and suppresses the relay on it,
 * so the archived pass must never relabel a real match. Every miss is a typed
 * reason at the caller — discovery is never silent.
 */
export function discoverNewestCodexRollout(
  sessionId: string | null,
  opts: { root?: string; archivedRoot?: string } = {},
): { path: string; degrade: 'transcript_discovered' | 'transcript_discovered_newest' } | null {
  const [root, archivedRoot] = codexRootsFor(opts);
  let seen = 0;
  const numericDesc = (dir: string, take: number): string[] => {
    try {
      const names = readdirSync(dir, { withFileTypes: true })
        .filter((d) => d.isDirectory() && /^\d+$/.test(d.name))
        .map((d) => d.name)
        .sort((a, b) => Number(b) - Number(a));
      seen += names.length;
      return names.slice(0, take);
    } catch {
      return [];
    }
  };
  const rolloutsIn = (dir: string): string[] => {
    try {
      return readdirSync(dir).filter((f) => f.startsWith('rollout-') && f.endsWith('.jsonl'));
    } catch {
      return [];
    }
  };
  let best: { path: string; mtimeMs: number } | null = null;
  /** Fold one directory's rollouts into `best`; true means the cap tripped. */
  const consider = (dir: string, files: string[]): boolean => {
    for (const f of files) {
      if (++seen > DISCOVERY_DIRENT_CAP) return true;
      if (sessionId && !f.includes(sessionId)) continue;
      const p = join(dir, f);
      try {
        const st = lstatSync(p);
        if (st.isSymbolicLink() || !st.isFile()) continue;
        if (!best || st.mtimeMs > best.mtimeMs) best = { path: p, mtimeMs: st.mtimeMs };
      } catch {
        /* raced away — skip */
      }
    }
    return false;
  };

  let capped = false;
  dated: for (const y of numericDesc(root, 2)) {
    for (const m of numericDesc(join(root, y), 2)) {
      for (const d of numericDesc(join(root, y, m), 3)) {
        const day = join(root, y, m, d);
        if (consider(day, rolloutsIn(day))) {
          capped = true;
          break dated;
        }
      }
    }
  }
  // The archived store is FLAT — no YYYY/MM/DD — so the dated walk above can
  // never reach it (see codexArchivedSessionsDir). Scanned under the SAME
  // dirent budget, and skipped entirely once the cap has tripped so a
  // pathological live store still degrades to "not found", never a hang.
  if (!capped && archivedRoot) consider(archivedRoot, rolloutsIn(archivedRoot));
  return best ? finish(best, sessionId) : null;
}

function finish(
  best: { path: string },
  sessionId: string | null,
): { path: string; degrade: 'transcript_discovered' | 'transcript_discovered_newest' } {
  return { path: best.path, degrade: sessionId ? 'transcript_discovered' : 'transcript_discovered_newest' };
}