mono-pilot 0.2.9 → 0.2.12

package/dist/src/cluster_v2/services/discord/rpc-client.js

@@ -0,0 +1,325 @@
+import { randomUUID } from "node:crypto";
+import net from "node:net";
+import { EventEmitter } from "node:events";
+const OPCODE_HANDSHAKE = 0;
+const OPCODE_FRAME = 1;
+const OPCODE_CLOSE = 2;
+const OPCODE_PING = 3;
+const OPCODE_PONG = 4;
+const DEFAULT_MAX_IPC_ID = 10;
+const DEFAULT_CONNECT_TIMEOUT_MS = 3_000;
+const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+const AUTHORIZE_TIMEOUT_MS = 120_000;
+const READY_TIMEOUT_MS = 10_000;
+function getIpcPath(id) {
+    if (process.platform === "win32") {
+        return `\\\\?\\pipe\\discord-ipc-${id}`;
+    }
+    const { XDG_RUNTIME_DIR, TMPDIR, TMP, TEMP } = process.env;
+    const prefix = XDG_RUNTIME_DIR || TMPDIR || TMP || TEMP || "/tmp";
+    return `${prefix.replace(/\/$/, "")}/discord-ipc-${id}`;
+}
+function encodeFrame(op, payload) {
+    const json = Buffer.from(JSON.stringify(payload), "utf8");
+    const packet = Buffer.alloc(8 + json.length);
+    packet.writeInt32LE(op, 0);
+    packet.writeInt32LE(json.length, 4);
+    json.copy(packet, 8);
+    return packet;
+}
+class FrameDecoder {
+    buffer = Buffer.alloc(0);
+    feed(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        const frames = [];
+        while (this.buffer.length >= 8) {
+            const op = this.buffer.readInt32LE(0);
+            const len = this.buffer.readInt32LE(4);
+            if (len < 0 || len > MAX_FRAME_BYTES) {
+                throw new Error(`invalid discord ipc frame length: ${len}`);
+            }
+            if (this.buffer.length < 8 + len) {
+                break;
+            }
+            const json = this.buffer.subarray(8, 8 + len).toString("utf8");
+            this.buffer = this.buffer.subarray(8 + len);
+            frames.push({ op, data: JSON.parse(json) });
+        }
+        return frames;
+    }
+}
+async function connectSocket(options) {
+    const maxIpcId = options?.maxIpcId ?? DEFAULT_MAX_IPC_ID;
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    let lastError = null;
+    for (let id = 0; id <= maxIpcId; id += 1) {
+        const socketPath = getIpcPath(id);
+        try {
+            const socket = await new Promise((resolve, reject) => {
+                const socket = net.createConnection(socketPath);
+                const timer = setTimeout(() => {
+                    socket.destroy();
+                    reject(new Error(`discord ipc connect timeout: ${socketPath}`));
+                }, timeoutMs);
+                socket.once("connect", () => {
+                    clearTimeout(timer);
+                    resolve(socket);
+                });
+                socket.once("error", (error) => {
+                    clearTimeout(timer);
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                });
+            });
+            socket.setNoDelay(true);
+            return socket;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+        }
+    }
+    throw lastError ?? new Error("unable to connect to discord ipc socket");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+export class DiscordRpcClient {
+    options;
+    socket = null;
+    decoder = new FrameDecoder();
+    pending = new Map();
+    emitter = new EventEmitter();
+    ready = false;
+    readyWaiters = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    async connect() {
+        if (this.socket && !this.socket.destroyed) {
+            if (!this.ready) {
+                await this.waitForReady();
+            }
+            return;
+        }
+        const socket = await connectSocket(this.options.connect);
+        this.socket = socket;
+        this.ready = false;
+        socket.on("data", (chunk) => {
+            try {
+                const frames = this.decoder.feed(chunk);
+                for (const frame of frames) {
+                    this.handleFrame(frame);
+                }
+            }
+            catch (error) {
+                this.failPending(error instanceof Error ? error : new Error(String(error)));
+                this.shutdownSocket();
+            }
+        });
+        socket.on("error", (error) => {
+            this.failPending(error instanceof Error ? error : new Error(String(error)));
+            this.shutdownSocket();
+        });
+        socket.on("close", () => {
+            this.failPending(new Error("discord ipc socket closed"));
+            this.shutdownSocket();
+        });
+        socket.write(encodeFrame(OPCODE_HANDSHAKE, {
+            v: 1,
+            client_id: this.options.clientId,
+        }));
+        await this.waitForReady();
+    }
+    async authenticate(accessToken) {
+        await this.request("AUTHENTICATE", { access_token: accessToken });
+    }
+    async authorize(scopes, options) {
+        const result = await this.request("AUTHORIZE", {
+            client_id: this.options.clientId,
+            scopes,
+            prompt: options?.prompt,
+            rpc_token: options?.rpcToken,
+        }, undefined, AUTHORIZE_TIMEOUT_MS);
+        if (!isRecord(result) || typeof result.code !== "string" || result.code.length === 0) {
+            throw new Error("discord rpc authorize did not return code");
+        }
+        return { code: result.code };
+    }
+    async subscribe(eventName, args) {
+        await this.request("SUBSCRIBE", args ?? {}, eventName);
+    }
+    async getChannel(channelId) {
+        const result = await this.request("GET_CHANNEL", { channel_id: channelId });
+        if (!isRecord(result)) {
+            throw new Error("discord rpc GET_CHANNEL returned invalid payload");
+        }
+        const id = readString(result.id);
+        if (!id) {
+            throw new Error("discord rpc GET_CHANNEL missing channel id");
+        }
+        return {
+            id,
+            name: readString(result.name),
+            guildId: readString(result.guild_id),
+        };
+    }
+    async getGuild(guildId) {
+        const result = await this.request("GET_GUILD", { guild_id: guildId });
+        if (!isRecord(result)) {
+            throw new Error("discord rpc GET_GUILD returned invalid payload");
+        }
+        const id = readString(result.id);
+        if (!id) {
+            throw new Error("discord rpc GET_GUILD missing guild id");
+        }
+        return {
+            id,
+            name: readString(result.name),
+        };
+    }
+    onEvent(eventName, handler) {
+        this.emitter.on(`event:${eventName}`, handler);
+        return () => {
+            this.emitter.off(`event:${eventName}`, handler);
+        };
+    }
+    onDisconnected(handler) {
+        this.emitter.on("disconnected", handler);
+        return () => {
+            this.emitter.off("disconnected", handler);
+        };
+    }
+    async waitForDisconnect() {
+        if (!this.socket || this.socket.destroyed) {
+            return;
+        }
+        await new Promise((resolve) => {
+            const off = this.onDisconnected(() => {
+                off();
+                resolve();
+            });
+        });
+    }
+    close() {
+        this.failPending(new Error("discord rpc client closed"));
+        this.shutdownSocket();
+    }
+    async request(cmd, args, evt, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+        const socket = this.socket;
+        if (!socket || socket.destroyed) {
+            throw new Error("discord ipc socket is not connected");
+        }
+        const nonce = randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(nonce);
+                reject(new Error(`discord rpc timeout: ${cmd}`));
+            }, timeoutMs);
+            this.pending.set(nonce, { resolve, reject, timer });
+            socket.write(encodeFrame(OPCODE_FRAME, {
+                cmd,
+                args,
+                evt,
+                nonce,
+            }));
+        });
+    }
+    handleFrame(frame) {
+        if (frame.op === OPCODE_PING) {
+            this.socket?.write(encodeFrame(OPCODE_PONG, frame.data));
+            return;
+        }
+        if (frame.op === OPCODE_CLOSE) {
+            this.shutdownSocket();
+            return;
+        }
+        if (frame.op !== OPCODE_FRAME || !isRecord(frame.data)) {
+            return;
+        }
+        const envelope = frame.data;
+        const nonce = typeof envelope.nonce === "string" ? envelope.nonce : undefined;
+        if (nonce && this.pending.has(nonce)) {
+            const pending = this.pending.get(nonce);
+            if (!pending) {
+                return;
+            }
+            this.pending.delete(nonce);
+            clearTimeout(pending.timer);
+            if (envelope.evt === "ERROR") {
+                const message = isRecord(envelope.data) && typeof envelope.data.message === "string"
+                    ? envelope.data.message
+                    : "discord rpc command failed";
+                pending.reject(new Error(message));
+                return;
+            }
+            pending.resolve(envelope.data);
+            return;
+        }
+        if (envelope.cmd === "DISPATCH" && typeof envelope.evt === "string") {
+            if (envelope.evt === "READY") {
+                this.markReady();
+            }
+            this.emitter.emit(`event:${envelope.evt}`, envelope.data);
+        }
+    }
+    waitForReady(timeoutMs = READY_TIMEOUT_MS) {
+        if (this.ready) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                resolve: () => {
+                    clearTimeout(waiter.timer);
+                    this.readyWaiters.delete(waiter);
+                    resolve();
+                },
+                reject: (error) => {
+                    clearTimeout(waiter.timer);
+                    this.readyWaiters.delete(waiter);
+                    reject(error);
+                },
+                timer: setTimeout(() => {
+                    this.readyWaiters.delete(waiter);
+                    reject(new Error("discord rpc timeout: READY"));
+                }, timeoutMs),
+            };
+            this.readyWaiters.add(waiter);
+        });
+    }
+    markReady() {
+        if (this.ready) {
+            return;
+        }
+        this.ready = true;
+        for (const waiter of this.readyWaiters) {
+            waiter.resolve();
+        }
+        this.readyWaiters.clear();
+    }
+    failPending(error) {
+        for (const [nonce, pending] of this.pending.entries()) {
+            this.pending.delete(nonce);
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+    }
+    shutdownSocket() {
+        const socket = this.socket;
+        this.ready = false;
+        for (const waiter of this.readyWaiters) {
+            waiter.reject(new Error("discord ipc socket closed before READY"));
+        }
+        this.readyWaiters.clear();
+        if (!socket) {
+            return;
+        }
+        this.socket = null;
+        if (!socket.destroyed) {
+            socket.destroy();
+        }
+        this.emitter.emit("disconnected");
+    }
+}

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

