@ask-llm/plugin 0.18.0 → 0.19.0

package/scripts/lib/broker-rpc.mjs

@@ -0,0 +1,173 @@
+// Source of truth: broker-rpc.mts. The sibling .mjs is generated by `yarn workspace @ask-llm/plugin build:hooks`; never edit it.
+let nextId = 1;
+function takeNextId() {
+    const id = nextId;
+    nextId = (nextId + 1) | 0; // wrap at 2^31 (effectively never)
+    if (nextId <= 0)
+        nextId = 1;
+    return id;
+}
+// The caller owns the WebSocket lifetime; this client owns request and notification state.
+export function createRpcClient(connection, options = {}) {
+    const { defaultTimeoutMs = 30000, onNotification = () => { }, onProtocolError = () => { } } = options;
+    const pending = new Map();
+    // Subscribe before turn/start so a fast completion cannot be missed.
+    const notificationSubscribers = new Set();
+    let closed = false;
+    connection.on("message", (text) => {
+        let env;
+        try {
+            env = JSON.parse(text);
+        }
+        catch (err) {
+            onProtocolError(new Error(`broker-rpc: malformed JSON from server: ${err?.message ?? String(err)}`));
+            return;
+        }
+        if (env && typeof env === "object" && "id" in env && env.id != null) {
+            const entry = pending.get(env.id);
+            if (!entry) {
+                // Late or unknown responses are soft protocol errors.
+                onProtocolError(new Error(`broker-rpc: response for unknown id ${env.id}`));
+                return;
+            }
+            pending.delete(env.id);
+            clearTimeout(entry.timer);
+            if (env.error) {
+                const err = new Error(env.error.message ?? `JSON-RPC error ${env.error.code ?? "?"}`);
+                err.code = env.error.code;
+                err.data = env.error.data;
+                entry.reject(err);
+            }
+            else {
+                entry.resolve(env.result);
+            }
+            return;
+        }
+        if (env && typeof env === "object" && typeof env.method === "string") {
+            // Pass server-pushed messages to callers even when they resemble server requests.
+            const notification = { method: env.method, params: env.params, id: env.id };
+            // Snapshot subscribers because dispatch removes resolved waiters.
+            for (const sub of [...notificationSubscribers]) {
+                if (sub.method === env.method) {
+                    try {
+                        if (!sub.predicate || sub.predicate(notification)) {
+                            notificationSubscribers.delete(sub);
+                            if (sub.timer)
+                                clearTimeout(sub.timer);
+                            sub.resolve(notification);
+                        }
+                    }
+                    catch (err) {
+                        notificationSubscribers.delete(sub);
+                        if (sub.timer)
+                            clearTimeout(sub.timer);
+                        sub.reject(err);
+                    }
+                }
+            }
+            onNotification(notification);
+            return;
+        }
+        onProtocolError(new Error(`broker-rpc: envelope has neither id nor method: ${text.slice(0, 120)}`));
+    });
+    connection.on("close", () => {
+        closed = true;
+        for (const [id, entry] of pending.entries()) {
+            clearTimeout(entry.timer);
+            entry.reject(new Error("broker-rpc: connection closed before response"));
+            pending.delete(id);
+        }
+        // Also reject any notification waiters — they'll never fire post-close.
+        for (const sub of notificationSubscribers) {
+            if (sub.timer)
+                clearTimeout(sub.timer);
+            sub.reject(new Error("broker-rpc: connection closed before notification"));
+        }
+        notificationSubscribers.clear();
+    });
+    connection.on("error", (err) => {
+        // Surface transport errors before pending request timers expire.
+        for (const [id, entry] of pending.entries()) {
+            clearTimeout(entry.timer);
+            entry.reject(err);
+            pending.delete(id);
+        }
+        // Reject waiters on transport error even if no close event follows.
+        for (const sub of notificationSubscribers) {
+            if (sub.timer)
+                clearTimeout(sub.timer);
+            sub.reject(err);
+        }
+        notificationSubscribers.clear();
+    });
+    return {
+        request(method, params, opts = {}) {
+            if (closed)
+                return Promise.reject(new Error("broker-rpc: client is closed"));
+            const id = takeNextId();
+            const timeoutMs = opts.timeoutMs ?? defaultTimeoutMs;
+            const envelope = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    pending.delete(id);
+                    reject(new Error(`broker-rpc: timeout after ${timeoutMs}ms (method=${method}, id=${id})`));
+                }, timeoutMs);
+                timer.unref?.();
+                pending.set(id, { resolve: resolve, reject, timer });
+                try {
+                    connection.sendText(envelope);
+                }
+                catch (err) {
+                    pending.delete(id);
+                    clearTimeout(timer);
+                    reject(err);
+                }
+            });
+        },
+        notify(method, params) {
+            // Notifications have no id and expect no response.
+            if (closed)
+                throw new Error("broker-rpc: client is closed");
+            connection.sendText(JSON.stringify({ jsonrpc: "2.0", method, params }));
+        },
+        // Register waitFor before the request that triggers its notification.
+        waitFor(method, predicate, timeoutMs) {
+            if (closed)
+                return Promise.reject(new Error("broker-rpc: client is closed"));
+            let sub;
+            const promise = new Promise((resolve, reject) => {
+                sub = { method, predicate, resolve, reject, timer: null };
+                const subscriber = sub;
+                sub.timer = setTimeout(() => {
+                    notificationSubscribers.delete(subscriber);
+                    // Preserve a structured timeout marker for callers.
+                    const err = new Error(`broker-rpc: waitFor(${method}) timed out after ${timeoutMs}ms`);
+                    err.timeout = true;
+                    reject(err);
+                }, timeoutMs);
+                sub.timer.unref?.();
+                notificationSubscribers.add(sub);
+            });
+            promise.cancel = () => {
+                if (!notificationSubscribers.delete(sub))
+                    return;
+                if (sub.timer)
+                    clearTimeout(sub.timer);
+                sub.resolve(null);
+            };
+            return promise;
+        },
+        get pendingCount() {
+            return pending.size;
+        },
+        get closed() {
+            return closed;
+        },
+    };
+}
+// Exports for tests
+export const __testing__ = {
+    resetIdCounter() {
+        nextId = 1;
+    },
+};

