@andocorp/openclaw-plugin 0.0.1

package/index.ts

@@ -0,0 +1,21 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import {
+  createPluginRuntimeStore,
+  type PluginRuntime,
+} from "openclaw/plugin-sdk/runtime-store";
+import { andoPlugin } from "./src/channel.js";
+import { registerAndoMcpTools } from "./src/mcp-tools.js";
+
+const { setRuntime: setAndoRuntime } =
+  createPluginRuntimeStore<PluginRuntime>("Ando runtime not initialized");
+
+export default defineChannelPluginEntry({
+  id: "ando",
+  name: "Ando",
+  description: "OpenClaw adapter for Ando",
+  plugin: andoPlugin,
+  setRuntime: setAndoRuntime,
+  registerFull(api) {
+    registerAndoMcpTools(api);
+  },
+});

package/openclaw.plugin.json

@@ -0,0 +1,8 @@
+{
+  "id": "ando",
+  "channels": ["ando"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false
+  }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@andocorp/openclaw-plugin",
+  "version": "0.0.1",
+  "description": "OpenClaw adapter for Ando",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "typecheck": "pnpm --filter @andocorp/sdk build && tsc --noEmit",
+    "test": "pnpm --filter @andocorp/sdk build && vitest run",
+    "test:boundaries": "pnpm --filter @andocorp/sdk build && vitest run src/monitor.test.ts src/channel.test.ts"
+  },
+  "dependencies": {
+    "@andocorp/sdk": "workspace:*",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.23"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.9",
+    "openclaw": "2026.3.23",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "ando",
+      "label": "Ando",
+      "selectionLabel": "Ando",
+      "docsPath": "/channels/ando",
+      "blurb": "Live agent membership inside Ando conversations."
+    }
+  }
+}

package/src/channel.ts