@@ -0,0 +1,66 @@
+export const EMBEDDING_METHOD_EMBED_BATCH = "embedding.embedBatch";
+const DEFAULT_MAX_CONCURRENT_REQUESTS = 4;
+const DEFAULT_MAX_TEXTS_PER_REQUEST = 16;
+function toPositiveInteger(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    const normalized = Math.floor(value);
+    if (normalized <= 0) {
+        return fallback;
+    }
+    return normalized;
+}
+function parseEmbedBatchParams(params) {
+    if (!params || typeof params !== "object") {
+        throw new Error("embedding.embedBatch requires object params");
+    }
+    const texts = params.texts;
+    if (!Array.isArray(texts) || texts.some((item) => typeof item !== "string")) {
+        throw new Error("embedding.embedBatch requires string[] texts");
+    }
+    return { texts };
+}
+export function createEmbeddingHandlers(provider, options) {
+    const maxConcurrentRequests = toPositiveInteger(options?.maxConcurrentRequests, DEFAULT_MAX_CONCURRENT_REQUESTS);
+    const maxTextsPerRequest = toPositiveInteger(options?.maxTextsPerRequest, DEFAULT_MAX_TEXTS_PER_REQUEST);
+    let inFlight = 0;
+    return {
+        [EMBEDDING_METHOD_EMBED_BATCH]: async (request) => {
+            const { texts } = parseEmbedBatchParams(request.params);
+            if (texts.length > maxTextsPerRequest) {
+                throw new Error(`embedding.embedBatch exceeded text limit ${maxTextsPerRequest}: got ${texts.length}`);
+            }
+            if (inFlight >= maxConcurrentRequests) {
+                throw new Error(`embedding service overloaded: in-flight limit ${maxConcurrentRequests} reached`);
+            }
+            inFlight += 1;
+            try {
+                const vectors = await provider.embedBatch(texts);
+                const result = { vectors };
+                return result;
+            }
+            finally {
+                inFlight = Math.max(0, inFlight - 1);
+            }
+        },
+    };
+}
+export function createEmbeddingClient(client, options) {
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    return {
+        id: "local",
+        model: options.model,
+        embedQuery: async (text) => {
+            const result = await client.call(EMBEDDING_METHOD_EMBED_BATCH, { texts: [text] }, { timeoutMs });
+            return result.vectors[0] ?? [];
+        },
+        embedBatch: async (texts) => {
+            const result = await client.call(EMBEDDING_METHOD_EMBED_BATCH, { texts }, { timeoutMs });
+            return result.vectors;
+        },
+        dispose: async () => {
+            // lifecycle owns ClusterRpcClient and closes it.
+        },
+    };
+}

