@masons/agent-network 0.5.28 → 0.5.29

package/dist/broker/broker-daemon.d.ts

@@ -0,0 +1,24 @@
+import type { IncomingMessage } from "node:http";
+import type { WebSocket } from "ws";
+import type { ConnectorWS } from "./connector-ws.js";
+import type { BrokerLogger } from "./logger.js";
+import type { BrokerPaths } from "./paths.js";
+import type { RuntimeEndpointPort } from "./runtime-endpoint-port.js";
+export interface BrokerDaemonOptions {
+    paths: BrokerPaths;
+    asNodeId: string;
+    connector: ConnectorWS;
+    apiPort: RuntimeEndpointPort;
+    logger: BrokerLogger;
+}
+export interface RunningBroker {
+    bearerToken: string;
+    ipcUrl: string;
+    shutdown(reason: string): Promise<void>;
+    registrySize(): number;
+    _bindPluginChannel(plugin_pid: number, ws: WebSocket): void;
+    _unbindPluginChannel(plugin_pid: number): void;
+}
+export declare function startBrokerDaemon(opts: BrokerDaemonOptions): Promise<RunningBroker>;
+export declare function readPluginPidHeader(req: IncomingMessage): number | null;
+//# sourceMappingURL=broker-daemon.d.ts.map

package/dist/broker/broker-daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broker-daemon.d.ts","sourceRoot":"","sources":["../../src/broker/broker-daemon.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAiBrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,WAAW,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,WAAW,CAAC;IACvB,OAAO,EAAE,mBAAmB,CAAC;IAC7B,MAAM,EAAE,YAAY,CAAC;CAEtB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC,YAAY,IAAI,MAAM,CAAC;IAEvB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5D,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAChD;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,aAAa,CAAC,CA8TxB;AAGD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAMvE"}

package/dist/broker/broker-daemon.js

