openclaw-channel-basicops 0.1.0

package/DESIGN.md

@@ -0,0 +1,374 @@
+# BasicOps ↔ OpenClaw Messaging Channel — Design / Spec (Draft)
+
+Status: draft (pre-coding)
+
+This document specifies the architecture and implementation plan for a custom **OpenClaw channel plugin** that connects **BasicOps Messaging (all message containers via MCP/API)** to OpenClaw as a first-class messaging surface.
+
+Key requirement (Justin): **The agent should be able to receive and respond when @mentioned on ANY BasicOps message type.**
+
+## 1) Goals
+
+- Add **BasicOps as an OpenClaw messaging channel** (like Telegram/WhatsApp).
+- Support **outbound** messages: OpenClaw → BasicOps (post a message into the chosen BasicOps thread).
+- Support **inbound** messages: BasicOps → OpenClaw (webhook events become inbound messages in the correct OpenClaw session).
+- Provide a clear **identity + conversation mapping** strategy.
+- Keep secrets safe (API tokens, webhook secrets), and validate webhook authenticity.
+
+## 2) Non-goals (initially)
+
+- Full parity with rich chat apps (typing indicators, read receipts, edits/deletes).
+- Perfect threading semantics across all BasicOps entities.
+- Complex file upload and media transformations (phase later).
+
+## 3) Key product decision: “What is a conversation?”
+
+### 3.1 Reality check: BasicOps now has real Messaging (via MCP/API)
+
+BasicOps now supports multiple **message containers** (not just notes/comments). We will treat each container as a first-class conversation surface and normalize them into OpenClaw sessions.
+
+From the BasicOps MCP server, the relevant messaging tools include:
+
+- Project messages: `list_messages_in_project`, `create_message_in_project`
+- Task messages: `list_messages_in_task`, `create_message_in_task`
+- Channels: `list_messages_in_channel`, `create_message_in_channel`
+- Chats (1:1 or generic chats): `list_messages_in_chat`, `create_message_in_chat`
+- Groupchats: `list_messages_in_groupchat`, `create_message_in_groupchat`
+
+Supporting tools (needed for richer behaviors / future phases):
+- Message CRUD: `get_message`, `update_message`, `delete_message`
+- Replies: `create_reply_in_message`, `list_replies_in_message`, `update_reply`, `delete_reply`
+- Reactions: `toggle_reaction_in_message`, `list_reactions_in_message`, `toggle_reaction_in_reply`, `list_reactions_in_reply`
+
+### 3.2 Normalized conversation key
+
+Define a stable normalized key:
+
+- `project:<projectId>`
+- `task:<taskId>`
+- `channel:<channelId>`
+- `chat:<chatId>`
+- `groupchat:<groupchatId>`
+
+This becomes the “target” in OpenClaw and the lookup key for session mapping.
+
+### 3.3 Mention-driven routing (hard requirement)
+
+Mention semantics:
+- A mention is `@<username>` in BasicOps.
+
+Policy:
+- The connector should **only invoke/route to the agent when the agent is mentioned** (configurable).
+- The connector should still be able to fetch recent context in the thread (e.g., last N messages) before responding.
+
+## 4) OpenClaw integration surface
+
+### 4.1 Plugin type
+
+- Implement as an OpenClaw **channel plugin** registered via:
+  - `api.registerChannel({ plugin })`
+
+Reference: OpenClaw docs `docs/tools/plugin.md` → “Register a messaging channel”.
+
+### 4.2 Config location + shape
+
+OpenClaw expects channel config under `channels.<id>` (not `plugins.entries`).
+
+Proposed config:
+
+```json5
+{
+  channels: {
+    basicops: {
+      accounts: {
+        default: {
+          enabled: true,
+
+          // REST (optional) + MCP (preferred)
+          apiBaseUrl: "https://api.basicops.com",
+          apiToken: "...",
+
+          // MCP settings (supplemental: context fetch, message send, recovery)
+          mcp: {
+            transport: "sse",
+            baseUrl: "https://app.basicops.com/mcp/sse",
+            // auth handled by OpenClaw secrets/persona integration
+            persona: "justin"
+          },
+
+          // Webhooks (required for Telegram-like responsiveness)
+          webhooks: {
+            enabled: true,
+            publicUrl: "https://<gateway-public>/channels/basicops/webhook/<pathToken>",
+            secret: "...", // optional if BasicOps does not sign; still useful for our own token
+            // BasicOps event types (observed via MCP list_webhooks)
+            eventTypes: [
+              "basicops.task.message.created",
+              "basicops.project.message.created",
+              "basicops.chat.message.created",
+              "basicops.groupchat.message.created",
+              "basicops.channel.message.created",
+              "basicops.task.reply.created",
+              "basicops.project.reply.created",
+              "basicops.chat.reply.created",
+              "basicops.groupchat.reply.created",
+              "basicops.channel.reply.created"
+            ]
+          },
+
+          // Mention policy
+          agentUsername: "Gus",              // the BasicOps username to match after '@'
+          respondOnlyWhenMentioned: true,
+          mentionRegexOverride: null,          // optional
+
+          // What containers to listen to
+          listen: {
+            project: true,
+            task: true,
+            channel: true,
+            chat: true,
+            groupchat: true
+          },
+
+          // Context fetching
+          context: {
+            fetchLastNMessages: 20
+          },
+
+          // optional: mapping store
+          mapping: {
+            provider: "sqlite" | "json",
+            path: "..."
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Notes:
+- `accounts.<id>` pattern matches OpenClaw’s multi-account model.
+- `conversationMode` is required for correctness unless we infer from targets.
+
+### 4.3 Channel metadata
+
+```ts
+meta: {
+  id: "basicops",
+  label: "BasicOps",
+  selectionLabel: "BasicOps Messaging",
+  docsPath: "/channels/basicops",
+  blurb: "BasicOps messaging connector",
+  aliases: ["bo", "basicops-messaging"],
+}
+```
+
+## 5) High-level architecture
+
+**Inbound requirement:** This connector MUST be **push-based** (webhooks) for near-real-time responsiveness (Telegram-like). Polling is not an acceptable primary mechanism; it is only a last-resort fallback for specific edge cases (e.g., missed events, replay/backfill).
+
+### 5.1 Components
+
+1) **OpenClaw Channel Plugin (this repo)**
+- Outbound adapter(s): `sendText` (and later replies/reactions/attachments)
+- Inbound adapter: **MCP event ingest** (preferred) and/or webhook receiver
+- Mention router: detect `@agentUsername` and decide whether to forward to agent
+- Routing/mapping: BasicOps conversation ↔ OpenClaw session
+
+2) **BasicOps MCP server (preferred for messaging)**
+- Tooling to list/create messages in:
+  - projects, tasks, channels, chats, groupchats
+- Tooling to read/update/delete messages + replies + reactions
+
+3) **BasicOps REST API (optional / supplemental)**
+- Used when MCP lacks an operation, or for identity enrichment if needed.
+
+4) **Mapping Store**
+- Persist mapping between:
+  - `basicopsConversationKey` ↔ `openclawSessionKey`
+  - `basicopsUserId` ↔ sender metadata
+  - optional: dedupe keys for inbound events
+
+### 5.2 Data flow
+
+**Outbound (OpenClaw → BasicOps)**
+1. Agent produces `message.send(channel="basicops", target=..., message=...)`.
+2. OpenClaw calls channel plugin `outbound.sendText({ account, target, text })`.
+3. Plugin resolves `target` into a BasicOps destination:
+   - projectId/taskId or conversationId
+4. Plugin POSTs to the appropriate BasicOps endpoint to create a note/comment/message.
+5. Plugin returns `{ ok: true }` or `{ ok: false, error }`.
+
+**Inbound (BasicOps → OpenClaw)**
+
+Primary path (Webhooks; required):
+1. BasicOps emits webhook payloads to the connector’s public URL.
+2. **Payload shape (from existing Webhooks Shim MVP):** BasicOps may batch events:
+   - top-level `body.events[]`
+   - each event has `{ event: string, records: any[] }`
+
+   **Observed messaging event names (via MCP `list_webhooks`):**
+   - `basicops.task.message.created`
+   - `basicops.project.message.created`
+   - `basicops.chat.message.created`
+   - `basicops.groupchat.message.created`
+   - `basicops.channel.message.created`
+   - replies:
+     - `basicops.task.reply.created`
+     - `basicops.project.reply.created`
+     - `basicops.chat.reply.created`
+     - `basicops.groupchat.reply.created`
+     - `basicops.channel.reply.created`
+
+   (The older shim example also shows non-message events like `basicops:task:created`.)
+3. Validate authenticity.
+   - If BasicOps provides signatures: validate HMAC + timestamp/replay.
+   - If BasicOps does **not** provide signatures (current shim does not verify any): use an unguessable URL path token + optional allowlist + strict JSON validation + dedupe.
+4. Normalize each record into a common message model:
+   - `containerType` (project/task/channel/chat/groupchat)
+   - `containerId`
+   - `messageId`
+   - `sender` (userId + display)
+   - `text` (and later attachments)
+5. Detect mention:
+   - if `respondOnlyWhenMentioned=true`, only forward messages containing `@<agentUsername>`.
+6. Find/create the OpenClaw session key for `containerType:containerId`.
+7. Forward into that OpenClaw session with sender metadata.
+
+Fallback/backfill (allowed but not primary):
+- MCP can be used to backfill context, resolve missing sender names, or recover from missed webhooks.
+- Short-interval polling is only acceptable for recovery or diagnostics, not as the main inbound mechanism.
+
+## 6) Routing + identity mapping
+
+### 6.1 Conversation mapping
+
+We need stable keys:
+
+- `basicopsConversationKey` (string):
+  - `project:<projectId>` OR `task:<taskId>`
+- `openclawSessionKey`:
+  - Prefer deterministic mapping like: `basicops:<accountId>:<basicopsConversationKey>`
+  - Or use OpenClaw session creation + store the mapping.
+
+**Recommendation:** deterministic session keys when OpenClaw allows it; otherwise persist mapping.
+
+### 6.2 User identity
+
+Map BasicOps users into OpenClaw sender metadata:
+
+- `sender.provider = "basicops"`
+- `sender.id = <basicopsUserId>`
+- `sender.label/name = <displayName>`
+
+If webhook payload does not include display name, fetch `/v1/user/<id>` and cache.
+
+## 7) Webhook security
+
+Target: Telegram-like responsiveness with production-grade verification.
+
+Reality (per existing Webhooks Shim MVP): current shim code does **not** verify signatures, implying BasicOps webhooks may not currently ship an HMAC signature header.
+
+Therefore the spec supports two modes:
+
+1) **Signed webhooks (ideal, if BasicOps provides it)**
+- Require a `webhooks.secret`.
+- Validate request signature (e.g., HMAC SHA256 of raw body) + timestamp/replay.
+
+2) **Unsigned webhooks (acceptable fallback)**
+- Use an unguessable path token, e.g. `/channels/basicops/webhook/<random>`.
+- Optionally add IP allowlisting at the reverse proxy.
+- Strict JSON schema validation.
+- Deduplicate by event id / hash.
+
+Reference MVP:
+- Receiver: `basicops-ops/scripts/webhook-receiver.mjs`
+- Example webhook creation: `basicops-ops/scripts/create-project-tag-webhook.mjs`
+
+## 8) Reliability & retries
+
+### 8.1 Outbound
+- Retry on transient failures (429/5xx) with backoff.
+- Log request ids / BasicOps response ids.
+- Return actionable error strings (status + body snippet).
+
+### 8.2 Inbound
+- Acknowledge webhooks quickly (2xx) and process asynchronously if supported.
+- Deduplicate events if BasicOps sends retries:
+  - Keep a small cache of event ids/hashes.
+
+## 9) Observability
+
+- Add `status` adapter (optional) to surface:
+  - token validity check
+  - webhook configured state
+  - last inbound event time
+- Structured logs:
+  - `accountId`, `conversationKey`, `basicopsEventId`
+
+## 10) OpenClaw “what changed since Feb 15?” (investigation)
+
+Local OpenClaw version on this host:
+- **OpenClaw 2026.3.13 (61d171a)**
+
+Key plugin/channel API notes from current `docs/tools/plugin.md`:
+- Channel plugins still register via `api.registerChannel({ plugin })`.
+- Config remains under `channels.<id>`.
+- **Newer/clarified capabilities** since earlier docs:
+  - `meta.preferOver`, `meta.detailLabel`, `meta.systemImage` (richer UI metadata)
+- **Channel onboarding hooks** are documented and appear to be first-class now:
+  - `plugin.onboarding.configure`, `configureInteractive`, `configureWhenConfigured`
+  - These can be used to guide users through token + webhook setup.
+
+No breaking change was observed in the minimal channel registration pattern; however, the onboarding hooks are worth using to reduce setup friction.
+
+(If you want a stricter diff vs Feb 15, we can compare the OpenClaw npm package changelog or git tags between those dates—this host only shows the currently installed docs.)
+
+## 11) Implementation plan (phased)
+
+### Phase 0 — Confirm webhook event schema + mention semantics
+- Confirm BasicOps webhook events for **message created** across all containers.
+- Confirm the BasicOps username to treat as the agent mention target (e.g., `@Gus`).
+- Collect:
+  - example webhook payloads for each message container (project/task/channel/chat/groupchat)
+  - signature scheme (headers, algorithm, timestamp/replay)
+  - how to fetch “recent context” in-thread via MCP (tool args + paging)
+
+### Phase 1 — Outbound-only MVP
+- Replace placeholder `/v1/messages/send` with real endpoint(s).
+- Implement:
+  - input validation
+  - request building
+  - error handling
+- Add unit tests for payload mapping.
+
+### Phase 2 — Inbound webhook
+- Add webhook handler entrypoint (OpenClaw gateway route / channel inbound adapter depending on SDK expectations).
+- Implement signature verification.
+- Implement mapping store (sqlite recommended).
+- Route inbound events into sessions.
+
+### Phase 3 — Quality
+- Deduplication
+- richer metadata (sender name, links back to BasicOps)
+- health/status commands
+
+### Phase 4 — Rich features
+- attachments (download/thumbnail endpoints exist for tasks)
+- reactions (if supported)
+- edits/deletes
+
+## 12) Open questions / required inputs
+
+1) What is “messaging” in BasicOps for this connector?
+   - project notes, task comments, or separate messaging API?
+2) What is the webhook payload schema + signature scheme?
+3) Do we need multi-workspace support (multiple BasicOps orgs) per OpenClaw account?
+4) What should `target` look like from OpenClaw?
+   - raw id (`123`), or typed (`project:123`)?
+
+---
+
+Appendix: Scaffold location
+- `/home/gus/.openclaw/workspace/basicops-openclaw-channel/`
+- `src/index.ts` registers channel + has outbound stub (currently placeholder endpoint).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# openclaw-channel-basicops
+
+BasicOps messaging channel connector for OpenClaw.
+
+- **Inbound:** BasicOps Webhooks (push-based, Telegram-like responsiveness)
+- **Outbound:** BasicOps MCP tools (create message in project/task/channel/chat/groupchat)
+- **Agent triggering:** mention-gated (`@<agentUsername>`) by default
+
+## Install (npm)
+
+```bash
+npm i openclaw-channel-basicops
+```
+
+## Enable in OpenClaw
+
+### 1) Load the plugin
+
+Add to your OpenClaw config:
+
+```json5
+{
+  plugins: {
+    load: {
+      paths: [
+        // if installed into the same environment as the gateway
+        "./node_modules/openclaw-channel-basicops/dist/index.js"
+      ]
+    }
+  }
+}
+```
+
+### 2) Configure the channel
+
+```json5
+{
+  channels: {
+    basicops: {
+      accounts: {
+        default: {
+          enabled: true,
+
+          // BasicOps MCP (MVP): paste an OAuth access token
+          mcp: {
+            accessToken: "...",
+            baseUrl: "https://app.basicops.com/mcp/sse"
+          },
+
+          // Mention routing
+          agentUsername: "Gus",
+          respondOnlyWhenMentioned: true,
+
+          // Webhook auth (recommended): unguessable path token
+          webhooks: {
+            enabled: true,
+            pathToken: "<random-long-token>"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Configure BasicOps Webhooks
+
+Point BasicOps webhooks at:
+
+- `https://<your-gateway-public>/channels/basicops/webhook/<pathToken>`
+
+Subscribe to these event types (observed via MCP `list_webhooks`):
+
+- `basicops.task.message.created`
+- `basicops.project.message.created`
+- `basicops.chat.message.created`
+- `basicops.groupchat.message.created`
+- `basicops.channel.message.created`
+- `basicops.task.reply.created`
+- `basicops.project.reply.created`
+- `basicops.chat.reply.created`
+- `basicops.groupchat.reply.created`
+- `basicops.channel.reply.created`
+
+## Sending messages from OpenClaw
+
+Use typed targets:
+
+- `task:<id>`
+- `project:<id>`
+- `channel:<id>`
+- `chat:<id>`
+- `groupchat:<id>`
+
+Example (tool call semantics vary by your agent tooling):
+
+- send to a task thread: `target="task:2103656"`
+
+## Notes / Roadmap
+
+- OAuth onboarding (no more pasted tokens)
+- Signature verification if/when BasicOps provides webhook signatures
+- Rich features: attachments, reactions, edits/deletes

package/dist/basicops-mcp.js

@@ -0,0 +1,108 @@
+// Minimal BasicOps MCP-over-SSE client (ported from skills/basicops-mcp/scripts/basicops_mcp.py)
+//
+// Notes:
+// - This intentionally keeps things simple: each tool call performs an SSE handshake
+//   to obtain a message endpoint, then POSTs a single JSON-RPC request.
+// - For production we may want connection reuse, retries, and token refresh.
+const DEFAULT_SSE_URL = "https://app.basicops.com/mcp/sse";
+const DEFAULT_PROTOCOL_VERSION = "2024-11-05";
+async function handshake(opts) {
+    const initPayload = {
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+            protocolVersion: opts.protocolVersion,
+            capabilities: {},
+            clientInfo: { name: "OpenClaw", version: "0.1" },
+        },
+    };
+    const res = await fetch(opts.baseUrl, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${opts.accessToken}`,
+            Accept: "text/event-stream",
+            "Content-Type": "application/json",
+            "Cache-Control": "no-cache",
+        },
+        body: JSON.stringify(initPayload),
+    });
+    if (!res.ok || !res.body) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`MCP handshake failed (${res.status}): ${body}`);
+    }
+    // Read SSE lines until we see the first `data: ...` line (endpoint)
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    const deadline = Date.now() + 20_000;
+    while (Date.now() < deadline) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buf += decoder.decode(value, { stream: true });
+        // SSE lines end with \n. We'll parse line-by-line.
+        let idx;
+        while ((idx = buf.indexOf("\n")) !== -1) {
+            const line = buf.slice(0, idx).trimEnd();
+            buf = buf.slice(idx + 1);
+            if (line.startsWith("data: ")) {
+                let endpoint = line.slice("data: ".length).trim();
+                if (!endpoint)
+                    continue;
+                if (endpoint.startsWith("/"))
+                    endpoint = `https://app.basicops.com${endpoint}`;
+                return endpoint;
+            }
+        }
+    }
+    throw new Error("MCP handshake failed: no endpoint returned");
+}
+export async function callMcpTool(opts) {
+    const baseUrl = opts.mcp.baseUrl || DEFAULT_SSE_URL;
+    const accessToken = opts.mcp.accessToken;
+    const protocolVersion = opts.mcp.protocolVersion || DEFAULT_PROTOCOL_VERSION;
+    if (!accessToken) {
+        throw new Error("Missing BasicOps MCP access token (channels.basicops.accounts.<id>.mcp.accessToken)");
+    }
+    const endpoint = await handshake({ baseUrl, accessToken, protocolVersion });
+    const payload = {
+        jsonrpc: "2.0",
+        id: opts.requestId ?? 2,
+        method: "tools/call",
+        params: {
+            name: opts.tool,
+            arguments: opts.args ?? {},
+        },
+    };
+    const res = await fetch(endpoint, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            Accept: "application/json",
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+    });
+    const raw = await res.text().catch(() => "");
+    if (!res.ok) {
+        throw new Error(`MCP tool call failed (${res.status}): ${raw}`);
+    }
+    let json;
+    try {
+        json = raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        throw new Error(`MCP tool call returned non-JSON: ${raw.slice(0, 400)}`);
+    }
+    // BasicOps MCP may return { result: { isError: true, content: [...] } }
+    const isError = Boolean(json?.result?.isError);
+    if (isError) {
+        const content = json?.result?.content;
+        const text = Array.isArray(content)
+            ? content.map((c) => (c && typeof c === "object" ? c.text : "")).join(" ")
+            : "";
+        throw new Error(`MCP tool error: ${text || "(unknown)"}`);
+    }
+    return json;
+}

package/dist/index.js

@@ -0,0 +1,272 @@
+import { callMcpTool } from "./basicops-mcp.js";
+function listAccountIds(cfg) {
+    return Object.keys(cfg?.channels?.basicops?.accounts ?? {});
+}
+function resolveAccount(cfg, accountId) {
+    const resolved = cfg?.channels?.basicops?.accounts?.[accountId ?? "default"];
+    const account = resolved ?? { accountId };
+    // Minimal configured heuristic
+    account.configured = Boolean(account?.enabled && (account?.mcp?.accessToken || account?.apiToken));
+    return account;
+}
+function normalizeTarget(raw) {
+    const s = String(raw || "").trim();
+    const m = s.match(/^(project|task|channel|chat|groupchat)\s*:\s*(.+)$/i);
+    if (m)
+        return { containerType: m[1].toLowerCase(), containerId: String(m[2]).trim() };
+    // If not typed, assume task id (common) — caller should prefer typed targets.
+    return { containerType: "task", containerId: s };
+}
+function buildMentionRegex(agentUsername) {
+    // Match @Username with a loose boundary so @Gus, @Gus, etc.
+    // We intentionally do not enforce word boundaries too strictly because some UIs
+    // include punctuation.
+    const escaped = agentUsername.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|\\s)@${escaped}(\\b|$)`, "i");
+}
+function extractText(record) {
+    // Best-effort: BasicOps record shapes may vary per container.
+    return (record?.message ??
+        record?.text ??
+        record?.body ??
+        record?.content ??
+        record?.Message ??
+        record?.Text ??
+        "").toString();
+}
+function extractSender(record) {
+    const senderId = (record?.UserId ??
+        record?.userId ??
+        record?.SenderId ??
+        record?.senderId ??
+        record?.FromUserId ??
+        record?.fromUserId ??
+        "unknown").toString();
+    const senderLabel = (record?.UserName ??
+        record?.username ??
+        record?.SenderName ??
+        record?.senderName ??
+        record?.FromUserName ??
+        record?.fromUserName ??
+        undefined);
+    return { senderId, senderLabel };
+}
+function extractContainerFromEvent(eventName, record) {
+    const e = String(eventName || "").toLowerCase();
+    if (e.includes("task.")) {
+        const id = record?.TaskId ?? record?.taskId ?? record?.TaskID ?? record?.taskID;
+        return { containerType: "task", containerId: String(id ?? record?.Task ?? record?.task ?? "") };
+    }
+    if (e.includes("project.")) {
+        const id = record?.ProjectId ?? record?.projectId ?? record?.ProjectID ?? record?.projectID;
+        return { containerType: "project", containerId: String(id ?? record?.Project ?? record?.project ?? "") };
+    }
+    if (e.includes("groupchat.")) {
+        const id = record?.GroupchatId ?? record?.groupchatId ?? record?.GroupChatId ?? record?.groupChatId;
+        return { containerType: "groupchat", containerId: String(id ?? "") };
+    }
+    if (e.includes("channel.")) {
+        const id = record?.ChannelId ?? record?.channelId;
+        return { containerType: "channel", containerId: String(id ?? "") };
+    }
+    if (e.includes("chat.")) {
+        const id = record?.ChatId ?? record?.chatId;
+        return { containerType: "chat", containerId: String(id ?? "") };
+    }
+    // Fallback: try obvious keys
+    for (const k of ["taskId", "TaskId", "projectId", "ProjectId", "chatId", "ChatId", "groupchatId", "GroupchatId", "channelId", "ChannelId"]) {
+        if (record?.[k] != null) {
+            const v = String(record[k]);
+            const type = k.toLowerCase().includes("task")
+                ? "task"
+                : k.toLowerCase().includes("project")
+                    ? "project"
+                    : k.toLowerCase().includes("group")
+                        ? "groupchat"
+                        : k.toLowerCase().includes("channel")
+                            ? "channel"
+                            : "chat";
+            return { containerType: type, containerId: v };
+        }
+    }
+    return { containerType: "task", containerId: "" };
+}
+async function sendViaMcp(opts) {
+    const { account, target, text } = opts;
+    const mcp = account?.mcp;
+    if (!mcp?.accessToken) {
+        return { ok: false, error: "Missing channels.basicops.accounts.<id>.mcp.accessToken" };
+    }
+    const { containerType, containerId } = normalizeTarget(target);
+    const toolByType = {
+        project: "create_message_in_project",
+        task: "create_message_in_task",
+        channel: "create_message_in_channel",
+        chat: "create_message_in_chat",
+        groupchat: "create_message_in_groupchat",
+    };
+    const tool = toolByType[containerType];
+    if (!tool) {
+        return { ok: false, error: `Unsupported BasicOps target container: ${containerType}` };
+    }
+    // NOTE: BasicOps tools use different arg names; we standardize to id + message.
+    // We learned at least one schema expectation: create_message_in_chat expects `message` not `text`.
+    const idKeyByType = {
+        project: "projectId",
+        task: "taskId",
+        channel: "channelId",
+        chat: "chatId",
+        groupchat: "groupchatId",
+    };
+    const args = {
+        [idKeyByType[containerType]]: containerId,
+        message: text,
+    };
+    await callMcpTool({ mcp, tool, args });
+    return { ok: true };
+}
+const basicopsChannel = {
+    id: "basicops",
+    meta: {
+        id: "basicops",
+        label: "BasicOps",
+        selectionLabel: "BasicOps Messaging",
+        docsPath: "/channels/basicops",
+        blurb: "BasicOps messaging connector",
+        aliases: ["bo", "basicops-messaging"],
+    },
+    capabilities: {
+        chatTypes: ["direct", "group"],
+    },
+    reload: { configPrefixes: ["channels.basicops"] },
+    config: {
+        listAccountIds,
+        resolveAccount,
+        // Helps status/doctor flows avoid materializing secrets
+        inspectAccount: (cfg, accountId) => {
+            const a = resolveAccount(cfg, accountId);
+            return {
+                accountId: a.accountId ?? accountId ?? "default",
+                enabled: Boolean(a.enabled),
+                configured: Boolean(a.configured),
+                hasMcpToken: Boolean(a?.mcp?.accessToken),
+                hasApiToken: Boolean(a?.apiToken),
+            };
+        },
+    },
+    messaging: {
+        normalizeTarget: (target) => {
+            const { containerType, containerId } = normalizeTarget(target);
+            return `${containerType}:${containerId}`;
+        },
+        targetResolver: {
+            looksLikeId: (input) => /^(project|task|channel|chat|groupchat)\s*:\s*\S+$/i.test(input.trim()),
+            hint: "project:<id> | task:<id> | channel:<id> | chat:<id> | groupchat:<id>",
+        },
+    },
+    outbound: {
+        deliveryMode: "direct",
+        sendText: async ({ account, target, to, text }) => {
+            const dest = target ?? to;
+            if (!dest)
+                return { ok: false, error: "Missing target/to" };
+            return sendViaMcp({ account, target: dest, text: text ?? "" });
+        },
+    },
+};
+export default function register(api) {
+    api.registerChannel({ plugin: basicopsChannel });
+    // Webhook route (plugin-managed auth)
+    // Recommended gateway path: /channels/basicops/webhook/<pathToken>
+    api.registerHttpRoute({
+        path: "/channels/basicops/webhook",
+        auth: "plugin",
+        match: "prefix",
+        handler: async (req, res) => {
+            try {
+                if (req.method !== "POST") {
+                    res.statusCode = 200;
+                    res.end("ok");
+                    return true;
+                }
+                // Read raw body
+                const chunks = [];
+                await new Promise((resolve, reject) => {
+                    req.on("data", (c) => chunks.push(c));
+                    req.on("end", () => resolve());
+                    req.on("error", (e) => reject(e));
+                });
+                const raw = Buffer.concat(chunks).toString("utf8");
+                const body = raw ? JSON.parse(raw) : {};
+                // Determine accountId; default only for now.
+                const cfg = api.runtime.config.loadConfig();
+                const accountId = "default";
+                const account = resolveAccount(cfg, accountId);
+                // Path token check (if configured)
+                const token = account?.webhooks?.pathToken;
+                if (token) {
+                    const url = String(req.url || "");
+                    // req.url includes the path from this route, e.g. /channels/basicops/webhook/<token>
+                    const parts = url.split("?")[0].split("/").filter(Boolean);
+                    const idx = parts.findIndex((p) => p === "webhook");
+                    const got = idx >= 0 ? parts[idx + 1] : null;
+                    if (got !== token) {
+                        res.statusCode = 401;
+                        res.end("unauthorized");
+                        return true;
+                    }
+                }
+                const agentUsername = (account.agentUsername || "Gus").trim();
+                const mentionRe = buildMentionRegex(agentUsername);
+                const mentionOnly = account.respondOnlyWhenMentioned !== false;
+                const events = Array.isArray(body?.events) ? body.events : [];
+                // Ack quickly; OpenClaw pipeline work happens after parsing anyway.
+                res.statusCode = 200;
+                res.setHeader("content-type", "application/json");
+                res.end(JSON.stringify({ ok: true }));
+                // Process events after ACK
+                for (const ev of events) {
+                    const eventName = String(ev?.event || ev?.name || "");
+                    const records = Array.isArray(ev?.records) ? ev.records : [];
+                    for (const record of records) {
+                        const text = extractText(record);
+                        if (!text)
+                            continue;
+                        if (mentionOnly && !mentionRe.test(text))
+                            continue;
+                        const { senderId, senderLabel } = extractSender(record);
+                        const { containerType, containerId } = extractContainerFromEvent(eventName, record);
+                        if (!containerId)
+                            continue;
+                        const chatId = `${containerType}:${containerId}`;
+                        const chatType = containerType === "chat" ? "direct" : "group";
+                        const runtime = api.runtime;
+                        await runtime.channel.reply.handleInboundMessage?.({
+                            channel: "basicops",
+                            accountId,
+                            senderId,
+                            senderLabel,
+                            chatType,
+                            chatId,
+                            text,
+                            // Provide a reply callback that posts back into the same container.
+                            reply: async (responseText) => {
+                                await sendViaMcp({ account, target: chatId, text: responseText });
+                            },
+                        });
+                    }
+                }
+                return true;
+            }
+            catch (err) {
+                api.logger?.error?.(`basicops webhook error: ${err?.message || String(err)}`);
+                try {
+                    res.statusCode = 500;
+                    res.end("error");
+                }
+                catch { }
+                return true;
+            }
+        },
+    });
+}

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "basicops",
+  "name": "BasicOps",
+  "description": "BasicOps messaging channel connector (webhooks inbound + MCP outbound)",
+  "version": "0.1.0",
+  "entry": "dist/index.js",
+  "tags": ["channel", "basicops", "messaging"],
+  "docs": {
+    "channelDocsPath": "/channels/basicops"
+  }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "openclaw-channel-basicops",
+  "version": "0.1.0",
+  "description": "BasicOps messaging channel connector for OpenClaw (webhooks inbound + MCP outbound)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "openclaw.plugin.json",
+    "README.md",
+    "DESIGN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -w -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "openclaw": ">=2026.3.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  },
+  "license": "MIT"
+}