feat: gbrain-context OpenClaw context engine — deterministic temporal/spatial injection

Adds a context engine plugin that runs on every assemble() call to inject
structured live context into the system prompt:

- Garry's current local time (computed from heartbeat-state.json timezone)
- Current location (city + timezone from heartbeat or flight data)
- Home time when traveling (e.g. 'Mon 7:58 AM PT')
- Active travel status
- Quiet hours detection
- Airport→timezone mapping for 30+ airports

This kills the 'time warp' bug class where compacted sessions lose track
of time/location. The engine delegates compaction to the legacy runtime
and only owns systemPromptAddition injection. Zero LLM calls, <5ms.

Files:
- src/core/context-engine.ts — engine implementation (SDK-free, testable)
- src/openclaw-context-engine.ts — plugin entry point (requires SDK)
- test/context-engine.test.ts — 9 tests, all passing

Enable: plugins.slots.contextEngine = 'gbrain-context'

openclaw.plugin.json

@@ -8,19 +8,25 @@
       "type": "string",
       "required": true,
       "description": "PostgreSQL connection URL (Supabase recommended)",
-      "uiHints": { "sensitive": true }
+      "uiHints": {
+        "sensitive": true
+      }
     },
     "openai_api_key": {
       "type": "string",
       "required": false,
       "description": "OpenAI API key for embeddings (uses OPENAI_API_KEY env var if not set)",
-      "uiHints": { "sensitive": true }
+      "uiHints": {
+        "sensitive": true
+      }
     }
   },
   "mcpServers": {
     "gbrain": {
       "command": "./bin/gbrain",
-      "args": ["serve"]
+      "args": [
+        "serve"
+      ]
     }
   },
   "skills": [
@@ -74,5 +80,10 @@
     "compat": {
       "pluginApi": ">=2026.4.0"
     }
+  },
+  "contracts": {
+    "contextEngines": [
+      "gbrain-context"
+    ]
   }
 }

package.json

@@ -63,7 +63,10 @@
   "openclaw": {
     "compat": {
       "pluginApi": ">=2026.4.0"
-    }
+    },
+    "extensions": [
+      "./src/openclaw-context-engine.ts"
+    ]
   },
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

src/core/context-engine.ts

