@maudecode/talaria-web 0.0.0

package/dist/sessions/gateway-watcher.js

@@ -0,0 +1,199 @@
+/**
+ * Gateway session watcher (Python `api/gateway_watcher.py`): polls one
+ * profile's `state.db` every 5 s, skips the projection while the O(1)
+ * fingerprint is unchanged (with a 300 s parity pass), and pushes
+ * `sessions_changed` snapshots to bounded subscriber queues. One watcher per
+ * profile home, started lazily by the SSE routes.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { cheapChangeFingerprint, readImportableAgentSessionRows } from './state-db.js';
+import { str } from '../util.js';
+export const GATEWAY_POLL_INTERVAL_S = 5;
+const PROJECTION_PARITY_INTERVAL_S = 300;
+const ERROR_LOG_INTERVAL_S = 60;
+const SUBSCRIBER_QUEUE_MAX = 10;
+export function snapshotHash(sessions) {
+    const key = [...sessions].sort((a, b) => str(a.session_id).localeCompare(str(b.session_id))).map((s) => `${str(s.session_id)}:${str(s.updated_at ?? 0)}:${str(s.message_count ?? 0)}`).join('|');
+    return createHash('md5').update(key).digest('hex');
+}
+/** Python `_get_agent_sessions_from_db`: the watcher's lightweight projection (null when the read failed). */
+export function agentSessionsFromDb(dbPath, onError) {
+    if (!existsSync(dbPath))
+        return [];
+    try {
+        return readImportableAgentSessionRows(dbPath, { limit: 200 }).map((row) => ({
+            session_id: row.id, title: row.title || 'Agent Session', model: row.model || null,
+            message_count: Number(row.message_count) || Number(row.actual_message_count) || 0,
+            created_at: row.started_at, updated_at: row.last_activity ?? row.started_at, source: row.source || 'cli',
+            raw_source: row.raw_source ?? null, session_source: row.session_source ?? null, source_label: row.source_label ?? null,
+        }));
+    }
+    catch (error) {
+        onError?.('session projection failed', error);
+        return null;
+    }
+}
+export class GatewayWatcher {
+    profileName;
+    hermesHome;
+    opts;
+    stateDbPath;
+    subscribers = new Set();
+    timer = null;
+    running = false;
+    stopping = false;
+    lastHash = '';
+    lastCheapFp = '';
+    lastFullProjectionAt = null;
+    lastErrorLogAt = Number.NEGATIVE_INFINITY;
+    constructor(profileName, hermesHome, opts) {
+        this.profileName = profileName;
+        this.hermesHome = hermesHome;
+        this.opts = opts;
+        this.stateDbPath = join(hermesHome, 'state.db');
+    }
+    isAlive() { return this.running; }
+    hasSubscribers() { return this.subscribers.size > 0; }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.stopping = false;
+        const tick = () => {
+            if (this.stopping)
+                return;
+            try {
+                this.pollOnce();
+            }
+            catch (error) {
+                this.warnFailure('poll loop raised', error);
+            }
+            if (this.stopping)
+                return;
+            this.timer = setTimeout(tick, this.opts.pollIntervalMs ?? GATEWAY_POLL_INTERVAL_S * 1000);
+            this.timer.unref();
+        };
+        tick();
+    }
+    stop() {
+        this.stopping = true;
+        this.running = false;
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        for (const q of this.subscribers)
+            this.push(q, null);
+    }
+    subscribe() {
+        const q = { items: [], wake: null };
+        this.subscribers.add(q);
+        // Stop-race safety: a subscriber attached after stop() still receives the sentinel so its SSE loop ends and reconnects.
+        if (this.stopping)
+            q.items.push(null);
+        return {
+            next: (signal) => new Promise((resolve) => {
+                const deliver = () => { resolve(q.items.shift() ?? null); };
+                if (q.items.length) {
+                    deliver();
+                    return;
+                }
+                if (signal?.aborted) {
+                    resolve(null);
+                    return;
+                }
+                const onAbort = () => { q.wake = null; resolve(null); };
+                signal?.addEventListener('abort', onAbort, { once: true });
+                q.wake = () => { signal?.removeEventListener('abort', onAbort); deliver(); };
+            }),
+            close: () => { this.subscribers.delete(q); },
+        };
+    }
+    push(q, event) {
+        q.items.push(event);
+        const wake = q.wake;
+        q.wake = null;
+        wake?.();
+    }
+    notify(sessions) {
+        for (const q of [...this.subscribers]) {
+            if (q.items.length >= SUBSCRIBER_QUEUE_MAX) {
+                // Slow consumer: drop it with a sentinel so the browser's EventSource reconnects.
+                this.subscribers.delete(q);
+                q.items.length = 0;
+                this.push(q, null);
+                continue;
+            }
+            this.push(q, { type: 'sessions_changed', sessions });
+        }
+    }
+    warnFailure(reason, error) {
+        const now = this.opts.now();
+        if (now - this.lastErrorLogAt >= ERROR_LOG_INTERVAL_S) {
+            this.lastErrorLogAt = now;
+            this.opts.log(`[webui] WARNING: Gateway watcher ${reason} for ${this.stateDbPath}; the session sidebar will not update until it recovers: ${error.message}`);
+        }
+    }
+    /** One change-detection pass; returns true when the projection ran. */
+    pollOnce(now = this.opts.now()) {
+        const exists = existsSync(this.stateDbPath);
+        // Never publish an empty first snapshot before the Agent has created state.db.
+        if (!exists && this.lastFullProjectionAt === null && !this.lastHash)
+            return false;
+        const cheapFp = exists ? cheapChangeFingerprint(this.stateDbPath, (reason, error) => { this.warnFailure(reason, error); }) : '';
+        const parityDue = this.lastFullProjectionAt === null || now - this.lastFullProjectionAt >= PROJECTION_PARITY_INTERVAL_S;
+        if (cheapFp !== null && cheapFp === this.lastCheapFp && !parityDue)
+            return false;
+        const sessions = agentSessionsFromDb(this.stateDbPath, (reason, error) => { this.warnFailure(reason, error); });
+        if (sessions === null)
+            return false;
+        const hash = snapshotHash(sessions);
+        if (cheapFp !== null)
+            this.lastCheapFp = cheapFp;
+        this.lastFullProjectionAt = now;
+        if (hash !== this.lastHash) {
+            this.lastHash = hash;
+            this.notify(sessions);
+        }
+        return true;
+    }
+}
+/** Python module-level watcher registry keyed by profile home. */
+export class GatewayWatcherRegistry {
+    deps;
+    watchers = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get(profile) {
+        const home = this.deps.profileHome(profile);
+        let watcher = this.watchers.get(home);
+        if (!watcher?.isAlive()) {
+            watcher?.stop();
+            watcher = new GatewayWatcher(profile, home, { now: this.deps.now, log: this.deps.log, ...(this.deps.pollIntervalMs !== undefined ? { pollIntervalMs: this.deps.pollIntervalMs } : {}) });
+            watcher.start();
+            this.watchers.set(home, watcher);
+        }
+        return watcher;
+    }
+    /** Python `restart_watcher_for_profile`: swap atomically; idle watchers for other homes are reaped. */
+    restartForProfile(profile) {
+        const home = this.deps.profileHome(profile);
+        const fresh = new GatewayWatcher(profile, home, { now: this.deps.now, log: this.deps.log, ...(this.deps.pollIntervalMs !== undefined ? { pollIntervalMs: this.deps.pollIntervalMs } : {}) });
+        fresh.start();
+        const existing = this.watchers.get(home);
+        const stale = existing ? [existing] : [...this.watchers.entries()].filter(([k, w]) => k !== home && !w.hasSubscribers()).map(([k, w]) => { this.watchers.delete(k); return w; });
+        this.watchers.set(home, fresh);
+        for (const w of stale)
+            w.stop();
+        return fresh;
+    }
+    stopAll() {
+        for (const w of this.watchers.values())
+            w.stop();
+        this.watchers.clear();
+    }
+}
+//# sourceMappingURL=gateway-watcher.js.map

