@masons/agent-network 0.5.28 → 0.5.29

package/dist/broker/entry.js

@@ -0,0 +1,85 @@
+import { pathToFileURL } from "node:url";
+import { readConfig } from "../config-fs.js";
+import { DEFAULT_API_HOST } from "../platform-client.js";
+import { heartbeatRuntimeEndpoint, registerRuntimeEndpoint, unregisterRuntimeEndpoint, } from "../runtime-endpoint-client.js";
+import { startBrokerDaemon } from "./broker-daemon.js";
+import { ConnectorWS } from "./connector-ws.js";
+import { createBrokerLogger } from "./logger.js";
+import { resolveBrokerPaths } from "./paths.js";
+const DEFAULT_ACCOUNT_ID = "default";
+async function resolveCredentials(accountId, envApiHost) {
+    const config = await readConfig();
+    const channels = config.channels;
+    const network = channels?.["agent-network"];
+    const apiHost = envApiHost ??
+        (typeof network?.apiHost === "string" ? network.apiHost : DEFAULT_API_HOST);
+    const accounts = network?.accounts;
+    const account = accounts?.[accountId];
+    const connectorUrl = typeof account?.connectorUrl === "string" ? account.connectorUrl : null;
+    const token = typeof account?.token === "string" ? account.token : null;
+    if (!connectorUrl || !token) {
+        throw new Error(`agent-network credentials missing for account "${accountId}"; ` +
+            "run setup before lazy-spawning the broker");
+    }
+    return { accountId, connectorUrl, token, apiHost };
+}
+function buildApiPort(apiHost, runtimeKey) {
+    return {
+        async register(params) {
+            return registerRuntimeEndpoint({ apiHost }, runtimeKey, params);
+        },
+        async heartbeat(endpointId) {
+            await heartbeatRuntimeEndpoint({ apiHost }, runtimeKey, endpointId);
+        },
+        async unregister(endpointId, asNodeId) {
+            await unregisterRuntimeEndpoint({ apiHost }, runtimeKey, endpointId, asNodeId);
+        },
+    };
+}
+export async function main() {
+    const accountId = process.env.MASONS_BROKER_ACCOUNT_ID ?? DEFAULT_ACCOUNT_ID;
+    const envApiHost = process.env.MASONS_BROKER_API_HOST;
+    const userDataOverride = process.env.MASONS_BROKER_USER_DATA;
+    const creds = await resolveCredentials(accountId, envApiHost);
+    const paths = resolveBrokerPaths(creds.accountId, creds.token, {
+        userDataDir: userDataOverride,
+    });
+    const logger = createBrokerLogger(paths.logDir);
+    logger.info("broker_entry_starting", {
+        accountId: creds.accountId,
+        apiHost: creds.apiHost,
+        pid: process.pid,
+    });
+    const asNodeId = creds.accountId;
+    const connector = new ConnectorWS({
+        url: creds.connectorUrl,
+        token: creds.token,
+    });
+    const apiPort = buildApiPort(creds.apiHost, creds.token);
+    const broker = await startBrokerDaemon({
+        paths,
+        asNodeId,
+        connector,
+        apiPort,
+        logger,
+    });
+    let shuttingDown = false;
+    const handleSignal = (sig) => async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        logger.info("broker_signal", { sig });
+        await broker.shutdown(`signal:${sig}`);
+        process.exit(0);
+    };
+    process.on("SIGTERM", handleSignal("SIGTERM"));
+    process.on("SIGINT", handleSignal("SIGINT"));
+    logger.info("broker_ready", { ipcUrl: broker.ipcUrl });
+}
+const argvUrl = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (import.meta.url === argvUrl) {
+    main().catch((err) => {
+        console.error("broker_entry_fatal", err);
+        process.exit(1);
+    });
+}

package/dist/broker/ipc-server.d.ts

