mono-pilot 0.2.9 → 0.2.12

package/dist/src/cluster_v2/connection.js

@@ -0,0 +1,159 @@
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import net from "node:net";
+import lockfile from "proper-lockfile";
+function normalizeScope(scope) {
+    const raw = scope?.trim() || "default";
+    return raw.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+const CLUSTER_ROOT = join(homedir(), ".mono-pilot");
+function socketPathFor(scope) {
+    return join(CLUSTER_ROOT, `cluster-v2.${scope}.sock`);
+}
+function lockPathFor(scope) {
+    return join(CLUSTER_ROOT, `cluster-v2.${scope}.leader`);
+}
+export function getSocketPath(scope) {
+    return socketPathFor(normalizeScope(scope));
+}
+async function isSocketAlive(socketPath) {
+    if (!existsSync(socketPath)) {
+        return false;
+    }
+    return new Promise((resolve) => {
+        const socket = net.createConnection(socketPath);
+        const timer = setTimeout(() => {
+            socket.destroy();
+            resolve(false);
+        }, 500);
+        socket.on("connect", () => {
+            clearTimeout(timer);
+            socket.end();
+            resolve(true);
+        });
+        socket.on("error", () => {
+            clearTimeout(timer);
+            resolve(false);
+        });
+    });
+}
+export function tryConnect(scope, timeoutMs = 2000) {
+    const socketPath = getSocketPath(scope);
+    return new Promise((resolve) => {
+        const socket = net.createConnection(socketPath);
+        const timeout = setTimeout(() => {
+            socket.destroy();
+            resolve(null);
+        }, timeoutMs);
+        socket.on("connect", () => {
+            clearTimeout(timeout);
+            resolve(socket);
+        });
+        socket.on("error", () => {
+            clearTimeout(timeout);
+            resolve(null);
+        });
+    });
+}
+/**
+ * Acquire leader lease and listen on scoped socket.
+ * Returns null if lease is held by another process or listening fails.
+ */
+export async function tryListen(options) {
+    const scope = normalizeScope(options?.scope);
+    const socketPath = socketPathFor(scope);
+    const lockPath = lockPathFor(scope);
+    const stale = options?.staleMs ?? 10_000;
+    const update = options?.updateMs ?? Math.max(1_000, Math.floor(stale / 2));
+    mkdirSync(CLUSTER_ROOT, { recursive: true });
+    writeFileSync(lockPath, "", { flag: "a" });
+    let releaseLock = null;
+    try {
+        releaseLock = await lockfile.lock(lockPath, {
+            stale,
+            update,
+            retries: 0,
+            onCompromised: (error) => {
+                const compromisedError = error instanceof Error ? error : new Error(String(error));
+                options?.onLeaseCompromised?.(compromisedError);
+            },
+        });
+    }
+    catch {
+        return null;
+    }
+    if (existsSync(socketPath)) {
+        const alive = await isSocketAlive(socketPath);
+        if (alive) {
+            await releaseLock();
+            return null;
+        }
+        try {
+            unlinkSync(socketPath);
+        }
+        catch {
+            await releaseLock();
+            return null;
+        }
+    }
+    const server = net.createServer();
+    const connections = new Set();
+    server.on("connection", (socket) => {
+        connections.add(socket);
+        socket.on("close", () => {
+            connections.delete(socket);
+        });
+    });
+    const listened = await new Promise((resolve) => {
+        server.once("error", () => resolve(false));
+        server.listen(socketPath, () => resolve(true));
+    });
+    if (!listened) {
+        try {
+            server.close();
+        }
+        catch {
+            // no-op
+        }
+        try {
+            await releaseLock();
+        }
+        catch {
+            // no-op
+        }
+        return null;
+    }
+    let closed = false;
+    const close = async () => {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        for (const socket of connections) {
+            socket.destroy();
+        }
+        await new Promise((resolve) => {
+            server.close(() => resolve());
+        });
+        try {
+            unlinkSync(socketPath);
+        }
+        catch {
+            // no-op
+        }
+        if (releaseLock) {
+            try {
+                await releaseLock();
+            }
+            catch {
+                // no-op
+            }
+        }
+    };
+    return {
+        socketPath,
+        server,
+        close,
+    };
+}

package/dist/src/cluster_v2/connection.test.js

@@ -0,0 +1,55 @@
+import net from "node:net";
+import { describe, expect, it } from "vitest";
+import { tryListen } from "./connection.js";
+function uniqueScope(prefix) {
+    return `${prefix}-${process.pid}-${Date.now()}-${Math.floor(Math.random() * 100000)}`;
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function connectFollower(socketPath) {
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(socketPath);
+        socket.once("connect", () => resolve(socket));
+        socket.once("error", reject);
+    });
+}
+describe("cluster_v2 connection lease", () => {
+    it("allows only one active leader per scope at a time", async () => {
+        const scope = uniqueScope("leader-scope");
+        const first = await tryListen({ scope });
+        expect(first).not.toBeNull();
+        if (!first)
+            return;
+        const second = await tryListen({ scope });
+        expect(second).toBeNull();
+        await first.close();
+        const third = await tryListen({ scope });
+        expect(third).not.toBeNull();
+        if (third) {
+            await third.close();
+        }
+    });
+    it("closes promptly even with active follower sockets", async () => {
+        const scope = uniqueScope("leader-close");
+        const leader = await tryListen({ scope });
+        expect(leader).not.toBeNull();
+        if (!leader)
+            return;
+        const follower = await connectFollower(leader.socketPath);
+        const followerClosed = new Promise((resolve) => {
+            follower.once("close", () => resolve());
+        });
+        const closeResult = await Promise.race([
+            leader.close().then(() => "closed"),
+            sleep(1000).then(() => "timeout"),
+        ]);
+        expect(closeResult).toBe("closed");
+        await Promise.race([
+            followerClosed.then(() => "closed"),
+            sleep(1000).then(() => "timeout"),
+        ]).then((result) => {
+            expect(result).toBe("closed");
+        });
+    });
+});