@@ -0,0 +1,329 @@
+/**
+ * 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
+ * Garry'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 { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+// 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;
+  }): Promise<AssembleResult>;
+  compact(params: {
+    sessionId: string;
+    sessionFile: string;
+    tokenBudget?: number;
+    force?: boolean;
+    [key: string]: unknown;
+  }): Promise<CompactResult>;
+}
+
+// Runtime helpers — loaded dynamically when running inside OpenClaw.
+// When running standalone (tests, dev), we use fallbacks.
+let _delegateCompactionToRuntime: ((params: any) => Promise<CompactResult>) | undefined;
+let _buildMemorySystemPromptAddition: ((params: any) => string | undefined) | undefined;
+
+try {
+  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;
+}
+
+export const ENGINE_ID = 'gbrain-context';
+export const ENGINE_NAME = 'GBrain Context Engine';
+export const ENGINE_VERSION = '0.1.0';
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+function loadJsonFile<T = unknown>(filePath: string): T | null {
+  try {
+    if (!existsSync(filePath)) return null;
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** 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',
+};
+
+const DEFAULT_TZ = 'US/Pacific';
+const DEFAULT_HOME = 'San Francisco';
+
+// ── Types ───────────────────────────────────────────────────────────────
+
+interface HeartbeatState {
+  garryAwake?: boolean;
+  garryAwokeAt?: string | null;
+  currentLocation?: {
+    city?: string;
+    state?: string;
+    province?: string;
+    country?: string;
+    timezone?: string;
+    source?: string;
+    note?: string;
+  };
+  lastChecks?: Record<string, string>;
+  blockers?: Record<string, string>;
+}
+
+interface FlightData {
+  flights?: Array<{
+    status?: string;
+    origin?: string;
+    destination?: string;
+    flightNumber?: string;
+    note?: string;
+  }>;
+}
+
+interface LiveContext {
+  now: string;
+  timezone: string;
+  dayOfWeek: string;
+  homeTime: string | null;
+  location: {
+    city: string;
+    tz: string;
+    source: string;
+  };
+  garryAwake: boolean;
+  isQuietHours: boolean;
+  activeTravel: string | null;
+}
+
+// ── 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 resolveLocation(workspaceDir: string): { city: string; tz: string; source: string } {
+  const hb = loadJsonFile<HeartbeatState>(join(workspaceDir, 'memory', 'heartbeat-state.json'));
+  if (hb?.currentLocation?.timezone) {
+    return {
+      city: hb.currentLocation.city ?? DEFAULT_HOME,
+      tz: hb.currentLocation.timezone,
+      source: hb.currentLocation.source ?? 'heartbeat',
+    };
+  }
+
+  // Check flights
+  const flights = loadJsonFile<FlightData>(join(workspaceDir, 'memory', 'upcoming-flights.json'));
+  const active = flights?.flights?.find(f => f.status === 'active');
+  if (active?.destination) {
+    const tz = AIRPORT_TZ[active.destination.toUpperCase()] ?? DEFAULT_TZ;
+    return { city: active.destination, tz, source: `flight:${active.flightNumber}` };
+  }
+
+  return { city: DEFAULT_HOME, tz: DEFAULT_TZ, source: 'default' };
+}
+
+function generateLiveContext(workspaceDir: string): LiveContext {
+  const location = resolveLocation(workspaceDir);
+  const time = getTimeInTz(location.tz);
+  const hb = loadJsonFile<HeartbeatState>(join(workspaceDir, 'memory', 'heartbeat-state.json'));
+
+  const garryAwake = hb?.garryAwake ?? true;
+  const isQuietHours = !garryAwake && (time.hour >= 23 || time.hour < 8);
+
+  // Home time when traveling
+  let homeTime: string | null = null;
+  if (location.tz !== DEFAULT_TZ && location.tz !== 'US/Pacific' && location.tz !== 'America/Los_Angeles') {
+    const ptFmt = new Intl.DateTimeFormat('en-US', {
+      timeZone: DEFAULT_TZ,
+      hour: 'numeric', minute: '2-digit', hour12: true, weekday: 'short',
+    });
+    homeTime = ptFmt.format(new Date()) + ' PT';
+  }
+
+  // Active travel
+  const flights = loadJsonFile<FlightData>(join(workspaceDir, 'memory', 'upcoming-flights.json'));
+  const activeFlight = flights?.flights?.find(f => f.status === 'active');
+  const activeTravel = activeFlight
+    ? `${activeFlight.flightNumber}: ${activeFlight.origin}→${activeFlight.destination}`
+    : null;
+
+  return {
+    now: time.iso,
+    timezone: location.tz,
+    dayOfWeek: time.dayOfWeek,
+    homeTime,
+    location,
+    garryAwake,
+    isQuietHours,
+    activeTravel,
+  };
+}
+
+function formatContextBlock(ctx: LiveContext): string {
+  const lines: string[] = [
+    `## Live Context (deterministic, injected by gbrain-context engine)`,
+    `- **Time:** ${ctx.now} (${ctx.timezone})`,
+    `- **Day:** ${ctx.dayOfWeek}`,
+    `- **Location:** ${ctx.location.city} (source: ${ctx.location.source})`,
+  ];
+
+  if (ctx.homeTime) {
+    lines.push(`- **Home (SF):** ${ctx.homeTime}`);
+  }
+  if (ctx.activeTravel) {
+    lines.push(`- **Active travel:** ${ctx.activeTravel}`);
+  }
+  if (!ctx.garryAwake) {
+    lines.push(`- **Garry awake:** no (quiet hours ${ctx.isQuietHours ? 'active' : 'paused'})`);
+  }
+
+  lines.push('');
+  lines.push('> This block is computed on every turn. Trust it over compaction summaries for time/location.');
+
+  return lines.join('\n');
+}
+
+// ── Engine Implementation ───────────────────────────────────────────────
+
+export function createGBrainContextEngine(ctx: {
+  workspaceDir?: string;
+}): ContextEngine {
+  const workspaceDir = ctx.workspaceDir ?? process.cwd();
+
+  const engine: ContextEngine = {
+    info: {
+      id: ENGINE_ID,
+      name: ENGINE_NAME,
+      version: ENGINE_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({ messages, tokenBudget, availableTools, citationsMode }) {
+      // 1. Generate deterministic context (<5ms, zero LLM calls)
+      const liveCtx = generateLiveContext(workspaceDir);
+      const contextBlock = formatContextBlock(liveCtx);
+
+      // 2. Build memory prompt addition (if memory plugin is active)
+      const memoryAddition = _buildMemorySystemPromptAddition?.({
+        availableTools: availableTools ?? new Set(),
+        citationsMode,
+      });
+
+      // 3. Combine: live context + memory prompt
+      const parts = [contextBlock];
+      if (memoryAddition) parts.push(memoryAddition);
+
+      // 4. Pass through messages unchanged (legacy assembly)
+      return {
+        messages,
+        estimatedTokens: messages.reduce((sum, m) => {
+          const text = typeof m.content === 'string'
+            ? m.content
+            : JSON.stringify(m.content);
+          return sum + Math.ceil(text.length / 4);
+        }, 0),
+        systemPromptAddition: parts.join('\n\n'),
+      };
+    },
+
+    async compact(params) {
+      // Delegate entirely to legacy runtime compaction
+      return _delegateCompactionToRuntime?.(params) ?? { ok: true, compacted: false, reason: 'no-runtime' };
+    },
+  };
+
+  return engine;
+}

src/openclaw-context-engine.ts

@@ -0,0 +1,38 @@
+/**
+ * OpenClaw plugin entry point for gbrain-context engine.
+ *
+ * Registers a deterministic context engine that injects live temporal/spatial
+ * context on every turn. Prevents the "time warp" bug class where compacted
+ * sessions lose track of the user's current time, location, and state.
+ *
+ * Enable in openclaw.json:
+ *   plugins.slots.contextEngine: "gbrain-context"
+ *
+ * @module
+ */
+
+/**
+ * OpenClaw plugin entry — registers gbrain-context engine.
+ *
+ * This file is discovered via the `openclaw.extensions` field in package.json.
+ * It requires the OpenClaw plugin SDK at runtime (available when loaded by the
+ * gateway). The core engine logic in `./core/context-engine.ts` is SDK-free
+ * and independently testable.
+ */
+
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
+import { createGBrainContextEngine, ENGINE_ID } from './core/context-engine.ts';
+
+export default definePluginEntry({
+  id: 'gbrain-context-engine',
+  name: 'GBrain Context Engine',
+  description: 'Deterministic temporal/spatial context injection on every turn',
+
+  register(api) {
+    api.registerContextEngine(ENGINE_ID, (ctx) =>
+      createGBrainContextEngine({
+        workspaceDir: ctx.workspaceDir,
+      }),
+    );
+  },
+});

