Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* openclaw.ts — OpenClaw session (.jsonl) adapter (cathedral-4).
*
* One session file = one session; `.checkpoint.<uuid>.jsonl` siblings are
* point-in-time copies and are excluded at DISCOVERY time (detect.ts glob)
* AND defensively here in detect(). Verified against a live local session
* 2026-08-14 (see SPEC_TARGET).
*/
import { readFileSync, statSync } from 'node:fs';
import { basename } from 'node:path';
import type { HostSpecTarget } from '../bootstrap/host-specs.ts';
import type {
FileDiagnostics,
ParsedSession,
ParseSessionsOpts,
TranscriptAdapter,
TranscriptMessage,
} from './types.ts';
import { TRANSCRIPT_JSONL_HARD_CAP, utcTimestamp } from './types.ts';
export const OPENCLAW_SPEC_TARGET: HostSpecTarget = {
id: 'openclaw-session-2026-08',
status: 'verified',
verifiedAt: '2026-08-14',
references: [
'local ~/.openclaw/agents/<agent>/sessions/<uuid>.jsonl (live sample 2026-08-14)',
'test/fixtures/transcripts/agent-session.jsonl',
],
note:
"One JSON object per line. Header: {type:'session', id, cwd, timestamp, " +
"version}. Turns: {type:'message', timestamp, message:{role, content, " +
"timestamp}} where content is [{type:'text', text}] blocks (non-text " +
'blocks skipped for TEXT). model_change / thinking_level_change / custom / ' +
"compaction lines are skipped. Sibling files named " +
"'<id>.checkpoint.<uuid>.jsonl' are snapshots, never imported. Unknown " +
'fields tolerated. Tool calls: content blocks {type:\'toolCall\', id, name} ' +
'(fixture-verified NAME-ONLY — the args field name and any result block ' +
'shape are PROVISIONAL/unobserved as of 2026-08-25; extraction ships ' +
'input:null and no result until a live session store characterizes them, ' +
'deliberately never guessing keys into an egress payload).',
};
const CHECKPOINT_RE = /\.checkpoint\.[^./]+\.jsonl$/;
/** True for `<id>.checkpoint.<uuid>.jsonl` snapshot siblings. */
export function isOpenclawCheckpointFile(path: string): boolean {
return CHECKPOINT_RE.test(path);
}
/**
* GST-2768: the retained transcript archives OpenClaw keeps under sessions/ (its isRetainedSessionTranscriptArchiveName,
* OpenClaw 2026.10.9 and 2026.11.3): `<id>.jsonl.reset.<stamp>`, `<id>.jsonl.deleted.<stamp>` and the legacy
* pre-compaction backup `<id>.jsonl.bak.<stamp>`, each optionally `.<32 hex>` and zstd `.zst` (recorded on both
* versions: `<id>.jsonl.deleted.2026-11-15T06-38-21.539Z.<hex>.zst`). Same line format as a live session file, so they
* are read; two files of one session merge in the archive reader.
*/
const ARCHIVED_RE = /\.jsonl\.(?:reset|deleted|bak)\.\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(?:\.\d{3})?Z(?:\.[0-9a-f]{32})?(?:\.zst)?$/;
export function isOpenclawArchivedFile(path: string): boolean {
return ARCHIVED_RE.test(path);
}
/**
* Files OpenClaw keeps beside sessions that are never read as conversations: migration rollback copies
* (`*.migrated`, `*.migrated.<n>` and `<id>.jsonl.pre-doctor-<kind>-repair-<stamp>.bak`, its
* isMigrationArchiveArtifactName: the original of a transcript already imported into the session database, which
* the Gateway serves) and Doctor's recovery copies of a zero-byte transcript (`<id>.jsonl.bak-<pid>-<timestamp>`).
* Reading them would count one conversation twice.
*/
const SKIPPED_RE = /(?:\.migrated(?:\.\d+)?|\.jsonl\.pre-doctor-[a-z-]+-repair-[0-9TZ:.-]+\.bak|\.jsonl\.bak-\d+-[0-9TZ:.-]+)$/;
export function isOpenclawSkippedArtifact(path: string): boolean {
return SKIPPED_RE.test(path);
}
async function readSessionText(path: string): Promise<string> {
const bytes = readFileSync(path);
if (!path.endsWith('.zst')) return bytes.toString('utf8');
const zlib = (await import('node:zlib')) as unknown as { zstdDecompressSync?: (b: Buffer) => Buffer };
const bun = (globalThis as { Bun?: { zstdDecompressSync?: (b: Buffer) => Uint8Array } }).Bun;
const out = zlib.zstdDecompressSync ? zlib.zstdDecompressSync(bytes) : bun?.zstdDecompressSync?.(bytes);
if (!out) throw new Error('openclaw archived session is zstd-compressed and this runtime has no zstd decoder');
return Buffer.from(out).toString('utf8');
}
/**
* One parsed openclaw session line, classified (cathedral-5). Exported so the
* compaction-boundary tail reader (corpus-segments) reuses the SAME
* line→message mapping as the import adapter — the dated SPEC_TARGET above
* stays the single source of truth for the format. `boundary` is a
* {type:'compaction'} line (excluded from messages, positions recorded by
* boundary-aware callers); `session` is the header line; `skip` covers
* model_change / thinking_level_change / custom / non-text / malformed.
*/
export type OpenclawLineResult =
| { kind: 'message'; message: TranscriptMessage; toolCalls?: OpenclawToolCall[] }
| { kind: 'boundary' }
| { kind: 'session'; id?: string; cwd?: string; startedAt?: string }
| { kind: 'skip'; toolCalls?: OpenclawToolCall[] };
/**
* A tool call surfaced from an openclaw message's content blocks
* (ToolCallRecord-shaped, memorable integration). NAME-ONLY v1: the fixture
* and spec target pin only {type:'toolCall', id, name}; the args field name is
* unobserved, and guessing keys (`arguments` ?? `args` ?? `input`) would feed
* speculative data into an egress payload — so `input` is literally null until
* an observation run characterizes the field. `result` is omitted for the
* same reason. Rides on OpenclawLineResult (a `skip` line can still carry
* calls — a placeholder-only message has no text but its calls are real work).
*/
export interface OpenclawToolCall {
name: string;
input: null;
}
/** Map one ALREADY-JSON-PARSED openclaw session line. */
export function mapOpenclawLine(entry: unknown): OpenclawLineResult {
if (typeof entry !== 'object' || entry === null) return { kind: 'skip' };
const e = entry as Record<string, unknown>;
if (e.type === 'session') {
return {
kind: 'session',
id: typeof e.id === 'string' ? e.id : undefined,
cwd: typeof e.cwd === 'string' ? e.cwd : undefined,
startedAt: typeof e.timestamp === 'string' ? utcTimestamp(e.timestamp) : undefined,
};
}
if (e.type === 'compaction') return { kind: 'boundary' };
if (e.type !== 'message') return { kind: 'skip' }; // model_change / custom / …
const msg = e.message;
if (typeof msg !== 'object' || msg === null) return { kind: 'skip' };
const m = msg as Record<string, unknown>;
const role = m.role === 'user' || m.role === 'assistant' ? m.role : null;
if (!role) return { kind: 'skip' };
const content = m.content;
let text = '';
const toolCalls: OpenclawToolCall[] = [];
if (typeof content === 'string') {
text = content;
} else if (Array.isArray(content)) {
const parts: string[] = [];
for (const block of content) {
if (typeof block !== 'object' || block === null) continue;
const b = block as Record<string, unknown>;
if (b.type === 'text' && typeof b.text === 'string' && b.text.trim()) parts.push(b.text);
if (b.type === 'toolCall' && typeof b.name === 'string' && b.name) toolCalls.push({ name: b.name, input: null });
}
text = parts.join('\n');
}
text = text.trim();
if (!text) return toolCalls.length > 0 ? { kind: 'skip', toolCalls } : { kind: 'skip' };
const timestamp = utcTimestamp(typeof m.timestamp === 'string' && m.timestamp ? m.timestamp : e.timestamp);
return { kind: 'message', message: { role, timestamp, text }, ...(toolCalls.length > 0 ? { toolCalls } : {}) };
}
export const openclawAdapter: TranscriptAdapter = {
format: 'openclaw',
specTarget: OPENCLAW_SPEC_TARGET,
detect(path: string, sample: Buffer): boolean {
if (isOpenclawCheckpointFile(path)) return false;
if (isOpenclawArchivedFile(path) && path.endsWith('.zst')) return true;
if (!path.endsWith('.jsonl') && !isOpenclawArchivedFile(path)) return false;
const firstLine = sample.toString('utf8').split('\n', 1)[0]?.trim();
if (!firstLine) return false;
try {
const obj = JSON.parse(firstLine) as Record<string, unknown>;
return obj !== null && typeof obj === 'object' && obj.type === 'session' && typeof obj.id === 'string';
} catch {
return false;
}
},
async *parse(path: string, opts: ParseSessionsOpts = {}): AsyncGenerator<ParsedSession, FileDiagnostics> {
const cap = opts.maxBytes ?? TRANSCRIPT_JSONL_HARD_CAP;
const size = statSync(path).size;
if (size > cap) {
throw new Error(`openclaw session too large for import: ${size} bytes (cap ${cap})`);
}
const raw = await readSessionText(path);
if (raw.length > cap) {
throw new Error(`openclaw session too large for import: ${raw.length} characters decompressed (cap ${cap})`);
}
let skippedLines = 0;
let sessionId = '';
let cwd: string | undefined;
let startedAt = '';
const messages: TranscriptMessage[] = [];
for (const line of raw.split('\n')) {
const t = line.trim();
if (!t) continue;
let entry: unknown;
try {
entry = JSON.parse(t);
} catch {
skippedLines++;
continue;
}
const mapped = mapOpenclawLine(entry);
if (mapped.kind === 'session') {
if (mapped.id) sessionId = mapped.id;
if (mapped.cwd) cwd = mapped.cwd;
if (mapped.startedAt) startedAt = mapped.startedAt;
continue;
}
if (mapped.kind !== 'message') continue; // boundary / model_change / custom
messages.push(mapped.message);
}
let sessions = 0;
if (messages.length > 0) {
sessions = 1;
const sid = sessionId || basename(path).split('.jsonl')[0]!;
yield {
meta: {
harness: 'openclaw',
sessionId: sid,
cwd,
startedAt: startedAt || messages[0].timestamp || undefined,
raw: { session_id: sid, cwd: cwd ?? null, source_path: path },
},
messages,
};
}
return {
bytesRead: size,
skippedLines,
truncated: false,
sessions,
zeroSessionsReason: sessions === 0 ? 'no text-bearing message lines in session file' : undefined,
};
},
};