@masons/agent-network 0.5.29 → 0.5.31

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

@@ -1,24 +1,34 @@
 import type { IncomingMessage } from "node:http";
-import type { WebSocket } from "ws";
+import type { ClosedEndpointLookup } from "./closed-endpoint-lookup.js";
 import type { ConnectorWS } from "./connector-ws.js";
+import { type ControlEventDispatcher } from "./control-event-dispatcher.js";
+import { type EndpointState } from "./endpoint-state-machine.js";
 import type { BrokerLogger } from "./logger.js";
 import type { BrokerPaths } from "./paths.js";
+import { type BufferedMessage } from "./reconnecting-buffer.js";
 import type { RuntimeEndpointPort } from "./runtime-endpoint-port.js";
+import { type UndispatchedInbox } from "./undispatched-inbox.js";
 export interface BrokerDaemonOptions {
     paths: BrokerPaths;
     asNodeId: string;
     connector: ConnectorWS;
     apiPort: RuntimeEndpointPort;
     logger: BrokerLogger;
+    closedEndpointLookup?: ClosedEndpointLookup;
+    inboxCapacity?: number;
+    graceMs?: number;
+    livenessProbe?: (plugin_pid: number) => boolean;
 }
 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;
+    state(endpoint_id: string): EndpointState | undefined;
+    undispatchedInbox: UndispatchedInbox;
+    controlEventDispatcher: ControlEventDispatcher;
 }
 export declare function startBrokerDaemon(opts: BrokerDaemonOptions): Promise<RunningBroker>;
 export declare function readPluginPidHeader(req: IncomingMessage): number | null;
+export type { BufferedMessage };
 //# sourceMappingURL=broker-daemon.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"broker-daemon.d.ts","sourceRoot":"","sources":["../../src/broker/broker-daemon.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,+BAA+B,CAAC;AAQvC,OAAO,EAEL,KAAK,aAAa,EAEnB,MAAM,6BAA6B,CAAC;AAarC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EACL,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,yBAAyB,CAAC;AAEjC,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;IAGrB,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAE5C,aAAa,CAAC,EAAE,MAAM,CAAC;IAGvB,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,aAAa,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;CACjD;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;IAGvB,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAEtD,iBAAiB,EAAE,iBAAiB,CAAC;IAErC,sBAAsB,EAAE,sBAAsB,CAAC;CAChD;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,aAAa,CAAC,CAqnBxB;AAGD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAMvE;AAED,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/dist/broker/broker-daemon.js

@@ -1,10 +1,18 @@
 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 { isPluginAlive as defaultIsPluginAlive } from "./plugin-liveness.js";
+import { createReconnectingBufferManager, } from "./reconnecting-buffer.js";
 import { RoutingTable } from "./routing-table.js";
+import { createUndispatchedInbox, } from "./undispatched-inbox.js";
 export async function startBrokerDaemon(opts) {
-    const { paths, connector, apiPort, logger } = opts;
+    const { paths, asNodeId: _asNodeIdReservedForA3, connector, apiPort, logger, closedEndpointLookup, livenessProbe = defaultIsPluginAlive, } = opts;
+    const graceMs = opts.graceMs ?? DEFAULT_GRACE_MS;
+    void _asNodeIdReservedForA3;
     logger.info("connecting_to_connector");
     await connector.connect();
     logger.info("connector_connected");
@@ -14,12 +22,142 @@ export async function startBrokerDaemon(opts) {
             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 channels = new Map();
+    const wsEndpoints = new WeakMap();
+    const displacedWs = new WeakSet();
+    const emitTransition = (endpoint_id, state, reason) => {
+        void apiPort.transitionState(endpoint_id, {
+            state,
+            reason,
+            ts: new Date().toISOString(),
+        });
+    };
+    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);
+                    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(),
+                });
+            }
+            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",
+            },
+        };
+        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,
+        });
+        return { ok: true };
+    });
     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}; ` +
+                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({
@@ -46,6 +184,13 @@ export async function startBrokerDaemon(opts) {
                     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");
             logger.info("endpoint_registered", {
                 endpoint_id: apiResp.endpoint_id,
                 plugin_pid: body.plugin_pid,
@@ -56,7 +201,7 @@ export async function startBrokerDaemon(opts) {
         async heartbeatEndpoint(endpoint_id) {
             const entry = registry.get(endpoint_id);
             if (!entry) {
-                throw new Error(`unknown endpoint_id: ${endpoint_id}`);
+                throw new BrokerHttpError(404, "endpoint_unknown", `unknown endpoint_id: ${endpoint_id}`);
             }
             await apiPort.heartbeat(endpoint_id);
         },
@@ -64,22 +209,16 @@ export async function startBrokerDaemon(opts) {
             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),
-                });
-            }
+            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");
@@ -100,17 +239,64 @@ export async function startBrokerDaemon(opts) {
                 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,
-            };
+            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;
+        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()}`,
+                undispatched_id,
+                target_endpoint_id,
+            });
+            if (!result.ok) {
+                throw new BrokerHttpError(400, "dispatch_failed", result.detail ?? "unknown");
+            }
         },
     };
     const bearerToken = mintBearerToken();
