This commit is contained in:
126
packages/hive-mind-hooks-hermes/src/compact-on-stop.ts
Normal file
126
packages/hive-mind-hooks-hermes/src/compact-on-stop.ts
Normal file
@@ -0,0 +1,126 @@
|
||||
/**
|
||||
* 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),
|
||||
});
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user