@kya-os/mcp-i-core 1.2.3-canary.7 → 1.3.0-canary.clientinfo.20251126003544

package/src/services/session-registration.service.ts

@@ -0,0 +1,251 @@
+/**
+ * Session Registration Service
+ *
+ * Registers MCP sessions with the AgentShield dashboard, enabling
+ * visibility into which MCP clients are connecting to agents.
+ *
+ * This is a fire-and-forget service - session registration should not
+ * block tool execution or affect the user experience.
+ *
+ * @package @kya-os/mcp-i-core
+ */
+
+import type {
+  RegisterSessionRequest,
+  RegisterSessionResponse,
+} from "@kya-os/contracts/agentshield-api";
+import {
+  registerSessionRequestSchema,
+  registerSessionResponseSchema,
+  AGENTSHIELD_ENDPOINTS,
+} from "@kya-os/contracts/agentshield-api";
+import type { FetchProvider } from "../providers/base.js";
+
+/**
+ * Configuration for the session registration service
+ */
+export interface SessionRegistrationServiceConfig {
+  /** Base URL for the AgentShield API (e.g., "https://kya.vouched.id") */
+  baseUrl: string;
+
+  /** API key for authentication */
+  apiKey: string;
+
+  /** Fetch provider for making HTTP requests (platform-agnostic) */
+  fetchProvider: FetchProvider;
+
+  /** Optional logger callback for diagnostics */
+  logger?: (message: string, data?: unknown) => void;
+
+  /** Timeout in milliseconds for the registration request (default: 5000) */
+  timeoutMs?: number;
+}
+
+/**
+ * Result of a session registration attempt
+ */
+export interface SessionRegistrationResult {
+  /** Whether registration was successful */
+  success: boolean;
+  /** Session ID that was registered */
+  sessionId: string;
+  /** Error message if registration failed */
+  error?: string;
+}
+
+/**
+ * Session Registration Service
+ *
+ * Registers MCP sessions with AgentShield for dashboard visibility.
+ * Designed to be non-blocking - failures are logged but don't throw.
+ */
+export class SessionRegistrationService {
+  private config: Required<
+    Omit<SessionRegistrationServiceConfig, "logger" | "timeoutMs">
+  > & {
+    logger: NonNullable<SessionRegistrationServiceConfig["logger"]>;
+    timeoutMs: number;
+  };
+
+  constructor(config: SessionRegistrationServiceConfig) {
+    this.config = {
+      baseUrl: config.baseUrl,
+      apiKey: config.apiKey,
+      fetchProvider: config.fetchProvider,
+      logger: config.logger || (() => {}),
+      timeoutMs: config.timeoutMs ?? 5000,
+    };
+  }
+
+  /**
+   * Register a session with AgentShield
+   *
+   * This is a fire-and-forget operation. Failures are logged but don't throw.
+   * The method returns quickly and doesn't block the caller.
+   *
+   * @param request - Session registration request data
+   * @returns Result indicating success or failure
+   */
+  async registerSession(
+    request: RegisterSessionRequest
+  ): Promise<SessionRegistrationResult> {
+    const sessionId = request.session_id;
+
+    try {
+      // Validate request
+      const validationResult = registerSessionRequestSchema.safeParse(request);
+      if (!validationResult.success) {
+        const errorMsg = `Invalid session registration request: ${validationResult.error.message}`;
+        this.config.logger("[SessionRegistration] Validation failed", {
+          sessionId,
+          error: errorMsg,
+        });
+        return { success: false, sessionId, error: errorMsg };
+      }
+
+      const url = `${this.config.baseUrl}${AGENTSHIELD_ENDPOINTS.SESSIONS}`;
+
+      this.config.logger("[SessionRegistration] Registering session", {
+        sessionId,
+        agentDid: request.agent_did,
+        clientName: request.client_info.name,
+        url,
+      });
+
+      // Make the request with timeout
+      const controller = new AbortController();
+      const timeoutId = setTimeout(
+        () => controller.abort(),
+        this.config.timeoutMs
+      );
+
+      try {
+        const response = await this.config.fetchProvider.fetch(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.config.apiKey}`,
+          },
+          body: JSON.stringify(request),
+          signal: controller.signal,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (!response.ok) {
+          // Log error but don't throw - this is fire-and-forget
+          const errorText = await response.text().catch(() => "Unknown error");
+          this.config.logger("[SessionRegistration] Registration failed", {
+            sessionId,
+            status: response.status,
+            error: errorText,
+          });
+          return {
+            success: false,
+            sessionId,
+            error: `HTTP ${response.status}: ${errorText}`,
+          };
+        }
+
+        // Parse response
+        const responseData = (await response.json()) as {
+          data?: RegisterSessionResponse;
+        } & RegisterSessionResponse;
+        const parseResult = registerSessionResponseSchema.safeParse(
+          responseData.data || responseData
+        );
+
+        if (!parseResult.success) {
+          this.config.logger(
+            "[SessionRegistration] Invalid response format",
+            {
+              sessionId,
+              response: responseData,
+            }
+          );
+          // Still consider it a success if we got a 200 OK
+          return { success: true, sessionId };
+        }
+
+        this.config.logger("[SessionRegistration] Session registered", {
+          sessionId,
+          registered: parseResult.data.registered,
+        });
+
+        return { success: true, sessionId };
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    } catch (error) {
+      // Handle abort/timeout
+      if (error instanceof Error && error.name === "AbortError") {
+        this.config.logger("[SessionRegistration] Request timed out", {
+          sessionId,
+          timeoutMs: this.config.timeoutMs,
+        });
+        return { success: false, sessionId, error: "Request timed out" };
+      }
+
+      // Log any other error
+      const errorMsg =
+        error instanceof Error ? error.message : "Unknown error";
+      this.config.logger("[SessionRegistration] Unexpected error", {
+        sessionId,
+        error: errorMsg,
+      });
+      return { success: false, sessionId, error: errorMsg };
+    }
+  }
+
+  /**
+   * Fire-and-forget session registration
+   *
+   * Starts registration in the background without waiting for completion.
+   * Useful when you want to register a session but not delay the response.
+   *
+   * @param request - Session registration request data
+   */
+  registerSessionAsync(request: RegisterSessionRequest): void {
+    // Start registration in background - don't await
+    this.registerSession(request).catch((error) => {
+      // This should never happen since registerSession catches all errors,
+      // but just in case
+      this.config.logger("[SessionRegistration] Background registration failed", {
+        sessionId: request.session_id,
+        error: error instanceof Error ? error.message : "Unknown error",
+      });
+    });
+  }
+}
+
+/**
+ * Create a session registration service from common runtime config
+ *
+ * Helper function to create the service from typical environment config.
+ */
+export function createSessionRegistrationService(options: {
+  apiUrl: string;
+  apiKey: string;
+  fetchProvider: FetchProvider;
+  logger?: (message: string, data?: unknown) => void;
+}): SessionRegistrationService | null {
+  // Validate required config
+  if (!options.apiUrl || !options.apiKey) {
+    options.logger?.(
+      "[SessionRegistration] Missing required config - session registration disabled",
+      {
+        hasApiUrl: !!options.apiUrl,
+        hasApiKey: !!options.apiKey,
+      }
+    );
+    return null;
+  }
+
+  return new SessionRegistrationService({
+    baseUrl: options.apiUrl,
+    apiKey: options.apiKey,
+    fetchProvider: options.fetchProvider,
+    logger: options.logger,
+  });
+}
+