Files
waggle-os/packages/hive-mind-hooks-hermes/src/compact-on-stop.ts
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
moving
2026-09-02 10:10:29 +02:00

127 lines
4.7 KiB
TypeScript

/**
* Hermes opportunistic, time-gated compact-on-Stop (OQ-4).
*
* Hermes ships no PreCompact lifecycle event, so the `cleanup_frames`
* maintenance pass every other built hook binds to PreCompact never runs.
* This module approximates "occasional before-compaction maintenance" by
* running `bridge.cleanupFrames()` opportunistically from the per-turn Stop
* hook — OPT-IN, DEFAULT OFF (`WAGGLE_HERMES_COMPACT_ON_STOP`), so OSS
* consumers see zero behavior change unless they ask for it.
*
* Statelessness bridge: Hermes' Stop is delivered to a fresh Node subprocess
* every turn, so an "every N turns" counter is impossible without persistence.
* We compact at most once per time window, tracking the last-compact instant
* in a small file under `~/.hermes/`. Turns are sequential subprocesses
* (process N exits before N+1 starts) → no read/write race.
*
* Fail-open is sacred: `maybeCompactOnStop` NEVER throws and NEVER rejects;
* every IO path is wrapped + swallowed. The timestamp is written ON SUCCESS
* ONLY — a failed compact stays eligible to retry next turn rather than being
* locked out for a whole window.
*/
import { mkdir, readFile, writeFile } from 'node:fs/promises';
import { dirname, join } from 'node:path';
import type { HookContext } from '@waggle/hive-mind-hooks-core';
import { resolvePaths } from './paths.js';
/** Default compact window: at most once per 10 minutes. */
export const DEFAULT_WINDOW_MS = 600_000;
const STATE_BASENAME = '.hive-mind-last-compact';
/**
* Absolute path to the last-compact timestamp file, under the hermes config
* root (`~/.hermes/.hive-mind-last-compact`). `home` overrides $HOME for tests.
*/
export function compactStatePath(home?: string): string {
return join(resolvePaths({ home }).hermesDir, STATE_BASENAME);
}
/**
* Whether opt-in compact-on-Stop is enabled. Parsed exactly like
* `WAGGLE_SIGNAL_EMIT` in `runStopBody`: truthy unless unset / empty / '0' /
* 'false' (case-insensitive).
*/
export function isCompactEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
const flag = env['WAGGLE_HERMES_COMPACT_ON_STOP'];
return flag != null && flag !== '' && flag !== '0' && flag.toLowerCase() !== 'false';
}
/**
* Resolve the compact window in ms. A test `overrideMs` wins; else
* `WAGGLE_HERMES_COMPACT_WINDOW_MIN` minutes when finite and > 0; else the
* 10-minute default.
*/
export function resolveWindowMs(
env: NodeJS.ProcessEnv = process.env,
overrideMs?: number,
): number {
if (overrideMs !== undefined) return overrideMs;
const raw = env['WAGGLE_HERMES_COMPACT_WINDOW_MIN'];
if (raw != null && raw !== '') {
const minutes = Number.parseFloat(raw);
if (Number.isFinite(minutes) && minutes > 0) return minutes * 60_000;
}
return DEFAULT_WINDOW_MS;
}
/**
* Read the persisted last-compact timestamp. Missing file / garbage / NaN →
* undefined ("never"). Fail-open: any error resolves to undefined.
*/
export async function readLastCompactTs(path: string): Promise<number | undefined> {
try {
const raw = await readFile(path, 'utf-8');
const ts = Number.parseInt(raw.trim(), 10);
return Number.isFinite(ts) ? ts : undefined;
} catch {
return undefined;
}
}
/**
* Persist the last-compact timestamp. mkdir-recursive the parent first (a bare
* writeFile would ENOENT every turn on a host where `~/.hermes/` doesn't exist
* yet, silently degrading the throttle to every-turn; mkdir-recursive is
* idempotent + cheap, and in a real install the dir already exists). The
* caller catches + swallows errors.
*/
export async function writeLastCompactTs(path: string, ts: number): Promise<void> {
await mkdir(dirname(path), { recursive: true });
await writeFile(path, String(ts));
}
export interface MaybeCompactOptions {
/** Injectable clock for tests; falls back to the system clock. */
now?: () => number;
/** $HOME override for the state file (tests). */
home?: string;
/** Compact window override in ms (tests); wins over the env var. */
windowMs?: number;
}
/**
* Opportunistically run the `cleanup_frames` maintenance pass, gated by the
* opt-in flag + a persisted time window. NEVER throws, NEVER rejects.
*/
export async function maybeCompactOnStop(
ctx: HookContext,
opts: MaybeCompactOptions = {},
): Promise<void> {
try {
if (!isCompactEnabled()) return;
const now = opts.now?.() ?? Date.now();
const path = compactStatePath(opts.home);
const last = await readLastCompactTs(path);
const windowMs = resolveWindowMs(process.env, opts.windowMs);
if (last !== undefined && now - last < windowMs) return;
await ctx.bridge.cleanupFrames();
await writeLastCompactTs(path, now);
} catch (err) {
ctx.logger.warn('compact-on-stop failed open', {
error: err instanceof Error ? err.message : String(err),
});
}
}