@@ -0,0 +1,229 @@
+import { randomUUID } from "node:crypto";
+import { deleteDiscoveryFile, mintBearerToken, writeDiscoveryFile, } from "./discovery-file.js";
+import { EndpointRegistry } from "./endpoint-registry.js";
+import { BrokerHttpError, pushToPlugin, startIPCServer, } from "./ipc-server.js";
+import { RoutingTable } from "./routing-table.js";
+export async function startBrokerDaemon(opts) {
+    const { paths, connector, apiPort, logger } = opts;
+    logger.info("connecting_to_connector");
+    await connector.connect();
+    logger.info("connector_connected");
+    const registry = new EndpointRegistry();
+    const router = new RoutingTable(registry, {
+        onCollision: (correlation_id, count) => {
+            logger.warn("correlation_id_collision", { correlation_id, count });
+        },
+    });
+    const channels = new Map();
+    const handlers = {
+        async registerEndpoint(body, _ipcWs) {
+            const boundWs = channels.get(body.plugin_pid);
+            if (!boundWs) {
+                throw new Error(`no open IPC channel for plugin_pid=${body.plugin_pid}; ` +
+                    "open WS /v1/stream with x-plugin-pid header first");
+            }
+            const apiResp = await apiPort.register({
+                runtime_kind: body.kind,
+                endpoint_nonce: randomUUID(),
+                display_label: body.session_name ??
+                    `${body.kind}-${String(body.plugin_pid).slice(-4)}`,
+                workspace: body.workspace
+                    ? { root: body.workspace, cwd: body.workspace }
+                    : undefined,
+                tracking_ref: body.tracking_ref,
+            });
+            registry.register({
+                endpoint_id: apiResp.endpoint_id,
+                agent_id: body.agent_id,
+                plugin_pid: body.plugin_pid,
+                ipc_ws: boundWs,
+                display_metadata: {
+                    session_name: body.session_name,
+                    kind: body.kind,
+                    started_at: body.started_at ?? new Date().toISOString(),
+                    workspace: body.workspace,
+                    tracking_ref: body.tracking_ref,
+                    task_hint: body.task_hint,
+                },
+            });
+            logger.info("endpoint_registered", {
+                endpoint_id: apiResp.endpoint_id,
+                plugin_pid: body.plugin_pid,
+                kind: body.kind,
+            });
+            return { endpoint_id: apiResp.endpoint_id };
+        },
+        async heartbeatEndpoint(endpoint_id) {
+            const entry = registry.get(endpoint_id);
+            if (!entry) {
+                throw new Error(`unknown endpoint_id: ${endpoint_id}`);
+            }
+            await apiPort.heartbeat(endpoint_id);
+        },
+        async unregisterEndpoint(endpoint_id) {
+            const entry = registry.get(endpoint_id);
+            if (!entry)
+                return;
+            registry.unregister(endpoint_id);
+            try {
+                await apiPort.unregister(endpoint_id);
+            }
+            catch (err) {
+                logger.warn("unregister_api_failed", {
+                    endpoint_id,
+                    err: err instanceof Error ? err.message : String(err),
+                });
+            }
+        },
+        async send(body) {
+            const entry = registry.get(body.endpoint_id);
+            if (!entry) {
+                throw new BrokerHttpError(404, "unknown_endpoint", `unknown endpoint_id: ${body.endpoint_id}`);
+            }
+            const incoming = body.metadata ?? {};
+            if ("correlation_id" in incoming) {
+                throw new BrokerHttpError(400, "correlation_id_forbidden", "broker is the sole issuer of correlation_id; do not pass it from the Plugin");
+            }
+            if ("target_endpoint_id" in incoming) {
+                throw new BrokerHttpError(400, "target_endpoint_id_forbidden", "target_endpoint_id is a reply-routing key, not an outbound input");
+            }
+            if ("source_endpoint_id" in incoming &&
+                incoming.source_endpoint_id !== body.endpoint_id) {
+                throw new BrokerHttpError(403, "source_endpoint_id_mismatch", "metadata.source_endpoint_id must equal body.endpoint_id");
+            }
+            const correlationId = randomUUID();
+            entry.correlation_ring.add(correlationId);
+            const metadata = {
+                ...incoming,
+                correlation_id: correlationId,
+                source_endpoint_id: body.endpoint_id,
+                require_live: body.require_live ?? false,
+            };
+            const ack = await connector.send(body.to, body.content, body.contentType ?? "text", metadata);
+            return {
+                messageId: ack.messageId,
+                status: ack.status,
+            };
+        },
+        async reattachEndpoint(endpoint_id, plugin_pid, ipcWs) {
+            const entry = registry.preconditionForReattach(endpoint_id, plugin_pid);
+            if (!entry)
+                return false;
+            entry.ipc_ws = ipcWs;
+            return true;
+        },
+    };
+    const bearerToken = mintBearerToken();
+    const ipc = await startIPCServer({
+        bearerToken,
+        handlers,
+        logger,
+        onChannelOpened: (plugin_pid, ws) => {
+            const prior = channels.get(plugin_pid);
+            if (prior && prior !== ws) {
+                try {
+                    prior.close(1000, "replaced");
+                }
+                catch {
+                }
+            }
+            channels.set(plugin_pid, ws);
+        },
+        onChannelClosed: (plugin_pid, ws) => {
+            if (channels.get(plugin_pid) === ws) {
+                channels.delete(plugin_pid);
+            }
+        },
+    });
+    connector.on("message_received", ({ payload }) => {
+        const meta = payload.metadata ?? {};
+        const decision = router.route({
+            target_endpoint_id: typeof meta.target_endpoint_id === "string"
+                ? meta.target_endpoint_id
+                : undefined,
+            correlation_id: typeof meta.correlation_id === "string"
+                ? meta.correlation_id
+                : undefined,
+        });
+        if (decision.kind === "endpoint") {
+            pushToPlugin(decision.entry.ipc_ws, {
+                event: "message_received",
+                from: payload.from,
+                content: payload.content,
+                contentType: payload.contentType,
+                metadata: meta,
+            });
+        }
+        else {
+            logger.info("inbound_no_match", { from: payload.from });
+        }
+    });
+    connector.on("delivery_pending", ({ payload }) => {
+        connector.ackDelivery(payload.upTo);
+    });
+    writeDiscoveryFile(paths.discoveryFile, {
+        version: 1,
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        ipcUrl: ipc.ipcUrl,
+        bearerToken,
+    });
+    logger.info("discovery_written", { path: paths.discoveryFile });
+    let shutdownStarted = false;
+    const shutdown = async (reason) => {
+        if (shutdownStarted)
+            return;
+        shutdownStarted = true;
+        logger.info("shutdown_begin", { reason });
+        const endpoints = registry.list();
+        await Promise.all(endpoints.map(async (entry) => {
+            try {
+                await apiPort.unregister(entry.endpoint_id);
+            }
+            catch {
+            }
+        }));
+        deleteDiscoveryFile(paths.discoveryFile);
+        try {
+            await ipc.close();
+        }
+        catch (err) {
+            logger.warn("ipc_close_error", {
+                err: err instanceof Error ? err.message : String(err),
+            });
+        }
+        try {
+            connector.disconnect();
+        }
+        catch {
+        }
+    };
+    return {
+        bearerToken,
+        ipcUrl: ipc.ipcUrl,
+        shutdown,
+        registrySize: () => registry.size(),
+        _bindPluginChannel: (plugin_pid, ws) => {
+            const prior = channels.get(plugin_pid);
+            if (prior) {
+                try {
+                    prior.close(1000, "replaced");
+                }
+                catch {
+                }
+            }
+            channels.set(plugin_pid, ws);
+        },
+        _unbindPluginChannel: (plugin_pid) => {
+            channels.delete(plugin_pid);
+        },
+    };
+}
+export function readPluginPidHeader(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;
+}