@@ -0,0 +1,287 @@
+import {
+  buildChannelConfigSchema,
+  ChannelPlugin,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk/core";
+import packageJson from "../package.json" with { type: "json" };
+import { DEFAULT_ACCOUNT_ID } from "openclaw/plugin-sdk/account-resolution";
+import { createTopLevelChannelConfigBase } from "openclaw/plugin-sdk/channel-config-helpers";
+import { formatAndoTarget, parseAndoTarget } from "@andocorp/sdk";
+import { z } from "zod";
+import { postAndoMessage } from "./client.js";
+import { monitorAndoProvider } from "./monitor.js";
+import { ResolvedAndoAccount } from "./types.js";
+
+const meta = packageJson.openclaw.channel as {
+  id: string;
+  label: string;
+  selectionLabel: string;
+  docsPath: string;
+  blurb: string;
+};
+
+type AndoConfig = {
+  baseUrl?: string;
+  apiKey?: string;
+  realtimeHost?: string;
+  mcpUrl?: string;
+};
+
+function trimValue(value?: string | null): string {
+  return (value ?? "").trim();
+}
+
+function normalizeUrl(value?: string | null): string {
+  return trimValue(value).replace(/\/+$/, "");
+}
+
+function waitForAbort(signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+
+    signal?.addEventListener("abort", () => resolve(), {
+      once: true,
+    });
+  });
+}
+export function resolveAndoMcpUrl(params: {
+  baseUrl: string;
+  mcpUrl?: string | null;
+}): string {
+  const explicitMcpUrl = normalizeUrl(params.mcpUrl);
+  if (explicitMcpUrl) {
+    return explicitMcpUrl;
+  }
+
+  const baseUrl = normalizeUrl(params.baseUrl);
+  return baseUrl ? `${baseUrl}/mcp` : "";
+}
+export function resolveAndoAccount(cfg: OpenClawConfig): ResolvedAndoAccount {
+  const config = (cfg.channels?.ando ?? {}) as AndoConfig;
+  const realtimeHost = normalizeUrl(config.realtimeHost);
+
+  return {
+    accountId: DEFAULT_ACCOUNT_ID,
+    baseUrl: normalizeUrl(config.baseUrl),
+    apiKey: trimValue(config.apiKey),
+    realtimeHost: realtimeHost || null,
+    mcpUrl: resolveAndoMcpUrl({
+      baseUrl: config.baseUrl ?? "",
+      mcpUrl: config.mcpUrl,
+    }),
+  };
+}
+
+const AndoConfigSchema = z
+  .object({
+    baseUrl: z.string().optional(),
+    apiKey: z.string().optional(),
+    realtimeHost: z.string().optional(),
+    mcpUrl: z.string().optional(),
+  })
+  .strict();
+
+const andoConfigBase = createTopLevelChannelConfigBase<
+  ResolvedAndoAccount,
+  OpenClawConfig
+>({
+  sectionKey: "ando",
+  resolveAccount: (cfg) => resolveAndoAccount(cfg),
+  listAccountIds: () => [DEFAULT_ACCOUNT_ID],
+  defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+  deleteMode: "clear-fields",
+  clearBaseFields: ["baseUrl", "apiKey", "realtimeHost", "mcpUrl"],
+});
+
+type AndoOutboundParams = {
+  cfg: OpenClawConfig;
+  to: string;
+  text: string;
+  replyToId?: string | null;
+  threadId?: string | number | null;
+};
+
+function isAndoRestConfigured(account: ResolvedAndoAccount): boolean {
+  return Boolean(account.baseUrl && account.apiKey);
+}
+
+function assertAndoRestConfigured(account: ResolvedAndoAccount): void {
+  if (!isAndoRestConfigured(account)) {
+    throw new Error(
+      `[ando] account "${account.accountId}" is missing baseUrl or apiKey`,
+    );
+  }
+}
+
+function assertAndoRealtimeConfigured(account: ResolvedAndoAccount): void {
+  assertAndoRestConfigured(account);
+
+  if (!account.realtimeHost) {
+    throw new Error(
+      `[ando] account "${account.accountId}" is missing realtimeHost for realtime monitoring`,
+    );
+  }
+}
+
+export function resolveThreadRootId(params: {
+  replyToId?: string | null;
+  threadId?: string | number | null;
+}): string | null {
+  const threadId = typeof params.threadId === "string" ? params.threadId.trim() : "";
+  if (threadId) {
+    return threadId;
+  }
+
+  const replyToId = params.replyToId?.trim();
+  if (replyToId) {
+    return replyToId;
+  }
+
+  return null;
+}
+
+function parseExplicitAndoChannelTarget(value?: string | null) {
+  const trimmed = value?.trim() ?? "";
+  if (!trimmed) {
+    return null;
+  }
+
+  const normalized = trimmed.replace(/^ando:/i, "").trim();
+  if (!/^(conversation|channel|group|room):/i.test(normalized)) {
+    return null;
+  }
+
+  const parsed = parseAndoTarget(trimmed);
+  return parsed?.kind === "channel" ? parsed : null;
+}
+
+function resolveAndoMentionStripPatterns(): string[] {
+  return ["<!member_group:[^>]+>"];
+}
+
+async function sendAndoOutbound(
+  params: Omit<AndoOutboundParams, "text"> & { text?: string | null },
+) {
+  const target = parseExplicitAndoChannelTarget(params.to);
+  if (!target) {
+    throw new Error(`[ando] unsupported outbound target: ${params.to}`);
+  }
+
+  const account = resolveAndoAccount(params.cfg);
+  assertAndoRestConfigured(account);
+
+  const response = await postAndoMessage({
+    account,
+    conversationId: target.conversationId,
+    markdownContent: params.text?.trim() || null,
+    threadRootId: resolveThreadRootId({
+      replyToId: params.replyToId,
+      threadId: params.threadId,
+    }),
+  });
+
+  return {
+    messageId: response.id,
+    chatId: target.conversationId,
+    to: formatAndoTarget(target),
+  };
+}
+
+async function handleOutboundSend(params: AndoOutboundParams) {
+  return {
+    channel: "ando" as const,
+    ...(await sendAndoOutbound(params)),
+  };
+}
+
+export const andoPlugin: ChannelPlugin<ResolvedAndoAccount> = {
+  id: "ando",
+  meta,
+  capabilities: {
+    chatTypes: ["channel", "thread"],
+    threads: true,
+    media: false,
+    nativeCommands: false,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.ando"] },
+  configSchema: buildChannelConfigSchema(AndoConfigSchema),
+  config: {
+    ...andoConfigBase,
+    isConfigured: isAndoRestConfigured,
+    unconfiguredReason: (account) => {
+      if (!account.baseUrl || !account.apiKey) {
+        return "baseUrl and apiKey are required";
+      }
+      return "Ando channel is configured";
+    },
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      configured: isAndoRestConfigured(account),
+    }),
+    resolveAllowFrom: () => undefined,
+    formatAllowFrom: () => [],
+  },
+  groups: {
+    resolveRequireMention: () => true,
+  },
+  mentions: {
+    stripPatterns: () => resolveAndoMentionStripPatterns(),
+  },
+  messaging: {
+    normalizeTarget: (target) => {
+      const parsed = parseExplicitAndoChannelTarget(target);
+      return parsed ? formatAndoTarget(parsed) : target.trim();
+    },
+    targetResolver: {
+      looksLikeId: (input, normalized) =>
+        parseExplicitAndoChannelTarget(normalized ?? input) != null,
+      hint: "<conversation:uuid>",
+      resolveTarget: async ({ normalized }) => {
+        const parsed = parseExplicitAndoChannelTarget(normalized);
+        if (!parsed) {
+          return null;
+        }
+        return {
+          to: formatAndoTarget(parsed),
+          kind: "channel" as const,
+          source: "normalized" as const,
+        };
+      },
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    textChunkLimit: 12_000,
+    sendText: handleOutboundSend,
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      if (!account.realtimeHost) {
+        ctx.runtime.log?.(
+          `[ando] skipping realtime monitoring for account "${account.accountId}" because realtimeHost is not configured`
+        );
+        await waitForAbort(ctx.abortSignal);
+        return;
+      }
+
+      assertAndoRealtimeConfigured(account);
+      const channelRuntime = ctx.channelRuntime;
+      if (!channelRuntime) {
+        throw new Error("[ando] channelRuntime is required");
+      }
+
+      await monitorAndoProvider({
+        account,
+        cfg: ctx.cfg,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        channelRuntime,
+      });
+    },
+  },
+};

