Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* claude-code.ts — TranscriptAdapter wrapper over the SHIPPED Claude Code
* parser (claude-code-jsonl.ts). The wrapper adds nothing to the parsing —
* the hardened parser, its SPEC_TARGET, and its fixture stay the single
* source of truth; this file only adapts its output to the seam contract
* (one .jsonl file = one session, timestamps preserved via
* parseClaudeSessionFile).
*/
import type {
FileDiagnostics,
ParsedSession,
ParseSessionsOpts,
TranscriptAdapter,
} from './types.ts';
import { TRANSCRIPT_JSONL_HARD_CAP, utcTimestamp } from './types.ts';
import { parseClaudeSessionFile, SPEC_TARGET } from './claude-code-jsonl.ts';
import { basename } from 'node:path';
import { closeSync, openSync, readSync } from 'node:fs';
/**
* Non-turn control records Claude Code writes into the session JSONL. These now
* routinely LEAD the file, and they carry no `parentUuid`/`isSidechain`, so a
* detector keyed only on turn shape rejects the whole transcript.
*
* Measured 2026-08-16 over 400 files in ~/.claude/projects: 273 led with
* `queue-operation`, 115 with `last-prompt`, 10 with `mode`, 2 with `ai-title`
* — and ZERO led with a user/assistant turn. Detection failure was total.
*/
const CLAUDE_CONTROL_TYPES = new Set([
'queue-operation',
'last-prompt',
'ai-title',
'mode',
'summary',
'attachment',
]);
/**
* True for a Claude Code SUBAGENT log:
* `<project>/<session-uuid>/subagents/agent-<id>.jsonl`. Every line in one is
* `isSidechain` (the parser skips them all, so the file parses to zero turns)
* and carries the PARENT session's id — it is not a session and can never
* import. Discovery and explicit-path expansion both skip these so they stop
* reading as a permanent not-yet-imported backlog + host-format drift (#4796).
* STRICT shape (a path segment literally `subagents` AND basename
* `agent-*.jsonl`) so a user project whose slug merely contains "subagents" is
* never hidden: Claude Code encodes a whole project path as ONE slug segment
* (`-Users-me-subagents-thing`), which never equals `subagents` exactly.
*
* The segment is matched at ANY depth above the file, not just the immediate
* parent. Workflow runs nest a second level —
* `<session>/subagents/workflows/<wf-id>/agent-<id>.jsonl` — and an
* immediate-parent check missed every one of them, so they stayed a permanent
* gap-table phantom and re-fired DRIFT WARNING on every ingest: the exact
* failure this function exists to prevent.
*/
export function isClaudeCodeSubagentFile(path: string): boolean {
const segs = path.split(/[/\\]/);
const base = segs[segs.length - 1] ?? '';
if (!/^agent-[^/\\]+\.jsonl$/.test(base)) return false;
return segs.slice(0, -1).includes('subagents');
}
/**
* True for a file inside a Claude Code WORKFLOW run directory:
* `<session>/subagents/workflows/<wf-id>/...`. The tree holds one
* `agent-<id>.jsonl` per fanned-out agent plus a `journal.jsonl` run log —
* bookkeeping for a workflow, never a top-level session. The journal is not
* a transcript in ANY adapter's format, so leaving it discoverable made every
* ingest report `unknown format` and, because an errored file also clears
* `cleanScan`, held the `--since last` watermark frozen indefinitely.
*
* Deliberately narrower than "everything under `subagents/`": a UUID-named
* file directly under `subagents/` IS a real session and must stay
* discoverable (pinned by transcripts-self-exclusion.test.ts).
*/
export function isClaudeCodeWorkflowArtifactFile(path: string): boolean {
const segs = path.split(/[/\\]/);
const i = segs.lastIndexOf('subagents');
return i !== -1 && segs[i + 1] === 'workflows' && segs.length > i + 2;
}
/**
* Claude Code Remote Control state files written next to session JSONL
* (`<session-uuid>.ccr-tip.json`, `bridge-pointer.json`). They match the
* importable `.json` extension but are never transcripts (#5597).
*/
const CCR_TIP_SUFFIX = '.ccr-tip.json';
const CCR_BRIDGE_POINTER = 'bridge-pointer.json';
/** True for Claude Code Remote Control state files (never transcripts). */
export function isClaudeCodeRemoteControlStateFile(path: string): boolean {
const segs = path.split(/[/\\]/);
const base = segs[segs.length - 1] ?? '';
if (base.endsWith(CCR_TIP_SUFFIX) || base === CCR_BRIDGE_POINTER) return true;
// Per-session layout (Claude Code 2.1.x): side files live INSIDE the
// `<session-uuid>/` directory.
const isSession = (s: string | undefined) => !!s && SESSION_DIR_RE.test(s);
const parent = segs[segs.length - 2];
if ((base === 'ccr-tip.json' || base === 'custom-title.json') && isSession(parent)) return true;
if (/^agent-[^/\\]+\.meta\.json$/.test(base) && parent === 'subagents' && isSession(segs[segs.length - 3])) {
return true;
}
return /^wf_[^/\\]+\.json$/.test(base) && parent === 'workflows' && isSession(segs[segs.length - 3]);
}
const SESSION_DIR_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
/** True for Claude Code's per-project session index (`sessions-index.json`), which lists sessions and holds no turns. */
export function isClaudeCodeSessionsIndexFile(path: string): boolean {
return (path.split(/[/\\]/).pop() ?? '') === 'sessions-index.json';
}
/** Keys that mark a Claude Code project transcript. */
function looksLikeClaudeLine(obj: Record<string, unknown>): boolean {
if (
typeof obj.sessionId === 'string' &&
(obj.type === 'user' || obj.type === 'assistant')
) {
return true;
}
// Control records: `sessionId` + a known control `type` is a specific enough
// pair that no other supported harness collides with it.
if (
typeof obj.sessionId === 'string' &&
typeof obj.type === 'string' &&
CLAUDE_CONTROL_TYPES.has(obj.type)
) {
return true;
}
// Non-turn head lines (summary, attachment) still carry the shape family.
return 'isSidechain' in obj || 'parentUuid' in obj;
}
/**
* How many leading lines of the sample to examine. Scanning past line 1 is
* defence-in-depth for control types not in the set above: a single unknown
* record at the head must not disqualify the file. Bounded so detection stays
* cheap — the sample is only 64KB, and a single queued-prompt record can exceed
* that on its own (observed: the first real turn at byte 88,283).
*/
const DETECT_SCAN_LINES = 25;
/**
* Bounded re-read used when the sample yields no parseable record. A single
* leading control record can exceed the 64KB sample on its own, leaving the
* sample holding one truncated partial line and nothing else.
*/
const DETECT_FALLBACK_BYTES = 2 * 1024 * 1024;
/** True when any of the first DETECT_SCAN_LINES lines is Claude-shaped. */
function scanForClaudeLine(text: string): boolean {
for (const raw of text.split('\n', DETECT_SCAN_LINES)) {
const line = raw.trim();
if (!line) continue;
let obj: unknown;
try {
obj = JSON.parse(line);
} catch {
// Byte-bounded reads routinely end mid-line; keep scanning.
continue;
}
if (typeof obj === 'object' && obj !== null && looksLikeClaudeLine(obj as Record<string, unknown>)) {
return true;
}
}
return false;
}
export const claudeCodeAdapter: TranscriptAdapter = {
format: 'claude-code',
specTarget: SPEC_TARGET,
detect(path: string, sample: Buffer): boolean {
if (!path.endsWith('.jsonl')) return false;
if (scanForClaudeLine(sample.toString('utf8'))) return true;
// The sample can be entirely consumed by one oversized leading record
// (observed: first real turn at byte 88,283 against a 64KB sample), so a
// negative result there is inconclusive. Re-read a bounded window before
// rejecting the file.
// Only worth re-reading when the sample holds no line terminator at all:
// that means one record already exceeded the sample and we never saw a
// complete line. Files with short lines fail fast here, as they should.
if (sample.includes(0x0a)) return false;
let fd: number | undefined;
try {
fd = openSync(path, 'r');
const buf = Buffer.allocUnsafe(DETECT_FALLBACK_BYTES);
const read = readSync(fd, buf, 0, DETECT_FALLBACK_BYTES, 0);
return scanForClaudeLine(buf.subarray(0, read).toString('utf8'));
} catch {
return false;
} finally {
if (fd !== undefined) {
try { closeSync(fd); } catch { /* best effort */ }
}
}
},
async *parse(
path: string,
opts: ParseSessionsOpts = {},
): AsyncGenerator<ParsedSession, FileDiagnostics> {
const r = parseClaudeSessionFile(path, {
maxBytes: opts.maxBytes ?? TRANSCRIPT_JSONL_HARD_CAP,
});
const sessionId = r.sessionId || basename(path, '.jsonl');
let sessions = 0;
if (r.turns.length > 0) {
sessions = 1;
yield {
meta: {
harness: 'claude-code',
sessionId,
cwd: r.cwd,
startedAt: utcTimestamp(r.startedAt) || undefined,
raw: { sessionId, cwd: r.cwd ?? null, source_path: path },
},
messages: r.turns.map((t) => ({
role: t.role,
timestamp: utcTimestamp(t.timestamp),
text: t.text,
})),
};
}
// A file with NO turn-shaped records never had anything to import: a
// title/metadata-only stub (`last-prompt` + `custom-title` and nothing
// else), explicitly non-human text, or all-`isSidechain` subagent traffic.
// That is understood, not host-format drift, so it must not freeze the
// shared watermark. As with grok's expectedEmpty, turn records that stop
// yielding text (`turnShapedLines > 0` with zero turns) still drift, and
// so does any file with unparseable lines.
const expectedEmpty =
sessions === 0 && r.skippedLines === 0 && r.turnShapedLines === 0;
return {
bytesRead: r.bytesRead,
skippedLines: r.skippedLines,
truncated: false,
sessions,
expectedEmpty: expectedEmpty || undefined,
zeroSessionsReason:
sessions === 0
? expectedEmpty
? 'no turn records in file (title/metadata-only, non-human text only, or all-subagent)'
: 'no user or assistant turns in file'
: undefined,
userTurnsMissing: r.turns.length > 0 && r.excludedUserLines === 0 && !r.turns.some((t) => t.role === 'user') ? true : undefined,
};
},
};