package/dist/broker/connector-ws.d.ts

@@ -0,0 +1,47 @@
+import { ConnectorError } from "../connector-client.js";
+import type { AddressedMessageEvent, DeliveryPendingEvent, DeliveryStatusEvent, SendAckEvent, StructuredErrorEvent } from "../types.js";
+export type ConnectorWSEvent = {
+    event: "message_received";
+    payload: AddressedMessageEvent;
+} | {
+    event: "send_ack";
+    payload: SendAckEvent;
+} | {
+    event: "delivery_pending";
+    payload: DeliveryPendingEvent;
+} | {
+    event: "delivery_status";
+    payload: DeliveryStatusEvent;
+} | {
+    event: "structured_error";
+    payload: StructuredErrorEvent;
+} | {
+    event: "connected";
+} | {
+    event: "disconnected";
+} | {
+    event: "error";
+    payload: Error;
+};
+type ListenerFor<E extends ConnectorWSEvent["event"]> = (e: Extract<ConnectorWSEvent, {
+    event: E;
+}>) => void;
+export interface ConnectorWSOptions {
+    url: string;
+    token: string;
+}
+export declare class ConnectorWS {
+    private readonly client;
+    private readonly bus;
+    constructor(opts: ConnectorWSOptions);
+    connect(): Promise<void>;
+    disconnect(): void;
+    send(to: string, content: string, contentType?: string, metadata?: Record<string, unknown>): Promise<SendAckEvent>;
+    ackDelivery(upTo: string): boolean;
+    on<E extends ConnectorWSEvent["event"]>(event: E, listener: ListenerFor<E>): this;
+    off<E extends ConnectorWSEvent["event"]>(event: E, listener: ListenerFor<E>): this;
+    _emitForTesting(e: ConnectorWSEvent): void;
+    private wireForwarders;
+}
+export { ConnectorError };
+//# sourceMappingURL=connector-ws.d.ts.map