package/dist/src/cluster_v2/services/registry-cache.js

@@ -0,0 +1,107 @@
+import { logClusterEvent } from "../observability.js";
+/**
+ * Follower-side registry cache with revision-bound guards.
+ *
+ * Conformance invariant: cacheRevision <= registryRevision.
+ */
+export class FollowerRegistryCache {
+    client;
+    context;
+    revision = 0;
+    services = new Map();
+    constructor(client, context) {
+        this.client = client;
+        this.context = context;
+    }
+    currentRevision() {
+        return this.revision;
+    }
+    invalidate(reason) {
+        if (this.revision !== 0 || this.services.size > 0) {
+            logClusterEvent("info", "registry_cache_invalidated", this.context, {
+                reason,
+                cacheRevision: this.revision,
+                cachedServices: this.services.size,
+            });
+        }
+        this.revision = 0;
+        this.services.clear();
+    }
+    async refresh() {
+        const snapshot = await this.client.call("registry.list", {});
+        this.applySnapshot(snapshot, "refresh");
+        return this.revision;
+    }
+    async resolve(name) {
+        const cached = this.services.get(name);
+        if (cached) {
+            return { ...cached };
+        }
+        const response = await this.client.call("registry.resolve", { name });
+        this.applyResolve(name, response);
+        const resolved = this.services.get(name);
+        return resolved ? { ...resolved } : undefined;
+    }
+    async requireService(name) {
+        const service = await this.resolve(name);
+        if (!service) {
+            throw new Error(`required service unavailable: ${name}`);
+        }
+        return service;
+    }
+    applySnapshot(snapshot, source) {
+        const registryRevision = this.normalizeRevision(snapshot.revision, source);
+        if (registryRevision < this.revision) {
+            logClusterEvent("warn", "registry_revision_regressed", this.context, {
+                source,
+                cacheRevision: this.revision,
+                registryRevision,
+            });
+            this.invalidate("revision_regressed");
+        }
+        this.assertCacheBound(registryRevision, `${source}:pre_apply`);
+        this.revision = registryRevision;
+        this.services.clear();
+        for (const service of snapshot.services) {
+            this.services.set(service.name, { ...service });
+        }
+        this.assertCacheBound(registryRevision, `${source}:post_apply`);
+    }
+    applyResolve(name, response) {
+        const registryRevision = this.normalizeRevision(response.revision, "resolve");
+        if (registryRevision < this.revision) {
+            logClusterEvent("warn", "registry_resolve_revision_regressed", this.context, {
+                cacheRevision: this.revision,
+                registryRevision,
+                serviceName: name,
+            });
+            this.invalidate("resolve_revision_regressed");
+            throw new Error("registry cache stale after leader change; refresh required");
+        }
+        this.assertCacheBound(registryRevision, "resolve:pre_apply");
+        this.revision = registryRevision;
+        if (response.service) {
+            this.services.set(name, { ...response.service });
+        }
+        else {
+            this.services.delete(name);
+        }
+        this.assertCacheBound(registryRevision, "resolve:post_apply");
+    }
+    assertCacheBound(registryRevision, source) {
+        if (this.revision > registryRevision) {
+            logClusterEvent("warn", "registry_cache_bound_violation", this.context, {
+                source,
+                cacheRevision: this.revision,
+                registryRevision,
+            });
+            throw new Error(`registry cache invariant violated: cacheVersion ${this.revision} > registryVersion ${registryRevision}`);
+        }
+    }
+    normalizeRevision(revision, source) {
+        if (!Number.isInteger(revision) || revision < 0) {
+            throw new Error(`invalid registry revision from ${source}: ${String(revision)}`);
+        }
+        return revision;
+    }
+}

