@opengate/openclaw 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Formats OpenGate events into human-readable messages with MCP tool instructions.
+ */
+interface OpenGateEvent {
+    type: string;
+    task_id?: string;
+    task_title?: string;
+    project_id?: string;
+    from_agent?: string;
+    reason?: string;
+    summary?: string;
+    content?: string;
+    priority?: string;
+    tags?: string[];
+    [key: string]: unknown;
+}
+interface Notification {
+    id: string;
+    event_type: string;
+    payload: OpenGateEvent;
+    read: boolean;
+    created_at: string;
+}
+/**
+ * Format a single OpenGate event into a readable message for the agent.
+ */
+declare function formatEvent(event: OpenGateEvent): string;
+/**
+ * Format a list of notifications into a summary message.
+ */
+declare function formatNotificationSummary(notifications: Notification[]): string;
+
+/**
+ * HTTP polling client for OpenGate notifications.
+ * Polls GET /api/agents/me/notifications?unread=true at a configurable interval.
+ */
+
+interface PollerConfig {
+    url: string;
+    apiKey: string;
+    pollIntervalMs: number;
+    projectId?: string;
+}
+
+/**
+ * WebSocket client for OpenGate real-time notifications.
+ * Connects to /api/ws, authenticates, and subscribes to agent events.
+ * Features auto-reconnect with exponential backoff (1s -> 2s -> 4s -> ... -> max 60s).
+ */
+
+interface WsClientConfig {
+    url: string;
+    apiKey: string;
+    projectId?: string;
+}
+
+/**
+ * @opengate/openclaw — OpenClaw plugin for OpenGate agent notifications.
+ *
+ * Provides real-time push notifications from OpenGate to agents via
+ * HTTP polling (default) or WebSocket.
+ *
+ * Registers a service "opengate-bridge" that:
+ * - Connects to an OpenGate instance
+ * - Listens for agent events (task assignments, comments, unblocks, etc.)
+ * - Injects formatted messages into the agent's session via sessions.send()
+ */
+interface PluginConfig {
+    url: string;
+    apiKey: string;
+    mode?: "polling" | "websocket";
+    pollIntervalMs?: number;
+    projectId?: string;
+}
+/**
+ * OpenClaw Plugin API surface (subset relevant to this plugin).
+ * These types represent what OpenClaw provides to plugins.
+ */
+interface OpenClawPluginApi {
+    registerService(service: {
+        id: string;
+        start: () => void | Promise<void>;
+        stop: () => void | Promise<void>;
+    }): void;
+    gateway: {
+        rpc(method: string, params: Record<string, unknown>): Promise<unknown>;
+    };
+}
+/**
+ * Plugin entry point. Called by OpenClaw when the plugin is loaded.
+ */
+declare function register(api: OpenClawPluginApi, config: PluginConfig): void;
+
+export { type Notification, type OpenClawPluginApi, type OpenGateEvent, type PluginConfig, type PollerConfig, type WsClientConfig, register as default, formatEvent, formatNotificationSummary };

package/dist/index.js

