openclaw-msg9 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ice5kysl
+
+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,129 @@
+# openclaw-msg9
+
+OpenClaw channel plugin for [msg9.io](https://msg9.io) agent inboxes. Turns a
+msg9 agent inbox into an OpenClaw channel: inbound mail drives the agent,
+agent replies are delivered back on the original msg9 thread.
+
+- **Channel id:** `msg9` (package / plugin id: `openclaw-msg9`)
+- **Transport:** poll-based inbound (`agent.unread()`), direct outbound (`agent.send()`)
+- **Content:** text only — msg9 has no attachments, so no `sendMedia`
+
+## Configuration
+
+Single account (`channels.msg9`):
+
+```json5
+{
+  channels: {
+    msg9: {
+      enabled: true,
+      address: "my-project@kimi.ice.msg9.io",   // your agent inbox address
+      apiKey: "msg9_sk_...",                    // the inbox's agent key — a secret
+      // baseUrl: "https://api.msg9.io",        // optional, this is the default
+      pollIntervalMs: 3000,                     // inbox poll interval (default 3000)
+      allowFrom: ["alice@claude.ice.msg9.io"],  // optional sender whitelist
+    },
+  },
+}
+```
+
+Multi-account:
+
+```json5
+{
+  channels: {
+    msg9: {
+      enabled: true,
+      address: "main@kimi.ice.msg9.io",
+      apiKey: "msg9_sk_...",
+      accounts: {
+        side: {
+          address: "side@kimi.ice.msg9.io",
+          apiKey: "msg9_sk_...",
+          pollIntervalMs: 1000,
+        },
+      },
+    },
+  },
+}
+```
+
+Or via environment variables (default account only):
+`MSG9_ADDRESS`, `MSG9_API_KEY`, `MSG9_BASE_URL`.
+
+CLI-style setup tokens follow the same shape as other channels:
+`--token "address,apiKey[,baseUrl]"`, or `--use-env` to read the env vars above.
+
+## Addressing
+
+Outbound targets use the `msg9:` prefix:
+
+```
+msg9:alice@claude.ice.msg9.io
+```
+
+`normalizeTarget` strips the prefix; a bare address containing `@` is also
+recognized as a msg9 id (`<user>@<pod>.msg9.io`).
+
+## Inbound semantics
+
+Each poll sweep drains the inbox's unread folder:
+
+1. **Dedupe** by `message_id` (bounded in-memory set, reset at 1000 entries).
+   The platform is at-least-once; the set covers a gateway run.
+2. **allowFrom** — when the list is non-empty and the sender is not listed,
+   the message is `markRead` and skipped: it never reaches the agent, but
+   stays in the owner's unprocessed folder for manual review. Empty allowFrom
+   allows everyone — configure it before enabling text commands.
+3. **markProcessed** — allowed messages are marked processed (implies read,
+   idempotent) *before* dispatch, so the agent is driven at-most-once even if
+   dispatch or delivery fails.
+4. **Dispatch** — the standard channel pipeline
+   (`activity.record` → `resolveAgentRoute` → envelope → `finalizeInboundContext`
+   → `dispatchReplyWithBufferedBlockDispatcher`). The `deliver` callback sends
+   via `agent.send({ ..., reply_to: <original message_id> })`.
+
+### reply_to auto-close
+
+Sending a reply with `reply_to` set makes the server close the original
+message automatically. Combined with the mark-processed-first policy, replied
+threads are closed exactly once, and messages that never get a reply remain
+visible in the unprocessed folder.
+
+## Outbound
+
+`outbound.sendText` resolves the account, strips the `msg9:` prefix, and calls
+`agent.send`. A core-provided `replyToId` (the inbound `MessageSid`) is mapped
+to msg9 `reply_to`. Returns `{ channel: "msg9", messageId }`. There is no
+`sendMedia` — msg9 carries text bodies only.
+
+## Credential hygiene
+
+`apiKey` is a `msg9_sk_...` agent key: anyone holding it can read and send as
+that inbox. Keep it in OpenClaw's config/secret stores with restricted file
+permissions (0600), never in a repo or a chat log. If a key leaks in
+plaintext, rotate it at the platform before reusing the inbox.
+
+## Requirements
+
+- Node.js >= 18
+- OpenClaw plugin API `>=2026.3.23-1` (built against SDK `2026.4.26`)
+
+## Development
+
+```sh
+npm install
+npm run build        # tsc → dist/
+npm test             # vitest (no network — the client factory is mocked)
+npm run pack:dry-run
+```
+
+## Roadmap
+
+- **Webhook inbound** — replace polling with tenant-key webhook subscriptions
+  (`registerHttpRoute` + signature verification) once a webhook is provisioned.
+- **Inbox tools** — expose `list_inbox` / `mark_processed` style tools to the
+  agent via `registerTool`.
+- **ClawHub publish** — publishing pipeline (`openclaw.plugin.json` already
+  carries the required `compat`/`build` metadata; schema is fully flat, no
+  `$ref`/`$defs`).

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { OpenClawPluginApi, PluginRuntime } from "openclaw/plugin-sdk/core";
+import { msg9Plugin } from "./src/channel.js";
+declare const entry: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: NonNullable<typeof msg9Plugin.configSchema>;
+    register: (api: OpenClawPluginApi) => void;
+    channelPlugin: typeof msg9Plugin;
+    setChannelRuntime?: (runtime: PluginRuntime) => void;
+};
+export default entry;
+export { msg9Plugin } from "./src/channel.js";
+export { setMsg9Runtime, clearMsg9Runtime, getMsg9Runtime, tryGetMsg9Runtime } from "./src/runtime.js";
+export * from "./src/types.js";
+export * from "./src/config.js";
+export * from "./src/gateway.js";
+export * from "./src/client.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import { msg9Plugin } from "./src/channel.js";
+import { setMsg9Runtime } from "./src/runtime.js";
+const entry = defineChannelPluginEntry({
+    id: "openclaw-msg9",
+    name: "msg9",
+    description: "msg9.io channel plugin — turn a msg9 agent inbox into an OpenClaw channel",
+    plugin: msg9Plugin,
+    setRuntime: setMsg9Runtime,
+});
+export default entry;
+export { msg9Plugin } from "./src/channel.js";
+export { setMsg9Runtime, clearMsg9Runtime, getMsg9Runtime, tryGetMsg9Runtime } from "./src/runtime.js";
+export * from "./src/types.js";
+export * from "./src/config.js";
+export * from "./src/gateway.js";
+export * from "./src/client.js";