package/dist/src/cluster_v2/services/registry-cache.test.js

@@ -0,0 +1,66 @@
+import { describe, it, expect, vi } from "vitest";
+import { FollowerRegistryCache } from "./registry-cache.js";
+import { createClusterLogContext } from "../observability.js";
+function createClientStub(resolver) {
+    return {
+        call: vi.fn((method, params) => resolver(method, params)),
+    };
+}
+function service(name) {
+    return { name, version: "v2" };
+}
+describe("cluster_v2 follower registry cache", () => {
+    it("refreshes cache and resolves required services", async () => {
+        const client = createClientStub(async (method, params) => {
+            if (method === "registry.list") {
+                return { revision: 3, services: [service("embedding"), service("bus")] };
+            }
+            if (method === "registry.resolve") {
+                const name = params.name;
+                return { revision: 3, service: service(name) };
+            }
+            throw new Error(`unexpected method: ${method}`);
+        });
+        const cache = new FollowerRegistryCache(client, createClusterLogContext({ role: "test" }));
+        await cache.refresh();
+        expect(cache.currentRevision()).toBe(3);
+        await expect(cache.requireService("embedding")).resolves.toEqual(service("embedding"));
+        await expect(cache.requireService("bus")).resolves.toEqual(service("bus"));
+    });
+    it("invalidates and rejects stale resolve when revision regresses", async () => {
+        let phase = "list";
+        const client = createClientStub(async (method) => {
+            if (method === "registry.list" && phase === "list") {
+                phase = "resolve";
+                return { revision: 5, services: [service("embedding")] };
+            }
+            if (method === "registry.resolve" && phase === "resolve") {
+                return { revision: 4, service: service("bus") };
+            }
+            throw new Error(`unexpected call for phase ${phase}: ${method}`);
+        });
+        const cache = new FollowerRegistryCache(client, createClusterLogContext({ role: "test" }));
+        await cache.refresh();
+        expect(cache.currentRevision()).toBe(5);
+        await expect(cache.resolve("bus")).rejects.toThrow("stale");
+        expect(cache.currentRevision()).toBe(0);
+    });
+    it("drops cache contents on explicit invalidation", async () => {
+        const client = createClientStub(async (method, params) => {
+            if (method === "registry.list") {
+                return { revision: 2, services: [service("embedding")] };
+            }
+            if (method === "registry.resolve") {
+                const name = params.name;
+                return { revision: 2, service: name === "embedding" ? undefined : service(name) };
+            }
+            throw new Error(`unexpected method: ${method}`);
+        });
+        const cache = new FollowerRegistryCache(client, createClusterLogContext({ role: "test" }));
+        await cache.refresh();
+        expect(cache.currentRevision()).toBe(2);
+        cache.invalidate("leader_disconnect");
+        expect(cache.currentRevision()).toBe(0);
+        await expect(cache.requireService("embedding")).rejects.toThrow("required service unavailable");
+    });
+});

package/dist/src/cluster_v2/services/registry.js

@@ -0,0 +1,36 @@
+/**
+ * Leader-local service registry with monotonic revision.
+ * Followers can use revision to invalidate stale snapshots after failover.
+ */
+export class ServiceRegistry {
+    services = new Map();
+    revision = 0;
+    register(service) {
+        this.services.set(service.name, { ...service });
+        this.revision++;
+        return service;
+    }
+    unregister(name) {
+        const deleted = this.services.delete(name);
+        if (deleted) {
+            this.revision++;
+        }
+        return deleted;
+    }
+    resolve(name) {
+        const svc = this.services.get(name);
+        return svc ? { ...svc } : undefined;
+    }
+    list() {
+        return [...this.services.values()].map((service) => ({ ...service }));
+    }
+    getRevision() {
+        return this.revision;
+    }
+    snapshot() {
+        return {
+            revision: this.revision,
+            services: this.list(),
+        };
+    }
+}