Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
11.8 KB
Raw Blame
/**
 * Per-session dedupe and budget state: `skill-index/sessions/<key>.json`,
 * keyed by sha256(scope, harness, session id) and never by catalog, so a
 * session merging a user and a project catalog has one no-repeat set and
 * one budget. The file holds canonical skill ids and turn counters only:
 * no turn text, no clock.
 *
 * Preparing a turn reads the state; committing it is separate and happens
 * only after the caller confirms delivery (the CLI after stdout is written,
 * the library through commit()). Shadow mode uses its own scope, so its
 * recorded blocks follow the same rules without touching real state.
 * Commits are serialized per file under a short lease with a bounded wait;
 * a lost commit only means a skill may be suggested again.
 *
 * Every commit (either kind) then starts a session GC pass, at most once per
 * GC_INTERVAL_MS per home (the mtime of logs/session-gc.stamp, touched when a
 * pass finishes its slice), after the commit has settled and with async I/O
 * only, so it never costs a turn's deadline; without it, past
 * MAX_SESSION_FILES new sessions would never dedupe. A short-lived process
 * (the hook lane) passes a GcBound and awaits sessionGcSettled() before it
 * exits: at most LANE_GC_FILES files, stopping at its deadline, and a pass the
 * deadline cut leaves no stamp, so the next turn tries again.
 */
import { createHash } from 'node:crypto';
import { promises, readdirSync, readFileSync, statSync, unlinkSync } from 'node:fs';
const { mkdir, open, readdir, readFile, rename, stat, unlink, writeFile } = promises;
import { randomBytes } from 'node:crypto';
import { join } from 'node:path';
import { ensureDir, writeFileDurable } from './fsutil.ts';
import { acquireLease, type Lease, releaseLease, releaseLeaseAsync, tryAcquireLeaseAsync } from './lock.ts';
import { logsDir, sessionsDir } from './paths.ts';

export const MAX_SESSION_FILES = 10_000;
export const MAX_SESSION_IDS = 10_000;
export const SESSION_TTL_MS = 7 * 24 * 3600 * 1000;
export const GC_WORK_BOUND = 1000;
export const GC_INTERVAL_MS = 10 * 60 * 1000;
export const LANE_GC_FILES = 64;

/** A GC pass for a short-lived process: at most `files` files, none started after `until` (performance.now()). */
export interface GcBound { files: number; until: number }
const gcStamp = (home: string) => join(logsDir(home), 'session-gc.stamp');
const STATE_CAP_BYTES = 2 * 1024 * 1024;

export interface SessionState {
  v: 1;
  /** Turns committed so far. */
  turn: number;
  /** Block tokens delivered so far. */
  spent: number;
  /** Skill id -> the turn it was last suggested. */
  last: Record<string, number>;
  /** Skill ids already re-suggested once. */
  again: Record<string, 1>;
  /** Hermes: the conversation history length the last committed turn saw (a shorter one means Hermes compacted in place). */
  history?: number;
}

export const freshState = (): SessionState => ({ v: 1, turn: 0, spent: 0, last: {}, again: {} });

export function sessionKey(scope: 'on' | 'shadow', harness: string | undefined, sessionId: string): string {
  return createHash('sha256').update(JSON.stringify(['gbrain-skill-resolver-session', 1, scope, harness ?? '', sessionId])).digest('hex');
}

const statePath = (home: string, key: string) => join(sessionsDir(home), `${key}.json`);

export function loadSession(home: string, key: string): SessionState {
  try {
    const p = statePath(home, key);
    if (statSync(p).size > STATE_CAP_BYTES) return freshState();
    const s = JSON.parse(readFileSync(p, 'utf8')) as SessionState;
    if (s?.v !== 1 || typeof s.turn !== 'number' || typeof s.spent !== 'number' || !s.last || typeof s.last !== 'object') return freshState();
    return { v: 1, turn: s.turn, spent: s.spent, last: s.last, again: s.again && typeof s.again === 'object' ? s.again : {}, ...historyOf(s) };
  } catch {
    return freshState();
  }
}

export interface TurnDelta { tokens: number; suggested: string[]; resuggested: string[]; reset: boolean; history?: number }

