@masons/agent-network 0.3.9 → 0.4.0

package/dist/session-lifecycle.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 type { ConnectorClient } from "./connector-client.js";
+export type SessionStatus = "idle" | "creating" | "active" | "recreating" | "failed";
+export interface SessionState {
+    status: SessionStatus;
+    sessionId: string | null;
+    pendingRequestId: string | null;
+    retryCount: number;
+    /** Promise that resolves when session creation completes. Used for dedup. */
+    createPromise: Promise<string> | null;
+    /** Resolve function for the create promise. */
+    createResolve: ((sessionId: string) => void) | null;
+    /** Reject function for the create promise. */
+    createReject: ((err: Error) => void) | null;
+}
+export declare class SessionLifecycle {
+    private readonly client;
+    /** Primary map: MSTP address -> session state */
+    private readonly sessions;
+    /** Reverse index: sessionId -> MSTP address */
+    private readonly sessionToAddress;
+    /** Configurable timeout for tests */
+    private timeoutMs;
+    constructor(client: ConnectorClient);
+    /**
+     * 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: string): Promise<string>;
+    /**
+     * Get the active sessionId for an address, or null.
+     */
+    getSession(address: string): string | null;
+    /**
+     * Close the session for an address.
+     */
+    closeSession(address: string, reason?: string): void;
+    /**
+     * Register an inbound session (remote initiated).
+     */
+    registerInbound(sessionId: string, address: string): void;
+    /**
+     * Invalidate all sessions. Called on transport disconnect.
+     * Conversations are preserved but sessions are cleared.
+     */
+    invalidateAll(): void;
+    /**
+     * Reverse lookup: sessionId -> MSTP address.
+     */
+    getAddressBySessionId(sessionId: string): string | undefined;
+    /**
+     * Get all session entries (for listing conversations).
+     */
+    listSessions(): Array<{
+        address: string;
+        status: SessionStatus;
+        sessionId: string | null;
+    }>;
+    /**
+     * Remove a session entry entirely (for endConversation).
+     */
+    removeSession(address: string): void;
+    /** @internal Override timeout for tests. */
+    _setTimeoutForTesting(ms: number): void;
+    /** @internal Reset for test isolation. */
+    _resetForTesting(): void;
+    private subscribe;
+    private createNewSession;
+    private handleSessionCreated;
+    private handleSessionEnded;
+    private handleSessionError;
+}
+//# sourceMappingURL=session-lifecycle.d.ts.map

package/dist/session-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-lifecycle.d.ts","sourceRoot":"","sources":["../src/session-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAQ7D,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,QAAQ,CAAC;AAEb,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;IACtC,+CAA+C;IAC/C,aAAa,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACpD,8CAA8C;IAC9C,YAAY,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7C;AAaD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,iDAAiD;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,+CAA+C;IAC/C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6B;IAE9D,qCAAqC;IACrC,OAAO,CAAC,SAAS,CAA6B;gBAElC,MAAM,EAAE,eAAe;IASnC;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoB/C;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAQ1C;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAqBpD;;OAEG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAqBzD;;;OAGG;IACH,aAAa,IAAI,IAAI;IAqBrB;;OAEG;IACH,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI5D;;OAEG;IACH,YAAY,IAAI,KAAK,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,aAAa,CAAC;QACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,CAAC;IAgBF;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAcpC,4CAA4C;IAC5C,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIvC,0CAA0C;IAC1C,gBAAgB,IAAI,IAAI;IAmBxB,OAAO,CAAC,SAAS;IAsBjB,OAAO,CAAC,gBAAgB;IA+GxB,OAAO,CAAC,oBAAoB;IAuC5B,OAAO,CAAC,kBAAkB;IAiB1B,OAAO,CAAC,kBAAkB;CA0B3B"}

package/dist/session-lifecycle.js

@@ -0,0 +1,348 @@
+/**
+ * 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);
+        }
+    }
+}

package/dist/tools.d.ts

@@ -1,7 +1,7 @@
 /**
  * LLM tools — setup, connection, profile, and conversation tools.
  *
- * Registers 12 tools with OpenClaw's Plugin API so the LLM can
+ * Registers tools with OpenClaw's Plugin API so the LLM can
  * drive setup, profile completion, connection listing, connection
  * requests, request management, and real-time conversations,
  * guided by SKILL.md.
@@ -9,9 +9,14 @@
  * Two access patterns:
  * - **HTTP tools** (setup, connection): read config via `requirePlatformConfig()`,
  *   call Platform API via `platform-client.ts`.
- * - **WebSocket tools** (conversation): read runtime client via
- *   `requireConnectorClient()`, send/receive over the live connection.
+ * - **WebSocket tools** (conversation): use `requireConversationManager()` for
+ *   identity-based messaging. Session management is fully transparent.
  *
+ * Session Abstraction (#741):
+ * - `masons_send_message(to, content)` — sends via ConversationManager
+ * - `masons_end_conversation(contact)` — ends via ConversationManager
+ * - `masons_create_session` — DEPRECATED SHIM (one release cycle)
+ * - `masons_end_session` — DEPRECATED SHIM (one release cycle)
  */
 interface ToolContent {
     content: Array<{
@@ -32,8 +37,6 @@ interface ToolApi {
 }
 /** @internal Reset module state for test isolation. */
 export declare function _resetToolsForTesting(): void;
-/** @internal Override session creation timeout for tests. */
-export declare function _setSessionTimeoutForTesting(ms: number): void;
 /**
  * Register agent network tools with the OpenClaw Plugin API.
  *

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAqCH,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,UAAU,OAAO;IACf,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AAmBD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAI5C;AAED,6DAA6D;AAC7D,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE7D;AAwJD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAurBhD"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAmCH,UAAU,WAAW;IACnB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,CACP,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,WAAW,CAAC,CAAC;CAC3B;AAED,UAAU,OAAO;IACf,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACzE;AAeD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAwFD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAqsBhD"}