package/src/client.ts

@@ -0,0 +1,26 @@
+import { AndoClient } from "@andocorp/sdk";
+import { ResolvedAndoAccount } from "./types.js";
+
+export function createAndoSdkClient(account: ResolvedAndoAccount) {
+  return new AndoClient({
+    baseUrl: account.baseUrl,
+    realtimeHost: account.realtimeHost ?? undefined,
+    auth: {
+      apiKey: account.apiKey,
+    },
+  });
+}
+
+export async function postAndoMessage(params: {
+  account: ResolvedAndoAccount;
+  client?: AndoClient;
+  conversationId: string;
+  markdownContent: string | null;
+  threadRootId?: string | null;
+}) {
+  return (params.client ?? createAndoSdkClient(params.account)).postMessage({
+    conversationId: params.conversationId,
+    markdownContent: params.markdownContent,
+    threadRootId: params.threadRootId ?? null,
+  });
+}

package/src/mcp-tool-catalog.ts

@@ -0,0 +1,223 @@
+export const DEFAULT_MCP_INPUT_SCHEMA = {
+  type: "object",
+  properties: {},
+} as const;
+
+export type ToolDefinition = {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+};
+
+function stringProperty(description: string) {
+  return {
+    type: "string",
+    description,
+  } as const;
+}
+
+function numberProperty(description: string) {
+  return {
+    type: "number",
+    description,
+  } as const;
+}
+
+function objectSchema(
+  properties: Record<string, unknown>,
+  required: string[] = []
+) {
+  return {
+    type: "object",
+    properties,
+    ...(required.length > 0 ? { required } : {}),
+  } as const;
+}
+
+const CURATED_ANDO_MCP_TOOLS: ToolDefinition[] = [
+  {
+    name: "search_messages",
+    description:
+      "Search messages across conversations by keyword or semantic similarity. Requires a real search query — do not use wildcards like '*'. To browse recent messages or filter by author without a keyword, use get_conversation_messages instead.",
+    inputSchema: objectSchema(
+      {
+        q: stringProperty(
+          "Search query text — must be a real keyword or phrase, not a wildcard"
+        ),
+        author: stringProperty("Comma-separated member IDs to filter by author"),
+        conversation: stringProperty(
+          "Comma-separated conversation IDs to restrict search scope"
+        ),
+        thread: stringProperty(
+          "Thread root message ID to search within a specific thread"
+        ),
+        after: stringProperty(
+          "ISO timestamp — only include messages after this date"
+        ),
+        before: stringProperty(
+          "ISO timestamp — only include messages before this date"
+        ),
+        mode: {
+          type: "string",
+          enum: ["full-text", "semantic"],
+          description:
+            "Search mode: 'full-text' for keyword search (default), 'semantic' for AI-powered similarity",
+        },
+      },
+      ["q"]
+    ),
+  },
+  {
+    name: "search_members",
+    description:
+      "Search workspace members by name, email, or title. Returns matching member profiles.",
+    inputSchema: objectSchema(
+      {
+        q: stringProperty("Search query text"),
+      },
+      ["q"]
+    ),
+  },
+  {
+    name: "search_conversations",
+    description:
+      "Search conversations (channels and DMs) by name or description. Returns matching conversations with member counts.",
+    inputSchema: objectSchema(
+      {
+        q: stringProperty("Search query text"),
+      },
+      ["q"]
+    ),
+  },
+  {
+    name: "search_clipboard",
+    description:
+      "Search clipboard items (curated context bundles). Returns matching clipboards with title, description, and item count.",
+    inputSchema: objectSchema(
+      {
+        q: stringProperty("Search query text"),
+      },
+      ["q"]
+    ),
+  },
+  {
+    name: "search_calls",
+    description:
+      "Search calls by transcript content. Returns matching calls with participants, duration, and summary.",
+    inputSchema: objectSchema(
+      {
+        q: stringProperty("Search query text"),
+        conversation: stringProperty(
+          "Comma-separated conversation IDs to restrict search scope"
+        ),
+        after: stringProperty(
+          "ISO timestamp — only include calls after this date"
+        ),
+        before: stringProperty(
+          "ISO timestamp — only include calls before this date"
+        ),
+      },
+      ["q"]
+    ),
+  },
+  {
+    name: "get_message",
+    description:
+      "Fetch a single message by ID. Returns the full message with author, conversation, and content.",
+    inputSchema: objectSchema(
+      {
+        message_id: stringProperty("The message ID to look up"),
+      },
+      ["message_id"]
+    ),
+  },
+  {
+    name: "get_member",
+    description:
+      "Fetch a single workspace member by ID. Returns the member's profile including name, email, and title.",
+    inputSchema: objectSchema(
+      {
+        member_id: stringProperty("The member ID to look up"),
+      },
+      ["member_id"]
+    ),
+  },
+  {
+    name: "get_clipboard",
+    description:
+      "Fetch a clipboard (curated context bundle) by ID. Returns full clipboard with all items including messages, members, conversations, and files.",
+    inputSchema: objectSchema(
+      {
+        clipboard_id: stringProperty("The clipboard ID to look up"),
+      },
+      ["clipboard_id"]
+    ),
+  },
+  {
+    name: "get_call",
+    description:
+      "Fetch a call by ID, also called a jam. Returns call details including participants, duration, status, and summary.",
+    inputSchema: objectSchema(
+      {
+        call_id: stringProperty("The call ID to look up"),
+      },
+      ["call_id"]
+    ),
+  },
+  {
+    name: "get_call_transcript",
+    description:
+      "Fetch a paginated transcript for a call, also called a jam. Returns transcript segments with speaker names and timestamps. Use cursor for pagination.",
+    inputSchema: objectSchema(
+      {
+        call_id: stringProperty("The call ID"),
+        limit: numberProperty(
+          "Maximum number of segments to return (default 100)"
+        ),
+        cursor: stringProperty(
+          "Pagination cursor from a previous response's pageInfo.endCursor"
+        ),
+      },
+      ["call_id"]
+    ),
+  },
+  {
+    name: "get_conversation_messages",
+    description:
+      "Fetch paginated messages from a conversation. Returns messages in reverse chronological order. Use this to browse recent messages, optionally filtered by author. Use 'before' cursor for pagination.",
+    inputSchema: objectSchema(
+      {
+        conversation_id: stringProperty("The conversation ID"),
+        author: stringProperty("Comma-separated member IDs to filter by author"),
+        limit: numberProperty(
+          "Maximum number of messages to return (default 20)"
+        ),
+        before: stringProperty(
+          "Pagination cursor — fetch messages before this cursor (from pageInfo.startCursor)"
+        ),
+      },
+      ["conversation_id"]
+    ),
+  },
+  {
+    name: "get_thread_replies",
+    description:
+      "Fetch paginated replies to a thread root message. Use this when a message has replies_count > 0. Returns replies in chronological order (oldest first). Use 'after' cursor for pagination.",
+    inputSchema: objectSchema(
+      {
+        message_id: stringProperty("The thread root message ID"),
+        limit: numberProperty(
+          "Maximum number of replies to return (default 20)"
+        ),
+        after: stringProperty(
+          "Pagination cursor — fetch replies after this cursor (from pageInfo.endCursor)"
+        ),
+      },
+      ["message_id"]
+    ),
+  },
+];
+
+export function listCuratedAndoMcpTools(): ToolDefinition[] {
+  return CURATED_ANDO_MCP_TOOLS;
+}

