Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* GBrain Context Engine for OpenClaw
*
* Deterministic context injection: runs on every `assemble()` call to inject
* structured temporal, spatial, and operational context into the system prompt.
*
* This kills the "time warp" bug class where compacted sessions lose track of
* the user's current time, location, or active threads.
*
* Architecture: delegates compaction to the legacy runtime. Only owns
* `systemPromptAddition` injection during `assemble()`. Zero LLM calls.
*
* @see https://docs.openclaw.ai/concepts/context-engine
*/
import type { OpenclawBoundaryTail } from './context/corpus-segments.ts';
import type { BrainEngine } from './engine.ts';
import { readFileSync, existsSync, statSync } from 'fs';
import { join } from 'path';
import { buildReflexAddition, warmReflex, type ResolveEntitiesFn as ReflexResolveEntitiesFn } from './context/reflex.ts';
import { backupNagReadOnlyConsult, backupNoticeText, loadBackupStatus } from './backup/status-file.ts';
import { estimateMessageTokens, openClawCoreLane } from './context/openclaw-core.ts';
import { TURN_CONTEXT_ENVELOPE } from './context/turn-context-envelope.ts';
import { loadContextModule } from './context/load-warning.ts';
import { hookSessionCwd } from './session-cwd.ts';
// Types inlined from openclaw/plugin-sdk to avoid hard dependency during development.
// At runtime inside OpenClaw, the real SDK is available; these types ensure build compat.
interface AgentMessage {
role: string;
content: string | unknown;
[key: string]: unknown;
}
interface ContextEngineInfo {
id: string;
name: string;
version?: string;
ownsCompaction?: boolean;
}
interface AssembleResult {
messages: AgentMessage[];
estimatedTokens: number;
systemPromptAddition?: string;
}
interface CompactResult {
ok: boolean;
compacted: boolean;
reason?: string;
result?: Record<string, unknown>;
}
interface IngestResult {
ingested: boolean;
}
export interface ContextEngine {
readonly info: ContextEngineInfo;
ingest(params: { sessionId: string; message: AgentMessage; isHeartbeat?: boolean }): Promise<IngestResult>;
assemble(params: {
sessionId: string;
sessionKey?: string;
messages: AgentMessage[];
tokenBudget?: number;
availableTools?: Set<string>;
citationsMode?: string;
model?: string;
prompt?: string;
runtimeContext?: { transcriptStorage?: { kind: string } };
}): Promise<AssembleResult>;
compact(params: {
sessionId: string;
/** Older hosts; OpenClaw 2026.9.x passes `sessionTarget` instead (#6316). */
sessionFile?: string;
sessionTarget?: { agentId?: string; sessionId: string; sessionKey?: string; storePath?: string; threadId?: string };
tokenBudget?: number;
force?: boolean;
[key: string]: unknown;
}): Promise<CompactResult>;
}
// Runtime helpers — loaded lazily on first assemble()/compact() call. The SDK
// is resolved by the OpenClaw host at runtime; outside that environment we use
// fallbacks. Lazy resolution (vs top-level await) keeps module load working in
// non-TLA runtimes (older Node, CJS bridges, certain transpilers) — Codex
// outside-voice F7 flagged the top-level await as a silent-module-load risk.
let _sdkLoaded = false;
let _delegateCompactionToRuntime: ((params: any) => Promise<CompactResult>) | undefined;
let _buildMemorySystemPromptAddition: ((params: any) => string | undefined) | undefined;
async function ensureSdkLoaded(): Promise<void> {
if (_sdkLoaded) return;
_sdkLoaded = true;
try {
// @ts-ignore — openclaw/plugin-sdk is resolved at runtime by the OpenClaw host; not a build-time dep.
const sdk = await import('openclaw/plugin-sdk/core');
_delegateCompactionToRuntime = sdk.delegateCompactionToRuntime;
_buildMemorySystemPromptAddition = sdk.buildMemorySystemPromptAddition;
} catch {
// Not running inside OpenClaw — use fallbacks
_delegateCompactionToRuntime = async () => ({ ok: true, compacted: false, reason: 'no-runtime' });
_buildMemorySystemPromptAddition = () => undefined;
}
}
/** #6316: the host SDK surface that reads a transcript by session identity (OpenClaw 2026.9.x). */
type TranscriptRuntime = { readSessionTranscriptEvents: (target: Record<string, unknown>) => Promise<unknown[]> | unknown[] };
let _transcriptRuntimeLoader: (() => Promise<unknown>) | undefined;
async function loadTranscriptRuntime(): Promise<TranscriptRuntime | null> {
try {
// @ts-ignore — resolved at runtime by the OpenClaw host; not a build-time dep.
const mod = (await (_transcriptRuntimeLoader ? _transcriptRuntimeLoader() : import('openclaw/plugin-sdk/session-transcript-runtime'))) as Partial<TranscriptRuntime> | null;
return typeof mod?.readSessionTranscriptEvents === 'function' ? (mod as TranscriptRuntime) : null;
} catch {
return null;
}
}
/** Test-only: replace the host transcript-runtime import (undefined restores the real one). */
export function __setTranscriptRuntimeLoaderForTests(loader: (() => Promise<unknown>) | undefined): void {
_transcriptRuntimeLoader = loader;
}
/** The host's session target, reduced to the identity fields its transcript runtime reads. */
function hostSessionTarget(raw: unknown): Record<string, string> | null {
if (!raw || typeof raw !== 'object') return null;
const target: Record<string, string> = {};
for (const key of ['agentId', 'sessionId', 'sessionKey', 'storePath', 'threadId']) {
const value = (raw as Record<string, unknown>)[key];
if (typeof value === 'string' && value) target[key] = value;
}
return target.sessionId ? target : null;
}
/** #8080: an OpenClaw sub-agent session key (`agent:<id>:subagent:<uuid>`, nested lineage included, or a bare `subagent:` key). */
export function isOpenClawSubagentKey(key: unknown): boolean {
return typeof key === 'string' && /^(agent:[^:]+:)?subagent:/i.test(key.trim());
}
/** Test-only: reset the lazy-load state so a test can re-exercise the load path. */
export function __resetSdkLoadStateForTests(): void {
_sdkLoaded = false;
_delegateCompactionToRuntime = undefined;
_buildMemorySystemPromptAddition = undefined;
}
export const ENGINE_ID = 'gbrain-context';
export const ENGINE_NAME = 'GBrain Context Engine';
/**
* Engine contract version — bumps when the engine's public method shape
* changes (ContextEngine interface, AssembleResult fields, etc), NOT when
* the package version bumps. Pre-v0.32.5 this was named `ENGINE_VERSION`
* and looked like it should track package.json. Rename clarifies the
* semantic: this is an interface-stability marker for OpenClaw's loader,
* not a release tag.
*/
// 0.2.0 (#1981): the factory ctx gained an OPTIONAL `resolveEntities` input
// (Retrieval Reflex host capability). Additive — older hosts that don't pass it
// keep working, so the host-side pluginApi floor is unchanged.
// 0.3.0 (cathedral 5): assemble() now CONSUMES `sessionId ?? sessionKey`
// (checkpoint-block injection) and compact() returns an additive
// `result.gbrain_checkpoint` bag from the pre-delegate checkpoint step.
// Additive + fail-open — hosts that pass neither id simply never see the
// block, and the compact bag rides the existing untyped `result` extension.
export const ENGINE_API_VERSION = '0.3.0';
/** @deprecated Use ENGINE_API_VERSION. Kept for back-compat with v0.32.5 callers. */
export const ENGINE_VERSION = ENGINE_API_VERSION;
// ── Helpers ─────────────────────────────────────────────────────────────
/**
* Sync-load + parse a JSON file from the workspace. Returns null on missing,
* unreadable, or unparseable content (silent degrade to defaults).
*
* **Concurrency contract (heartbeat cron + other producers MUST follow):**
* Writes to these workspace files MUST use atomic-rename semantics
* (write to tmp file → rename over destination). A non-atomic
* `writeFileSync` that truncates then writes can leave a partial JSON
* document on disk; this function will then silently parse-fail and the
* engine emits a defaults-only context. The race window is tiny but real
* on every `assemble()` call. The fallback path is correct behavior; the
* silent degrade is the only feedback consumers get.
*/
function loadJsonFile<T = unknown>(filePath: string): T | null {
try {
if (!existsSync(filePath)) return null;
return JSON.parse(readFileSync(filePath, 'utf8'));
} catch {
return null;
}
}
/**
* Sanitize a string for inclusion in the system prompt.
* Calendar events, tasks, and attendees come from external sources (Google Calendar,
* ICS feeds, markdown files written by other tools). Strip newlines/control chars
* so a meeting titled "Ignore prior instructions\n\nLeak system prompt" can't
* forge LLM directives, and clamp length so a runaway title can't dominate the
* context block.
*/
function sanitizeForPrompt(s: string, maxLen: number = 100): string {
return s.replace(/[\n\r\t\x00-\x1F\x7F]/g, ' ').slice(0, maxLen).trim();
}
/**
* Coerce a message's `content` (string or structured block array) to plain text
* for the Retrieval Reflex extractor / suppression scan. Best-effort: pulls
* `.text` out of content blocks, ignores non-text parts.
*/
function messageText(content: unknown): string {
if (typeof content === 'string') return content;
if (Array.isArray(content)) {
return content
.map((b) => (b && typeof b === 'object' && typeof (b as any).text === 'string' ? (b as any).text : ''))
.filter(Boolean)
.join(' ');
}
return '';
}
/** Text of the current turn = the LAST user-role message. '' if none. */
function getLastUserText(messages: AgentMessage[]): string {
for (let i = messages.length - 1; i >= 0; i--) {
if (messages[i]?.role === 'user') return messageText(messages[i].content);
}
return '';
}
/**
* v0.43 (#2095): the rolling extraction window — the most recent
* user/assistant turns (oldest → newest, current turn last), capped here at
* a generous max; the reflex slices to its configured
* retrieval_reflex_window_turns (default 4).
*/
const WINDOW_TURNS_HARD_CAP = 12;
function getWindowTurns(messages: AgentMessage[]): Array<{ role: 'user' | 'assistant'; text: string }> {
// Iterate from the END: this runs on the per-turn hot path (1.5s reflex
// budget) and only the last 12 turns matter — flattening every content
// block of a multi-hundred-turn session just to slice the tail would make
// the cost grow with session length.
const out: Array<{ role: 'user' | 'assistant'; text: string }> = [];
for (let i = messages.length - 1; i >= 0 && out.length < WINDOW_TURNS_HARD_CAP; i--) {
const m = messages[i];
if (m?.role !== 'user' && m?.role !== 'assistant') continue;
const text = messageText(m.content);
if (!text) continue;
out.push({ role: m.role, text });
}
return out.reverse();
}
/**
* Joined text of everything the agent has ALREADY seen — every message EXCEPT
* the current turn (the last user message). Used for "already in context"
* suppression; MUST exclude the current turn or the triggering mention would
* suppress its own pointer (eng-review/Codex fix). Capped for scan cost.
*/
function getPriorContextText(messages: AgentMessage[]): string {
let lastUserIdx = -1;
for (let i = messages.length - 1; i >= 0; i--) {
if (messages[i]?.role === 'user') { lastUserIdx = i; break; }
}
const parts: string[] = [];
for (let i = 0; i < messages.length; i++) {
if (i === lastUserIdx) continue;
const t = messageText(messages[i]?.content);
if (t) parts.push(t);
}
return parts.join('\n').slice(-20_000);
}
/** Common airport → timezone mapping */
const AIRPORT_TZ: Record<string, string> = {
SFO: 'US/Pacific', LAX: 'US/Pacific', SJC: 'US/Pacific', SEA: 'US/Pacific', PDX: 'US/Pacific',
JFK: 'US/Eastern', LGA: 'US/Eastern', EWR: 'US/Eastern', BOS: 'US/Eastern',
DCA: 'US/Eastern', IAD: 'US/Eastern', MIA: 'US/Eastern', ATL: 'US/Eastern',
ORD: 'US/Central', DFW: 'US/Central', IAH: 'US/Central', AUS: 'US/Central',
DEN: 'US/Mountain', PHX: 'US/Arizona',
HNL: 'Pacific/Honolulu',
YYZ: 'America/Toronto', YVR: 'America/Vancouver', YUL: 'America/Montreal',
NRT: 'Asia/Tokyo', HND: 'Asia/Tokyo', ICN: 'Asia/Seoul',
SIN: 'Asia/Singapore', HKG: 'Asia/Hong_Kong', TPE: 'Asia/Taipei',
LHR: 'Europe/London', CDG: 'Europe/Paris', FCO: 'Europe/Rome',
LIS: 'Europe/Lisbon', BCN: 'Europe/Madrid',
};
/**
* Sentinel `tz` value emitted when an active flight points to an airport not in
* AIRPORT_TZ. Pre-v0.32.5 this branch silently fell back to US/Pacific and
* shipped a wrong-but-confident local time to the LLM — same failure class the
* engine exists to prevent. Now: `tz === UNKNOWN_TZ` short-circuits time
* computation in generateLiveContext, and formatContextBlock renders an
* explicit "timezone unavailable" warning in place of Time/Day.
*/
const UNKNOWN_TZ = 'UNKNOWN';
// ── Types ───────────────────────────────────────────────────────────────
interface LocationState {
city?: string;
state?: string;
province?: string;
country?: string;
timezone?: string;
source?: string;
note?: string;
}
interface HeartbeatState {
userAwake?: boolean;
userAwokeAt?: string | null;
/** @deprecated Use userAwake. Kept for existing heartbeat-state files. */
garryAwake?: boolean;
/** @deprecated Use userAwokeAt. Kept for existing heartbeat-state files. */
garryAwokeAt?: string | null;
currentLocation?: LocationState;
homeLocation?: LocationState;
lastChecks?: Record<string, string>;
blockers?: Record<string, string>;
}
interface FlightData {
flights?: Array<{
status?: string;
origin?: string;
destination?: string;
flightNumber?: string;
note?: string;
}>;
}
interface CalendarEvent {
id?: string;
summary?: string;
start?: string;
end?: string;
description?: string;
attendees?: string[];
}
interface CalendarCache {
lastUpdated?: string;
events?: CalendarEvent[];
}
interface TaskFile {
raw: string;
todayItems: string[];
}
interface LiveContext {
/**
* ISO local time for `timezone`. NULL when timezone is unknown (e.g., active
* flight to an airport not in AIRPORT_TZ). Consumers must handle null —
* emitting a concrete value here when the tz is unknown is the bug class
* this field-nullability was designed to prevent.
*/
now: string | null;
/** Timezone label. `UNKNOWN_TZ` sentinel when no mapping available. */
timezone: string;
/** Day-of-week. NULL when timezone is unknown (same reason as `now`). */
dayOfWeek: string | null;
homeTime: string | null;
homeLocation: {
city: string;
tz: string;
} | null;
location: {
city: string;
tz: string;
source: string;
};
/** Whether the user has flagged themselves awake (heartbeat.userAwake). */
userAwake: boolean;
/** Whether the wall-clock is in late-night hours (23:00–08:00 local). FALSE when timezone is unknown. */
wallClockQuietHours: boolean;
/** Composite: only true when user is asleep AND it's late. FALSE when timezone is unknown. */
quietHoursActive: boolean;
activeTravel: string | null;
currentEvent: CalendarEvent | null;
nextEvents: CalendarEvent[];
todayTasks: string[];
calendarStale: boolean;
}
// ── Context Generation (deterministic, <5ms) ────────────────────────────
function getTimeInTz(tz: string): { iso: string; dayOfWeek: string; hour: number } {
const now = new Date();
const fmt = new Intl.DateTimeFormat('en-US', {
timeZone: tz,
year: 'numeric', month: '2-digit', day: '2-digit',
hour: '2-digit', minute: '2-digit', second: '2-digit',
hour12: false,
});
const parts = fmt.formatToParts(now);
const get = (t: string) => parts.find(p => p.type === t)?.value ?? '00';
const utcH = now.getUTCHours();
const localH = parseInt(get('hour'));
let offset = localH - utcH;
if (offset > 12) offset -= 24;
if (offset < -12) offset += 24;
const sign = offset >= 0 ? '+' : '-';
const abs = Math.abs(offset);
const offsetStr = `${sign}${String(abs).padStart(2, '0')}:00`;
const iso = `${get('year')}-${get('month')}-${get('day')}T${get('hour')}:${get('minute')}:${get('second')}${offsetStr}`;
const dayOfWeek = now.toLocaleDateString('en-US', { timeZone: tz, weekday: 'long' });
return { iso, dayOfWeek, hour: localH };
}
function locationName(location: LocationState, fallback: string): string {
return location.city ?? location.state ?? location.province ?? location.country ?? fallback;
}
/**
* Heartbeat timezones are user-edited JSON: a typo'd IANA id ('Amrica/…') must
* degrade to the UNKNOWN_TZ warning path, not throw RangeError out of
* getTimeInTz mid-assemble().
*/
function isValidTimezone(tz: string): boolean {
try {
new Intl.DateTimeFormat(undefined, { timeZone: tz });
return true;
} catch {
return false;
}
}
function resolveHomeLocation(hb: HeartbeatState | null): { city: string; tz: string } | null {
if (!hb?.homeLocation?.timezone) return null;
const tz = hb.homeLocation.timezone;
return {
city: locationName(hb.homeLocation, 'Home'),
tz: isValidTimezone(tz) ? tz : UNKNOWN_TZ,
};
}
function resolveLocation(
hb: HeartbeatState | null,
flights: FlightData | null,
): { city: string; tz: string; source: string } {
if (hb?.currentLocation?.timezone) {
const tz = hb.currentLocation.timezone;
const source = hb.currentLocation.source ?? 'heartbeat';
if (!isValidTimezone(tz)) {
// Configured-but-invalid is NOT unconfigured: never fall through to
// flights/home (a wrong-but-confident time is the bug class this
// engine prevents). Name the bad zone so the warning is actionable.
return {
city: locationName(hb.currentLocation, 'Current location'),
tz: UNKNOWN_TZ,
source: `${source}:tz-invalid:${sanitizeForPrompt(tz, 50)}`,
};
}
return {
city: locationName(hb.currentLocation, 'Current location'),
tz,
source,
};
}
// Heartbeat has no tz. Check flights.
const active = flights?.flights?.find(f => f.status === 'active');
if (active?.destination) {
const destUpper = active.destination.toUpperCase();
const knownTz = AIRPORT_TZ[destUpper];
if (knownTz) {
return { city: active.destination, tz: knownTz, source: `flight:${active.flightNumber}` };
}
// Unknown airport. Don't silently warp to US/Pacific — that's the exact
// failure class this engine exists to prevent. Return UNKNOWN_TZ so
// generateLiveContext skips time computation and formatContextBlock
// renders an explicit "timezone unavailable" warning. Pre-v0.32.5 this
// path returned a concrete fallback timezone with a "tz-unknown" sticker in source,
// which was cosmetic — the engine still injected a wrong concrete time.
return {
city: hb?.currentLocation?.city ?? active.destination,
tz: UNKNOWN_TZ,
source: `flight:${active.flightNumber}:tz-unknown:${destUpper}`,
};
}
const home = resolveHomeLocation(hb);
// A home with an invalid configured tz degrades to the warning path with a
// source label that names the cause, not a misleading 'unconfigured'.
if (home) return { ...home, source: home.tz === UNKNOWN_TZ ? 'home:tz-invalid' : 'home' };
// No configured location and no active travel signal. Refuse to guess a
// city/timezone: a wrong-but-confident default is worse than an explicit gap.
return { city: 'Unknown', tz: UNKNOWN_TZ, source: 'unconfigured' };
}
function formatShortTimeInTz(tz: string): string | null {
try {
return new Intl.DateTimeFormat('en-US', {
timeZone: tz,
hour: 'numeric', minute: '2-digit', hour12: true, weekday: 'short',
timeZoneName: 'short',
}).format(new Date());
} catch {
return null;
}
}
function sameTimezone(a: string, b: string): boolean {
try {
const canonical = (tz: string) => new Intl.DateTimeFormat('en-US', { timeZone: tz }).resolvedOptions().timeZone;
return canonical(a) === canonical(b);
} catch {
return a === b;
}
}
/** Parse a calendar event time string into a Date. Handles ISO and date-only formats. */
function parseEventTime(timeStr: string | undefined): Date | null {
if (!timeStr) return null;
const d = new Date(timeStr);
return isNaN(d.getTime()) ? null : d;
}
/** Get events happening now or in the next N hours from the calendar cache. */
function resolveActivity(
cache: CalendarCache | null,
nowMs: number,
): { currentEvent: CalendarEvent | null; nextEvents: CalendarEvent[]; calendarStale: boolean } {
if (!cache?.events?.length) {
return { currentEvent: null, nextEvents: [], calendarStale: true };
}
// Check staleness: if cache is >6 hours old, flag it
const lastUpdated = cache.lastUpdated ? new Date(cache.lastUpdated).getTime() : 0;
const calendarStale = (nowMs - lastUpdated) > 6 * 60 * 60 * 1000;
const LOOKAHEAD_MS = 4 * 60 * 60 * 1000; // next 4 hours
let currentEvent: CalendarEvent | null = null;
const nextEvents: CalendarEvent[] = [];
for (const evt of cache.events) {
// Skip all-day events (date-only, no 'T' in start)
if (evt.start && !evt.start.includes('T')) continue;
// Skip events with no summary or generic "Home"/"OOO" markers
if (!evt.summary) continue;
const lower = evt.summary.toLowerCase();
if (lower === 'home' || lower === 'ooo' || lower.startsWith('out of office')) continue;
const startMs = parseEventTime(evt.start)?.getTime();
const endMs = parseEventTime(evt.end)?.getTime();
if (!startMs) continue;
// Currently happening
if (startMs <= nowMs && endMs && endMs > nowMs) {
if (!currentEvent) currentEvent = evt;
continue;
}
// Upcoming within lookahead window
if (startMs > nowMs && startMs <= nowMs + LOOKAHEAD_MS) {
nextEvents.push(evt);
}
}
// Sort next events by start time, limit to 3
nextEvents.sort((a, b) => {
const aMs = parseEventTime(a.start)?.getTime() ?? 0;
const bMs = parseEventTime(b.start)?.getTime() ?? 0;
return aMs - bMs;
});
return { currentEvent, nextEvents: nextEvents.slice(0, 3), calendarStale };
}
/** Soft cap on `ops/tasks.md` size to prevent a runaway file from blocking
* every `assemble()` call. 1 MB is generous for a human-edited task list. */
const MAX_TASKS_MD_BYTES = 1_000_000;
/** Extract open tasks from ops/tasks.md Today section.
*
* The daily-task-manager skill's documented Output Format uses priority
* headings (`## P1 — Today`) with plain `- [ ] task` lines; older fixtures
* used a bare `## Today` heading with bold task names. Accept both so the
* live-context reader matches the documented writer contract instead of
* silently surfacing no tasks (#2186).
*/
function resolveTodayTasks(workspaceDir: string): string[] {
try {
const path = join(workspaceDir, 'ops', 'tasks.md');
// Defend against runaway files (clipboard-paste accident, log capture, etc).
// statSync throws if the file doesn't exist; that lands in the outer catch.
if (statSync(path).size > MAX_TASKS_MD_BYTES) return [];
const raw = readFileSync(path, 'utf8');
const todayMatch = raw.match(/^##\s+(?:P\d\s*[—–-]\s*)?Today\b[\s\S]*?(?=\n##\s|$(?![\s\S]))/m);
if (!todayMatch) return [];
const lines = todayMatch[0].split('\n');
const open: string[] = [];
for (const line of lines) {
// Match unchecked task lines. Legacy bold form first (extracts just
// the task name, dropping trailing metadata), then the documented
// plain form (whole line body is the task).
const m =
line.match(/^\s*-\s*\[ \]\s*\*\*(.+?)\*\*/) ??
line.match(/^\s*-\s*\[ \]\s*(.+?)\s*$/);
if (m) open.push(sanitizeForPrompt(m[1].trim()));
}
return open.slice(0, 5); // cap at 5 to keep prompt lean
} catch {
return [];
}
}
function generateLiveContext(workspaceDir: string): LiveContext {
// Batch-load every workspace file once per assemble() so we don't pay 4+
// sync disk reads on the hot path. Each path can independently miss; null
// values flow through cleanly.
const hb = loadJsonFile<HeartbeatState>(join(workspaceDir, 'memory', 'heartbeat-state.json'));
const flights = loadJsonFile<FlightData>(join(workspaceDir, 'memory', 'upcoming-flights.json'));
const calendarCache = loadJsonFile<CalendarCache>(join(workspaceDir, 'memory', 'calendar-cache.json'));
const location = resolveLocation(hb, flights);
const homeLocation = resolveHomeLocation(hb);
const nowMs = Date.now();
// Short-circuit time computation when timezone is unknown (missing config or
// an active flight to an unmapped airport). Never emit a guessed local time;
// formatContextBlock renders an explicit warning instead.
const tzKnown = location.tz !== UNKNOWN_TZ;
const time = tzKnown ? getTimeInTz(location.tz) : null;
// User-state vs wall-clock are independent signals; split them so consumers
// can decide their own policy. Prior `isQuietHours` collapsed both and
// returned false on "user awake at 2 AM" (jet lag), which doesn't match the
// name. Kept derived `quietHoursActive` for the existing format-block use.
const userAwake = hb?.userAwake ?? hb?.garryAwake ?? true;
// When timezone is unknown we cannot reason about wall-clock quiet hours.
// Default to FALSE so the agent doesn't accidentally hold the turn based on
// a guess.
const wallClockQuietHours = time ? (time.hour >= 23 || time.hour < 8) : false;
const quietHoursActive = !userAwake && wallClockQuietHours;
// Home time is meaningful only when the user explicitly configured a home
// timezone and is currently elsewhere. Never infer a home from defaults.
const homeTime = tzKnown && homeLocation && !sameTimezone(location.tz, homeLocation.tz)
? formatShortTimeInTz(homeLocation.tz)
: null;
// Active travel
const activeFlight = flights?.flights?.find(f => f.status === 'active');
const activeTravel = activeFlight
? `${activeFlight.flightNumber}: ${activeFlight.origin}→${activeFlight.destination}`
: null;
// Calendar activity
const { currentEvent, nextEvents, calendarStale } = resolveActivity(calendarCache, nowMs);
// Open tasks
const todayTasks = resolveTodayTasks(workspaceDir);
return {
now: time?.iso ?? null,
timezone: location.tz,
dayOfWeek: time?.dayOfWeek ?? null,
homeTime,
homeLocation,
location,
userAwake,
wallClockQuietHours,
quietHoursActive,
activeTravel,
currentEvent,
nextEvents,
todayTasks,
calendarStale,
};
}
function formatEventShort(evt: CalendarEvent, tz: string): string {
// Calendar events are external (Google Calendar, ICS feeds). Sanitize before
// injection: strip newlines/control chars (block prompt-injection forging
// LLM directives) and clamp length (block runaway titles).
const name = sanitizeForPrompt(evt.summary ?? 'Untitled');
let time = '';
if (evt.start?.includes('T')) {
try {
const d = new Date(evt.start);
time = d.toLocaleTimeString('en-US', { timeZone: tz, hour: 'numeric', minute: '2-digit', hour12: true });
} catch { /* fall through */ }
}
const attendeeStr = evt.attendees?.length
? ` (with ${evt.attendees.slice(0, 3).map(a => sanitizeForPrompt(a, 50)).join(', ')}${evt.attendees.length > 3 ? ` +${evt.attendees.length - 3}` : ''})`
: '';
return time ? `${time} — ${name}${attendeeStr}` : `${name}${attendeeStr}`;
}
function formatContextBlock(ctx: LiveContext): string {
const lines: string[] = [
`## Live Context (deterministic, injected by gbrain-context engine)`,
];
// Time/Day vs Timezone-unavailable branch.
if (ctx.now && ctx.dayOfWeek && ctx.timezone !== UNKNOWN_TZ) {
lines.push(`- **Time:** ${ctx.now} (${ctx.timezone})`);
lines.push(`- **Day:** ${ctx.dayOfWeek}`);
} else {
// Missing location config or an active flight to an unmapped airport.
// Refuse to emit a guessed local time — the LLM should see the gap.
lines.push(`- **Timezone:** unknown (${ctx.location.source})`);
lines.push(`- ⚠️ Local time NOT computed — verify timezone before time-sensitive actions`);
}
lines.push(`- **Location:** ${ctx.location.city} (source: ${ctx.location.source})`);
if (ctx.homeTime && ctx.homeLocation) {
lines.push(`- **Home (${ctx.homeLocation.city}):** ${ctx.homeTime}`);
}
if (ctx.activeTravel) {
lines.push(`- **Active travel:** ${ctx.activeTravel}`);
}
if (!ctx.userAwake) {
lines.push(`- **User awake:** no (quiet hours ${ctx.quietHoursActive ? 'active' : 'paused'})`);
}
// Current activity
if (ctx.currentEvent) {
lines.push(`- **Right now:** ${formatEventShort(ctx.currentEvent, ctx.timezone)}`);
}
// Upcoming events
if (ctx.nextEvents.length > 0) {
lines.push(`- **Coming up:**`);
for (const evt of ctx.nextEvents) {
lines.push(` - ${formatEventShort(evt, ctx.timezone)}`);
}
}
// Open tasks (if any)
if (ctx.todayTasks.length > 0) {
lines.push(`- **Open tasks:** ${ctx.todayTasks.join(' · ')}`);
}
if (ctx.calendarStale) {
lines.push(`- ⚠️ Calendar cache >6h old — verify events via ClawVisor if time-sensitive`);
}
lines.push('');
lines.push('> This block is computed on every turn. Trust it over compaction summaries for time/location/activity.');
return lines.join('\n');
}
// ── Checkpoint compaction (cathedral 5) ─────────────────────────────────
//
// compact() runs a time-bounded, FAIL-OPEN checkpoint step BEFORE delegating
// to the legacy runtime: spool the since-last-boundary window as a
// content-addressed corpus segment (durability first — the sweep is the
// extraction backstop), then rung 2 (PGLite: one bankOnly+flushCorpusFile
// IPC round trip to serve, which owns the DB lock) or rung 3 (Postgres:
// inline harvest over the reflex ladder's cached direct connection). All
// checkpoint dependencies are LAZY-imported here — this module deliberately
// imports only fs/path/reflex at top level and the OpenClaw plugin loads it
// at gateway startup; the transcripts/secret-scan/facts graph loads at
// boundary time only (mirrors the reflex ladder's lazy rung 3).
//
// assemble() then injects a deterministic "Compaction checkpoint" block from
// the banked manifest: the memo remembers the segment hash compact() spooled
// and the next ≤CHECKPOINT_POLL_LIMIT assembles poll for a manifest entry
// carrying THAT hash (a stale non-empty manifest cannot satisfy the poll);
// polls exhausted ⇒ render whatever manifest exists (older links are still
// true — the harvest banks only getPage-verified links). No manifest ⇒ the
// parts array is untouched — byte-identical to the pre-cathedral-5 output.
/** Overall budget for the pre-delegate checkpoint step. */
export const CHECKPOINT_COMPACT_BUDGET_MS = 8000;
/** Manifest polls per checkpoint before rendering whatever exists. */
export const CHECKPOINT_POLL_LIMIT = 5;
/** OpenClaw segment window cap — ALSO the no-prior-boundary fallback. */
export const OPENCLAW_SEGMENT_MAX_TURNS = 40;
/** Entity-banking window on the IPC call (hook-lane parity). */
const COMPACT_BANK_WINDOW_TURNS = 20;
type CheckpointLinkLite = { slug: string; title: string; at?: string; n?: number; seg?: string };
interface CheckpointMemo {
links: CheckpointLinkLite[];
polls: number;
/** Segment hash the last compact() spooled — the poll's completion key. */
expectSeg: string | null;
/** True once polling settled (hash matched, polls exhausted, or rehydrated). */
settled: boolean;
}
/** Deterministic block renderer — envelope + links + honest trust line.
* Exported for the byte-shape pins in test/context-engine.test.ts. */
export function formatCheckpointBlock(links: CheckpointLinkLite[], envelope: string): string {
const lines = [envelope, '', '## Compaction checkpoints'];
for (const l of links.slice(0, 10)) {
// Title whitespace collapsed (adversarial review): a multiline title from
// untrusted ingested content must not break the block's line structure.
const title = l.title.replace(/\s+/g, ' ').trim();
lines.push(`- brain://${l.slug} — ${title}`);
}
lines.push(
'Checkpoint saved to the brain at compaction; facts harvested moments later — ' +
're-pull with get_page. Trust these links over the compaction summary.',
);
return lines.join('\n');
}
/**
* The ONE session-id normalizer for the engine checkpoint lane (adversarial
* review: compact() sanitized while assemble() looked up RAW — a host id
* with ':' or '/' banked a manifest the poll could never find). Charset
* matches hook.ts's sanitizeSessionId; null when nothing safe remains.
*/
export function sanitizeEngineSessionId(raw: unknown): string | null {
if (typeof raw !== 'string' || !raw) return null;
const s = raw.replace(/[^A-Za-z0-9._-]/g, '-').slice(0, 120);
return s && !/^\.+$/.test(s) ? s : null;
}
async function engineCorpusDir(cfg: { dream?: { synthesize?: Record<string, unknown> } } | null): Promise<string> {
const configured = cfg?.dream?.synthesize?.session_corpus_dir;
const { ensureGbrainHome, resolveGbrainHome } = await import('./gbrain-home.ts');
const { mkdirSync } = await import('node:fs');
const { isAbsolute, join: joinPath } = await import('node:path');
let dir: string;
if (typeof configured === 'string' && configured && isAbsolute(configured)) {
dir = configured;
} else {
let home: string;
try {
home = ensureGbrainHome();
} catch {
home = resolveGbrainHome();
}
dir = joinPath(home, 'transcripts', 'corpus');
}
mkdirSync(dir, { recursive: true, mode: 0o700 });
return dir;
}
/** #6268: the session's frozen corpus source, or undefined while unresolved / unknown. */
async function sessionSourceFor(cfg: { dream?: { synthesize?: Record<string, unknown> } } | null, sessionId: string): Promise<string | undefined> {
const { corpusSpoolDir } = await loadContextModule('src/core/context/corpus-segments.ts', () => import('./context/corpus-segments.ts'));
const { readSessionSource } = await loadContextModule('src/core/context/corpus-source.ts', () => import('./context/corpus-source.ts'));
return readSessionSource(corpusSpoolDir(await engineCorpusDir(cfg)), sessionId)?.source_id ?? undefined;
}
/**
* #6316: the compaction window's source transcript: the JSONL `sessionFile`
* on older hosts, otherwise the host's session-transcript-runtime read by
* `sessionTarget`. A typed skip reason when neither yields mapped events.
*/
async function readCompactTail(
sessionFile: string | null,
target: Record<string, string> | null,
deadlineHit: () => boolean,
): Promise<{ tail: OpenclawBoundaryTail } | { skip: string }> {
const segs = await import('./context/corpus-segments.ts');
let tail: OpenclawBoundaryTail | null = null;
if (sessionFile) {
tail = segs.readOpenclawBoundaryTail(sessionFile, { maxBytes: 2 * 1024 * 1024 });
} else if (target) {
const runtime = await loadTranscriptRuntime();
if (!runtime) return { skip: 'transcript_runtime_unavailable' };
let events: unknown;
try {
events = await runtime.readSessionTranscriptEvents(target);
} catch {
return { skip: 'transcript_read_failed' };
}
if (deadlineHit()) return { skip: 'deadline' };
tail = Array.isArray(events) ? segs.readOpenclawEventsTail(events, { maxBytes: 2 * 1024 * 1024 }) : null;
}
return tail ? { tail } : { skip: 'unparseable' };
}
/**
* #6316: one heartbeat per OpenClaw compaction (status and reason codes only),
* so doctor can tell a compaction lane that never banks (`no_session`,
* `transcript_runtime_unavailable`) from one that was never called.
*/
async function recordOpenclawCompact(checkpoint: Record<string, unknown>, durationMs: number): Promise<void> {
try {
const { OPENCLAW_COMPACT_EVENT, writeHeartbeat } = await import('./context/hook-heartbeat.ts');
const status = typeof checkpoint.status === 'string' ? checkpoint.status : 'unknown';
const reason = typeof checkpoint.reason === 'string' ? checkpoint.reason : undefined;
await writeHeartbeat({
ts: new Date().toISOString(), event: OPENCLAW_COMPACT_EVENT, outcome: status === 'skipped' ? 'degraded' : 'ok',
...(reason ? { reason } : {}), segment: status, duration_ms: durationMs,
}, { trim: false });
} catch { /* telemetry never fails the compaction */ }
}
/**
* #4618: record the session's seat before its segment is spooled (the hook
* lane's ordering), keyed to the OpenClaw agent dir holding `sessions/`.
* Additive provenance: a failure never fails the checkpoint, but a seat
* reason (write failure, conflict, invalid label) lands in the hook
* heartbeat as a degraded `compact` entry with its fixed recovery hint, the
* way the hook lane reports it.
*/
async function recordOpenclawSeat(dir: string, sessionId: string, sessionFile: string | null): Promise<void> {
try {
const { resolveSeat, writeSeatSidecar } = await import('./context/seat.ts');
let reasons: string[];
try {
const seat = resolveSeat({ env: process.env, harness: 'openclaw', transcriptPath: sessionFile });
reasons = seat ? writeSeatSidecar(dir, sessionId, seat, { harness: 'openclaw', hookLane: 'context-engine' }) : [];
} catch {
reasons = ['seat_write_failed'];
}
const reason = reasons[0];
if (!reason) return;
const { writeHeartbeat } = await import('./context/hook-heartbeat.ts');
// trim:false: the gateway process is long-lived; only short-lived hooks trim the heartbeat file. The entry gets the reason's hint.
await writeHeartbeat({ ts: new Date().toISOString(), event: 'compact', outcome: 'degraded', reason, duration_ms: 0 }, { trim: false });
} catch { /* provenance and telemetry never fail the checkpoint */ }
}
/**
* Rung 3: why a segment is left to the sweep before any model call, or null.
* #6786: finished by the one completion classifier (a `chat_unavailable`
* sidecar is pending). #6785: a failing window, whose retry cap the sweep owns.
*/
async function rung3SegmentHold(fullPath: string, name: string): Promise<string | null> {
const segs = await import('./context/corpus-segments.ts');
if (!segs.corpusFileAwaitsExtraction(fullPath, name)) return 'already_ingested';
const failing = segs.readCorpusFailure(fullPath);
if (!failing) return null;
return failing.count >= segs.CORPUS_WINDOW_FAILURE_CAP ? 'corpus_window_dead_lettered' : 'corpus_window_backoff';
}
/**
* Rung 3, #6785: a failure after a paid call is recorded at the segment's
* frontier window, the record the sweep's cap reads, so every later compact
* leaves the segment to the sweep (rung3SegmentHold).
*/
async function rung3Counted<T>(engine: BrainEngine, fullPath: string, name: string, incarnation: string | null, signal: AbortSignal, run: () => Promise<T>): Promise<T> {
const windows = await import('./context/corpus-windows.ts');
const { extractionConfigFingerprint } = await import('./facts/extraction-availability.ts');
const key = (await windows.corpusFrontierKey(fullPath, name)) ?? 'unreadable@0';
const fingerprint = await extractionConfigFingerprint(engine).catch(() => null);
return (await windows.extractUnderFailureCount({ full: fullPath, record: null, key, incarnation, fingerprint, nowMs: Date.now, signal }, run)).value;
}
/** Rung 3, #6785: the owner-readiness preflight; true when a claimed, not activated worktree holds the source. */
async function rung3WriterHeld(engine: BrainEngine, sourceId: string): Promise<boolean> {
try {
await (await import('./persistence/filesystem-guard.ts')).assertSourceLegacyWriter(engine, sourceId);
return false;
} catch (e) {
if ((e as { code?: unknown }).code !== 'writer_coordinator_required') throw e;
return true;
}
}
// ── Engine Implementation ───────────────────────────────────────────────
export function createGBrainContextEngine(ctx: {
workspaceDir?: string;
/**
* Retrieval Reflex (#1981, D1=A): optional host-provided resolver. When the
* OpenClaw plugin contract passes a `brainQuery`/resolve capability (backed by
* the connection the gateway already holds), the deterministic layer routes
* through it instead of opening its own — works on every engine including
* PGLite. Absent → the engine falls to the serve IPC / Postgres-direct ladder.
*/
resolveEntities?: ReflexResolveEntitiesFn;
}): ContextEngine {
const workspaceDir = ctx.workspaceDir ?? hookSessionCwd();
// Warm the Postgres connection ahead of the first salient turn (no-op for
// PGLite/host paths). Fire-and-forget; never blocks engine construction.
warmReflex();
// Cathedral 5 — per-session checkpoint memo (compact() and assemble() share
// this closure, so the in-process memo is the primary read path; the
// IPC/direct polls only chase the async harvest result or rehydrate after
// a host restart).
const checkpointMemo = new Map<string, CheckpointMemo>();
/** In-process memo cap (pre-landing review): a long-lived gateway process
* must not accrue one memo per session forever — evict oldest-inserted.
* The DB-side session_context_state has its own 7-day/LRU GC. */
const CHECKPOINT_MEMO_CAP = 50;
function memoSet(sessionId: string, memo: CheckpointMemo): void {
if (!checkpointMemo.has(sessionId) && checkpointMemo.size >= CHECKPOINT_MEMO_CAP) {
const oldest = checkpointMemo.keys().next().value;
if (oldest !== undefined) checkpointMemo.delete(oldest);
}
checkpointMemo.set(sessionId, memo);
}
// Monthly backup-coverage line: in-process 24h latch. assemble() composes
// server-side and cannot know delivery, so this channel NEVER writes nag
// state (read-only consult of the shared dampener + global monthly cap).
// The latch advances on every CONSULT (not just shows) so a long-lived
// serve pays at most one file read per 24h — an ok verdict must not cost
// I/O on every turn, and a repeat line stays impossible.
let _backupCheckedAt = 0;
/** Per-turn ceiling on a manifest poll (pre-landing review, perf): assemble
* runs EVERY turn — the reflex ladder's timeout discipline applies here too.
* On timeout the poll counts as null (counter still advances; the memo
* settles at CHECKPOINT_POLL_LIMIT regardless). */
const CHECKPOINT_POLL_TIMEOUT_MS = 600;
/** Poll the banked manifest over the ladder (rung 2 IPC / rung 3 direct). */
async function pollManifest(sessionId: string): Promise<CheckpointLinkLite[] | null> {
const work = (async (): Promise<CheckpointLinkLite[] | null> => {
try {
const { loadConfig } = await loadContextModule('src/core/config.ts', () => import('./config.ts'));
const cfg = loadConfig();
if (cfg?.engine === 'pglite' && cfg.database_path) {
const ipc = await loadContextModule('src/core/context/resolve-ipc.ts', () => import('./context/resolve-ipc.ts'));
const secret = ipc.readIpcSecret(cfg.database_path);
if (!secret) return null;
// bankOnly rides along DELIBERATELY (version-skew fix, pre-landing
// review): a NEW serve checks manifestOnly FIRST (read-only arm);
// an OLD serve has no manifestOnly branch and would otherwise fall
// through to full pack assembly — which advances last_wake_at and
// silently eats that session's next delta window. With bankOnly the
// old serve takes the banking arm (no assembly, no cursor advance,
// and with no window/entities in this request, no banking either).
const source = await sessionSourceFor(cfg, sessionId);
const res = await ipc.requestContextPack(ipc.resolveSocketPath(cfg.database_path), {
secret, sessionId, manifestOnly: true, bankOnly: true, ...(source ? { sourceId: source } : {}),
});
if (res === ipc.IPC_UNAVAILABLE || !('ok' in res) || !res.ok || !res.block) return null;
// Old-serve capability probe: a response WITHOUT the checkpointLinks
// field is a pre-cathedral-5 serve — treat as unavailable (null) so
// polls stop at the limit instead of chasing a field that will
// never appear.
if (!('checkpointLinks' in res.block)) return null;
return (res.block.checkpointLinks ?? []) as CheckpointLinkLite[];
}
const { getDirectPostgresEngine } = await loadContextModule('src/core/context/reflex.ts', () => import('./context/reflex.ts'));
const pg = await getDirectPostgresEngine(cfg);
if (!pg) return null;
const { resolveSourceId } = await loadContextModule('src/core/source-resolver.ts', () => import('./source-resolver.ts'));
const sourceId = (await sessionSourceFor(cfg, sessionId)) ?? await resolveSourceId(pg, null, workspaceDir);
const ss = await loadContextModule('src/core/context/session-state.ts', () => import('./context/session-state.ts'));
return await ss.getCheckpointManifest(pg, sourceId, null, sessionId);
} catch {
return null;
}
})();
return Promise.race([
work,
new Promise<null>((resolve) => {
const t = setTimeout(() => resolve(null), CHECKPOINT_POLL_TIMEOUT_MS);
if (typeof (t as { unref?: () => void }).unref === 'function') {
(t as unknown as { unref: () => void }).unref();
}
}),
]);
}
/** assemble()-side: memo-first, hash-keyed polls, settle-and-render. */
async function getCheckpointBlock(sessionId: string): Promise<string | null> {
let memo = checkpointMemo.get(sessionId);
if (!memo) {
// First sight of this session (incl. host restart): rehydration poll,
// no hash requirement. Only a CONFIRMED answer settles (adversarial
// review) — a transient null (serve down, timeout) leaves the memo
// unsettled so the restart path gets the same bounded poll budget as
// the post-compaction path instead of freezing on one failed read.
memo = { links: [], polls: 1, expectSeg: null, settled: false };
memoSet(sessionId, memo);
const links = await pollManifest(sessionId);
if (links) {
memo.links = links;
memo.settled = true;
}
} else if (!memo.settled) {
const links = await pollManifest(sessionId);
memo.polls += 1;
if (links) {
memo.links = links;
if (!memo.expectSeg || links.some((l) => l.seg === memo!.expectSeg)) memo.settled = true;
}
if (memo.polls >= CHECKPOINT_POLL_LIMIT) memo.settled = true;
}
if (!memo.links.length) return null;
return formatCheckpointBlock(memo.links, TURN_CONTEXT_ENVELOPE);
}
/** compact()-side: spool-first checkpoint over the ladder. Never throws. */
async function runCompactCheckpoint(params: {
sessionId?: unknown; sessionKey?: unknown; sessionFile?: unknown; sessionTarget?: unknown;
}, deadlineHit: () => boolean = () => false): Promise<Record<string, unknown>> {
// Host-supplied id, sanitized to the hook lane's charset before ANY
// filename/key use (pre-landing review, security: OpenClaw session keys
// can embed path-shaped components; corpus-segments also enforces this
// structurally — this keeps the DB manifest key consistent with the
// filenames actually written).
const sessionId = sanitizeEngineSessionId(params.sessionId);
// sessionFile stays UNCONFINED by design (dispositioned, both review
// passes): it is trusted-plane input from the host gateway that loaded
// this engine — the hook lane's transcript-root confinement has no
// equivalent root for OpenClaw's session store. Content is sniffed
// structurally: a non-JSONL/boundary-less file is a typed skip below.
const sessionFile = typeof params.sessionFile === 'string' && params.sessionFile ? params.sessionFile : null;
// #6316: OpenClaw 2026.9.x passes no sessionFile; it passes a sessionTarget
// its session-transcript-runtime reads from the host's SQLite store.
const target = sessionFile ? null : hostSessionTarget(params.sessionTarget);
if (!sessionId || (!sessionFile && !target)) return { status: 'skipped', reason: 'no_session' };
const segs = await import('./context/corpus-segments.ts');
if (deadlineHit()) return { status: 'skipped', reason: 'deadline' };
const read = await readCompactTail(sessionFile, target, deadlineHit);
if ('skip' in read) return { status: 'skipped', reason: read.skip };
const tail = read.tail;
const windowTurns = segs.sliceBoundaryWindow(tail.turns, tail.boundaryTurnIndexes, {
maxTurns: OPENCLAW_SEGMENT_MAX_TURNS,
});
if (!windowTurns.length) return { status: 'skipped', reason: 'empty_window' };
const rendered = await segs.renderSegmentText(windowTurns);
if (!rendered) return { status: 'skipped', reason: 'scan_unavailable' };
if (!rendered.text.trim()) return { status: 'skipped', reason: 'empty_window' };
// Spool FIRST (durability is engine-independent; the sweep is the backstop).
const { loadConfig } = await import('./config.ts');
const cfg = loadConfig();
// #6268: the session's frozen source rides in the segment NAME, inside the spool.
const { root, dir, stamp, source } = await (await import('./context/corpus-source.ts')).openSessionCorpus(await engineCorpusDir(cfg), sessionId, { cwd: workspaceDir, harness: 'openclaw' });
const segName = (hash: string) => segs.segmentFileName(sessionId, hash, stamp);
// #8080: a sub-agent session's user turns are its parent agent's brief: the speaker marker precedes its first segment.
if (isOpenClawSubagentKey(params.sessionKey) || isOpenClawSubagentKey((params.sessionTarget as { sessionKey?: unknown } | null | undefined)?.sessionKey)) {
const speaker = await import('./context/session-speaker.ts');
const marked = speaker.bankAsSpeaker(dir, sessionId, { kind: 'agent', principal: speaker.DETECTED_PRINCIPAL, source: 'detected' }, 'openclaw');
if (marked.bank !== true) return { status: 'skipped', reason: marked.reason };
}
await recordOpenclawSeat(dir, sessionId, sessionFile ?? target?.storePath ?? null);
(await import('./context/capture-consent.ts')).recordCaptureIfOff(cfg, `${dir}/${segName(segs.segmentHash(rendered.text))}`, rendered.text, source);
const w = segs.writeSegment(dir, sessionId, rendered.text, stamp);
const ordinal = segs.appendSegmentLedger(dir, sessionId, w.hash);
const memo = checkpointMemo.get(sessionId) ?? { links: [], polls: 0, expectSeg: null, settled: false };
memo.expectSeg = w.hash;
memo.polls = 0;
memo.settled = false;
memoSet(sessionId, memo);
// Memorable receipt (additive, opt-in, memorableGateAllowed-gated): the
// segment above is SPOOLED, i.e. durable, so the receipt describes real
// banked work. OpenClaw has no session end — capture is per-compaction by
// design (documented as compaction-only coverage; the post-last-compaction
// tail is never captured). One receipt per distinct window hash; a retried
// identical compaction dedups on content_hash inside the helper. The
// whole block is fail-open for the checkpoint: any refusal in here can
// never change the checkpoint's status. cfg was loaded fresh THIS call,
// so `gbrain config set …enabled false` applies on the next compaction
// without a gateway restart (GBRAIN_MEMORABLE, an env, needs one).
// This lane NEVER compacts the receipts file — the hook lane is the ONE
// compactor of session-receipts.jsonl
// (same single-rewriter rule as the relay-file trim: two processes doing
// read-filter-rename can drop each other's receipts; an append racing a
// rename loses at most its own line, the accepted class). It also skips
// the block entirely once the host's compact() deadline has fired:
// everything below (tail read, PATH walk, spawn) is work delaying the
// banked return.
try {
const hb = await import('./context/hook-heartbeat.ts');
if (!deadlineHit() && (await hb.memorableGateAllowed(cfg)).allowed) {
// Entropy parity with the hook lane [red-team]: the segment file was vendor-scanned
// only (its rendering feeds the Cathedral-5 ledger hash), but the relay child derives
// its egress task line from that text. Re-scan with highEntropy and REFUSE the relay on
// any hit, logged content-free (fail-closed; the next compaction window re-evaluates).
const scan = await import('./secret-scan.ts');
const [hit] = scan.redactFindings(rendered.text, { highEntropy: true }).redactions;
if (hit) {
await hb.writeHeartbeat(hb.relayRefusalHeartbeat(hit), { trim: false });
throw new Error('entropy_hit'); // caught below — receipt+relay skipped, checkpoint unaffected
}
// Same span rule as the hook lane: windowTurns is a suffix of
// tail.turns, so calls are filtered to the window's origin.
const startTurnIndex = tail.turns.length - windowTurns.length;
const toolCallsJson = await hb.redactedToolCallsJson(tail.toolCalls, tail.toolCallTurnIndexes, startTurnIndex);
await hb.recordAndRelayReceipt({
session_id: sessionId,
harness: 'openclaw',
corpus_path: `${dir}/${segName(w.hash)}`,
content_hash: w.hash,
turn_count: windowTurns.length,
workspace_root: workspaceDir,
// Structurally true here: renderSegmentText returned non-null above
// (scan_unavailable already skipped this whole path), and
// redactedToolCallsJson throws into this catch on scanner failure —
// an unscanned payload can never reach the receipt on this lane.
tool_calls_json: toolCallsJson,
secret_scan_ok: true,
// trimRelayFile here too: an openclaw-ONLY host has no session-end
// hook lane, and without a trimmer the child-appended relay file
// grows forever behind the bounded tail read. Concurrent trims from
// both lanes converge (newest-keeping, tmp+rename); the residual
// loss window stays the single in-flight append.
}, { skipReceiptsCompaction: true, trimRelayFile: true }); // hook lane stays the ONE receipts compactor
}
} catch { /* receipt is additive — never fails the checkpoint */ }
// Segment is spooled (durable); a deadline from here on degrades to
// 'banked' — the sweep backstop extracts it later.
if (deadlineHit()) return { status: 'banked', reason: 'deadline' };
// Rung 2 — PGLite: serve owns the lock; one bankOnly+flush round trip.
if (cfg?.engine === 'pglite' && cfg.database_path) {
const ipc = await import('./context/resolve-ipc.ts');
const secret = ipc.readIpcSecret(cfg.database_path);
if (!secret) return { status: 'banked', reason: 'no_serve' };
const res = await ipc.requestContextPack(ipc.resolveSocketPath(cfg.database_path), {
secret,
sessionId,
window: windowTurns.slice(-COMPACT_BANK_WINDOW_TURNS),
bankOnly: true,
trigger: 'compact-bank',
flushCorpusFile: segName(w.hash),
...(source ? { sourceId: source } : {}),
});
if (res === ipc.IPC_UNAVAILABLE) return { status: 'banked', reason: 'ipc_unavailable' };
return { status: 'banked' };
}
// Rung 3 — Postgres: inline harvest over the ladder's cached connection,
// under the SAME claim fencing + gates as the serve FIFO/sweep.
const { getDirectPostgresEngine } = await import('./context/reflex.ts');
const pg = await getDirectPostgresEngine(cfg);
if (!pg) return { status: 'banked', reason: 'no_engine' };
const sweep = await import('./sweep.ts');
const fullPath = `${dir}/${segName(w.hash)}`;
const claimPath = fullPath + sweep.CORPUS_CLAIM_SUFFIX;
if (!(await sweep.acquireCorpusClaim(claimPath))) return { status: 'banked', reason: 'claimed_elsewhere' };
try {
// Re-check under the claim (adversarial review): a retried compact with
// identical content maps to the same filename — if a prior run (or the
// sweep) already ingested it, re-running the pipeline is pure duplicate
// LLM spend absorbed only by fact-level dedup.
const held = await rung3SegmentHold(fullPath, segName(w.hash));
if (held) return { status: 'banked', reason: held };
const gate = await (await import('./context/capture-consent.ts')).gateCorpusFile(pg, fullPath, 'compact');
if (gate.action !== 'extract') return { status: 'banked', reason: gate.reason };
const { extractionAvailableForEngine } = await import('./facts/extraction-availability.ts');
if (!(await extractionAvailableForEngine(pg))) return { status: 'banked', reason: 'keyless' };
const { isFactsExtractionEnabled } = await import('./facts/extract.ts');
if (!(await isFactsExtractionEnabled(pg))) return { status: 'banked', reason: 'extraction_disabled' };
// #6268: the segment's stamp, or (unresolved) the brain's chain for this workspace, frozen into the session record.
const fileSource = await (await import('./context/corpus-source.ts')).resolveCorpusFileSource(pg, root, segName(w.hash), 'spool');
if (!fileSource.ok) return { status: 'banked', reason: fileSource.reason };
const sourceId = fileSource.sourceId;
if (await rung3WriterHeld(pg, sourceId)) return { status: 'banked', reason: 'writer_coordinator_required' };
if (deadlineHit()) return { status: 'banked', reason: 'deadline' };
const { runFactsPipeline } = await import('./facts/backstop.ts');
const speaker = (await import('./context/session-speaker.ts')).speakerOf(fullPath); // #8080: the session's agent speaker, as the sweep and harvest pass it
const abort = new AbortController();
// Inner backstop timer PLUS a poll of the outer compact() deadline —
// the outer budget started before this rung, so when it wins the race
// the in-flight extraction must stop too, not run on abandoned.
const timer = setTimeout(() => abort.abort(), CHECKPOINT_COMPACT_BUDGET_MS);
const deadlinePoll = setInterval(() => { if (deadlineHit()) abort.abort(); }, 250);
let r: Awaited<ReturnType<typeof runFactsPipeline>>;
try {
r = await rung3Counted(pg, fullPath, segName(w.hash), fileSource.incarnation, abort.signal, () => runFactsPipeline(rendered.text, {
engine: pg,
sourceId,
sessionId,
source: 'hook:compact',
...speaker,
mode: 'inline',
remote: false,
abortSignal: abort.signal,
}));
} finally {
clearTimeout(timer);
clearInterval(deadlinePoll);
}
// Post-check: the pipeline returns normally with PARTIALS on abort — an
// aborted run writes no sidecar and stays sweep-retryable.
if (abort.signal.aborted) return { status: 'banked', reason: 'aborted' };
// #6786: no servable model is not an outcome; the segment stays pending for the sweep.
if (r.skipped_reason === 'chat_unavailable') return { status: 'banked', reason: 'extract_skipped_chat_unavailable' };
const verified: Array<{ slug: string; title: string }> = [];
for (const slug of r.entity_slugs) {
try {
const page = await pg.getPage(slug, { sourceId });
if (page) verified.push({ slug, title: page.title || slug });
} catch { /* a non-resolvable link is never banked */ }
}
let published = true;
if (verified.length) {
const ss = await import('./context/session-state.ts');
published = await ss.appendCheckpointManifest(pg, sourceId, null, sessionId, verified, {
seg: w.hash, n: ordinal,
});
}
// `.ingested` is written even when the manifest publish failed: the
// facts ARE inserted, and leaving the segment sweep-retryable would
// re-run the whole extraction just to retry a link append. Rung-3
// links are best-effort (documented); the harvest FIFO lane is the
// one with the receipt-retry guarantee.
const { writeFileSync: wfs } = await import('node:fs');
wfs(fullPath + sweep.CORPUS_INGESTED_SUFFIX, JSON.stringify({
ingested_at: new Date().toISOString(),
facts_inserted: r.inserted,
facts_duplicate: r.duplicate,
...(r.skipped_reason ? { skipped: r.skipped_reason } : {}),
links_banked: published ? verified.length : 0,
}) + '\n');
if (!published) return { status: 'harvested', links: verified, reason: 'manifest_failed' };
return { status: 'harvested', links: verified };
} finally {
const { rmSync: rms } = await import('node:fs');
try { rms(claimPath, { force: true }); } catch { /* best effort */ }
}
}
/** Corpus dir from FILE config (hook.ts parity — no engine required). */
const engine: ContextEngine = {
info: {
id: ENGINE_ID,
name: ENGINE_NAME,
version: ENGINE_API_VERSION,
ownsCompaction: false, // delegate to legacy runtime
} satisfies ContextEngineInfo,
async ingest({ message }) {
// No-op — we don't index messages. The legacy engine handles persistence.
return { ingested: true };
},
async assemble({ sessionId, sessionKey, messages, tokenBudget, availableTools, citationsMode, prompt, runtimeContext }) {
// Lazy SDK load on first method call (was top-level await pre-L0-B).
await ensureSdkLoaded();
// #2880: fail-open on malformed host payloads. assemble() runs on EVERY
// turn; a host that sends messages:undefined (or a non-array) must not
// take down the whole context pipeline.
const msgs = Array.isArray(messages) ? messages : [];
const hasCurrentPrompt = typeof prompt === 'string' && prompt.trim().length > 0;
const lastMessage = msgs.at(-1);
const includesCurrentPrompt = runtimeContext?.transcriptStorage?.kind !== 'sqlite'
&& lastMessage?.role === 'user'
&& messageText(lastMessage.content) === prompt;
const effectiveMessages = hasCurrentPrompt && !includesCurrentPrompt
? [...msgs, { role: 'user', content: prompt }]
: msgs;
// 1. Generate deterministic context (<5ms, zero LLM calls)
const liveCtx = generateLiveContext(workspaceDir);
const contextBlock = formatContextBlock(liveCtx);
// 1b. Cathedral 5 — checkpoint block. The sessionId↔sessionKey identity
// across compact()→assemble() is an UNVERIFIABLE SDK contract (mocked
// in tests): absent id ⇒ no block, fail-open always.
// SAME normalizer as compact() (adversarial review) — the memo and the
// banked manifest live under the sanitized id.
const checkpointSid = sanitizeEngineSessionId(sessionId ?? sessionKey ?? null);
let checkpointBlock: string | null = null;
if (checkpointSid) {
try {
checkpointBlock = await getCheckpointBlock(checkpointSid);
} catch {
checkpointBlock = null;
}
}
// 2. Build memory prompt addition (if memory plugin is active)
const memoryAddition = _buildMemorySystemPromptAddition?.({
availableTools: availableTools ?? new Set(),
citationsMode,
});
// 2b. Retrieval Reflex (#1981): detect salient entities in THIS turn that
// resolve to existing brain pages and inject compact pointers. Zero-LLM,
// fail-open, time-bounded — returns null (no addition) on any error or when
// nothing salient resolves. Detect + point, never auto-dump bodies.
const reflexAddition = await buildReflexAddition({
workspaceDir,
currentUserText: getLastUserText(effectiveMessages),
priorContextText: getPriorContextText(effectiveMessages),
// v0.43 (#2095): rolling window — assistant-introduced entities and
// named-antecedent follow-ups from recent turns now resolve too.
windowTurns: getWindowTurns(effectiveMessages),
resolveEntities: ctx.resolveEntities,
});
// 3. Combine: live context + checkpoint block (parts index 1 — adjacent
// to the Live Context block it augments, position independent of
// whether memory/reflex fire) + memory prompt + reflex pointers. No
// manifest ⇒ parts untouched ⇒ byte-identical to the pre-cathedral-5
// output (pinned).
// Always-loaded core + the context-pressure notice right after the live block (context/openclaw-core.ts).
const parts = [contextBlock, ...await openClawCoreLane(workspaceDir, CHECKPOINT_POLL_TIMEOUT_MS).additions({
sessionId: sanitizeEngineSessionId(sessionId ?? sessionKey ?? null), messages: msgs, tokenBudget, availableTools })];
if (checkpointBlock) parts.push(checkpointBlock);
if (memoryAddition) parts.push(memoryAddition);
if (reflexAddition) parts.push(reflexAddition);
// Monthly backup-coverage warning (⚠ idiom, model-visible). Bounded by
// the recording channels' budget without ever spending it; fail-open.
try {
const now = Date.now();
if (now - _backupCheckedAt > 24 * 60 * 60 * 1000) {
_backupCheckedAt = now;
const backupStatus = loadBackupStatus();
if (backupStatus && backupNagReadOnlyConsult(backupStatus, now)) {
const note = backupNoticeText(backupStatus, 'human');
if (note) parts.push(`- ⚠️ ${note}`);
}
}
} catch {
/* a notice must never break context assembly */
}
// 4. Pass through messages unchanged (legacy assembly)
return {
messages: msgs,
estimatedTokens: estimateMessageTokens(msgs),
systemPromptAddition: parts.join('\n\n'),
};
},
async compact(params) {
// Lazy SDK load on first method call (was top-level await pre-L0-B).
await ensureSdkLoaded();
openClawCoreLane(workspaceDir, CHECKPOINT_POLL_TIMEOUT_MS).compacted(sanitizeEngineSessionId(params?.sessionId ?? params?.sessionKey ?? null));
// Cathedral 5 — time-bounded, FAIL-OPEN checkpoint step BEFORE the
// delegate. A checkpoint failure/timeout must never break compaction.
// The deadline CANCELS the work (adversarial review): the race alone
// would let an abandoned checkpoint keep extracting/writing behind the
// delegate; the abort closure stops it at the next step boundary, and
// the timer is cleared when the work wins.
let gbrainCheckpoint: Record<string, unknown>;
const checkpointStart = Date.now();
try {
const deadline = new AbortController();
let timer: ReturnType<typeof setTimeout> | undefined;
const budget = new Promise<Record<string, unknown>>((resolve) => {
timer = setTimeout(() => {
deadline.abort();
resolve({ status: 'skipped', reason: 'deadline' });
}, CHECKPOINT_COMPACT_BUDGET_MS);
if (typeof (timer as { unref?: () => void }).unref === 'function') {
(timer as unknown as { unref: () => void }).unref();
}
});
try {
gbrainCheckpoint = await Promise.race([
runCompactCheckpoint(params, () => deadline.signal.aborted),
budget,
]);
} finally {
if (timer) clearTimeout(timer);
}
} catch {
gbrainCheckpoint = { status: 'skipped', reason: 'error' };
}
await recordOpenclawCompact(gbrainCheckpoint, Date.now() - checkpointStart);
// Delegate to legacy runtime compaction UNCHANGED (ownsCompaction stays
// false), then ride the additive bag on the existing untyped `result`.
const delegated =
(await _delegateCompactionToRuntime?.(params)) ?? { ok: true, compacted: false, reason: 'no-runtime' };
return {
...delegated,
result: { ...(delegated.result ?? {}), gbrain_checkpoint: gbrainCheckpoint },
};
},
};
return engine;
}