mono-pilot 0.2.10 → 0.2.13

package/dist/src/cluster/bus.js

@@ -0,0 +1,102 @@
+/**
+ * High-level message bus API over the cluster socket.
+ *
+ * Wraps ClusterClient RPC + push into a simple event-driven interface.
+ * Socket lifecycle is owned by FollowerHandle — bus only manages messaging.
+ */
+import { clusterLog } from "./log.js";
+/**
+ * Connect to the cluster message bus.
+ *
+ * Calls `register` on the leader, wires push dispatch, returns a BusHandle.
+ * The underlying socket is owned by the FollowerHandle — call bus.close()
+ * to detach messaging without killing the embedding connection.
+ */
+export async function connectBus(client, agentId, displayName, channels) {
+    let messageHandlers = [];
+    let presenceHandlers = [];
+    let closed = false;
+    const eventBuffer = [];
+    let buffering = true;
+    function dispatch(method, payload) {
+        switch (method) {
+            case "message": {
+                const msg = payload;
+                for (const h of messageHandlers)
+                    h(msg);
+                break;
+            }
+            case "presence": {
+                const evt = payload;
+                for (const h of presenceHandlers)
+                    h(evt);
+                break;
+            }
+            default:
+                clusterLog.debug("unknown push method", { method });
+        }
+    }
+    // Wire push handler BEFORE register so presence events for existing agents are captured
+    client.onPush((method, payload) => {
+        if (closed)
+            return;
+        if (buffering) {
+            eventBuffer.push({ method, payload });
+            return;
+        }
+        dispatch(method, payload);
+    });
+    const result = await client.call("register", { agentId, displayName, channels });
+    clusterLog.info("bus connected", { agentId: result.agentId, channels: result.channels });
+    // Flush buffered events on next tick — gives caller time to register handlers synchronously
+    process.nextTick(() => {
+        buffering = false;
+        for (const evt of eventBuffer)
+            dispatch(evt.method, evt.payload);
+        eventBuffer.length = 0;
+    });
+    const roster = async () => {
+        return client.call("roster", {});
+    };
+    const resolveTarget = async (target) => {
+        const { agents } = await roster();
+        const byId = agents.find((agent) => agent.agentId === target);
+        if (byId)
+            return { agentId: byId.agentId, displayName: byId.displayName };
+        const matches = agents.filter((agent) => agent.displayName?.trim() && agent.displayName.trim() === target);
+        if (matches.length === 1) {
+            return { agentId: matches[0].agentId, displayName: matches[0].displayName };
+        }
+        if (matches.length === 0) {
+            throw new Error(`No agent found for "${target}". Use /cluster who to list agents.`);
+        }
+        const ids = matches.map((agent) => agent.agentId).join(", ");
+        throw new Error(`DisplayName "${target}" is not unique. Candidates: ${ids}. Use agentId instead.`);
+    };
+    return {
+        async send(to, payload, channel) {
+            return client.call("send", { to, channel, payload });
+        },
+        async broadcast(payload, channel) {
+            return client.call("broadcast", { channel, payload });
+        },
+        async subscribe(chs) {
+            return client.call("subscribe", { channels: chs });
+        },
+        roster,
+        resolveTarget,
+        onMessage(handler) {
+            messageHandlers.push(handler);
+        },
+        onPresence(handler) {
+            presenceHandlers.push(handler);
+        },
+        close() {
+            closed = true;
+            messageHandlers = [];
+            presenceHandlers = [];
+            client.onPush(() => { });
+            clusterLog.debug("bus detached", { agentId });
+        },
+    };
+}

package/dist/src/cluster/follower.js