package/dist/broker/connector-ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-ws.d.ts","sourceRoot":"","sources":["../../src/broker/connector-ws.ts"],"names":[],"mappings":"AAaA,OAAO,EAAmB,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,gBAAgB,GACxB;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAA;CAAE,GAC7D;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAC5C;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GAC5D;IAAE,KAAK,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,GAC1D;IAAE,KAAK,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,GAC5D;IAAE,KAAK,EAAE,WAAW,CAAA;CAAE,GACtB;IAAE,KAAK,EAAE,cAAc,CAAA;CAAE,GACzB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC;AAEvC,KAAK,WAAW,CAAC,CAAC,SAAS,gBAAgB,CAAC,OAAO,CAAC,IAAI,CACtD,CAAC,EAAE,OAAO,CAAC,gBAAgB,EAAE;IAAE,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC,KACvC,IAAI,CAAC;AAEV,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsB;gBAE9B,IAAI,EAAE,kBAAkB;IAMpC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAKxB,UAAU,IAAI,IAAI;IASlB,IAAI,CACF,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,WAAW,SAAS,EACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,YAAY,CAAC;IAKxB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIlC,EAAE,CAAC,CAAC,SAAS,gBAAgB,CAAC,OAAO,CAAC,EACpC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,GACvB,IAAI;IAKP,GAAG,CAAC,CAAC,SAAS,gBAAgB,CAAC,OAAO,CAAC,EACrC,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,GACvB,IAAI;IAMS,eAAe,CAAC,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAI1D,OAAO,CAAC,cAAc;CA0BvB;AAED,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/broker/connector-ws.js

@@ -0,0 +1,60 @@
+import { EventEmitter } from "node:events";
+import { ConnectorClient, ConnectorError } from "../connector-client.js";
+export class ConnectorWS {
+    client;
+    bus = new EventEmitter();
+    constructor(opts) {
+        this.client = new ConnectorClient(opts.url, opts.token);
+        this.wireForwarders();
+    }
+    connect() {
+        return this.client.connect();
+    }
+    disconnect() {
+        this.client.disconnect();
+    }
+    send(to, content, contentType = "text", metadata) {
+        return this.client.send(to, content, contentType, metadata);
+    }
+    ackDelivery(upTo) {
+        return this.client.ackDelivery(upTo);
+    }
+    on(event, listener) {
+        this.bus.on(event, listener);
+        return this;
+    }
+    off(event, listener) {
+        this.bus.off(event, listener);
+        return this;
+    }
+    _emitForTesting(e) {
+        this.bus.emit(e.event, e);
+    }
+    wireForwarders() {
+        this.client.on("message_received", (payload) => {
+            this.bus.emit("message_received", { event: "message_received", payload });
+        });
+        this.client.on("send_ack", (payload) => {
+            this.bus.emit("send_ack", { event: "send_ack", payload });
+        });
+        this.client.on("delivery_pending", (payload) => {
+            this.bus.emit("delivery_pending", { event: "delivery_pending", payload });
+        });
+        this.client.on("delivery_status", (payload) => {
+            this.bus.emit("delivery_status", { event: "delivery_status", payload });
+        });
+        this.client.on("structured_error", (payload) => {
+            this.bus.emit("structured_error", { event: "structured_error", payload });
+        });
+        this.client.on("connected", () => {
+            this.bus.emit("connected", { event: "connected" });
+        });
+        this.client.on("disconnected", () => {
+            this.bus.emit("disconnected", { event: "disconnected" });
+        });
+        this.client.on("error", (err) => {
+            this.bus.emit("error", { event: "error", payload: err });
+        });
+    }
+}
+export { ConnectorError };

package/dist/broker/correlation-ring.d.ts

