@vincentwei1021/synapse-openclaw-plugin 0.5.0

package/src/mcp-client.ts

@@ -0,0 +1,144 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+export type McpClientStatus = "disconnected" | "connecting" | "connected" | "reconnecting";
+
+export interface SynapseMcpClientOptions {
+  synapseUrl: string;
+  apiKey: string;
+  logger: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
+}
+
+/**
+ * Wraps @modelcontextprotocol/sdk Client with:
+ * - Lazy connection (connect on first callTool)
+ * - Auto-reconnect on session expiry (404)
+ * - Status tracking
+ * - Graceful disconnect
+ */
+export class SynapseMcpClient {
+  private client: Client | null = null;
+  private transport: StreamableHTTPClientTransport | null = null;
+  private _status: McpClientStatus = "disconnected";
+  private readonly opts: SynapseMcpClientOptions;
+
+  constructor(opts: SynapseMcpClientOptions) {
+    this.opts = opts;
+  }
+
+  get status(): McpClientStatus {
+    return this._status;
+  }
+
+  /** Establish MCP connection. Called lazily on first callTool. */
+  async connect(): Promise<void> {
+    if (this._status === "connected" && this.client) return;
+
+    this._status = "connecting";
+    try {
+      this.transport = new StreamableHTTPClientTransport(
+        new URL("/api/mcp", this.opts.synapseUrl),
+        {
+          requestInit: {
+            headers: {
+              Authorization: `Bearer ${this.opts.apiKey}`,
+            },
+          },
+        }
+      );
+
+      this.client = new Client({
+        name: "openclaw-synapse",
+        version: "0.1.0",
+      });
+
+      await this.client.connect(this.transport);
+      this._status = "connected";
+      this.opts.logger.info("MCP connection established");
+    } catch (err) {
+      this._status = "disconnected";
+      await this.cleanupConnection();
+      throw err;
+    }
+  }
+
+  /**
+   * Call a Synapse MCP tool. Handles lazy connection and auto-reconnect.
+   * Returns parsed JSON from the first text content block.
+   */
+  async callTool(name: string, args: Record<string, unknown> = {}): Promise<unknown> {
+    // Lazy connect
+    if (!this.client || this._status !== "connected") {
+      await this.connect();
+    }
+
+    try {
+      return await this._doCallTool(name, args);
+    } catch (err: unknown) {
+      // Session expired (404) or connection lost — reconnect and retry once
+      if (this.isSessionExpiredError(err)) {
+        this.opts.logger.warn("MCP session expired, reconnecting...");
+        this._status = "reconnecting";
+        await this.cleanupConnection();
+        await this.connect();
+        return await this._doCallTool(name, args);
+      }
+      throw err;
+    }
+  }
+
+  /** Graceful disconnect. */
+  async disconnect(): Promise<void> {
+    await this.cleanupConnection();
+    this._status = "disconnected";
+    this.opts.logger.info("MCP connection closed");
+  }
+
+  private async cleanupConnection(): Promise<void> {
+    if (this.client) {
+      try {
+        await this.client.close();
+      } catch {
+        // Ignore close errors during cleanup
+      }
+    }
+
+    this.client = null;
+    this.transport = null;
+  }
+
+  private async _doCallTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+    if (!this.client) throw new Error("MCP client not connected");
+
+    const result = await this.client.callTool({ name, arguments: args });
+
+    if (result.isError) {
+      const errorText = (result.content as Array<{ type: string; text?: string }>)
+        .filter((c) => c.type === "text")
+        .map((c) => c.text)
+        .join("\n");
+      throw new Error(`Synapse MCP tool error (${name}): ${errorText}`);
+    }
+
+    // Parse first text content block as JSON
+    const textContent = (result.content as Array<{ type: string; text?: string }>).find(
+      (c) => c.type === "text"
+    );
+    if (!textContent?.text) return null;
+
+    try {
+      return JSON.parse(textContent.text);
+    } catch {
+      // Return raw text if not valid JSON
+      return textContent.text;
+    }
+  }
+
+  private isSessionExpiredError(err: unknown): boolean {
+    if (err instanceof Error) {
+      const msg = err.message.toLowerCase();
+      return msg.includes("404") || msg.includes("session expired") || msg.includes("session not found");
+    }
+    return false;
+  }
+}

package/src/sse-listener.test.ts