@@ -0,0 +1,137 @@
+import { tryConnect } from "./socket.js";
+import { CLUSTER_PROTOCOL_VERSION, encodeMessage, MessageDecoder, isPush, } from "./protocol.js";
+import { clusterLog } from "./log.js";
+/**
+ * Try to connect to an existing cluster leader.
+ * Returns a FollowerHandle on success, or null if no leader is running.
+ */
+export async function tryFollowLeader(modelId, identity) {
+    const socket = await tryConnect();
+    if (!socket) {
+        clusterLog.debug("no leader found, cannot follow");
+        return null;
+    }
+    // Verify the leader is alive with a ping
+    const client = new ClusterClient(socket, identity);
+    try {
+        const pong = await client.call("ping", null, 3000);
+        if (pong !== "pong") {
+            clusterLog.warn("leader ping returned unexpected response", { pong });
+            client.close();
+            return null;
+        }
+    }
+    catch {
+        clusterLog.warn("leader ping failed, disconnecting");
+        client.close();
+        return null;
+    }
+    clusterLog.info("connected as follower");
+    const provider = {
+        id: "local",
+        model: modelId,
+        embedQuery: async (text) => {
+            const result = await client.call("embed", { texts: [text] });
+            return result.vectors[0];
+        },
+        embedBatch: async (texts) => {
+            const result = await client.call("embed", { texts });
+            return result.vectors;
+        },
+        dispose: async () => {
+            client.close();
+        },
+    };
+    const handle = { provider, close: () => client.close(), client };
+    client.onDisconnect(() => {
+        if (handle.onDisconnect)
+            handle.onDisconnect();
+    });
+    return handle;
+}
+/**
+ * Low-level RPC client over a connected Unix socket.
+ */
+export class ClusterClient {
+    socket;
+    nextId = 1;
+    pending = new Map();
+    decoder = new MessageDecoder();
+    closed = false;
+    from;
+    pushHandler;
+    constructor(socket, identity) {
+        this.socket = socket;
+        this.from = { pid: process.pid, ...identity };
+        socket.on("data", (chunk) => {
+            const messages = this.decoder.feed(chunk);
+            for (const msg of messages) {
+                this.handleIncoming(msg);
+            }
+        });
+        socket.on("error", () => this.abortAll("socket error"));
+        socket.on("close", () => {
+            clusterLog.info("connection to leader closed", { pending: this.pending.size });
+            this.abortAll("socket closed");
+            this.disconnectCallback?.();
+        });
+    }
+    disconnectCallback;
+    onDisconnect(cb) {
+        this.disconnectCallback = cb;
+    }
+    onPush(handler) {
+        this.pushHandler = handler;
+    }
+    handleIncoming(msg) {
+        if (isPush(msg)) {
+            this.pushHandler?.(msg.method, msg.payload);
+            return;
+        }
+        const res = msg;
+        const handler = this.pending.get(res.id);
+        if (handler) {
+            this.pending.delete(res.id);
+            if (res.error) {
+                handler.reject(new Error(res.error));
+            }
+            else {
+                handler.resolve(res.result);
+            }
+        }
+    }
+    call(method, params, timeoutMs = 30_000) {
+        if (this.closed)
+            return Promise.reject(new Error("client closed"));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`cluster RPC timeout: ${method}`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (v) => {
+                    clearTimeout(timer);
+                    resolve(v);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            this.socket.write(encodeMessage({ id, version: CLUSTER_PROTOCOL_VERSION, method, params, from: this.from }));
+        });
+    }
+    close() {
+        clusterLog.debug("follower client closing");
+        this.closed = true;
+        this.socket.destroy();
+        this.abortAll("client closed");
+    }
+    abortAll(reason) {
+        for (const [, handler] of this.pending) {
+            handler.reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
+}

package/dist/src/cluster/init.js

@@ -0,0 +1,182 @@
+/**
+ * Unified cluster entry point.
+ *
+ * Initializes the cluster (leader or follower), returning a single ClusterService
+ * that provides both embedding and message bus capabilities.
+ */
+import { tryBecomeLeader } from "./leader.js";
+import { tryFollowLeader } from "./follower.js";
+import { createEmbeddingHandler } from "./services/embedding.js";
+import { createBusHandler } from "./services/bus.js";
+import { createLeaderBus } from "./services/bus.js";
+import { connectBus } from "./bus.js";
+import { clusterLog, setLogContext } from "./log.js";
+let activeService = null;
+let cachedParams = null;
+let reElecting = null;
+export function getActiveClusterService() {
+    return activeService;
+}
+/**
+ * Initialize the cluster. Tries follower first, falls back to leader.
+ * Returns a ClusterService with both embedding and bus.
+ */
+export async function initCluster(params) {
+    if (activeService)
+        return activeService;
+    cachedParams = params;
+    const { agentId, getSessionId } = params;
+    setLogContext(() => ({
+        ...(agentId ? { agentId } : {}),
+        ...(getSessionId ? { sessionId: getSessionId() } : {}),
+    }));
+    const modelId = params.modelPath ?? "local";
+    const identity = {
+        ...(agentId ? { agentId } : {}),
+        ...(getSessionId ? { sessionId: getSessionId() } : {}),
+    };
+    // Try follower first — avoids loading model if leader exists
+    clusterLog.info("resolving cluster role");
+    const follower = await tryFollowLeader(modelId, identity);
+    if (follower) {
+        clusterLog.info("resolved as follower");
+        activeService = await makeFollowerService(follower, agentId, params);
+        return activeService;
+    }
+    // No leader — become one
+    activeService = await makeLeaderService(params);
+    if (activeService)
+        return activeService;
+    // Race condition: another process just became leader between our two attempts
+    const retryFollower = await tryFollowLeader(modelId, identity);
+    if (retryFollower) {
+        clusterLog.info("resolved as follower (retry)");
+        activeService = await makeFollowerService(retryFollower, agentId, params);
+        return activeService;
+    }
+    // Fallback: standalone (no cluster)
+    clusterLog.warn("cluster unavailable, loading model directly (standalone)");
+    const { createLocalEmbeddingProvider } = await import("../memory/embeddings/local.js");
+    const provider = await createLocalEmbeddingProvider(params);
+    activeService = {
+        role: "leader",
+        embedding: provider,
+        bus: null,
+        async close() {
+            if (provider.dispose)
+                await provider.dispose();
+            activeService = null;
+        },
+    };
+    return activeService;
+}
+export async function closeCluster() {
+    if (activeService) {
+        clusterLog.info("closing cluster", { role: activeService.role });
+        await activeService.close();
+        activeService = null;
+    }
+}
+// --- Leader setup ---
+async function makeLeaderService(params) {
+    const { createLocalEmbeddingProvider } = await import("../memory/embeddings/local.js");
+    clusterLog.info("trying to become leader, loading embedding model");
+    const provider = await createLocalEmbeddingProvider(params);
+    const embeddingHandler = createEmbeddingHandler(provider);
+    const busHandler = createBusHandler();
+    const leader = await tryBecomeLeader([embeddingHandler, busHandler], async () => { if (provider.dispose)
+        await provider.dispose(); });
+    if (!leader) {
+        // Lost election — dispose the model we just loaded
+        if (provider.dispose)
+            await provider.dispose();
+        return null;
+    }
+    clusterLog.info("resolved as leader");
+    const bus = createLeaderBus(params.agentId, params.displayName);
+    return {
+        role: "leader",
+        embedding: provider,
+        bus,
+        async close() {
+            bus.close();
+            await leader.close();
+            activeService = null;
+        },
+    };
+}
+// --- Follower setup ---
+async function makeFollowerService(handle, agentId, params) {
+    const inner = handle.provider;
+    // Proactive re-election on leader disconnect
+    handle.onDisconnect = () => {
+        if (reElecting || !activeService || activeService.role !== "follower")
+            return;
+        clusterLog.info("leader disconnected, proactively re-electing");
+        activeService = null;
+        reElecting = initCluster(cachedParams)
+            .then(() => { reElecting = null; })
+            .catch((err) => {
+            reElecting = null;
+            clusterLog.error("proactive re-election failed", { error: String(err) });
+        });
+    };
+    async function withReconnect(op) {
+        try {
+            return await op(inner);
+        }
+        catch (err) {
+            if (!isConnectionError(err))
+                throw err;
+            if (reElecting) {
+                clusterLog.debug("waiting for proactive re-election");
+                await reElecting;
+            }
+            else {
+                clusterLog.warn("leader lost, re-electing on demand", { error: String(err) });
+                handle.close();
+                activeService = null;
+                await initCluster(cachedParams);
+            }
+            if (!activeService)
+                throw err;
+            return op(activeService.embedding);
+        }
+    }
+    const embedding = {
+        id: inner.id,
+        model: inner.model,
+        embedQuery: (text) => withReconnect((p) => p.embedQuery(text)),
+        embedBatch: (texts) => withReconnect((p) => p.embedBatch(texts)),
+        dispose: async () => handle.close(),
+    };
+    // Connect bus over the same socket
+    let bus = null;
+    try {
+        bus = await connectBus(handle.client, agentId, params.displayName);
+    }
+    catch (err) {
+        clusterLog.warn("bus connect failed", { error: String(err) });
+    }
+    return {
+        role: "follower",
+        embedding,
+        bus,
+        async close() {
+            if (bus)
+                bus.close();
+            handle.close();
+            activeService = null;
+        },
+    };
+}
+function isConnectionError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const msg = err.message;
+    return msg.includes("socket closed")
+        || msg.includes("socket error")
+        || msg.includes("client closed")
+        || msg.includes("EPIPE")
+        || msg.includes("ECONNRESET");
+}

