mono-pilot 0.2.9 → 0.2.12

package/dist/src/cluster/services/bus.js

@@ -0,0 +1,243 @@
+/**
+ * Message bus service handler for the cluster leader.
+ * Manages agent route table, message routing, presence, and channel subscriptions.
+ *
+ * Also exports createLeaderBus() for in-process loopback (leader participates in bus
+ * without going through a socket).
+ */
+import { encodeMessage, } from "../protocol.js";
+import { clusterLog } from "../log.js";
+const agents = new Map();
+let messageSeq = 0;
+function broadcastPresence(agentId, status, exclude) {
+    const payload = { agentId, displayName: agents.get(agentId)?.displayName, status };
+    for (const [id, agent] of agents) {
+        if (id !== exclude)
+            agent.push("presence", payload);
+    }
+}
+function socketPush(socket) {
+    return (method, payload) => {
+        if (!socket.destroyed) {
+            socket.write(encodeMessage({ type: "push", method, payload }));
+        }
+    };
+}
+function registerAgent(agentId, push, role, channels, displayName) {
+    const existing = agents.get(agentId);
+    if (existing)
+        existing.push = () => { };
+    const defaultChannels = ["public", `private:${agentId}`];
+    const allChannels = [...defaultChannels, ...(channels ?? [])];
+    agents.set(agentId, { agentId, displayName, role, push, channels: new Set(allChannels) });
+    clusterLog.info("agent registered", { agentId, channels: allChannels });
+    broadcastPresence(agentId, "joined", agentId);
+    for (const [id, existing] of agents) {
+        if (id !== agentId) {
+            push("presence", { agentId: id, displayName: existing.displayName, status: "joined" });
+        }
+    }
+    return allChannels;
+}
+// --- ServiceHandler for follower RPC requests ---
+export function createBusHandler() {
+    return {
+        methods: ["register", "subscribe", "send", "broadcast", "roster"],
+        async handle(req, ctx) {
+            switch (req.method) {
+                case "register": {
+                    const { agentId, channels, displayName } = req.params;
+                    if (!agentId) {
+                        ctx.respond({ error: "register requires agentId" });
+                        return;
+                    }
+                    const allChannels = registerAgent(agentId, socketPush(ctx.socket), "follower", channels, displayName);
+                    ctx.setRegisteredId(agentId);
+                    ctx.respond({ result: { agentId, channels: allChannels } });
+                    return;
+                }
+                case "subscribe": {
+                    const registeredId = ctx.getRegisteredId();
+                    if (!registeredId) {
+                        ctx.respond({ error: "must register before subscribe" });
+                        return;
+                    }
+                    const agent = agents.get(registeredId);
+                    if (!agent) {
+                        ctx.respond({ error: "agent not found in route table" });
+                        return;
+                    }
+                    const { channels } = req.params;
+                    for (const ch of channels)
+                        agent.channels.add(ch);
+                    clusterLog.debug("subscribe", { agentId: registeredId, channels });
+                    ctx.respond({ result: { channels: [...agent.channels] } });
+                    return;
+                }
+                case "send": {
+                    const registeredId = ctx.getRegisteredId();
+                    if (!registeredId) {
+                        ctx.respond({ error: "must register before send" });
+                        return;
+                    }
+                    const { to, channel, payload } = req.params;
+                    const target = agents.get(to);
+                    if (!target) {
+                        ctx.respond({ error: `agent not found: ${to}` });
+                        return;
+                    }
+                    const seq = ++messageSeq;
+                    target.push("message", {
+                        from: registeredId,
+                        fromName: agents.get(registeredId)?.displayName,
+                        channel,
+                        payload,
+                        seq,
+                    });
+                    clusterLog.debug("send", { from: registeredId, to, seq });
+                    ctx.respond({ result: { seq } });
+                    return;
+                }
+                case "broadcast": {
+                    const registeredId = ctx.getRegisteredId();
+                    if (!registeredId) {
+                        ctx.respond({ error: "must register before broadcast" });
+                        return;
+                    }
+                    const { channel, payload } = req.params;
+                    const targetChannel = channel ?? "public";
+                    const seq = ++messageSeq;
+                    const fromName = agents.get(registeredId)?.displayName;
+                    const pushPayload = {
+                        from: registeredId,
+                        fromName,
+                        channel: targetChannel,
+                        payload,
+                        seq,
+                    };
+                    let delivered = 0;
+                    for (const [id, agent] of agents) {
+                        if (id === registeredId)
+                            continue;
+                        if (agent.channels.has(targetChannel)) {
+                            agent.push("message", pushPayload);
+                            delivered++;
+                        }
+                    }
+                    clusterLog.debug("broadcast", { from: registeredId, channel: targetChannel, seq, delivered });
+                    ctx.respond({ result: { seq, delivered } });
+                    return;
+                }
+                case "roster": {
+                    const roster = [...agents.entries()].map(([id, a]) => ({
+                        agentId: id,
+                        displayName: a.displayName,
+                        role: a.role,
+                        channels: [...a.channels],
+                    }));
+                    ctx.respond({ result: { agents: roster } });
+                    return;
+                }
+            }
+        },
+        onDisconnect(agentId) {
+            clusterLog.info("follower left", { agentId });
+            agents.delete(agentId);
+            broadcastPresence(agentId, "left");
+        },
+    };
+}
+// --- Leader loopback: in-process BusHandle without socket ---
+export function createLeaderBus(agentId, displayName) {
+    let messageHandlers = [];
+    let presenceHandlers = [];
+    let closed = false;
+    const push = (method, payload) => {
+        if (closed)
+            return;
+        if (method === "message") {
+            for (const h of messageHandlers)
+                h(payload);
+        }
+        else if (method === "presence") {
+            for (const h of presenceHandlers)
+                h(payload);
+        }
+    };
+    registerAgent(agentId, push, "leader", undefined, displayName);
+    return {
+        async send(to, payload, channel) {
+            const target = agents.get(to);
+            if (!target)
+                throw new Error(`agent not found: ${to}`);
+            const seq = ++messageSeq;
+            target.push("message", { from: agentId, fromName: agents.get(agentId)?.displayName, channel, payload, seq });
+            clusterLog.debug("send (leader)", { from: agentId, to, seq });
+            return { seq };
+        },
+        async broadcast(payload, channel) {
+            const targetChannel = channel ?? "public";
+            const seq = ++messageSeq;
+            const pushPayload = {
+                from: agentId,
+                fromName: agents.get(agentId)?.displayName,
+                channel: targetChannel,
+                payload,
+                seq,
+            };
+            let delivered = 0;
+            for (const [id, agent] of agents) {
+                if (id === agentId)
+                    continue;
+                if (agent.channels.has(targetChannel)) {
+                    agent.push("message", pushPayload);
+                    delivered++;
+                }
+            }
+            clusterLog.debug("broadcast (leader)", { from: agentId, channel: targetChannel, seq, delivered });
+            return { seq, delivered };
+        },
+        async subscribe(chs) {
+            const entry = agents.get(agentId);
+            if (entry)
+                for (const ch of chs)
+                    entry.channels.add(ch);
+            return { channels: entry ? [...entry.channels] : [] };
+        },
+        async roster() {
+            return {
+                agents: [...agents.entries()].map(([id, a]) => ({
+                    agentId: id,
+                    displayName: a.displayName,
+                    role: a.role,
+                    channels: [...a.channels],
+                })),
+            };
+        },
+        async resolveTarget(target) {
+            const { agents } = await this.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.`);
+        },
+        onMessage(handler) { messageHandlers.push(handler); },
+        onPresence(handler) { presenceHandlers.push(handler); },
+        close() {
+            closed = true;
+            messageHandlers = [];
+            presenceHandlers = [];
+            agents.delete(agentId);
+            broadcastPresence(agentId, "left");
+            clusterLog.debug("leader bus closed", { agentId });
+        },
+    };
+}

package/dist/src/cluster/services/embedding.js

@@ -0,0 +1,12 @@
+import { clusterLog } from "../log.js";
+export function createEmbeddingHandler(provider) {
+    return {
+        methods: ["embed"],
+        async handle(req, ctx) {
+            const { texts } = req.params;
+            clusterLog.debug("embed request", { count: texts.length, reqId: req.id, ...req.from });
+            const vectors = await provider.embedBatch(texts);
+            ctx.respond({ result: { vectors } });
+        },
+    };
+}

package/dist/src/cluster/socket.js

@@ -0,0 +1,86 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { unlinkSync, mkdirSync, writeFileSync } from "node:fs";
+import net from "node:net";
+import lockfile from "proper-lockfile";
+import { clusterLog } from "./log.js";
+const MONO_PILOT_DIR = join(homedir(), ".mono-pilot");
+const SOCKET_PATH = join(MONO_PILOT_DIR, "cluster.sock");
+const LOCK_FILE = join(MONO_PILOT_DIR, "cluster.leader");
+export function getSocketPath() {
+    return SOCKET_PATH;
+}
+/**
+ * Try to connect to an existing cluster leader.
+ * Returns the socket on success, or null if no leader is listening.
+ */
+export function tryConnect() {
+    return new Promise((resolve) => {
+        const socket = net.createConnection(SOCKET_PATH);
+        const timeout = setTimeout(() => {
+            socket.destroy();
+            resolve(null);
+        }, 2000);
+        socket.on("connect", () => {
+            clearTimeout(timeout);
+            resolve(socket);
+        });
+        socket.on("error", () => {
+            clearTimeout(timeout);
+            resolve(null);
+        });
+    });
+}
+/**
+ * Try to become leader: acquire file lock, clean stale socket, listen.
+ * Uses proper-lockfile (mkdir + mtime heartbeat) for atomic, crash-safe locking.
+ */
+export async function tryListen() {
+    mkdirSync(MONO_PILOT_DIR, { recursive: true });
+    writeFileSync(LOCK_FILE, "", { flag: "a" });
+    try {
+        await lockfile.lock(LOCK_FILE, {
+            stale: 10000, // lock considered stale after 10s without heartbeat
+            retries: 0,
+            onCompromised: (err) => {
+                clusterLog.warn("leader lock compromised", { error: String(err) });
+            },
+        });
+    }
+    catch {
+        clusterLog.debug("leader lock held by another process");
+        return null;
+    }
+    // We hold the lock — safe to clean stale socket file
+    try {
+        unlinkSync(SOCKET_PATH);
+    }
+    catch { }
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.on("error", (err) => {
+            clusterLog.debug("listen failed", { code: err.code });
+            try {
+                lockfile.unlockSync(LOCK_FILE);
+            }
+            catch { }
+            resolve(null);
+        });
+        server.listen(SOCKET_PATH, () => {
+            resolve(server);
+        });
+    });
+}
+/**
+ * Clean up socket and release lock on leader shutdown.
+ */
+export function cleanupSocket() {
+    try {
+        unlinkSync(SOCKET_PATH);
+    }
+    catch { }
+    try {
+        lockfile.unlockSync(LOCK_FILE);
+    }
+    catch { }
+}

package/dist/src/cluster/test-bus.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env npx tsx
+/**
+ * Smoke test for the cluster message bus.
+ *
+ * Starts a leader (with dummy embedding provider), connects two followers
+ * as "alice" and "bob", tests register/send/broadcast/presence.
+ *
+ * Run: npx tsx src/cluster/test-bus.ts
+ */
+import { tryBecomeLeader } from "./leader.js";
+import { createEmbeddingHandler } from "./services/embedding.js";
+import { createBusHandler } from "./services/bus.js";
+import { tryFollowLeader } from "./follower.js";
+import { connectBus } from "./bus.js";
+import { cleanupSocket } from "./socket.js";
+const dummyProvider = {
+    id: "local",
+    model: "test",
+    embedQuery: async () => [0],
+    embedBatch: async (texts) => texts.map(() => [0]),
+};
+let passed = 0;
+let failed = 0;
+function assert(condition, label) {
+    if (condition) {
+        console.log(`  ✅ ${label}`);
+        passed++;
+    }
+    else {
+        console.log(`  ❌ ${label}`);
+        failed++;
+    }
+}
+async function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function main() {
+    console.log("=== Cluster Message Bus Test ===\n");
+    // --- Start leader ---
+    console.log("Starting leader...");
+    const services = [createEmbeddingHandler(dummyProvider), createBusHandler()];
+    const leader = await tryBecomeLeader(services);
+    assert(leader !== null, "leader started");
+    if (!leader) {
+        process.exit(1);
+    }
+    // --- Connect Alice ---
+    console.log("\nConnecting Alice...");
+    const aliceHandle = await tryFollowLeader("test", { agentId: "alice" });
+    assert(aliceHandle !== null, "alice connected");
+    if (!aliceHandle) {
+        await leader.close();
+        process.exit(1);
+    }
+    // --- Connect Bob ---
+    console.log("\nConnecting Bob...");
+    const bobHandle = await tryFollowLeader("test", { agentId: "bob" });
+    assert(bobHandle !== null, "bob connected");
+    if (!bobHandle) {
+        aliceHandle.close();
+        await leader.close();
+        process.exit(1);
+    }
+    // --- Register on bus ---
+    console.log("\nRegistering on bus...");
+    const aliceBus = await connectBus(aliceHandle.client, "alice", undefined, ["public"]);
+    assert(true, "alice registered");
+    const presenceEvents = [];
+    // Alice registers a presence handler to capture bob's join + bob's leave later
+    aliceBus.onPresence((evt) => { presenceEvents.push(evt); });
+    const bobBus = await connectBus(bobHandle.client, "bob", undefined, ["public"]);
+    assert(true, "bob registered");
+    // Bob registers presence handler synchronously after connectBus —
+    // buffered events flush on nextTick, so this handler will catch them.
+    const bobPresenceOnJoin = [];
+    bobBus.onPresence((evt) => { bobPresenceOnJoin.push(evt); });
+    await sleep(50);
+    // --- Test: late joiner sees existing agents ---
+    console.log("\nTest: late joiner sees existing agents...");
+    // Alice should have received bob's join
+    const aliceSawBobJoin = presenceEvents.some((e) => e.agentId === "bob" && e.status === "joined");
+    assert(aliceSawBobJoin, "alice received bob's presence:joined");
+    // Bob should know alice was already there
+    const bobSawAlice = bobPresenceOnJoin.some((e) => e.agentId === "alice" && e.status === "joined");
+    assert(bobSawAlice, "bob received alice's presence:joined on connect");
+    // Wire up remaining handlers
+    const aliceMessages = [];
+    const bobMessages = [];
+    aliceBus.onMessage((msg) => { aliceMessages.push(msg); });
+    bobBus.onMessage((msg) => { bobMessages.push(msg); });
+    // --- Test: send (alice → bob) ---
+    console.log("\nTest: send (alice → bob)...");
+    const sendResult = await aliceBus.send("bob", { text: "你昨晚在哪？" });
+    assert(typeof sendResult.seq === "number", `send returned seq=${sendResult.seq}`);
+    await sleep(50); // let push arrive
+    assert(bobMessages.length === 1, `bob received 1 message (got ${bobMessages.length})`);
+    if (bobMessages[0]) {
+        assert(bobMessages[0].from === "alice", `message from alice`);
+        assert(bobMessages[0].payload?.text === "你昨晚在哪？", `message payload correct`);
+    }
+    // --- Test: send (bob → alice) ---
+    console.log("\nTest: send (bob → alice)...");
+    await bobBus.send("alice", { text: "我在图书馆" });
+    await sleep(50);
+    assert(aliceMessages.length === 1, `alice received 1 message (got ${aliceMessages.length})`);
+    if (aliceMessages[0]) {
+        assert(aliceMessages[0].from === "bob", `message from bob`);
+        assert(aliceMessages[0].payload?.text === "我在图书馆", `message payload correct`);
+    }
+    // --- Test: broadcast ---
+    console.log("\nTest: broadcast (alice → public)...");
+    const bcResult = await aliceBus.broadcast({ text: "大家注意！" });
+    assert(typeof bcResult.seq === "number", `broadcast returned seq=${bcResult.seq}`);
+    assert(bcResult.delivered === 1, `broadcast delivered to 1 (got ${bcResult.delivered})`);
+    await sleep(50);
+    assert(bobMessages.length === 2, `bob received broadcast (total ${bobMessages.length})`);
+    if (bobMessages[1]) {
+        assert(bobMessages[1].from === "alice", `broadcast from alice`);
+        assert(bobMessages[1].channel === "public", `broadcast channel is public`);
+    }
+    // Alice should NOT receive her own broadcast
+    assert(aliceMessages.length === 1, `alice did not receive own broadcast (still ${aliceMessages.length})`);
+    // --- Test: subscribe + channel routing ---
+    console.log("\nTest: subscribe + channel routing...");
+    await bobBus.subscribe(["secret"]);
+    await aliceBus.broadcast({ text: "秘密消息" }, "secret");
+    await sleep(50);
+    // Alice is not subscribed to "secret", so she won't get it either
+    // Bob IS subscribed to "secret"
+    assert(bobMessages.length === 3, `bob received secret channel message (total ${bobMessages.length})`);
+    if (bobMessages[2]) {
+        assert(bobMessages[2].channel === "secret", `message on secret channel`);
+    }
+    // --- Test: send to non-existent agent ---
+    // --- Test: private channel (auto-subscribed) ---
+    console.log("\nTest: private channel (auto-subscribed)...");
+    const bobBefore = bobMessages.length;
+    const aliceBefore = aliceMessages.length;
+    await aliceBus.broadcast({ text: "只给 bob 看" }, "private:bob");
+    await sleep(50);
+    assert(bobMessages.length === bobBefore + 1, `bob received private:bob message`);
+    if (bobMessages[bobMessages.length - 1]) {
+        assert(bobMessages[bobMessages.length - 1].channel === "private:bob", `channel is private:bob`);
+    }
+    assert(aliceMessages.length === aliceBefore, `alice did NOT receive private:bob message`);
+    // --- Test: send to non-existent agent ---
+    console.log("\nTest: send to non-existent agent...");
+    try {
+        await aliceBus.send("charlie", { text: "hello?" });
+        assert(false, "should have thrown");
+    }
+    catch (err) {
+        assert(err.message.includes("not found"), `error: ${err.message}`);
+    }
+    // --- Test: presence on disconnect ---
+    console.log("\nTest: presence on disconnect...");
+    presenceEvents.length = 0;
+    bobBus.close();
+    bobHandle.close();
+    await sleep(100);
+    const leftEvent = presenceEvents.find((e) => e.agentId === "bob" && e.status === "left");
+    assert(leftEvent !== undefined, `alice received bob's presence:left`);
+    // --- Cleanup ---
+    console.log("\nCleaning up...");
+    aliceBus.close();
+    aliceHandle.close();
+    await leader.close();
+    console.log(`\n=== Results: ${passed} passed, ${failed} failed ===`);
+    process.exit(failed > 0 ? 1 : 0);
+}
+main().catch((err) => {
+    console.error("Test crashed:", err);
+    cleanupSocket();
+    process.exit(1);
+});

package/dist/src/cluster_v2/connection-lifecycle.js

@@ -0,0 +1,31 @@
+const ALLOWED_TRANSITIONS = {
+    disconnected: new Set(["connecting", "closed"]),
+    connecting: new Set(["connected", "disconnected", "closed"]),
+    connected: new Set(["reconnecting", "disconnected", "closed"]),
+    reconnecting: new Set(["connecting", "disconnected", "closed"]),
+    closed: new Set(["connecting"]),
+};
+export class ConnectionLifecycleTracker {
+    current;
+    constructor(initialState = "disconnected") {
+        this.current = initialState;
+    }
+    state() {
+        return this.current;
+    }
+    transition(next, label) {
+        if (next === this.current) {
+            return;
+        }
+        const allowed = ALLOWED_TRANSITIONS[this.current];
+        if (!allowed.has(next)) {
+            throw new Error(`[cluster_v2/lifecycle] invalid transition ${this.current} -> ${next} at ${label}`);
+        }
+        this.current = next;
+    }
+    assertOpenImpliesConnected(socketOpen, label) {
+        if (socketOpen && this.current !== "connected") {
+            throw new Error(`[cluster_v2/lifecycle] socket invariant violated at ${label}: state=${this.current}, socketOpen=${socketOpen}`);
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "vitest";
+import { ConnectionLifecycleTracker } from "./connection-lifecycle.js";
+describe("cluster_v2 connection lifecycle tracker", () => {
+    it("accepts valid lifecycle transitions", () => {
+        const tracker = new ConnectionLifecycleTracker("disconnected");
+        tracker.transition("connecting", "start_connect");
+        tracker.transition("connected", "connect_ok");
+        tracker.transition("reconnecting", "leader_lost");
+        tracker.transition("connecting", "retry_connect");
+        tracker.transition("connected", "retry_ok");
+        tracker.transition("closed", "shutdown");
+        expect(tracker.state()).toBe("closed");
+    });
+    it("rejects invalid lifecycle transitions", () => {
+        const tracker = new ConnectionLifecycleTracker("disconnected");
+        expect(() => tracker.transition("connected", "skip_connecting")).toThrow("invalid transition");
+    });
+    it("enforces socketOpen => connected invariant", () => {
+        const tracker = new ConnectionLifecycleTracker("connecting");
+        expect(() => tracker.assertOpenImpliesConnected(true, "pre_connect_socket_open")).toThrow("socket invariant violated");
+        tracker.transition("connected", "connect_ok");
+        expect(() => tracker.assertOpenImpliesConnected(true, "connected_socket_open")).not.toThrow();
+    });
+});