package/src/mcp-tools.ts

@@ -0,0 +1,369 @@
+import { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk/core";
+import { resolveAndoAccount } from "./channel.js";
+import {
+  DEFAULT_MCP_INPUT_SCHEMA,
+  listCuratedAndoMcpTools,
+} from "./mcp-tool-catalog.js";
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+const MCP_ACCEPT_HEADER = "application/json, text/event-stream";
+
+type JsonRpcEnvelope = {
+  result?: unknown;
+  error?: {
+    message?: string;
+  };
+};
+
+type McpHttpResponse = {
+  ok: boolean;
+  status: number;
+  body: string;
+  sessionId: string | null;
+};
+
+function buildMcpJsonRpcRequest(params: {
+  id: string;
+  method: string;
+  params: Record<string, unknown>;
+}) {
+  return {
+    jsonrpc: "2.0" as const,
+    id: params.id,
+    method: params.method,
+    params: params.params,
+  };
+}
+
+function buildMcpJsonRpcNotification(params: {
+  method: string;
+  params?: Record<string, unknown>;
+}) {
+  return {
+    jsonrpc: "2.0" as const,
+    method: params.method,
+    ...(params.params ? { params: params.params } : {}),
+  };
+}
+
+function buildMcpRequestHeaders(apiKey: string, sessionId?: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: MCP_ACCEPT_HEADER,
+    Authorization: `Bearer ${apiKey}`,
+  };
+
+  if (sessionId) {
+    headers["mcp-session-id"] = sessionId;
+  }
+
+  return headers;
+}
+
+export function toAndoOpenClawToolName(toolName: string): string {
+  return `ando_${toolName}`;
+}
+
+export function extractMcpJsonPayload(raw: string): JsonRpcEnvelope {
+  const events = raw
+    .split(/\r?\n\r?\n/)
+    .map((chunk) =>
+      chunk
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trim())
+        .filter(Boolean)
+        .join("\n"),
+    )
+    .filter(Boolean);
+  const jsonText = (events.length > 0 ? events.at(-1) ?? "" : raw).trim();
+
+  if (!jsonText) {
+    throw new Error("Empty MCP response");
+  }
+
+  return JSON.parse(jsonText) as JsonRpcEnvelope;
+}
+
+function collectTextParts(content: unknown): string[] {
+  if (!Array.isArray(content)) {
+    return [];
+  }
+
+  return content.map((part) => {
+    const typedPart = asMcpTextPart(part);
+    if (typedPart?.type === "text") {
+      return typedPart.text ?? "";
+    }
+
+    return JSON.stringify(part, null, 2);
+  });
+}
+
+type McpToolResult = {
+  structuredContent?: unknown;
+  content?: unknown;
+  isError?: boolean;
+};
+
+function asMcpTextPart(value: unknown): { type?: string; text?: string } | null {
+  if (!value || typeof value !== "object" || !("type" in value)) {
+    return null;
+  }
+
+  return value as { type?: string; text?: string };
+}
+
+function asMcpToolResult(value: unknown): McpToolResult {
+  if (!value || typeof value !== "object") {
+    return {};
+  }
+
+  return value as McpToolResult;
+}
+
+export function formatMcpToolResultText(result: McpToolResult): string {
+  if (result?.structuredContent != null) {
+    return JSON.stringify(result.structuredContent, null, 2);
+  }
+
+  const textParts = collectTextParts(result?.content);
+  if (textParts.length > 0) {
+    return textParts.join("\n");
+  }
+
+  return JSON.stringify(result, null, 2);
+}
+
+function extractMcpResultErrorMessage(result: McpToolResult): string {
+  const textParts = collectTextParts(result?.content);
+  for (const text of textParts) {
+    try {
+      const parsed = JSON.parse(text) as { error?: unknown };
+      if (typeof parsed.error === "string" && parsed.error.trim()) {
+        return parsed.error;
+      }
+    } catch {
+      // Ignore non-JSON content and fall back to the raw text below.
+    }
+
+    const trimmed = text.trim();
+    if (trimmed) {
+      return trimmed;
+    }
+  }
+
+  return formatMcpToolResultText(result);
+}
+
+function ensureMcpOk(payload: JsonRpcEnvelope): void {
+  if (payload.error) {
+    throw new Error(payload.error.message ?? "Unknown MCP error");
+  }
+
+  if (
+    payload.result &&
+    typeof payload.result === "object" &&
+    "isError" in payload.result &&
+    (payload.result as McpToolResult).isError
+  ) {
+    throw new Error(extractMcpResultErrorMessage(payload.result as McpToolResult));
+  }
+}
+
+function ensureMcpHttpOk(response: McpHttpResponse, action: string): void {
+  if (response.ok) {
+    return;
+  }
+
+  throw new Error(`MCP ${action} failed: ${response.status} ${response.body}`);
+}
+
+async function runMcpJsonRpc(params: {
+  mcpUrl: string;
+  apiKey: string;
+  action: string;
+  request: Record<string, unknown>;
+  sessionId?: string;
+}): Promise<McpHttpResponse> {
+  const response = await fetch(params.mcpUrl, {
+    method: "POST",
+    headers: buildMcpRequestHeaders(params.apiKey, params.sessionId),
+    body: JSON.stringify(params.request),
+  });
+  const body = await response.text();
+  const result: McpHttpResponse = {
+    ok: response.ok,
+    status: response.status,
+    body,
+    sessionId: response.headers.get("mcp-session-id"),
+  };
+  ensureMcpHttpOk(result, params.action);
+  return result;
+}
+
+async function closeMcpSession(params: {
+  mcpUrl: string;
+  apiKey: string;
+  sessionId: string;
+}): Promise<void> {
+  const response = await fetch(params.mcpUrl, {
+    method: "DELETE",
+    headers: buildMcpRequestHeaders(params.apiKey, params.sessionId),
+  });
+
+  if (response.ok) {
+    return;
+  }
+
+  const body = await response.text();
+  ensureMcpHttpOk(
+    {
+      ok: response.ok,
+      status: response.status,
+      body,
+      sessionId: response.headers.get("mcp-session-id"),
+    },
+    "session/delete"
+  );
+}
+
+async function initializeMcpSession(mcpUrl: string, apiKey: string): Promise<string> {
+  const response = await runMcpJsonRpc({
+    mcpUrl,
+    apiKey,
+    action: "initialize",
+    request: buildMcpJsonRpcRequest({
+      id: "1",
+      method: "initialize",
+      params: {
+        protocolVersion: MCP_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: {
+          name: "openclaw-ando-plugin",
+          version: "1.0",
+        },
+      },
+    }),
+  });
+
+  const payload = extractMcpJsonPayload(response.body);
+  ensureMcpOk(payload);
+
+  const sessionId = response.sessionId?.trim();
+  if (!sessionId) {
+    throw new Error("Missing MCP session ID");
+  }
+
+  return sessionId;
+}
+
+async function notifyMcpSessionInitialized(params: {
+  mcpUrl: string;
+  apiKey: string;
+  sessionId: string;
+}): Promise<void> {
+  await runMcpJsonRpc({
+    mcpUrl: params.mcpUrl,
+    apiKey: params.apiKey,
+    sessionId: params.sessionId,
+    action: "notifications/initialized",
+    request: buildMcpJsonRpcNotification({
+      method: "notifications/initialized",
+    }),
+  });
+}
+
+async function callAndoMcpTool(params: {
+  mcpUrl: string;
+  apiKey: string;
+  name: string;
+  arguments_: Record<string, unknown>;
+}): Promise<string> {
+  const sessionId = await initializeMcpSession(params.mcpUrl, params.apiKey);
+  try {
+    await notifyMcpSessionInitialized({
+      mcpUrl: params.mcpUrl,
+      apiKey: params.apiKey,
+      sessionId,
+    });
+
+    const response = await runMcpJsonRpc({
+      mcpUrl: params.mcpUrl,
+      apiKey: params.apiKey,
+      sessionId,
+      action: `tools/call(${params.name})`,
+      request: buildMcpJsonRpcRequest({
+        id: "2",
+        method: "tools/call",
+        params: {
+          name: params.name,
+          arguments: params.arguments_,
+        },
+      }),
+    });
+
+    const payload = extractMcpJsonPayload(response.body);
+    ensureMcpOk(payload);
+    return formatMcpToolResultText(asMcpToolResult(payload.result));
+  } finally {
+    await closeMcpSession({
+      mcpUrl: params.mcpUrl,
+      apiKey: params.apiKey,
+      sessionId,
+    }).catch(() => undefined);
+  }
+}
+
+export function registerAndoMcpTools(
+  api: Pick<OpenClawPluginApi, "config" | "registerTool" | "logger">,
+) {
+  const tools = listCuratedAndoMcpTools();
+
+  for (const tool of tools) {
+    const openClawToolName = toAndoOpenClawToolName(tool.name);
+    api.registerTool((context: OpenClawPluginToolContext) => {
+      const account = resolveAndoAccount(context.config ?? {});
+
+      if (!account.mcpUrl || !account.apiKey) {
+        return null;
+      }
+
+      const mcpUrl = account.mcpUrl;
+
+      return {
+        name: openClawToolName,
+        label: openClawToolName,
+        description: tool.description
+          ? `Ando MCP: ${tool.description}`
+          : "Ando MCP tool",
+        parameters: (tool.inputSchema ?? DEFAULT_MCP_INPUT_SCHEMA) as Record<
+          string,
+          unknown
+        >,
+        async execute(_toolCallId: string, params: Record<string, unknown>) {
+          try {
+            const text = await callAndoMcpTool({
+              mcpUrl,
+              apiKey: account.apiKey,
+              name: tool.name,
+              arguments_: params,
+            });
+
+            return {
+              content: [{ type: "text" as const, text }],
+              details: null,
+            };
+          } catch (error) {
+            const message =
+              error instanceof Error ? error.message : String(error);
+            throw new Error(`Error calling Ando MCP tool ${tool.name}: ${message}`);
+          }
+        },
+      };
+    });
+  }
+
+  api.logger.info?.(
+    `[ando] registered ${tools.length} curated MCP tool proxy factories`
+  );
+}

