@masons/agent-network 0.5.322 → 0.5.323

package/dist/broker/broker-daemon.js

@@ -1,837 +0,0 @@
-import { spawn as spawnChild } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { createControlEventDispatcher, } from "./control-event-dispatcher.js";
-import { deleteDiscoveryFile, mintBearerToken, writeDiscoveryFile, } from "./discovery-file.js";
-import { EndpointRegistry } from "./endpoint-registry.js";
-import { DEFAULT_GRACE_MS, transition, } from "./endpoint-state-machine.js";
-import { createGraceTimerManager } from "./grace-timer.js";
-import { BrokerHttpError, pushToPlugin, startIPCServer, } from "./ipc-server.js";
-import { transitionPresence, } from "./network-presence.js";
-import { createNetworkPresenceEmitter, postNetworkPresenceChangedViaPort, } from "./network-presence-emitter.js";
-import { isPluginAlive as defaultIsPluginAlive } from "./plugin-liveness.js";
-import { createReceivedMessageCorrelationCache, DEFAULT_TTL_MS as DEFAULT_REPLY_CORRELATION_TTL_MS, } from "./received-message-correlation-cache.js";
-import { createReconnectingBufferManager, } from "./reconnecting-buffer.js";
-import { RoutingTable } from "./routing-table.js";
-import { createSpawnCorrelationManager, createSpawnRateLimiter, } from "./spawn-correlation.js";
-import { TASK_HINT_MAX_LENGTH, updateTaskHint } from "./task-hint-handler.js";
-import { createTransitionStateRetryQueue } from "./transition-state-retry-queue.js";
-import { CONTENT_PREVIEW_MAX_CODEPOINTS, truncateContentPreview, } from "./undispatched-changed-event-types.js";
-import { createUndispatchedChangedEmitter, postUndispatchedChangedViaPort, } from "./undispatched-emitter.js";
-import { createUndispatchedInbox, } from "./undispatched-inbox.js";
-export async function startBrokerDaemon(opts) {
-    const { paths, asNodeId: _asNodeIdReservedForA3, connector, apiPort, logger, closedEndpointLookup, livenessProbe = defaultIsPluginAlive, spawnDriverRegistry, spawnFn = spawnChild, servicesEventClientFactory, } = opts;
-    const graceMs = opts.graceMs ?? DEFAULT_GRACE_MS;
-    const presenceGraceMs = opts.presenceGraceMs;
-    const postControlAck = opts.postControlAck ??
-        (async () => {
-        });
-    void _asNodeIdReservedForA3;
-    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 undispatchedInbox = createUndispatchedInbox({
-        capacity: opts.inboxCapacity,
-    });
-    const reconnectingBuffers = createReconnectingBufferManager(paths.buffersDir);
-    const graceTimers = createGraceTimerManager();
-    const controlEventDispatcher = createControlEventDispatcher();
-    const spawnCorrelation = createSpawnCorrelationManager({
-        timeoutMs: opts.spawnCorrelationTimeoutMs,
-    });
-    const spawnRateLimiter = createSpawnRateLimiter({
-        maxInWindow: opts.spawnRateLimitMaxInWindow,
-        windowMs: opts.spawnRateLimitWindowMs,
-    });
-    const retryQueue = createTransitionStateRetryQueue({
-        capacity: opts.retryQueueCapacity,
-        onDrop: (dropped) => {
-            logger.warn("transition_state_retry_queue_overflow", {
-                endpoint_id: dropped.endpoint_id,
-                state: dropped.params.state,
-                reason: dropped.params.reason,
-                enqueued_at: dropped.enqueued_at,
-            });
-        },
-    });
-    const replyCorrelationCache = createReceivedMessageCorrelationCache({
-        ttlMs: opts.replyCorrelationTtlMs,
-        capPerEndpoint: opts.replyCorrelationCapPerEndpoint,
-    });
-    const replyCorrelationTtl = opts.replyCorrelationTtlMs ?? DEFAULT_REPLY_CORRELATION_TTL_MS;
-    const replyCorrelationSweepInterval = Math.max(Math.floor(replyCorrelationTtl / 4), 60_000);
-    const replyCorrelationSweepTimer = setInterval(() => {
-        const evicted = replyCorrelationCache.sweep();
-        if (evicted > 0) {
-            logger.info("reply_correlation_cache_sweep", { evicted });
-        }
-    }, replyCorrelationSweepInterval);
-    replyCorrelationSweepTimer.unref?.();
-    const undispatchedEmitter = createUndispatchedChangedEmitter(opts.undispatchedChangedPost ?? postUndispatchedChangedViaPort(apiPort), logger, {
-        capacity: opts.undispatchedChangedCapacity,
-        backoffInitialMs: opts.undispatchedChangedBackoffInitialMs,
-        backoffMaxMs: opts.undispatchedChangedBackoffMaxMs,
-        maxRetries: opts.undispatchedChangedMaxRetries,
-    });
-    const emitUndispatched = (event) => {
-        undispatchedEmitter.enqueue(event);
-    };
-    const networkPresenceEmitter = createNetworkPresenceEmitter(opts.networkPresenceChangedPost ??
-        postNetworkPresenceChangedViaPort(apiPort), logger, {
-        capacity: opts.networkPresenceChangedCapacity,
-        backoffInitialMs: opts.networkPresenceChangedBackoffInitialMs,
-        backoffMaxMs: opts.networkPresenceChangedBackoffMaxMs,
-        maxRetries: opts.networkPresenceChangedMaxRetries,
-    });
-    const emitNetworkPresence = (event) => {
-        networkPresenceEmitter.enqueue(event);
-    };
-    const recordInboundCorrelation = (endpoint_id, metadata) => {
-        const c = metadata && typeof metadata.correlation_id === "string"
-            ? metadata.correlation_id
-            : undefined;
-        if (!c)
-            return;
-        replyCorrelationCache.record(endpoint_id, c);
-    };
-    let networkPresence = "offline";
-    let presenceGraceTimer;
-    const applyPresenceTransition = (event) => {
-        const result = transitionPresence(networkPresence, event, {
-            graceMs: presenceGraceMs,
-        });
-        if (result.ignored)
-            return;
-        networkPresence = result.next;
-        for (const effect of result.effects) {
-            switch (effect.type) {
-                case "start_grace_timer":
-                    if (presenceGraceTimer)
-                        clearTimeout(presenceGraceTimer);
-                    presenceGraceTimer = setTimeout(() => {
-                        applyPresenceTransition({ type: "presence_grace_expired" });
-                    }, effect.deadline_ms);
-                    presenceGraceTimer.unref?.();
-                    break;
-                case "cancel_grace_timer":
-                    if (presenceGraceTimer) {
-                        clearTimeout(presenceGraceTimer);
-                        presenceGraceTimer = undefined;
-                    }
-                    break;
-                case "emit_presence":
-                    logger.info("network_presence_changed", {
-                        presence: effect.presence,
-                        reason: effect.reason,
-                    });
-                    emitNetworkPresence({
-                        type: "network_presence_changed",
-                        version: 1,
-                        state: effect.presence,
-                        ts: Date.now(),
-                        reason: effect.reason,
-                    });
-                    if (effect.presence === "online") {
-                        void retryQueue.flush(async (entry) => {
-                            await apiPort.transitionState(entry.endpoint_id, entry.params);
-                        });
-                    }
-                    break;
-            }
-        }
-    };
-    applyPresenceTransition({ type: "connector_connected" });
-    connector.on("connected", () => {
-        applyPresenceTransition({ type: "connector_connected" });
-    });
-    connector.on("disconnected", () => {
-        applyPresenceTransition({ type: "connector_disconnected" });
-    });
-    const channels = new Map();
-    const wsEndpoints = new WeakMap();
-    const displacedWs = new WeakSet();
-    const emitTransition = (endpoint_id, state, reason) => {
-        const params = {
-            state,
-            reason,
-            ts: new Date().toISOString(),
-        };
-        if (networkPresence === "online") {
-            void apiPort.transitionState(endpoint_id, params);
-            return;
-        }
-        const accepted = retryQueue.enqueue(endpoint_id, params);
-        logger.info("transition_state_deferred", {
-            endpoint_id,
-            state,
-            reason,
-            presence: networkPresence,
-            queued: accepted,
-            retry_queue_size: retryQueue.size(),
-        });
-    };
-    const handleTransition = (endpoint_id, event) => {
-        const entry = registry.get(endpoint_id);
-        if (!entry)
-            return;
-        const result = transition(entry.state, event, { graceMs });
-        if (result.ignored) {
-            logger.info("state_event_ignored", {
-                endpoint_id,
-                current: entry.state,
-                event,
-            });
-            return;
-        }
-        for (const effect of result.effects) {
-            switch (effect.type) {
-                case "start_grace_timer": {
-                    const deadline = new Date(Date.now() + effect.deadline_ms);
-                    registry.markReconnecting(endpoint_id, deadline);
-                    graceTimers.start(endpoint_id, effect.deadline_ms, () => {
-                        handleTransition(endpoint_id, { type: "grace_expired" });
-                    });
-                    break;
-                }
-                case "cancel_grace_timer":
-                    graceTimers.cancel(endpoint_id);
-                    break;
-                case "emit_state":
-                    emitTransition(endpoint_id, effect.state, effect.reason);
-                    break;
-                case "drain_buffer": {
-                    const buf = reconnectingBuffers.forEndpoint(endpoint_id);
-                    const drained = buf.drain();
-                    const e = registry.get(endpoint_id);
-                    if (e) {
-                        for (const msg of drained) {
-                            pushToPlugin(e.ipc_ws, {
-                                event: "message_received",
-                                from: msg.envelope.from,
-                                content: msg.envelope.content,
-                                contentType: msg.envelope.contentType,
-                                metadata: msg.envelope.metadata,
-                            });
-                        }
-                    }
-                    break;
-                }
-                case "delete_buffer":
-                    reconnectingBuffers.cleanup(endpoint_id);
-                    break;
-                case "remove_from_registry":
-                    registry.unregister(endpoint_id);
-                    replyCorrelationCache.forgetEndpoint(endpoint_id);
-                    void apiPort.unregister(endpoint_id).catch(() => {
-                    });
-                    break;
-            }
-        }
-    };
-    controlEventDispatcher.on("dispatch_undispatched", async (event) => {
-        const taken = undispatchedInbox.take(event.undispatched_id);
-        if (!taken) {
-            return {
-                ok: false,
-                detail: `unknown undispatched_id: ${event.undispatched_id}`,
-            };
-        }
-        const target = registry.get(event.target_endpoint_id);
-        if (!target) {
-            const readded = undispatchedInbox.tryAdd(taken);
-            if (!readded) {
-                logger.error("dispatch_reinsert_failed_at_capacity", {
-                    undispatched_id: event.undispatched_id,
-                    target_endpoint_id: event.target_endpoint_id,
-                    inbox_size: undispatchedInbox.size(),
-                    inbox_capacity: undispatchedInbox.capacity(),
-                });
-                emitUndispatched({
-                    type: "undispatched_changed",
-                    version: 1,
-                    action: "remove",
-                    undispatched_id: event.undispatched_id,
-                    remove_reason: "lost_at_capacity_during_redispatch_bounce",
-                });
-            }
-            return {
-                ok: false,
-                detail: `target endpoint not found: ${event.target_endpoint_id}`,
-            };
-        }
-        const stamped = {
-            event: "message_received",
-            from: taken.sender_address,
-            content: taken.content,
-            contentType: taken.content_type,
-            metadata: {
-                ...taken.metadata,
-                dispatched_from: event.undispatched_id,
-                dispatched_by: "passport",
-            },
-        };
-        recordInboundCorrelation(target.endpoint_id, stamped.metadata);
-        if (target.state === "active") {
-            pushToPlugin(target.ipc_ws, stamped);
-        }
-        else {
-            const buf = reconnectingBuffers.forEndpoint(target.endpoint_id);
-            buf.append({
-                id: randomUUID(),
-                arrived_at: new Date().toISOString(),
-                envelope: {
-                    from: taken.sender_address,
-                    content: taken.content,
-                    contentType: taken.content_type,
-                    metadata: stamped.metadata,
-                },
-            });
-        }
-        logger.info("undispatched_dispatched", {
-            undispatched_id: event.undispatched_id,
-            target_endpoint_id: event.target_endpoint_id,
-            target_state: target.state,
-        });
-        emitUndispatched({
-            type: "undispatched_changed",
-            version: 1,
-            action: "dispatch",
-            undispatched_id: event.undispatched_id,
-            dispatched_to_endpoint_id: event.target_endpoint_id,
-        });
-        return { ok: true };
-    });
-    controlEventDispatcher.on("spawn_request", async (event) => {
-        if (!spawnRateLimiter.tryConsume()) {
-            return {
-                ok: false,
-                detail: "spawn_rate_limited",
-            };
-        }
-        if (!spawnDriverRegistry) {
-            return {
-                ok: false,
-                detail: "spawn_driver_registry_not_configured",
-            };
-        }
-        const driver = spawnDriverRegistry.lookup(event.runtime_kind);
-        if (!driver) {
-            return {
-                ok: false,
-                detail: `runtime_kind_unsupported: ${event.runtime_kind}`,
-            };
-        }
-        const avail = await driver.isAvailable();
-        if (!avail.available) {
-            return {
-                ok: false,
-                detail: avail.reason ?? "driver_unavailable",
-            };
-        }
-        const cmd = driver.buildSpawnCommand({
-            prompt: event.prompt,
-            spawn_token: event.idempotency_key,
-        });
-        let child;
-        try {
-            child = spawnFn(cmd.binary, cmd.args, {
-                detached: true,
-                stdio: "ignore",
-                windowsHide: true,
-                env: { ...process.env, ...(cmd.env ?? {}) },
-                cwd: cmd.cwd,
-            });
-            child.unref();
-        }
-        catch (err) {
-            return {
-                ok: false,
-                detail: `spawn_failed: ${err instanceof Error ? err.message : String(err)}`,
-            };
-        }
-        spawnCorrelation.track(event.idempotency_key, () => {
-            logger.warn("spawn_correlation_timeout", {
-                spawn_token: event.idempotency_key,
-                runtime_kind: event.runtime_kind,
-            });
-            void postControlAck({
-                idempotency_key: event.idempotency_key,
-                status: "failed",
-                detail: "spawn_correlation_timeout",
-            });
-        });
-        logger.info("spawn_request_initiated", {
-            spawn_token: event.idempotency_key,
-            runtime_kind: event.runtime_kind,
-            pid: child.pid,
-        });
-        return { ok: true, ack_hint: "received" };
-    });
-    controlEventDispatcher.on("force_unregister", async (event) => {
-        const entry = registry.get(event.endpoint_id);
-        if (!entry) {
-            return { ok: true };
-        }
-        logger.info("force_unregister_received", {
-            endpoint_id: event.endpoint_id,
-            reason: event.reason,
-        });
-        handleTransition(event.endpoint_id, { type: "explicit_unregister" });
-        return { ok: true };
-    });
-    const handlers = {
-        async registerEndpoint(body, _ipcWs) {
-            const boundWs = channels.get(body.plugin_pid);
-            if (!boundWs) {
-                throw new BrokerHttpError(400, "ipc_channel_missing", `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,
-                },
-            });
-            let bound = wsEndpoints.get(boundWs);
-            if (!bound) {
-                bound = new Set();
-                wsEndpoints.set(boundWs, bound);
-            }
-            bound.add(apiResp.endpoint_id);
-            emitTransition(apiResp.endpoint_id, "active", "register");
-            if (typeof body.spawn_token === "string") {
-                const pending = spawnCorrelation.consume(body.spawn_token);
-                if (pending) {
-                    logger.info("endpoint_spawned_correlation_resolved", {
-                        endpoint_id: apiResp.endpoint_id,
-                        spawn_token: body.spawn_token,
-                    });
-                    void postControlAck({
-                        idempotency_key: pending.spawn_token,
-                        status: "applied",
-                    });
-                }
-                else {
-                    logger.warn("endpoint_register_unknown_spawn_token", {
-                        endpoint_id: apiResp.endpoint_id,
-                        spawn_token: body.spawn_token,
-                    });
-                }
-            }
-            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 BrokerHttpError(404, "endpoint_unknown", `unknown endpoint_id: ${endpoint_id}`);
-            }
-            await apiPort.heartbeat(endpoint_id);
-        },
-        async unregisterEndpoint(endpoint_id) {
-            const entry = registry.get(endpoint_id);
-            if (!entry)
-                return;
-            handleTransition(endpoint_id, { type: "explicit_unregister" });
-        },
-        async send(body) {
-            const entry = registry.get(body.endpoint_id);
-            if (!entry) {
-                throw new BrokerHttpError(404, "unknown_endpoint", `unknown endpoint_id: ${body.endpoint_id}`);
-            }
-            if (entry.state !== "active") {
-                throw new BrokerHttpError(409, "endpoint_not_active", `endpoint ${body.endpoint_id} is ${entry.state}; outbound send is only allowed from Active`);
-            }
-            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 inReplyTo = typeof incoming.in_reply_to === "string"
-                ? incoming.in_reply_to
-                : undefined;
-            let correlationId;
-            if (inReplyTo) {
-                const resolved = replyCorrelationCache.resolve(body.endpoint_id, inReplyTo);
-                if (resolved.ok) {
-                    correlationId = inReplyTo;
-                }
-                else {
-                    logger.warn("reply_aware_fallback", {
-                        endpoint_id: body.endpoint_id,
-                        in_reply_to: inReplyTo,
-                        reason: resolved.reason,
-                    });
-                    correlationId = randomUUID();
-                }
-            }
-            else {
-                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, _ipcWsHint) {
-            const ipcWs = channels.get(plugin_pid);
-            if (!ipcWs) {
-                throw new BrokerHttpError(400, "ipc_channel_missing", `no open IPC channel for plugin_pid=${plugin_pid}; open WS /v1/stream first`);
-            }
-            const status = registry.getReattachStatus(endpoint_id, plugin_pid);
-            if (!status.ok) {
-                if (status.reason === "endpoint_unknown") {
-                    throw new BrokerHttpError(404, "endpoint_unknown", `unknown endpoint_id: ${endpoint_id}`);
-                }
-                if (status.reason === "reattach_pid_mismatch") {
-                    throw new BrokerHttpError(403, "reattach_pid_mismatch", "plugin_pid does not match the registered endpoint");
-                }
-                throw new BrokerHttpError(409, "endpoint_not_reconnecting", "endpoint is currently active; reattach is only valid from reconnecting");
-            }
-            let bound = wsEndpoints.get(ipcWs);
-            if (!bound) {
-                bound = new Set();
-                wsEndpoints.set(ipcWs, bound);
-            }
-            bound.add(endpoint_id);
-            const buf = reconnectingBuffers.forEndpoint(endpoint_id);
-            const drained = buf.drain();
-            graceTimers.cancel(endpoint_id);
-            registry.markActive(endpoint_id, ipcWs);
-            for (const msg of drained) {
-                pushToPlugin(ipcWs, {
-                    event: "message_received",
-                    from: msg.envelope.from,
-                    content: msg.envelope.content,
-                    contentType: msg.envelope.contentType,
-                    metadata: msg.envelope.metadata,
-                });
-            }
-            emitTransition(endpoint_id, "active", "reattach");
-            logger.info("endpoint_reattached", {
-                endpoint_id,
-                plugin_pid,
-                reconnecting_buffer_count: drained.length,
-            });
-            return { restored: true, reconnecting_buffer_count: drained.length };
-        },
-        async listUndispatched() {
-            return undispatchedInbox.list();
-        },
-        async dispatch(undispatched_id, target_endpoint_id) {
-            const result = await controlEventDispatcher.dispatch({
-                type: "dispatch_undispatched",
-                version: 1,
-                idempotency_key: `local-${randomUUID()}`,
-                emitted_at: Date.now(),
-                undispatched_id,
-                target_endpoint_id,
-            });
-            if (!result.ok) {
-                throw new BrokerHttpError(400, "dispatch_failed", result.detail ?? "unknown");
-            }
-        },
-        async setTaskHint(body) {
-            const result = updateTaskHint({ registry }, {
-                endpoint_id: body.endpoint_id,
-                plugin_pid: body.plugin_pid,
-                task_hint: body.task_hint,
-            });
-            if (!result.ok) {
-                const status = result.code === "endpoint_unknown"
-                    ? 404
-                    : result.code === "ownership_mismatch"
-                        ? 403
-                        : 400;
-                throw new BrokerHttpError(status, result.code, result.message);
-            }
-            logger.info("task_hint_updated", {
-                endpoint_id: body.endpoint_id,
-                truncated: result.truncated,
-                length: result.effective.length,
-                max: TASK_HINT_MAX_LENGTH,
-            });
-        },
-    };
-    const bearerToken = mintBearerToken();
-    const ipc = await startIPCServer({
-        bearerToken,
-        handlers,
-        logger,
-        onChannelOpened: (plugin_pid, ws) => {
-            const prior = channels.get(plugin_pid);
-            if (prior && prior !== ws) {
-                displacedWs.add(prior);
-                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);
-            }
-            if (displacedWs.has(ws))
-                return;
-            const bound = wsEndpoints.get(ws);
-            if (!bound)
-                return;
-            const alive = livenessProbe(plugin_pid);
-            for (const endpoint_id of bound) {
-                handleTransition(endpoint_id, {
-                    type: "ipc_close",
-                    plugin_alive: alive,
-                });
-            }
-        },
-    });
-    connector.on("message_received", async ({ payload }) => {
-        const meta = payload.metadata ?? {};
-        const target_endpoint_id = typeof meta.target_endpoint_id === "string"
-            ? meta.target_endpoint_id
-            : undefined;
-        const correlation_id = typeof meta.correlation_id === "string" ? meta.correlation_id : undefined;
-        const decision = router.route({ target_endpoint_id, correlation_id });
-        if (decision.kind === "endpoint") {
-            recordInboundCorrelation(decision.entry.endpoint_id, meta);
-            if (decision.entry.state === "active") {
-                pushToPlugin(decision.entry.ipc_ws, {
-                    event: "message_received",
-                    from: payload.from,
-                    content: payload.content,
-                    contentType: payload.contentType,
-                    metadata: meta,
-                });
-            }
-            else {
-                const buf = reconnectingBuffers.forEndpoint(decision.entry.endpoint_id);
-                buf.append({
-                    id: randomUUID(),
-                    arrived_at: new Date().toISOString(),
-                    envelope: {
-                        from: payload.from,
-                        content: payload.content,
-                        contentType: payload.contentType,
-                        metadata: meta,
-                    },
-                });
-                logger.info("buffered_for_reconnecting_endpoint", {
-                    endpoint_id: decision.entry.endpoint_id,
-                    buffer_size: buf.size(),
-                });
-            }
-            return;
-        }
-        let reason = "unaddressed";
-        let originalTarget;
-        if (target_endpoint_id && closedEndpointLookup) {
-            try {
-                const result = await closedEndpointLookup.lookup(target_endpoint_id, opts.asNodeId);
-                if (result.exists && result.closed) {
-                    reason = "closed_session_continuation";
-                    originalTarget = target_endpoint_id;
-                }
-            }
-            catch (err) {
-                logger.warn("closed_lookup_failed", {
-                    target_endpoint_id,
-                    err: err instanceof Error ? err.message : String(err),
-                });
-            }
-        }
-        const undispatched = {
-            id: randomUUID(),
-            arrived_at: new Date().toISOString(),
-            sender_address: payload.from,
-            content: payload.content,
-            content_type: payload.contentType,
-            metadata: meta,
-            reason,
-            original_target_endpoint_id: originalTarget,
-            original_correlation_id: correlation_id,
-        };
-        const added = undispatchedInbox.tryAdd(undispatched);
-        if (!added) {
-            logger.warn("undispatched_inbox_at_capacity", {
-                from: payload.from,
-                size: undispatchedInbox.size(),
-                capacity: undispatchedInbox.capacity(),
-            });
-        }
-        else {
-            logger.info("undispatched_added", { id: undispatched.id, reason });
-            const wireReason = undispatched.reason === "unaddressed"
-                ? "no_target_endpoint"
-                : undispatched.reason;
-            emitUndispatched({
-                type: "undispatched_changed",
-                version: 1,
-                action: "add",
-                undispatched_id: undispatched.id,
-                sender_address: undispatched.sender_address,
-                content_preview: truncateContentPreview(undispatched.content, CONTENT_PREVIEW_MAX_CODEPOINTS),
-                reason: wireReason,
-                ...(undispatched.original_target_endpoint_id !== undefined && {
-                    target_endpoint_id_hint: undispatched.original_target_endpoint_id,
-                }),
-                ...(typeof correlation_id === "string" && {
-                    in_reply_to: correlation_id,
-                }),
-                arrived_at: Date.parse(undispatched.arrived_at),
-            });
-        }
-    });
-    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 servicesEventClient;
-    if (servicesEventClientFactory) {
-        servicesEventClient = servicesEventClientFactory({
-            dispatcher: controlEventDispatcher,
-            logger,
-        });
-        try {
-            await servicesEventClient.start();
-        }
-        catch (err) {
-            logger.warn("services_event_client_start_failed", {
-                err: err instanceof Error ? err.message : String(err),
-            });
-        }
-    }
-    let shutdownStarted = false;
-    const shutdown = async (reason) => {
-        if (shutdownStarted)
-            return;
-        shutdownStarted = true;
-        logger.info("shutdown_begin", { reason });
-        if (servicesEventClient) {
-            try {
-                await servicesEventClient.stop();
-            }
-            catch {
-            }
-        }
-        graceTimers.cancelAll();
-        spawnCorrelation.cancelAll();
-        if (presenceGraceTimer) {
-            clearTimeout(presenceGraceTimer);
-            presenceGraceTimer = undefined;
-        }
-        clearInterval(replyCorrelationSweepTimer);
-        if (retryQueue.size() > 0) {
-            logger.warn("retry_queue_dropped_on_shutdown", {
-                size: retryQueue.size(),
-                reason,
-            });
-        }
-        if (undispatchedEmitter.size() > 0) {
-            logger.warn("undispatched_changed_queue_dropped_on_shutdown", {
-                size: undispatchedEmitter.size(),
-                reason,
-            });
-        }
-        await undispatchedEmitter.shutdown();
-        if (networkPresenceEmitter.size() > 0) {
-            logger.warn("network_presence_changed_queue_dropped_on_shutdown", {
-                size: networkPresenceEmitter.size(),
-                reason,
-            });
-        }
-        await networkPresenceEmitter.shutdown();
-        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(),
-        state: (endpoint_id) => registry.get(endpoint_id)?.state,
-        undispatchedInbox,
-        controlEventDispatcher,
-        networkPresence: () => networkPresence,
-        pendingSpawnCount: () => spawnCorrelation.size(),
-        retryQueueSize: () => retryQueue.size(),
-        undispatchedChangedQueueSize: () => undispatchedEmitter.size(),
-        networkPresenceChangedQueueSize: () => networkPresenceEmitter.size(),
-        replyCorrelationCacheSize: (endpoint_id) => replyCorrelationCache.sizeForEndpoint(endpoint_id),
-    };
-}
-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;
-}