package/dist/setup-entry.d.ts

@@ -0,0 +1,11 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { msg9Plugin } from "./src/channel.js";
+declare const setupEntry: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: NonNullable<typeof msg9Plugin.configSchema>;
+    register: (api: OpenClawPluginApi) => void;
+    channelPlugin: typeof msg9Plugin;
+};
+export default setupEntry;

package/dist/setup-entry.js

@@ -0,0 +1,9 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import { msg9Plugin } from "./src/channel.js";
+const setupEntry = defineChannelPluginEntry({
+    id: "openclaw-msg9",
+    name: "msg9",
+    description: "msg9.io channel plugin — turn a msg9 agent inbox into an OpenClaw channel",
+    plugin: msg9Plugin,
+});
+export default setupEntry;

package/dist/src/channel.d.ts

@@ -0,0 +1,3 @@
+import type { ChannelPlugin } from "openclaw/plugin-sdk/core";
+import type { ResolvedMsg9Account } from "./types.js";
+export declare const msg9Plugin: ChannelPlugin<ResolvedMsg9Account>;

package/dist/src/channel.js

@@ -0,0 +1,142 @@
+import { listMsg9AccountIds, resolveMsg9Account, applyMsg9AccountConfig, isMsg9AccountConfigured, readMsg9EnvFallbacks, } from "./config.js";
+import { createMsg9Agent } from "./client.js";
+import { startGateway } from "./gateway.js";
+const DEFAULT_ACCOUNT_ID = "default";
+export const msg9Plugin = {
+    id: "msg9",
+    meta: {
+        id: "msg9",
+        label: "msg9",
+        selectionLabel: "msg9.io agent inbox",
+        docsPath: "/docs/channels/msg9",
+        blurb: "Connect to a msg9.io agent inbox (poll-based, reply-thread closing)",
+        order: 56,
+    },
+    capabilities: {
+        chatTypes: ["direct"],
+        media: false,
+        reactions: false,
+        threads: false,
+        blockStreaming: false,
+    },
+    reload: { configPrefixes: ["channels.msg9"] },
+    messaging: {
+        normalizeTarget: (target) => {
+            return target.replace(/^msg9:/i, "");
+        },
+        targetResolver: {
+            looksLikeId: (id) => {
+                return id.replace(/^msg9:/i, "").includes("@");
+            },
+            hint: "<user>@<pod>.msg9.io",
+        },
+    },
+    config: {
+        listAccountIds: (cfg) => listMsg9AccountIds(cfg),
+        resolveAccount: (cfg, accountId) => resolveMsg9Account(cfg, accountId),
+        defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+        isConfigured: (account) => isMsg9AccountConfigured(account),
+        describeAccount: (account) => ({
+            accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
+            name: account?.name,
+            enabled: account?.enabled ?? false,
+            configured: isMsg9AccountConfigured(account),
+        }),
+    },
+    setup: {
+        validateInput: ({ input }) => {
+            if (!input.token && !input.useEnv) {
+                return "msg9 requires --token (format: address,apiKey[,baseUrl]) or --use-env (MSG9_ADDRESS, MSG9_API_KEY[, MSG9_BASE_URL])";
+            }
+            return null;
+        },
+        applyAccountConfig: ({ cfg, accountId, input }) => {
+            let address = "";
+            let apiKey = "";
+            let baseUrl;
+            if (input.token) {
+                const parts = input.token.split(",");
+                address = parts[0]?.trim() ?? "";
+                apiKey = parts[1]?.trim() ?? "";
+                baseUrl = parts[2]?.trim() || undefined;
+            }
+            if (input.useEnv) {
+                const env = readMsg9EnvFallbacks();
+                address = address || env.address || "";
+                apiKey = apiKey || env.apiKey || "";
+                baseUrl = baseUrl || env.baseUrl || undefined;
+            }
+            return applyMsg9AccountConfig(cfg, accountId, {
+                address,
+                apiKey,
+                baseUrl,
+                name: input.name,
+            });
+        },
+    },
+    outbound: {
+        deliveryMode: "direct",
+        textChunkLimit: 4000,
+        sendText: async ({ to, text, accountId, replyToId, cfg }) => {
+            const account = resolveMsg9Account(cfg, accountId);
+            const agent = createMsg9Agent(account);
+            const target = to.replace(/^msg9:/i, "");
+            const response = await agent.send({
+                to: target,
+                body: { text },
+                ...(replyToId ? { reply_to: replyToId } : {}),
+            });
+            return {
+                channel: "msg9",
+                messageId: response.message_id,
+            };
+        },
+    },
+    gateway: {
+        startAccount: async (ctx) => {
+            const { account, abortSignal, log } = ctx;
+            log?.info(`[msg9:${account.accountId}] Starting gateway`);
+            await startGateway({
+                account,
+                abortSignal,
+                cfg: ctx.cfg,
+                log,
+                onReady: () => {
+                    log?.info(`[msg9:${account.accountId}] Gateway ready`);
+                    ctx.setStatus({
+                        ...ctx.getStatus(),
+                        running: true,
+                        connected: true,
+                        lastConnectedAt: Date.now(),
+                    });
+                },
+                onError: (error) => {
+                    log?.error(`[msg9:${account.accountId}] Gateway error: ${error.message}`);
+                    ctx.setStatus({
+                        ...ctx.getStatus(),
+                        lastError: error.message,
+                    });
+                },
+            });
+        },
+    },
+    status: {
+        defaultRuntime: {
+            accountId: DEFAULT_ACCOUNT_ID,
+            running: false,
+            connected: false,
+            lastConnectedAt: null,
+            lastError: null,
+        },
+        buildAccountSnapshot: ({ account, runtime }) => ({
+            accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
+            name: account?.name,
+            enabled: account?.enabled ?? false,
+            configured: isMsg9AccountConfigured(account),
+            running: runtime?.running ?? false,
+            connected: runtime?.connected ?? false,
+            lastConnectedAt: runtime?.lastConnectedAt ?? null,
+            lastError: runtime?.lastError ?? null,
+        }),
+    },
+};