test/context-engine.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Tests for the gbrain-context OpenClaw context engine.
+ *
+ * Validates:
+ * - Engine creation with correct info
+ * - Deterministic context injection (time, location, timezone)
+ * - Compaction delegation to runtime
+ * - Quiet hours detection
+ * - Travel timezone resolution
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { createGBrainContextEngine, ENGINE_ID, ENGINE_NAME } from '../src/core/context-engine.ts';
+
+function makeWorkspace(heartbeat: Record<string, unknown> = {}, flights: Record<string, unknown> = {}) {
+  const dir = mkdtempSync(join(tmpdir(), 'gbrain-ce-test-'));
+  mkdirSync(join(dir, 'memory'), { recursive: true });
+  writeFileSync(join(dir, 'memory', 'heartbeat-state.json'), JSON.stringify(heartbeat));
+  writeFileSync(join(dir, 'memory', 'upcoming-flights.json'), JSON.stringify(flights));
+  return dir;
+}
+
+describe('gbrain-context engine', () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('has correct engine info', () => {
+    tmpDir = makeWorkspace();
+    const engine = createGBrainContextEngine({ workspaceDir: tmpDir });
+    expect(engine.info.id).toBe(ENGINE_ID);
+    expect(engine.info.name).toBe(ENGINE_NAME);
+    expect(engine.info.ownsCompaction).toBe(false);
+  });
+
+  it('injects systemPromptAddition on assemble', async () => {
+    tmpDir = makeWorkspace({
+      garryAwake: true,
+      currentLocation: {
+        city: 'Markham',
+        timezone: 'America/Toronto',
+        source: 'garry-confirmed',
+      },
+    });
+    const engine = createGBrainContextEngine({ workspaceDir: tmpDir });
+
+    const result = await engine.assemble({
+      sessionId: 'test-session',
+      messages: [],
+      tokenBudget: 100000,
+    });
+
+    expect(result.systemPromptAddition).toBeDefined();
+    expect(result.systemPromptAddition).toContain('Live Context');
+    expect(result.systemPromptAddition).toContain('America/Toronto');
+    expect(result.systemPromptAddition).toContain('Markham');
+    // Should include home time since we're traveling (not US/Pacific)
+    expect(result.systemPromptAddition).toContain('Home (SF)');
+    expect(result.systemPromptAddition).toContain('PT');
+  });
+
+  it('uses US/Pacific when no location set', async () => {
+    tmpDir = makeWorkspace({});
+    const engine = createGBrainContextEngine({ workspaceDir: tmpDir });
+
+    const result = await engine.assemble({
+      sessionId: 'test-session',
+      messages: [],
+    });
+
+    expect(result.systemPromptAddition).toContain('San Francisco');
+    // Should NOT have home time (already home)
+    expect(result.systemPromptAddition).not.toContain('Home (SF)');
+  });
+
+  it('passes messages through unchanged', async () => {
+    tmpDir = makeWorkspace({ garryAwake: true });
+    const engine = createGBrainContextEngine({ workspaceDir: tmpDir });
+
+    const messages = [
+      { role: 'user' as const, content: 'hello' },
+      { role: 'assistant' as const, content: 'hi there' },
+    ];
+
+    const result = await engine.assemble({
+      sessionId: 'test-session',
+      messages: messages as any[],
+    });
+
+    expect(result.messages).toBe(messages); // same reference, not modified
+  });
+
+  it('ingest is a no-op that returns ingested: true', async () => {
+    tmpDir = makeWorkspace();
+    const engine = createGBrainContextEngine({ workspaceDir: tmpDir });
+
+    const result = await engine.ingest({
+      sessionId: 'test-session',
+      message: { role: 'user', content: 'test' } as any,
+    });
+
+    expect(result.ingested).toBe(true);
+  });
+
+  it('detects quiet hours when garryAwake is false and hour is late', async () => {
+    tmpDir = makeWorkspace({
+      garryAwake: false,
+      currentLocation: {
+        city: 'San Francisco',
+        timezone: 'US/Pacific',
+      },
+    });
+    const engine = createGBrainContextEngine({ workspaceDir: tmpDir });
+
+    const result = await engine.assemble({
+      sessionId: 'test-session',
+      messages: [],
+    });
+
+    // We can't control the actual time, but we can verify the structure
+    expect(result.systemPromptAddition).toBeDefined();
+    expect(result.systemPromptAddition).toContain('Live Context');
+  });
+
+  it('reports day of week as a real weekday name', async () => {
+    tmpDir = makeWorkspace({
+      garryAwake: true,
+      currentLocation: { city: 'Tokyo', timezone: 'Asia/Tokyo' },
+    });
+    const engine = createGBrainContextEngine({ workspaceDir: tmpDir });
+
+    const result = await engine.assemble({
+      sessionId: 'test-session',
+      messages: [],
+    });
+
+    const validDays = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];
+    const hasDay = validDays.some(d => result.systemPromptAddition?.includes(d));
+    expect(hasDay).toBe(true);
+  });
+
+  it('handles missing workspace files gracefully', async () => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'gbrain-ce-test-'));
+    // No memory directory at all
+    const engine = createGBrainContextEngine({ workspaceDir: tmpDir });
+
+    const result = await engine.assemble({
+      sessionId: 'test-session',
+      messages: [],
+    });
+
+    // Should still work with defaults
+    expect(result.systemPromptAddition).toContain('San Francisco');
+    expect(result.systemPromptAddition).toContain('Live Context');
+  });
+
+  it('estimates tokens from message content', async () => {
+    tmpDir = makeWorkspace({ garryAwake: true });
+    const engine = createGBrainContextEngine({ workspaceDir: tmpDir });
+
+    const messages = [
+      { role: 'user' as const, content: 'a'.repeat(400) },
+    ];
+
+    const result = await engine.assemble({
+      sessionId: 'test-session',
+      messages: messages as any[],
+    });
+
+    // 400 chars / 4 = ~100 tokens
+    expect(result.estimatedTokens).toBeGreaterThanOrEqual(90);
+    expect(result.estimatedTokens).toBeLessThanOrEqual(110);
+  });
+});