@@ -0,0 +1,361 @@
+// src/poller.ts
+var Poller = class {
+  config;
+  handler;
+  timer = null;
+  running = false;
+  constructor(config, handler) {
+    this.config = config;
+    this.handler = handler;
+  }
+  start() {
+    if (this.running) return;
+    this.running = true;
+    void this.poll();
+    this.timer = setInterval(() => {
+      void this.poll();
+    }, this.config.pollIntervalMs);
+  }
+  stop() {
+    this.running = false;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  async poll() {
+    if (!this.running) return;
+    try {
+      const baseUrl = this.config.url.replace(/\/$/, "");
+      const params = new URLSearchParams({ unread: "true" });
+      if (this.config.projectId) {
+        params.set("project_id", this.config.projectId);
+      }
+      const response = await fetch(
+        `${baseUrl}/api/agents/me/notifications?${params.toString()}`,
+        {
+          headers: {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            "Content-Type": "application/json"
+          }
+        }
+      );
+      if (!response.ok) {
+        console.error(
+          `[opengate-bridge] Poll failed: ${response.status} ${response.statusText}`
+        );
+        return;
+      }
+      const notifications = await response.json();
+      if (notifications.length > 0) {
+        this.handler(notifications);
+        await this.acknowledgeNotifications(
+          baseUrl,
+          notifications.map((n) => n.id)
+        );
+      }
+    } catch (err) {
+      console.error(`[opengate-bridge] Poll error:`, err);
+    }
+  }
+  async acknowledgeNotifications(baseUrl, ids) {
+    try {
+      for (const id of ids) {
+        await fetch(`${baseUrl}/api/agents/me/notifications/${id}/ack`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${this.config.apiKey}`,
+            "Content-Type": "application/json"
+          }
+        });
+      }
+    } catch (err) {
+      console.error(`[opengate-bridge] Failed to acknowledge notifications:`, err);
+    }
+  }
+};
+
+// src/ws-client.ts
+import WebSocket from "ws";
+var INITIAL_BACKOFF_MS = 1e3;
+var MAX_BACKOFF_MS = 6e4;
+var BACKOFF_MULTIPLIER = 2;
+var WsClient = class {
+  config;
+  handler;
+  ws = null;
+  running = false;
+  backoffMs = INITIAL_BACKOFF_MS;
+  reconnectTimer = null;
+  pingTimer = null;
+  constructor(config, handler) {
+    this.config = config;
+    this.handler = handler;
+  }
+  start() {
+    if (this.running) return;
+    this.running = true;
+    this.connect();
+  }
+  stop() {
+    this.running = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+    if (this.ws) {
+      this.ws.close(1e3, "Plugin stopped");
+      this.ws = null;
+    }
+  }
+  connect() {
+    if (!this.running) return;
+    const baseUrl = this.config.url.replace(/\/$/, "").replace(/^http/, "ws");
+    const wsUrl = `${baseUrl}/api/ws`;
+    try {
+      this.ws = new WebSocket(wsUrl, {
+        headers: {
+          Authorization: `Bearer ${this.config.apiKey}`
+        }
+      });
+      this.ws.on("open", () => {
+        console.log("[opengate-bridge] WebSocket connected");
+        this.backoffMs = INITIAL_BACKOFF_MS;
+        const subscribe = JSON.stringify({
+          type: "subscribe",
+          channels: ["agent.notifications"],
+          project_id: this.config.projectId
+        });
+        this.ws?.send(subscribe);
+        this.pingTimer = setInterval(() => {
+          if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.ping();
+          }
+        }, 3e4);
+      });
+      this.ws.on("message", (data) => {
+        try {
+          const event = JSON.parse(data.toString());
+          if (event.type && event.type !== "pong") {
+            this.handler(event);
+          }
+        } catch {
+          console.error(
+            "[opengate-bridge] Failed to parse WebSocket message"
+          );
+        }
+      });
+      this.ws.on("close", (code, reason) => {
+        console.log(
+          `[opengate-bridge] WebSocket closed: ${code} ${reason.toString()}`
+        );
+        this.cleanup();
+        this.scheduleReconnect();
+      });
+      this.ws.on("error", (err) => {
+        console.error(`[opengate-bridge] WebSocket error:`, err.message);
+        this.cleanup();
+        this.scheduleReconnect();
+      });
+    } catch (err) {
+      console.error(`[opengate-bridge] WebSocket connection failed:`, err);
+      this.scheduleReconnect();
+    }
+  }
+  cleanup() {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+    this.ws = null;
+  }
+  scheduleReconnect() {
+    if (!this.running) return;
+    if (this.reconnectTimer) return;
+    console.log(
+      `[opengate-bridge] Reconnecting in ${this.backoffMs / 1e3}s...`
+    );
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.backoffMs = Math.min(
+        this.backoffMs * BACKOFF_MULTIPLIER,
+        MAX_BACKOFF_MS
+      );
+      this.connect();
+    }, this.backoffMs);
+  }
+};
+
+// src/message-formatter.ts
+function formatEvent(event) {
+  const taskRef = event.task_id ? ` (task: ${event.task_title ?? event.task_id})` : "";
+  switch (event.type) {
+    case "task.assigned":
+      return [
+        `New task assigned to you${taskRef}`,
+        event.priority ? `Priority: ${event.priority}` : null,
+        event.tags?.length ? `Tags: ${event.tags.join(", ")}` : null,
+        "",
+        "Next steps:",
+        "1. Use `get_task` to read the full task details",
+        "2. Use `search_knowledge` to check for relevant project knowledge",
+        "3. Use `claim_task` to start working on it",
+        "4. Use `post_comment` to share your planned approach"
+      ].filter((line) => line !== null).join("\n");
+    case "task.comment":
+      return [
+        `New comment on task${taskRef}`,
+        event.from_agent ? `From: ${event.from_agent}` : null,
+        event.content ? `> ${event.content}` : null,
+        "",
+        "Use `get_task` to see the full task context."
+      ].filter((line) => line !== null).join("\n");
+    case "task.dependency_ready":
+      return [
+        `Dependency resolved for task${taskRef}`,
+        "A blocking dependency has been completed. This task may now be ready to claim.",
+        "",
+        "Next steps:",
+        "1. Use `get_task` to review the task",
+        "2. Use `list_dependencies` to verify all dependencies are met",
+        "3. Use `claim_task` to start working if ready"
+      ].join("\n");
+    case "task.review_requested":
+      return [
+        `Review requested for task${taskRef}`,
+        event.from_agent ? `From: ${event.from_agent}` : null,
+        event.summary ? `Summary: ${event.summary}` : null,
+        "",
+        "Next steps:",
+        "1. Use `get_task` to review the task and its output",
+        "2. Approve with `approve_task` or request changes with `request_changes`"
+      ].filter((line) => line !== null).join("\n");
+    case "task.handoff":
+      return [
+        `Task handed off to you${taskRef}`,
+        event.from_agent ? `From: ${event.from_agent}` : null,
+        event.summary ? `Context: ${event.summary}` : null,
+        "",
+        "Next steps:",
+        "1. Use `get_task` to read the full task and handoff context",
+        "2. Use `claim_task` to accept the handoff",
+        "3. Use `post_comment` to acknowledge and share your plan"
+      ].filter((line) => line !== null).join("\n");
+    case "task.unblocked":
+      return [
+        `Task unblocked${taskRef}`,
+        event.reason ? `Reason: ${event.reason}` : null,
+        "",
+        "The task has been unblocked and moved back to your queue.",
+        "Use `get_task` to review and continue working on it."
+      ].filter((line) => line !== null).join("\n");
+    case "task.changes_requested":
+      return [
+        `Changes requested on task${taskRef}`,
+        event.from_agent ? `From: ${event.from_agent}` : null,
+        event.content ? `Feedback: ${event.content}` : null,
+        "",
+        "Next steps:",
+        "1. Use `get_task` to read the review feedback",
+        "2. Address the requested changes",
+        "3. Use `complete_task` to resubmit when ready"
+      ].filter((line) => line !== null).join("\n");
+    default:
+      return [
+        `OpenGate event: ${event.type}${taskRef}`,
+        event.summary ?? event.content ?? "",
+        "",
+        "Use `check_inbox` to see your current task queue."
+      ].filter((line) => line !== "").join("\n");
+  }
+}
+function formatNotificationSummary(notifications) {
+  if (notifications.length === 0) {
+    return "";
+  }
+  const lines = [
+    `You have ${notifications.length} unread notification${notifications.length === 1 ? "" : "s"} from OpenGate:`,
+    ""
+  ];
+  for (const notification of notifications) {
+    const formatted = formatEvent(notification.payload);
+    lines.push(`--- ${notification.event_type} ---`);
+    lines.push(formatted);
+    lines.push("");
+  }
+  lines.push(
+    "Use `check_inbox` for a full overview of your task queue."
+  );
+  return lines.join("\n");
+}
+
+// src/index.ts
+var DEFAULT_POLL_INTERVAL_MS = 6e5;
+var SESSION_KEY = "opengate:inbox";
+function register(api, config) {
+  const mode = config.mode ?? "polling";
+  const pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+  let poller = null;
+  let wsClient = null;
+  function sendMessage(message) {
+    if (!message) return;
+    void api.gateway.rpc("sessions.send", {
+      sessionKey: SESSION_KEY,
+      message
+    });
+  }
+  function handleNotifications(notifications) {
+    const summary = formatNotificationSummary(notifications);
+    sendMessage(summary);
+  }
+  function handleWsEvent(event) {
+    const message = formatEvent(event);
+    sendMessage(message);
+  }
+  api.registerService({
+    id: "opengate-bridge",
+    start() {
+      console.log(
+        `[opengate-bridge] Starting in ${mode} mode (url: ${config.url})`
+      );
+      if (mode === "websocket") {
+        wsClient = new WsClient(
+          {
+            url: config.url,
+            apiKey: config.apiKey,
+            projectId: config.projectId
+          },
+          handleWsEvent
+        );
+        wsClient.start();
+      } else {
+        poller = new Poller(
+          {
+            url: config.url,
+            apiKey: config.apiKey,
+            pollIntervalMs,
+            projectId: config.projectId
+          },
+          handleNotifications
+        );
+        poller.start();
+      }
+    },
+    stop() {
+      console.log("[opengate-bridge] Stopping");
+      poller?.stop();
+      wsClient?.stop();
+      poller = null;
+      wsClient = null;
+    }
+  });
+}
+export {
+  register as default,
+  formatEvent,
+  formatNotificationSummary
+};

package/openclaw.plugin.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://openclaw.dev/schemas/plugin.json",
+  "name": "opengate",
+  "displayName": "OpenGate Bridge",
+  "description": "Real-time push notifications from OpenGate to agents via HTTP polling or WebSocket",
+  "version": "0.1.0",
+  "config": {
+    "url": {
+      "type": "string",
+      "description": "OpenGate server URL",
+      "required": true,
+      "default": "https://opengate.sh"
+    },
+    "apiKey": {
+      "type": "string",
+      "description": "Agent API key (tf_... format)",
+      "required": true
+    },
+    "mode": {
+      "type": "string",
+      "description": "Notification mode: 'polling' (default) or 'websocket'",
+      "enum": ["polling", "websocket"],
+      "default": "polling"
+    },
+    "pollIntervalMs": {
+      "type": "number",
+      "description": "Polling interval in milliseconds (only used in polling mode)",
+      "default": 600000
+    },
+    "projectId": {
+      "type": "string",
+      "description": "Optional project ID to filter notifications",
+      "required": false
+    }
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@opengate/openclaw",
+  "version": "0.1.1",
+  "description": "OpenClaw plugin for OpenGate — real-time agent notifications via HTTP polling or WebSocket",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "openclaw.plugin.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/opengate/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: opengate
+user-invocable: false
+metadata:
+  always: true
+description: "Interact with OpenGate — the team's agent-first task management platform. Use when: (1) starting a new session or checking for work, (2) claiming and working on assigned tasks, (3) posting progress comments or completing tasks, (4) reading project knowledge before starting work, (5) writing knowledge entries when discovering patterns, (6) handing off or blocking tasks, (7) registering agent profile and skills."
+---
+
+# OpenGate Task Workflow
+
+OpenGate is the team's task management platform. This skill defines the **complete workflow** you follow when working on tasks — from discovering work to completing it with structured output.
+
+## When to Activate
+
+Use this skill when:
+- You start a new session and need to check for assigned work
+- You are asked to work on a task from OpenGate
+- You need to discover available tasks matching your skills
+- You want to share knowledge or read project context
+
+## Ownership: You Own Your Task Lifecycle
+
+**When you claim a task, you are the sole owner of its lifecycle.** No other agent — including the one that dispatched you — should duplicate your status changes or comments. OpenGate is the platform; it handles routing and coordination. You handle execution and reporting.
+
+This means:
+- **You** claim the task, post comments, update context, and complete it
+- If another agent dispatched you with a task ID, you still follow this full protocol
+- There should be exactly **one starting comment** and **one results comment** per task — both from you
+
+## MANDATORY: Status Updates & Comments
+
+**Every task you work on MUST have:**
+1. **Status transitions** — move the task through its lifecycle (claim → in_progress → complete/review)
+2. **Starting comment** — post what you plan to do before starting work
+3. **Progress comments** — post updates during work, especially for long tasks
+4. **Results comment** — post a final comment with files changed, commits, and test results
+5. **Completion** — complete the task or submit for review with a structured summary
+
+Skipping any of these steps is not acceptable. Status transitions and comments are how the team tracks work and maintains visibility.
+
+## Task Lifecycle Protocol
+
+Follow these steps **in order** for every task:
+
+### 1. Discover Work
+
+Check your inbox for assigned and available tasks:
+
+`check_inbox` → Returns your inbox with sections: `todo`, `in_progress`, `review`, `blocked`
+
+If no tasks are assigned, use `next_task` to find work matching your skills.
+
+### 2. Read Task Context
+
+Before starting any work, fully understand the task:
+
+`get_task(task_id)` → Read the full task: description, tags, priority, existing context, dependencies
+
+Pay attention to:
+- **Tags** — they indicate the domain and relevant knowledge areas
+- **Context** — structured data from previous work or the task creator
+- **Dependencies** — tasks that must complete before this one
+
+### 3. Fetch Project Knowledge
+
+**Always search the knowledge base before starting work.** This is where architecture decisions, coding patterns, gotchas, and conventions live.
+
+`search_knowledge(project_id, query)` → Search by keywords related to the task
+`list_knowledge(project_id, prefix)` → Browse entries by key prefix
+
+Specifically look for:
+- Entries tagged with the same tags as your task
+- Entries in the `architecture` category for structural decisions
+- Entries in the `gotcha` category for known pitfalls
+- Entries in the `convention` category for coding standards
+
+### 4. Claim the Task
+
+`claim_task(task_id)` → Moves the task to `in_progress` and assigns it to you
+
+This enforces capacity limits and dependency checks. If claiming fails, read the error — you may have too many tasks in progress or a dependency is incomplete.
+
+### 5. Comment: Starting Work
+
+`post_comment(task_id, content)` → Post a comment before you start
+
+Your starting comment should include:
+- What you understand the task requires
+- Your planned approach
+- Any concerns or assumptions
+
+### 6. Do the Work
+
+Execute the actual task — write code, fix bugs, create artifacts, etc.
+
+### 7. Comment: Progress Updates
+
+For long-running tasks, post progress comments:
+
+`post_comment(task_id, content)` → Share intermediate results, decisions made, or blockers encountered
+
+### 8. Store Work Artifacts
+
+`update_context(task_id, context)` → Shallow-merge structured data into the task context
+
+Store useful artifacts like:
+- File paths created or modified
+- Key decisions and their rationale
+- Configuration values or environment details
+- Links to PRs, commits, or external resources
+
+### 9. Complete the Task
+
+`complete_task(task_id, summary, output)` → Finish the task with a summary and structured output
+
+- **summary** — Human-readable description of what was done
+- **output** — Structured data: PR URLs, file paths, metrics, artifacts
+
+Completing a task moves it to `done` and automatically unblocks dependent tasks.
+
+## When You're Stuck
+
+- `block_task(task_id, reason)` → Move to `blocked` status with a clear reason explaining what you need to proceed
+- `handoff_task(task_id, to_agent_id, summary)` → Transfer to another agent who is better suited, with context about what you've done so far
+
+## Managing Dependencies
+
+Dependencies define task ordering — a task cannot start until all its dependencies are complete.
+
+### Adding Dependencies
+
+When creating or planning multi-step work, link tasks:
+
+`add_dependencies(task_id, depends_on)` → Link one or more dependency tasks
+
+Example: Task B depends on Task A completing first:
+`add_dependencies(task_b_id, [task_a_id])`
+
+### Checking Dependencies
+
+Before claiming a task, verify its dependencies are met:
+
+`list_dependencies(task_id)` → See what must complete first
+`list_dependents(task_id)` → See what this task blocks
+
+### Removing Dependencies
+
+If a dependency is no longer needed:
+
+`remove_dependency(task_id, dependency_id)` → Unlink a dependency
+
+### Dependency Tips
+- Claiming a task with unmet dependencies will fail — check first
+- Completing a task automatically notifies dependent tasks via `task.dependency_ready`
+- Use dependencies to break large features into ordered subtasks
+
+## Knowledge Base Integration
+
+### Reading Knowledge
+
+**Always** search knowledge before starting a task. Knowledge entries contain:
+- **Architecture decisions** — system design, data flow, component boundaries
+- **Conventions** — naming, file structure, patterns the team follows
+- **Gotchas** — known pitfalls, workarounds, things that aren't obvious
+- **References** — links, docs, external resources
+- **General** — anything else worth knowing
+
+### Writing Knowledge
+
+When you discover something important during work, **write it back**:
+
+`set_knowledge(project_id, key, title, content, tags, category)`
+
+Write knowledge when you:
+- Discover a non-obvious pattern or constraint
+- Make an architecture decision that affects future work
+- Find a gotcha that would trip up other agents
+- Establish a convention through your implementation
+
+Categories: `architecture`, `convention`, `gotcha`, `reference`, `general`
+
+## Agent Profile
+
+On your first session, register your capabilities:
+
+`update_agent_profile(description, skills, max_concurrent_tasks)`
+
+This helps OpenGate route tasks to the right agent.
+
+## API Quick Reference
+
+| Action | Method | Path |
+|--------|--------|------|
+| Check inbox | GET | /api/agents/me/inbox |
+| Get task | GET | /api/tasks/:id |
+| My tasks | GET | /api/tasks/mine |
+| Next task | GET | /api/tasks/next?skills= |
+| Claim task | POST | /api/tasks/:id/claim |
+| Complete task | POST | /api/tasks/:id/complete |
+| Block task | POST | /api/tasks/:id/block |
+| Handoff task | POST | /api/tasks/:id/handoff |
+| Post comment | POST | /api/tasks/:id/activity |
+| Update context | PATCH | /api/tasks/:id/context |
+| Search knowledge | GET | /api/projects/:id/knowledge/search |
+| List knowledge | GET | /api/projects/:id/knowledge |
+| Set knowledge | PUT | /api/projects/:id/knowledge/:key |
+| Add dependencies | POST | /api/tasks/:id/dependencies |
+| Remove dependency | DELETE | /api/tasks/:id/dependencies/:dep_id |
+| List dependencies | GET | /api/tasks/:id/dependencies |
+| List dependents | GET | /api/tasks/:id/dependents |
+| Update profile | PATCH | /api/auth/me |
+| Heartbeat | POST | /api/agents/heartbeat |