package/dist/src/cluster_v2/events.js

@@ -0,0 +1,102 @@
+const leaderOfflineHandlers = new Set();
+const leaderRecoveredHandlers = new Set();
+const discordChannelBatchHandlers = new Set();
+const twitterPullBatchHandlers = new Set();
+const twitterPullFailedHandlers = new Set();
+const twitterCollectorStartupFailedHandlers = new Set();
+export function onClusterV2LeaderOffline(handler) {
+    leaderOfflineHandlers.add(handler);
+    return () => {
+        leaderOfflineHandlers.delete(handler);
+    };
+}
+export function onClusterV2LeaderRecovered(handler) {
+    leaderRecoveredHandlers.add(handler);
+    return () => {
+        leaderRecoveredHandlers.delete(handler);
+    };
+}
+export function onClusterV2DiscordChannelBatch(handler) {
+    discordChannelBatchHandlers.add(handler);
+    return () => {
+        discordChannelBatchHandlers.delete(handler);
+    };
+}
+export function onClusterV2TwitterPullBatch(handler) {
+    twitterPullBatchHandlers.add(handler);
+    return () => {
+        twitterPullBatchHandlers.delete(handler);
+    };
+}
+export function onClusterV2TwitterPullFailed(handler) {
+    twitterPullFailedHandlers.add(handler);
+    return () => {
+        twitterPullFailedHandlers.delete(handler);
+    };
+}
+export function onClusterV2TwitterCollectorStartupFailed(handler) {
+    twitterCollectorStartupFailedHandlers.add(handler);
+    return () => {
+        twitterCollectorStartupFailedHandlers.delete(handler);
+    };
+}
+export function emitClusterV2LeaderOffline(event) {
+    for (const handler of leaderOfflineHandlers) {
+        try {
+            handler(event);
+        }
+        catch {
+            // Best-effort notification only.
+        }
+    }
+}
+export function emitClusterV2LeaderRecovered(event) {
+    for (const handler of leaderRecoveredHandlers) {
+        try {
+            handler(event);
+        }
+        catch {
+            // Best-effort notification only.
+        }
+    }
+}
+export function emitClusterV2DiscordChannelBatch(event) {
+    for (const handler of discordChannelBatchHandlers) {
+        try {
+            handler(event);
+        }
+        catch {
+            // Best-effort notification only.
+        }
+    }
+}
+export function emitClusterV2TwitterPullBatch(event) {
+    for (const handler of twitterPullBatchHandlers) {
+        try {
+            handler(event);
+        }
+        catch {
+            // Best-effort notification only.
+        }
+    }
+}
+export function emitClusterV2TwitterPullFailed(event) {
+    for (const handler of twitterPullFailedHandlers) {
+        try {
+            handler(event);
+        }
+        catch {
+            // Best-effort notification only.
+        }
+    }
+}
+export function emitClusterV2TwitterCollectorStartupFailed(event) {
+    for (const handler of twitterCollectorStartupFailedHandlers) {
+        try {
+            handler(event);
+        }
+        catch {
+            // Best-effort notification only.
+        }
+    }
+}

package/dist/src/cluster_v2/index.js

