pi-better-subagents 0.1.5 → 0.1.7

package/cleanup.ts

@@ -0,0 +1,403 @@
+import {
+    existsSync,
+    mkdirSync,
+    readFileSync,
+    readdirSync,
+    rmSync,
+    statSync,
+    writeFileSync,
+} from "node:fs";
+import { join, relative } from "node:path";
+import {
+    baseDir,
+    listMetas,
+    ownedByThisParent,
+    readMeta,
+    runDir,
+    sessionsDir,
+    type RunMeta,
+    type RunStatus,
+} from "./registry.ts";
+import type { SubagentConfig } from "./config.ts";
+
+export const DEFAULT_CLEANUP_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Total registry budget. Age alone cannot bound this directory: 63 GB
+ * accumulated inside five days, so a seven-day window never saw it. A
+ * `message_update` event re-serialises the whole accumulated message, so one
+ * long-running subagent can write gigabytes in an afternoon.
+ *
+ * Deliberately tight. A single run's log has been observed past 3 GB, so a
+ * budget generous enough to hold several of those defeats the purpose: what a
+ * developer wants back is the disk, and what they lose is a log nothing reads
+ * once its result has been delivered.
+ */
+export const DEFAULT_MAX_REGISTRY_BYTES = 2 * 1024 * 1024 * 1024; // 2 GiB
+
+/**
+ * How often the size bound may be enforced. Independent of the daily marker:
+ * the point of a size cap is to react inside a day, and it only stats run
+ * directories rather than walking the session tree.
+ */
+export const SIZE_SWEEP_INTERVAL_MS = 10 * 60 * 1000; // 10min
+
+interface CleanupState {
+    lastLocalDate?: string;
+    lastRunAt?: number;
+    lastSizeSweepAt?: number;
+}
+
+export interface DailyCleanupResult {
+    ran: boolean;
+    dateKey: string;
+    removedRunDirs: number;
+    removedSessionPaths: number;
+    errors: string[];
+}
+
+export interface DailyCleanupOptions {
+    now?: number;
+    config?: Pick<SubagentConfig, "cleanupTerminalRunRetentionMs" | "cleanupSessionRetentionMs">;
+    terminalRunRetentionMs?: number;
+    sessionRetentionMs?: number;
+}
+
+const TERMINAL_CLEANUP_STATUSES = new Set<RunStatus>(["completed", "failed", "killed", "lost"]);
+
+export interface SizeCapEntry {
+    id: string;
+    status?: RunStatus;
+    /** End of the run, when recorded; oldest-first ordering uses it. */
+    endedAt?: number;
+    dirMtimeMs: number;
+    bytes: number;
+}
+
+export interface SizeCapPlan {
+    remove: string[];
+    reclaimedBytes: number;
+    keptBytes: number;
+    /** The cap could not be met without deleting live or protected runs. */
+    overBudget: boolean;
+}
+
+export interface SizeCapLimits {
+    maxBytes: number;
+    /**
+     * Runs the calling pi owns. Never removed: unlike the age bound, a size
+     * sweep goes after the NEWEST large runs once a cap is exceeded, which is
+     * exactly the live session's own work — the session can still deliver their
+     * callbacks and answer `subagent_result` for them.
+     */
+    protectedIds?: ReadonlySet<string>;
+}
+
+/**
+ * Choose run directories to retire so the registry fits `maxBytes`,
+ * oldest-terminal-first. Pure; the caller supplies the entries.
+ */
+export function planRegistrySizeCap(
+    entries: readonly SizeCapEntry[],
+    limits: SizeCapLimits,
+): SizeCapPlan {
+    let kept = entries.reduce((sum, entry) => sum + entry.bytes, 0);
+    const remove: string[] = [];
+    if (kept <= limits.maxBytes) {
+        return { remove, reclaimedBytes: 0, keptBytes: kept, overBudget: false };
+    }
+
+    const candidates = entries
+        .filter((entry) => entry.status !== undefined
+            && TERMINAL_CLEANUP_STATUSES.has(entry.status)
+            && !limits.protectedIds?.has(entry.id))
+        .sort((a, b) => (a.endedAt ?? a.dirMtimeMs) - (b.endedAt ?? b.dirMtimeMs));
+
+    let reclaimed = 0;
+    for (const candidate of candidates) {
+        if (kept <= limits.maxBytes) break;
+        remove.push(candidate.id);
+        kept -= candidate.bytes;
+        reclaimed += candidate.bytes;
+    }
+    return { remove, reclaimedBytes: reclaimed, keptBytes: kept, overBudget: kept > limits.maxBytes };
+}
+
+export function cleanupStatePath(): string {
+    return join(baseDir(), "cleanup-state.json");
+}
+
+export function localDateKey(now: number = Date.now()): string {
+    const d = new Date(now);
+    const year = d.getFullYear();
+    const month = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${year}-${month}-${day}`;
+}
+
+function readCleanupState(): CleanupState {
+    try {
+        return JSON.parse(readFileSync(cleanupStatePath(), "utf8")) as CleanupState;
+    } catch {
+        return {};
+    }
+}
+
+function writeCleanupState(state: CleanupState): void {
+    mkdirSync(baseDir(), { recursive: true });
+    writeFileSync(cleanupStatePath(), JSON.stringify(state, null, 2));
+}
+
+function retentionMs(explicit: number | undefined, configured: number | null | undefined): number {
+    const raw = explicit ?? configured;
+    return Number.isFinite(raw) && raw! >= 0 ? raw! : DEFAULT_CLEANUP_RETENTION_MS;
+}
+
+function terminalTimestamp(meta: RunMeta): number {
+    return meta.endedAt ?? meta.lostAt ?? meta.startedAt;
+}
+
+function safeStatMtime(path: string): number | undefined {
+    try {
+        return statSync(path).mtimeMs;
+    } catch {
+        return undefined;
+    }
+}
+
+function removePath(path: string, errors: string[]): boolean {
+    try {
+        rmSync(path, { recursive: true, force: true });
+        return true;
+    } catch (err) {
+        errors.push(`${path}: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+
+function cleanRunDirs(cutoff: number, errors: string[]): number {
+    let removed = 0;
+    let ids: string[];
+    try {
+        ids = readdirSync(join(baseDir(), "runs"));
+    } catch {
+        return 0;
+    }
+
+    for (const id of ids) {
+        const dir = runDir(id);
+        const meta = readMeta(id);
+        if (meta) {
+            if (!TERMINAL_CLEANUP_STATUSES.has(meta.status)) continue;
+            if (terminalTimestamp(meta) >= cutoff) continue;
+            if (removePath(dir, errors)) removed += 1;
+            continue;
+        }
+
+        const mtimeMs = safeStatMtime(dir);
+        if (mtimeMs !== undefined && mtimeMs < cutoff && removePath(dir, errors)) removed += 1;
+    }
+    return removed;
+}
+
+function activeSessionIds(metas: RunMeta[]): Set<string> {
+    const active = new Set<string>();
+    for (const meta of metas) {
+        if (meta.status === "running" || meta.status === "orphaned") active.add(meta.sessionId);
+    }
+    return active;
+}
+
+function pathMentionsActiveSession(path: string, active: Set<string>): boolean {
+    if (active.size === 0) return false;
+    const rel = relative(sessionsDir(), path);
+    for (const sessionId of active) {
+        if (sessionId && rel.includes(sessionId)) return true;
+    }
+    return false;
+}
+
+function cleanSessionTree(cutoff: number, active: Set<string>, errors: string[]): number {
+    const root = sessionsDir();
+    if (!existsSync(root)) return 0;
+    let removed = 0;
+
+    const visit = (dir: string): boolean => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        } catch (err) {
+            errors.push(`${dir}: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+
+        let empty = true;
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                const childEmpty = visit(path);
+                if (childEmpty && !pathMentionsActiveSession(path, active)) {
+                    const mtimeMs = safeStatMtime(path);
+                    if (mtimeMs !== undefined && mtimeMs < cutoff && removePath(path, errors)) {
+                        removed += 1;
+                        continue;
+                    }
+                }
+                empty = false;
+                continue;
+            }
+
+            if (pathMentionsActiveSession(path, active)) {
+                empty = false;
+                continue;
+            }
+            const mtimeMs = safeStatMtime(path);
+            if (mtimeMs !== undefined && mtimeMs < cutoff && removePath(path, errors)) {
+                removed += 1;
+                continue;
+            }
+            empty = false;
+        }
+        return empty;
+    };
+
+    visit(root);
+    return removed;
+}
+
+export function runDailyCleanupOnce(options: DailyCleanupOptions = {}): DailyCleanupResult {
+    const now = options.now ?? Date.now();
+    const dateKey = localDateKey(now);
+    const state = readCleanupState();
+    if (state.lastLocalDate === dateKey) {
+        return { ran: false, dateKey, removedRunDirs: 0, removedSessionPaths: 0, errors: [] };
+    }
+
+    const errors: string[] = [];
+    const terminalRetention = retentionMs(options.terminalRunRetentionMs, options.config?.cleanupTerminalRunRetentionMs);
+    const sessionRetention = retentionMs(options.sessionRetentionMs, options.config?.cleanupSessionRetentionMs);
+    const metas = listMetas();
+    const removedRunDirs = cleanRunDirs(now - terminalRetention, errors);
+    const removedSessionPaths = cleanSessionTree(now - sessionRetention, activeSessionIds(metas), errors);
+
+    try {
+        writeCleanupState({ lastLocalDate: dateKey, lastRunAt: now });
+    } catch (err) {
+        errors.push(`${cleanupStatePath()}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    return { ran: true, dateKey, removedRunDirs, removedSessionPaths, errors };
+}
+
+/** Bytes held under one run directory. Best-effort; unreadable entries count 0. */
+function dirBytes(dir: string): number {
+    let bytes = 0;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return 0;
+    }
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        try {
+            bytes += entry.isDirectory() ? dirBytes(path) : statSync(path).size;
+        } catch { /* vanished mid-scan */ }
+    }
+    return bytes;
+}
+
+/** Read the registry into size-cap entries. */
+export function collectSizeCapEntries(): SizeCapEntry[] {
+    let ids: string[];
+    try {
+        ids = readdirSync(join(baseDir(), "runs"));
+    } catch {
+        return [];
+    }
+    const entries: SizeCapEntry[] = [];
+    for (const id of ids) {
+        const dir = runDir(id);
+        const meta = readMeta(id);
+        entries.push({
+            id,
+            status: meta?.status,
+            endedAt: meta ? terminalTimestamp(meta) : undefined,
+            dirMtimeMs: safeStatMtime(dir) ?? 0,
+            bytes: dirBytes(dir),
+        });
+    }
+    return entries;
+}
+
+export interface SizeCapResult extends SizeCapPlan {
+    ran: boolean;
+    removed: string[];
+    errors: string[];
+}
+
+export interface SizeCapOptions {
+    now?: number;
+    config?: Pick<SubagentConfig, "maxRegistryBytes">;
+    maxBytes?: number;
+    /** Bypass the interval marker (tests, explicit operator sweeps). */
+    force?: boolean;
+    protectedIds?: ReadonlySet<string>;
+}
+
+/**
+ * Enforce the registry byte budget, at most once per SIZE_SWEEP_INTERVAL_MS.
+ * Complements the daily age sweep: age retires history, this bounds the peak a
+ * single busy day can reach. Best-effort; never throws into a caller.
+ */
+export function enforceRegistrySizeCapOnce(options: SizeCapOptions = {}): SizeCapResult {
+    const now = options.now ?? Date.now();
+    const idle: SizeCapResult = {
+        ran: false,
+        remove: [],
+        removed: [],
+        reclaimedBytes: 0,
+        keptBytes: 0,
+        overBudget: false,
+        errors: [],
+    };
+
+    const state = readCleanupState();
+    if (!options.force
+        && typeof state.lastSizeSweepAt === "number"
+        && now - state.lastSizeSweepAt >= 0
+        && now - state.lastSizeSweepAt < SIZE_SWEEP_INTERVAL_MS) {
+        return idle;
+    }
+
+    const configured = options.config?.maxRegistryBytes;
+    const maxBytes = options.maxBytes
+        ?? (Number.isFinite(configured) && configured! > 0 ? configured! : DEFAULT_MAX_REGISTRY_BYTES);
+
+    const errors: string[] = [];
+    const protectedIds = options.protectedIds ?? ownRunIds();
+    const plan = planRegistrySizeCap(collectSizeCapEntries(), { maxBytes, protectedIds });
+    const removed: string[] = [];
+    for (const id of plan.remove) {
+        if (removePath(runDir(id), errors)) removed.push(id);
+    }
+
+    try {
+        writeCleanupState({ ...state, lastSizeSweepAt: now });
+    } catch (err) {
+        errors.push(`${cleanupStatePath()}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    return { ...plan, ran: true, removed, errors };
+}
+
+/** Run ids owned by this pi process, which a size sweep must never remove. */
+function ownRunIds(): Set<string> {
+    const own = new Set<string>();
+    try {
+        for (const meta of listMetas()) {
+            if (ownedByThisParent(meta)) own.add(meta.id);
+        }
+    } catch { /* registry unreadable: protect nothing, remove nothing new */ }
+    return own;
+}

package/config.ts

@@ -45,6 +45,16 @@ export interface SubagentConfig {
     healthStaleMs?: number | null;
     healthLongToolMs?: number | null;
     healthLongCompactionMs?: number | null;
+    /** Retention for terminal run directories during once-daily cleanup. Default: 7 days. */
+    cleanupTerminalRunRetentionMs?: number | null;
+    /** Retention for child pi session files during once-daily cleanup. Default: 7 days. */
+    cleanupSessionRetentionMs?: number | null;
+    /**
+     * Total registry byte budget. Enforced between daily sweeps, oldest terminal
+     * run first — age alone cannot bound a directory that can grow by gigabytes
+     * in an afternoon. Default: 2 GiB. See cleanup.ts.
+     */
+    maxRegistryBytes?: number | null;
 }
 
 /** Concurrency cap when config.json sets none. */

package/health-observation.ts

@@ -10,7 +10,8 @@
  * and must not collapse into stale. Raw log mtime/size is diagnostic only.
  */
 
-import { readFileSync, statSync } from "node:fs";
+import { statSync } from "node:fs";
+import { DEFAULT_MAX_READ_BYTES, readAppendedLines, type LogCursor } from "./log-cursor.ts";
 import { logPathFor } from "./registry.ts";
 import type { RunStatus } from "./registry.ts";
 import { loadConfig, type SubagentConfig } from "./config.ts";
@@ -119,6 +120,14 @@ export interface RawLogDiagnostic {
     mtimeMs?: number;
     sizeBytes?: number;
     error?: string;
+    /**
+     * Bytes of the log were never read: a bounded cold start on an already-huge
+     * log, or a log that outran the per-read budget. Diagnostic only — facts
+     * from a partial window are still facts, they are just not the whole run.
+     */
+    windowTruncated?: boolean;
+    /** Retained fact-relevant events were dropped to stay inside the memory budget. */
+    eventsDropped?: boolean;
 }
 
 type LooseEvent = Record<string, unknown>;
@@ -184,6 +193,43 @@ function pushError(history: ModelErrorEntry[], entry: ModelErrorEntry, max = 8):
     while (history.length > max) history.shift();
 }
 
+/**
+ * Every event type `extractChildEventFacts` below branches on. The fold has no
+ * default branch — an event of any other type (`message_update` and friends,
+ * which are 98% of a log by volume) cannot move a single fact — so incremental
+ * readers may drop unlisted types before parsing them without changing any
+ * observation. Keep in step with the fold: `health_observation.test.mjs` fails
+ * if the fold branches on a type this set does not name, or names one the fold
+ * no longer reads.
+ */
+export const CHILD_EVENT_FACT_TYPES: ReadonlySet<string> = new Set([
+    "tool_execution_start",
+    "tool_execution_update",
+    "tool_execution_end",
+    "compaction_start",
+    "compaction_end",
+    "auto_retry_start",
+    "auto_retry_end",
+    "message_end",
+    "turn_end",
+    "agent_end",
+    "agent_settled",
+]);
+
+/** Leading `{"type":"…"` of an NDJSON event line, read without parsing it. */
+const LEADING_TYPE = /^\s*\{\s*"type"\s*:\s*"([A-Za-z0-9_.-]+)"/;
+
+/**
+ * Whether a raw log line could move any fact. Lines whose type we can read
+ * cheaply and that the fold ignores are rejected without a `JSON.parse`; a line
+ * whose shape we cannot read cheaply is kept, so the fold stays authoritative.
+ */
+export function mayAffectChildEventFacts(line: string): boolean {
+    const match = LEADING_TYPE.exec(line);
+    if (!match) return true;
+    return CHILD_EVENT_FACT_TYPES.has(match[1]!);
+}
+
 /**
  * Extract health-relevant facts from an in-memory event list (tests / callers
  * that already parsed NDJSON). Skips non-objects; ignores raw non-JSON noise.
@@ -371,9 +417,99 @@ export function extractChildEventFacts(events: ReadonlyArray<unknown>): ChildEve
     };
 }
 
+/** Parse the fact-relevant events out of raw NDJSON lines. */
+function parseFactEvents(lines: Iterable<string>): { events: unknown[]; sizes: number[] } {
+    const events: unknown[] = [];
+    const sizes: number[] = [];
+    for (const line of lines) {
+        const s = line.trim();
+        if (!s || s[0] !== "{") continue;
+        if (!mayAffectChildEventFacts(s)) continue;
+        try {
+            events.push(JSON.parse(s));
+            sizes.push(s.length);
+        } catch {
+            // bad JSON — ignore (noise / partial line)
+        }
+    }
+    return { events, sizes };
+}
+
+// ---- incremental log reading ----------------------------------------------
+//
+// Logs are append-only and reach gigabytes, so facts are folded from an
+// accumulated event list that grows by the bytes appended since the last read
+// (see log-cursor.ts). Only the types the fold consumes are retained, which is
+// ~2% of a log's lines; `message_update` alone is 98% of the volume and cannot
+// move a fact. The retained list is capped, oldest-first, and a drop is
+// reported as a diagnostic rather than silently changing an observation.
+
+/** Memory budget for one run's retained fact-relevant events. */
+const MAX_RETAINED_EVENT_BYTES = 8 * 1024 * 1024; // 8 MiB
+
+function maxHealthReadBytes(): number {
+    const raw = process.env.PI_SUBAGENT_MAX_HEALTH_READ_BYTES;
+    if (!raw) return DEFAULT_MAX_READ_BYTES;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_READ_BYTES;
+}
+
+/**
+ * Runs tracked at once. A backstop, not a policy: callers are expected to reset
+ * a dismissed run, and this bounds the leak if one forgets.
+ */
+const MAX_TRACKED_RUNS = 64;
+
+interface FactLogState {
+    cursor: LogCursor;
+    events: unknown[];
+    /** Retained source bytes per event, index-aligned with `events`. */
+    sizes: number[];
+    /** Sum of `sizes`, for the drop-oldest budget. */
+    bytes: number;
+    truncated: boolean;
+    dropped: boolean;
+}
+
+const factLogStates = new Map<string, FactLogState>();
+
+/**
+ * Forget the incremental read position for a run (or all runs). Call after a run
+ * is dismissed, and in tests that rewrite a log under a reused id.
+ */
+export function resetChildEventLogCursor(id?: string): void {
+    if (id === undefined) factLogStates.clear();
+    else factLogStates.delete(id);
+}
+
+function rememberState(id: string, state: FactLogState): void {
+    // Re-insert so the map orders least-recently-read first.
+    factLogStates.delete(id);
+    factLogStates.set(id, state);
+    while (factLogStates.size > MAX_TRACKED_RUNS) {
+        const oldest = factLogStates.keys().next();
+        if (oldest.done) break;
+        factLogStates.delete(oldest.value);
+    }
+}
+
+function trimToBudget(state: FactLogState): void {
+    while (state.bytes > MAX_RETAINED_EVENT_BYTES && state.events.length > 1) {
+        state.events.shift();
+        state.bytes -= state.sizes.shift() ?? 0;
+        state.dropped = true;
+    }
+    if (state.bytes < 0) state.bytes = 0;
+}
+
 /**
  * Read a run log for event facts + raw mtime/size diagnostics.
  * Raw log write time never promotes activity health by itself.
+ *
+ * Reads incrementally: only bytes appended since the previous call for this id
+ * are parsed, so a hot-path caller never re-reads a whole multi-gigabyte log.
+ * Pass `logText` to fold a caller-supplied log instead, which bypasses the
+ * cursor entirely.
  */
 export function extractChildEventFactsFromLog(
     id: string,
@@ -389,33 +525,42 @@ export function extractChildEventFactsFromLog(
         rawLog.error = err instanceof Error ? err.message : String(err);
     }
 
-    let text = opts.logText;
-    if (text === undefined) {
-        try {
-            text = readFileSync(path, "utf-8");
-        } catch (err) {
-            rawLog.error = rawLog.error ?? (err instanceof Error ? err.message : String(err));
-            return { facts: emptyFacts(), rawLog };
-        }
-    }
-
-    const events: unknown[] = [];
-    for (const line of text.split("\n")) {
-        const s = line.trim();
-        if (!s || s[0] !== "{") continue;
-        try {
-            events.push(JSON.parse(s));
-        } catch {
-            // bad JSON — ignore (noise / partial line)
-        }
-    }
-
     // Do not synthesise wall-clock timestamps from raw mtime / now. Untimestamped
     // events still contribute structural facts (open tools, compacting, model
     // phase); activity age only moves on parsed-event write provenance.
     // `opts.now` is accepted for API symmetry with callers but must not mint times.
     void opts.now;
-    return { facts: extractChildEventFacts(events), rawLog };
+
+    if (opts.logText !== undefined) {
+        const { events } = parseFactEvents(opts.logText.split("\n"));
+        return { facts: extractChildEventFacts(events), rawLog };
+    }
+
+    const previous = factLogStates.get(id);
+    const read = readAppendedLines(path, previous?.cursor, maxHealthReadBytes());
+    if (read.error !== undefined) {
+        rawLog.error = rawLog.error ?? read.error;
+        if (!previous) return { facts: emptyFacts(), rawLog };
+    }
+
+    const state: FactLogState = read.restarted || !previous
+        ? { cursor: read.cursor, events: [], sizes: [], bytes: 0, truncated: false, dropped: false }
+        : previous;
+    state.cursor = read.cursor;
+    state.truncated = state.truncated || read.truncated;
+
+    const parsed = parseFactEvents(read.lines);
+    if (parsed.events.length > 0) {
+        state.events.push(...parsed.events);
+        state.sizes.push(...parsed.sizes);
+        for (const size of parsed.sizes) state.bytes += size;
+        trimToBudget(state);
+    }
+    rememberState(id, state);
+
+    if (state.truncated) rawLog.windowTruncated = true;
+    if (state.dropped) rawLog.eventsDropped = true;
+    return { facts: extractChildEventFacts(state.events), rawLog };
 }
 
 // ---- observation ----------------------------------------------------------