package/dist/sessions/gateway-watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway-watcher.js","sourceRoot":"","sources":["../../src/sessions/gateway-watcher.ts"],"names":[],"mappings":"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"}

package/dist/sessions/journal.d.ts

@@ -0,0 +1,103 @@
+export declare const RUN_JOURNAL_DIR_NAME = "_run_journal";
+export declare const TERMINAL_SSE_EVENTS: Set<string>;
+export declare const SSE_RELAY_CLOSE_EVENTS: Set<string>;
+export interface JournalEvent {
+    version: 1;
+    event_id: string;
+    seq: number;
+    run_id: string;
+    session_id: string;
+    event: string;
+    type: string;
+    created_at: number;
+    terminal: boolean;
+    terminal_state: string | null;
+    payload: unknown;
+    synthetic?: boolean;
+}
+export interface RunSummary {
+    session_id: string;
+    run_id: string;
+    stream_id: string;
+    event_count: number;
+    last_seq: number;
+    last_event_id: string | null;
+    terminal: boolean;
+    terminal_state: string;
+    last_event: string | null;
+    journal_truncated?: boolean;
+    journal_pruned?: boolean;
+    path?: string;
+}
+export declare function validateId(value: string, field: string): string;
+export declare function parseRunJournalEventId(raw: string | null | undefined): [string | null, number | null];
+export declare function terminalStateForEvent(eventName: string, payload: unknown): string | null;
+export declare class RunJournal {
+    readonly sessionDir: string;
+    private readonly env;
+    constructor(sessionDir: string, env?: Record<string, string | undefined>);
+    root(): string;
+    pathFor(sessionId: string, runId: string): string;
+    /** Python `delete_run_journal`: remove one session's journal directory; false for a missing or unsafe id. */
+    deleteSession(sessionId: string): boolean;
+    private fsyncMode;
+    writer(sessionId: string, runId: string): RunJournalWriter;
+    private static parseLines;
+    readRunEvents(sessionId: string, runId: string, opts?: {
+        afterSeq?: number | null;
+        maxSeq?: number | null;
+    }): JournalEvent[];
+    readRunEventTail(sessionId: string, runId: string, maxBytes?: number, maxRows?: number): {
+        events: JournalEvent[];
+        truncated: boolean;
+    };
+    static selectAuthoritativeTerminalEvent(events: JournalEvent[]): JournalEvent | null;
+    static summaryFromEvents(sessionId: string, runId: string, events: JournalEvent[]): RunSummary;
+    private loadPrunedSummary;
+    latestRunSummary(sessionId: string, runId: string): RunSummary;
+    /**
+     * Python `prune_settled_run_journals`: compact terminal journals older than
+     * `HERMES_WEBUI_RUN_JOURNAL_RETENTION_DAYS` (14) into `.summary.json`, keeping
+     * the `HERMES_WEBUI_RUN_JOURNAL_KEEP_RECENT` (3) newest per session and any
+     * path with a live writer.
+     */
+    pruneSettled(opts?: {
+        now?: number;
+        retentionSeconds?: number;
+        keepRecent?: number;
+        isActive?: (path: string) => boolean;
+        dryRun?: boolean;
+    }): {
+        examined: number;
+        terminal: number;
+        pruned: number;
+        bytes_reclaimed: number;
+    };
+    /** Locate a run across sessions (Python `find_run_summary`). */
+    findRunSummary(runId: string): RunSummary | null;
+    sessionJournalFingerprint(sessionId: string): string;
+    /** Python `read_session_run_events`: replay rows after an opaque cursor across a session's runs. */
+    readSessionRunEvents(sessionId: string, afterEventId: string | null | undefined): {
+        status: string;
+        events: JournalEvent[];
+        cursor_run_id: string | null;
+        cursor_seq: number | null;
+    };
+    /** Python `stale_interrupted_event`: a synthetic terminal row for a journal whose worker died. */
+    staleInterruptedEvent(sessionId: string, runId: string, afterSeq?: number | null, now?: number): JournalEvent | null;
+}
+export declare class RunJournalWriter {
+    private readonly journal;
+    readonly sessionId: string;
+    readonly runId: string;
+    private readonly fsyncMode;
+    private readonly now;
+    private fd;
+    private seq;
+    private closed;
+    readonly path: string;
+    constructor(journal: RunJournal, sessionId: string, runId: string, fsyncMode: 'eager' | 'terminal-only', now?: () => number);
+    appendSseEvent(eventName: string, payload: unknown): JournalEvent;
+    private closeHandle;
+    close(): void;
+}