package/scripts/lib/broker-transport.mjs

@@ -0,0 +1,327 @@
+// Source of truth: broker-transport.mts. The sibling .mjs is generated by `yarn workspace @ask-llm/plugin build:hooks`; never edit it.
+// App-server responses may omit jsonrpc; the RPC layer correlates by id.
+import { Buffer } from "node:buffer";
+import { createHash, randomBytes } from "node:crypto";
+import { connect } from "node:net";
+// RFC 6455 frame opcodes we recognize.
+const OPCODE_CONTINUATION = 0x0;
+const OPCODE_TEXT = 0x1;
+const OPCODE_BINARY = 0x2;
+const OPCODE_CLOSE = 0x8;
+const OPCODE_PING = 0x9;
+const OPCODE_PONG = 0xa;
+// RFC 6455 magic GUID for the Sec-WebSocket-Accept derivation (§4.2.2).
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+export function parseTransportUrl(url) {
+    if (typeof url !== "string") {
+        throw new TypeError(`broker-transport: transport URL must be string, got ${typeof url}`);
+    }
+    if (url.startsWith("unix://")) {
+        const path = url.slice("unix://".length);
+        if (!path)
+            throw new Error(`broker-transport: unix:// URL has empty path`);
+        return { connectOptions: { path }, host: "localhost", isUnix: true };
+    }
+    if (url.startsWith("ws://")) {
+        const rest = url.slice("ws://".length);
+        const slashIdx = rest.indexOf("/");
+        const authority = slashIdx === -1 ? rest : rest.slice(0, slashIdx);
+        const colonIdx = authority.lastIndexOf(":");
+        const host = colonIdx === -1 ? authority : authority.slice(0, colonIdx);
+        const port = colonIdx === -1 ? 80 : Number(authority.slice(colonIdx + 1));
+        if (!Number.isFinite(port) || port <= 0) {
+            throw new Error(`broker-transport: ws:// URL has invalid port: ${authority}`);
+        }
+        return { connectOptions: { host, port }, host: authority, isUnix: false };
+    }
+    throw new Error(`broker-transport: unsupported transport URL scheme: ${url} (need unix:// or ws://)`);
+}
+// HTTP upgrade needs a Host header even over a Unix socket.
+function buildUpgradeRequest(host, secKey) {
+    return [
+        `GET / HTTP/1.1`,
+        `Host: ${host}`,
+        `Upgrade: websocket`,
+        `Connection: Upgrade`,
+        `Sec-WebSocket-Key: ${secKey}`,
+        `Sec-WebSocket-Version: 13`,
+        ``,
+        ``,
+    ].join("\r\n");
+}
+// Verify the required status and accept hash; optional upgrade headers are ignored.
+function validateUpgradeResponse(headerText, sentKey) {
+    const lines = headerText.split("\r\n");
+    if (!lines[0] || !/^HTTP\/1\.[01]\s+101\b/.test(lines[0])) {
+        throw new Error(`broker-transport: upgrade rejected, status line: ${lines[0] ?? "(empty)"}`);
+    }
+    let accept = null;
+    for (let i = 1; i < lines.length; i++) {
+        const colon = lines[i].indexOf(":");
+        if (colon === -1)
+            continue;
+        const name = lines[i].slice(0, colon).trim().toLowerCase();
+        if (name === "sec-websocket-accept") {
+            accept = lines[i].slice(colon + 1).trim();
+            break;
+        }
+    }
+    const expected = createHash("sha1")
+        .update(sentKey + WS_GUID)
+        .digest("base64");
+    if (accept !== expected) {
+        throw new Error(`broker-transport: Sec-WebSocket-Accept mismatch (got ${accept ?? "(missing)"}, expected ${expected})`);
+    }
+}
+// RFC 6455 requires masking client frames.
+function encodeTextFrame(text) {
+    const payload = Buffer.from(text, "utf-8");
+    const mask = randomBytes(4);
+    const masked = Buffer.allocUnsafe(payload.length);
+    for (let i = 0; i < payload.length; i++)
+        masked[i] = payload[i] ^ mask[i % 4];
+    let lenBytes;
+    if (payload.length < 126) {
+        lenBytes = Buffer.from([0x80 | payload.length]); // MASK bit + 7-bit length
+    }
+    else if (payload.length < 0x10000) {
+        lenBytes = Buffer.allocUnsafe(3);
+        lenBytes[0] = 0x80 | 126;
+        lenBytes.writeUInt16BE(payload.length, 1);
+    }
+    else {
+        lenBytes = Buffer.allocUnsafe(9);
+        lenBytes[0] = 0x80 | 127;
+        // BigInt handles 64-bit frame lengths before safe conversion.
+        lenBytes.writeBigUInt64BE(BigInt(payload.length), 1);
+    }
+    return Buffer.concat([
+        Buffer.from([0x80 | OPCODE_TEXT]), // FIN bit + TEXT opcode
+        lenBytes,
+        mask,
+        masked,
+    ]);
+}
+// Control-frame payloads cannot exceed 125 bytes under RFC 6455.
+const MAX_CONTROL_FRAME_PAYLOAD = 125;
+// Truncate CLOSE reasons to the control-frame payload limit.
+function encodeCloseFrame(code = 1000, reason = "") {
+    let reasonBuf = Buffer.from(reason, "utf-8");
+    // Reserve two control-frame bytes for the close status code.
+    if (2 + reasonBuf.length > MAX_CONTROL_FRAME_PAYLOAD) {
+        reasonBuf = reasonBuf.slice(0, MAX_CONTROL_FRAME_PAYLOAD - 2);
+    }
+    const payload = Buffer.allocUnsafe(2 + reasonBuf.length);
+    payload.writeUInt16BE(code, 0);
+    reasonBuf.copy(payload, 2);
+    const mask = randomBytes(4);
+    const masked = Buffer.allocUnsafe(payload.length);
+    for (let i = 0; i < payload.length; i++)
+        masked[i] = payload[i] ^ mask[i % 4];
+    return Buffer.concat([Buffer.from([0x80 | OPCODE_CLOSE, 0x80 | payload.length]), mask, masked]);
+}
+// Truncate malformed oversized PING payloads before echoing PONG.
+function encodePongFrame(payload) {
+    const capped = payload.length > MAX_CONTROL_FRAME_PAYLOAD ? payload.slice(0, MAX_CONTROL_FRAME_PAYLOAD) : payload;
+    const mask = randomBytes(4);
+    const masked = Buffer.allocUnsafe(capped.length);
+    for (let i = 0; i < capped.length; i++)
+        masked[i] = capped[i] ^ mask[i % 4];
+    return Buffer.concat([Buffer.from([0x80 | OPCODE_PONG, 0x80 | capped.length]), mask, masked]);
+}
+// Corrupted framing stops parsing; the connector destroys the socket to reject pending RPCs.
+function createFrameParser(onFrame, onError) {
+    let buf = Buffer.alloc(0);
+    let corrupted = false;
+    return (chunk) => {
+        if (corrupted)
+            return; // already reported fatal — discard further bytes
+        buf = Buffer.concat([buf, chunk]);
+        while (buf.length >= 2) {
+            const first = buf[0];
+            const second = buf[1];
+            const fin = (first & 0x80) !== 0;
+            const opcode = first & 0x0f;
+            let len = second & 0x7f;
+            let offset = 2;
+            if (len === 126) {
+                if (buf.length < 4)
+                    return; // need more
+                len = buf.readUInt16BE(2);
+                offset = 4;
+            }
+            else if (len === 127) {
+                if (buf.length < 10)
+                    return;
+                // Reject frame lengths outside the safe integer range before converting from BigInt.
+                len = Number(buf.readBigUInt64BE(2));
+                offset = 10;
+            }
+            // Server frames must be unmasked; skip an unexpected mask if present.
+            const maskBit = (second & 0x80) !== 0;
+            if (maskBit)
+                offset += 4;
+            if (buf.length < offset + len)
+                return; // need more
+            if (!fin && opcode !== OPCODE_CONTINUATION) {
+                // Unsupported fragmentation corrupts the parser and closes the connection.
+                corrupted = true;
+                buf = Buffer.alloc(0);
+                onError(new Error(`broker-transport: fragmentation not supported (opcode=${opcode}) — connection terminating`));
+                return;
+            }
+            const payload = buf.slice(offset, offset + len);
+            buf = buf.slice(offset + len);
+            onFrame({ opcode, payload });
+        }
+    };
+}
+// The caller owns the connection after upgrade; the handshake timeout applies only until then.
+export async function connectWebSocket(transportUrl, options = {}) {
+    const { handshakeTimeoutMs = 5000 } = options;
+    const { connectOptions, host } = parseTransportUrl(transportUrl);
+    return new Promise((resolve, reject) => {
+        const socket = connect(connectOptions);
+        const listeners = { message: [], close: [], error: [] };
+        let upgraded = false;
+        let headerBuf = Buffer.alloc(0);
+        let parser = null;
+        const timer = setTimeout(() => {
+            if (!upgraded) {
+                socket.destroy();
+                reject(new Error(`broker-transport: handshake timeout after ${handshakeTimeoutMs}ms`));
+            }
+        }, handshakeTimeoutMs);
+        timer.unref?.();
+        const secKey = randomBytes(16).toString("base64");
+        // Keep the error listener after upgrade to avoid an unhandled second socket error.
+        socket.on("error", (err) => {
+            if (!upgraded) {
+                clearTimeout(timer);
+                reject(err);
+            }
+            else {
+                for (const cb of listeners.error)
+                    cb(err);
+            }
+        });
+        // Send the HTTP upgrade after transport connection; TCP and Unix sockets both require it.
+        socket.once("connect", () => {
+            try {
+                socket.write(buildUpgradeRequest(host, secKey));
+            }
+            catch (err) {
+                if (!upgraded) {
+                    clearTimeout(timer);
+                    reject(err);
+                }
+            }
+        });
+        socket.once("close", () => {
+            clearTimeout(timer);
+            if (!upgraded)
+                reject(new Error("broker-transport: socket closed before upgrade"));
+            else
+                for (const cb of listeners.close)
+                    cb();
+        });
+        socket.on("data", (chunk) => {
+            if (upgraded) {
+                parser?.(chunk);
+                return;
+            }
+            headerBuf = Buffer.concat([headerBuf, chunk]);
+            const end = headerBuf.indexOf("\r\n\r\n");
+            if (end === -1)
+                return;
+            const headerText = headerBuf.slice(0, end).toString("utf-8");
+            const tail = headerBuf.slice(end + 4);
+            try {
+                validateUpgradeResponse(headerText, secKey);
+            }
+            catch (err) {
+                socket.destroy();
+                clearTimeout(timer);
+                reject(err);
+                return;
+            }
+            upgraded = true;
+            clearTimeout(timer);
+            parser = createFrameParser(({ opcode, payload }) => {
+                if (opcode === OPCODE_TEXT) {
+                    const text = payload.toString("utf-8");
+                    for (const cb of listeners.message)
+                        cb(text);
+                }
+                else if (opcode === OPCODE_PING) {
+                    // Auto-respond with PONG mirroring the payload (RFC §5.5.2).
+                    socket.write(encodePongFrame(payload));
+                }
+                else if (opcode === OPCODE_CLOSE) {
+                    // Echo close + half-close (RFC §5.5.1).
+                    try {
+                        socket.write(encodeCloseFrame(1000, ""));
+                    }
+                    catch {
+                        // best-effort
+                    }
+                    socket.end();
+                }
+                else if (opcode === OPCODE_BINARY) {
+                    // codex doesn't send binary for JSON-RPC; ignore silently.
+                }
+                // PONG and CONTINUATION are no-ops here.
+            }, (err) => {
+                for (const cb of listeners.error)
+                    cb(err);
+                // Destroy the socket on parser corruption so pending RPCs reject.
+                try {
+                    socket.destroy();
+                }
+                catch {
+                    // best-effort
+                }
+            });
+            const conn = {
+                sendText(text) {
+                    socket.write(encodeTextFrame(text));
+                },
+                close(code = 1000, reason = "") {
+                    try {
+                        socket.write(encodeCloseFrame(code, reason));
+                    }
+                    catch {
+                        // best-effort — caller treats close as fire-and-forget
+                    }
+                    socket.end();
+                },
+                on(event, cb) {
+                    if (!listeners[event])
+                        throw new Error(`broker-transport: unknown event ${event}`);
+                    listeners[event].push(cb);
+                },
+                get destroyed() {
+                    return socket.destroyed;
+                },
+                // For tests / diagnostics
+                _underlyingSocket() {
+                    return socket;
+                },
+            };
+            // If the upgrade response had body bytes already buffered, feed them.
+            if (tail.length > 0)
+                parser(tail);
+            resolve(conn);
+        });
+    });
+}
+// Exports for tests
+export const __testing__ = {
+    encodeTextFrame,
+    encodeCloseFrame,
+    encodePongFrame,
+    createFrameParser,
+    validateUpgradeResponse,
+    buildUpgradeRequest,
+    WS_GUID,
+};