@@ -0,0 +1,10 @@
+export declare class CorrelationRingBuffer {
+    private readonly capacity;
+    private readonly set;
+    private readonly order;
+    constructor(capacity?: number);
+    add(correlation_id: string): void;
+    has(correlation_id: string): boolean;
+    size(): number;
+}
+//# sourceMappingURL=correlation-ring.d.ts.map

package/dist/broker/correlation-ring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"correlation-ring.d.ts","sourceRoot":"","sources":["../../src/broker/correlation-ring.ts"],"names":[],"mappings":"AAaA,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;gBAErB,QAAQ,GAAE,MAAoB;IAU1C,GAAG,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAYjC,GAAG,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAIpC,IAAI,IAAI,MAAM;CAGf"}

package/dist/broker/correlation-ring.js

@@ -0,0 +1,32 @@
+const DEFAULT_CAP = 1024;
+export class CorrelationRingBuffer {
+    capacity;
+    set;
+    order;
+    constructor(capacity = DEFAULT_CAP) {
+        if (capacity <= 0) {
+            throw new Error(`capacity must be positive: ${capacity}`);
+        }
+        this.capacity = capacity;
+        this.set = new Set();
+        this.order = [];
+    }
+    add(correlation_id) {
+        if (this.set.has(correlation_id)) {
+            return;
+        }
+        if (this.order.length >= this.capacity) {
+            const oldest = this.order.shift();
+            if (oldest !== undefined)
+                this.set.delete(oldest);
+        }
+        this.set.add(correlation_id);
+        this.order.push(correlation_id);
+    }
+    has(correlation_id) {
+        return this.set.has(correlation_id);
+    }
+    size() {
+        return this.set.size;
+    }
+}

package/dist/broker/discovery-file.d.ts

@@ -0,0 +1,12 @@
+export interface DiscoveryRecord {
+    version: 1;
+    pid: number;
+    startedAt: string;
+    ipcUrl: string;
+    bearerToken: string;
+}
+export declare function mintBearerToken(): string;
+export declare function writeDiscoveryFile(path: string, record: DiscoveryRecord): void;
+export declare function readDiscoveryFile(path: string): DiscoveryRecord | null;
+export declare function deleteDiscoveryFile(path: string): void;
+//# sourceMappingURL=discovery-file.d.ts.map

package/dist/broker/discovery-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery-file.d.ts","sourceRoot":"","sources":["../../src/broker/discovery-file.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAGD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAMD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,eAAe,GACtB,IAAI,CA4BN;AAMD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAetE;AAGD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAOtD"}

package/dist/broker/discovery-file.js