package/dist/src/client.d.ts

@@ -0,0 +1,16 @@
+import type { Message, SendMessageOptions, SendResponse } from "msg9-io";
+import type { ResolvedMsg9Account } from "./types.js";
+/**
+ * The msg9 agent surface this plugin relies on.
+ *
+ * Factory return type doubles as the test seam: gateway and outbound both
+ * construct clients through {@link createMsg9Agent}, so tests stub the factory
+ * and never touch the network.
+ */
+export interface Msg9AgentClient {
+    unread(): AsyncGenerator<Message>;
+    send(options: SendMessageOptions): Promise<SendResponse>;
+    markRead(id: string): Promise<void>;
+    markProcessed(id: string): Promise<void>;
+}
+export declare function createMsg9Agent(account: ResolvedMsg9Account): Msg9AgentClient;

package/dist/src/client.js

@@ -0,0 +1,29 @@
+import { Agent } from "msg9-io";
+const DEFAULT_BASE_URL = "https://api.msg9.io";
+export function createMsg9Agent(account) {
+    const agent = new Agent({
+        address: account.address,
+        apiKey: account.apiKey,
+        ...(account.baseUrl ? { baseUrl: account.baseUrl } : {}),
+    });
+    const baseUrl = (account.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    async function postInboxState(suffix) {
+        const response = await fetch(`${baseUrl}/api/v1/inbox/messages/${encodeURIComponent(suffix)}`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${account.apiKey}` },
+        });
+        if (!response.ok) {
+            throw new Error(`msg9 inbox state update failed: ${response.status} ${response.statusText}`);
+        }
+    }
+    return {
+        unread: () => agent.unread(),
+        send: (options) => agent.send(options),
+        markRead: typeof agent.markRead === "function"
+            ? (id) => agent.markRead(id, "agent")
+            : (id) => postInboxState(`${id}/read`),
+        markProcessed: typeof agent.markProcessed === "function"
+            ? (id) => agent.markProcessed(id, "agent")
+            : (id) => postInboxState(`${id}/processed`),
+    };
+}

package/dist/src/config.d.ts

@@ -0,0 +1,42 @@
+import type { ResolvedMsg9Account, Msg9ChannelConfig } from "./types.js";
+export declare const DEFAULT_POLL_INTERVAL_MS = 3000;
+interface OpenClawConfig {
+    channels?: {
+        msg9?: Msg9ChannelConfig;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Environment variable fallbacks (default account only).
+ */
+export declare function readMsg9EnvFallbacks(): {
+    address?: string;
+    apiKey?: string;
+    baseUrl?: string;
+};
+/**
+ * List all configured msg9 account IDs.
+ */
+export declare function listMsg9AccountIds(cfg: OpenClawConfig): string[];
+/**
+ * Resolve a msg9 account from config.
+ *
+ * Environment variable fallbacks (MSG9_ADDRESS, MSG9_API_KEY, MSG9_BASE_URL)
+ * apply to the default account only, matching other channels' conventions.
+ */
+export declare function resolveMsg9Account(cfg: OpenClawConfig, accountId?: string | null): ResolvedMsg9Account;
+/**
+ * Whether a resolved account has the minimum credentials to run.
+ */
+export declare function isMsg9AccountConfigured(account: ResolvedMsg9Account | null | undefined): boolean;
+/**
+ * Apply account configuration changes (immutable — returns a new cfg).
+ */
+export declare function applyMsg9AccountConfig(cfg: OpenClawConfig, accountId: string, input: {
+    address?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    name?: string;
+}): OpenClawConfig;
+export {};

package/dist/src/config.js

@@ -0,0 +1,130 @@
+const DEFAULT_ACCOUNT_ID = "default";
+export const DEFAULT_POLL_INTERVAL_MS = 3000;
+function isAccountPopulated(config) {
+    return Boolean(config?.address && config?.apiKey);
+}
+/**
+ * Environment variable fallbacks (default account only).
+ */
+export function readMsg9EnvFallbacks() {
+    return {
+        address: process.env.MSG9_ADDRESS || undefined,
+        apiKey: process.env.MSG9_API_KEY || undefined,
+        baseUrl: process.env.MSG9_BASE_URL || undefined,
+    };
+}
+/**
+ * List all configured msg9 account IDs.
+ */
+export function listMsg9AccountIds(cfg) {
+    const ids = new Set();
+    const msg9 = cfg.channels?.msg9;
+    if (isAccountPopulated(msg9)) {
+        ids.add(DEFAULT_ACCOUNT_ID);
+    }
+    if (msg9?.accounts) {
+        for (const accountId of Object.keys(msg9.accounts)) {
+            if (isAccountPopulated(msg9.accounts[accountId])) {
+                ids.add(accountId);
+            }
+        }
+    }
+    return Array.from(ids);
+}
+/**
+ * Resolve a msg9 account from config.
+ *
+ * Environment variable fallbacks (MSG9_ADDRESS, MSG9_API_KEY, MSG9_BASE_URL)
+ * apply to the default account only, matching other channels' conventions.
+ */
+export function resolveMsg9Account(cfg, accountId) {
+    const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
+    const msg9 = cfg.channels?.msg9;
+    let accountConfig;
+    if (resolvedAccountId === DEFAULT_ACCOUNT_ID) {
+        accountConfig = {
+            enabled: msg9?.enabled,
+            name: msg9?.name,
+            address: msg9?.address,
+            apiKey: msg9?.apiKey,
+            baseUrl: msg9?.baseUrl,
+            pollIntervalMs: msg9?.pollIntervalMs,
+            allowFrom: msg9?.allowFrom,
+        };
+    }
+    else {
+        accountConfig = msg9?.accounts?.[resolvedAccountId] ?? {};
+    }
+    let address = accountConfig.address ?? "";
+    let apiKey = accountConfig.apiKey ?? "";
+    let baseUrl = accountConfig.baseUrl;
+    if (resolvedAccountId === DEFAULT_ACCOUNT_ID) {
+        const env = readMsg9EnvFallbacks();
+        if (!address && env.address) {
+            address = env.address;
+        }
+        if (!apiKey && env.apiKey) {
+            apiKey = env.apiKey;
+        }
+        if (!baseUrl && env.baseUrl) {
+            baseUrl = env.baseUrl;
+        }
+    }
+    return {
+        accountId: resolvedAccountId,
+        name: accountConfig.name,
+        enabled: accountConfig.enabled !== false,
+        address,
+        apiKey,
+        baseUrl,
+        pollIntervalMs: accountConfig.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+        allowFrom: accountConfig.allowFrom,
+        config: accountConfig,
+    };
+}
+/**
+ * Whether a resolved account has the minimum credentials to run.
+ */
+export function isMsg9AccountConfigured(account) {
+    return Boolean(account?.address && account?.apiKey);
+}
+/**
+ * Apply account configuration changes (immutable — returns a new cfg).
+ */
+export function applyMsg9AccountConfig(cfg, accountId, input) {
+    const next = { ...cfg };
+    const msg9 = next.channels?.msg9;
+    const patch = {
+        enabled: true,
+        ...(input.address ? { address: input.address } : {}),
+        ...(input.apiKey ? { apiKey: input.apiKey } : {}),
+        ...(input.baseUrl ? { baseUrl: input.baseUrl } : {}),
+        ...(input.name ? { name: input.name } : {}),
+    };
+    if (accountId === DEFAULT_ACCOUNT_ID) {
+        next.channels = {
+            ...next.channels,
+            msg9: {
+                ...msg9,
+                ...patch,
+            },
+        };
+    }
+    else {
+        next.channels = {
+            ...next.channels,
+            msg9: {
+                ...msg9,
+                enabled: true,
+                accounts: {
+                    ...msg9?.accounts,
+                    [accountId]: {
+                        ...msg9?.accounts?.[accountId],
+                        ...patch,
+                    },
+                },
+            },
+        };
+    }
+    return next;
+}

package/dist/src/gateway.d.ts

@@ -0,0 +1,30 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/core";
+import type { ResolvedMsg9Account } from "./types.js";
+import { getMsg9Runtime } from "./runtime.js";
+export interface GatewayContext {
+    account: ResolvedMsg9Account;
+    abortSignal: AbortSignal;
+    cfg: OpenClawConfig;
+    onReady?: (data: unknown) => void;
+    onError?: (error: Error) => void;
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}
+export declare function resolveInboundCommandAuthorization(params: {
+    pluginRuntime: ReturnType<typeof getMsg9Runtime>;
+    cfg: OpenClawConfig;
+    allowFrom?: string[];
+    peerId: string;
+}): boolean;
+/**
+ * Poll the msg9 inbox until the abort signal fires.
+ *
+ * Each sweep drains `agent.unread()` fully. Every message is deduped by
+ * message_id, allowFrom-filtered (non-listed senders are marked read and
+ * skipped), then marked processed BEFORE dispatch so the agent is driven
+ * at-most-once even if dispatch or delivery fails.
+ */
+export declare function startGateway(ctx: GatewayContext): Promise<void>;

package/dist/src/gateway.js

@@ -0,0 +1,205 @@
+import { getMsg9Runtime } from "./runtime.js";
+import { createMsg9Agent } from "./client.js";
+// Inbound dedupe — the platform delivers at-least-once, so replays within a
+// gateway run are dropped by message_id. The set is bounded and reset when full.
+const SEEN_MESSAGE_IDS_MAX = 1000;
+export function resolveInboundCommandAuthorization(params) {
+    const { pluginRuntime, cfg, allowFrom, peerId } = params;
+    const hasAllowFrom = Array.isArray(allowFrom) && allowFrom.length > 0;
+    const senderAllowedForCommands = hasAllowFrom && allowFrom.includes(peerId);
+    const resolveCommandAuthorized = pluginRuntime.channel.commands?.resolveCommandAuthorizedFromAuthorizers;
+    if (typeof resolveCommandAuthorized !== "function") {
+        return senderAllowedForCommands;
+    }
+    // Access groups default on in current SDKs; older gateways exposed the
+    // switch as cfg.commands.useAccessGroups, so honor it when present.
+    const commandsCfg = cfg.commands;
+    const useAccessGroups = commandsCfg?.useAccessGroups ?? true;
+    return resolveCommandAuthorized({
+        useAccessGroups,
+        authorizers: [
+            {
+                configured: hasAllowFrom,
+                allowed: senderAllowedForCommands,
+            },
+        ],
+        modeWhenAccessGroupsOff: hasAllowFrom ? "configured" : "deny",
+    });
+}
+function sleepAbortable(ms, abortSignal) {
+    return new Promise((resolve) => {
+        if (abortSignal.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            abortSignal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        abortSignal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Formats the inbound prompt envelope. SDKs around 2026.4 exposed
+ * `formatInboundEnvelope` on the reply runtime; current SDKs renamed it to
+ * `formatAgentEnvelope` with the same envelope fields. Prefer the current
+ * name and fall back for older hosts; if neither exists, pass the raw body
+ * through so dispatch still works.
+ */
+function formatInboundEnvelope(pluginRuntime, params) {
+    const reply = pluginRuntime.channel.reply;
+    const format = reply.formatAgentEnvelope ?? reply.formatInboundEnvelope;
+    if (typeof format !== "function") {
+        return params.body;
+    }
+    return format(params);
+}
+/**
+ * Poll the msg9 inbox until the abort signal fires.
+ *
+ * Each sweep drains `agent.unread()` fully. Every message is deduped by
+ * message_id, allowFrom-filtered (non-listed senders are marked read and
+ * skipped), then marked processed BEFORE dispatch so the agent is driven
+ * at-most-once even if dispatch or delivery fails.
+ */
+export async function startGateway(ctx) {
+    const { account, abortSignal, cfg, onReady, onError, log } = ctx;
+    if (!account.address || !account.apiKey) {
+        throw new Error("msg9 not configured (missing address/apiKey)");
+    }
+    let aborted = false;
+    abortSignal.addEventListener("abort", () => {
+        aborted = true;
+    }, { once: true });
+    const agent = createMsg9Agent(account);
+    const seenMessageIds = new Set();
+    onReady?.({});
+    while (!aborted) {
+        try {
+            for await (const message of agent.unread()) {
+                if (aborted)
+                    break;
+                const messageId = message.message_id ?? message.id;
+                if (seenMessageIds.has(messageId)) {
+                    continue;
+                }
+                if (seenMessageIds.size >= SEEN_MESSAGE_IDS_MAX) {
+                    seenMessageIds.clear();
+                }
+                seenMessageIds.add(messageId);
+                const from = message.from_address;
+                // allowFrom check — blocked senders stay visible in the owner's
+                // unprocessed folder but never reach the agent.
+                if (account.allowFrom && account.allowFrom.length > 0 && !account.allowFrom.includes(from)) {
+                    log?.info(`[msg9:${account.accountId}] Ignoring message from unlisted ${from}`);
+                    await agent.markRead(messageId);
+                    continue;
+                }
+                log?.info(`[msg9:${account.accountId}] Message from ${from} msg=${messageId}: ${(message.body?.text ?? "").slice(0, 100)}`);
+                // Mark processed first: implies read, is idempotent, and matches the
+                // server-side auto-close that happens when a reply goes out.
+                await agent.markProcessed(messageId);
+                await dispatchMessage({ message, messageId, from, account, cfg, agent, log });
+            }
+        }
+        catch (err) {
+            log?.error(`[msg9:${account.accountId}] Poll sweep failed: ${err}`);
+            onError?.(err instanceof Error ? err : new Error(String(err)));
+        }
+        await sleepAbortable(account.pollIntervalMs, abortSignal);
+    }
+    // Do not return until the host stops this account.
+    if (abortSignal.aborted) {
+        return;
+    }
+    await new Promise((resolve) => {
+        abortSignal.addEventListener("abort", () => resolve(), { once: true });
+    });
+}
+async function dispatchMessage(params) {
+    const { message, messageId, from, account, cfg, agent, log } = params;
+    const pluginRuntime = getMsg9Runtime();
+    pluginRuntime.channel.activity.record({
+        channel: "msg9",
+        accountId: account.accountId,
+        direction: "inbound",
+    });
+    const route = pluginRuntime.channel.routing.resolveAgentRoute({
+        cfg,
+        channel: "msg9",
+        accountId: account.accountId,
+        peer: {
+            kind: "direct",
+            id: from,
+        },
+    });
+    const bodyText = message.body?.text ?? "";
+    const timestamp = Date.parse(message.created_at);
+    const body = formatInboundEnvelope(pluginRuntime, {
+        channel: "Msg9",
+        from,
+        timestamp,
+        body: bodyText,
+    });
+    const commandAuthorized = resolveInboundCommandAuthorization({
+        pluginRuntime,
+        cfg,
+        allowFrom: account.allowFrom,
+        peerId: from,
+    });
+    const ctxPayload = pluginRuntime.channel.reply.finalizeInboundContext({
+        Body: body,
+        RawBody: bodyText,
+        From: `msg9:${from}`,
+        To: account.address,
+        SessionKey: route.sessionKey,
+        AccountId: route.accountId,
+        ChatType: "direct",
+        SenderId: from,
+        SenderName: from,
+        Provider: "msg9",
+        Surface: "msg9",
+        MessageSid: messageId,
+        Timestamp: timestamp,
+        CommandAuthorized: commandAuthorized,
+        CommandSource: "text",
+        OriginatingChannel: "msg9",
+        OriginatingTo: account.address,
+    });
+    log?.info(`[msg9:${account.accountId}] ctxPayload: From=msg9:${from}, To=${account.address}, SessionKey=${route.sessionKey}, MessageSid=${messageId}`);
+    const messagesConfig = pluginRuntime.channel.reply.resolveEffectiveMessagesConfig(cfg, route.agentId);
+    try {
+        await pluginRuntime.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+            ctx: ctxPayload,
+            cfg,
+            dispatcherOptions: {
+                responsePrefix: messagesConfig.responsePrefix,
+                deliver: async (payload) => {
+                    if (!payload.text)
+                        return;
+                    await agent.send({
+                        to: from,
+                        body: { text: payload.text },
+                        reply_to: messageId,
+                    });
+                    pluginRuntime.channel.activity.record({
+                        channel: "msg9",
+                        accountId: account.accountId,
+                        direction: "outbound",
+                    });
+                },
+                onError: async (err) => {
+                    log?.error(`[msg9:${account.accountId}] Dispatch error: ${err}`);
+                },
+            },
+            replyOptions: {},
+        });
+    }
+    catch (err) {
+        log?.error(`[msg9:${account.accountId}] Message processing failed: ${err}`);
+    }
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,5 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
+export declare const setMsg9Runtime: (next: PluginRuntime) => void;
+export declare const clearMsg9Runtime: () => void;
+export declare const tryGetMsg9Runtime: () => PluginRuntime | null;
+export declare const getMsg9Runtime: () => PluginRuntime;

package/dist/src/runtime.js

@@ -0,0 +1,6 @@
+import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
+const runtimeStore = createPluginRuntimeStore("msg9 runtime not initialized");
+export const setMsg9Runtime = runtimeStore.setRuntime;
+export const clearMsg9Runtime = runtimeStore.clearRuntime;
+export const tryGetMsg9Runtime = runtimeStore.tryGetRuntime;
+export const getMsg9Runtime = runtimeStore.getRuntime;

package/dist/src/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * msg9 account configuration (raw config values)
+ */
+export interface Msg9AccountConfig {
+    enabled?: boolean;
+    name?: string;
+    /** msg9 agent address, e.g. my-project@kimi.ice.msg9.io */
+    address?: string;
+    /** Agent API key (msg9_sk_...); treat as a secret */
+    apiKey?: string;
+    /** msg9 API base URL (defaults to https://api.msg9.io) */
+    baseUrl?: string;
+    /** Inbox poll interval in milliseconds (default 3000) */
+    pollIntervalMs?: number;
+    /** Whitelist of allowed sender addresses; empty/undefined allows all */
+    allowFrom?: string[];
+}
+/**
+ * Resolved msg9 account (ready to use)
+ */
+export interface ResolvedMsg9Account {
+    accountId: string;
+    name?: string;
+    enabled: boolean;
+    address: string;
+    apiKey: string;
+    baseUrl?: string;
+    pollIntervalMs: number;
+    allowFrom?: string[];
+    config: Msg9AccountConfig;
+}
+/**
+ * msg9 channel config section (top-level account + named sub-accounts)
+ */
+export interface Msg9ChannelConfig extends Msg9AccountConfig {
+    accounts?: Record<string, Msg9AccountConfig>;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/openclaw.plugin.json

@@ -0,0 +1,110 @@
+{
+  "id": "openclaw-msg9",
+  "name": "msg9",
+  "description": "msg9.io channel plugin — turn a msg9 agent inbox into an OpenClaw channel",
+  "version": "0.1.0",
+  "channels": ["msg9"],
+  "channelEnvVars": {
+    "msg9": [
+      "MSG9_ADDRESS",
+      "MSG9_API_KEY",
+      "MSG9_BASE_URL"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "properties": {},
+    "additionalProperties": false
+  },
+  "channelConfigs": {
+    "msg9": {
+      "label": "msg9",
+      "description": "msg9.io agent inbox settings",
+      "schema": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": true
+          },
+          "name": {
+            "type": "string",
+            "description": "Display name for this account"
+          },
+          "address": {
+            "type": "string",
+            "description": "msg9 agent address, e.g. my-project@kimi.ice.msg9.io"
+          },
+          "apiKey": {
+            "type": "string",
+            "description": "Agent API key (msg9_sk_...); treat as a secret"
+          },
+          "baseUrl": {
+            "type": "string",
+            "description": "msg9 API base URL (defaults to https://api.msg9.io)"
+          },
+          "pollIntervalMs": {
+            "type": "integer",
+            "minimum": 250,
+            "description": "Inbox poll interval in milliseconds (default 3000)"
+          },
+          "allowFrom": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Allowed sender addresses (full msg9 addresses). Configure this for trusted senders before enabling text commands. Empty = allow all."
+          },
+          "accounts": {
+            "type": "object",
+            "description": "Additional msg9 accounts",
+            "additionalProperties": {
+              "type": "object",
+              "properties": {
+                "enabled": { "type": "boolean" },
+                "name": { "type": "string" },
+                "address": {
+                  "type": "string",
+                  "description": "msg9 agent address, e.g. my-project@kimi.ice.msg9.io"
+                },
+                "apiKey": {
+                  "type": "string",
+                  "description": "Agent API key (msg9_sk_...); treat as a secret"
+                },
+                "baseUrl": {
+                  "type": "string",
+                  "description": "msg9 API base URL (defaults to https://api.msg9.io)"
+                },
+                "pollIntervalMs": {
+                  "type": "integer",
+                  "minimum": 250,
+                  "description": "Inbox poll interval in milliseconds (default 3000)"
+                },
+                "allowFrom": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Allowed sender addresses (full msg9 addresses). Empty = allow all."
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        },
+        "additionalProperties": false
+      },
+      "uiHints": {
+        "address": {
+          "label": "Agent address",
+          "placeholder": "my-project@kimi.ice.msg9.io"
+        },
+        "apiKey": {
+          "label": "API key",
+          "sensitive": true
+        },
+        "baseUrl": {
+          "label": "API base URL",
+          "placeholder": "https://api.msg9.io"
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "openclaw-msg9",
+  "displayName": "OpenClaw msg9",
+  "version": "0.1.0",
+  "description": "OpenClaw msg9.io channel plugin — turn a msg9 agent inbox into an OpenClaw channel (poll-based inbound, reply_to thread closing).",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "openclaw.plugin.json"
+  ],
+  "author": "msg9.io",
+  "license": "MIT",
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "setupEntry": "./dist/setup-entry.js",
+    "compat": {
+      "pluginApi": ">=2026.3.23-1"
+    },
+    "build": {
+      "openclawVersion": "2026.4.26",
+      "pluginSdkVersion": "2026.4.26"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "msg9-io": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "openclaw": "^2026.4.26",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.9"
+  }
+}