@@ -121,6 +307,7 @@ export async function startBrokerDaemon(opts) {
         onChannelOpened: (plugin_pid, ws) => {
             const prior = channels.get(plugin_pid);
             if (prior && prior !== ws) {
+                displacedWs.add(prior);
                 try {
                     prior.close(1000, "replaced");
                 }
@@ -133,29 +320,94 @@ export async function startBrokerDaemon(opts) {
             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", ({ payload }) => {
+    connector.on("message_received", async ({ 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,
-        });
+        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") {
-            pushToPlugin(decision.entry.ipc_ws, {
-                event: "message_received",
+            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,
-                content: payload.content,
-                contentType: payload.contentType,
-                metadata: meta,
+                size: undispatchedInbox.size(),
+                capacity: undispatchedInbox.capacity(),
             });
         }
         else {
-            logger.info("inbound_no_match", { from: payload.from });
+            logger.info("undispatched_added", { id: undispatched.id, reason });
         }
     });
     connector.on("delivery_pending", ({ payload }) => {
@@ -175,6 +427,7 @@ export async function startBrokerDaemon(opts) {
             return;
         shutdownStarted = true;
         logger.info("shutdown_begin", { reason });
+        graceTimers.cancelAll();
         const endpoints = registry.list();
         await Promise.all(endpoints.map(async (entry) => {
             try {
@@ -203,20 +456,9 @@ export async function startBrokerDaemon(opts) {
         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);
-        },
+        state: (endpoint_id) => registry.get(endpoint_id)?.state,
+        undispatchedInbox,
+        controlEventDispatcher,
     };
 }
 export function readPluginPidHeader(req) {

package/dist/broker/closed-endpoint-lookup.d.ts

@@ -0,0 +1,25 @@
+import type { PlatformClientConfig } from "../platform-client.js";
+import { type OwnedRuntimeEndpointView } from "../runtime-endpoint-client.js";
+export interface ClosedEndpointInfo {
+    exists: true;
+    closed: boolean;
+    view: OwnedRuntimeEndpointView;
+}
+export interface UnknownEndpoint {
+    exists: false;
+}
+export type LookupResult = ClosedEndpointInfo | UnknownEndpoint;
+export interface ClosedEndpointLookup {
+    lookup(endpoint_id: string, asNodeId: string): Promise<LookupResult>;
+    invalidate(endpoint_id: string): void;
+    size(): number;
+}
+export interface ClosedEndpointLookupOptions {
+    cfg: PlatformClientConfig;
+    runtimeKey: string;
+    cacheSize?: number;
+    cacheTtlMs?: number;
+    fetcher?: (cfg: PlatformClientConfig, runtimeKey: string, endpointId: string, asNodeId: string) => Promise<OwnedRuntimeEndpointView>;
+}
+export declare function createClosedEndpointLookup(opts: ClosedEndpointLookupOptions): ClosedEndpointLookup;
+//# sourceMappingURL=closed-endpoint-lookup.d.ts.map

package/dist/broker/closed-endpoint-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"closed-endpoint-lookup.d.ts","sourceRoot":"","sources":["../../src/broker/closed-endpoint-lookup.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,kBAAkB;IAEjC,MAAM,EAAE,IAAI,CAAC;IAEb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,wBAAwB,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,KAAK,CAAC;CACf;AAED,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,eAAe,CAAC;AAEhE,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAIrE,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtC,IAAI,IAAI,MAAM,CAAC;CAChB;AAaD,MAAM,WAAW,2BAA2B;IAC1C,GAAG,EAAE,oBAAoB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IAEnB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,OAAO,CAAC,EAAE,CACR,GAAG,EAAE,oBAAoB,EACzB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACxC;AAED,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,2BAA2B,GAChC,oBAAoB,CA6DtB"}

package/dist/broker/closed-endpoint-lookup.js

@@ -0,0 +1,59 @@
+import { getOwnedRuntimeEndpoint, } from "../runtime-endpoint-client.js";
+const DEFAULT_CACHE_SIZE = 64;
+const DEFAULT_CACHE_TTL_MS = 5_000;
+export function createClosedEndpointLookup(opts) {
+    const cacheSize = opts.cacheSize ?? DEFAULT_CACHE_SIZE;
+    const ttl = opts.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    const fetcher = opts.fetcher ?? getOwnedRuntimeEndpoint;
+    const cache = new Map();
+    const evict = () => {
+        if (cache.size <= cacheSize)
+            return;
+        const oldest = cache.keys().next();
+        if (!oldest.done)
+            cache.delete(oldest.value);
+    };
+    return {
+        async lookup(endpoint_id, asNodeId) {
+            const now = Date.now();
+            const hit = cache.get(endpoint_id);
+            if (hit && hit.expires_at > now) {
+                cache.delete(endpoint_id);
+                cache.set(endpoint_id, hit);
+                return hit.result;
+            }
+            let result;
+            try {
+                const view = await fetcher(opts.cfg, opts.runtimeKey, endpoint_id, asNodeId);
+                result = {
+                    exists: true,
+                    closed: typeof view.retired_at === "string" && view.retired_at.length > 0,
+                    view,
+                };
+            }
+            catch (err) {
+                if (isPlatformApi404(err)) {
+                    result = { exists: false };
+                }
+                else {
+                    return { exists: false };
+                }
+            }
+            cache.set(endpoint_id, { result, expires_at: now + ttl });
+            evict();
+            return result;
+        },
+        invalidate(endpoint_id) {
+            cache.delete(endpoint_id);
+        },
+        size() {
+            return cache.size;
+        },
+    };
+}
+function isPlatformApi404(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const status = err.status;
+    return status === 404;
+}

package/dist/broker/control-event-dispatcher.d.ts

@@ -0,0 +1,20 @@
+import type { ControlEvent } from "./control-event-types.js";
+export declare const DEFAULT_IDEMPOTENCY_RING_SIZE = 1024;
+export type ControlEventOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    detail: string;
+};
+export type ControlEventHandler<E extends ControlEvent = ControlEvent> = (event: E) => Promise<ControlEventOutcome>;
+export interface ControlEventDispatcher {
+    on<E extends ControlEvent>(type: E["type"], handler: ControlEventHandler<E>): void;
+    dispatch(event: ControlEvent): Promise<ControlEventOutcome>;
+    ringSize(): number;
+    hasSeen(idempotency_key: string): boolean;
+}
+export interface ControlEventDispatcherOptions {
+    ringSize?: number;
+}
+export declare function createControlEventDispatcher(opts?: ControlEventDispatcherOptions): ControlEventDispatcher;
+//# sourceMappingURL=control-event-dispatcher.d.ts.map

package/dist/broker/control-event-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-event-dispatcher.d.ts","sourceRoot":"","sources":["../../src/broker/control-event-dispatcher.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD,MAAM,MAAM,mBAAmB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,IAAI,CACvE,KAAK,EAAE,CAAC,KACL,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAElC,MAAM,WAAW,sBAAsB;IAErC,EAAE,CAAC,CAAC,SAAS,YAAY,EACvB,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EACf,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC9B,IAAI,CAAC;IAKR,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAE5D,QAAQ,IAAI,MAAM,CAAC;IAEnB,OAAO,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3C;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,GAAE,6BAAkC,GACvC,sBAAsB,CAqDxB"}

package/dist/broker/control-event-dispatcher.js

@@ -0,0 +1,45 @@
+export const DEFAULT_IDEMPOTENCY_RING_SIZE = 1024;
+export function createControlEventDispatcher(opts = {}) {
+    const cap = opts.ringSize ?? DEFAULT_IDEMPOTENCY_RING_SIZE;
+    if (cap <= 0)
+        throw new Error(`ringSize must be positive: ${cap}`);
+    const seen = new Set();
+    const order = [];
+    const handlers = new Map();
+    return {
+        on(type, handler) {
+            handlers.set(type, handler);
+        },
+        async dispatch(event) {
+            if (seen.has(event.idempotency_key)) {
+                return { ok: true };
+            }
+            seen.add(event.idempotency_key);
+            order.push(event.idempotency_key);
+            if (order.length > cap) {
+                const oldest = order.shift();
+                if (oldest !== undefined)
+                    seen.delete(oldest);
+            }
+            const handler = handlers.get(event.type);
+            if (!handler) {
+                return { ok: false, detail: `no_handler:${event.type}` };
+            }
+            try {
+                return await handler(event);
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    detail: err instanceof Error ? err.message : String(err),
+                };
+            }
+        },
+        ringSize() {
+            return seen.size;
+        },
+        hasSeen(idempotency_key) {
+            return seen.has(idempotency_key);
+        },
+    };
+}

package/dist/broker/control-event-types.d.ts

@@ -0,0 +1,30 @@
+export type ControlEvent = DispatchUndispatchedEvent | SpawnRequestEvent | ForceUnregisterEvent;
+export interface DispatchUndispatchedEvent {
+    type: "dispatch_undispatched";
+    version: 1;
+    idempotency_key: string;
+    undispatched_id: string;
+    target_endpoint_id: string;
+}
+export interface SpawnRequestEvent {
+    type: "spawn_request";
+    version: 1;
+    idempotency_key: string;
+    request_id: string;
+    prompt: string;
+    runtime_kind: string;
+    origin: "passport-spawn";
+}
+export interface ForceUnregisterEvent {
+    type: "force_unregister";
+    version: 1;
+    idempotency_key: string;
+    endpoint_id: string;
+    reason: string;
+}
+export interface ControlAck {
+    request_id: string;
+    status: "ok" | "error";
+    detail?: string;
+}
+//# sourceMappingURL=control-event-types.d.ts.map