@vincentwei1021/synapse-openclaw-plugin 0.5.0

package/README.md

@@ -0,0 +1,95 @@
+# @vincentwei1021/synapse-openclaw-plugin
+
+OpenClaw plugin for [Synapse](https://github.com/Vincentwei1021/Synapse) -- the AI research orchestration platform.
+
+Connects OpenClaw agents to Synapse via a persistent SSE connection and MCP tool bridge, enabling autonomous experiment execution, deep research, progress reporting, and report generation.
+
+## Installation
+
+```bash
+openclaw plugins install @vincentwei1021/synapse-openclaw-plugin
+```
+
+## Configuration
+
+Add to `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "token": "your-hooks-token"
+  },
+  "plugins": {
+    "enabled": true,
+    "entries": {
+      "synapse-openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "synapseUrl": "https://synapse.example.com",
+          "apiKey": "syn_your_api_key_here",
+          "autoStart": true
+        }
+      }
+    }
+  }
+}
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `synapseUrl` | `string` | Yes | -- | Synapse server URL |
+| `apiKey` | `string` | Yes | -- | Synapse API key (`syn_` prefix) |
+| `projectUuids` | `string[]` | No | `[]` | Project UUIDs to monitor (empty = all) |
+| `autoStart` | `boolean` | No | `true` | Auto-claim experiment runs on assignment |
+
+## How It Works
+
+1. **SSE listener** maintains a persistent connection to `/api/events/notifications` for real-time events
+2. **Event router** maps notifications to agent actions (experiment assignments, autonomous loop, deep research, mentions, etc.)
+3. **Agent trigger** dispatches isolated agent turns via OpenClaw's `/hooks/agent` endpoint
+4. **MCP tools** are registered as native OpenClaw agent tools, bridging to Synapse's MCP server at `/api/mcp`
+
+### Event Handling
+
+| Event | Behavior |
+|-------|----------|
+| `task_assigned` (experiment) | Fetch experiment + project context, wake agent with full assignment prompt |
+| `autonomous_loop_triggered` | Wake agent to analyze project and propose new experiments |
+| `deep_research_requested` | Wake agent to perform literature review |
+| `experiment_report_requested` | Wake agent to write a detailed experiment report |
+| `mentioned` | Wake agent with @mention context |
+| `hypothesis_formulation_requested` | Wake agent to review hypothesis formulation questions |
+| `hypothesis_formulation_answered` | Wake agent to validate answers |
+| `research_question_claimed` | Wake agent when assigned a research question |
+
+### Registered MCP Tools
+
+All Synapse MCP tools are available to all agents. The plugin registers them as native OpenClaw tools via passthrough to the Synapse MCP server.
+
+## Local Development
+
+```json
+{
+  "plugins": {
+    "enabled": true,
+    "load": {
+      "paths": ["/path/to/Synapse/packages/openclaw-plugin"]
+    },
+    "entries": {
+      "synapse-openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "synapseUrl": "http://localhost:3000",
+          "apiKey": "syn_your_dev_key",
+          "autoStart": true
+        }
+      }
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/openclaw.plugin.json

@@ -0,0 +1,28 @@
+{
+  "id": "synapse-openclaw-plugin",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "synapseUrl": {
+        "type": "string",
+        "description": "Synapse server URL"
+      },
+      "apiKey": {
+        "type": "string",
+        "description": "Synapse API Key (syn_ prefix)"
+      },
+      "projectUuids": {
+        "type": "array",
+        "items": { "type": "string" },
+        "default": [],
+        "description": "Project UUIDs to monitor (empty = all)"
+      },
+      "autoStart": {
+        "type": "boolean",
+        "default": true,
+        "description": "Auto-claim experiment runs on assignment"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@vincentwei1021/synapse-openclaw-plugin",
+  "version": "0.5.0",
+  "description": "OpenClaw plugin for Synapse research orchestration — SSE notifications, MCP tools, experiment lifecycle, autonomous loop",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "cd ../.. && pnpm exec vitest run packages/openclaw-plugin/src/event-router.test.ts packages/openclaw-plugin/src/mcp-client.test.ts packages/openclaw-plugin/src/sse-listener.test.ts"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0"
+  },
+  "openclaw": {
+    "extensions": ["src/index.ts"]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Vincentwei1021/Synapse",
+    "directory": "packages/openclaw-plugin"
+  },
+  "homepage": "https://github.com/Vincentwei1021/Synapse",
+  "keywords": ["openclaw", "synapse", "research", "mcp", "plugin", "agent", "experiments"],
+  "files": [
+    "src",
+    "openclaw.plugin.json",
+    "README.md"
+  ]
+}

package/src/commands.ts

@@ -0,0 +1,151 @@
+import type { SynapseMcpClient } from "./mcp-client.js";
+
+// ===== Response types from Synapse MCP tools =====
+
+interface CheckinResponse {
+  checkinTime: string;
+  agent: {
+    uuid: string;
+    name: string;
+    roles: string[];
+    persona: string | null;
+    systemPrompt: string | null;
+  };
+  assignments: {
+    researchQuestions?: AssignedQuestion[];
+    experimentRuns?: AssignedRun[];
+  };
+  pending: {
+    researchQuestionsCount?: number;
+    experimentRunsCount?: number;
+  };
+  notifications: {
+    unreadCount: number;
+  };
+}
+
+interface AssignedQuestion {
+  uuid: string;
+  title: string;
+  status: string;
+  project: { uuid: string; name: string };
+}
+
+interface AssignedRun {
+  uuid: string;
+  title: string;
+  status: string;
+  priority: string;
+  project: { uuid: string; name: string };
+}
+
+interface AssignmentsResponse {
+  researchQuestions?: AssignedQuestion[];
+  experimentRuns?: AssignedRun[];
+}
+
+// ===== Formatting helpers =====
+
+function formatStatus(checkin: CheckinResponse, connectionStatus: string): string {
+  const questionCount = checkin?.pending?.researchQuestionsCount ?? 0;
+  const runCount = checkin?.pending?.experimentRunsCount ?? 0;
+  const lines: string[] = [
+    `Connection: ${connectionStatus}`,
+    `Assignments: ${questionCount} questions, ${runCount} experiments`,
+    `Notifications: ${checkin?.notifications?.unreadCount ?? 0} unread`,
+  ];
+  return lines.join("\n");
+}
+
+function formatExperimentList(runs: AssignedRun[] | undefined): string {
+  if (!runs?.length) {
+    return "No assigned experiments.";
+  }
+
+  const lines = runs.map(
+    (r) => `[${r.status}] [${r.priority}] ${r.title}  (${r.project.name})`
+  );
+  return `Assigned experiments (${runs.length}):\n${lines.join("\n")}`;
+}
+
+function formatQuestionList(questions: AssignedQuestion[] | undefined): string {
+  if (!questions?.length) {
+    return "No assigned research questions.";
+  }
+
+  const lines = questions.map(
+    (q) => `[${q.status}] ${q.title}  (${q.project.name})`
+  );
+  return `Assigned research questions (${questions.length}):\n${lines.join("\n")}`;
+}
+
+const HELP_TEXT = [
+  "Synapse commands:",
+  "  /synapse              Show connection status and summary",
+  "  /synapse status       Same as above",
+  "  /synapse experiments  List assigned experiments",
+  "  /synapse questions    List assigned research questions",
+].join("\n");
+
+interface CommandRegistry {
+  registerCommand(command: {
+    name: string;
+    description: string;
+    handler: (ctx: { args: string }) => Promise<{ text: string }>;
+  }): void;
+}
+
+// ===== Registration =====
+
+export function registerSynapseCommands(
+  api: CommandRegistry,
+  mcpClient: SynapseMcpClient,
+  getStatus: () => string
+): void {
+  api.registerCommand({
+    name: "synapse",
+    description: "Synapse plugin commands: status, experiments, questions",
+    async handler(ctx: { args: string }) {
+      const sub = (ctx.args ?? "").trim().toLowerCase();
+
+      // /synapse or /synapse status
+      if (!sub || sub === "status") {
+        try {
+          const checkin = (await mcpClient.callTool("synapse_checkin", {})) as CheckinResponse;
+          return { text: formatStatus(checkin, getStatus()) };
+        } catch (err) {
+          return { text: `Failed to check in: ${err instanceof Error ? err.message : String(err)}` };
+        }
+      }
+
+      // /synapse experiments
+      if (sub === "experiments" || sub === "tasks") {
+        try {
+          const data = (await mcpClient.callTool(
+            "synapse_get_my_assignments",
+            {}
+          )) as AssignmentsResponse;
+          return { text: formatExperimentList(data?.experimentRuns) };
+        } catch (err) {
+          return { text: `Failed to fetch experiments: ${err instanceof Error ? err.message : String(err)}` };
+        }
+      }
+
+      // /synapse questions
+      if (sub === "questions" || sub === "ideas") {
+        try {
+          const data = (await mcpClient.callTool(
+            "synapse_get_my_assignments",
+            {}
+          )) as AssignmentsResponse;
+          return { text: formatQuestionList(data?.researchQuestions) };
+        } catch (err) {
+          return { text: `Failed to fetch research questions: ${err instanceof Error ? err.message : String(err)}` };
+        }
+      }
+
+      // Unknown subcommand
+      return { text: HELP_TEXT };
+    },
+  });
+}

package/src/config.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+
+export const CONFIG_FILE_PATH = "~/.openclaw/openclaw.json";
+export const CONFIG_KEY_PATH = "plugins.entries.synapse-openclaw-plugin.config";
+
+export const synapseConfigSchema = z.object({
+  synapseUrl: z
+    .string()
+    .url()
+    .optional()
+    .describe("Synapse server URL (e.g. https://synapse.example.com)"),
+  apiKey: z
+    .string()
+    .startsWith("syn_")
+    .optional()
+    .describe("Synapse API Key (syn_ prefix)"),
+  projectUuids: z
+    .array(z.string().uuid())
+    .optional()
+    .default([])
+    .describe("Project UUIDs to monitor. Empty = all projects"),
+  autoStart: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe("Auto-claim and start work on task_assigned events"),
+});
+
+export type SynapsePluginConfig = z.infer<typeof synapseConfigSchema>;
+
+/**
+ * Check required config fields and warn about missing ones.
+ * Returns true if all required fields are present, false otherwise.
+ */
+export function validateConfigWithWarnings(
+  config: SynapsePluginConfig,
+  logger: { warn: (msg: string) => void },
+): boolean {
+  const missing: string[] = [];
+
+  if (!config.synapseUrl) {
+    missing.push(`  - "synapseUrl": set at ${CONFIG_KEY_PATH}.synapseUrl in ${CONFIG_FILE_PATH}`);
+  }
+  if (!config.apiKey) {
+    missing.push(`  - "apiKey": set at ${CONFIG_KEY_PATH}.apiKey in ${CONFIG_FILE_PATH}`);
+  }
+
+  if (missing.length > 0) {
+    logger.warn(
+      `[Synapse] Plugin is missing required configuration. Features will be disabled until configured:\n` +
+      missing.join("\n")
+    );
+    return false;
+  }
+  return true;
+}

package/src/event-router.test.ts

@@ -0,0 +1,265 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { SynapseEventRouter } from "./event-router.js";
+
+function createLogger() {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  };
+}
+
+describe("SynapseEventRouter", () => {
+  const triggerAgent = vi.fn();
+  const callTool = vi.fn();
+  const logger = createLogger();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("routes experiment assignments with full context and unlimited budget text", async () => {
+    callTool
+      .mockResolvedValueOnce({
+        notifications: [
+          {
+            uuid: "notification-1",
+            researchProjectUuid: "project-1",
+            entityType: "experiment",
+            entityUuid: "experiment-1",
+            entityTitle: "Train the baseline",
+            action: "task_assigned",
+            message: "Assigned to you",
+            actorType: "user",
+            actorUuid: "user-1",
+            actorName: "Alice",
+          },
+        ],
+      })
+      .mockResolvedValueOnce({
+        experiment: {
+          uuid: "experiment-1",
+          researchProjectUuid: "project-1",
+          title: "Train the baseline",
+          description: "Run the first baseline.",
+          priority: "high",
+          computeBudgetHours: null,
+          attachments: [{ originalName: "spec.md" }],
+          researchQuestion: { uuid: "question-1", title: "Why is recall dropping?" },
+          parentQuestionExperiments: [],
+        },
+      })
+      .mockResolvedValueOnce({
+        uuid: "project-1",
+        name: "Recall recovery",
+        description: "Improve retrieval quality",
+        goal: "Raise recall by 5 points",
+        datasets: ["train.jsonl"],
+        evaluationMethods: ["recall@10"],
+      });
+
+    const router = new SynapseEventRouter({
+      mcpClient: { callTool } as never,
+      config: {
+        synapseUrl: "http://synapse.local",
+        apiKey: "syn_key",
+        autoStart: true,
+        projectUuids: [],
+      },
+      triggerAgent,
+      logger,
+    });
+
+    await (router as unknown as { fetchAndRoute: (notificationUuid: string) => Promise<void> }).fetchAndRoute("notification-1");
+
+    expect(triggerAgent).toHaveBeenCalledTimes(1);
+    const [prompt, metadata] = triggerAgent.mock.calls[0];
+    expect(prompt).toContain("Experiment assigned: Train the baseline");
+    expect(prompt).toContain("Compute budget (hours): Unlimited");
+    expect(prompt).toContain("post a comment on this experiment");
+    expect(prompt).toContain("@[Alice](user:user-1)");
+    expect(prompt).toContain("synapse_report_experiment_progress");
+    expect(metadata).toMatchObject({
+      action: "task_assigned",
+      entityType: "experiment",
+      entityUuid: "experiment-1",
+      projectUuid: "project-1",
+    });
+  });
+
+  it("skips notifications outside the configured project filter", async () => {
+    callTool.mockResolvedValueOnce({
+      notifications: [
+        {
+          uuid: "notification-2",
+          researchProjectUuid: "project-2",
+          entityType: "experiment",
+          entityUuid: "experiment-2",
+          entityTitle: "Ignored experiment",
+          action: "task_assigned",
+          message: "Assigned to you",
+          actorType: "user",
+          actorUuid: "user-2",
+          actorName: "Bob",
+        },
+      ],
+    });
+
+    const router = new SynapseEventRouter({
+      mcpClient: { callTool } as never,
+      config: {
+        synapseUrl: "http://synapse.local",
+        apiKey: "syn_key",
+        autoStart: true,
+        projectUuids: ["project-allowed"],
+      },
+      triggerAgent,
+      logger,
+    });
+
+    await (router as unknown as { fetchAndRoute: (notificationUuid: string) => Promise<void> }).fetchAndRoute("notification-2");
+
+    expect(triggerAgent).not.toHaveBeenCalled();
+    expect(callTool).toHaveBeenCalledTimes(1);
+    expect(logger.info).toHaveBeenCalledWith("Notification for project project-2 filtered out");
+  });
+
+  it("routes autonomous loop triggered events", async () => {
+    callTool.mockResolvedValueOnce({
+      notifications: [
+        {
+          uuid: "notification-3",
+          researchProjectUuid: "project-1",
+          entityType: "research_project",
+          entityUuid: "project-1",
+          entityTitle: "My Project",
+          action: "autonomous_loop_triggered",
+          message: "Queue empty",
+          actorType: "system",
+          actorUuid: "system",
+          actorName: "Synapse",
+        },
+      ],
+    });
+
+    const router = new SynapseEventRouter({
+      mcpClient: { callTool } as never,
+      config: {
+        synapseUrl: "http://synapse.local",
+        apiKey: "syn_key",
+        autoStart: true,
+        projectUuids: [],
+      },
+      triggerAgent,
+      logger,
+    });
+
+    await (router as unknown as { fetchAndRoute: (notificationUuid: string) => Promise<void> }).fetchAndRoute("notification-3");
+
+    expect(triggerAgent).toHaveBeenCalledTimes(1);
+    const [prompt, metadata] = triggerAgent.mock.calls[0];
+    expect(prompt).toContain("Autonomous research loop triggered");
+    expect(prompt).toContain("synapse_propose_experiment");
+    expect(metadata).toMatchObject({
+      action: "autonomous_loop_triggered",
+      projectUuid: "project-1",
+    });
+  });
+
+  it("routes experiment report requested events", async () => {
+    callTool.mockResolvedValueOnce({
+      notifications: [
+        {
+          uuid: "notification-4",
+          researchProjectUuid: "project-1",
+          entityType: "experiment",
+          entityUuid: "experiment-1",
+          entityTitle: "Baseline experiment",
+          action: "experiment_report_requested",
+          message: "Write report",
+          actorType: "system",
+          actorUuid: "system",
+          actorName: "Synapse",
+        },
+      ],
+    });
+
+    const router = new SynapseEventRouter({
+      mcpClient: { callTool } as never,
+      config: {
+        synapseUrl: "http://synapse.local",
+        apiKey: "syn_key",
+        autoStart: true,
+        projectUuids: [],
+      },
+      triggerAgent,
+      logger,
+    });
+
+    await (router as unknown as { fetchAndRoute: (notificationUuid: string) => Promise<void> }).fetchAndRoute("notification-4");
+
+    expect(triggerAgent).toHaveBeenCalledTimes(1);
+    const [prompt] = triggerAgent.mock.calls[0];
+    expect(prompt).toContain("Baseline experiment");
+    expect(prompt).toContain("synapse_add_comment");
+  });
+
+  it("routes @mention events with entity context", async () => {
+    callTool.mockResolvedValueOnce({
+      notifications: [
+        {
+          uuid: "notification-5",
+          researchProjectUuid: "project-1",
+          entityType: "experiment",
+          entityUuid: "experiment-1",
+          entityTitle: "Recall test",
+          action: "mentioned",
+          message: "@Agent please review",
+          actorType: "user",
+          actorUuid: "user-1",
+          actorName: "Alice",
+        },
+      ],
+    });
+
+    const router = new SynapseEventRouter({
+      mcpClient: { callTool } as never,
+      config: {
+        synapseUrl: "http://synapse.local",
+        apiKey: "syn_key",
+        autoStart: true,
+        projectUuids: [],
+      },
+      triggerAgent,
+      logger,
+    });
+
+    await (router as unknown as { fetchAndRoute: (notificationUuid: string) => Promise<void> }).fetchAndRoute("notification-5");
+
+    expect(triggerAgent).toHaveBeenCalledTimes(1);
+    const [prompt] = triggerAgent.mock.calls[0];
+    expect(prompt).toContain("@mentioned");
+    expect(prompt).toContain("synapse_get_comments");
+    expect(prompt).toContain("@[Alice](user:user-1)");
+  });
+
+  it("ignores non-new_notification event types", () => {
+    const router = new SynapseEventRouter({
+      mcpClient: { callTool } as never,
+      config: {
+        synapseUrl: "http://synapse.local",
+        apiKey: "syn_key",
+        autoStart: true,
+        projectUuids: [],
+      },
+      triggerAgent,
+      logger,
+    });
+
+    router.dispatch({ type: "count_update", unreadCount: 5 } as unknown as import("./sse-listener.js").SseNotificationEvent);
+
+    expect(triggerAgent).not.toHaveBeenCalled();
+    expect(callTool).not.toHaveBeenCalled();
+    expect(logger.info).toHaveBeenCalledWith('SSE event type "count_update" ignored');
+  });
+});