package/dist/src/cluster/leader.js

@@ -0,0 +1,97 @@
+import { tryListen, cleanupSocket } from "./socket.js";
+import { CLUSTER_PROTOCOL_VERSION, encodeMessage, MessageDecoder, } from "./protocol.js";
+import { clusterLog } from "./log.js";
+/**
+ * Try to become the cluster leader.
+ *
+ * Registers the given service handlers and dispatches incoming requests.
+ * Returns a LeaderHandle on success, or null if another leader is already running.
+ */
+export async function tryBecomeLeader(services, onClose) {
+    const server = await tryListen();
+    if (!server) {
+        clusterLog.debug("leader election lost (socket in use)");
+        return null;
+    }
+    // Build method → handler dispatch table
+    const dispatch = new Map();
+    for (const svc of services) {
+        for (const m of svc.methods)
+            dispatch.set(m, svc);
+    }
+    clusterLog.info("became leader", { methods: [...dispatch.keys()] });
+    server.on("connection", (socket) => {
+        clusterLog.info("follower connected", { remote: socket.remoteAddress ?? "unknown" });
+        handleConnection(socket, dispatch, services);
+    });
+    const close = async () => {
+        clusterLog.info("leader shutting down");
+        server.close();
+        cleanupSocket();
+        if (onClose)
+            await onClose();
+    };
+    const onExit = () => { server.close(); cleanupSocket(); };
+    process.on("exit", onExit);
+    process.on("SIGINT", onExit);
+    process.on("SIGTERM", onExit);
+    return { close };
+}
+function handleConnection(socket, dispatch, services) {
+    const decoder = new MessageDecoder();
+    let registeredId;
+    const ctx = {
+        socket,
+        respond: () => { }, // overwritten per request
+        getRegisteredId: () => registeredId,
+        setRegisteredId: (id) => { registeredId = id; },
+    };
+    socket.on("data", (chunk) => {
+        for (const msg of decoder.feed(chunk)) {
+            void routeRequest(msg, ctx, dispatch);
+        }
+    });
+    const cleanup = () => {
+        if (registeredId) {
+            for (const svc of services)
+                svc.onDisconnect?.(registeredId);
+            registeredId = undefined;
+        }
+    };
+    socket.on("error", (err) => {
+        clusterLog.debug("follower socket error", { error: String(err) });
+        cleanup();
+    });
+    socket.on("close", cleanup);
+}
+async function routeRequest(req, baseCtx, dispatch) {
+    // Per-request respond bound to this req.id
+    const respond = (res) => {
+        if (!baseCtx.socket.destroyed) {
+            baseCtx.socket.write(encodeMessage({ id: req.id, ...res }));
+        }
+    };
+    const ctx = { ...baseCtx, respond };
+    if (req.version !== CLUSTER_PROTOCOL_VERSION) {
+        clusterLog.warn("protocol version mismatch", { expected: CLUSTER_PROTOCOL_VERSION, got: req.version });
+        respond({ error: `unsupported protocol version: ${req.version}` });
+        return;
+    }
+    if (req.method === "ping") {
+        respond({ result: "pong" });
+        return;
+    }
+    const handler = dispatch.get(req.method);
+    if (!handler) {
+        clusterLog.warn("unknown method", { method: req.method, reqId: req.id });
+        respond({ error: `unknown method: ${req.method}` });
+        return;
+    }
+    try {
+        await handler.handle(req, ctx);
+    }
+    catch (err) {
+        clusterLog.error("handler error", { method: req.method, reqId: req.id, error: err instanceof Error ? err.message : String(err) });
+        respond({ error: err instanceof Error ? err.message : String(err) });
+    }
+}