package/src/monitor.ts

@@ -0,0 +1,394 @@
+import {
+  resolveThreadSessionKeys,
+  OpenClawConfig,
+  PluginRuntime,
+} from "openclaw/plugin-sdk/core";
+import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
+import {
+  createNormalizedOutboundDeliverer,
+  deliverFormattedTextWithAttachments,
+} from "openclaw/plugin-sdk/reply-payload";
+import {
+  formatAndoTarget,
+  AndoConversation,
+  AndoNormalizedMessageCreatedEvent,
+} from "@andocorp/sdk";
+import { createAndoSdkClient, postAndoMessage } from "./client.js";
+import { ResolvedAndoAccount } from "./types.js";
+
+type MonitorRuntime = {
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+const ANDO_MEMBER_GROUP_MENTION_REGEX = /(^|\s)<!member_group:[^>]+>\s*/g;
+type AndoInboundHistory =
+  NonNullable<AndoNormalizedMessageCreatedEvent["context"]>["inboundHistory"];
+type AndoInboundHistoryEntry = AndoInboundHistory[number];
+
+function stringifyError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+function stripAndoMemberGroupMentions(text?: string | null): string {
+  const value = text ?? "";
+  return value.replace(ANDO_MEMBER_GROUP_MENTION_REGEX, "$1").trim();
+}
+
+function stripAndoInboundHistory(
+  history: AndoInboundHistory,
+): AndoInboundHistory {
+  return history.map((entry: AndoInboundHistoryEntry) => ({
+    ...entry,
+    body: stripAndoMemberGroupMentions(entry.body),
+  }));
+}
+
+function toUnixTimestamp(value: string | Date | undefined): number | undefined {
+  if (!value) {
+    return undefined;
+  }
+
+  return value instanceof Date ? value.getTime() : Date.parse(value);
+}
+
+function resolveAuthorLabel(author: {
+  display_name?: string | null;
+  id?: string | null;
+}): string {
+  return author.display_name?.trim() || author.id || "unknown";
+}
+
+function resolveConversationLabel(
+  conversation: AndoConversation | undefined,
+  conversationId: string
+): string {
+  const name = conversation?.name?.trim();
+  if (name) {
+    return name;
+  }
+  return `Ando conversation ${conversationId}`;
+}
+
+export function resolveAndoInboundThreadId(params: {
+  replyThreadRootId?: string | null;
+}): string | undefined {
+  const threadId = params.replyThreadRootId?.trim();
+  if (!threadId) {
+    return undefined;
+  }
+
+  return threadId;
+}
+
+export function resolveAndoReplyThreadRootId(params: {
+  contextReplyThreadRootId?: string | null;
+  payloadReplyToId?: string | null;
+}): string | null {
+  const contextThreadRootId = params.contextReplyThreadRootId?.trim();
+  if (contextThreadRootId) {
+    return contextThreadRootId;
+  }
+
+  const payloadReplyToId = params.payloadReplyToId?.trim();
+  return payloadReplyToId || null;
+}
+
+export function resolveAndoConversationTarget(params: {
+  conversationId: string;
+}): string {
+  return formatAndoTarget({
+    kind: "channel",
+    conversationId: params.conversationId,
+  });
+}
+
+export function resolveAndoDispatchKey(params: {
+  accountId: string;
+  event: AndoNormalizedMessageCreatedEvent;
+}): string {
+  const threadId = resolveAndoInboundThreadId({
+    replyThreadRootId: params.event.context?.replyThreadRootId,
+  });
+  const baseTarget = resolveAndoConversationTarget({
+    conversationId: params.event.message.conversation_id,
+  });
+
+  return threadId
+    ? `${params.accountId}:${baseTarget}:thread:${threadId}`
+    : `${params.accountId}:${baseTarget}`;
+}
+
+export function createAndoDispatchSerializer() {
+  const pending = new Map<string, Promise<void>>();
+
+  return function runSerialized<T>(
+    key: string,
+    task: () => Promise<T>,
+  ): Promise<T> {
+    const previous = pending.get(key) ?? Promise.resolve();
+    const current = previous.then(task);
+    const tracked = current.then(
+      () => {
+        if (pending.get(key) === tracked) {
+          pending.delete(key);
+        }
+      },
+      () => {
+        if (pending.get(key) === tracked) {
+          pending.delete(key);
+        }
+      },
+    );
+
+    pending.set(key, tracked);
+    return current;
+  };
+}
+
+async function dispatchAndoMessage(params: {
+  cfg: OpenClawConfig;
+  channelRuntime: PluginRuntime["channel"];
+  client: ReturnType<typeof createAndoSdkClient>;
+  account: ResolvedAndoAccount;
+  event: AndoNormalizedMessageCreatedEvent;
+  runtime: MonitorRuntime;
+}) {
+  if (params.event.isDirectMessage) {
+    params.runtime.log?.(
+      `[ando] skipping direct message=${params.event.message.id} because this adapter only handles channel mentions`
+    );
+    return;
+  }
+
+  const context = params.event.context;
+  if (!context) {
+    params.runtime.log?.(
+      `[ando] skipping message=${params.event.message.id} because inbound context is empty`
+    );
+    return;
+  }
+
+  const message = params.event.message;
+  const conversation = params.event.conversation;
+  const route = params.channelRuntime.routing.resolveAgentRoute({
+    cfg: params.cfg,
+    channel: "ando",
+    accountId: params.account.accountId,
+    peer: {
+      kind: "channel",
+      id: message.conversation_id,
+    },
+  });
+  const inboundThreadId = resolveAndoInboundThreadId({
+    replyThreadRootId: context.replyThreadRootId,
+  });
+  const threadKeys = resolveThreadSessionKeys({
+    baseSessionKey: route.sessionKey,
+    threadId: inboundThreadId,
+    parentSessionKey: undefined,
+  });
+  const conversationLabel = resolveConversationLabel(
+    conversation,
+    message.conversation_id
+  );
+  const senderName = resolveAuthorLabel(message.author);
+  const channelTo = resolveAndoConversationTarget({
+    conversationId: message.conversation_id,
+  });
+  const currentText = stripAndoMemberGroupMentions(context.currentText);
+  if (!currentText) {
+    return;
+  }
+  const inboundHistory = stripAndoInboundHistory(context.inboundHistory);
+  const threadStarterBody = stripAndoMemberGroupMentions(
+    context.threadStarterBody,
+  );
+  const threadHistoryBody = stripAndoMemberGroupMentions(
+    context.threadHistoryBody,
+  );
+  const ctxPayload = params.channelRuntime.reply.finalizeInboundContext({
+    Body: params.channelRuntime.reply.formatInboundEnvelope({
+      channel: "Ando",
+      from: conversationLabel,
+      timestamp: toUnixTimestamp(message.created_at),
+      body: currentText,
+      chatType: "channel",
+      senderLabel: senderName,
+    }),
+    BodyForAgent: currentText,
+    RawBody: currentText,
+    CommandBody: currentText,
+    BodyForCommands: currentText,
+    InboundHistory: inboundHistory,
+    ThreadStarterBody: threadStarterBody || undefined,
+    ThreadHistoryBody: threadHistoryBody,
+    From: `ando:${channelTo}`,
+    To: channelTo,
+    SessionKey: threadKeys.sessionKey,
+    ParentSessionKey: threadKeys.parentSessionKey,
+    AccountId: route.accountId,
+    ChatType: "channel",
+    ConversationLabel: conversationLabel,
+    GroupSubject: conversationLabel,
+    SenderName: senderName,
+    SenderId: message.author.id,
+    Provider: "ando",
+    Surface: "ando",
+    MessageSid: message.id,
+    ReplyToId: context.replyThreadRootId,
+    MessageThreadId: inboundThreadId,
+    Timestamp: toUnixTimestamp(message.created_at) ?? Date.now(),
+    WasMentioned: true,
+    CommandAuthorized: false,
+    OriginatingChannel: "ando",
+    OriginatingTo: channelTo,
+  });
+
+  const storePath = params.channelRuntime.session.resolveStorePath(
+    params.cfg.session?.store,
+    {
+      agentId: route.agentId,
+    }
+  );
+
+  params.runtime.log?.(
+    `[ando] dispatching message=${message.id} agent=${route.agentId} session=${threadKeys.sessionKey}`
+  );
+
+  await params.channelRuntime.session.recordInboundSession({
+    storePath,
+    sessionKey: ctxPayload.SessionKey ?? threadKeys.sessionKey,
+    ctx: ctxPayload,
+    onRecordError: (error) => {
+      params.runtime.error?.(
+        `[ando] failed to record inbound session: ${stringifyError(error)}`
+      );
+    },
+  });
+
+  const { onModelSelected, ...replyPipeline } = createChannelReplyPipeline({
+    cfg: params.cfg,
+    agentId: route.agentId,
+    channel: "ando",
+    accountId: route.accountId,
+  });
+
+  await params.channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: ctxPayload,
+    cfg: params.cfg,
+    dispatcherOptions: {
+      ...replyPipeline,
+      deliver: createNormalizedOutboundDeliverer(async (payload) => {
+        await deliverFormattedTextWithAttachments({
+          payload,
+          send: async ({ text, replyToId }) => {
+            const markdownContent = text.trim();
+            if (!markdownContent) {
+              return;
+            }
+
+            await postAndoMessage({
+              client: params.client,
+              account: params.account,
+              conversationId: message.conversation_id,
+              markdownContent,
+              threadRootId: resolveAndoReplyThreadRootId({
+                contextReplyThreadRootId: context.replyThreadRootId,
+                payloadReplyToId: replyToId,
+              }),
+            });
+          },
+        });
+      }),
+      onError: (error, info) => {
+        params.runtime.error?.(
+          `[ando] reply ${info.kind} failed: ${stringifyError(error)}`
+        );
+      },
+    },
+    replyOptions: {
+      onModelSelected,
+    },
+  });
+}
+
+export async function monitorAndoProvider(params: {
+  account: ResolvedAndoAccount;
+  cfg: OpenClawConfig;
+  runtime: MonitorRuntime;
+  abortSignal?: AbortSignal;
+  channelRuntime: PluginRuntime["channel"];
+}) {
+  const channelRuntime = params.channelRuntime;
+  const runSerializedDispatch = createAndoDispatchSerializer();
+  const pendingDispatches = new Set<Promise<void>>();
+  const client = createAndoSdkClient(params.account);
+
+  const trackDispatch = (task: Promise<void>) => {
+    pendingDispatches.add(task);
+    task.finally(() => {
+      pendingDispatches.delete(task);
+    });
+  };
+
+  const waitForPendingDispatches = async () => {
+    while (pendingDispatches.size > 0) {
+      await Promise.allSettled(Array.from(pendingDispatches));
+    }
+  };
+
+  const stream = await client.realtime.subscribeMember({
+    signal: params.abortSignal,
+    onMessage: async (event) => {
+      const dispatchKey = resolveAndoDispatchKey({
+        accountId: params.account.accountId,
+        event,
+      });
+      const task = runSerializedDispatch(dispatchKey, async () => {
+        if (params.abortSignal?.aborted) {
+          return;
+        }
+
+        await dispatchAndoMessage({
+          cfg: params.cfg,
+          channelRuntime,
+          client,
+          account: params.account,
+          event,
+          runtime: params.runtime,
+        });
+      }).catch((error) => {
+        params.runtime.error?.(
+          `[ando] dispatch failed: ${stringifyError(error)}`
+        );
+      });
+      trackDispatch(task);
+    },
+  });
+  try {
+    const stopReason = await Promise.race([
+      stream.done().then(() => "stream-ended" as const),
+      new Promise<"aborted">((resolve) => {
+        if (params.abortSignal?.aborted) {
+          resolve("aborted");
+          return;
+        }
+
+        params.abortSignal?.addEventListener("abort", () => resolve("aborted"), {
+          once: true,
+        });
+      }),
+    ]);
+
+    if (stopReason === "stream-ended") {
+      throw new Error("[ando] realtime subscription stopped unexpectedly");
+    }
+  } finally {
+    await stream.close();
+    await waitForPendingDispatches();
+  }
+}

package/src/types.ts

@@ -0,0 +1,7 @@
+export type ResolvedAndoAccount = {
+  accountId: string;
+  baseUrl: string;
+  apiKey: string;
+  realtimeHost: string | null;
+  mcpUrl: string;
+};