@@ -0,0 +1,150 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { SynapseSseListener } from "./sse-listener.js";
+
+function createLogger() {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  };
+}
+
+function createSseResponse(chunks: string[]) {
+  const encoder = new TextEncoder();
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const chunk of chunks) {
+        controller.enqueue(encoder.encode(chunk));
+      }
+      controller.close();
+    },
+  });
+
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": "text/event-stream" },
+  });
+}
+
+async function flushMicrotasks() {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe("SynapseSseListener", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it("parses SSE data events and forwards them to onEvent", async () => {
+    const logger = createLogger();
+    const onEvent = vi.fn();
+    const onReconnect = vi.fn().mockResolvedValue(undefined);
+
+    const fetchMock = vi.fn().mockResolvedValue(
+      createSseResponse([
+        ": heartbeat\n\n",
+        "data: {\"type\":\"new_notification\",\"notificationUuid\":\"notification-1\"}\n\n",
+      ]),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const listener = new SynapseSseListener({
+      synapseUrl: "https://synapse.example.com/",
+      apiKey: "syn_test_key",
+      onEvent,
+      onReconnect,
+      logger,
+    });
+
+    await listener.connect();
+    await flushMicrotasks();
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      "https://synapse.example.com/api/events/notifications",
+      expect.objectContaining({
+        headers: {
+          Authorization: "Bearer syn_test_key",
+          Accept: "text/event-stream",
+        },
+      }),
+    );
+    expect(onEvent).toHaveBeenCalledWith({
+      type: "new_notification",
+      notificationUuid: "notification-1",
+    });
+    expect(listener.status).toBe("reconnecting");
+    expect(logger.info).toHaveBeenCalledWith("[Synapse] SSE connection established");
+
+    listener.disconnect();
+  });
+
+  it("reconnects after an initial fetch failure and runs onReconnect once connected", async () => {
+    const logger = createLogger();
+    const onEvent = vi.fn();
+    const onReconnect = vi.fn().mockResolvedValue(undefined);
+
+    const fetchMock = vi.fn()
+      .mockRejectedValueOnce(new Error("network down"))
+      .mockResolvedValueOnce(createSseResponse(["data: {\"type\":\"count_update\",\"unreadCount\":2}\n\n"]));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const listener = new SynapseSseListener({
+      synapseUrl: "https://synapse.example.com",
+      apiKey: "syn_test_key",
+      onEvent,
+      onReconnect,
+      logger,
+    });
+
+    await listener.connect();
+    expect(listener.status).toBe("reconnecting");
+    expect(logger.error).toHaveBeenCalledWith(expect.stringContaining("SSE connection failed"));
+    expect(logger.info).toHaveBeenCalledWith("SSE reconnecting in 1000ms");
+
+    await vi.advanceTimersByTimeAsync(1000);
+    await flushMicrotasks();
+
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(onReconnect).toHaveBeenCalledTimes(1);
+    expect(onEvent).toHaveBeenCalledWith({
+      type: "count_update",
+      unreadCount: 2,
+    });
+
+    listener.disconnect();
+  });
+
+  it("warns on malformed JSON payloads without crashing the listener", async () => {
+    const logger = createLogger();
+    const onEvent = vi.fn();
+    const onReconnect = vi.fn().mockResolvedValue(undefined);
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(createSseResponse(["data: not-json\n\n"])),
+    );
+
+    const listener = new SynapseSseListener({
+      synapseUrl: "https://synapse.example.com",
+      apiKey: "syn_test_key",
+      onEvent,
+      onReconnect,
+      logger,
+    });
+
+    await listener.connect();
+    await flushMicrotasks();
+
+    expect(onEvent).not.toHaveBeenCalled();
+    expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining("SSE JSON parse error"));
+
+    listener.disconnect();
+  });
+});

package/src/sse-listener.ts