package/dist/src/cluster/log.js

@@ -0,0 +1,49 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+let resolveContext = () => ({});
+/** Called internally by cluster init — not exported to consumers. */
+export function setLogContext(resolve) {
+    resolveContext = resolve;
+}
+const LOGS_DIR = join(homedir(), ".mono-pilot", "logs");
+function getLogPath(date = new Date()) {
+    const stamp = date.toISOString().slice(0, 10);
+    return join(LOGS_DIR, `cluster.${stamp}.log`);
+}
+function formatLine(level, message, data) {
+    const timestamp = new Date().toISOString();
+    const merged = { pid: process.pid, ...resolveContext(), ...data };
+    const payload = Object.keys(merged).length > 0 ? ` ${safeJson(merged)}` : "";
+    return `${timestamp} [${level}] ${message}${payload}`;
+}
+function safeJson(data) {
+    try {
+        return JSON.stringify(data);
+    }
+    catch {
+        return "[unserializable]";
+    }
+}
+let writeQueue = Promise.resolve();
+function enqueue(level, message, data) {
+    const line = formatLine(level, message, data);
+    writeQueue = writeQueue.then(async () => {
+        await mkdir(LOGS_DIR, { recursive: true });
+        await appendFile(getLogPath(), `${line}\n`, { encoding: "utf-8" });
+    }).catch(() => { });
+}
+export const clusterLog = {
+    debug(message, data) {
+        enqueue("debug", message, data);
+    },
+    info(message, data) {
+        enqueue("info", message, data);
+    },
+    warn(message, data) {
+        enqueue("warn", message, data);
+    },
+    error(message, data) {
+        enqueue("error", message, data);
+    },
+};

