@masons/agent-network 0.5.322 → 0.5.324

package/dist/session-lifecycle.js

@@ -1,348 +0,0 @@
-/**
- * Session Lifecycle — manages MSTP session state per contact.
- *
- * State machine: idle -> creating -> active -> recreating -> failed.
- * Internal key: MSTP address (not handle) — supports same handle on different Connectors.
- *
- * Responsibilities:
- * - Maps MSTP address to session state (sessionId, status, pending promise)
- * - Auto-creates sessions on demand via ensureSession()
- * - Deduplicates concurrent creates (second caller awaits first's promise)
- * - Registers inbound sessions from remote agents
- * - Invalidates all sessions on transport disconnect
- * - Subscribes to ConnectorClient events: session_created, session_error, session_ended, disconnected
- *
- * @see docs/openclaw/session-abstraction-system-design.md §6.1
- */
-import createDebug from "debug";
-const dbg = createDebug("agent-network:session-lifecycle");
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const SESSION_CREATE_TIMEOUT_MS = 15_000;
-const MAX_RETRY_COUNT = 1;
-// ---------------------------------------------------------------------------
-// SessionLifecycle
-// ---------------------------------------------------------------------------
-export class SessionLifecycle {
-    client;
-    /** Primary map: MSTP address -> session state */
-    sessions = new Map();
-    /** Reverse index: sessionId -> MSTP address */
-    sessionToAddress = new Map();
-    /** Configurable timeout for tests */
-    timeoutMs = SESSION_CREATE_TIMEOUT_MS;
-    constructor(client) {
-        this.client = client;
-        this.subscribe();
-    }
-    // -------------------------------------------------------------------------
-    // Public API
-    // -------------------------------------------------------------------------
-    /**
-     * Ensure an active session exists for the given address.
-     * Returns the sessionId. Creates a new session if none exists.
-     * Concurrent callers get the same promise (dedup).
-     */
-    ensureSession(address) {
-        const state = this.sessions.get(address);
-        // Active session — return immediately
-        if (state?.status === "active" && state.sessionId) {
-            return Promise.resolve(state.sessionId);
-        }
-        // Creating/recreating — dedup: return existing promise
-        if ((state?.status === "creating" || state?.status === "recreating") &&
-            state.createPromise) {
-            return state.createPromise;
-        }
-        // Idle, failed, or no state — create new session
-        return this.createNewSession(address, state?.retryCount ?? 0);
-    }
-    /**
-     * Get the active sessionId for an address, or null.
-     */
-    getSession(address) {
-        const state = this.sessions.get(address);
-        if (state?.status === "active" && state.sessionId) {
-            return state.sessionId;
-        }
-        return null;
-    }
-    /**
-     * Close the session for an address.
-     */
-    closeSession(address, reason) {
-        const state = this.sessions.get(address);
-        if (!state)
-            return;
-        if (state.sessionId) {
-            this.client.endSession(state.sessionId, reason);
-            this.sessionToAddress.delete(state.sessionId);
-        }
-        // Reject any pending create promise
-        if (state.createReject) {
-            state.createReject(new Error("Session closed by caller"));
-            state.createResolve = null;
-            state.createReject = null;
-            state.createPromise = null;
-        }
-        this.sessions.delete(address);
-        dbg("closeSession address=%s", address);
-    }
-    /**
-     * Register an inbound session (remote initiated).
-     */
-    registerInbound(sessionId, address) {
-        // If there's an existing session for this address, clean up
-        const existing = this.sessions.get(address);
-        if (existing?.sessionId && existing.sessionId !== sessionId) {
-            this.sessionToAddress.delete(existing.sessionId);
-        }
-        const state = {
-            status: "active",
-            sessionId,
-            pendingRequestId: null,
-            retryCount: 0,
-            createPromise: null,
-            createResolve: null,
-            createReject: null,
-        };
-        this.sessions.set(address, state);
-        this.sessionToAddress.set(sessionId, address);
-        dbg("registerInbound sessionId=%s address=%s", sessionId, address);
-    }
-    /**
-     * Invalidate all sessions. Called on transport disconnect.
-     * Conversations are preserved but sessions are cleared.
-     */
-    invalidateAll() {
-        const count = this.sessions.size;
-        for (const [address, state] of this.sessions) {
-            // Reject pending creates
-            if (state.createReject) {
-                state.createReject(new Error("Transport disconnected"));
-                state.createResolve = null;
-                state.createReject = null;
-                state.createPromise = null;
-            }
-            // Reset to idle — next send() will auto-create
-            state.status = "idle";
-            state.sessionId = null;
-            state.pendingRequestId = null;
-            state.retryCount = 0;
-            this.sessions.set(address, state);
-        }
-        this.sessionToAddress.clear();
-        dbg("invalidateAll cleared %d sessions", count);
-    }
-    /**
-     * Reverse lookup: sessionId -> MSTP address.
-     */
-    getAddressBySessionId(sessionId) {
-        return this.sessionToAddress.get(sessionId);
-    }
-    /**
-     * Get all session entries (for listing conversations).
-     */
-    listSessions() {
-        const entries = [];
-        for (const [address, state] of this.sessions) {
-            entries.push({
-                address,
-                status: state.status,
-                sessionId: state.sessionId,
-            });
-        }
-        return entries;
-    }
-    /**
-     * Remove a session entry entirely (for endConversation).
-     */
-    removeSession(address) {
-        const state = this.sessions.get(address);
-        if (state?.sessionId) {
-            this.sessionToAddress.delete(state.sessionId);
-        }
-        if (state?.createReject) {
-            state.createReject(new Error("Session removed"));
-            state.createResolve = null;
-            state.createReject = null;
-            state.createPromise = null;
-        }
-        this.sessions.delete(address);
-    }
-    /** @internal Override timeout for tests. */
-    _setTimeoutForTesting(ms) {
-        this.timeoutMs = ms;
-    }
-    /** @internal Reset for test isolation. */
-    _resetForTesting() {
-        // Reject pending creates silently
-        for (const state of this.sessions.values()) {
-            if (state.createReject) {
-                state.createReject(new Error("Reset for testing"));
-                state.createResolve = null;
-                state.createReject = null;
-                state.createPromise = null;
-            }
-        }
-        this.sessions.clear();
-        this.sessionToAddress.clear();
-        this.timeoutMs = SESSION_CREATE_TIMEOUT_MS;
-    }
-    // -------------------------------------------------------------------------
-    // Private
-    // -------------------------------------------------------------------------
-    subscribe() {
-        this.client.on("session_created", (event) => {
-            this.handleSessionCreated(event.sessionId, event.requestId, event.direction);
-        });
-        this.client.on("session_error", (sessionId, message) => {
-            this.handleSessionError(sessionId, message);
-        });
-        this.client.on("session_ended", (event) => {
-            this.handleSessionEnded(event.sessionId);
-        });
-        this.client.on("disconnected", () => {
-            this.invalidateAll();
-        });
-    }
-    createNewSession(address, previousRetryCount) {
-        const status = previousRetryCount > 0 ? "recreating" : "creating";
-        let createResolve = null;
-        let createReject = null;
-        const createPromise = new Promise((resolve, reject) => {
-            createResolve = resolve;
-            createReject = reject;
-        });
-        const { requestId, sent } = this.client.createSession(address);
-        if (!sent) {
-            const state = {
-                status: "failed",
-                sessionId: null,
-                pendingRequestId: null,
-                retryCount: previousRetryCount,
-                createPromise: null,
-                createResolve: null,
-                createReject: null,
-            };
-            this.sessions.set(address, state);
-            return Promise.reject(new Error("Failed to create session: transport unavailable"));
-        }
-        const state = {
-            status,
-            sessionId: null,
-            pendingRequestId: requestId,
-            retryCount: previousRetryCount,
-            createPromise,
-            createResolve,
-            createReject,
-        };
-        this.sessions.set(address, state);
-        // Timeout
-        const timer = setTimeout(() => {
-            const current = this.sessions.get(address);
-            if (current &&
-                current.pendingRequestId === requestId &&
-                (current.status === "creating" || current.status === "recreating")) {
-                dbg("session create timeout address=%s requestId=%s", address, requestId);
-                // Can we retry?
-                if (current.retryCount < MAX_RETRY_COUNT) {
-                    // Move to failed, then retry
-                    current.status = "failed";
-                    current.retryCount++;
-                    current.pendingRequestId = null;
-                    const retryResolve = current.createResolve;
-                    const retryReject = current.createReject;
-                    current.createPromise = null;
-                    current.createResolve = null;
-                    current.createReject = null;
-                    this.sessions.set(address, current);
-                    // Retry: create a new session, pipe result to original promise
-                    this.createNewSession(address, current.retryCount)
-                        .then((sessionId) => retryResolve?.(sessionId))
-                        .catch((err) => retryReject?.(err));
-                }
-                else {
-                    // Max retries exhausted
-                    current.status = "idle";
-                    current.pendingRequestId = null;
-                    current.retryCount = 0;
-                    if (current.createReject) {
-                        current.createReject(new Error("Session creation timed out. The remote agent may be unavailable."));
-                    }
-                    current.createPromise = null;
-                    current.createResolve = null;
-                    current.createReject = null;
-                    this.sessions.set(address, current);
-                }
-            }
-        }, this.timeoutMs);
-        // Attach cleanup to the promise to clear the timer if resolved early
-        createPromise
-            .then(() => clearTimeout(timer))
-            .catch(() => clearTimeout(timer));
-        dbg("createNewSession address=%s requestId=%s status=%s retry=%d", address, requestId, status, previousRetryCount);
-        return createPromise;
-    }
-    handleSessionCreated(sessionId, requestId, direction) {
-        // Outbound: match by requestId
-        if (direction === "outbound" && requestId) {
-            for (const [address, state] of this.sessions) {
-                if (state.pendingRequestId === requestId &&
-                    (state.status === "creating" || state.status === "recreating")) {
-                    state.status = "active";
-                    state.sessionId = sessionId;
-                    state.pendingRequestId = null;
-                    this.sessionToAddress.set(sessionId, address);
-                    if (state.createResolve) {
-                        state.createResolve(sessionId);
-                    }
-                    state.createPromise = null;
-                    state.createResolve = null;
-                    state.createReject = null;
-                    dbg("session created (outbound) address=%s sessionId=%s", address, sessionId);
-                    return;
-                }
-            }
-        }
-        // Inbound sessions are registered externally via registerInbound()
-        // from the channel adapter (which has the metadata to derive the address).
-        // We don't handle inbound SESSION_CREATED here.
-    }
-    handleSessionEnded(sessionId) {
-        const address = this.sessionToAddress.get(sessionId);
-        if (!address)
-            return;
-        const state = this.sessions.get(address);
-        if (!state)
-            return;
-        // Only clear if this session is the current one
-        if (state.sessionId === sessionId) {
-            state.status = "idle";
-            state.sessionId = null;
-            dbg("session ended address=%s sessionId=%s", address, sessionId);
-        }
-        this.sessionToAddress.delete(sessionId);
-    }
-    handleSessionError(sessionId, message) {
-        const address = this.sessionToAddress.get(sessionId);
-        if (!address)
-            return;
-        const state = this.sessions.get(address);
-        if (!state)
-            return;
-        dbg("session error address=%s sessionId=%s message=%s", address, sessionId, message);
-        // Session error on active session — mark for auto-recreate on next send().
-        // Reset retryCount to 0: this is a new failure context (transport error),
-        // not a continuation of a creation timeout. The next ensureSession() gets
-        // a fresh retry budget.
-        if (state.status === "active") {
-            this.sessionToAddress.delete(sessionId);
-            state.status = "idle";
-            state.sessionId = null;
-            state.retryCount = 0;
-            dbg("auto-recreate queued address=%s", address);
-        }
-    }
-}