@@ -0,0 +1,2 @@
+export { closeClusterV2, getActiveClusterV2Service, initClusterV2, reelectClusterV2, stepdownClusterV2Leader, } from "./runtime.js";
+export { onClusterV2DiscordChannelBatch, onClusterV2LeaderOffline, onClusterV2LeaderRecovered, onClusterV2TwitterCollectorStartupFailed, onClusterV2TwitterPullBatch, onClusterV2TwitterPullFailed, } from "./events.js";

package/dist/src/cluster_v2/observability.js

@@ -0,0 +1,99 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const LOGS_DIR = join(homedir(), ".mono-pilot", "logs");
+const STDIO_ENV = "MONO_PILOT_CLUSTER_V2_LOG_STDIO";
+let writeQueue = Promise.resolve();
+function getLogPath(date = new Date()) {
+    const stamp = date.toISOString().slice(0, 10);
+    return join(LOGS_DIR, `cluster_v2.${stamp}.log`);
+}
+function shouldMirrorToStdout() {
+    if (process.env.NODE_ENV === "test") {
+        return true;
+    }
+    return process.env[STDIO_ENV] === "1";
+}
+function enqueueLogLine(line) {
+    writeQueue = writeQueue
+        .then(async () => {
+        await mkdir(LOGS_DIR, { recursive: true });
+        await appendFile(getLogPath(), `${line}\n`, { encoding: "utf-8" });
+    })
+        .catch(() => {
+        // Keep logging failures non-fatal.
+    });
+}
+function mirrorToStdio(level, line) {
+    if (!shouldMirrorToStdout()) {
+        return;
+    }
+    if (level === "error") {
+        console.error(line);
+        return;
+    }
+    if (level === "warn") {
+        console.warn(line);
+        return;
+    }
+    console.info(line);
+}
+export function createClusterLogContext(context) {
+    return {
+        pid: process.pid,
+        agentId: context?.agentId ?? null,
+        sessionId: context?.sessionId ?? null,
+        scope: context?.scope ?? null,
+        role: context?.role ?? null,
+    };
+}
+export function logClusterEvent(level, event, context, details) {
+    const record = {
+        timestamp: new Date().toISOString(),
+        event,
+        ...context,
+        ...(details ?? {}),
+    };
+    const line = `[cluster_v2] ${JSON.stringify(record)}`;
+    enqueueLogLine(line);
+    mirrorToStdio(level, line);
+}
+export class RequestCounters {
+    started = 0;
+    completed = 0;
+    byState = {
+        ok: 0,
+        timeout: 0,
+        error: 0,
+        aborted: 0,
+        closed: 0,
+    };
+    start() {
+        this.started++;
+    }
+    complete(state) {
+        this.completed++;
+        this.byState[state]++;
+    }
+    outstanding() {
+        return this.started - this.completed;
+    }
+    snapshot() {
+        return {
+            started: this.started,
+            completed: this.completed,
+            outstanding: this.outstanding(),
+            byState: { ...this.byState },
+        };
+    }
+    assertConsistency(expectedOutstanding, context, source) {
+        const outstanding = this.outstanding();
+        if (this.completed > this.started || outstanding !== expectedOutstanding) {
+            logClusterEvent("warn", "request_counter_mismatch", context, {
+                source,
+                expectedOutstanding,
+                ...this.snapshot(),
+            });
+        }
+    }
+}

package/dist/src/cluster_v2/observability.test.js

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from "vitest";
+import { createClusterLogContext, RequestCounters } from "./observability.js";
+describe("cluster_v2 observability", () => {
+    it("builds structured log context with required fields", () => {
+        const ctx = createClusterLogContext({
+            agentId: "agent-a",
+            sessionId: "session-a",
+            scope: "scope-a",
+            role: "test",
+        });
+        expect(ctx.pid).toBeGreaterThan(0);
+        expect(ctx.agentId).toBe("agent-a");
+        expect(ctx.sessionId).toBe("session-a");
+        expect(ctx.scope).toBe("scope-a");
+        expect(ctx.role).toBe("test");
+    });
+    it("warns on request counter mismatch", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {
+            // mute test logs
+        });
+        try {
+            const counters = new RequestCounters();
+            counters.start();
+            counters.assertConsistency(0, createClusterLogContext({ role: "test" }), "mismatch_case");
+            expect(warnSpy).toHaveBeenCalled();
+        }
+        finally {
+            warnSpy.mockRestore();
+        }
+    });
+    it("stays silent when request counters are consistent", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {
+            // mute test logs
+        });
+        try {
+            const counters = new RequestCounters();
+            counters.start();
+            counters.complete("ok");
+            counters.assertConsistency(0, createClusterLogContext({ role: "test" }), "consistent_case");
+            expect(warnSpy).not.toHaveBeenCalled();
+        }
+        finally {
+            warnSpy.mockRestore();
+        }
+    });
+});