const historyOf = (s: { history?: unknown }) => (Number.isSafeInteger(s.history) && (s.history as number) >= 0 ? { history: s.history as number } : {});

/**
 * Whether a Hermes turn must start the session fresh: Hermes compacts in
 * place (same session id) and sends hooks no compaction event, so a history
 * shorter than the one the last committed turn saw is the compaction. A
 * session with no stored length (a new one, or state from before this field)
 * or a turn whose length is unknown never resets.
 */
export async function historyShrank(home: string, key: string, length: number | undefined): Promise<boolean> {
  if (length === undefined) return false;
  try {
    const p = statePath(home, key);
    if ((await stat(p)).size > STATE_CAP_BYTES) return false;
    const stored = historyOf(JSON.parse(await readFile(p, 'utf8')) as { history?: unknown }).history;
    return stored !== undefined && length < stored;
  } catch {
    return false;
  }
}

/** Apply one delivered turn. False when the commit was skipped (busy lock, file cap). */
export async function commitSession(home: string, key: string, delta: TurnDelta): Promise<boolean> {
  try { return await commitSync(home, key, delta); } finally { scheduleSessionGc(home); }
}

async function commitSync(home: string, key: string, delta: TurnDelta): Promise<boolean> {
  const dir = sessionsDir(home);
  ensureDir(dir);
  const p = statePath(home, key);
  let exists = true;
  try { statSync(p); } catch { exists = false; }
  if (!exists) { try { if (readdirSync(dir).length >= MAX_SESSION_FILES) return false; } catch { return false; } }
  let lease;
  try { lease = await acquireLease(`${p}.lock`, { purpose: 'session-commit', leaseMs: 2000, retries: 3, waitMs: 5 }); } catch { return false; }
  try {
    writeFileDurable(p, JSON.stringify(applyDelta(delta.reset ? freshState() : loadSession(home, key), delta)));
    return true;
  } finally {
    releaseLease(lease);
  }
}

function applyDelta(s: SessionState, delta: TurnDelta): SessionState {
  s.turn += 1;
  s.spent += delta.tokens;
  for (const id of delta.resuggested) s.again[id] = 1;
  for (const id of delta.suggested) if (id in s.last || Object.keys(s.last).length < MAX_SESSION_IDS) s.last[id] = s.turn;
  if (delta.history !== undefined) s.history = delta.history;
  return s;
}

/**
 * commitSession with async I/O only (no sync file call), for the hook lane,
 * whose event loop owns its deadline. Same file, lease and rules; a busy
 * lease is retried a few times over at most ~15 ms, then the commit is
 * skipped (a skipped commit only means a repeat).
 */
export interface CommitHold { lease?: Lease | null; tmp?: string | null; at?: (stage: 'held' | 'written') => Promise<void> }

export async function commitSessionAsync(home: string, key: string, delta: TurnDelta, hold: CommitHold = {}, gc?: GcBound): Promise<boolean> {
  try { return await commitAsync(home, key, delta, hold); } finally { scheduleSessionGc(home, gc); }
}

async function commitAsync(home: string, key: string, delta: TurnDelta, hold: CommitHold): Promise<boolean> {
  const dir = sessionsDir(home);
  const p = statePath(home, key);
  try {
    await mkdir(dir, { recursive: true, mode: 0o700 });
    let exists = true;
    try { await stat(p); } catch { exists = false; }
    if (!exists && (await readdir(dir)).length >= MAX_SESSION_FILES) return false;
    let lease = null;
    for (let attempt = 0; attempt < 4 && !lease; attempt++) {
      lease = await tryAcquireLeaseAsync(`${p}.lock`, { purpose: 'session-commit', leaseMs: 2000 });
      if (!lease && attempt < 3) await new Promise(r => setTimeout(r, 2 ** attempt * 2));
    }
    if (!lease) return false;
    hold.lease = lease;
    try {
      await hold.at?.('held');
      let s = freshState();
      if (!delta.reset) {
        try {
          if ((await stat(p)).size <= STATE_CAP_BYTES) {
            const raw = JSON.parse(await readFile(p, 'utf8')) as SessionState;
            if (raw?.v === 1 && typeof raw.turn === 'number' && typeof raw.spent === 'number' && raw.last && typeof raw.last === 'object') s = { v: 1, turn: raw.turn, spent: raw.spent, last: raw.last, again: raw.again && typeof raw.again === 'object' ? raw.again : {}, ...historyOf(raw) };
          }
        } catch { /* none or unreadable: fresh */ }
      }
      const tmp = join(dir, `.${key}.json.tmp-${randomBytes(6).toString('hex')}`);
      hold.tmp = tmp;
      const fh = await open(tmp, 'wx', 0o600);
      try { await fh.writeFile(JSON.stringify(applyDelta(s, delta))); await fh.sync(); } finally { await fh.close(); }
      await hold.at?.('written');
      try { await rename(tmp, p); } catch (e) { await unlink(tmp).catch(() => {}); throw e; } finally { hold.tmp = null; }
      return true;
    } finally {
      await releaseLeaseAsync(lease);
      hold.lease = null;
    }
  } catch {
    return false;
  }
}