@@ -0,0 +1,77 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+export function mintBearerToken() {
+    return randomBytes(32).toString("base64url");
+}
+export function writeDiscoveryFile(path, record) {
+    if (record.version !== 1) {
+        throw new Error(`unsupported discovery record version: ${record.version}`);
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.tmp.${process.pid}.${randomBytes(4).toString("hex")}`;
+    const payload = JSON.stringify(record, null, 2);
+    writeFileSync(tmp, payload, { mode: 0o600, encoding: "utf8" });
+    try {
+        chmodSync(tmp, 0o600);
+    }
+    catch {
+    }
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+        }
+        throw err;
+    }
+}
+export function readDiscoveryFile(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        if (isNodeErr(err, "ENOENT"))
+            return null;
+        throw err;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isDiscoveryRecord(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function deleteDiscoveryFile(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (err) {
+        if (isNodeErr(err, "ENOENT"))
+            return;
+        throw err;
+    }
+}
+function isDiscoveryRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (v.version === 1 &&
+        typeof v.pid === "number" &&
+        typeof v.startedAt === "string" &&
+        typeof v.ipcUrl === "string" &&
+        typeof v.bearerToken === "string");
+}
+function isNodeErr(err, code) {
+    return (typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        err.code === code);
+}

package/dist/broker/endpoint-registry.d.ts

@@ -0,0 +1,37 @@
+import type WebSocket from "ws";
+import { CorrelationRingBuffer } from "./correlation-ring.js";
+export interface DisplayMetadata {
+    session_name?: string;
+    kind: string;
+    started_at: string;
+    workspace?: string;
+    tracking_ref?: string;
+    task_hint?: string;
+}
+export interface BrokerEndpointEntry {
+    endpoint_id: string;
+    agent_id: string;
+    plugin_pid: number;
+    ipc_ws: WebSocket;
+    state: "active";
+    state_since: Date;
+    display_metadata: DisplayMetadata;
+    correlation_ring: CorrelationRingBuffer;
+}
+export interface RegisterArgs {
+    endpoint_id: string;
+    agent_id: string;
+    plugin_pid: number;
+    ipc_ws: WebSocket;
+    display_metadata: DisplayMetadata;
+}
+export declare class EndpointRegistry {
+    private readonly byId;
+    register(args: RegisterArgs): BrokerEndpointEntry;
+    get(endpoint_id: string): BrokerEndpointEntry | undefined;
+    unregister(endpoint_id: string): BrokerEndpointEntry | undefined;
+    preconditionForReattach(endpoint_id: string, plugin_pid: number): BrokerEndpointEntry | undefined;
+    list(): BrokerEndpointEntry[];
+    size(): number;
+}
+//# sourceMappingURL=endpoint-registry.d.ts.map

package/dist/broker/endpoint-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-registry.d.ts","sourceRoot":"","sources":["../../src/broker/endpoint-registry.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,SAAS,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,WAAW,EAAE,IAAI,CAAC;IAClB,gBAAgB,EAAE,eAAe,CAAC;IAClC,gBAAgB,EAAE,qBAAqB,CAAC;CACzC;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,CAAC;IAClB,gBAAgB,EAAE,eAAe,CAAC;CACnC;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0C;IAG/D,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,mBAAmB;IAkBjD,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAKzD,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAchE,uBAAuB,CACrB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GACjB,mBAAmB,GAAG,SAAS;IAQlC,IAAI,IAAI,mBAAmB,EAAE;IAK7B,IAAI,IAAI,MAAM;CAGf"}

package/dist/broker/endpoint-registry.js

@@ -0,0 +1,44 @@
+import { CorrelationRingBuffer } from "./correlation-ring.js";
+export class EndpointRegistry {
+    byId = new Map();
+    register(args) {
+        if (this.byId.has(args.endpoint_id)) {
+            throw new Error(`endpoint_id already registered: ${args.endpoint_id}`);
+        }
+        const entry = {
+            endpoint_id: args.endpoint_id,
+            agent_id: args.agent_id,
+            plugin_pid: args.plugin_pid,
+            ipc_ws: args.ipc_ws,
+            state: "active",
+            state_since: new Date(),
+            display_metadata: args.display_metadata,
+            correlation_ring: new CorrelationRingBuffer(),
+        };
+        this.byId.set(args.endpoint_id, entry);
+        return entry;
+    }
+    get(endpoint_id) {
+        return this.byId.get(endpoint_id);
+    }
+    unregister(endpoint_id) {
+        const entry = this.byId.get(endpoint_id);
+        if (entry)
+            this.byId.delete(endpoint_id);
+        return entry;
+    }
+    preconditionForReattach(endpoint_id, plugin_pid) {
+        const entry = this.byId.get(endpoint_id);
+        if (!entry)
+            return undefined;
+        if (entry.plugin_pid !== plugin_pid)
+            return undefined;
+        return entry;
+    }
+    list() {
+        return Array.from(this.byId.values());
+    }
+    size() {
+        return this.byId.size;
+    }
+}

package/dist/broker/entry.d.ts

@@ -0,0 +1,2 @@
+export declare function main(): Promise<void>;
+//# sourceMappingURL=entry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/broker/entry.ts"],"names":[],"mappings":"AAmGA,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAgD1C"}