@@ -0,0 +1,65 @@
+import { type RawData, WebSocket } from "ws";
+import type { BrokerLogger } from "./logger.js";
+export interface IPCServerHandlers {
+    registerEndpoint(body: RegisterEndpointBody, ipcWs: WebSocket): Promise<RegisterEndpointResponse>;
+    heartbeatEndpoint(endpoint_id: string): Promise<void>;
+    unregisterEndpoint(endpoint_id: string): Promise<void>;
+    send(body: SendBody): Promise<SendResponse>;
+    reattachEndpoint(endpoint_id: string, plugin_pid: number, ipcWs: WebSocket): Promise<boolean>;
+}
+export interface RegisterEndpointBody {
+    agent_id: string;
+    plugin_pid: number;
+    kind: string;
+    started_at?: string;
+    workspace?: string;
+    tracking_ref?: string;
+    session_name?: string;
+    task_hint?: string;
+}
+export interface RegisterEndpointResponse {
+    endpoint_id: string;
+}
+export interface SendBody {
+    endpoint_id: string;
+    to: string;
+    content: string;
+    contentType?: string;
+    metadata?: Record<string, unknown>;
+    require_live?: boolean;
+}
+export interface SendResponse {
+    messageId: string;
+    status: string;
+}
+export declare class BrokerHttpError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export interface IPCServerOptions {
+    bearerToken: string;
+    handlers: IPCServerHandlers;
+    logger: BrokerLogger;
+    onChannelOpened?: (plugin_pid: number, ws: WebSocket) => void;
+    onChannelClosed?: (plugin_pid: number, ws: WebSocket) => void;
+}
+export interface RunningIPCServer {
+    ipcUrl: string;
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startIPCServer(opts: IPCServerOptions): Promise<RunningIPCServer>;
+export declare function pushToPlugin(ws: WebSocket, event: PushEvent): void;
+export type PushEvent = {
+    event: "message_received";
+    from: string;
+    content: string;
+    contentType: string;
+    metadata?: Record<string, unknown>;
+} | {
+    event: "ping";
+    ts: string;
+};
+export declare function parsePluginFrame(data: RawData): unknown;
+//# sourceMappingURL=ipc-server.d.ts.map

package/dist/broker/ipc-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ipc-server.d.ts","sourceRoot":"","sources":["../../src/broker/ipc-server.ts"],"names":[],"mappings":"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"}

package/dist/broker/ipc-server.js

@@ -0,0 +1,212 @@
+import { createServer } from "node:http";
+import { WebSocket, WebSocketServer } from "ws";
+import { PLUGIN_VERSION } from "../version.js";
+import { handleInitialize, IPC_PROTOCOL_VERSION, SERVER_CAPABILITIES, } from "./version-handshake.js";
+export class BrokerHttpError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = "BrokerHttpError";
+        this.status = status;
+        this.code = code;
+    }
+}
+export async function startIPCServer(opts) {
+    const { bearerToken, handlers, logger, onChannelOpened, onChannelClosed } = opts;
+    const http = createServer((req, res) => {
+        void routeHttp(req, res, bearerToken, handlers, logger);
+    });
+    const wss = new WebSocketServer({ noServer: true });
+    http.on("upgrade", (req, socket, head) => {
+        if (req.url !== "/v1/stream") {
+            socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        if (!authorizedRequest(req, bearerToken)) {
+            socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        const pid = readPluginPid(req);
+        if (pid === null) {
+            socket.write("HTTP/1.1 400 Bad Request\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => {
+            onChannelOpened?.(pid, ws);
+            ws.once("close", () => onChannelClosed?.(pid, ws));
+            wss.emit("connection", ws, req);
+        });
+    });
+    await new Promise((resolve, reject) => {
+        http.once("error", reject);
+        http.listen(0, "127.0.0.1", () => {
+            http.off("error", reject);
+            resolve();
+        });
+    });
+    const addr = http.address();
+    const ipcUrl = `http://127.0.0.1:${addr.port}`;
+    logger.info("ipc_server_listening", { ipcUrl });
+    return {
+        ipcUrl,
+        port: addr.port,
+        async close() {
+            await closeServer(http, wss);
+        },
+    };
+}
+async function routeHttp(req, res, bearerToken, handlers, logger) {
+    const url = req.url ?? "";
+    const method = req.method ?? "GET";
+    if (method === "GET" && url === "/health") {
+        sendJson(res, 200, {
+            ok: true,
+            version: PLUGIN_VERSION,
+            protocol_version: IPC_PROTOCOL_VERSION,
+            capabilities: SERVER_CAPABILITIES,
+        });
+        return;
+    }
+    if (!authorizedRequest(req, bearerToken)) {
+        sendJson(res, 401, { error: "unauthorized" });
+        return;
+    }
+    try {
+        if (method === "POST" && url === "/v1/initialize") {
+            const body = await readJson(req);
+            const result = handleInitialize(body);
+            sendJson(res, result.status, result.body);
+            return;
+        }
+        if (method === "POST" && url === "/v1/endpoint/register") {
+            const body = await readJson(req);
+            const out = await handlers.registerEndpoint(body, null);
+            sendJson(res, 200, out);
+            return;
+        }
+        const heartbeatMatch = /^\/v1\/endpoint\/([^/]+)\/heartbeat$/.exec(url);
+        if (method === "POST" && heartbeatMatch && heartbeatMatch[1]) {
+            await handlers.heartbeatEndpoint(decodeURIComponent(heartbeatMatch[1]));
+            sendJson(res, 200, { ok: true });
+            return;
+        }
+        const unregisterMatch = /^\/v1\/endpoint\/([^/]+)$/.exec(url);
+        if (method === "DELETE" && unregisterMatch && unregisterMatch[1]) {
+            await handlers.unregisterEndpoint(decodeURIComponent(unregisterMatch[1]));
+            sendJson(res, 200, { ok: true });
+            return;
+        }
+        if (method === "POST" && url === "/v1/send") {
+            const body = await readJson(req);
+            const out = await handlers.send(body);
+            sendJson(res, 200, out);
+            return;
+        }
+        sendJson(res, 404, { error: "not_found", path: url });
+    }
+    catch (err) {
+        if (err instanceof BrokerHttpError) {
+            logger.info("ipc_route_rejected", {
+                url,
+                method,
+                status: err.status,
+                code: err.code,
+                message: err.message,
+            });
+            sendJson(res, err.status, { error: err.code, message: err.message });
+            return;
+        }
+        logger.error("ipc_route_error", {
+            url,
+            method,
+            err: err instanceof Error ? err.message : String(err),
+        });
+        sendJson(res, 500, {
+            error: "internal_error",
+            message: err instanceof Error ? err.message : "unknown",
+        });
+    }
+}
+function authorizedRequest(req, bearerToken) {
+    const header = req.headers.authorization;
+    if (typeof header !== "string")
+        return false;
+    const trimmed = header.startsWith("Bearer ")
+        ? header.slice("Bearer ".length)
+        : header;
+    return constantTimeEquals(trimmed, bearerToken);
+}
+function readPluginPid(req) {
+    const raw = req.headers["x-plugin-pid"];
+    const str = Array.isArray(raw) ? raw[0] : raw;
+    if (!str)
+        return null;
+    const n = Number.parseInt(str, 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+}
+function constantTimeEquals(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let mismatch = 0;
+    for (let i = 0; i < a.length; i++) {
+        mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return mismatch === 0;
+}
+async function readJson(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        const MAX = 1 * 1024 * 1024;
+        req.on("data", (chunk) => {
+            const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            total += buf.length;
+            if (total > MAX) {
+                reject(new Error("request body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(buf);
+        });
+        req.on("end", () => {
+            try {
+                const raw = Buffer.concat(chunks).toString("utf8");
+                resolve(raw.length === 0 ? {} : JSON.parse(raw));
+            }
+            catch (err) {
+                reject(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        req.on("error", reject);
+    });
+}
+function sendJson(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json; charset=utf-8");
+    res.end(JSON.stringify(body));
+}
+async function closeServer(http, wss) {
+    await new Promise((resolve) => {
+        wss.close(() => resolve());
+    });
+    await new Promise((resolve, reject) => {
+        http.close((err) => (err ? reject(err) : resolve()));
+    });
+}
+export function pushToPlugin(ws, event) {
+    if (ws.readyState !== WebSocket.OPEN)
+        return;
+    ws.send(JSON.stringify(event));
+}
+export function parsePluginFrame(data) {
+    try {
+        return JSON.parse(data.toString());
+    }
+    catch {
+        return null;
+    }
+}

package/dist/broker/logger.d.ts

@@ -0,0 +1,10 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface BrokerLogger {
+    debug(msg: string, fields?: Record<string, unknown>): void;
+    info(msg: string, fields?: Record<string, unknown>): void;
+    warn(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+}
+export declare function createBrokerLogger(logDir: string): BrokerLogger;
+export declare function createNullLogger(): BrokerLogger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/broker/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/broker/logger.ts"],"names":[],"mappings":"AAaA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1D,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1D,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC5D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CA6B/D;AAGD,wBAAgB,gBAAgB,IAAI,YAAY,CAO/C"}

package/dist/broker/logger.js

@@ -0,0 +1,34 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+export function createBrokerLogger(logDir) {
+    mkdirSync(logDir, { recursive: true, mode: 0o700 });
+    const path = join(logDir, `broker-${process.pid}.log`);
+    const write = (level, msg, fields) => {
+        const line = JSON.stringify({
+            ts: new Date().toISOString(),
+            level,
+            pid: process.pid,
+            msg,
+            ...fields,
+        });
+        try {
+            appendFileSync(path, `${line}\n`);
+        }
+        catch {
+        }
+    };
+    return {
+        debug: (msg, fields) => write("debug", msg, fields),
+        info: (msg, fields) => write("info", msg, fields),
+        warn: (msg, fields) => write("warn", msg, fields),
+        error: (msg, fields) => write("error", msg, fields),
+    };
+}
+export function createNullLogger() {
+    return {
+        debug: () => { },
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+    };
+}

package/dist/broker/paths.d.ts

@@ -0,0 +1,10 @@
+export interface BrokerPathOptions {
+    userDataDir?: string;
+}
+export interface BrokerPaths {
+    discoveryFile: string;
+    discoveryDir: string;
+    logDir: string;
+}
+export declare function resolveBrokerPaths(principal: string, runtimeToken: string, opts?: BrokerPathOptions): BrokerPaths;
+//# sourceMappingURL=paths.d.ts.map

package/dist/broker/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/broker/paths.ts"],"names":[],"mappings":"AAgCA,MAAM,WAAW,iBAAiB;IAEhC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAE1B,aAAa,EAAE,MAAM,CAAC;IAEtB,YAAY,EAAE,MAAM,CAAC;IAErB,MAAM,EAAE,MAAM,CAAC;CAChB;AASD,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,IAAI,GAAE,iBAAsB,GAC3B,WAAW,CA8Bb"}

package/dist/broker/paths.js

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import envPaths from "env-paths";
+const AGENT_IDENTITY_HEX_LEN = 16;
+const ENV_PATHS_NAME = "masons-runtime-broker";
+export function resolveBrokerPaths(principal, runtimeToken, opts = {}) {
+    if (!principal) {
+        throw new Error("principal must be a non-empty string");
+    }
+    if (!runtimeToken) {
+        throw new Error("runtimeToken must be a non-empty string");
+    }
+    const userData = opts.userDataDir ?? envPaths(ENV_PATHS_NAME, { suffix: "" }).data;
+    const agentIdentity = createHash("sha256")
+        .update(runtimeToken, "utf8")
+        .digest("hex")
+        .slice(0, AGENT_IDENTITY_HEX_LEN);
+    const discoveryDir = join(userData, "runtime-broker", sanitizeSegment(principal), agentIdentity);
+    const logDir = join(userData, "runtime-broker", "log");
+    return {
+        discoveryFile: join(discoveryDir, "discovery.json"),
+        discoveryDir,
+        logDir,
+    };
+}
+function sanitizeSegment(segment) {
+    return segment.replace(/[^a-zA-Z0-9._-]/g, "_");
+}

package/dist/broker/routing-table.d.ts

@@ -0,0 +1,22 @@
+import type { BrokerEndpointEntry, EndpointRegistry } from "./endpoint-registry.js";
+export interface InboundMessageMeta {
+    target_endpoint_id?: string;
+    correlation_id?: string;
+}
+export type RouteResult = {
+    kind: "endpoint";
+    entry: BrokerEndpointEntry;
+    via: "target_endpoint_id" | "correlation_id";
+} | {
+    kind: "no_match";
+};
+export interface RoutingTableOptions {
+    onCollision?: (correlation_id: string, count: number) => void;
+}
+export declare class RoutingTable {
+    private readonly registry;
+    private readonly opts;
+    constructor(registry: EndpointRegistry, opts?: RoutingTableOptions);
+    route(meta: InboundMessageMeta): RouteResult;
+}
+//# sourceMappingURL=routing-table.d.ts.map

package/dist/broker/routing-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-table.d.ts","sourceRoot":"","sources":["../../src/broker/routing-table.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EACV,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,WAAW,GACnB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,GAAG,EAAE,oBAAoB,GAAG,gBAAgB,CAAC;CAC9C,GACD;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAEzB,MAAM,WAAW,mBAAmB;IAElC,WAAW,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/D;AAED,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADJ,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,GAAE,mBAAwB;IASjD,KAAK,CAAC,IAAI,EAAE,kBAAkB,GAAG,WAAW;CA6B7C"}

package/dist/broker/routing-table.js

@@ -0,0 +1,35 @@
+export class RoutingTable {
+    registry;
+    opts;
+    constructor(registry, opts = {}) {
+        this.registry = registry;
+        this.opts = opts;
+    }
+    route(meta) {
+        if (meta.target_endpoint_id) {
+            const entry = this.registry.get(meta.target_endpoint_id);
+            if (entry && entry.state === "active") {
+                return { kind: "endpoint", entry, via: "target_endpoint_id" };
+            }
+        }
+        if (meta.correlation_id) {
+            let matched;
+            let collisionCount = 0;
+            for (const entry of this.registry.list()) {
+                if (entry.correlation_ring.has(meta.correlation_id)) {
+                    collisionCount++;
+                    if (!matched) {
+                        matched = entry;
+                    }
+                }
+            }
+            if (collisionCount > 1 && this.opts.onCollision) {
+                this.opts.onCollision(meta.correlation_id, collisionCount);
+            }
+            if (matched) {
+                return { kind: "endpoint", entry: matched, via: "correlation_id" };
+            }
+        }
+        return { kind: "no_match" };
+    }
+}

package/dist/broker/runtime-endpoint-port.d.ts

@@ -0,0 +1,7 @@
+import type { RegisterRuntimeEndpointParams, RegisterRuntimeEndpointResponse } from "../runtime-endpoint-client.js";
+export interface RuntimeEndpointPort {
+    register(params: RegisterRuntimeEndpointParams): Promise<RegisterRuntimeEndpointResponse>;
+    heartbeat(endpointId: string): Promise<void>;
+    unregister(endpointId: string, asNodeId?: string): Promise<void>;
+}
+//# sourceMappingURL=runtime-endpoint-port.d.ts.map

package/dist/broker/runtime-endpoint-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-endpoint-port.d.ts","sourceRoot":"","sources":["../../src/broker/runtime-endpoint-port.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,6BAA6B,EAC7B,+BAA+B,EAChC,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CACN,MAAM,EAAE,6BAA6B,GACpC,OAAO,CAAC,+BAA+B,CAAC,CAAC;IAC5C,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAO7C,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClE"}

package/dist/broker/runtime-endpoint-port.js

@@ -0,0 +1 @@
+export {};

package/dist/broker/version-handshake.d.ts

@@ -0,0 +1,30 @@
+export declare const IPC_PROTOCOL_VERSION = "1.0";
+export interface IpcCapabilities {
+    endpoint_metadata_v1?: boolean;
+    remote_spawn_v1?: boolean;
+    undispatched_inbox_v1?: boolean;
+}
+export declare const SERVER_CAPABILITIES: Readonly<IpcCapabilities>;
+export interface InitializeRequestBody {
+    client_protocol_version: string;
+    client_kind: string;
+    client_version: string;
+    capabilities?: IpcCapabilities;
+}
+export interface InitializeResponseBody {
+    server_protocol_version: string;
+    server_capabilities: IpcCapabilities;
+    session_id: string;
+}
+export interface InitializeErrorBody {
+    error: "protocol_version_mismatch" | "bad_request";
+    message: string;
+}
+export declare function handleInitialize(req: InitializeRequestBody): {
+    status: 200;
+    body: InitializeResponseBody;
+} | {
+    status: 400;
+    body: InitializeErrorBody;
+};
+//# sourceMappingURL=version-handshake.d.ts.map

package/dist/broker/version-handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-handshake.d.ts","sourceRoot":"","sources":["../../src/broker/version-handshake.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,oBAAoB,QAAQ,CAAC;AAM1C,MAAM,WAAW,eAAe;IAE9B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B,eAAe,CAAC,EAAE,OAAO,CAAC;IAG1B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAGD,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,eAAe,CAIxD,CAAC;AAEH,MAAM,WAAW,qBAAqB;IAEpC,uBAAuB,EAAE,MAAM,CAAC;IAEhC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,eAAe,CAAC;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC,uBAAuB,EAAE,MAAM,CAAC;IAChC,mBAAmB,EAAE,eAAe,CAAC;IAErC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,2BAA2B,GAAG,aAAa,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,qBAAqB,GAExB;IAAE,MAAM,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,sBAAsB,CAAA;CAAE,GAC7C;IAAE,MAAM,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,CA0C7C"}

package/dist/broker/version-handshake.js

@@ -0,0 +1,47 @@
+import { randomUUID } from "node:crypto";
+export const IPC_PROTOCOL_VERSION = "1.0";
+export const SERVER_CAPABILITIES = Object.freeze({
+    endpoint_metadata_v1: true,
+    remote_spawn_v1: false,
+    undispatched_inbox_v1: false,
+});
+export function handleInitialize(req) {
+    if (typeof req.client_protocol_version !== "string") {
+        return {
+            status: 400,
+            body: {
+                error: "bad_request",
+                message: "client_protocol_version is required and must be a string",
+            },
+        };
+    }
+    if (typeof req.client_kind !== "string" || !req.client_kind) {
+        return {
+            status: 400,
+            body: {
+                error: "bad_request",
+                message: "client_kind is required and must be a non-empty string",
+            },
+        };
+    }
+    const clientMajor = req.client_protocol_version.split(".")[0];
+    const serverMajor = IPC_PROTOCOL_VERSION.split(".")[0];
+    if (clientMajor !== serverMajor) {
+        return {
+            status: 400,
+            body: {
+                error: "protocol_version_mismatch",
+                message: `broker IPC protocol major ${serverMajor} does not match client ` +
+                    `protocol major ${clientMajor}`,
+            },
+        };
+    }
+    return {
+        status: 200,
+        body: {
+            server_protocol_version: IPC_PROTOCOL_VERSION,
+            server_capabilities: { ...SERVER_CAPABILITIES },
+            session_id: randomUUID(),
+        },
+    };
+}