@@ -0,0 +1,184 @@
+export type SseListenerStatus = "connected" | "disconnected" | "reconnecting";
+
+export interface SseNotificationEvent {
+  type: string; // "new_notification"
+  notificationUuid?: string;
+  notificationType?: string; // "task_assigned", "mentioned", etc.
+  unreadCount?: number;
+  [key: string]: unknown;
+}
+
+export interface SynapseSseListenerOptions {
+  synapseUrl: string;
+  apiKey: string;
+  onEvent: (event: SseNotificationEvent) => void;
+  onReconnect: () => Promise<void>;
+  logger: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
+}
+
+const INITIAL_DELAY_MS = 1_000;
+const MAX_DELAY_MS = 30_000;
+
+export class SynapseSseListener {
+  private readonly opts: SynapseSseListenerOptions;
+  private _status: SseListenerStatus = "disconnected";
+  private abortController: AbortController | null = null;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectDelay = INITIAL_DELAY_MS;
+
+  constructor(opts: SynapseSseListenerOptions) {
+    this.opts = opts;
+  }
+
+  get status(): SseListenerStatus {
+    return this._status;
+  }
+
+  /** Start the SSE connection. Resolves once the first bytes arrive (or rejects on immediate failure). */
+  async connect(): Promise<void> {
+    this.clearReconnectTimer();
+
+    const abortController = new AbortController();
+    this.abortController = abortController;
+
+    const url = `${this.opts.synapseUrl.replace(/\/$/, "")}/api/events/notifications`;
+
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        headers: {
+          Authorization: `Bearer ${this.opts.apiKey}`,
+          Accept: "text/event-stream",
+        },
+        signal: abortController.signal,
+      });
+    } catch (err) {
+      if (abortController.signal.aborted) return; // intentional disconnect
+      this.opts.logger.error(`SSE connection failed: ${err}`);
+      this.scheduleReconnect();
+      return;
+    }
+
+    if (!response.ok) {
+      this.opts.logger.error(`SSE endpoint returned ${response.status}`);
+      this.scheduleReconnect();
+      return;
+    }
+
+    if (!response.body) {
+      this.opts.logger.error("SSE response has no body");
+      this.scheduleReconnect();
+      return;
+    }
+
+    // Connection succeeded — reset backoff
+    const isReconnect = this._status === "reconnecting";
+    this._status = "connected";
+    this.reconnectDelay = INITIAL_DELAY_MS;
+    this.opts.logger.info("[Synapse] SSE connection established");
+
+    if (isReconnect) {
+      // Fire onReconnect callback so the caller can back-fill missed notifications
+      try {
+        await this.opts.onReconnect();
+      } catch (err) {
+        this.opts.logger.warn(`onReconnect callback error: ${err}`);
+      }
+    }
+
+    // Read the stream
+    this.consumeStream(response.body, abortController.signal);
+  }
+
+  /** Gracefully close the SSE connection. */
+  disconnect(): void {
+    this.clearReconnectTimer();
+    if (this.abortController) {
+      this.abortController.abort();
+      this.abortController = null;
+    }
+    this._status = "disconnected";
+    this.opts.logger.info("SSE connection closed");
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  private async consumeStream(body: ReadableStream<Uint8Array>, signal: AbortSignal): Promise<void> {
+    const decoder = new TextDecoder();
+    const reader = body.getReader();
+    let buffer = "";
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done || signal.aborted) break;
+
+        buffer += decoder.decode(value, { stream: true });
+
+        // SSE messages are delimited by double newlines
+        let boundary: number;
+        while ((boundary = buffer.indexOf("\n\n")) !== -1) {
+          const raw = buffer.slice(0, boundary);
+          buffer = buffer.slice(boundary + 2);
+          this.processMessage(raw);
+        }
+      }
+    } catch (err) {
+      if (signal.aborted) return; // intentional disconnect
+      this.opts.logger.warn(`SSE stream error: ${err}`);
+    } finally {
+      try {
+        reader.releaseLock();
+      } catch {
+        // already released
+      }
+    }
+
+    // Stream ended unexpectedly — reconnect unless we were intentionally disconnected
+    if (!signal.aborted) {
+      this.opts.logger.warn("SSE stream ended, scheduling reconnect");
+      this.scheduleReconnect();
+    }
+  }
+
+  private processMessage(raw: string): void {
+    for (const line of raw.split("\n")) {
+      // Comment lines (heartbeats) — ignore
+      if (line.startsWith(":")) continue;
+
+      // Data lines
+      if (line.startsWith("data: ")) {
+        const jsonStr = line.slice(6);
+        try {
+          const event: SseNotificationEvent = JSON.parse(jsonStr);
+          this.opts.onEvent(event);
+        } catch (err) {
+          this.opts.logger.warn(`SSE JSON parse error: ${err} — raw: ${jsonStr}`);
+        }
+      }
+    }
+  }
+
+  private scheduleReconnect(): void {
+    this.clearReconnectTimer();
+    this._status = "reconnecting";
+
+    this.opts.logger.info(`SSE reconnecting in ${this.reconnectDelay}ms`);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect();
+    }, this.reconnectDelay);
+
+    // Exponential backoff: 1s → 2s → 4s → 8s → 16s → 30s
+    this.reconnectDelay = Math.min(this.reconnectDelay * 2, MAX_DELAY_MS);
+  }
+
+  private clearReconnectTimer(): void {
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+}