export async function resetSession(home: string, key: string): Promise<void> {
  try { await unlink(statePath(home, key)); } catch { /* none */ }
}

/** At most `bound` of a directory's names, from a random start once there are more. */
function gcSlice(names: string[], bound = GC_WORK_BOUND): string[] {
  const start = names.length > bound ? Math.floor(Math.random() * names.length) : 0;
  return Array.from({ length: Math.min(names.length, bound) }, (_, i) => names[(start + i) % names.length]!);
}

/** Delete session files idle for 7 days, examining at most GC_WORK_BOUND files per run. */
export function gcSessions(home: string, now: number = Date.now()): number {
  let removed = 0;
  let names: string[];
  try { names = readdirSync(sessionsDir(home)); } catch { return 0; }
  for (const name of gcSlice(names)) {
    const p = join(sessionsDir(home), name);
    try { if (now - statSync(p).mtimeMs > SESSION_TTL_MS) { unlinkSync(p); removed++; } } catch { /* raced */ }
  }
  return removed;
}

/**
 * gcSessions with async I/O only. An idle session file is deleted only under
 * its commit lease and after a second stat, so a commit landing between the
 * first stat and the unlink keeps its file; a held lease skips it. A pass
 * that finishes its slice touches the GC stamp, so the commit-path pass skips
 * the next interval; a bounded pass its deadline cut does not.
 */
export async function gcSessionsAsync(home: string, now: number = Date.now(), bound?: GcBound): Promise<number> {
  const dir = sessionsDir(home);
  let names: string[];
  try { names = await readdir(dir); } catch { return 0; }
  let removed = 0;
  const idle = async (p: string) => now - (await stat(p)).mtimeMs > SESSION_TTL_MS;
  for (const name of gcSlice(names, bound?.files)) {
    if (bound && performance.now() > bound.until) return removed;
    const p = join(dir, name);
    try {
      if (!(await idle(p))) continue;
      if (!name.endsWith('.json')) { await unlink(p); removed++; continue; }
      const lease = await tryAcquireLeaseAsync(`${p}.lock`, { purpose: 'session-gc', leaseMs: 2000 });
      if (!lease) continue;
      try { if (await idle(p)) { await unlink(p); removed++; } } finally { await releaseLeaseAsync(lease); }
    } catch { /* raced */ }
  }
  try {
    await mkdir(logsDir(home), { recursive: true, mode: 0o700 });
    await writeFile(gcStamp(home), '', { mode: 0o600 });
  } catch { /* unwritable: the next commit tries again */ }
  return removed;
}

let gcPass: Promise<number> | null = null;

/** Start a GC pass once the current task ends, unless one finished in this home within GC_INTERVAL_MS. Never throws; a long-lived host never waits on it. */
export function scheduleSessionGc(home: string, bound?: GcBound): void {
  const prev = gcPass;
  gcPass = new Promise<void>(r => setImmediate(r)).then(async () => {
    await prev;
    try { if (Date.now() - (await stat(gcStamp(home))).mtimeMs < GC_INTERVAL_MS) return 0; } catch { /* none yet */ }
    return gcSessionsAsync(home, Date.now(), bound);
  }).catch(() => 0);
}

/** Resolves once the GC passes started so far have finished (tests, and the hook lane before it exits). */
export const sessionGcSettled = async (): Promise<void> => { await gcPass; };