package/dist/src/cluster/protocol.js

@@ -0,0 +1,34 @@
+/** Wire protocol for cluster IPC over Unix domain socket. */
+export const CLUSTER_PROTOCOL_VERSION = 2;
+export function isPush(msg) {
+    return "type" in msg && msg.type === "push";
+}
+// --- Serialize / Deserialize (length-prefixed JSON over stream) ---
+/**
+ * Encode a message as a length-prefixed buffer: [4-byte LE length][JSON payload].
+ */
+export function encodeMessage(msg) {
+    const json = Buffer.from(JSON.stringify(msg), "utf8");
+    const header = Buffer.alloc(4);
+    header.writeUInt32LE(json.length, 0);
+    return Buffer.concat([header, json]);
+}
+/**
+ * Streaming decoder: feed chunks, get back parsed messages.
+ */
+export class MessageDecoder {
+    buf = Buffer.alloc(0);
+    feed(chunk) {
+        this.buf = Buffer.concat([this.buf, chunk]);
+        const messages = [];
+        while (this.buf.length >= 4) {
+            const len = this.buf.readUInt32LE(0);
+            if (this.buf.length < 4 + len)
+                break;
+            const json = this.buf.subarray(4, 4 + len).toString("utf8");
+            this.buf = this.buf.subarray(4 + len);
+            messages.push(JSON.parse(json));
+        }
+        return messages;
+    }
+}